@vryzel/file-next-headless 0.4.0 → 0.4.2

package/README.md

@@ -1,18 +1,176 @@
 # @vryzel/file-next-headless
 
-Headless React hooks for `@vryzel/file-next`. No UI, no Tailwind, no Radix. Server work is injected as callbacks.
+Headless React hooks for file-next. No UI, no Tailwind, no Radix. You inject server callbacks; the hook owns state.
 
 ```bash
 pnpm add @vryzel/file-next-headless
 ```
 
-| Hook | Role |
+Peer: `react`, `@vryzel/file-next`. Safe in Client Components — it never imports `server-only`.
+
+## Quick path
+
+```tsx
+"use client";
+import { useFileBrowser } from "@vryzel/file-next-headless";
+import { asTenantId } from "@vryzel/file-next";
+import { listFiles } from "./actions"; // "use server"
+
+export function Folder({ parentId }: { parentId: string | null }) {
+  const { status, files, error, refetch } = useFileBrowser({
+    listFiles,
+    tenantId: asTenantId("acme"),
+    parentId,
+    autoFetch: true,
+  });
+
+  if (status === "loading") return <p>Loading…</p>;
+  if (status === "error") return <p>{error?.message}</p>;
+  return (
+    <ul>
+      {files.map((f) => (
+        <li key={f.id}>{f.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+`listFiles` must be a **stable** function (module-level or `useCallback`). A new arrow every render refetches.
+
+## Hooks
+
+| Hook | Use when |
 |---|---|
-| `useFileBrowser` | List + loading/empty/error |
-| `useFileExplorer` | View mode, selection, drag on top of the list |
-| `useUploader` | XHR upload with progress and cancel |
+| `useFileBrowser` | You need a list + loading/empty/error |
+| `useFileExplorer` | List + view mode + selection + drag |
+| `useUploader` | XHR upload with `%` and cancel |
 | `useFileActions` | Optimistic delete/move/copy/rename |
-| `useFileUrl` | Presigned download URL |
-| `useDownloadProgress` | Fetch download with progress |
+| `useFileUrl` | Resolve a presigned download URL |
+| `useDownloadProgress` | Browser download with progress |
+
+If you want the full explorer UI, use `@vryzel/file-next-ui` instead of assembling these yourself.
+
+## Use cases
+
+### 1. List a folder — `useFileBrowser`
+
+```tsx
+const { status, files, error, refetch } = useFileBrowser({
+  listFiles,          // (input) => Promise<Result<{ items }, FileSystemError>>
+  tenantId,
+  parentId,           // null = root
+  autoFetch: true,
+  limit: 50,
+});
+```
+
+Statuses: `idle` → `loading` → `success` | `error`.
+
+### 2. Custom explorer chrome — `useFileExplorer`
+
+```tsx
+const explorer = useFileExplorer({
+  listFiles,
+  tenantId,
+  parentId,
+  initialView: "list",
+  onMove: async ({ itemIds, destinationFolderId }) => {
+    await moveFiles({ itemIds, destinationFolderId });
+  },
+});
+
+explorer.view;          // "list" | "grid"
+explorer.setView("grid");
+explorer.selectedId;
+explorer.beginDrag(id);
+explorer.commitDrop(destinationFolderId);
+```
+
+### 3. Upload with progress — `useUploader`
+
+Uses **XHR**, not `fetch`, so `progress` is real.
+
+```tsx
+const uploader = useUploader({
+  requestUpload: async (file) => ({
+    url: `/api/upload?name=${encodeURIComponent(file.name)}`,
+    method: "PUT",
+    headers: { "Content-Type": file.type || "application/octet-stream" },
+  }),
+  confirmUpload: async () => {
+    await refetch();
+  },
+});
+
+<input
+  type="file"
+  onChange={(e) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    uploader.upload({
+      name: file.name,
+      size: file.size,
+      type: file.type,
+      content: file,
+    });
+  }}
+/>
+<button type="button" onClick={uploader.cancel} disabled={uploader.status !== "uploading"}>
+  Cancel {uploader.progress}%
+</button>
+```
+
+For a queue that survives leaving the page, use `UploadQueueProvider` from `@vryzel/file-next-ui`.
+
+### 4. Optimistic mutations — `useFileActions`
+
+```tsx
+const [files, setFiles] = useState(listed);
+const { deleteFile, moveFile, copyFile, renameFile, isPending, error } =
+  useFileActions({
+    files,
+    setFiles,
+    actions: {
+      deleteFile: (input) => deleteFileAction(input),
+      moveFile: (input) => moveFileAction(input),
+      copyFile: (input) => copyFileAction(input),
+      renameFile: async (id, newName) => {
+        await moveFileAction({ id, newParentId: parentId, newName });
+      },
+    },
+  });
+```
+
+On failure the previous list is restored.
+
+### 5. Preview / download URL — `useFileUrl`
+
+```tsx
+const { url, status } = useFileUrl({
+  getDownloadUrl: ({ key }) => getDownloadUrlAction({ key }),
+  key: file.s3Key,
+});
+return url ? <img src={url} alt={file.name} /> : null;
+```
+
+### 6. Download with progress — `useDownloadProgress`
+
+Starts when `url` is set. Status: `idle` | `loading` | `success` | `error` | `aborted`.
+
+```tsx
+const dl = useDownloadProgress({ url: signedUrl });
+<p>{dl.status === "loading" ? `${dl.progress}%` : dl.status}</p>
+<button type="button" onClick={dl.cancel}>Cancel</button>
+{dl.blob ? <a href={URL.createObjectURL(dl.blob)} download>Save</a> : null}
+```
+
+## Contract
+
+Callbacks return the same `Result` as the server:
+
+```ts
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+```
 
-Public on npmjs. See the repository README.
+Do not import `@vryzel/file-next/server` from a file that also imports these hooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vryzel/file-next-headless",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Headless React hooks for file-next: behavior-only state machines for file browsers, uploaders, file actions, presigned URL resolution, and download progress. No UI, no Tailwind, no Radix. State is local per-hook (useReducer); server actions are dependency-injected.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "react-dom": "^18.3.1",
     "tsup": "^8.3.5",
     "vitest": "^2.1.5",
-    "@vryzel/file-next": "0.4.0"
+    "@vryzel/file-next": "0.4.2"
   },
   "keywords": [
     "react",