@vryzel/file-next-ui 0.4.0 → 0.4.2

package/README.md

@@ -1,39 +1,224 @@
 # @vryzel/file-next-ui
 
-Ready-to-use file explorer for `@vryzel/file-next`. Tailwind classes. Compose the pieces, or drop in `FileExplorer`.
+Ready-made file explorer for Next.js. Import `FileExplorer`, pass server callbacks, done. Or compose the pieces.
 
 ```bash
 pnpm add @vryzel/file-next-ui
 ```
 
-Scan the package in `tailwind.config`:
+Scan the package so Tailwind keeps the classes:
 
 ```js
-content: ["./node_modules/@vryzel/file-next-ui/dist/**/*.{js,mjs}"]
+// tailwind.config.ts
+content: [
+  "./app/**/*.{ts,tsx}",
+  "./node_modules/@vryzel/file-next-ui/dist/**/*.{js,mjs}",
+]
 ```
 
-## Default explorer
+Your theme must define the usual shadcn CSS variables (`--background`, `--foreground`, `--border`, `--primary`, `--muted`, `--destructive`, `--card`, `--ring`, …).
+
+## Quick path
 
 ```tsx
+"use client";
 import { FileExplorer } from "@vryzel/file-next-ui";
 
 <FileExplorer
-  className="h-[70vh] rounded-[10px] border border-border"
+  className="h-[70vh] overflow-hidden rounded-[10px] border border-border bg-card"
   tenantId="acme"
-  parentId={null}
+  parentId={folderId}
   listFiles={listFiles}
   searchFiles={searchFiles}
   listTrash={listTrash}
   requestUpload={requestUpload}
-  actions={actions}
-  onOpenFolder={setFolder}
+  actions={{
+    deleteFile,
+    moveFile,
+    copyFile,
+    renameFile,
+    createFolder,
+    restoreNode,
+    createShare,
+  }}
+  onOpenFolder={(folder) => setFolderId(folder.id)}
+  breadcrumbs={crumbs}
+  onBreadcrumbNavigate={(seg) => setFolderId(seg.id === "root" ? null : seg.id)}
+/>
+```
+
+`listFiles` / `searchFiles` / `listTrash` return:
+
+```ts
+Promise<
+  | { ok: true; value: { items: FileNode[]; nextCursor?: string } }
+  | { ok: false; error: { code: string; message: string } }
+>
+```
+
+Revive dates if they crossed the server action boundary (`new Date(node.updatedAt)`). `FileExplorer` also revives them.
+
+Keep callback identities stable (`useCallback` or module scope).
+
+## Use cases
+
+### 1. Default explorer (batteries)
+
+What you get with `FileExplorer`:
+
+- List / grid, sort, persisted view (`persistViewKey`)
+- Search, trash, upload (multi-file + OS drop)
+- New folder / rename dialogs (not `window.prompt`)
+- Multi-select, shift-click, ⌘A, copy/paste, drag onto folders
+- Pagination (`limit` 50 + Load more)
+- Quota footer, selection toast, upload queue
+
+```tsx
+<FileExplorer
+  persistViewKey="my-app.files.view"
+  usedBytes={used}
+  quotaBytes={quota}
+  refreshKey={refreshKey}
+  onPreview={openPreview}
+  onDownload={download}
+  extraFileAction={{ label: "Create quote", onSelect: (f) => router.push(`/quotes/new?file=${f.id}`) }}
+  protectedIds={linkedIds}  // cannot move to trash
+  labels={{ search: "Buscar", emptyFolder: "Carpeta vacía" }}
+  {...props}
+/>
+```
+
+### 2. Uploads that survive navigation
+
+Put the provider on a layout. Unmounting the files page will not kill XHR.
+
+```tsx
+// app/(dashboard)/layout.tsx
+import { UploadQueueProvider } from "@vryzel/file-next-ui";
+
+<UploadQueueProvider requestUpload={requestUpload} confirmUpload={onUploaded}>
+  {children}
+</UploadQueueProvider>
+```
+
+`FileExplorer` uses the nearest provider; if none exists it creates its own.
+
+### 3. Preview dialog
+
+```tsx
+import { FileExplorer, FilePreviewDialog, canPreviewFile } from "@vryzel/file-next-ui";
+
+const [preview, setPreview] = useState<{ file: FileNode; src: string } | null>(null);
+
+<FileExplorer
+  onPreview={async (file) => {
+    const src = await signedUrl(file);
+    if (canPreviewFile(file)) setPreview({ file, src });
+    else window.open(src, "_blank");
+  }}
+  onDownload={async (file) => window.open(await signedUrl(file), "_blank")}
+/>
+<FilePreviewDialog
+  file={preview?.file ?? null}
+  src={preview?.src ?? ""}
+  onClose={() => setPreview(null)}
+  onDownload={(file) => void signedUrl(file).then((src) => window.open(src, "_blank"))}
 />
 ```
 
-Pass `labels` to override copy. Pass `className` on any piece to restyle.
+`src` is yours (presigned GET). The dialog does not call S3.
+
+### 4. Compose your own shell
+
+```tsx
+import {
+  Breadcrumbs,
+  ExplorerToolbar,
+  ExplorerListView,
+  ExplorerGridView,
+  EmptyState,
+  ErrorState,
+  FileIcon,
+} from "@vryzel/file-next-ui";
+import { useFileExplorer } from "@vryzel/file-next-headless";
+
+const explorer = useFileExplorer({ listFiles, tenantId, parentId });
+
+return (
+  <div className="flex h-[70vh] flex-col rounded-[10px] border">
+    <Breadcrumbs segments={crumbs} onNavigate={go} className="px-4 py-3" />
+    <ExplorerToolbar
+      view={explorer.view}
+      onViewChange={explorer.setView}
+      query={query}
+      onQueryChange={setQuery}
+      sortKey={sortKey}
+      sortDirection={sortDir}
+      onSortChange={setSort}
+    />
+    {explorer.status === "error" ? (
+      <ErrorState error={explorer.error!} onRetry={explorer.refetch} />
+    ) : explorer.files.length === 0 ? (
+      <EmptyState title="Empty folder" description="Drop files here." />
+    ) : explorer.view === "list" ? (
+      <ExplorerListView files={explorer.files} {...selectionAndDrag} />
+    ) : (
+      <ExplorerGridView files={explorer.files} {...selectionAndDrag} />
+    )}
+  </div>
+);
+```
+
+Every piece takes `className`.
 
-Put `UploadQueueProvider` on a layout if uploads should survive unmounting the page.
+### 5. Copy / i18n
+
+```tsx
+<FileExplorer
+  labels={{
+    search: "Buscar",
+    upload: "Subir",
+    newFolder: "Nueva carpeta",
+    emptyFolder: "Esta carpeta está vacía",
+    moveToTrash: "Mover a la papelera",
+  }}
+/>
+```
+
+Partial overlay on English defaults. Or wrap several pieces:
+
+```tsx
+import { ExplorerLabelsProvider, defaultLabels } from "@vryzel/file-next-ui";
+
+<ExplorerLabelsProvider labels={{ search: "Buscar" }}>
+  <ExplorerToolbar ... />
+</ExplorerLabelsProvider>
+```
+
+### 6. Icons only
+
+```tsx
+import { FileIcon } from "@vryzel/file-next-ui";
+<FileIcon kind={file.kind} mimeType={file.mimeType} className="size-6" />
+```
 
 ## Pieces
 
-`ExplorerToolbar`, `ExplorerListView`, `ExplorerGridView`, `ExplorerContextMenu`, `Breadcrumbs`, `EmptyState`, `ErrorState`, `FileIcon`, `FilePreviewDialog`, `CreateFolderDialog`, `ConfirmDeleteDialog`, `ExplorerSelectionToast`, `ExplorerUploadStatus`.
+| Export | Role |
+|---|---|
+| `FileExplorer` | Default composed explorer |
+| `ExplorerToolbar` | Search, upload, new folder, sort, trash, list/grid |
+| `ExplorerListView` / `ExplorerGridView` | Rows / cards + drag |
+| `ExplorerContextMenu` | Right-click / overflow menu |
+| `Breadcrumbs` | Path |
+| `EmptyState` / `ErrorState` | Empty / error |
+| `FileIcon` | Mime icon |
+| `FilePreviewDialog` | Image/pdf/video/text overlay |
+| `CreateFolderDialog` / `ConfirmDeleteDialog` | Modals |
+| `ExplorerSelectionToast` / `ExplorerClipboardToast` | Multi-select / copy |
+| `UploadQueueProvider` / `ExplorerUploadStatus` | Upload queue |
+| `defaultLabels` | English copy |
+
+## Not this package
+
+Server wiring → `@vryzel/file-next`. Hooks without UI → `@vryzel/file-next-headless`.

package/dist/index.cjs

@@ -836,24 +836,26 @@ function ExplorerContextMenu(props) {
           /* @__PURE__ */ jsxRuntime.jsx(lucideReact.RotateCcw, { "aria-hidden": "true", className: "size-4" }),
           labels.restore
         ] }),
-        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "my-1 h-px bg-border" }),
-        /* @__PURE__ */ jsxRuntime.jsxs(
-          "button",
-          {
-            type: "button",
-            role: "menuitem",
-            className: cn(itemClass, "text-destructive"),
-            onClick: () => {
-              close();
-              if (onRequestPurge) onRequestPurge(target.file);
-              else void actions.purgeNode?.({ id: target.file.id });
-            },
-            children: [
-              /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { "aria-hidden": "true", className: "size-4" }),
-              labels.deleteForever
-            ]
-          }
-        )
+        onRequestPurge || actions.purgeNode ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+          /* @__PURE__ */ jsxRuntime.jsx("div", { className: "my-1 h-px bg-border" }),
+          /* @__PURE__ */ jsxRuntime.jsxs(
+            "button",
+            {
+              type: "button",
+              role: "menuitem",
+              className: cn(itemClass, "text-destructive"),
+              onClick: () => {
+                close();
+                if (onRequestPurge) onRequestPurge(target.file);
+                else void actions.purgeNode?.({ id: target.file.id });
+              },
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { "aria-hidden": "true", className: "size-4" }),
+                labels.deleteForever
+              ]
+            }
+          )
+        ] }) : null
       ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
         target.file.kind === "file" && onPreview ? /* @__PURE__ */ jsxRuntime.jsxs("button", { type: "button", role: "menuitem", className: itemClass, onClick: () => {
           close();
@@ -1954,7 +1956,7 @@ function FileExplorerInner(props) {
       if ((event.key === "Delete" || event.key === "Backspace") && selectedFiles.length > 0) {
         event.preventDefault();
         if (trashOpen) {
-          setPurgeTargets(selectedFiles);
+          if (actions.purgeNode) setPurgeTargets(selectedFiles);
           return;
         }
         if (selectedFiles.some((file) => protectedSet.has(file.id))) return;
@@ -2157,7 +2159,7 @@ function FileExplorerInner(props) {
             onDownload,
             onRename: setRenameTarget,
             onRequestDelete: (file) => setDeleteTargets([file]),
-            onRequestPurge: (file) => setPurgeTargets([file]),
+            onRequestPurge: actions.purgeNode ? (file) => setPurgeTargets([file]) : void 0,
             onCopy: (file) => copyToClipboard([file]),
             onPaste: clipboard.length > 0 && !trashOpen ? (folder) => void pasteClipboard(folder ? folder.id : parentId) : void 0,
             onNewFolder: actions.createFolder ? () => setFolderOpen(true) : void 0,
@@ -2186,7 +2188,7 @@ function FileExplorerInner(props) {
               clearSelection();
               await reload();
             } : void 0,
-            onPurge: () => setPurgeTargets(selectedFiles),
+            onPurge: actions.purgeNode ? () => setPurgeTargets(selectedFiles) : void 0,
             onClear: clearSelection
           }
         ),