@unciatech/file-manager 0.0.1

package/README.md

@@ -0,0 +1,251 @@
+# 🗂️ File Manager
+
+A robust, production-ready React / Next.js file management system designed to mirror the capabilities of professional asset managers (like Google Drive, macOS Finder, or Strapi Media Library).
+
+It supports deep folder nesting, drag-and-drop file uploads, metadata management for various file types (Images, Videos, Audio, Documents), unified grid layouts, and fully optimized loading states.
+
+## 🌟 Key Features
+- **Dual Operating Modes**: Use it as a standalone full-page media library or instantiate it as a picker modal for form inputs.
+- **Unified Grid View**: Beautiful, responsive layout that intelligently renders thumbnails, icons, and metadata based on the file's MIME type.
+- **Nested Folder Structure**: Infinite folder depth with smooth virtualized/paginated fetching.
+- **Provider Agnostic**: Built on an `IFileManagerProvider` interface. You can easily hot-swap the mock data provider for a real backend (Node.js, Supabase, Strapi, etc.).
+- **Bulk Actions**: Select multiple files/folders at once to bulk move or bulk delete.
+- **Optimistic UI Updates**: Instant visual feedback when renaming folders or updating file descriptions, with silent background synchronization.
+- **Graceful Error Handling**: Resilient `<FileManagerErrorBoundary>` that captures catastrophic failures and allows users to hard-reload safely without app crashes.
+
+## 🛠️ Tech Stack
+- **Framework**: Next.js / React
+- **Styling**: Tailwind CSS
+- **Icons**: Lucide React
+- **Notifications**: Sonner
+
+## 🚀 How to Install and Use in Your Project
+
+If you want to integrate this File Manager into your own Next.js or React application, follow this step-by-step guide.
+
+### Step 1: Copy the Core Files
+Copy the `components`, `types`, `hooks`, `context`, and `providers` folders related to the file manager into your project's source directory (e.g., `src/`).
+
+### Step 2: Create your Custom API Provider
+
+The file manager is completely agnostic to your backend database. You simply need to create a class that implements the `IFileManagerProvider` interface. 
+
+Here is an example of what your custom provider might look like, making real API calls to your backend using `fetch`:
+
+```typescript
+// lib/my-api-provider.ts
+import { 
+  IFileManagerProvider, 
+  FolderId, 
+  FileUploadInput 
+} from "@/types/file-manager";
+
+export class MyCustomApiProvider implements IFileManagerProvider {
+  private baseUrl = "https://api.mybackend.com/v1";
+
+  // Example 1: Fetching folders from your Real API
+  async getFolders(folderId: FolderId, page = 1, limit = 24) {
+    const parentQuery = folderId ? `&parentId=${folderId}` : "&isRoot=true";
+    
+    // Simulate real API Call
+    const res = await fetch(`${this.baseUrl}/folders?page=${page}&limit=${limit}${parentQuery}`);
+    
+    if (!res.ok) throw new Error("Failed to fetch folders");
+    
+    const data = await res.json();
+    
+    return {
+      folders: data.folders, // Array of Folder objects matching our interface
+      pagination: data.pagination // { currentPage, totalPages, totalFiles, filesPerPage }
+    };
+  }
+
+  // Example 2: Uploading files via multipart/form-data
+  async uploadFiles(filesInput: FileUploadInput[], folderId?: FolderId) {
+    const formData = new FormData();
+    if (folderId) formData.append("folderId", String(folderId));
+    
+    filesInput.forEach(({ file }) => {
+      formData.append("files", file);
+    });
+
+    const res = await fetch(`${this.baseUrl}/upload`, {
+      method: 'POST',
+      body: formData
+    });
+
+    return res.json(); // Returns array of FileMetaData
+  }
+
+  // ... Implement the remaining interface methods (getFiles, renameFolder, bulkMove, etc.)
+}
+```
+
+> **💡 Pro Tip - The Mock Provider:**
+> If you are just prototyping and don't have a backend ready yet, you can skip Step 2 entirely! We included a fully functional `MockFileManagerProvider` that fakes network latency and stores data in memory. Just import it and use it right away to see the UI in action.
+
+### Step 3: Wrap Your Page with the Provider
+
+Finally, import your provider and wrap the `<FileManager />` component in the Context Provider. Define which file types you want to allow.
+
+```tsx
+// app/media/page.tsx
+import { FileManagerProvider } from "@/context/file-manager-context";
+import { FileManager } from "@/components/file-manager";
+
+// Import your real provider OR the mock one
+import { MyCustomApiProvider } from "@/lib/my-api-provider"; 
+// import { MockFileManagerProvider } from "@/providers/mock-provider";
+
+export default function MediaLibraryPage() {
+  // Instantiate the provider
+  const apiProvider = new MyCustomApiProvider(); 
+
+  return (
+    <div className="h-screen w-full">
+      <FileManagerProvider
+        mode="page"
+        selectionMode="multiple"
+        allowedFileTypes={["images", "videos", "audios", "files"]}
+        provider={apiProvider}
+      >
+        <FileManager />
+      </FileManagerProvider>
+    </div>
+  );
+}
+```
+
+---
+
+## 💾 Database Schema Design
+
+Because this application relies heavily on tree structures (Folders inside Folders) and varied JSON metadata (Video durations vs Document page counts), using a relational database with JSONB support (like PostgreSQL) is highly recommended. 
+
+Below are production-ready schema examples using **Prisma** and **Drizzle ORM**.
+
+### Option A: Prisma Schema (PostgreSQL/MySQL)
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql" // or "mysql"
+  url      = env("DATABASE_URL")
+}
+
+model Folder {
+  id          Int       @id @default(autoincrement())
+  name        String
+  
+  // Self-referencing relationship for infinite folder depth
+  parentId    Int?      
+  parent      Folder?   @relation("FolderHierarchy", fields: [parentId], references: [id])
+  children    Folder[]  @relation("FolderHierarchy")
+  
+  // Cached counts for fast UI rendering
+  folderCount Int       @default(0)
+  fileCount   Int       @default(0)
+  
+  // Path optimization
+  pathId      Int       @default(0)
+  path        String?   // e.g. "/1/5/12"
+  
+  createdAt   DateTime  @default(now())
+  updatedAt   DateTime  @updatedAt
+  
+  files       File[]
+
+  @@index([parentId])
+}
+
+model File {
+  id              Int       @id @default(autoincrement())
+  name            String
+  
+  // Foreign Key to Folder
+  folderId        Int?
+  folder          Folder?   @relation(fields: [folderId], references: [id], onDelete: Cascade)
+  folderPath      String?
+  
+  // Core Asset Data
+  size            Int
+  url             String
+  previewUrl      String?   // Lightweight thumbnail URL
+  mime            String    // e.g. "image/jpeg", "video/mp4"
+  ext             String?
+  hash            String?
+  
+  // Common Media Details
+  alternativeText String?
+  caption         String?
+  width           Int?
+  height          Int?
+  
+  // JSONB storage for flexible metadata 
+  // (e.g., formats: { thumbnail: {...}, small: {...} })
+  formats         Json?     
+  // (e.g., metaData: { duration: 120, bitrate: 320, pageCount: 15 })
+  metaData        Json?     
+  
+  createdAt       DateTime  @default(now())
+  updatedAt       DateTime  @updatedAt
+
+  @@index([folderId])
+}
+```
+
+
+### Option B: Drizzle ORM Schema (PostgreSQL)
+
+If you prefer a lighter, TypeScript-first approach using Drizzle:
+
+```typescript
+import { pgTable, serial, varchar, integer, timestamp, jsonb, text } from "drizzle-orm/pg-core";
+
+export const folders = pgTable("folders", {
+  id: serial("id").primaryKey(),
+  name: varchar("name", { length: 255 }).notNull(),
+  
+  // Nullable parentId allows root-level folders
+  parentId: integer("parent_id"), // Needs recursive FK setup in relations
+  
+  folderCount: integer("folder_count").default(0),
+  fileCount: integer("file_count").default(0),
+  
+  pathId: integer("path_id").default(0),
+  path: varchar("path", { length: 255 }),
+  
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});
+
+export const files = pgTable("files", {
+  id: serial("id").primaryKey(),
+  name: varchar("name", { length: 255 }).notNull(),
+  
+  folderId: integer("folder_id").references(() => folders.id, { onDelete: "cascade" }),
+  folderPath: varchar("folder_path", { length: 255 }),
+  
+  size: integer("size").notNull(),
+  url: text("url").notNull(),
+  previewUrl: text("preview_url"),
+  mime: varchar("mime", { length: 100 }).notNull(),
+  ext: varchar("ext", { length: 20 }),
+  hash: varchar("hash", { length: 255 }),
+  
+  alternativeText: text("alternative_text"),
+  caption: text("caption"),
+  width: integer("width"),
+  height: integer("height"),
+  
+  // JSONB is perfect for storing our dynamic metadata & responsive formats
+  formats: jsonb("formats"),
+  metaData: jsonb("meta_data"), 
+  
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});
+```

package/dist/index.d.mts

@@ -0,0 +1,292 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type FileUploadInput = {
+    file: File;
+    metadata: Partial<FileMetaData>;
+    videoSource?: VideoSource;
+};
+interface IFileManagerProvider {
+    getFolder(folderId: FolderId): Promise<Folder | null>;
+    getFolders(folderId: FolderId, page?: number, limit?: number, query?: string): Promise<{
+        folders: Folder[];
+        pagination: PaginationInfo;
+    }>;
+    getTags(): Promise<string[]>;
+    getFiles(folderId: FolderId, fileTypes?: FileType[] | null, page?: number, limit?: number, query?: string): Promise<{
+        files: FileMetaData[];
+        pagination: PaginationInfo;
+    }>;
+    /**
+     * Get files and folders separately (folders always come first)
+     * Folders are returned for the current page, followed by files
+     */
+    getItems(folderId: FolderId, fileTypes?: FileType[], page?: number, limit?: number, query?: string): Promise<{
+        folders: Folder[];
+        files: FileMetaData[];
+        pagination: PaginationInfo;
+    }>;
+    createFolder(name: string, parentId?: FolderId): Promise<Folder>;
+    uploadFiles(files: FileUploadInput[], folderId?: FolderId): Promise<FileMetaData[]>;
+    renameFolder(folderId: FolderId, newName: string): Promise<Folder>;
+    moveFiles(fileIds: EntityId[], newFolderId: FolderId): Promise<FileMetaData[]>;
+    moveFolders(folderIds: FolderId[], newParentId: FolderId): Promise<Folder[]>;
+    updateFileMetaData(fileId: EntityId, metaData: Partial<FileMetaData>): Promise<FileMetaData>;
+    deleteFiles(fileIds: EntityId[]): Promise<void>;
+    deleteFolders(folderIds: FolderId[]): Promise<void>;
+    findFiles(searchQuery: string): Promise<FileMetaData[]>;
+    findFolders(searchQuery: string): Promise<Folder[]>;
+}
+
+declare const MODE: {
+    readonly PAGE: "page";
+    readonly MODAL: "modal";
+};
+type Mode = (typeof MODE)[keyof typeof MODE];
+declare const FILE_TYPE: {
+    readonly IMAGE: "images";
+    readonly VIDEO: "videos";
+    readonly AUDIO: "audios";
+    readonly FILE: "files";
+};
+type FileType = (typeof FILE_TYPE)[keyof typeof FILE_TYPE];
+declare const SELECTION_MODE: {
+    readonly SINGLE: "single";
+    readonly MULTIPLE: "multiple";
+};
+type SelectionMode = (typeof SELECTION_MODE)[keyof typeof SELECTION_MODE];
+declare const VIEW_MODE: {
+    readonly GRID: "grid";
+    readonly LIST: "list";
+};
+type ViewMode = (typeof VIEW_MODE)[keyof typeof VIEW_MODE];
+declare const VIDEO_SOURCE: {
+    readonly LOCAL: "local";
+    readonly REMOTE: "remote";
+    readonly YOUTUBE: "youtube";
+    readonly VIMEO: "vimeo";
+};
+type VideoSource = (typeof VIDEO_SOURCE)[keyof typeof VIDEO_SOURCE];
+interface MetaDataType {
+    /** Video or Audio duration in seconds. */
+    duration?: number;
+    /** Provider source for video content (e.g., 'local', 'youtube'). */
+    videoSource?: VideoSource;
+    /** Audio bitrate in kbps. */
+    bitrate?: number;
+    /** Total number of pages for document file types. */
+    pageCount?: number;
+    /** Original creator or author of the document. */
+    author?: string;
+    /** General description text used across multiple asset types. */
+    description?: string;
+}
+type EntityId = string | number;
+type FolderId = string | number | null;
+interface Folder {
+    id: FolderId;
+    name: string;
+    pathId: number;
+    path: string;
+    parent?: Folder | null;
+    folderCount?: number;
+    parentId: FolderId;
+    folderPath?: string;
+    color?: string;
+    fileCount?: number;
+    createdAt: Date;
+    updatedAt: Date;
+    tags?: string[];
+}
+interface FormatDetails {
+    ext: string;
+    url: string;
+    hash: string;
+    mime: string;
+    name: string;
+    path: string | null;
+    size: number;
+    width: number;
+    height: number;
+}
+/**
+ * Core interface representing a File entity in the file manager.
+ * Supports various formats (images, videos, audio, documents) via common fields
+ * and nested metadata structures.
+ */
+interface FileMetaData {
+    /** Unique identifier for the file. */
+    id: EntityId;
+    /** Human-readable name of the file (including extension). */
+    name: string;
+    /** ID of the folder containing this file. Null represents the root directory. */
+    folderId: FolderId;
+    /** Path representation of the file's location (e.g., "/1/156"). */
+    folderPath?: string;
+    /** Size of the file in bytes. */
+    size: number;
+    /** Direct URL path to access or download the full asset. */
+    url: string;
+    /** URL to an optimized, lightweight thumbnail or preview of the asset. */
+    previewUrl?: string;
+    /** Content-Type HTTP header representation (e.g., "image/jpeg"). */
+    mime: string;
+    /** File extension including the dot (e.g., ".jpg"). */
+    ext?: string;
+    /** Content hash for deduplication and cache busting. */
+    hash?: string;
+    /** Accessible alt text for images to display when images are disabled. */
+    alternativeText?: string;
+    /** Caption text commonly used in images and videos. */
+    caption?: string;
+    /** Intrinsic width in pixels for image/video assets. */
+    width?: number;
+    /** Intrinsic height in pixels for image/video assets. */
+    height?: number;
+    /** Collection of generated optimized formats for images. */
+    formats?: Record<string, FormatDetails>;
+    /** Dynamic metadata payload containing properties specific to the asset type. */
+    metaData: MetaDataType;
+    /** Timestamp of file creation. */
+    createdAt: Date;
+    /** Timestamp of last file modification. */
+    updatedAt: Date;
+    /** Categorization tags for sorting and discovery. */
+    tags?: string[];
+}
+interface PaginationInfo {
+    currentPage: number;
+    totalPages: number;
+    totalFiles: number;
+    filesPerPage: number;
+}
+interface FileManagerPageProps {
+    allowedFileTypes: FileType[];
+    viewMode: ViewMode;
+    initialFolderId?: FolderId;
+    provider: IFileManagerProvider;
+    basePath?: string;
+}
+interface FileManagerModalProps {
+    open: boolean;
+    onClose: () => void;
+    onFilesSelected: (files: FileMetaData[]) => void;
+    fileSelectionMode?: SelectionMode;
+    allowedFileTypes: FileType[];
+    acceptedFileTypes?: FileType[];
+    viewMode?: ViewMode;
+    initialFolderId?: FolderId;
+    provider: IFileManagerProvider;
+    basePath?: string;
+}
+interface FileManagerRootProps {
+    mode: Mode;
+    selectionMode: SelectionMode;
+    allowedFileTypes: FileType[];
+    viewMode: ViewMode;
+    initialFolderId?: FolderId;
+    acceptedFileTypesForModal?: FileType[];
+    provider: IFileManagerProvider;
+    basePath?: string;
+    onFilesSelected?: (files: FileMetaData[]) => void;
+    onClose?: () => void;
+    maxUploadFiles?: number;
+    maxUploadSize?: number;
+}
+
+declare function FileManager(props: FileManagerPageProps): react_jsx_runtime.JSX.Element;
+
+declare function FileManagerModal({ open, onClose, ...props }: FileManagerModalProps): react_jsx_runtime.JSX.Element;
+
+interface FileManagerContextType {
+    files: FileMetaData[];
+    folders: Folder[];
+    selectedFiles: FileMetaData[];
+    selectedFolders: Folder[];
+    currentFolder: Folder | null;
+    isLoading: boolean;
+    pagination: PaginationInfo;
+    isUploadModalOpen: boolean;
+    isCreateFolderModalOpen: boolean;
+    isSearchModalOpen: boolean;
+    isMoveFileModalOpen: boolean;
+    isRenameFolderModalOpen: boolean;
+    fileDetailsModalFile: FileMetaData | null;
+    folderToRename: Folder | null;
+    mode: Mode;
+    selectionMode: SelectionMode;
+    allowedFileTypes: FileType[];
+    acceptedFileTypesForModal?: FileType[];
+    maxUploadFiles: number;
+    maxUploadSize: number;
+    provider: IFileManagerProvider;
+    basePath?: string;
+    setSelectedFiles: (files: FileMetaData[]) => void;
+    setSelectedFolders: (folders: Folder[]) => void;
+    setIsUploadModalOpen: (isOpen: boolean) => void;
+    setIsCreateFolderModalOpen: (isOpen: boolean) => void;
+    setIsSearchModalOpen: (isOpen: boolean) => void;
+    setIsMoveFileModalOpen: (isOpen: boolean) => void;
+    setIsRenameFolderModalOpen: (isOpen: boolean) => void;
+    setFileDetailsModalFile: (file: FileMetaData | null) => void;
+    setFolderToRename: (folder: Folder | null) => void;
+    handleFileClick: (file: FileMetaData, event?: React.MouseEvent, isCheckboxClick?: boolean) => void;
+    handleFolderClick: (folder: Folder | null, event?: React.MouseEvent, isCheckboxClick?: boolean) => void;
+    handleClearSelection: () => void;
+    handleSelectAllGlobal: (checked: boolean) => void;
+    handlePageChange: (page: number) => void;
+    searchQuery: string;
+    updateSearchQuery: (query: string) => void;
+    uploadFiles: (fileUploadInput: FileUploadInput[]) => Promise<void>;
+    createFolder: (name: string) => Promise<void>;
+    bulkMove: (targetFolderId: FolderId) => Promise<void>;
+    renameFolder: (folderId: EntityId, newName: string) => Promise<void>;
+    updateFileMetadata: (fileId: EntityId, metadata: Partial<FileMetaData>) => Promise<void>;
+    bulkDelete: () => Promise<void>;
+    refreshData: () => Promise<void>;
+    isInSelectionMode: () => boolean;
+    getCurrentFolder: () => Folder | null;
+    getSelectionState: () => boolean | "indeterminate";
+    onClose?: () => void;
+    onFilesSelected?: (files: FileMetaData[]) => void;
+}
+declare function FileManagerProvider({ children, mode, selectionMode, allowedFileTypes, onFilesSelected, onClose, acceptedFileTypesForModal, initialFolderId, provider, basePath, maxUploadFiles, maxUploadSize, }: FileManagerRootProps & {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useFileManager(): FileManagerContextType;
+
+declare class MockProvider implements IFileManagerProvider {
+    getFolder(folderId: FolderId): Promise<Folder | null>;
+    getFolders(folderId: FolderId, page?: number, limit?: number, query?: string): Promise<{
+        folders: Folder[];
+        pagination: PaginationInfo;
+    }>;
+    getTags(): Promise<string[]>;
+    getFiles(folderId: FolderId, fileTypes?: FileType[], page?: number, limit?: number, query?: string): Promise<{
+        files: FileMetaData[];
+        pagination: PaginationInfo;
+    }>;
+    /**
+     * Get files and folders separately (folders always come first)
+     * Folders are not paginated (all folders in current directory are returned)
+     * Files are paginated after folders
+     */
+    getItems(folderId: FolderId, fileTypes?: FileType[], page?: number, limit?: number, query?: string): Promise<{
+        folders: Folder[];
+        files: FileMetaData[];
+        pagination: PaginationInfo;
+    }>;
+    createFolder(name: string, parentId?: FolderId): Promise<Folder>;
+    private getMetaDataType;
+    private getFileType;
+    uploadFiles(files: FileUploadInput[], folderId?: FolderId): Promise<FileMetaData[]>;
+    renameFolder(folderId: EntityId, newName: string): Promise<Folder>;
+    updateFileMetaData(fileId: EntityId, updates: Partial<FileMetaData>): Promise<FileMetaData>;
+    deleteFiles(fileIds: EntityId[]): Promise<void>;
+    deleteFolders(folderIds: EntityId[]): Promise<void>;
+    findFiles(searchQuery: string): Promise<FileMetaData[]>;
+    findFolders(searchQuery: string): Promise<Folder[]>;
+    moveFiles(fileIds: EntityId[], newFolderId: FolderId): Promise<FileMetaData[]>;
+    moveFolders(folderIds: FolderId[], newParentId: FolderId): Promise<Folder[]>;
+}
+
+export { FileManager, FileManagerModal, type FileManagerModalProps, type FileManagerPageProps, FileManagerProvider, type FileMetaData, type FileType, type Folder, type IFileManagerProvider, MockProvider, type SelectionMode, type ViewMode, useFileManager };