@unciatech/file-manager 0.0.32 → 0.0.33

package/README.md

@@ -1,6 +1,6 @@
 # 🗂️ 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).
+A robust, production-ready file management component for any **React** application — works with Vite, Next.js, Remix, CRA, and more.
 
 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.
 
@@ -14,7 +14,7 @@ It supports deep folder nesting, drag-and-drop file uploads, metadata management
 - **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
+- **Framework**: React (any — Vite, Next.js, Remix, CRA)
 - **Styling**: Tailwind CSS
 - **Icons**: Custom SVG Icons
 - **Notifications**: Sonner
@@ -22,9 +22,32 @@ It supports deep folder nesting, drag-and-drop file uploads, metadata management
 > [!WARNING]
 > This library is currently in **BETA**. Please report any bugs or feature requests on the GitHub issues page.
 
-## 🚀 How to Install and Use in Your Project
+## Setup & Requirements
 
-If you want to integrate this File Manager into your own Next.js or React application, follow this step-by-step guide.
+Because this library relies heavily on Tailwind CSS for minimal zero-config styling, ensure your app is configured to scan the library's components for Tailwind utility classes.
+
+### Tailwind v4
+If you are using **Tailwind CSS v4** (like in newer Next.js or Vite projects), add this to your main CSS file (`globals.css` or `index.css`). This pulls in the required theme configuration and ensures the library is scanned:
+
+```css
+@import "tailwindcss";
+@import "@unciatech/file-manager/styles";
+@source "../node_modules/@unciatech/file-manager";
+```
+
+### Tailwind v3
+If you are still on **Tailwind v3**, add the library path to your `tailwind.config.ts`:
+
+```ts
+content: [
+  // ... your other paths
+  "./node_modules/@unciatech/file-manager/dist/**/*.{js,ts,jsx,tsx}",
+],
+```
+
+## Basic Usage in Your Project
+
+If you want to integrate this File Manager into your own React application (Next.js, Vite, Remix, CRA, etc.), follow this step-by-step guide.
 
 ### Step 1: Install the Package
 
@@ -46,30 +69,6 @@ The init script includes this automatically, but if you are installing manually,
 import '@unciatech/file-manager/styles';
 ```
 
-**(CRITICAL) Configure Tailwind CSS:**
-Because this library uses Tailwind CSS, you MUST tell your Tailwind compiler to scan the library components for utility classes, otherwise it will render with zero styles!
-
-**For Tailwind v3 (`tailwind.config.ts`):**
-```typescript
-import type { Config } from "tailwindcss";
-
-const config: Config = {
-  content: [
-    // Your existing paths...
-    "./node_modules/@unciatech/file-manager/dist/**/*.js",
-    "./node_modules/@unciatech/file-manager/dist/**/*.mjs",
-  ],
-  // ...
-};
-export default config;
-```
-
-**For Tailwind v4 (`globals.css`):**
-```css
-@import "tailwindcss";
-@source "../node_modules/@unciatech/file-manager/dist";
-```
-
 ### 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.
@@ -129,10 +128,11 @@ export class MyCustomApiProvider implements IFileManagerProvider {
 > If you are just prototyping and don't have a backend ready yet, you can skip Step 2 entirely! We included a fully functional `MockProvider` that fakes network latency and stores data in memory. Just import it and use it right away to see the UI in action.
 
 // app/media/page.tsx
-import { FileManagerProvider } from "@/context/file-manager-context";
-import { FileManager } from "@/components/file-manager";
-import { MockProvider } from "@/providers/mock-provider";
+import { FileManager, MockProvider } from "@unciatech/file-manager";
+import "@unciatech/file-manager/styles";
 
+// **Tailwind v4 Users:** Make sure your `globals.css` or `index.css` includes:
+// @source "../node_modules/@unciatech/file-manager";
 // OR import your real provider
 import { MyCustomApiProvider } from "@/lib/my-api-provider"; 
 
@@ -148,7 +148,7 @@ export default function MediaLibraryPage() {
         allowedFileTypes={["images", "videos", "audios", "files"]}
         provider={apiProvider}
       >
-        <FileManager />
+        <FileManager basePath="/media" />
       </FileManagerProvider>
     </div>
   );
@@ -157,6 +157,99 @@ export default function MediaLibraryPage() {
 
 ---
 
+## 🔀 Framework Router Integration
+
+By default, the file manager uses the browser's native `history.pushState` API for navigation — no full page reloads, no dependencies. This works out of the box in any bare React app (Vite, CRA, etc.).
+
+However, if your app already has its own router (React Router, Next.js, TanStack Router), you should pass the `onNavigate` prop so the file manager delegates all navigation to your router instead of calling `history.pushState` directly. This keeps your router's internal state in sync.
+
+### React Router v6
+
+```tsx
+import { useNavigate } from 'react-router-dom';
+
+function MyPage() {
+  const navigate = useNavigate();
+
+  return (
+    <FileManager
+      provider={provider}
+      allowedFileTypes={['images', 'videos']}
+      onNavigate={(url) => navigate(url)}
+      basePath="/media"
+    />
+  );
+}
+```
+
+### Next.js (App Router)
+
+```tsx
+'use client';
+import { useRouter } from 'next/navigation';
+
+export default function MediaPage() {
+  const router = useRouter();
+
+  return (
+    <FileManager
+      provider={provider}
+      allowedFileTypes={['images', 'videos']}
+      onNavigate={(url) => router.push(url)}
+      basePath="/media"
+    />
+  );
+}
+```
+
+### TanStack Router
+
+```tsx
+import { useRouter } from '@tanstack/react-router';
+
+function MyPage() {
+  const router = useRouter();
+
+  return (
+    <FileManager
+      provider={provider}
+      allowedFileTypes={['images', 'videos']}
+      onNavigate={(url) => router.navigate({ href: url })}
+      basePath="/media"
+    />
+  );
+}
+```
+
+```tsx
+<FileManager
+  provider={provider}
+  allowedFileTypes={['images', 'videos']}
+  basePath="/media"
+  // no onNavigate needed
+/>
+```
+
+## 🎮 Playgrounds & Reference Implementations
+
+For complete, working examples of how to integrate the File Manager into different application architectures, check out the [playgrounds](file:///Users/avi/Developer/Uncia/file-manager/playgrounds) directory. These are fully functional Vite-based projects that demonstrate real-world integration patterns.
+
+- **[React Router v7 Playground](file:///Users/avi/Developer/Uncia/file-manager/playgrounds/test-react-router)**: Demonstrates integration with `react-router-dom` using `useNavigate` and route-based navigation.
+- **[TanStack Router Playground](file:///Users/avi/Developer/Uncia/file-manager/playgrounds/test-tanstack)**: Demonstrates integration with `@tanstack/react-router` using the `router` object and `href` based navigation.
+
+These playgrounds are a great starting point for seeing how to handle:
+- Styling with Tailwind CSS v4
+- Mapping `onNavigate` to your framework's router
+- Using the `MockProvider` for rapid prototyping
+- Configuring `FileManagerModal` v/s full-page `FileManager`
+
+---
+
+> [!NOTE]
+> The `onNavigate` prop is also available on `<FileManagerModal>` for modal mode.
+
+---
+
 ## 💾 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. 

package/dist/cli.cjs

@@ -24,25 +24,27 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // cli.ts
-var fs = __toESM(require("fs"), 1);
-var path = __toESM(require("path"), 1);
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
 var import_child_process = require("child_process");
-var readline = __toESM(require("readline"), 1);
+var import_readline = __toESM(require("readline"), 1);
 var args = process.argv.slice(2);
 var command = args[0];
 var projectName = args[1];
-var rl = readline.createInterface({
+var rl = import_readline.default.createInterface({
   input: process.stdin,
   output: process.stdout
 });
-var askQuestion = (query) => new Promise((resolve) => rl.question(query, resolve));
-var TEMPLATE = `"use client";
+var askQuestion = (query) => {
+  return new Promise((resolve) => rl.question(query, resolve));
+};
+var getTemplate = (basePath = "/media") => `"use client";
 
-import React, { Suspense, useMemo } from "react";
+import React, { Suspense } from "react";
 import { FileManager, MockProvider } from "@unciatech/file-manager";
 
 export default function FileManagerDemo() {
-  const provider = useMemo(() => new MockProvider(), []);
+  const mockProvider = new MockProvider();
 
   return (
     <div className="h-screen w-full">
@@ -50,7 +52,8 @@ export default function FileManagerDemo() {
         <FileManager
           allowedFileTypes={["audios", "videos", "images", "files"]}
           viewMode="grid"
-          provider={provider}
+          provider={mockProvider}
+          basePath="${basePath}"
         />
       </Suspense>
     </div>
@@ -63,30 +66,39 @@ async function main() {
     process.exit(0);
   }
   if (!projectName) {
-    console.log("\u{1F680} Generating <FileManagerDemo /> component...");
+    console.log("\u{1F680} Generating <FileManagerDemo /> component in the current project...");
     let targetDir2 = process.cwd();
-    if (fs.existsSync(path.join(process.cwd(), "src/components"))) {
-      targetDir2 = path.join(process.cwd(), "src/components");
-    } else if (fs.existsSync(path.join(process.cwd(), "components"))) {
-      targetDir2 = path.join(process.cwd(), "components");
+    if (import_fs.default.existsSync(import_path.default.join(process.cwd(), "components"))) {
+      targetDir2 = import_path.default.join(process.cwd(), "components");
+    } else if (import_fs.default.existsSync(import_path.default.join(process.cwd(), "src", "components"))) {
+      targetDir2 = import_path.default.join(process.cwd(), "src", "components");
+    }
+    const targetFile = import_path.default.join(targetDir2, "FileManagerDemo.tsx");
+    if (import_fs.default.existsSync(targetFile)) {
+      console.error(`\u274C Error: ${targetFile} already exists.`);
+      process.exit(1);
     }
-    const file = path.join(targetDir2, "FileManagerDemo.tsx");
-    fs.writeFileSync(file, TEMPLATE);
-    console.log(`\u2705 Created ${file}`);
+    import_fs.default.writeFileSync(targetFile, getTemplate("/"), "utf-8");
+    console.log(`\u2705 Success! Created ${targetFile}`);
+    console.log("");
+    console.log("You can now import and render <FileManagerDemo /> anywhere in your application.");
+    console.log("Don't forget to configure your Tailwind CSS content to scan the library for styles!");
     process.exit(0);
   }
   console.log(`
-\u{1F680} Initializing project: ${projectName}
+\u{1F680} Initializing a new application: ${projectName}
 `);
-  console.log("Choose framework:");
-  console.log("1) Next.js");
-  console.log("2) Vite (React)");
-  console.log("3) Cancel");
-  const choice = await askQuestion("\nSelect option (1-3): ");
-  rl.close();
-  const targetDir = path.join(process.cwd(), projectName);
-  if (fs.existsSync(targetDir)) {
-    console.error("\u274C Directory already exists");
+  console.log("Which framework would you like to use?");
+  console.log("  1) Next.js (App Router, Tailwind v4)");
+  console.log("  2) Vite (React, Tailwind v4)");
+  console.log("  3) Cancel");
+  const choice = await askQuestion("\nSelect an option (1-3): ");
+  const targetDir = import_path.default.join(process.cwd(), projectName);
+  if (import_fs.default.existsSync(targetDir)) {
+    console.error(`
+\u274C Error: Directory "${projectName}" already exists in ${process.cwd()}.`);
+    console.error(`   Please choose a different project name or delete the existing directory first.`);
+    rl.close();
     process.exit(1);
   }
   try {
@@ -96,34 +108,40 @@ async function main() {
       await scaffoldVite(projectName, targetDir);
     } else {
       console.log("Canceled.");
+      process.exit(0);
     }
-  } catch (e) {
-    console.error("\u274C Error:", e);
+  } catch (error) {
+    console.error("\n\u274C Scaffolding failed:", error);
+    process.exit(1);
   }
+  process.exit(0);
 }
 async function scaffoldNextjs(projectName2, targetDir) {
-  console.log("\n\u{1F4E6} Creating Next.js app...");
-  (0, import_child_process.execSync)(
-    `npx create-next-app@latest ${projectName2} --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm`,
-    { stdio: "inherit" }
-  );
-  console.log("\n\u{1F4E6} Installing dependencies...");
-  (0, import_child_process.execSync)("npm install @unciatech/file-manager tailwindcss-animate", {
-    cwd: targetDir,
-    stdio: "inherit"
-  });
-  const componentsDir = path.join(targetDir, "src/components");
-  fs.mkdirSync(componentsDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(componentsDir, "FileManagerDemo.tsx"),
-    TEMPLATE
+  console.log("\n\u{1F4E6} Creating Next.js application (this may take a minute)...");
+  (0, import_child_process.execSync)(`npx create-next-app@latest ${projectName2} --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm`, { stdio: "inherit" });
+  console.log("\n\u{1F4E6} Installing dependencies (@unciatech/file-manager, tailwindcss-animate)...");
+  (0, import_child_process.execSync)("npm install @unciatech/file-manager tailwindcss-animate", { cwd: targetDir, stdio: "inherit" });
+  const componentsDir = import_path.default.join(targetDir, "src", "components");
+  if (!import_fs.default.existsSync(componentsDir)) import_fs.default.mkdirSync(componentsDir, { recursive: true });
+  import_fs.default.writeFileSync(import_path.default.join(componentsDir, "FileManagerDemo.tsx"), getTemplate("/media"), "utf-8");
+  const pagePath = import_path.default.join(targetDir, "src", "app", "page.tsx");
+  import_fs.default.writeFileSync(pagePath, `import FileManagerDemo from "@/components/FileManagerDemo";
+
+export default function Home() {
+  return (
+    <main className="min-h-screen bg-neutral-50">
+      <FileManagerDemo />
+    </main>
   );
-  const pagePath = path.join(targetDir, "src/app/page.tsx");
-  fs.writeFileSync(
-    pagePath,
+}
+`);
+  const mediaRouteDir = import_path.default.join(targetDir, "src", "app", "media", "[[...path]]");
+  import_fs.default.mkdirSync(mediaRouteDir, { recursive: true });
+  import_fs.default.writeFileSync(
+    import_path.default.join(mediaRouteDir, "page.tsx"),
     `import FileManagerDemo from "@/components/FileManagerDemo";
 
-export default function Home() {
+export default function MediaPage() {
   return (
     <main className="min-h-screen bg-neutral-50">
       <FileManagerDemo />
@@ -132,49 +150,61 @@ export default function Home() {
 }
 `
   );
+  const layoutPath = import_path.default.join(targetDir, "src", "app", "layout.tsx");
+  if (import_fs.default.existsSync(layoutPath)) {
+    let layoutContent = import_fs.default.readFileSync(layoutPath, "utf8");
+    if (!layoutContent.includes("@unciatech/file-manager/styles")) {
+      layoutContent = layoutContent.replace(
+        /^(import type)/m,
+        `import '@unciatech/file-manager/styles';
+$1`
+      );
+      import_fs.default.writeFileSync(layoutPath, layoutContent);
+    }
+  }
+  const cssPath = import_path.default.join(targetDir, "src", "app", "globals.css");
+  import_fs.default.writeFileSync(cssPath, `@import "tailwindcss";
+@import "@unciatech/file-manager/styles";
+@import "tw-animate-css";
+
+@source "../../node_modules/@unciatech/file-manager";
+
+@theme {
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+`);
   printSuccess(projectName2);
 }
 async function scaffoldVite(projectName2, targetDir) {
-  console.log("\n\u{1F4E6} Creating Vite app...");
-  (0, import_child_process.execSync)(
-    `npm create vite@latest ${projectName2} -- --template react-ts`,
-    { stdio: "inherit" }
-  );
-  console.log("\n\u{1F4E6} Installing dependencies...");
+  console.log("\n\u{1F4E6} Creating Vite React application...");
+  (0, import_child_process.execSync)(`npm create vite@latest ${projectName2} -- --template react-ts`, { stdio: "inherit" });
+  console.log("\n\u{1F4E6} Installing dependencies (Tailwind + File Manager)...");
   (0, import_child_process.execSync)("npm install", { cwd: targetDir, stdio: "inherit" });
-  (0, import_child_process.execSync)(
-    "npm install tailwindcss @tailwindcss/vite tw-animate-css @unciatech/file-manager",
-    { cwd: targetDir, stdio: "inherit" }
-  );
+  (0, import_child_process.execSync)("npm install tailwindcss @tailwindcss/vite @unciatech/file-manager", { cwd: targetDir, stdio: "inherit" });
+  const viteConfigPath = import_path.default.join(targetDir, "vite.config.ts");
   const viteConfig = `import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 
 export default defineConfig({
-  plugins: [react(), tailwindcss()],
+  plugins: [
+    react(),
+    tailwindcss(),
+  ],
 })
 `;
-  fs.writeFileSync(path.join(targetDir, "vite.config.ts"), viteConfig);
-  const css = `@import "tailwindcss";
-@import "tw-animate-css";
-
-@source "../node_modules/@unciatech/file-manager/dist/**/*.{js,ts,jsx,tsx}";
-`;
-  fs.writeFileSync(path.join(targetDir, "src/index.css"), css);
-  const mainFile = path.join(targetDir, "src/main.tsx");
-  let main2 = fs.readFileSync(mainFile, "utf8");
-  if (!main2.includes("@unciatech/file-manager/styles")) {
-    main2 = `import "@unciatech/file-manager/styles";
-` + main2;
-  }
-  fs.writeFileSync(mainFile, main2);
-  const compDir = path.join(targetDir, "src/components");
-  fs.mkdirSync(compDir, { recursive: true });
-  fs.writeFileSync(
-    path.join(compDir, "FileManagerDemo.tsx"),
-    TEMPLATE
-  );
-  const app = `import FileManagerDemo from "./components/FileManagerDemo";
+  import_fs.default.writeFileSync(viteConfigPath, viteConfig);
+  const cssPath = import_path.default.join(targetDir, "src", "index.css");
+  import_fs.default.writeFileSync(cssPath, `@import "tailwindcss";
+@import "@unciatech/file-manager/styles";
+@source "../node_modules/@unciatech/file-manager";
+`);
+  const componentsDir = import_path.default.join(targetDir, "src", "components");
+  if (!import_fs.default.existsSync(componentsDir)) import_fs.default.mkdirSync(componentsDir, { recursive: true });
+  import_fs.default.writeFileSync(import_path.default.join(componentsDir, "FileManagerDemo.tsx"), getTemplate("/"), "utf-8");
+  const appPath = import_path.default.join(targetDir, "src", "App.tsx");
+  import_fs.default.writeFileSync(appPath, `import FileManagerDemo from "./components/FileManagerDemo";
 
 function App() {
   return (
@@ -185,18 +215,16 @@ function App() {
 }
 
 export default App;
-`;
-  fs.writeFileSync(path.join(targetDir, "src/App.tsx"), app);
-  printSuccess(projectName2);
-}
-function printSuccess(projectName2) {
-  console.log("\n=================================");
-  console.log("\u{1F389} Project ready!");
-  console.log("=================================");
-  console.log(`
-Next steps:`);
-  console.log(`cd ${projectName2}`);
-  console.log(`npm run dev
 `);
+  printSuccess(projectName2, "npm run dev");
+}
+function printSuccess(projectName2, devCmd = "npm run dev") {
+  console.log("\n=========================================");
+  console.log("\u{1F389} Your Media Library application is ready!");
+  console.log("=========================================");
+  console.log("\nNext steps:");
+  console.log(`  cd ${projectName2}`);
+  console.log(`  ${devCmd}`);
+  console.log("\nEnjoy building! \u{1F5C2}\uFE0F\n");
 }
 main();