@vryzel/file-next-headless 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 file-next contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @vryzel/file-next-headless
+
+Headless React hooks for `@vryzel/file-next`. No UI, no Tailwind, no Radix. Server work is injected as callbacks.
+
+```bash
+pnpm add @vryzel/file-next-headless
+```
+
+| Hook | Role |
+|---|---|
+| `useFileBrowser` | List + loading/empty/error |
+| `useFileExplorer` | View mode, selection, drag on top of the list |
+| `useUploader` | XHR upload with progress and cancel |
+| `useFileActions` | Optimistic delete/move/copy/rename |
+| `useFileUrl` | Presigned download URL |
+| `useDownloadProgress` | Fetch download with progress |
+
+Public on npmjs. See the repository README.

package/dist/index.cjs

@@ -0,0 +1,559 @@
+'use strict';
+
+var react = require('react');
+var errors = require('@vryzel/file-next/errors');
+
+// src/use-file-browser.ts
+var initial = {
+  status: "idle",
+  files: [],
+  error: null
+};
+var reducer = (state, action) => {
+  switch (action.type) {
+    case "FETCH_START":
+      return { status: "loading", files: [], error: null };
+    case "FETCH_SUCCESS":
+      return { status: "success", files: action.files, error: null };
+    case "FETCH_ERROR":
+      return { status: "error", files: [], error: action.error };
+  }
+};
+function useFileBrowser(options) {
+  const { listFiles, tenantId, parentId, prefix, limit, autoFetch = false } = options;
+  const [state, dispatch] = react.useReducer(reducer, initial);
+  const run = react.useCallback(async () => {
+    dispatch({ type: "FETCH_START" });
+    const result = await listFiles({ tenantId, parentId, prefix, limit });
+    if (result.ok) {
+      dispatch({ type: "FETCH_SUCCESS", files: result.value.items });
+    } else {
+      dispatch({ type: "FETCH_ERROR", error: result.error });
+    }
+  }, [listFiles, tenantId, parentId, prefix, limit]);
+  react.useEffect(() => {
+    if (autoFetch) {
+      void run();
+    }
+  }, [autoFetch, run]);
+  return {
+    status: state.status,
+    files: state.files,
+    error: state.error,
+    refetch: run
+  };
+}
+var initial2 = {
+  status: "idle",
+  progress: 0,
+  error: null
+};
+var reducer2 = (state, action) => {
+  switch (action.type) {
+    case "UPLOAD_START":
+      return { status: "uploading", progress: 0, error: null };
+    case "PROGRESS": {
+      if (action.total <= 0) return state;
+      const pct = Math.min(100, Math.round(action.loaded / action.total * 100));
+      return { ...state, progress: pct };
+    }
+    case "UPLOAD_SUCCESS":
+      return { status: "success", progress: 100, error: null };
+    case "UPLOAD_ERROR":
+      return { status: "error", progress: state.progress, error: action.error };
+    case "UPLOAD_ABORTED":
+      return { status: "aborted", progress: state.progress, error: null };
+  }
+};
+function useUploader(options) {
+  const { uploadUrl, requestUpload, confirmUpload } = options;
+  const [state, dispatch] = react.useReducer(reducer2, initial2);
+  const xhrRef = react.useRef(null);
+  const canceledRef = react.useRef(false);
+  const startXhr = react.useCallback(
+    (file, target) => {
+      if (xhrRef.current !== null) return;
+      const xhr = new XMLHttpRequest();
+      xhrRef.current = xhr;
+      canceledRef.current = false;
+      xhr.upload.addEventListener("progress", (event) => {
+        if (event.lengthComputable) {
+          dispatch({ type: "PROGRESS", loaded: event.loaded, total: event.total });
+        }
+      });
+      xhr.addEventListener("load", () => {
+        if (xhrRef.current !== xhr || canceledRef.current) return;
+        xhrRef.current = null;
+        if (xhr.status < 200 || xhr.status >= 300) {
+          let message = `Upload failed (${xhr.status})`;
+          try {
+            const parsed = JSON.parse(xhr.responseText);
+            if (parsed.error?.message) message = parsed.error.message;
+          } catch {
+          }
+          dispatch({
+            type: "UPLOAD_ERROR",
+            error: new errors.FileSystemError({
+              code: "NetworkError",
+              retryable: true,
+              message,
+              cause: { code: "HttpError", message: `status ${xhr.status}` }
+            })
+          });
+          return;
+        }
+        dispatch({ type: "UPLOAD_SUCCESS" });
+        void Promise.resolve(confirmUpload?.(xhr, file, { id: target.id })).catch(
+          (error) => {
+            dispatch({
+              type: "UPLOAD_ERROR",
+              error: new errors.FileSystemError({
+                code: "InternalError",
+                retryable: false,
+                message: error instanceof Error ? error.message : "confirmUpload failed"
+              })
+            });
+          }
+        );
+      });
+      xhr.addEventListener("error", () => {
+        if (xhrRef.current !== xhr || canceledRef.current) return;
+        xhrRef.current = null;
+        dispatch({
+          type: "UPLOAD_ERROR",
+          error: new errors.FileSystemError({
+            code: "NetworkError",
+            retryable: true,
+            message: "XHR upload failed (usually CORS). Same-origin /api/upload avoids this.",
+            cause: { code: "XhrError", message: "XHR error event" }
+          })
+        });
+      });
+      dispatch({ type: "UPLOAD_START" });
+      xhr.open(target.method ?? "PUT", target.url);
+      xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+      for (const [header, value] of Object.entries(target.headers ?? {})) {
+        xhr.setRequestHeader(header, value);
+      }
+      xhr.send(file.content);
+    },
+    [confirmUpload]
+  );
+  const upload = react.useCallback(
+    (file) => {
+      if (xhrRef.current !== null) return;
+      if (requestUpload) {
+        dispatch({ type: "UPLOAD_START" });
+        void requestUpload(file).then((target) => {
+          if (canceledRef.current) return;
+          xhrRef.current = null;
+          startXhr(file, target);
+        }).catch((error) => {
+          dispatch({
+            type: "UPLOAD_ERROR",
+            error: new errors.FileSystemError({
+              code: "NetworkError",
+              retryable: true,
+              message: error instanceof Error ? error.message : "requestUpload failed"
+            })
+          });
+        });
+        return;
+      }
+      if (!uploadUrl) return;
+      startXhr(file, { url: uploadUrl, method: "PUT" });
+    },
+    [requestUpload, startXhr, uploadUrl]
+  );
+  const cancel = react.useCallback(() => {
+    const xhr = xhrRef.current;
+    if (xhr === null) return;
+    xhr.abort();
+    canceledRef.current = true;
+    xhrRef.current = null;
+    dispatch({ type: "UPLOAD_ABORTED" });
+  }, []);
+  return {
+    status: state.status,
+    progress: state.progress,
+    error: state.error,
+    upload,
+    cancel
+  };
+}
+var initial3 = {
+  status: "idle",
+  error: null
+};
+var reducer3 = (state, action) => {
+  switch (action.type) {
+    case "START":
+      return { status: "pending", error: null };
+    case "SUCCESS":
+      return { status: "idle", error: null };
+    case "ERROR":
+      return { status: "idle", error: action.error };
+  }
+};
+function applyDelete(files, id) {
+  return files.filter((f) => f.id !== id);
+}
+function applyMove(files, id, newParentId) {
+  return files.map((f) => f.id === id ? { ...f, parentId: newParentId } : f);
+}
+function applyCopy(files, node) {
+  return [...files, node];
+}
+function applyRename(files, id, newName) {
+  return files.map((file) => file.id === id ? { ...file, name: newName } : file);
+}
+function useFileActions(options) {
+  const { files, setFiles, actions } = options;
+  const [state, dispatch] = react.useReducer(reducer3, initial3);
+  const run = react.useCallback(
+    async (args) => {
+      const snapshot = files;
+      const optimisticNext = args.optimistic();
+      dispatch({ type: "START" });
+      if (optimisticNext !== snapshot) {
+        setFiles(optimisticNext);
+      }
+      const result = await args.act(args.input);
+      if (result.ok) {
+        if (args.onSuccess) {
+          setFiles(args.onSuccess(result.value));
+        }
+        dispatch({ type: "SUCCESS" });
+      } else {
+        setFiles(snapshot);
+        dispatch({ type: "ERROR", error: result.error });
+      }
+    },
+    [files, setFiles]
+  );
+  const deleteFile = react.useCallback(
+    (id) => run({
+      input: { id },
+      optimistic: () => applyDelete(files, id),
+      act: actions.deleteFile
+    }),
+    [run, actions.deleteFile, files]
+  );
+  const moveFile = react.useCallback(
+    (id, newParentId) => run({
+      input: { id, newParentId },
+      optimistic: () => applyMove(files, id, newParentId),
+      act: actions.moveFile
+    }),
+    [run, actions.moveFile, files]
+  );
+  const copyFile = react.useCallback(
+    (id, newParentId) => run({
+      input: { id, newParentId },
+      optimistic: () => files,
+      // copy doesn't remove anything
+      act: actions.copyFile,
+      onSuccess: (output) => applyCopy(files, output.node)
+    }),
+    [run, actions.copyFile, files]
+  );
+  const renameFile = react.useCallback(
+    async (id, newName) => {
+      const snapshot = files;
+      dispatch({ type: "START" });
+      setFiles(applyRename(files, id, newName));
+      try {
+        await actions.renameFile(id, newName);
+        dispatch({ type: "SUCCESS" });
+      } catch (error) {
+        setFiles(snapshot);
+        dispatch({ type: "ERROR", error });
+      }
+    },
+    [actions.renameFile, files, setFiles]
+  );
+  return {
+    status: state.status,
+    isPending: state.status === "pending",
+    error: state.error,
+    deleteFile,
+    moveFile,
+    copyFile,
+    renameFile
+  };
+}
+function useFileUrl(options) {
+  const { getDownloadUrl, key, enabled = true } = options;
+  const [url, setUrl] = react.useState(null);
+  const [error, setError] = react.useState(null);
+  const [status, setStatus] = react.useState(enabled ? "loading" : "idle");
+  const latestKeyRef = react.useRef(null);
+  const latestEnabledRef = react.useRef(null);
+  react.useEffect(() => {
+    if (!enabled) {
+      latestEnabledRef.current = false;
+      setStatus("idle");
+      return;
+    }
+    latestEnabledRef.current = true;
+    latestKeyRef.current = key;
+    setStatus("loading");
+    setError(null);
+    let cancelled = false;
+    void (async () => {
+      const result = await getDownloadUrl({ key });
+      if (cancelled) return;
+      if (latestKeyRef.current !== key) return;
+      if (latestEnabledRef.current === false) return;
+      if (result.ok) {
+        setUrl(result.value.url);
+        setStatus("success");
+      } else {
+        setError(result.error);
+        setStatus("error");
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [getDownloadUrl, key, enabled]);
+  return { url, status, error };
+}
+var initial4 = {
+  status: "idle",
+  progress: 0,
+  blob: null,
+  error: null
+};
+var reducer4 = (state, action) => {
+  switch (action.type) {
+    case "START":
+      return { status: "loading", progress: 0, blob: null, error: null };
+    case "PROGRESS": {
+      if (action.total <= 0) return state;
+      const pct = Math.min(100, Math.round(action.loaded / action.total * 100));
+      return { ...state, progress: pct };
+    }
+    case "SUCCESS":
+      return { status: "success", progress: 100, blob: action.blob, error: null };
+    case "ERROR":
+      return { ...state, status: "error", error: action.error };
+    case "ABORTED":
+      return { ...state, status: "aborted" };
+  }
+};
+function useDownloadProgress(options) {
+  const { url, externalSignal } = options;
+  const [state, dispatch] = react.useReducer(reducer4, initial4);
+  const acRef = react.useRef(null);
+  const fetchIdRef = react.useRef(0);
+  react.useEffect(() => {
+    const fetchId = ++fetchIdRef.current;
+    const ac = new AbortController();
+    acRef.current = ac;
+    let onExternalAbort = null;
+    if (externalSignal) {
+      onExternalAbort = () => ac.abort();
+      if (externalSignal.aborted) {
+        ac.abort();
+      } else {
+        externalSignal.addEventListener("abort", onExternalAbort);
+      }
+    }
+    dispatch({ type: "START" });
+    void (async () => {
+      try {
+        const res = await fetch(url, { signal: ac.signal });
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`);
+        }
+        const body = res.body;
+        if (!body) {
+          if (fetchId !== fetchIdRef.current) return;
+          dispatch({ type: "SUCCESS", blob: new Blob([]) });
+          return;
+        }
+        const reader = body.getReader();
+        const chunks = [];
+        let loaded = 0;
+        const totalRaw = res.headers?.get?.("content-length");
+        const total = totalRaw ? Number(totalRaw) : 0;
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          if (!value) continue;
+          chunks.push(value);
+          loaded += value.byteLength;
+          if (fetchId !== fetchIdRef.current) return;
+          if (total > 0) {
+            dispatch({ type: "PROGRESS", loaded, total });
+          }
+        }
+        if (fetchId !== fetchIdRef.current) return;
+        const blob = new Blob(chunks);
+        dispatch({ type: "SUCCESS", blob });
+      } catch (err) {
+        if (fetchId !== fetchIdRef.current) return;
+        if (ac.signal.aborted || err instanceof Error && err.name === "AbortError") {
+          dispatch({ type: "ABORTED" });
+          return;
+        }
+        dispatch({
+          type: "ERROR",
+          error: new errors.FileSystemError({
+            code: "NetworkError",
+            retryable: true,
+            message: err instanceof Error ? err.message : "fetch failed"
+          })
+        });
+      } finally {
+        if (onExternalAbort && externalSignal) {
+          externalSignal.removeEventListener("abort", onExternalAbort);
+        }
+      }
+    })();
+    return () => {
+      ac.abort();
+    };
+  }, [url, externalSignal]);
+  const cancel = react.useCallback(() => {
+    acRef.current?.abort();
+    dispatch({ type: "ABORTED" });
+  }, []);
+  return {
+    status: state.status,
+    progress: state.progress,
+    blob: state.blob,
+    error: state.error,
+    cancel
+  };
+}
+var reducer5 = (state, action) => {
+  switch (action.type) {
+    case "SET_VIEW":
+      return { ...state, view: action.view };
+    case "SELECT":
+      return { ...state, selectedId: action.id };
+    case "OPEN_CONTEXT":
+      return { ...state, contextTarget: action.file };
+    case "BEGIN_DRAG":
+      return { ...state, draggingId: action.id, dropTargetId: null };
+    case "SET_DROP_TARGET":
+      return { ...state, dropTargetId: action.id };
+    case "END_DRAG":
+      return { ...state, draggingId: null, dropTargetId: null };
+  }
+};
+var initialState = (initialView) => ({
+  view: initialView,
+  selectedId: null,
+  contextTarget: null,
+  draggingId: null,
+  dropTargetId: null
+});
+function useFileExplorer(options) {
+  const {
+    listFiles,
+    tenantId,
+    parentId,
+    initialView = "list",
+    autoFetch = true,
+    onActivate,
+    onMove
+  } = options;
+  const [state, dispatch] = react.useReducer(reducer5, initialView, initialState);
+  const lastParentId = react.useRef(parentId);
+  react.useEffect(() => {
+    if (lastParentId.current !== parentId) {
+      lastParentId.current = parentId;
+      dispatch({ type: "SELECT", id: null });
+      dispatch({ type: "OPEN_CONTEXT", file: null });
+      dispatch({ type: "END_DRAG" });
+    }
+  }, [parentId]);
+  const { status, files, error, refetch } = useFileBrowser({
+    listFiles,
+    tenantId,
+    parentId,
+    autoFetch
+  });
+  const setView = react.useCallback((view) => {
+    dispatch({ type: "SET_VIEW", view });
+  }, []);
+  const setSelected = react.useCallback((id) => {
+    dispatch({ type: "SELECT", id });
+    if (id && onActivate) {
+      const file = files.find((f) => f.id === id);
+      if (file) onActivate(file);
+    }
+  }, [files, onActivate]);
+  const openContextMenu = react.useCallback((file) => {
+    dispatch({ type: "OPEN_CONTEXT", file });
+  }, []);
+  const beginDrag = react.useCallback((id) => {
+    dispatch({ type: "BEGIN_DRAG", id });
+  }, []);
+  const setDropTarget = react.useCallback((id) => {
+    dispatch({ type: "SET_DROP_TARGET", id });
+  }, []);
+  const commitDrop = react.useCallback((destinationFolderId) => {
+    const destination = files.find((file) => file.id === destinationFolderId);
+    if (state.draggingId && destination?.kind === "folder" && state.draggingId !== destinationFolderId) {
+      void onMove?.({
+        itemIds: [state.draggingId],
+        destinationFolderId
+      });
+    }
+    dispatch({ type: "END_DRAG" });
+  }, [files, onMove, state.draggingId]);
+  const endDrag = react.useCallback(() => {
+    dispatch({ type: "END_DRAG" });
+  }, []);
+  return react.useMemo(
+    () => ({
+      status,
+      files,
+      error,
+      refetch,
+      view: state.view,
+      setView,
+      selectedId: state.selectedId,
+      setSelected,
+      contextTarget: state.contextTarget,
+      openContextMenu,
+      draggingId: state.draggingId,
+      dropTargetId: state.dropTargetId,
+      beginDrag,
+      setDropTarget,
+      commitDrop,
+      endDrag
+    }),
+    [
+      status,
+      files,
+      error,
+      refetch,
+      state.view,
+      state.selectedId,
+      state.contextTarget,
+      state.draggingId,
+      state.dropTargetId,
+      setView,
+      setSelected,
+      openContextMenu,
+      beginDrag,
+      setDropTarget,
+      commitDrop,
+      endDrag
+    ]
+  );
+}
+
+exports.useDownloadProgress = useDownloadProgress;
+exports.useFileActions = useFileActions;
+exports.useFileBrowser = useFileBrowser;
+exports.useFileExplorer = useFileExplorer;
+exports.useFileUrl = useFileUrl;
+exports.useUploader = useUploader;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map