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

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

@@ -0,0 +1,116 @@
+/**
+ * File Handle Store - IndexedDB storage for FileSystemFileHandle
+ *
+ * This store handles FileSystemFileHandle persistence for the 'file-system-access' mode.
+ * FileSystemFileHandle can be stored in IndexedDB via structured clone.
+ *
+ * Note: After page reload, permission must be re-requested with a user gesture.
+ */
+/**
+ * Stored handle entry structure
+ */
+interface StoredHandleEntry {
+    /** File ID (key) */
+    id: string;
+    /** The FileSystemFileHandle - can be cloned to IndexedDB */
+    handle: FileSystemFileHandle;
+    /** Original file name at save time */
+    fileName: string;
+    /** Storage timestamp */
+    createdAt: number;
+}
+/**
+ * Permission check result
+ */
+export interface PermissionResult {
+    /** Whether permission is granted */
+    granted: boolean;
+    /** Permission state */
+    state: PermissionState;
+    /** Whether permission can be requested (user gesture available) */
+    canRequest: boolean;
+}
+/**
+ * File Handle Store class for FileSystemFileHandle persistence
+ */
+export declare class FileHandleStore {
+    private prefix;
+    private db;
+    constructor(prefix?: string);
+    /**
+     * Check if File System Access API is supported
+     */
+    static isSupported(): boolean;
+    /**
+     * Initialize the store (open database connection)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure database is initialized
+     */
+    private ensureDb;
+    /**
+     * Save a file handle
+     * @param fileId - Unique file identifier
+     * @param handle - FileSystemFileHandle to store
+     * @param fileName - Original file name
+     */
+    saveHandle(fileId: string, handle: FileSystemFileHandle, fileName?: string): Promise<void>;
+    /**
+     * Get a file handle by ID
+     */
+    getHandle(fileId: string): Promise<FileSystemFileHandle | null>;
+    /**
+     * Get handle entry with metadata
+     */
+    getHandleEntry(fileId: string): Promise<StoredHandleEntry | null>;
+    /**
+     * Check permission status for a handle
+     * @param handle - FileSystemFileHandle to check
+     * @param requestIfNeeded - Whether to request permission (requires user gesture)
+     */
+    checkPermission(handle: FileSystemFileHandle, requestIfNeeded?: boolean): Promise<PermissionResult>;
+    /**
+     * Get file from handle (with permission check)
+     * @param handle - FileSystemFileHandle
+     * @param requestPermission - Whether to request permission if needed
+     */
+    getFileFromHandle(handle: FileSystemFileHandle, requestPermission?: boolean): Promise<File | null>;
+    /**
+     * Check if a handle exists
+     */
+    hasHandle(fileId: string): Promise<boolean>;
+    /**
+     * Delete a handle
+     */
+    deleteHandle(fileId: string): Promise<void>;
+    /**
+     * Delete multiple handles
+     */
+    deleteMany(fileIds: string[]): Promise<void>;
+    /**
+     * Clear all handles
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get all stored file IDs
+     */
+    getAllIds(): Promise<string[]>;
+    /**
+     * Get all entries
+     */
+    getAllEntries(): Promise<StoredHandleEntry[]>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete the entire database (for mode switching)
+     */
+    deleteDatabase(): Promise<void>;
+}
+/**
+ * Default singleton instance
+ */
+export declare const fileHandleStore: FileHandleStore;
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * Persistence Module - File persistence for upload state
+ *
+ * Provides three persistence modes:
+ * - `repick`: No persistence; user reselects files after reload (default)
+ * - `indexeddb`: Store file blobs in IndexedDB for auto-resume
+ * - `file-system-access`: Store FileSystemFileHandle for efficient resume (Chromium + HTTPS)
+ *
+ * Storage architecture:
+ * - Metadata is ALWAYS stored in IndexedDB (separate database)
+ * - File blobs stored in IndexedDB when mode='indexeddb'
+ * - File handles stored in IndexedDB when mode='file-system-access'
+ *
+ * @example
+ * ```tsx
+ * // Wrap with PersistenceProvider inside UploadProvider
+ * <UploadProvider config={{ concurrentFiles: 3 }}>
+ *   <PersistenceProvider
+ *     config={{ mode: 'indexeddb' }}
+ *     restoreHandler={(runtime, meta) => ({
+ *       onGetUploadUrls: (name, count) => api.getUrls(runtime.folderId, name, count),
+ *       onPartComplete: (name, uploadId, part) => api.completePart(name, uploadId, part),
+ *       onFileComplete: (name, uploadId) => api.completeFile(name, uploadId),
+ *     })}
+ *   >
+ *     <App />
+ *   </PersistenceProvider>
+ * </UploadProvider>
+ *
+ * // In your component, use the hook
+ * const { pendingFiles, restoreFiles, repickFile } = usePersistence();
+ * ```
+ */
+export type { PersistenceMode, PersistenceStorageConfig, PersistenceConfig, // Deprecated, use PersistenceStorageConfig
+RestoreHandlerFn, StoredFileMeta, StoredChunkMeta, FileRecoveryResult, StorageQuotaInfo, PersistenceManagerInterface, FileSystemPermissionDescriptor, FileSystemHandleWithPermission, FilePickerOptions, WindowWithFileSystem, PendingFile, RestoreFilesResult, RepickFileResult, PersistenceContextValue, } from './types';
+export { MetadataStore, metadataStore } from './metadata-store';
+export { FileBlobStore, fileBlobStore } from './file-blob-store';
+export { FileHandleStore, fileHandleStore, type PermissionResult } from './file-handle-store';
+export { PersistenceManager, createPersistenceManager } from './persistence-manager';
+export { PersistenceContext, usePersistence, usePersistenceOptional } from './persistence-context';
+export { PersistenceProvider, type PersistenceProviderProps } from './persistence-provider';
+export { uploadFileToStoredMeta, storedMetaToUploadFile } from './use-persistence';

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

@@ -0,0 +1,63 @@
+/**
+ * Metadata Store - IndexedDB storage for file metadata
+ *
+ * This store handles ONLY file metadata, separate from actual file blob storage.
+ * Metadata is stored in IndexedDB regardless of persistence mode.
+ */
+import type { StoredFileMeta } from './types';
+/**
+ * Metadata Store class for file metadata persistence
+ */
+export declare class MetadataStore {
+    private prefix;
+    private db;
+    constructor(prefix?: string);
+    /**
+     * Initialize the store (open database connection)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure database is initialized
+     */
+    private ensureDb;
+    /**
+     * Save file metadata
+     */
+    saveMeta(meta: StoredFileMeta): Promise<void>;
+    /**
+     * Get file metadata by ID
+     */
+    getMeta(fileId: string): Promise<StoredFileMeta | null>;
+    /**
+     * Get all file metadata
+     */
+    getAllMeta(): Promise<StoredFileMeta[]>;
+    /**
+     * Delete file metadata by ID
+     */
+    deleteMeta(fileId: string): Promise<void>;
+    /**
+     * Delete multiple file metadata by IDs
+     */
+    deleteMany(fileIds: string[]): Promise<void>;
+    /**
+     * Clear all metadata
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Query metadata by status
+     */
+    getByStatus(status: string): Promise<StoredFileMeta[]>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete the entire database (for mode switching)
+     */
+    deleteDatabase(): Promise<void>;
+}
+/**
+ * Default singleton instance
+ */
+export declare const metadataStore: MetadataStore;

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

@@ -0,0 +1,20 @@
+/**
+ * Persistence Context
+ *
+ * Context for the pluggable PersistenceProvider component.
+ */
+import type { PersistenceContextValue } from './types';
+/**
+ * Persistence context - null before provider mounts
+ */
+export declare const PersistenceContext: import("react").Context<PersistenceContextValue | null>;
+/**
+ * Hook to consume persistence context
+ * Must be used within PersistenceProvider
+ */
+export declare function usePersistence(): PersistenceContextValue;
+/**
+ * Hook to optionally consume persistence context
+ * Returns null if not within PersistenceProvider (no error thrown)
+ */
+export declare function usePersistenceOptional(): PersistenceContextValue | null;

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

@@ -0,0 +1,103 @@
+/**
+ * Persistence Manager - Orchestrates file persistence across modes
+ *
+ * Manages mode selection, storage switching, and coordinated data recovery.
+ * Handles the complexity of switching between persistence modes and ensures
+ * data integrity during transitions.
+ *
+ * Storage separation:
+ * - Metadata: Always in IndexedDB (metadata-store)
+ * - File blobs: IndexedDB when mode='indexeddb' (file-blob-store)
+ * - File handles: IndexedDB when mode='file-system-access' (file-handle-store)
+ */
+import type { PersistenceMode, PersistenceStorageConfig, StoredFileMeta, FileRecoveryResult, StorageQuotaInfo, PersistenceManagerInterface } from './types';
+import { MetadataStore } from './metadata-store';
+import { FileBlobStore } from './file-blob-store';
+import { FileHandleStore } from './file-handle-store';
+/**
+ * Persistence Manager class
+ */
+export declare class PersistenceManager implements PersistenceManagerInterface {
+    private config;
+    private metadataStore;
+    private blobStore;
+    private handleStore;
+    private initialized;
+    private _mode;
+    constructor(config?: Partial<PersistenceStorageConfig>);
+    /**
+     * Current persistence mode
+     */
+    get mode(): PersistenceMode;
+    /**
+     * Initialize the persistence manager
+     * Handles mode switching if stored mode differs from config mode
+     */
+    initialize(): Promise<void>;
+    /**
+     * Hard reset - clear all persisted data (used during mode switch)
+     */
+    hardReset(): Promise<void>;
+    /**
+     * Save file metadata to IndexedDB
+     */
+    saveFileMeta(meta: StoredFileMeta): Promise<void>;
+    /**
+     * Save file blob to IndexedDB (indexeddb mode only)
+     */
+    saveFileBlob(fileId: string, file: File): Promise<void>;
+    /**
+     * Save file handle to IndexedDB (file-system-access mode only)
+     */
+    saveFileHandle(fileId: string, handle: FileSystemFileHandle): Promise<void>;
+    /**
+     * Load all stored file metadata
+     */
+    loadAllFileMeta(): Promise<StoredFileMeta[]>;
+    /**
+     * Recover a single file with its data/handle
+     */
+    recoverFile(meta: StoredFileMeta): Promise<FileRecoveryResult>;
+    /**
+     * Request permission for a file handle (requires user gesture)
+     * @param fileId - File ID to request permission for
+     * @returns The file if permission granted, null otherwise
+     */
+    requestFilePermission(fileId: string): Promise<File | null>;
+    /**
+     * Remove file data from all storage
+     */
+    removeFile(fileId: string): Promise<void>;
+    /**
+     * Remove multiple files from storage
+     */
+    removeFiles(fileIds: string[]): Promise<void>;
+    /**
+     * Clear all persisted data
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get storage quota information
+     */
+    getStorageQuota(): Promise<StorageQuotaInfo>;
+    /**
+     * Check if File System Access API is supported
+     */
+    isFileSystemAccessSupported(): boolean;
+    /**
+     * Get the raw stores for advanced usage
+     */
+    getStores(): {
+        metadata: MetadataStore;
+        blob: FileBlobStore;
+        handle: FileHandleStore;
+    };
+    /**
+     * Close all database connections
+     */
+    close(): void;
+}
+/**
+ * Create a persistence manager instance with the given config
+ */
+export declare function createPersistenceManager(config?: Partial<PersistenceStorageConfig>): PersistenceManager;

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

@@ -0,0 +1,49 @@
+/**
+ * Persistence Provider - Pluggable component for file persistence
+ *
+ * Wraps inside UploadProvider to add persistence capabilities.
+ * Handles auto-save, restore, and exposes pending files for dev to manage.
+ *
+ * @example
+ * ```tsx
+ * <UploadProvider config={{ concurrentFiles: 3 }}>
+ *   <PersistenceProvider
+ *     config={{ mode: 'indexeddb' }}
+ *     restoreHandler={(runtime, meta) => ({
+ *       onGetUploadUrls: (name, count) => api.getUrls(runtime.folderId, name, count),
+ *       onPartComplete: (name, uploadId, part) => api.completePart(name, uploadId, part),
+ *       onFileComplete: (name, uploadId) => api.completeFile(name, uploadId),
+ *     })}
+ *   >
+ *     <App />
+ *   </PersistenceProvider>
+ * </UploadProvider>
+ *
+ * // In App:
+ * const { pendingFiles, restoreFiles, repickFile } = usePersistence();
+ * ```
+ */
+import { type ReactNode } from 'react';
+import type { PersistenceStorageConfig, RestoreHandlerFn } from './types';
+export interface PersistenceProviderProps {
+    /** Storage configuration (mode, prefix, quota) */
+    config: PersistenceStorageConfig;
+    /** Auto-restore files on provider mount (default: true) */
+    autoRestore?: boolean;
+    /** Auto-save file state changes (default: true) */
+    autoSave?: boolean;
+    /** Cleanup completed uploads from storage (default: true) */
+    cleanupOnComplete?: boolean;
+    /**
+     * Handler to rebuild upload handlers for restored files.
+     * Called for each file that can be auto-restored.
+     * Return null if handlers cannot be rebuilt (file will be added to pendingFiles).
+     */
+    restoreHandler?: RestoreHandlerFn;
+    /** Child components */
+    children: ReactNode;
+}
+export declare function PersistenceProvider({ config, autoRestore, autoSave, cleanupOnComplete, restoreHandler, children, }: PersistenceProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace PersistenceProvider {
+    var displayName: string;
+}

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

@@ -0,0 +1,268 @@
+/**
+ * Persistence Types for File Uploader
+ *
+ * Defines types for three persistence modes:
+ * - `repick`: No persistence; user reselects files after reload
+ * - `indexeddb`: Store file blobs in IndexedDB for auto-resume
+ * - `file-system-access`: Store FileSystemFileHandle in IndexedDB (Chromium + HTTPS only)
+ */
+import type { UploadStatusType, ChunkStatusType } from '../constants';
+import type { UploadHandlers } from '../types';
+/**
+ * Persistence modes for file storage
+ */
+export type PersistenceMode = 'repick' | 'indexeddb' | 'file-system-access';
+/**
+ * Storage configuration for persistence (how to persist)
+ */
+export interface PersistenceStorageConfig {
+    /** Selected persistence mode */
+    mode: PersistenceMode;
+    /** Storage key prefix for namespacing (default: 'file-uploader') */
+    storageKeyPrefix?: string;
+    /** Maximum storage quota in bytes before cleanup warning (default: 500MB) */
+    maxStorageQuota?: number;
+}
+/**
+ * @deprecated Use PersistenceStorageConfig instead. This is kept for backward compatibility.
+ */
+export interface PersistenceConfig extends PersistenceStorageConfig {
+    /** @deprecated Move to PersistenceProviderProps.autoRestore */
+    autoRestore?: boolean;
+    /** @deprecated Move to PersistenceProviderProps.autoSave */
+    autoSave?: boolean;
+    /** @deprecated Move to PersistenceProviderProps.cleanupOnComplete */
+    cleanupOnComplete?: boolean;
+}
+/**
+ * Handler restore function type
+ * Called for each file being restored to rebuild its upload handlers
+ *
+ * @param runtime - The runtime context stored with the file (dev's custom data)
+ * @param meta - The stored file metadata
+ * @returns Upload handlers for the file, or null if cannot restore
+ *
+ * @example
+ * ```ts
+ * restoreHandler: (runtime, meta) => {
+ *   const { folderId } = runtime as { folderId: string };
+ *   return {
+ *     onGetUploadUrls: (name, count) => api.getUrls(folderId, name, count),
+ *     onPartComplete: (name, uploadId, part) => api.completePart(name, uploadId, part),
+ *     onFileComplete: (name, uploadId) => api.completeFile(name, uploadId),
+ *   };
+ * }
+ * ```
+ */
+export type RestoreHandlerFn = (runtime: unknown, meta: StoredFileMeta) => UploadHandlers | null;
+/**
+ * Stored chunk metadata (without actual data)
+ */
+export interface StoredChunkMeta {
+    partNum?: number;
+    status: ChunkStatusType;
+    progress: number;
+    uploadUrl?: string;
+    error?: string;
+}
+/**
+ * Stored file metadata - saved in IndexedDB for all modes
+ * This is separate from the actual file blob storage
+ */
+export interface StoredFileMeta {
+    /** Unique file ID */
+    id: string;
+    /** Original file name */
+    fileName: string;
+    /** File size in bytes */
+    fileSize: number;
+    /** Relative path of the file */
+    relativePath: string;
+    /** File last modified timestamp */
+    lastModified: number;
+    /** Current upload status */
+    status: UploadStatusType;
+    /** Upload progress (0-100) */
+    progress: number;
+    /** Server-assigned upload ID */
+    uploadId: string;
+    /** Chunk states */
+    chunks: StoredChunkMeta[];
+    /** Chunk size used for this upload */
+    chunkSize: number;
+    /** Arbitrary runtime context for handler rebuild */
+    runtime?: unknown;
+    /** Error message if failed */
+    error?: string;
+    /** Structured error code */
+    errorCode?: string;
+    /** Number of retry attempts */
+    retryCount?: number;
+    /** File creation timestamp */
+    createdAt: number;
+    /** Last updated timestamp */
+    updatedAt: number;
+    /** MIME type of the file */
+    mimeType?: string;
+    /** Hash of file content for integrity check (optional) */
+    contentHash?: string;
+}
+/**
+ * Result of file recovery operation
+ */
+export interface FileRecoveryResult {
+    /** Successfully recovered file metadata */
+    meta: StoredFileMeta;
+    /** Recovered File object (if available) */
+    file: File | null;
+    /** FileSystemFileHandle (for file-system-access mode) */
+    handle?: FileSystemFileHandle;
+    /** Whether user action is needed (e.g., permission grant, repick) */
+    needsUserAction: boolean;
+    /** Reason for needing user action */
+    userActionReason?: 'permission_required' | 'repick_required' | 'file_modified';
+}
+/**
+ * Storage quota information
+ */
+export interface StorageQuotaInfo {
+    /** Used storage in bytes */
+    used: number;
+    /** Available storage quota in bytes */
+    quota: number;
+    /** Percentage of quota used (0-100) */
+    usagePercent: number;
+}
+/**
+ * Persistence manager interface
+ */
+export interface PersistenceManagerInterface {
+    /** Current persistence mode */
+    readonly mode: PersistenceMode;
+    /** Initialize the persistence manager */
+    initialize(): Promise<void>;
+    /** Save file metadata */
+    saveFileMeta(meta: StoredFileMeta): Promise<void>;
+    /** Save file blob (indexeddb mode only) */
+    saveFileBlob(fileId: string, blob: Blob): Promise<void>;
+    /** Save file handle (file-system-access mode only) */
+    saveFileHandle(fileId: string, handle: FileSystemFileHandle): Promise<void>;
+    /** Load all stored file metadata */
+    loadAllFileMeta(): Promise<StoredFileMeta[]>;
+    /** Recover a single file with its data/handle */
+    recoverFile(meta: StoredFileMeta): Promise<FileRecoveryResult>;
+    /** Remove file data from storage */
+    removeFile(fileId: string): Promise<void>;
+    /** Clear all persisted data */
+    clearAll(): Promise<void>;
+    /** Get storage quota information */
+    getStorageQuota(): Promise<StorageQuotaInfo>;
+    /** Check if file-system-access mode is supported */
+    isFileSystemAccessSupported(): boolean;
+}
+/**
+ * Pending file that needs user action to restore
+ */
+export interface PendingFile {
+    /** Unique file ID */
+    id: string;
+    /** Original file name - dev can show this to guide user */
+    fileName: string;
+    /** File size in bytes */
+    fileSize: number;
+    /** File last modified timestamp */
+    lastModified: number;
+    /** Upload progress before interruption (0-100) */
+    progress: number;
+    /** Reason why file needs action */
+    reason: 'permission_required' | 'repick_required' | 'file_modified' | 'handlers_unavailable';
+    /** Full metadata for internal use */
+    meta: StoredFileMeta;
+    /** FileSystemFileHandle if available (file-system-access mode) */
+    handle?: FileSystemFileHandle;
+}
+/**
+ * Result of restoreFiles operation (for file-system-access mode)
+ */
+export interface RestoreFilesResult {
+    /** Successfully restored file IDs */
+    restored: string[];
+    /** Files that failed to restore */
+    failed: Array<{
+        id: string;
+        reason: 'permission_denied' | 'file_modified' | 'file_not_found' | 'unknown_error';
+        fileName: string;
+    }>;
+}
+/**
+ * Result of repickFile operation
+ */
+export type RepickFileResult = {
+    success: true;
+} | {
+    success: false;
+    reason: 'name_mismatch';
+    expected: string;
+    actual: string;
+} | {
+    success: false;
+    reason: 'size_mismatch';
+    expected: number;
+    actual: number;
+} | {
+    success: false;
+    reason: 'modified_mismatch';
+    expected: number;
+    actual: number;
+} | {
+    success: false;
+    reason: 'file_not_pending';
+};
+/**
+ * Persistence context value exposed via usePersistence hook
+ */
+export interface PersistenceContextValue {
+    /** Whether persistence is initialized */
+    isInitialized: boolean;
+    /** Current persistence mode */
+    mode: PersistenceMode;
+    /** Files pending user action to restore */
+    pendingFiles: PendingFile[];
+    /**
+     * Restore files by requesting permission (file-system-access mode)
+     * Call this after user confirms they want to restore
+     */
+    restoreFiles: (fileIds?: string[]) => Promise<RestoreFilesResult>;
+    /**
+     * Repick a file (repick mode)
+     * Dev passes the file user selected, we validate and restore
+     */
+    repickFile: (fileId: string, file: File) => Promise<RepickFileResult>;
+    /** Dismiss a pending file without restoring */
+    dismissFile: (fileId: string) => Promise<void>;
+    /** Dismiss all pending files */
+    dismissAll: () => Promise<void>;
+    /** Storage quota info */
+    storageQuota: StorageQuotaInfo | null;
+}
+/**
+ * File-system-access API types (for TypeScript)
+ */
+export interface FileSystemPermissionDescriptor {
+    mode?: 'read' | 'readwrite';
+}
+export interface FileSystemHandleWithPermission extends FileSystemFileHandle {
+    queryPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
+    requestPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
+}
+export interface FilePickerOptions {
+    types?: Array<{
+        description?: string;
+        accept: Record<string, string[]>;
+    }>;
+    excludeAcceptAllOption?: boolean;
+    multiple?: boolean;
+}
+export interface WindowWithFileSystem extends Window {
+    showOpenFilePicker(options?: FilePickerOptions): Promise<FileSystemFileHandle[]>;
+}