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

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

@@ -0,0 +1,78 @@
+/**
+ * Persistence Hooks - React integration for file persistence
+ *
+ * Provides hooks for:
+ * - Auto-saving file state changes
+ * - Restoring files on mount
+ * - Converting between UploadFile and StoredFileMeta
+ */
+import type { UploadFile, UploadState } from '../types';
+import type { StoredFileMeta, PersistenceConfig, FileRecoveryResult } from './types';
+import { PersistenceManager } from './persistence-manager';
+/**
+ * Convert UploadFile to StoredFileMeta (for saving)
+ */
+export declare function uploadFileToStoredMeta(file: UploadFile): StoredFileMeta;
+/**
+ * Convert StoredFileMeta back to partial UploadFile (file prop will be added by recovery)
+ */
+export declare function storedMetaToUploadFile(meta: StoredFileMeta, file: File | null): UploadFile | null;
+/**
+ * Result of restore operation
+ */
+export interface RestoreResult {
+    /** Successfully restored files */
+    restored: UploadFile[];
+    /** Files that need user action (repick/permission) */
+    needsAction: Array<{
+        meta: StoredFileMeta;
+        reason: FileRecoveryResult['userActionReason'];
+        handle?: FileSystemFileHandle;
+    }>;
+}
+/**
+ * Hook options
+ */
+export interface UsePersistenceOptions {
+    /** Persistence configuration */
+    config?: Partial<PersistenceConfig>;
+    /** Called when files are restored */
+    onRestore?: (result: RestoreResult) => void;
+    /** Called when a file needs user action */
+    onNeedsAction?: (fileId: string, reason: FileRecoveryResult['userActionReason']) => void;
+}
+/**
+ * Hook return type
+ */
+export interface UsePersistenceReturn {
+    /** Persistence manager instance */
+    manager: PersistenceManager | null;
+    /** Whether persistence is initialized */
+    isInitialized: boolean;
+    /** Current persistence mode */
+    mode: PersistenceManager['mode'] | null;
+    /** Save current files state */
+    saveFiles: (files: UploadFile[]) => Promise<void>;
+    /** Restore files from storage */
+    restoreFiles: () => Promise<RestoreResult>;
+    /** Request permission for a file (file-system-access mode) */
+    requestPermission: (fileId: string) => Promise<File | null>;
+    /** Remove a file from storage */
+    removeFile: (fileId: string) => Promise<void>;
+    /** Clear all storage */
+    clearAll: () => Promise<void>;
+}
+/**
+ * Create persistence manager hook
+ * This is a factory that creates the manager - should be called once at provider level
+ */
+export declare function usePersistenceManager(config?: Partial<PersistenceConfig>): UsePersistenceReturn;
+/**
+ * Hook to auto-save file state changes
+ * Should be used within UploadProvider
+ */
+export declare function useAutoSave(manager: PersistenceManager | null, state: UploadState, enabled?: boolean): void;
+/**
+ * Hook to cleanup completed uploads from storage
+ */
+export declare function useCleanupCompleted(manager: PersistenceManager | null, state: UploadState, enabled?: boolean): void;

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

@@ -0,0 +1,138 @@
+import type { UploadStatusType, ChunkStatusType } from './constants';
+import type { QueueManager } from './engine/queue-manager';
+export interface UploadUrl {
+    uploadUrl: string;
+    partNum: number;
+}
+export interface ChunkState {
+    partNum: number;
+    status: ChunkStatusType;
+    progress: number;
+    uploadUrl?: string;
+    error?: string;
+}
+export interface UploadFile {
+    id: string;
+    file: File;
+    fileName: string;
+    fileSize: number;
+    lastModified: number;
+    status: UploadStatusType;
+    progress: number;
+    uploadId: string;
+    chunks: ChunkState[];
+    chunkSize: number;
+    runtime?: unknown;
+    error?: string;
+    errorCode?: string;
+    retryCount?: number;
+    createdAt: number;
+}
+export type GetUploadUrlsResult = {
+    success: false;
+    reason?: string;
+} | {
+    success: true;
+    uploadInfo: {
+        uploadUrls: UploadUrl[];
+        uploadId: string;
+    };
+};
+export type CallbackResult = {
+    success: true;
+} | {
+    success: false;
+    reason?: string;
+};
+/**
+ * Upload lifecycle handler callbacks
+ * These hooks allow consumers to integrate with the upload process at various stages
+ */
+export interface UploadHandlers {
+    /** Called before requesting upload URLs. Return { status: false } to cancel upload */
+    onBeforeUpload?: (file: UploadFile) => Promise<CallbackResult>;
+    /** Request upload URLs from server (required) */
+    onGetUploadUrls: (fileName: string, partCount: number) => Promise<GetUploadUrlsResult>;
+    /** Called after URLs received, before chunk uploads begin */
+    onUploadStart?: (file: UploadFile) => void;
+    /** Called when file progress updates (0-100) */
+    onProgress?: (file: UploadFile, progress: number) => void;
+    /** Called when a chunk upload completes (required) */
+    onPartComplete: (fileName: string, uploadId: string, partNum: number) => Promise<CallbackResult>;
+    /** Called when upload is paused */
+    onPause?: (file: UploadFile) => void;
+    /** Called when upload is resumed */
+    onResume?: (file: UploadFile) => void;
+    /** Called when entire file upload completes (required) */
+    onFileComplete: (fileName: string, uploadId: string) => Promise<CallbackResult>;
+    /** Called when upload is successful */
+    onUploadSuccess?: (file: UploadFile) => void;
+    /** Called when upload is cancelled */
+    onUploadCancel?: (fileName: string, uploadId: string) => Promise<CallbackResult>;
+    /** Called when file is deleted */
+    onDeleteFile?: (file: UploadFile) => Promise<CallbackResult>;
+    /** Called when upload is retried (smart or full retry) */
+    onRetry?: (file: UploadFile, retryType: 'smart' | 'full') => void;
+    /** Called when an error occurs during upload */
+    onError?: (file: UploadFile, error: Error) => void;
+}
+export interface UploadConfig {
+    /** Maximum chunk size in bytes */
+    maxChunkSize?: number;
+    /** Minimum chunk size in bytes */
+    minChunkSize?: number;
+    /** Number of concurrent chunk uploads per file */
+    concurrentChunks?: number;
+    /** Number of concurrent file uploads */
+    concurrentFiles?: number;
+}
+type AddFilesHandlerOption = {
+    /**
+     * Static handlers applied to all files in a single addFiles call
+     */
+    handlers: UploadHandlers;
+    getHandlers?: never;
+} | {
+    /**
+     * Factory to derive handlers per file (runtime context like folder selection)
+     */
+    handlers?: never;
+    getHandlers: (file: File) => UploadHandlers;
+};
+export type AddFilesOptions = AddFilesHandlerOption;
+export interface UploadState {
+    files: UploadFile[];
+}
+export type UploadAction = {
+    type: 'ADD_FILES';
+    files: UploadFile[];
+} | {
+    type: 'UPDATE_FILE';
+    id: string;
+    updates: Partial<UploadFile>;
+} | {
+    type: 'UPDATE_CHUNK';
+    fileId: string;
+    partNum: number;
+    updates: Partial<ChunkState>;
+} | {
+    type: 'REMOVE_FILE';
+    id: string;
+} | {
+    type: 'CLEAR_COMPLETED';
+} | {
+    type: 'CLEAR_ALL';
+};
+export interface UploadContextValue {
+    /** Upload state (files list, processing status) */
+    state: UploadState;
+    /** Dispatch function for state updates */
+    dispatch: React.Dispatch<UploadAction>;
+    /** Global upload configuration (chunk sizes, concurrency) */
+    config: Required<UploadConfig>;
+    /** Shared QueueManager ref - singleton across all useUploadEngine consumers */
+    queueManagerRef: React.MutableRefObject<QueueManager | null>;
+    /** Get or create the QueueManager singleton instance */
+    getQueueManager: () => QueueManager;
+}
+export {};

package/dist/types/components/file-uploader/utils/chunk-handlers.d.ts

@@ -0,0 +1,40 @@
+import type { ChunkState, UploadConfig } from '../types';
+/**
+ * Calculate optimal chunk size based on file size and config constraints
+ */
+export declare function calculateChunkSize(fileSize: number, config: Required<UploadConfig>): number;
+/**
+ * Calculate total number of chunks for a file
+ */
+export declare function calculateTotalChunks(fileSize: number, chunkSize: number): number;
+/**
+ * Create initial chunk states for a file
+ * @param fileSize - Total file size in bytes
+ * @param chunkSize - Size of each chunk in bytes
+ * @returns Array of ChunkState objects
+ */
+export declare function createChunks(fileSize: number, chunkSize: number): ChunkState[];
+/**
+ * Extract a specific chunk blob from file
+ * @param file - The File object
+ * @param partNum - 0-indexed part number
+ * @param chunkSize - Size of each chunk in bytes
+ * @returns Blob containing the chunk data
+ */
+export declare function getChunkBlob(file: File, partNum: number, chunkSize: number): Blob;
+/**
+ * Get chunk byte range info
+ * @param fileSize - Total file size
+ * @param partNum - 0-indexed part number
+ * @param chunkSize - Size of each chunk
+ * @returns Object with start, end, and size
+ */
+export declare function getChunkRange(fileSize: number, partNum: number, chunkSize: number): {
+    start: number;
+    end: number;
+    size: number;
+};
+/**
+ * Generate unique upload file ID
+ */
+export declare function generateUploadId(): string;

package/dist/types/components/file-uploader/utils/ensure-handlers.d.ts

@@ -0,0 +1,7 @@
+import type { Dispatch } from 'react';
+import type { UploadHandlers, UploadFile, UploadAction } from '../types';
+/**
+ * Pure helper to fetch and validate handlers for a file.
+ * Returns null and dispatches failure if required handlers are missing.
+ */
+export declare function ensureHandlers(uploadFile: UploadFile, dispatch: Dispatch<UploadAction>): UploadHandlers | null;

package/dist/types/components/file-uploader/utils/error-handler.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Standard error codes for upload operations.
+ * Allows consumers to handle specific error scenarios.
+ *
+ * Using const object instead of enum for compatibility with --erasableSyntaxOnly
+ * (TypeScript 5.8+) and better tree-shaking.
+ */
+export declare const UPLOAD_ERROR_CODE: {
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly ABORT: "ABORT";
+    readonly URL_REQUEST_FAILED: "URL_REQUEST_FAILED";
+    readonly CHUNK_UPLOAD_FAILED: "CHUNK_UPLOAD_FAILED";
+    readonly MERGE_FAILED: "MERGE_FAILED";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly FILE_TOO_LARGE: "FILE_TOO_LARGE";
+    readonly INVALID_FILE_TYPE: "INVALID_FILE_TYPE";
+    readonly FILE_VALIDATION_FAILED: "FILE_VALIDATION_FAILED";
+    readonly MISSING_FILE: "MISSING_FILE";
+    readonly MISSING_HANDLER: "MISSING_HANDLER";
+    readonly INVALID_STATE: "INVALID_STATE";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+export type UPLOAD_ERROR_CODE_TYPE = (typeof UPLOAD_ERROR_CODE)[keyof typeof UPLOAD_ERROR_CODE];
+/**
+ * Structured error object with code, message, and context.
+ */
+export interface UploadError {
+    code: UPLOAD_ERROR_CODE_TYPE;
+    message: string;
+    originalError?: Error;
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a structured upload error.
+ */
+export declare function createUploadError(code: UPLOAD_ERROR_CODE_TYPE, message: string, originalError?: Error, context?: Record<string, unknown>): UploadError;
+/**
+ * Parse an unknown error into a structured UploadError.
+ * Attempts to extract meaningful information from various error types.
+ */
+export declare function parseError(error: unknown, defaultMessage?: string): UploadError;
+/**
+ * Type guard to check if an error is an UploadError.
+ */
+export declare function isUploadError(error: unknown): error is UploadError;
+/**
+ * Get a user-friendly error message for display.
+ * Provides actionable guidance when possible.
+ */
+export declare function getUserFriendlyMessage(error: UploadError): string;
+/**
+ * Determine if an error is recoverable (retry might work).
+ */
+export declare function isRecoverableError(error: UploadError): boolean;
+/**
+ * Determine if an error should trigger automatic retry.
+ */
+export declare function shouldAutoRetry(error: UploadError, attemptCount: number, maxAttempts?: number): boolean;

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

@@ -0,0 +1,72 @@
+import type { UploadFile, ChunkState } from '../types';
+/**
+ * Result of preparing chunks for resume
+ */
+export interface ResumeChunksResult {
+    /** Chunk part numbers that need to be uploaded */
+    pendingPartNums: number[];
+    /** Total chunks to upload */
+    pendingCount: number;
+    /** Already completed chunks */
+    completedCount: number;
+}
+/**
+ * Get chunks that need to be uploaded after a resume.
+ * Returns pending and failed chunks (excludes completed).
+ */
+export declare function getChunksForResume(file: UploadFile): ResumeChunksResult;
+/**
+ * Reset interrupted chunks to pending state.
+ * Called when pausing - any uploading chunks should be marked pending.
+ * Returns updated chunks array.
+ */
+export declare function resetInterruptedChunks(chunks: ChunkState[]): ChunkState[];
+/**
+ * Check if a file has any chunks that can be resumed.
+ * Returns true if there are pending or failed chunks.
+ */
+export declare function canResumeFile(file: UploadFile): boolean;
+/**
+ * Calculate progress from completed chunks.
+ */
+export declare function calculateProgressFromChunks(chunks: ChunkState[]): number;
+/**
+ * Filter upload URLs to only include pending chunks.
+ * Used when resuming to avoid re-uploading completed chunks.
+ */
+export declare function filterUrlsForPendingChunks(uploadUrls: {
+    partNum: number;
+    uploadUrl: string;
+}[], pendingPartNums: number[]): {
+    partNum: number;
+    uploadUrl: string;
+}[];
+/**
+ * Result of preparing chunks for retry
+ */
+export interface RetryChunksResult {
+    /** Chunk part numbers that failed */
+    failedPartNums: number[];
+    /** Total failed chunks */
+    failedCount: number;
+    /** Already completed chunks */
+    completedCount: number;
+    /** Has any failed chunks */
+    hasFailed: boolean;
+}
+/**
+ * Get chunks that failed and need to be retried.
+ * Returns only FAILED chunks, preserves COMPLETED chunks.
+ */
+export declare function getFailedChunks(file: UploadFile): RetryChunksResult;
+/**
+ * Reset only failed chunks to pending state.
+ * Preserves completed chunks for efficient retry.
+ * Returns updated chunks array.
+ */
+export declare function resetFailedChunks(chunks: ChunkState[]): ChunkState[];
+/**
+ * Reset all chunks to pending state (for full retry).
+ * Used when smart retry fails or server state is lost.
+ */
+export declare function resetAllChunks(chunks: ChunkState[]): ChunkState[];

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

@@ -0,0 +1,17 @@
+export interface UploadChunkResult {
+    success: boolean;
+    partNum: number;
+    error?: Error;
+}
+export type ChunkProgressCallback = (partNum: number, progress: number) => void;
+export interface UploadRequestConfig {
+    timeout?: number;
+    withCredentials?: boolean;
+    headers?: Record<string, string>;
+}
+/** Upload a chunk with automatic retry and exponential backoff */
+export declare function uploadChunkWithRetry(chunk: Blob, uploadUrl: string, partNum: number, options?: {
+    signal?: AbortSignal;
+    requestConfig?: UploadRequestConfig;
+    maxRetries?: number;
+}): Promise<UploadChunkResult>;

package/dist/types/components/file-uploader/utils/validate-handlers.d.ts

@@ -0,0 +1,6 @@
+import type { UploadHandlers } from '../types';
+/**
+ * Get list of missing required handler names.
+ * Returns empty array if all required handlers are present.
+ */
+export declare function getMissingHandlers(handlers: UploadHandlers): string[];

package/dist/types/components/section-heading/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { type JSX } from 'react';
 import './index.css';
 type Align = 'left' | 'center' | 'right';
 type Size = 'sm' | 'md' | 'lg';

package/dist/types/components/tip-tap/extensions/index.d.ts

@@ -1,2 +1,2 @@
-export declare const editorExtensions: (placeholder?: string) => (import("@tiptap/core").Extension<import("@tiptap/starter-kit").StarterKitOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-text-style").TextStyleOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-style").ColorOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-align").TextAlignOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-highlight").HighlightOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-image").ImageOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableRowOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-code-block-lowlight").CodeBlockLowlightOptions, any> | import("@tiptap/core").Extension<any, any> | import("@tiptap/core").Extension<import("@tiptap/extension-placeholder").PlaceholderOptions, any> | import("@tiptap/core").Extension<import("@tiptap/markdown").MarkdownExtensionOptions, import("@tiptap/markdown").MarkdownExtensionStorage>)[];
+export declare const editorExtensions: (placeholder?: string) => (import("@tiptap/core").Extension<import("@tiptap/starter-kit").StarterKitOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-placeholder").PlaceholderOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-text-style").TextStyleOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-style").ColorOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-align").TextAlignOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-highlight").HighlightOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-image").ImageOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableRowOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-code-block-lowlight").CodeBlockLowlightOptions, any> | import("@tiptap/core").Extension<import("@tiptap/markdown").MarkdownExtensionOptions, import("@tiptap/markdown").MarkdownExtensionStorage> | import("@tiptap/core").Extension<any, any>)[];
 export declare const readerExtensions: () => (import("@tiptap/core").Extension<import("@tiptap/starter-kit").StarterKitOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-text-style").TextStyleOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-style").ColorOptions, any> | import("@tiptap/core").Extension<import("@tiptap/extension-text-align").TextAlignOptions, any> | import("@tiptap/core").Mark<import("@tiptap/extension-highlight").HighlightOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-image").ImageOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-table").TableRowOptions, any> | import("@tiptap/core").Node<import("@tiptap/extension-code-block-lowlight").CodeBlockLowlightOptions, any>)[];