@zjlab-fe/data-hub-ui 0.9.0 → 0.10.0

package/dist/types/components/file-uploader/context/handler-registry.d.ts

@@ -0,0 +1,96 @@
+import type { UploadHandlers } from '../types';
+/**
+ * Per-file handler storage.
+ *
+ * When a file is added for upload, its handlers are registered here.
+ * Even if the originating component unmounts, the handlers remain
+ * available for the QueueManager to use during background uploads.
+ */
+export interface FileHandlerEntry {
+    /** The handlers specific to this file's upload context */
+    handlers: UploadHandlers;
+    /** Timestamp when handlers were registered */
+    registeredAt: number;
+    /** Optional metadata for debugging */
+    context?: string;
+}
+/**
+ * Global handler registry for background uploads.
+ *
+ * This registry stores handlers per-file, allowing uploads to continue
+ * even when the user navigates away from the page that initiated the upload.
+ *
+ * Flow:
+ * 1. Component calls addFiles() -> handlers are registered per file ID
+ * 2. User navigates away -> component unmounts but handlers persist
+ * 3. QueueManager continues -> looks up handlers by file ID
+ * 4. Upload completes -> handlers are cleaned up
+ *
+ * @example
+ * ```tsx
+ * // In page component
+ * const { addFiles } = useUpload();
+ * addFiles(files, {
+ *   getHandlers: (file) => ({
+ *     onGetUploadUrls: (name, parts) => api.getUrls(datasetId, name, parts, folderFromUI()),
+ *     // ... other handlers
+ *   })
+ * });
+ *
+ * // When user adds files, handlers are registered:
+ * // handlerRegistry.register(file.id, handlers)
+ *
+ * // User navigates away - no problem!
+ * // QueueManager uses: handlerRegistry.get(fileId)
+ * ```
+ */
+declare class HandlerRegistry {
+    private registry;
+    /**
+     * Register handlers for a file.
+     * Called when a file is added for upload.
+     */
+    register(fileId: string, handlers: UploadHandlers, context?: string): void;
+    /**
+     * Get handlers for a file.
+     * Returns undefined if file has no registered handlers.
+     */
+    get(fileId: string): UploadHandlers | undefined;
+    /**
+     * Check if handlers exist for a file.
+     */
+    has(fileId: string): boolean;
+    /**
+     * Remove handlers for a file.
+     * Called when upload completes, fails permanently, or is cancelled.
+     */
+    unregister(fileId: string): void;
+    /**
+     * Get all registered file IDs.
+     * Useful for debugging and cleanup.
+     */
+    getRegisteredFileIds(): string[];
+    /**
+     * Get entry with metadata for debugging.
+     */
+    getEntry(fileId: string): FileHandlerEntry | undefined;
+    /**
+     * Clear all registrations.
+     * Use with caution - mainly for testing or complete reset.
+     */
+    clear(): void;
+    /**
+     * Get count of registered handlers.
+     */
+    get size(): number;
+}
+/**
+ * Singleton instance of the handler registry.
+ * This is intentionally a module-level singleton, not React context,
+ * because it needs to persist completely independently of React lifecycle.
+ */
+export declare const handlerRegistry: HandlerRegistry;
+export {};
+/**
+ * Debug helper to log current registry state.
+ */

package/dist/types/components/file-uploader/context/upload-context.d.ts

@@ -0,0 +1,14 @@
+import type { UploadState, UploadContextValue, UploadConfig } from '../types';
+export declare const initialUploadState: UploadState;
+/**
+ * Default upload configuration (Provider level).
+ * Controls chunk sizes and concurrency - typically same across app.
+ */
+export declare const defaultUploadConfig: Required<UploadConfig>;
+export declare const UploadContext: import("react").Context<UploadContextValue | null>;
+/**
+ * Hook to consume upload context
+ * Must be used within UploadProvider
+ * @throws Error if used outside of UploadProvider
+ */
+export declare function useUploadContext(): UploadContextValue;

package/dist/types/components/file-uploader/context/upload-provider.d.ts

@@ -0,0 +1,47 @@
+import { type ReactNode } from 'react';
+import type { UploadConfig } from '../types';
+/**
+ * Props for UploadProvider component
+ *
+ * The provider manages shared state (files list, queue manager) and
+ * global upload configuration (chunk sizes, concurrency).
+ *
+ * For persistence, wrap with PersistenceProvider inside UploadProvider.
+ */
+export interface UploadProviderProps {
+    /** Global upload configuration (chunk sizes, concurrency) */
+    config?: UploadConfig;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * Upload Provider Component
+ *
+ * Provides shared upload state and global configuration across the application.
+ * Manages:
+ * - Files state (list of files, their status, progress)
+ * - QueueManager singleton (shared upload queue)
+ * - Global config (chunk sizes, concurrency)
+ *
+ * For persistence support, wrap your app with PersistenceProvider inside UploadProvider:
+ *
+ * @example
+ * ```tsx
+ * // App level - state management + global config
+ * <UploadProvider config={{ concurrentFiles: 3 }}>
+ *   <PersistenceProvider config={{ mode: 'indexeddb' }}>
+ *     <App />
+ *   </PersistenceProvider>
+ * </UploadProvider>
+ *
+ * // In App - use persistence hook
+ * const { pendingFiles, restoreFiles } = usePersistence();
+ *
+ * // Component level - provide handlers & per-usage options
+ * const { addFiles } = useUpload();
+ * ```
+ */
+export declare function UploadProvider({ config, children }: UploadProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace UploadProvider {
+    var displayName: string;
+}

package/dist/types/components/file-uploader/context/upload-reducer.d.ts

@@ -0,0 +1,6 @@
+import type { UploadState, UploadAction } from '../types';
+/**
+ * Reducer for upload state management
+ * Handles all file upload state transitions
+ */
+export declare function uploadReducer(state: UploadState, action: UploadAction): UploadState;

package/dist/types/components/file-uploader/context/use-upload-engine.d.ts

@@ -0,0 +1,22 @@
+import type { UploadFile } from '../types';
+/**
+ * Hook that integrates QueueManager with React context.
+ *
+ * This hook bridges the imperative QueueManager with React's declarative state.
+ * It provides functions to control uploads while keeping UI state in sync.
+ *
+ * Global config (chunk sizes, concurrency) comes from context.
+ * Handlers are provided per-file via addFiles().
+ *
+ * @returns Upload control functions: startUpload, pauseUpload, resumeUpload, cancelUpload
+ */
+export declare function useUploadEngine(): {
+    /** Start uploading a file */
+    startUpload: (uploadFile: UploadFile) => Promise<void>;
+    /** Pause an uploading file */
+    pauseUpload: (fileId: string) => void;
+    /** Resume a paused file */
+    resumeUpload: (fileId: string) => Promise<void>;
+    /** Cancel a file upload */
+    cancelUpload: (fileId: string) => Promise<void>;
+};

package/dist/types/components/file-uploader/demo/index.d.ts

@@ -0,0 +1,2 @@
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/types/components/file-uploader/engine/queue-callbacks.d.ts

@@ -0,0 +1,21 @@
+import type { Dispatch } from 'react';
+import type { QueueCallbacks } from './queue-types';
+import type { UploadAction } from '../types';
+/**
+ * Dependencies required to create queue callbacks.
+ * These are injected from the React hook to maintain reactivity.
+ */
+export interface QueueCallbackDeps {
+    /** React dispatch function for state updates */
+    dispatch: Dispatch<UploadAction>;
+}
+/**
+ * Creates QueueManager callbacks that integrate with React state.
+ *
+ * These callbacks are called by QueueManager during upload lifecycle:
+ * - onChunkProgress: When chunk upload progress updates
+ * - onChunkComplete: When a chunk finishes uploading
+ * - onChunkError: When a chunk upload fails
+ * - onFileComplete: When all chunks of a file are uploaded
+ */
+export declare function createQueueCallbacks({ dispatch }: QueueCallbackDeps): QueueCallbacks;

package/dist/types/components/file-uploader/engine/queue-manager.d.ts

@@ -0,0 +1,63 @@
+import type { UploadFile } from '../types';
+import type { QueueCallbacks, QueueConfig } from './queue-types';
+export type { QueueItem, QueueCallbacks, QueueConfig } from './queue-types';
+/**
+ * Manages upload queue with configurable concurrency.
+ *
+ * Handles scheduling of chunk uploads across multiple files,
+ * respecting concurrency limits for both files and chunks per file.
+ */
+export declare class QueueManager {
+    /** Pending items waiting to be uploaded */
+    private queue;
+    /** Currently uploading items, grouped by file ID */
+    private activeByFile;
+    /** Set of file IDs that are paused */
+    private pausedFiles;
+    /** Track chunk completion counts per file */
+    private fileChunkCounts;
+    private config;
+    private callbacks;
+    constructor(config: QueueConfig, callbacks: QueueCallbacks);
+    /**
+     * Add a file's chunks to the upload queue.
+     * Only pending chunks are added; completed chunks are skipped.
+     */
+    addFile(uploadFile: UploadFile): void;
+    /**
+     * Process queue and start uploads respecting concurrency limits.
+     * - Max `concurrentFiles` files can upload simultaneously
+     * - Each file can have max `concurrentChunks` chunks uploading
+     */
+    private processQueue;
+    /**
+     * Start uploading a single chunk.
+     * Handles progress, completion, and error callbacks.
+     */
+    private startUpload;
+    /** Remove an item from the active uploads map */
+    private removeFromActive;
+    /** Pause uploads for a file (aborts active uploads) */
+    pauseFile(fileId: string): void;
+    /** Resume uploads for a paused file */
+    resumeFile(fileId: string): void;
+    /** Cancel all uploads for a file and clean up */
+    cancelFile(fileId: string): void;
+    /** Abort all active uploads for a file */
+    private abortFileUploads;
+    /** Get count of active files and total active chunks */
+    getActiveCount(): {
+        files: number;
+        chunks: number;
+    };
+    /** Check if a file is currently paused */
+    isFilePaused(fileId: string): boolean;
+    /** Get number of items waiting in queue */
+    getQueueLength(): number;
+    /** Get number of pending queue items for a specific file */
+    getFileQueueLength(fileId: string): number;
+    /** Check if file has any items in queue or active uploads */
+    hasFileInQueue(fileId: string): boolean;
+    /** Clear all queue items for a file (used before re-adding on resume) */
+    clearFileFromQueue(fileId: string): void;
+}

package/dist/types/components/file-uploader/engine/queue-types.d.ts

@@ -0,0 +1,37 @@
+import type { ChunkState } from '../types';
+import type { UploadRequestConfig } from '../utils/upload-handler';
+/** Item in the upload queue */
+export interface QueueItem {
+    fileId: string;
+    file: File;
+    chunk: ChunkState;
+    uploadUrl: string;
+    chunkSize: number;
+    abortController: AbortController;
+}
+/** Callbacks for queue events */
+export interface QueueCallbacks {
+    onChunkUploadComplete: (fileId: string, partNum: number) => void;
+    onChunkComplete: (fileId: string, partNum: number) => Promise<{
+        success: boolean;
+        reason?: string;
+    }>;
+    onChunkError: (fileId: string, partNum: number, error: Error) => void;
+    onFileComplete: (fileId: string, result: {
+        succeeded: number;
+        total: number;
+        allSucceeded: boolean;
+    }) => Promise<void>;
+}
+/** Queue manager configuration */
+export interface QueueConfig {
+    concurrentFiles: number;
+    concurrentChunks: number;
+    requestConfig?: UploadRequestConfig;
+}
+/** Chunk count tracker for a file */
+export interface FileChunkCount {
+    total: number;
+    completed: number;
+    succeeded: number;
+}

package/dist/types/components/file-uploader/engine/queue-uploader.d.ts

@@ -0,0 +1,8 @@
+import type { QueueItem, QueueConfig } from './queue-types';
+export interface UploadResult {
+    item: QueueItem;
+    success: boolean;
+    error?: Error;
+}
+/** Upload a single queue item and return result */
+export declare function uploadQueueItem(item: QueueItem, config: QueueConfig): Promise<UploadResult>;

package/dist/types/components/file-uploader/hooks/use-upload-batch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hook for batch upload operations.
+ *
+ * Provides:
+ * - Start all pending files
+ * - Pause all uploading files
+ * - Resume all paused files
+ * - Cancel all uploads
+ *
+ * Use this hook when you need bulk control over multiple files.
+ *
+ * @example
+ * ```tsx
+ * function BatchControls() {
+ *   const { startAll, pauseAll, cancelAll } = useUploadBatch();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={startAll}>Start All</button>
+ *       <button onClick={pauseAll}>Pause All</button>
+ *       <button onClick={cancelAll}>Cancel All</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUploadBatch(): {
+    /** Start all pending files */
+    startAll: () => Promise<void>;
+    /** Pause all uploading files */
+    pauseAll: () => void;
+    /** Resume all paused files */
+    resumeAll: () => Promise<void>;
+    /** Cancel all uploads */
+    cancelAll: () => void;
+};

package/dist/types/components/file-uploader/hooks/use-upload-control.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook for single file upload controls.
+ *
+ * Provides:
+ * - Start a pending file
+ * - Pause an uploading file
+ * - Resume a paused file
+ * - Cancel an upload
+ *
+ * Use this hook when you only need to control individual file uploads.
+ *
+ * @example
+ * ```tsx
+ * function FileControlButtons({ fileId, status }: { fileId: string; status: string }) {
+ *   const { start, pause, resume, cancel } = useUploadControl();
+ *
+ *   return (
+ *     <div>
+ *       {status === 'pending' && <button onClick={() => start(fileId)}>Start</button>}
+ *       {status === 'uploading' && <button onClick={() => pause(fileId)}>Pause</button>}
+ *       {status === 'paused' && <button onClick={() => resume(fileId)}>Resume</button>}
+ *       <button onClick={() => cancel(fileId)}>Cancel</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUploadControl(): {
+    /** Start uploading a pending file */
+    start: (id: string) => Promise<void>;
+    /** Pause an uploading file */
+    pause: (id: string) => void;
+    /** Resume a paused file */
+    resume: (id: string) => Promise<void>;
+    /** Cancel a file upload */
+    cancel: (id: string) => Promise<void>;
+};

package/dist/types/components/file-uploader/hooks/use-upload-files.d.ts

@@ -0,0 +1,40 @@
+import type { UploadFile } from '../types';
+/**
+ * Hook for accessing upload file state and filtered lists.
+ *
+ * Provides:
+ * - All files in the upload queue
+ * - Filtered lists by status (pending, uploading, completed, failed, paused)
+ * - File lookup by ID
+ *
+ * Use this hook when you only need to display/read file data without controlling uploads.
+ *
+ * @example
+ * ```tsx
+ * function FileList() {
+ *   const { files, pendingFiles, completedFiles } = useUploadFiles();
+ *   return (
+ *     <div>
+ *       <h3>Pending: {pendingFiles.length}</h3>
+ *       <ul>{files.map(f => <li key={f.id}>{f.fileName}</li>)}</ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUploadFiles(): {
+    /** All files in the upload queue */
+    files: UploadFile[];
+    /** Get a specific file by ID */
+    getFileById: (id: string) => UploadFile | undefined;
+    /** Files waiting to be uploaded */
+    pendingFiles: UploadFile[];
+    /** Files currently uploading */
+    uploadingFiles: UploadFile[];
+    /** Successfully completed uploads */
+    completedFiles: UploadFile[];
+    /** Failed uploads */
+    failedFiles: UploadFile[];
+    /** Paused uploads */
+    pausedFiles: UploadFile[];
+};

package/dist/types/components/file-uploader/hooks/use-upload-operations.d.ts

@@ -0,0 +1,43 @@
+import type { UploadFile, AddFilesOptions } from '../types';
+/**
+ * Hook for file management operations.
+ *
+ * Provides:
+ * - Adding files to the upload queue
+ * - Removing individual files
+ * - Clearing completed/all files
+ *
+ * Use this hook when you need to manage the file queue without upload controls.
+ *
+ * @example
+ * ```tsx
+ * function FileInput({ datasetId }: { datasetId: string }) {
+ *   const { addFiles } = useUploadOperations();
+ *
+ *   return (
+ *     <input
+ *       type="file"
+ *       onChange={(e) =>
+ *         addFiles(e.target.files, {
+ *           getHandlers: (file) => ({
+ *             onGetUploadUrls: (fileName, partCount) =>
+ *               api.getUploadUrls(datasetId, fileName, partCount),
+ *             // ... other handlers
+ *           }),
+ *         })
+ *       }
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useUploadOperations(): {
+    /** Add files to the upload queue */
+    addFiles: (files: FileList | File[], addOptions: AddFilesOptions, runtime?: unknown) => UploadFile[] | undefined;
+    /** Remove a file from the queue */
+    removeFile: (id: string) => Promise<void>;
+    /** Clear all completed files */
+    clearCompleted: () => void;
+    /** Clear all files */
+    clearAll: () => void;
+};

package/dist/types/components/file-uploader/hooks/use-upload.d.ts

@@ -0,0 +1,85 @@
+import type { AddFilesOptions, UploadFile } from '../types';
+import type { FileWithPath } from '../components/utils/directory-reader';
+/**
+ * Main consumer hook for file uploads - Core functionality.
+ *
+ * This hook provides essential upload API with:
+ * - `files` - All files in the upload queue
+ * - `start`, `pause`, `resume`, `cancel` - Single file controls
+ * - `addFiles`, `removeFile` - File operations
+ *
+ * Use this hook for the most common upload scenarios.
+ * For extended functionality (batch operations, file selectors), use `useUploadExtend`.
+ *
+ * Global config (chunk sizes, concurrency) comes from UploadProvider.
+ * Handlers are provided per-file at selection time via addFiles options,
+ * allowing runtime-dependent targets (e.g., different folders/datasets).
+ *
+ * @example
+ * ```tsx
+ * function MyUploader({ datasetId }: { datasetId: string }) {
+ *   const { files, addFiles, start, pause } = useUpload();
+ *
+ *   return (
+ *     <>
+ *       <input
+ *         type="file"
+ *         onChange={(e) =>
+ *           addFiles(e.target.files, {
+ *             getHandlers: (file) => ({
+ *               onGetUploadUrls: (fileName, partCount) =>
+ *                 api.getUploadUrls(datasetId, fileName, partCount),
+ *               onPartComplete: (fileName, uploadId, partNum) =>
+ *                 api.markPartComplete(datasetId, uploadId, partNum),
+ *               onFileComplete: (fileName, uploadId) =>
+ *                 api.completeUpload(datasetId, uploadId),
+ *             }),
+ *           })
+ *         }
+ *       />
+ *       <div>
+ *         {files.map(f => (
+ *           <div key={f.id}>
+ *             {f.fileName}
+ *             <button onClick={() => start(f.id)}>Start</button>
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useUpload(): {
+    files: UploadFile[];
+    addFiles: (files: FileWithPath[], addOptions: AddFilesOptions, runtime?: unknown) => undefined;
+    removeFile: (id: string) => Promise<void>;
+    start: (id: string) => Promise<void>;
+    pause: (id: string) => void;
+    resume: (id: string) => Promise<void>;
+    cancel: (id: string) => Promise<void>;
+    /** Get a specific file by ID */
+    getFileById: (id: string) => UploadFile | undefined;
+    /** Files waiting to be uploaded */
+    pendingFiles: UploadFile[];
+    /** Files currently uploading */
+    uploadingFiles: UploadFile[];
+    /** Successfully completed uploads */
+    successFiles: UploadFile[];
+    /** Failed uploads */
+    failedFiles: UploadFile[];
+    /** Paused uploads */
+    pausedFiles: UploadFile[];
+    /** Start all pending files */
+    startAll: () => Promise<void>;
+    /** Pause all uploading files */
+    pauseAll: () => void;
+    /** Resume all paused files */
+    resumeAll: () => Promise<void>;
+    /** Cancel all uploads */
+    cancelAll: () => void;
+    /** Clear all succeeded files */
+    clearSucceeded: () => Promise<void>;
+    /** Clear all files */
+    clearAll: () => Promise<void>;
+};

package/dist/types/components/file-uploader/index.d.ts

@@ -0,0 +1,13 @@
+export { UploadProvider } from './context/upload-provider';
+export { Uploader as FileUploader } from './components/uploader';
+export { UploaderDropZone } from './components/uploader-drop-zone';
+export { UploaderFileListLayout } from './components/uploader-file-list';
+export { UploaderFileItem } from './components/uploader-file-item';
+export { useUpload } from './hooks/use-upload';
+export type { UploadFile, ChunkState, UploadHandlers, CallbackResult, GetUploadUrlsResult, UploadUrl, UploadConfig, AddFilesOptions, } from './types';
+export type { DropZoneError, UploaderDropZoneClassNames, UploaderDropZoneProps, } from './components/uploader-drop-zone';
+export type { FileWithPath } from './components/utils/directory-reader';
+export type { FileListClassNames } from './components/uploader-file-list';
+export type { UploaderFileItemClassNames } from './components/uploader-file-item';
+export { UploadStatus } from './constants';
+export type { UploadStatusType } from './constants';

package/dist/types/components/file-uploader/persistence/file-blob-store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * File Blob Store - IndexedDB storage for file blobs
+ *
+ * This store handles file blob persistence for the 'indexeddb' mode.
+ * Separate from metadata storage for cleaner data management and quota handling.
+ */
+/**
+ * File Blob Store class for file data persistence
+ */
+export declare class FileBlobStore {
+    private prefix;
+    private db;
+    constructor(prefix?: string);
+    /**
+     * Initialize the store (open database connection)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure database is initialized
+     */
+    private ensureDb;
+    /**
+     * Save a file blob
+     * @param fileId - Unique file identifier
+     * @param file - File object to store
+     */
+    saveBlob(fileId: string, file: File): Promise<void>;
+    /**
+     * Get a file by ID
+     * @param fileId - Unique file identifier
+     * @returns Reconstructed File object or null
+     */
+    getFile(fileId: string): Promise<File | null>;
+    /**
+     * Check if a file blob exists
+     */
+    hasBlob(fileId: string): Promise<boolean>;
+    /**
+     * Delete a file blob
+     */
+    deleteBlob(fileId: string): Promise<void>;
+    /**
+     * Delete multiple file blobs
+     */
+    deleteMany(fileIds: string[]): Promise<void>;
+    /**
+     * Clear all blobs
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get all stored file IDs
+     */
+    getAllIds(): Promise<string[]>;
+    /**
+     * Estimate storage usage for blobs
+     * @returns Estimated bytes used
+     */
+    estimateUsage(): Promise<number>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete the entire database (for mode switching)
+     */
+    deleteDatabase(): Promise<void>;
+}
+/**
+ * Default singleton instance
+ */
+export declare const fileBlobStore: FileBlobStore;