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

package/.github/instructions/i.instructions.md

@@ -0,0 +1,249 @@
+---
+applyTo: '**'
+---
+Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.
+
+INITIALIZATION PHASE:
+When user provides initial project instruction:
+- STOP and analyze if the instruction is high-level or lacks detail
+- ASK clarifying questions about:
+  * Specific features and functionality required
+  * Technology stack preferences
+  * UI/UX requirements and design preferences
+  * Data models and business logic
+  * Integration requirements (APIs, databases, third-party services)
+  * User workflows and interactions
+  * Performance requirements
+  * Security and authentication needs
+- Continue asking questions until user explicitly says "enough" or "that's sufficient"
+- NEVER start coding during this phase
+- Focus ONLY on understanding requirements completely
+
+AFTER REQUIREMENTS GATHERING:
+Once user confirms requirements are sufficient:
+- Check if a bundler/package manager is detected (package.json, vite.config, etc.)
+- If bundler detected: Create ONLY feature_list.json
+- If NO bundler detected: Create init.sh AND feature_list.json
+- DO NOT write any code yet
+- STOP after creating these files
+
+FEATURE_LIST.JSON TEMPLATE:
+``` json
+{
+  "features": [
+    {
+      "id": 1,
+      "category": "functional",
+      "description": "Clear one-line description of what user can do",
+      "steps": [
+        "Concrete step 1 to test",
+        "Concrete step 2 to test",
+        "Concrete step 3 to verify expected outcome"
+      ],
+      "passes": false,
+      "estimatedTime": "15-20 minutes",
+      "dependencies": []
+    }
+  ]
+}
+```
+
+Categories: "functional", "performance", "security", "ui/ux", "data", "integration"
+
+CLAUDE-PROGRESS.TXT TEMPLATE:
+```
+=== Session [Date/Time] ===
+Feature ID: [#]
+Feature: [Feature description from feature_list.json]
+Implementation Approach: [Brief description of how it was implemented]
+Files Created/Modified:
+- file1.js (85 lines) - [what was changed]
+- file2.html (45 lines) - [what was changed]
+- mock/testData.js (150 lines - mock data)
+Status: Completed / Partially Complete / Blocked
+Changes Made:
+- [Specific change 1]
+- [Specific change 2]
+Issues Encountered:
+- [Any problems or limitations]
+Solutions Applied:
+- [How issues were resolved]
+File Size Check: All files under 120 lines ✓ / Required refactoring ✗
+Tests Performed:
+- [What tests were run]
+Next Feature Suggested: [Feature ID and description]
+App State: Working / Needs Testing / Broken
+---
+```
+
+INIT.SH TEMPLATE (Only if no bundler detected):
+```
+#!/bin/bash
+# Purpose: Start development environment
+# Should include:
+# - Dependency installation (if needed)
+# - Database startup (if applicable)
+# - Development server startup
+# - Any required environment variables
+# Must be runnable multiple times safely
+```
+
+FEATURE SIZE REQUIREMENTS:
+- Each feature must be completable in ONE conversation session
+- Break down complex features into multiple small features
+- Each feature should take 15-30 minutes maximum
+- Features must be independently testable
+- Features must be focused on ONE specific capability
+- Example: Instead of "User authentication system", break into:
+  * "User can register with email and password"
+  * "User can login with credentials"
+  * "User can logout"
+  * "User can reset password via email"
+
+EVERY SESSION START (Working on ONE feature):
+- Run pwd to confirm working directory
+- Read claude-progress.txt to understand what was last completed
+- Read git log (last 5-10 commits) for recent changes
+- Look at feature_list.json to see current feature status
+- User will tell you which feature to work on OR work on next incomplete feature
+- If init.sh exists, run it to start development environment
+- If no init.sh (bundler detected), start dev server using package manager (npm run dev, yarn dev, etc.)
+- Run basic smoke test to verify app works
+
+IMPLEMENTATION PLANNING PHASE (BEFORE ANY CODING):
+After understanding the current feature, MUST do this:
+- Explain your implementation approach in detail:
+  * Which files will be created/modified
+  * What code structure you'll use
+  * How you'll keep files under 120 lines
+  * Where mock data will be stored (separate file)
+  * What libraries or dependencies needed
+  * How you'll implement the logic
+  * How you'll test the feature
+  * Any potential challenges or trade-offs
+- Present your plan clearly and wait for user feedback
+- DISCUSS with user - they may have preferences on:
+  * Architecture decisions
+  * Code organization
+  * Technology choices
+  * Implementation approach
+- Adjust plan based on user input
+- ONLY start coding after user explicitly approves (says "go ahead", "looks good", "start", etc.)
+- If user suggests changes, revise plan and confirm again
+
+IMPLEMENTATION PLAN FORMAT:
+## Implementation Plan for: [Feature Name]
+
+**Files to Create/Modify:**
+- file1.js (~70 lines) - [what changes]
+- file2.html (~40 lines) - [what changes]
+- utils/helpers.js (~30 lines) - [extracted utilities]
+- mock/featureData.js (~80 lines) - [mock data for this feature]
+
+**File Organization Strategy:**
+[Explain how you'll keep files under 120 lines]
+
+**Mock Data Location:**
+[Specify which mock data file(s) and what data they contain]
+
+**Approach:**
+[Detailed explanation of implementation strategy]
+
+**Dependencies/Libraries:**
+[Any new packages or tools needed]
+
+**Testing Strategy:**
+[How you'll verify it works]
+
+**Trade-offs/Considerations:**
+[Any architectural decisions or potential issues]
+
+**Estimated Time:** [X minutes]
+
+Does this approach work for you? Any preferences or changes?
+
+FILE SIZE AND ORGANIZATION RULES:
+- EVERY file must be 120 lines or below (HARD LIMIT)
+- If a file approaches 120 lines, MUST split into multiple files
+- Use modular architecture to keep files small:
+  * Separate concerns into different files
+  * Extract utilities into separate files
+  * Split large components into smaller sub-components
+  * Create separate files for constants, types, interfaces
+- Mock data MUST ALWAYS be in separate files:
+  * Create mock/ or data/ directory for all mock data
+  * File naming: mockUsers.js, mockProducts.json, testData.js, etc.
+  * NEVER inline large mock data arrays/objects in implementation files
+  * Even small mock data (3+ items) should be in separate file
+- When a file reaches ~100 lines, proactively refactor before adding more
+- Prefer many small focused files over few large files
+
+DURING SESSION - SINGLE FEATURE FOCUS:
+- Work ONLY on the current feature being discussed
+- Do NOT look ahead to other features
+- Do NOT implement anything beyond the current feature scope
+- Stay laser-focused on completing this ONE feature
+- If you notice the feature is too large, STOP and suggest breaking it into smaller features
+- If you need to deviate from approved plan, STOP and discuss changes with user first
+- If any file exceeds 120 lines during implementation, STOP and refactor before continuing
+
+TESTING FOR CURRENT FEATURE:
+- Test ONLY the current feature end-to-end
+- Use browser automation for web features
+- Verify the specific acceptance criteria in feature_list.json
+- Do NOT test unrelated features unless they break
+
+SESSION END (After completing ONE feature):
+FOLLOW THIS EXACT ORDER:
+1. Verify ALL files are under 120 lines (except mock data files)
+2. Ensure code is in clean state
+3. Update claude-progress.txt with complete session information
+4. Update feature_list.json: change ONLY current feature's "passes" to true
+5. WAIT for user to say "commit" or give commit instruction
+6. When user says "commit": Write git commit with descriptive message
+7. STOP - user will start new conversation for next feature
+
+COMMIT RULES:
+- NEVER commit automatically
+- ONLY commit when user explicitly says "commit", "git commit", "save this", or similar
+- Wait for user instruction before committing
+- Commit message should be descriptive of the feature completed
+- Commit includes: code changes + claude-progress.txt + feature_list.json
+
+SINGLE FEATURE CONVERSATION FLOW:
+1. Read context (progress file, git log, feature list)
+2. Confirm which feature to work on
+3. Start dev environment (init.sh or bundler command)
+4. Verify app still works (smoke test)
+5. Present implementation plan and WAIT for approval
+6. Discuss and adjust plan based on user feedback
+7. Get explicit approval before coding
+8. Implement ONLY that feature (following approved plan)
+9. Monitor file sizes - refactor immediately if approaching 120 lines
+10. Ensure mock data is in separate files
+11. Test ONLY that feature
+12. Verify all files under 120 lines
+13. Update claude-progress.txt (document everything)
+14. Update feature_list.json (mark feature as passes: true)
+15. WAIT for user to say "commit"
+16. When user says commit: Write git commit with descriptive message
+17. STOP - end conversation
+
+BETWEEN CONVERSATIONS:
+- User starts fresh conversation for each new feature
+- Each conversation = ONE feature from feature_list.json
+- Context resets between features (this is intentional)
+- Progress tracking via git commits + claude-progress.txt + feature_list.json
+
+FORBIDDEN BEHAVIORS:
+- Never start coding during requirements gathering
+- Never create more than necessary files during initialization (only feature_list.json if bundler detected, or init.sh + feature_list.json if no bundler)
+- Never work on multiple features in one conversation
+- Never look ahead or prepare for future features
+- Never create large features that span multiple conversations
+- NEVER start coding before presenting and discussing implementation plan
+- NEVER start coding without explicit user approval
+- NEVER create files over 120 lines (except mock data files)
+- NEVER put mock data inline in implementation files
+- NEVER continue coding if a file exceeds 120 lines without refactoring first
+- NEVER commit without user explicitly instructing to commit

package/dist/types/components/feature-card/demo/moha.d.ts

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

package/dist/types/components/feature-card/index.d.ts

@@ -1,5 +1,7 @@
-import React from 'react';
+import React, { type JSX } from 'react';
 import './index.css';
+type Align = 'left' | 'center' | 'right';
+type Size = 'sm' | 'md' | 'lg';
 export interface FeatureCardClassNames {
     root?: string;
     icon?: string;
@@ -14,6 +16,10 @@ export interface FeatureCardProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     cardTitle?: React.ReactNode;
     description?: React.ReactNode;
     titleAs?: keyof JSX.IntrinsicElements;
+    /** Alignment: left (default), center, right */
+    align?: Align;
+    /** Size: sm, md (default), lg */
+    size?: Size;
     /** Custom classNames for each element */
     classNames?: FeatureCardClassNames;
 }

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

@@ -0,0 +1,6 @@
+import './circle-progress.css';
+export declare function CircleProgress({ percent, isFailed, isCompleted, }: {
+    percent: number;
+    isFailed: boolean;
+    isCompleted: boolean;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,17 @@
+import { type DragEvent } from 'react';
+import type { DropZoneError } from '../uploader-drop-zone';
+interface UseDropZoneProps {
+    disabled: boolean;
+    directory: boolean;
+    accept: string;
+    onFilesReady: (files: File[]) => void;
+    onError?: (error: DropZoneError) => void;
+}
+export declare function useDropZone({ disabled, directory, accept, onFilesReady, onError }: UseDropZoneProps): {
+    isDragging: boolean;
+    handleDragEnter: (e: DragEvent<HTMLElement>) => void;
+    handleDragOver: (e: DragEvent<HTMLElement>) => void;
+    handleDragLeave: (e: DragEvent<HTMLElement>) => void;
+    handleDrop: (e: DragEvent<HTMLElement>) => Promise<void>;
+};
+export {};

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

@@ -0,0 +1,12 @@
+import type { DropZoneError } from '../uploader-drop-zone';
+interface UseFileValidationProps {
+    maxSize?: number;
+    maxFiles?: number;
+    fileValidation?: (file: File) => boolean | Promise<boolean>;
+    onDrop: (files: File[]) => void;
+    onError?: (error: DropZoneError) => void;
+}
+export declare function useFileValidation({ maxSize, maxFiles, fileValidation, onDrop, onError, }: UseFileValidationProps): {
+    processFiles: (files: File[]) => Promise<void>;
+};
+export {};

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

@@ -0,0 +1,5 @@
+export default function UploadIcon(props: React.SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;
+export declare function FileIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function CloseIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function PauseIcon(): import("react/jsx-runtime").JSX.Element;
+export declare function ResumeIcon(): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,49 @@
+import { type ReactNode } from 'react';
+import './theme.css';
+import './uploader-drop-zone.css';
+export interface UploadDropZoneClassNames {
+    /** Container wrapper class */
+    container?: string;
+    /** Drag area class */
+    dragArea?: string;
+    /** Additional class when dragging is active */
+    dragging?: string;
+    /** Additional class when disabled */
+    disabled?: string;
+    /** Icon wrapper class */
+    icon?: string;
+    /** Description text class */
+    description?: string;
+    /** File input class */
+    input?: string;
+}
+export interface UploadDropZoneProps {
+    /** File type filter (e.g., "image/*,video/*" or ".pdf,.doc") */
+    accept?: string;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Maximum number of files allowed */
+    maxFiles?: number;
+    /** Support folder/directory drop (recursive) */
+    directory?: boolean;
+    /** Disable the drop zone */
+    disabled?: boolean;
+    /** Description text for drag area */
+    dragAreaDescription?: ReactNode;
+    /** Custom icon - can be a React component or image/svg path */
+    icon?: ReactNode | string;
+    /** Custom class names for different elements */
+    classNames?: UploadDropZoneClassNames;
+    /** Callback when files are dropped or selected */
+    onDrop: (files: File[]) => void;
+    /** custom file validation callback */
+    fileValidation?: (file: File) => boolean | Promise<boolean>;
+    /** Called when validation fails */
+    onError?: (error: DropZoneError) => void;
+}
+export interface DropZoneError {
+    type: 'FILE_TOO_LARGE' | 'TOO_MANY_FILES' | 'INVALID_TYPE' | 'DROP_FAILED';
+    message: string;
+    rejectedFiles?: File[];
+}
+export declare function UploadDropZone({ accept, maxSize, maxFiles, directory, disabled, dragAreaDescription, icon, classNames, onDrop, fileValidation, onError, }: UploadDropZoneProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,40 @@
+import type { UploadFile } from '../types';
+import './theme.css';
+import './uploader-file-item.css';
+export interface UploaderFileItemClassNames {
+    /** Root container class */
+    container?: string;
+    /** File info section wrapper */
+    info?: string;
+    /** File icon wrapper */
+    icon?: string;
+    /** File name text */
+    name?: string;
+    /** Status section wrapper */
+    status?: string;
+    /** Status text */
+    statusText?: string;
+    /** Progress component wrapper */
+    progress?: string;
+    /** Pause button */
+    pauseBtn?: string;
+    /** Resume button */
+    resumeBtn?: string;
+    /** Close/Cancel button */
+    closeBtn?: string;
+}
+interface FileItemProps {
+    file: UploadFile;
+    /** Custom class names for different elements */
+    classNames?: UploaderFileItemClassNames;
+    /** Cancel function passed from parent that has upload handlers */
+    onCancel?: (id: string) => void;
+    /** Remove function passed from parent that has upload handlers */
+    onRemove?: (id: string) => void;
+    /** Pause function passed from parent that has upload handlers */
+    onPause?: (id: string) => void;
+    /** Resume function passed from parent that has upload handlers */
+    onResume?: (id: string) => void;
+}
+export declare function UploaderFileItem({ file, classNames, onCancel, onRemove, onPause, onResume }: FileItemProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,29 @@
+import './theme.css';
+import './uploader-file-list.css';
+export interface FileListClassNames {
+    /** File list container */
+    container?: string;
+    /** Empty state wrapper */
+    empty?: string;
+}
+interface FileListProps {
+    /** Custom class names for different elements */
+    classNames?: FileListClassNames;
+    /** Empty state text or component */
+    emptyText?: string;
+    /** Children components (e.g., file items) */
+    children: React.ReactNode;
+}
+/**
+ * Simple file list component that displays all uploaded files.
+ * Uses the useUploadFiles hook to access file state.
+ *
+ * @example
+ * ```tsx
+ * <FileList
+ *   emptyText="No files uploaded yet"
+ * />
+ * ```
+ */
+export declare function UploaderFileListLayout({ classNames, emptyText, children }: FileListProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,64 @@
+import './theme.css';
+import './uploader.css';
+import { type ReactNode } from 'react';
+import { type DropZoneError, type UploadDropZoneClassNames } from './uploader-drop-zone';
+import type { UploadHandlers } from '../types';
+import { type FileListClassNames } from './uploader-file-list';
+import { type UploaderFileItemClassNames } from './uploader-file-item';
+interface UploaderProps {
+    /** Provide handlers per file (decided at selection time) */
+    handlers: UploadHandlers;
+    /** Arbitrary runtime context to rebuild handlers after reload */
+    runtime?: unknown;
+    /** Optional description text for drag area */
+    dragAreaDescription?: ReactNode;
+    /** Accept file types */
+    accept?: string;
+    /** Enable directory/folder upload */
+    directory?: boolean;
+    /** Maximum number of files */
+    maxFiles?: number;
+    /** Maximum file size in bytes (per-usage option) */
+    maxSize?: number;
+    /** Additional class name for the uploader container */
+    classNames?: {
+        container?: string;
+        dragZone?: UploadDropZoneClassNames;
+        fileList?: UploaderFileItemClassNames;
+        fileItem?: FileListClassNames;
+    };
+    /** Error callback for upload errors */
+    onDropZoneError?: (error: DropZoneError) => void;
+    /** custom file validation callback */
+    fileValidation?: (file: File) => boolean | Promise<boolean>;
+}
+/**
+ * Styled File Uploader - Matches FileUploader capabilities with custom styling
+ *
+ * Note: This component must be used within an UploadProvider.
+ * The UploadProvider should be placed at the app level for shared state and global config.
+ *
+ * @example
+ * ```tsx
+ * // App level - with global config
+ * <UploadProvider config={{ concurrentFiles: 3 }}>
+ *   <App />
+ * </UploadProvider>
+ *
+ * // Component level - provide handlers with local context
+ * <StyledUploader
+ *   maxFileSize={10 * 1024 * 1024 * 1024} // 10GB for this dataset
+ *   getHandlers={(file) => ({
+ *     onGetUploadUrls: (fileName, partCount) =>
+ *       api.getUrls(datasetId, fileName, partCount, resolveFolderFromUI()),
+ *     onPartComplete: (fileName, uploadId, partNum) =>
+ *       api.markPartComplete(datasetId, uploadId, partNum),
+ *     onFileComplete: (fileName, uploadId) =>
+ *       api.complete(datasetId, uploadId),
+ *   })}
+ * />
+ * ```
+ */
+export declare function Uploader({ handlers, runtime, dragAreaDescription, accept, directory, maxFiles, maxSize, // 10GB default
+classNames, onDropZoneError, fileValidation, }: UploaderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/file-uploader/components/utils/directory-reader.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Recursively reads files from a FileSystemEntry (file or directory)
+ */
+export declare function readEntry(entry: FileSystemEntry, acceptFilter: string): Promise<File[]>;

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

@@ -0,0 +1,27 @@
+export declare const KB = 1024;
+export declare const MB: number;
+export declare const GB: number;
+export declare const DEFAULT_CHUNK_SIZE: number;
+export declare const DEFAULT_MAX_CHUNK_SIZE: number;
+export declare const DEFAULT_MIN_CHUNK_SIZE: number;
+export declare const DEFAULT_CONCURRENT_CHUNKS = 2;
+export declare const DEFAULT_CONCURRENT_FILES = 1;
+export declare const DEFAULT_MAX_FILE_SIZE: number;
+export declare const UploadStatus: {
+    readonly PENDING: "pending";
+    readonly PREPARING: "preparing";
+    readonly UPLOADING: "uploading";
+    readonly PAUSED: "paused";
+    readonly MERGING: "merging";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+export type UploadStatusType = (typeof UploadStatus)[keyof typeof UploadStatus];
+export declare const ChunkStatus: {
+    readonly PENDING: "pending";
+    readonly UPLOADING: "uploading";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+};
+export type ChunkStatusType = (typeof ChunkStatus)[keyof typeof ChunkStatus];

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

@@ -0,0 +1,64 @@
+import type { UploadFile } from '../types';
+/**
+ * Global file state store for background uploads.
+ *
+ * This store maintains a copy of file state that can be accessed
+ * even when the originating React component is unmounted.
+ *
+ * The store is updated whenever React state changes, ensuring
+ * QueueManager callbacks always have access to fresh file data.
+ *
+ * Flow:
+ * 1. UploadProvider updates state via reducer
+ * 2. Provider syncs state to this store via useEffect
+ * 3. QueueManager callbacks access files via getFile()
+ * 4. Even if user navigates away, store still has current data
+ *
+ * @example
+ * ```tsx
+ * // In UploadProvider - sync state to store
+ * useEffect(() => {
+ *   fileStateStore.syncFiles(state.files);
+ * }, [state.files]);
+ *
+ * // In queue callbacks - get fresh file data
+ * const file = fileStateStore.getFile(fileId);
+ * ```
+ */
+declare class FileStateStore {
+    /** Current files indexed by ID for O(1) lookup */
+    private filesMap;
+    /**
+     * Sync files from React state to the global store.
+     * Called by UploadProvider whenever state.files changes.
+     */
+    syncFiles(files: UploadFile[]): void;
+    /**
+     * Get a file by ID.
+     * Returns undefined if file not found.
+     */
+    getFile(fileId: string): UploadFile | undefined;
+    /**
+     * Check if a file exists in the store.
+     */
+    hasFile(fileId: string): boolean;
+    /**
+     * Get all files (for debugging).
+     */
+    getAllFiles(): UploadFile[];
+    /**
+     * Clear all files from the store.
+     * Called when UploadProvider unmounts.
+     */
+    clear(): void;
+    /**
+     * Get the number of files in the store.
+     */
+    get size(): number;
+}
+/**
+ * Singleton instance of the file state store.
+ * Shared across all upload components and QueueManager.
+ */
+export declare const fileStateStore: FileStateStore;
+export {};