@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.13

package/src/storage/hooks/usePathState.ts

@@ -0,0 +1,94 @@
+import { useCallback, useMemo, useState } from 'react';
+
+/** Strip leading/trailing slashes and collapse repeats — mirrors
+ *  `pyric/storage`'s reference normalization so `usePathState` and
+ *  `useStorageList` always agree on what a path is. */
+export function normalizeStoragePath(path: string): string {
+  return path.split('/').filter(Boolean).join('/');
+}
+
+export interface UsePathStateOptions {
+  /**
+   * Controlled value. When provided, the hook derives everything
+   * from it and navigation calls only fire `onPathChange` — the
+   * owner owns the state (e.g. a router binding `?path=`).
+   */
+  path?: string;
+  /** Fired with the normalized next path on every navigation. Called
+   *  in both modes. */
+  onPathChange?: (path: string) => void;
+  /** Uncontrolled initial value. Default `''` (bucket root). */
+  defaultPath?: string;
+}
+
+export interface UsePathStateResult {
+  /** Current normalized path. `''` is the bucket root. */
+  path: string;
+  /** Path split into segments. `[]` at root. */
+  segments: string[];
+  /** Jump to an absolute path (normalized). */
+  setPath: (path: string) => void;
+  /** Descend into a child folder — accepts a bare name (`'sub'`) or
+   *  an absolute path (`'docs/sub'`, e.g. a prefix's `fullPath`). */
+  enter: (nameOrPath: string) => void;
+  /** Ascend one level. No-op at root. */
+  up: () => void;
+  /**
+   * Jump to the ancestor ending at `segments[index]` — the breadcrumb
+   * click. `navigateToIndex(-1)` (or any negative) is the root.
+   */
+  navigateToIndex: (index: number) => void;
+}
+
+/**
+ * Path navigation state for the storage browser. Controlled when
+ * `path` is provided (the owner re-renders with the next value),
+ * uncontrolled otherwise — standard React value/defaultValue
+ * semantics. All emitted paths are normalized (`normalizeStoragePath`).
+ */
+export function usePathState(
+  options: UsePathStateOptions = {},
+): UsePathStateResult {
+  const { path: controlled, onPathChange, defaultPath = '' } = options;
+  const isControlled = controlled !== undefined;
+  const [internal, setInternal] = useState(() => normalizeStoragePath(defaultPath));
+  const path = isControlled ? normalizeStoragePath(controlled) : internal;
+
+  const setPath = useCallback(
+    (next: string) => {
+      const normalized = normalizeStoragePath(next);
+      if (!isControlled) setInternal(normalized);
+      onPathChange?.(normalized);
+    },
+    [isControlled, onPathChange],
+  );
+
+  const segments = useMemo(
+    () => (path === '' ? [] : path.split('/')),
+    [path],
+  );
+
+  const enter = useCallback(
+    (nameOrPath: string) => {
+      const target = normalizeStoragePath(nameOrPath);
+      // An absolute descendant path (a prefix ref's fullPath) is used
+      // as-is; a bare name appends to the current path.
+      setPath(target.includes('/') || path === '' ? target : `${path}/${target}`);
+    },
+    [path, setPath],
+  );
+
+  const up = useCallback(() => {
+    if (segments.length === 0) return;
+    setPath(segments.slice(0, -1).join('/'));
+  }, [segments, setPath]);
+
+  const navigateToIndex = useCallback(
+    (index: number) => {
+      setPath(index < 0 ? '' : segments.slice(0, index + 1).join('/'));
+    },
+    [segments, setPath],
+  );
+
+  return { path, segments, setPath, enter, up, navigateToIndex };
+}

package/src/storage/hooks/useStorageDelete.ts

@@ -0,0 +1,195 @@
+import { useCallback, useRef, useState } from 'react';
+import {
+  deleteObject as defaultDeleteObject,
+  listAll as defaultListAll,
+  type FirebaseStorage,
+  type StorageReference,
+} from 'pyric/storage';
+import type { StorageSelectionEntry } from './useStorageSelection.js';
+import type { UseStorageListResult } from './useStorageList.js';
+import { useStorageApi, type StorageApi } from '../storageApi.js';
+import { asFolderPlaceholder } from '../folderPlaceholder.js';
+
+export interface StorageDeleteProgress {
+  /** Objects deleted so far in this folder walk. */
+  deletedCount: number;
+  /** True for the final emission. */
+  done: boolean;
+}
+
+/**
+ * Recursive folder delete implementation — the same injection seam
+ * as the Firestore half's `RecursiveDeleteImpl`. Unlike Firestore
+ * (where tree-walking needs sandbox introspection or a Cloud
+ * Function), the public storage surface CAN walk a prefix, so the
+ * package ships {@link createListAllDeleteImpl} as the default;
+ * inject your own for server-driven deletes.
+ */
+export interface StorageRecursiveDeleteImpl {
+  start: (
+    target: StorageReference,
+  ) => AsyncIterableIterator<StorageDeleteProgress>;
+}
+
+/**
+ * The default, `listAll`-driven impl: walks the prefix tree,
+ * `deleteObject`s every item (yielding progress per object), then
+ * sweeps each visited folder's `<path>/` placeholder so emptied
+ * create-folder folders disappear too (`listAll` hides placeholders,
+ * so the walk alone would leave ghost folders). Placeholder sweeps
+ * are best-effort — `deletedCount` counts listed objects only.
+ */
+export function createListAllDeleteImpl(
+  api?: Pick<StorageApi, 'listAll' | 'deleteObject'>,
+): StorageRecursiveDeleteImpl {
+  return {
+    async *start(target: StorageReference) {
+      const operations = api ?? {
+        listAll: defaultListAll,
+        deleteObject: defaultDeleteObject,
+      };
+      let deletedCount = 0;
+      const stack: StorageReference[] = [target];
+      const visited: StorageReference[] = [];
+      while (stack.length > 0) {
+        const folder = stack.pop()!;
+        visited.push(folder);
+        const result = await operations.listAll(folder);
+        stack.push(...result.prefixes);
+        for (const item of result.items) {
+          await operations.deleteObject(item);
+          deletedCount++;
+          yield { deletedCount, done: false };
+        }
+      }
+      for (const folder of visited) {
+        try {
+          await operations.deleteObject(asFolderPlaceholder(folder));
+        } catch {
+          // Best-effort: a strict backend may reject the structural
+          // placeholder or throw not-found. Neither should fail the
+          // recursive delete that already succeeded.
+        }
+      }
+      yield { deletedCount, done: true };
+    },
+  };
+}
+
+/** One entry's failure in a bulk run. `error` is the typed
+ *  `StorageError` (`.code` e.g. `storage/unauthorized`). */
+export interface StorageDeleteFailure {
+  fullPath: string;
+  error: Error;
+}
+
+export interface StorageDeleteOutcome {
+  /** fullPaths of entries fully deleted. */
+  deleted: string[];
+  failed: StorageDeleteFailure[];
+}
+
+export interface UseStorageDeleteOptions {
+  /** Folder-walk implementation. Default {@link createListAllDeleteImpl}. */
+  impl?: StorageRecursiveDeleteImpl;
+  /**
+   * Optimistic seam from `useStorageList`: entries vanish from the
+   * local list immediately and roll back (object → item, folder →
+   * trailing-slash prefix insert) on failure.
+   */
+  list?: Pick<UseStorageListResult, 'insertItem' | 'removeItem'>;
+}
+
+export interface UseStorageDeleteResult {
+  /**
+   * Delete a mixed object/folder selection (objects via
+   * `deleteObject`, folders via the recursive impl), sequentially in
+   * selection order. Resolves with the outcome and never rejects —
+   * per-entry failures land in `outcome.failed` (and `error` keeps
+   * the first one for simple renders).
+   */
+  deleteEntries: (
+    entries: StorageSelectionEntry[],
+  ) => Promise<StorageDeleteOutcome>;
+  /** Objects deleted in the current/last run (folder walks included). */
+  progress: number;
+  isRunning: boolean;
+  /** First failure of the current/last run. Cleared on the next call. */
+  error: Error | undefined;
+}
+
+/**
+ * Drive bulk + recursive deletes from a React component — the
+ * storage counterpart of `useRecursiveDelete` (same progress /
+ * isRunning / error shape, same stale-run generation token), bulk
+ * because storage selections are flat multi-row affairs.
+ */
+export function useStorageDelete(
+  storage: FirebaseStorage | null | undefined,
+  options: UseStorageDeleteOptions = {},
+): UseStorageDeleteResult {
+  const api = useStorageApi();
+  const [progress, setProgress] = useState(0);
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const generationRef = useRef(0);
+  // Latest-value ref so `deleteEntries` stays stable across option
+  // identity changes (house pattern).
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const deleteEntries = useCallback(
+    async (entries: StorageSelectionEntry[]): Promise<StorageDeleteOutcome> => {
+      const myGen = ++generationRef.current;
+      setProgress(0);
+      setError(undefined);
+      const outcome: StorageDeleteOutcome = { deleted: [], failed: [] };
+      if (storage == null || entries.length === 0) return outcome;
+      setIsRunning(true);
+      const impl = optionsRef.current.impl ?? createListAllDeleteImpl(api);
+      let count = 0;
+      try {
+        for (const entry of entries) {
+          // Optimistic removal — the row vanishes immediately.
+          optionsRef.current.list?.removeItem(entry.fullPath);
+          try {
+            if (entry.kind === 'object') {
+              await api.deleteObject(api.ref(storage, entry.fullPath));
+              count++;
+            } else {
+              for await (const evt of impl.start(api.ref(storage, entry.fullPath))) {
+                if (myGen !== generationRef.current) return outcome;
+                // The impl reports counts local to its walk; add the
+                // objects already deleted by earlier entries.
+                setProgress(count + evt.deletedCount);
+                if (evt.done) {
+                  count += evt.deletedCount;
+                  break;
+                }
+              }
+            }
+            outcome.deleted.push(entry.fullPath);
+            if (myGen === generationRef.current) setProgress(count);
+          } catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            outcome.failed.push({ fullPath: entry.fullPath, error: err });
+            // Roll the optimistic removal back: objects re-insert as
+            // items, folders as trailing-slash prefixes.
+            optionsRef.current.list?.insertItem(
+              entry.kind === 'folder' ? `${entry.fullPath}/` : entry.fullPath,
+            );
+            if (myGen === generationRef.current && outcome.failed.length === 1) {
+              setError(err);
+            }
+          }
+        }
+        return outcome;
+      } finally {
+        if (myGen === generationRef.current) setIsRunning(false);
+      }
+    },
+    [api, storage],
+  );
+
+  return { deleteEntries, progress, isRunning, error };
+}

package/src/storage/hooks/useStorageList.ts

@@ -0,0 +1,261 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type {
+  FirebaseStorage,
+  StorageReference,
+} from 'pyric/storage';
+import { useStorageApi } from '../storageApi.js';
+
+export type StorageListStatus = 'idle' | 'loading' | 'success' | 'error';
+
+/**
+ * One row of the merged folder/object model, the prefix→folder
+ * synthesis ported (as an idea, not code) from the emulator UI's
+ * `useStorageFiles`: `listAll`'s `prefixes` become `kind: 'folder'`
+ * rows, its `items` become `kind: 'object'` rows, folders first.
+ */
+export interface StorageListEntry {
+  kind: 'folder' | 'object';
+  /** Last path segment, display name. */
+  name: string;
+  /** Bucket-rooted path (no trailing slash, even for folders). */
+  fullPath: string;
+  ref: StorageReference;
+}
+
+export interface UseStorageListResult {
+  /** `'idle'` only when `storage` is null/undefined. */
+  status: StorageListStatus;
+  /** Direct child objects under `path`. Sorted by `fullPath`. */
+  items: StorageReference[];
+  /** Synthetic folder prefixes under `path`. Sorted by `fullPath`. */
+  prefixes: StorageReference[];
+  /** Folders-first merged row model. Derived from `prefixes` + `items`. */
+  entries: StorageListEntry[];
+  /**
+   * `StorageError` (with a typed `storage/<code>` on `.code`) from the
+   * sandbox. A denied list is `error.code === 'storage/unauthorized'`
+   * (ST-B2).
+   */
+  error: Error | undefined;
+  /** Re-run `listAll` for the current path. */
+  refresh: () => void;
+  /**
+   * Optimistic seam (consumed by M3 upload / M6 bulk ops, exposed
+   * now so those hooks layer on without reshaping this one). Inserts
+   * `fullPath` into the local list immediately, applying the same
+   * prefix→folder synthesis `listAll` would: a direct child becomes
+   * an item, a deeper descendant surfaces as its first-segment
+   * folder. A trailing slash declares a folder (the GCS placeholder
+   * convention `useObjectUpload.createFolder` writes): a direct
+   * trailing-slash child inserts a prefix, not an item. No-op for
+   * paths outside the listed path, duplicates, or when `status` is
+   * `'idle'`. What each call ACTUALLY inserted is recorded (keyed by
+   * the given `fullPath`) so `removeItem` can reverse it precisely.
+   * Rollback = `removeItem` or `refresh`.
+   */
+  insertItem: (fullPath: string) => void;
+  /**
+   * Optimistic counterpart. When `fullPath` was previously given to
+   * `insertItem`, this reverses EXACTLY what that call inserted: a
+   * deep upload that synthesized a first-segment folder row removes
+   * that folder row, and an insert that was a no-op (the row already
+   * existed — e.g. a real, listed folder) removes NOTHING, so a
+   * failed upload can never delete server-truth rows. For paths never
+   * seen by `insertItem` it removes the matching item/folder row
+   * directly (the optimistic-delete use). Rollback = `refresh`.
+   */
+  removeItem: (fullPath: string) => void;
+}
+
+interface ListState {
+  status: StorageListStatus;
+  items: StorageReference[];
+  prefixes: StorageReference[];
+  error: Error | undefined;
+}
+
+/** Strip leading/trailing slashes so `'a/b/'`, `'/a/b'`, `'a/b'` agree. */
+function normalizePath(path: string): string {
+  return path.replace(/^\/+|\/+$/g, '');
+}
+
+function byFullPath(a: StorageReference, b: StorageReference): number {
+  return a.fullPath < b.fullPath ? -1 : a.fullPath > b.fullPath ? 1 : 0;
+}
+
+function insertSorted(
+  list: StorageReference[],
+  next: StorageReference,
+): StorageReference[] {
+  if (list.some((r) => r.fullPath === next.fullPath)) return list;
+  return [...list, next].sort(byFullPath);
+}
+
+/**
+ * List the objects + synthetic folders directly under `path` :
+ * `listAll` over the package's sandbox Storage handle. Read-via-get,
+ * not realtime: the list updates on `refresh`, path change, or the
+ * optimistic seam. Pass `''` (or the result of `usePathState`) for
+ * the bucket root.
+ *
+ * `listAll` has no pagination; a very large prefix arrives as one flat
+ * result (virtualize the rendering, which `<ObjectBrowser>` does).
+ */
+export function useStorageList(
+  storage: FirebaseStorage | null | undefined,
+  path: string,
+): UseStorageListResult {
+  // Injected: in-process `pyric/storage` by default, or the SharedWorker client
+  // bundle in Studio served mode (via StorageApiProvider).
+  const { listAll, ref: refFn } = useStorageApi();
+  const normalized = normalizePath(path);
+  const [state, setState] = useState<ListState>(() => ({
+    status: storage == null ? 'idle' : 'loading',
+    items: [],
+    prefixes: [],
+    error: undefined,
+  }));
+  const [tick, setTick] = useState(0);
+
+  // What each `insertItem(fullPath)` call ACTUALLY inserted, keyed by the
+  // normalized argument: the inserted row's fullPath, or null when the call
+  // was a no-op (row already present). `removeItem` consults this to reverse
+  // precisely; a fresh listing (server truth) clears the ledger.
+  const optimisticInserts = useRef(new Map<string, string | null>());
+
+  useEffect(() => {
+    optimisticInserts.current.clear();
+    if (storage == null) {
+      setState({ status: 'idle', items: [], prefixes: [], error: undefined });
+      return;
+    }
+    let cancelled = false;
+    setState({ status: 'loading', items: [], prefixes: [], error: undefined });
+    listAll(refFn(storage, normalized))
+      .then((result) => {
+        if (cancelled) return;
+        setState({
+          status: 'success',
+          // Defensive copy + sort pins the invariant the optimistic seam
+          // relies on even if the backing implementation changes.
+          items: [...result.items].sort(byFullPath),
+          prefixes: [...result.prefixes].sort(byFullPath),
+          error: undefined,
+        });
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setState({
+          status: 'error',
+          items: [],
+          prefixes: [],
+          error: e instanceof Error ? e : new Error(String(e)),
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [storage, normalized, tick]);
+
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  const insertItem = useCallback(
+    (fullPath: string) => {
+      if (storage == null) return;
+      // Trailing slash = folder declaration (a `<path>/` placeholder
+      // object surfaces as a prefix, never an item, same synthesis
+      // `listAll` applies).
+      const isFolder = fullPath.endsWith('/');
+      const target = normalizePath(fullPath);
+      const scanPrefix = normalized === '' ? '' : `${normalized}/`;
+      if (!target.startsWith(scanPrefix) || target === normalized) return;
+      const relative = target.slice(scanPrefix.length);
+      const slashIdx = relative.indexOf('/');
+      setState((prev) => {
+        if (prev.status === 'idle') return prev;
+        // Record what this call really adds (null = no-op) so removeItem can
+        // reverse it precisely. Idempotent under StrictMode's double-invoke:
+        // the same prev yields the same record.
+        if (slashIdx === -1) {
+          if (isFolder) {
+            // Direct child folder.
+            optimisticInserts.current.set(
+              target,
+              prev.prefixes.some((r) => r.fullPath === target) ? null : target,
+            );
+            return {
+              ...prev,
+              prefixes: insertSorted(prev.prefixes, refFn(storage, target)),
+            };
+          }
+          // Direct child object.
+          optimisticInserts.current.set(
+            target,
+            prev.items.some((r) => r.fullPath === target) ? null : target,
+          );
+          return { ...prev, items: insertSorted(prev.items, refFn(storage, target)) };
+        }
+        // Deeper descendant, surface its first segment as a folder,
+        // exactly like listAll's synthesis.
+        const folderPath = `${scanPrefix}${relative.slice(0, slashIdx)}`;
+        optimisticInserts.current.set(
+          target,
+          prev.prefixes.some((r) => r.fullPath === folderPath) ? null : folderPath,
+        );
+        return {
+          ...prev,
+          prefixes: insertSorted(prev.prefixes, refFn(storage, folderPath)),
+        };
+      });
+    },
+    [storage, normalized],
+  );
+
+  const removeItem = useCallback((fullPath: string) => {
+    const target = normalizePath(fullPath);
+    const record = optimisticInserts.current.get(target);
+    optimisticInserts.current.delete(target);
+    // This path was optimistically inserted and the insert added nothing
+    // (the row pre-existed) — there is nothing of ours to remove, and
+    // removing by path would delete a server-truth row.
+    if (record === null) return;
+    // Reverse the exact row the insert created (a deep upload's synthesized
+    // first-segment folder differs from the upload's own fullPath); fall
+    // back to the path itself for plain optimistic deletes.
+    const rowPath = record ?? target;
+    setState((prev) => ({
+      ...prev,
+      items: prev.items.filter((r) => r.fullPath !== rowPath),
+      prefixes: prev.prefixes.filter((r) => r.fullPath !== rowPath),
+    }));
+  }, []);
+
+  const entries = useMemo<StorageListEntry[]>(
+    () => [
+      ...state.prefixes.map((p) => ({
+        kind: 'folder' as const,
+        name: p.name,
+        fullPath: p.fullPath,
+        ref: p,
+      })),
+      ...state.items.map((i) => ({
+        kind: 'object' as const,
+        name: i.name,
+        fullPath: i.fullPath,
+        ref: i,
+      })),
+    ],
+    [state.prefixes, state.items],
+  );
+
+  return {
+    status: state.status,
+    items: state.items,
+    prefixes: state.prefixes,
+    entries,
+    error: state.error,
+    refresh,
+    insertItem,
+    removeItem,
+  };
+}