@vryzel/file-next-headless 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import { TenantId, Result, FileNode, FileSystemError } from '@vryzel/file-next';
+import { FileSystemError as FileSystemError$1 } from '@vryzel/file-next/errors';
+
+/** Narrow shape of what the hook needs from the server action. */
+type ListFilesInput = {
+    readonly tenantId: TenantId;
+    readonly parentId: string | null;
+    readonly prefix?: string;
+    readonly limit?: number;
+};
+type ListFilesOutput = {
+    readonly items: ReadonlyArray<FileNode>;
+};
+/** The injected dependency. Returns the same Result shape the server uses. */
+type ListFilesFn = (input: ListFilesInput) => Promise<Result<ListFilesOutput, FileSystemError>>;
+interface UseFileBrowserOptions {
+    /** The list callback (injected; typically wraps a server action). */
+    readonly listFiles: ListFilesFn;
+    /** Tenant scope — forwarded to every listFiles call. */
+    readonly tenantId: TenantId;
+    /** Folder to list (null = root). */
+    readonly parentId: string | null;
+    /** Optional S3 prefix filter. */
+    readonly prefix?: string;
+    /** Optional cap on items per call. */
+    readonly limit?: number;
+    /**
+     * Auto-fetch on mount (default: false). The spec describes the
+     * state machine as `idle → user calls refetch() → loading → ...`,
+     * so the hook is imperative by default. Set `true` to fetch as
+     * soon as the component mounts (typical for full-page file
+     * browsers that want to show data immediately).
+     */
+    readonly autoFetch?: boolean;
+}
+type UseFileBrowserStatus = "idle" | "loading" | "success" | "error";
+interface UseFileBrowserState {
+    readonly status: UseFileBrowserStatus;
+    readonly files: ReadonlyArray<FileNode>;
+    readonly error: FileSystemError | null;
+}
+interface UseFileBrowserReturn {
+    readonly status: UseFileBrowserStatus;
+    readonly files: ReadonlyArray<FileNode>;
+    readonly error: FileSystemError | null;
+    /** Re-run the listFiles call. Safe to call any time; cancels nothing. */
+    readonly refetch: () => Promise<void>;
+}
+/**
+ * useFileBrowser — list files for a folder via an injected callback.
+ *
+ * The hook fires the list on mount (unless `autoFetch: false`) and
+ * exposes a stable `refetch` to re-run. The state is local: every
+ * consumer instance has its own state machine.
+ */
+declare function useFileBrowser(options: UseFileBrowserOptions): UseFileBrowserReturn;
+
+/** Narrow file shape — the hook doesn't need the full DOM File. */
+interface UploaderFile {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    readonly content: Blob;
+}
+/** Optional post-upload confirm callback. Receives the XHR + the file. */
+type ConfirmUploadFn = (xhr: XMLHttpRequest, file: UploaderFile, meta?: {
+    id?: string;
+}) => void;
+interface RequestUploadResult {
+    readonly url: string;
+    readonly method?: "PUT" | "POST";
+    readonly headers?: Record<string, string>;
+    readonly id?: string;
+}
+interface UseUploaderOptions {
+    /** The presigned URL to PUT the file to. Ignored when `requestUpload` is set. */
+    readonly uploadUrl?: string;
+    /** Resolve a fresh presigned URL per file (preferred). */
+    readonly requestUpload?: (file: UploaderFile) => Promise<RequestUploadResult>;
+    /**
+     * Optional callback fired once the upload completes successfully.
+     * Typically used to trigger a server action that records metadata.
+     * NEVER fires if the upload is canceled.
+     */
+    readonly confirmUpload?: ConfirmUploadFn;
+}
+type UseUploaderStatus = "idle" | "uploading" | "success" | "error" | "aborted";
+interface UseUploaderState {
+    readonly status: UseUploaderStatus;
+    readonly progress: number;
+    readonly error: FileSystemError$1 | null;
+}
+interface UseUploaderReturn {
+    readonly status: UseUploaderStatus;
+    readonly progress: number;
+    readonly error: FileSystemError$1 | null;
+    /** Kick off an upload. No-op if an upload is already in flight. */
+    readonly upload: (file: UploaderFile) => void;
+    /** Abort the in-flight upload. No-op if idle / done. */
+    readonly cancel: () => void;
+}
+/**
+ * useUploader — upload via XHR with progress + cancel.
+ *
+ * The hook is intentionally imperative: the consumer calls
+ * `upload(file)` to start, and may call `cancel()` to abort.
+ * No effects fire automatically (uploads should not happen until
+ * the user picks a file).
+ */
+declare function useUploader(options: UseUploaderOptions): UseUploaderReturn;
+
+interface DeleteFileInput {
+    readonly id: string;
+}
+interface DeleteFileOutput {
+    readonly id: string;
+}
+interface MoveFileInput {
+    readonly id: string;
+    readonly newParentId: string;
+}
+interface MoveFileOutput {
+    readonly id: string;
+}
+interface CopyFileInput {
+    readonly id: string;
+    readonly newParentId: string;
+}
+interface CopyFileOutput {
+    readonly node: FileNode;
+}
+type DeleteFileFn = (input: DeleteFileInput) => Promise<Result<DeleteFileOutput, FileSystemError>>;
+type MoveFileFn = (input: MoveFileInput) => Promise<Result<MoveFileOutput, FileSystemError>>;
+type CopyFileFn = (input: CopyFileInput) => Promise<Result<CopyFileOutput, FileSystemError>>;
+type RenameFileFn = (id: string, newName: string) => Promise<void>;
+interface UseFileActionsOptions {
+    /** The current file list (consumer-owned). */
+    readonly files: ReadonlyArray<FileNode>;
+    /** The state setter for the file list (consumer-owned). */
+    readonly setFiles: (next: ReadonlyArray<FileNode>) => void;
+    /** The three server-action callbacks (typically wrappers around RSC actions). */
+    readonly actions: {
+        readonly deleteFile: DeleteFileFn;
+        readonly moveFile: MoveFileFn;
+        readonly copyFile: CopyFileFn;
+        readonly renameFile: RenameFileFn;
+    };
+}
+type UseFileActionsStatus = "idle" | "pending";
+interface UseFileActionsState {
+    readonly status: UseFileActionsStatus;
+    readonly error: FileSystemError | null;
+}
+interface UseFileActionsReturn {
+    readonly status: UseFileActionsStatus;
+    readonly isPending: boolean;
+    readonly error: FileSystemError | null;
+    readonly deleteFile: (id: string) => Promise<void>;
+    readonly moveFile: (id: string, newParentId: string) => Promise<void>;
+    readonly copyFile: (id: string, newParentId: string) => Promise<void>;
+    readonly renameFile: (id: string, newName: string) => Promise<void>;
+}
+/**
+ * useFileActions — optimistic mutations with rollback.
+ *
+ * Each mutator:
+ *   1. Snapshots the current `files` reference.
+ *   2. Dispatches `START` (isPending = true).
+ *   3. Calls `setFiles(optimistic)` immediately.
+ *   4. Awaits the action.
+ *   5. On `ok: true`, dispatches `SUCCESS` (no further setFiles — the
+ *      server's response is the new truth; the optimistic value
+ *      either matches or the consumer reconciles via refresh).
+ *   6. On `ok: false`, calls `setFiles(snapshot)` to roll back, then
+ *      dispatches `ERROR`.
+ */
+declare function useFileActions(options: UseFileActionsOptions): UseFileActionsReturn;
+
+interface GetDownloadUrlInput {
+    readonly key: string;
+}
+interface GetDownloadUrlOutput {
+    readonly url: string;
+}
+type GetDownloadUrlFn = (input: GetDownloadUrlInput) => Promise<Result<GetDownloadUrlOutput, FileSystemError>>;
+interface UseFileUrlOptions {
+    /** The injected download-URL resolver (wraps a server action). */
+    readonly getDownloadUrl: GetDownloadUrlFn;
+    /** The object key to resolve a URL for. */
+    readonly key: string;
+    /**
+     * When false, the fetch is skipped (status stays `idle`, url is
+     * null). Useful for click-to-load patterns and conditional prefetch.
+     * Default: true.
+     */
+    readonly enabled?: boolean;
+}
+type UseFileUrlStatus = "idle" | "loading" | "success" | "error";
+interface UseFileUrlReturn {
+    readonly url: string | null;
+    readonly status: UseFileUrlStatus;
+    readonly error: FileSystemError | null;
+}
+declare function useFileUrl(options: UseFileUrlOptions): UseFileUrlReturn;
+
+interface UseDownloadProgressOptions {
+    /** The URL to download from. */
+    readonly url: string;
+    /**
+     * Optional AbortSignal to share cancellation with the consumer's
+     * own logic (e.g., the consumer unmounts the component).
+     * If provided, the hook's `cancel()` AND this signal both abort.
+     */
+    readonly externalSignal?: AbortSignal;
+}
+type UseDownloadProgressStatus = "idle" | "loading" | "success" | "error" | "aborted";
+interface UseDownloadProgressState {
+    readonly status: UseDownloadProgressStatus;
+    readonly progress: number;
+    readonly blob: Blob | null;
+    readonly error: FileSystemError$1 | null;
+}
+interface UseDownloadProgressReturn {
+    readonly status: UseDownloadProgressStatus;
+    readonly progress: number;
+    readonly blob: Blob | null;
+    readonly error: FileSystemError$1 | null;
+    readonly cancel: () => void;
+}
+declare function useDownloadProgress(options: UseDownloadProgressOptions): UseDownloadProgressReturn;
+
+type ViewMode = "list" | "grid";
+interface UseFileExplorerOptions {
+    /** List callback (injected). */
+    readonly listFiles: Parameters<typeof useFileBrowser>[0]["listFiles"];
+    /** Tenant scope. */
+    readonly tenantId: TenantId;
+    /** Current folder (null = root). */
+    readonly parentId: string | null;
+    /** Initial view mode. Default: "list". */
+    readonly initialView?: ViewMode;
+    /** Auto-fetch on mount. Default: true (the explorer expects data). */
+    readonly autoFetch?: boolean;
+    /** Optional callback fired when the user picks a file/folder via click or keyboard. */
+    readonly onActivate?: (file: FileNode) => void;
+    readonly onMove?: (input: {
+        itemIds: ReadonlyArray<string>;
+        destinationFolderId: string;
+    }) => Promise<void> | void;
+}
+interface UseFileExplorerReturn {
+    readonly status: ReturnType<typeof useFileBrowser>["status"];
+    readonly files: ReadonlyArray<FileNode>;
+    readonly error: ReturnType<typeof useFileBrowser>["error"];
+    readonly refetch: () => Promise<void>;
+    readonly view: ViewMode;
+    readonly setView: (v: ViewMode) => void;
+    readonly selectedId: string | null;
+    readonly setSelected: (id: string | null) => void;
+    readonly contextTarget: FileNode | null;
+    readonly openContextMenu: (file: FileNode | null) => void;
+    readonly draggingId: string | null;
+    readonly dropTargetId: string | null;
+    readonly beginDrag: (id: string) => void;
+    readonly setDropTarget: (id: string | null) => void;
+    readonly commitDrop: (destinationFolderId: string) => void;
+    readonly endDrag: () => void;
+}
+declare function useFileExplorer(options: UseFileExplorerOptions): UseFileExplorerReturn;
+
+export { type ConfirmUploadFn, type CopyFileFn, type CopyFileInput, type CopyFileOutput, type DeleteFileFn, type DeleteFileInput, type DeleteFileOutput, type GetDownloadUrlFn, type GetDownloadUrlInput, type GetDownloadUrlOutput, type ListFilesFn, type ListFilesInput, type ListFilesOutput, type MoveFileFn, type MoveFileInput, type MoveFileOutput, type RequestUploadResult, type UploaderFile, type UseDownloadProgressOptions, type UseDownloadProgressReturn, type UseDownloadProgressState, type UseDownloadProgressStatus, type UseFileActionsOptions, type UseFileActionsReturn, type UseFileActionsState, type UseFileActionsStatus, type UseFileBrowserOptions, type UseFileBrowserReturn, type UseFileBrowserState, type UseFileBrowserStatus, type UseFileExplorerOptions, type UseFileExplorerReturn, type UseFileUrlOptions, type UseFileUrlReturn, type UseFileUrlStatus, type UseUploaderOptions, type UseUploaderReturn, type UseUploaderState, type UseUploaderStatus, type ViewMode, useDownloadProgress, useFileActions, useFileBrowser, useFileExplorer, useFileUrl, useUploader };