From dcadada7d30cab363669662057cc390c4b7d272d Mon Sep 17 00:00:00 2001 From: Reece Browne Date: Mon, 4 Aug 2025 11:59:32 +0100 Subject: [PATCH] feat: Implement shared hooks for tool operations - Introduced `useToolApiCalls` for handling API calls with file processing and cancellation support. - Created `useToolOperation` to manage tool operations, including state management, error handling, and file processing. - Added `useToolResources` for managing blob URLs and generating thumbnails. - Developed `useToolState` for centralized state management of tool operations. - Refactored `useSplitOperation` to utilize the new shared hooks, simplifying the execution of split operations. - Updated `useSplitParameters` to remove mode state and integrate with the new parameter structure. - Enhanced error handling with `toolErrorHandler` utilities for standardized error extraction and messaging. - Implemented `toolOperationTracker` for creating operation tracking data for file context integration. - Added `toolResponseProcessor` for processing API response blobs based on handler configuration. --- CLAUDE.md | 60 ++- .../components/tools/split/SplitSettings.tsx | 17 +- .../tools/compress/useCompressOperation.ts | 288 ++---------- .../tools/convert/useConvertOperation.ts | 429 +++-------------- .../src/hooks/tools/ocr/useOCROperation.ts | 433 ++++++------------ .../src/hooks/tools/shared/useToolApiCalls.ts | 87 ++++ .../hooks/tools/shared/useToolOperation.ts | 241 ++++++++++ .../hooks/tools/shared/useToolResources.ts | 81 ++++ .../src/hooks/tools/shared/useToolState.ts | 137 ++++++ .../hooks/tools/split/useSplitOperation.ts | 305 +++--------- .../hooks/tools/split/useSplitParameters.ts | 15 +- frontend/src/tools/Split.tsx | 7 +- frontend/src/utils/toolErrorHandler.ts | 33 ++ frontend/src/utils/toolOperationTracker.ts | 28 ++ frontend/src/utils/toolResponseProcessor.ts | 45 ++ 15 files changed, 1013 insertions(+), 1193 deletions(-) create mode 100644 frontend/src/hooks/tools/shared/useToolApiCalls.ts create mode 100644 frontend/src/hooks/tools/shared/useToolOperation.ts create mode 100644 frontend/src/hooks/tools/shared/useToolResources.ts create mode 100644 frontend/src/hooks/tools/shared/useToolState.ts create mode 100644 frontend/src/utils/toolErrorHandler.ts create mode 100644 frontend/src/utils/toolOperationTracker.ts create mode 100644 frontend/src/utils/toolResponseProcessor.ts diff --git a/CLAUDE.md b/CLAUDE.md index 8bdd7c235..894c981b8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,12 +59,53 @@ Frontend designed for **stateful document processing**: Without cleanup: browser crashes with memory leaks. #### Tool Development -- **Pattern**: Follow `src/tools/Split.tsx` as reference implementation -- **File Access**: Tools receive `selectedFiles` prop (computed from activeFiles based on user selection) -- **File Selection**: Users select files in FileEditor (tool mode) → stored as IDs → computed to File objects for tools -- **Integration**: All files are part of FileContext ecosystem - automatic memory management and operation tracking -- **Parameters**: Tool parameter handling patterns still being standardized -- **Preview Integration**: Tools can implement preview functionality (see Split tool's thumbnail preview) + +**Architecture**: Modular hook-based system with clear separation of concerns: + +- **useToolOperation** (`frontend/src/hooks/tools/shared/useToolOperation.ts`): Main orchestrator hook + - Coordinates all tool operations with consistent interface + - Integrates with FileContext for operation tracking + - Handles validation, error handling, and UI state management + +- **Supporting Hooks**: + - **useToolState**: UI state management (loading, progress, error, files) + - **useToolApiCalls**: HTTP requests and file processing + - **useToolResources**: Blob URLs, thumbnails, ZIP downloads + +- **Utilities**: + - **toolErrorHandler**: Standardized error extraction and i18n support + - **toolResponseProcessor**: API response handling (single/zip/custom) + - **toolOperationTracker**: FileContext integration utilities + +**Tool Implementation Pattern**: +1. Create hook in `frontend/src/hooks/tools/[toolname]/use[ToolName]Operation.ts` +2. Define parameters interface and validation +3. Implement `buildFormData` function for API requests +4. Configure `useToolOperation` with endpoints and settings +5. UI components consume the hook's state and actions + +**Example Pattern** (see `useCompressOperation.ts`): +```typescript +export const useCompressOperation = () => { + const { t } = useTranslation(); + + return useToolOperation({ + operationType: 'compress', + endpoint: '/api/v1/misc/compress-pdf', + buildFormData, + filePrefix: 'compressed_', + validateParams: (params) => { /* validation logic */ }, + getErrorMessage: createStandardErrorHandler(t('compress.error.failed')) + }); +}; +``` + +**Benefits**: +- **Consistent**: All tools follow same pattern and interface +- **Maintainable**: Single responsibility hooks, easy to test and modify +- **i18n Ready**: Built-in internationalization support +- **Type Safe**: Full TypeScript support with generic interfaces +- **Memory Safe**: Automatic resource cleanup and blob URL management ## Architecture Overview @@ -126,7 +167,10 @@ Without cleanup: browser crashes with memory leaks. - **Core Status**: React SPA architecture complete with multi-tool workflow support - **State Management**: FileContext handles all file operations and tool navigation - **File Processing**: Production-ready with memory management for large PDF workflows (up to 100GB+) -- **Tool Integration**: Standardized tool interface - see `src/tools/Split.tsx` as reference +- **Tool Integration**: Modular hook architecture with `useToolOperation` orchestrator + - Individual hooks: `useToolState`, `useToolApiCalls`, `useToolResources` + - Utilities: `toolErrorHandler`, `toolResponseProcessor`, `toolOperationTracker` + - Pattern: Each tool creates focused operation hook, UI consumes state/actions - **Preview System**: Tool results can be previewed without polluting file context (Split tool example) - **Performance**: Web Worker thumbnails, IndexedDB persistence, background processing @@ -141,7 +185,7 @@ Without cleanup: browser crashes with memory leaks. - **Security**: When `DOCKER_ENABLE_SECURITY=false`, security-related classes are excluded from compilation - **FileContext**: All file operations MUST go through FileContext - never bypass with direct File handling - **Memory Management**: Manual cleanup required for PDF.js documents and blob URLs - don't remove cleanup code -- **Tool Development**: New tools should follow Split tool pattern (`src/tools/Split.tsx`) +- **Tool Development**: New tools should follow `useToolOperation` hook pattern (see `useCompressOperation.ts`) - **Performance Target**: Must handle PDFs up to 100GB+ without browser crashes - **Preview System**: Tools can preview results without polluting main file context (see Split tool implementation) diff --git a/frontend/src/components/tools/split/SplitSettings.tsx b/frontend/src/components/tools/split/SplitSettings.tsx index 50ca49f20..95e972eaf 100644 --- a/frontend/src/components/tools/split/SplitSettings.tsx +++ b/frontend/src/components/tools/split/SplitSettings.tsx @@ -3,6 +3,7 @@ import { useTranslation } from 'react-i18next'; import { SPLIT_MODES, SPLIT_TYPES, type SplitMode, type SplitType } from '../../../constants/splitConstants'; export interface SplitParameters { + mode: SplitMode | ''; pages: string; hDiv: string; vDiv: string; @@ -15,16 +16,12 @@ export interface SplitParameters { } export interface SplitSettingsProps { - mode: SplitMode | ''; - onModeChange: (mode: SplitMode | '') => void; parameters: SplitParameters; onParameterChange: (parameter: keyof SplitParameters, value: string | boolean) => void; disabled?: boolean; } const SplitSettings = ({ - mode, - onModeChange, parameters, onParameterChange, disabled = false @@ -125,8 +122,8 @@ const SplitSettings = ({