@pyric/ui 0.1.0-alpha.10 → 0.1.0-alpha.12

package/src/storage/hooks/index.ts

@@ -0,0 +1,59 @@
+export {
+  useStorageList,
+  type StorageListStatus,
+  type StorageListEntry,
+  type UseStorageListResult,
+} from './useStorageList.js';
+export {
+  usePathState,
+  normalizeStoragePath,
+  type UsePathStateOptions,
+  type UsePathStateResult,
+} from './usePathState.js';
+export {
+  useStorageObject,
+  type StorageObjectStatus,
+  type UseStorageObjectResult,
+} from './useStorageObject.js';
+export {
+  useMetadataEditor,
+  metadataEditorReducer,
+  initMetadataEditorState,
+  type CustomMetadataEntry,
+  type MetadataEditorState,
+  type MetadataEditorAction,
+  type UseMetadataEditorOptions,
+  type UseMetadataEditorResult,
+} from './useMetadataEditor.js';
+export {
+  useStorageSelection,
+  type StorageSelectionEntry,
+  type UseStorageSelectionResult,
+} from './useStorageSelection.js';
+export {
+  useStorageDelete,
+  createListAllDeleteImpl,
+  type StorageDeleteProgress,
+  type StorageRecursiveDeleteImpl,
+  type StorageDeleteFailure,
+  type StorageDeleteOutcome,
+  type UseStorageDeleteOptions,
+  type UseStorageDeleteResult,
+} from './useStorageDelete.js';
+export {
+  useStorageRulesGate,
+  type StorageRulesGateStatus,
+  type StorageRulesSource,
+  type StorageGateVerdict,
+  type UseStorageRulesGateOptions,
+  type UseStorageRulesGateResult,
+} from './useStorageRulesGate.js';
+export {
+  useObjectUpload,
+  type UploadTask,
+  type UploadTaskStatus,
+  type UploadEntry,
+  type UploadInput,
+  type UseObjectUploadOptions,
+  type UseObjectUploadResult,
+} from './useObjectUpload.js';

package/src/storage/hooks/useMetadataEditor.ts

@@ -0,0 +1,329 @@
+import { useCallback, useMemo, useReducer, useRef, useState } from 'react';
+import {
+  ref as refFn,
+  updateMetadata,
+  type FirebaseStorage,
+  type FullMetadata,
+  type SettableMetadata,
+} from 'pyric/storage';
+import { normalizeStoragePath } from './usePathState.js';
+
+/** One `customMetadata` row. `id` is a stable render key — keys are
+ *  user-editable, so they can't key the rows themselves. */
+export interface CustomMetadataEntry {
+  id: string;
+  key: string;
+  value: string;
+  /** Validation error (`'Key is required'` / `'Duplicate key'`). */
+  error?: string;
+}
+
+interface MetadataDraft {
+  contentType: string;
+  cacheControl: string;
+  custom: CustomMetadataEntry[];
+}
+
+export interface MetadataEditorState {
+  draft: MetadataDraft;
+  /** Snapshot for `isDirty` / `reset` — same reference-compare
+   *  semantics as the document editor's `tree !== initial`. */
+  initial: MetadataDraft;
+  errorCount: number;
+}
+
+export type MetadataEditorAction =
+  | { type: 'setContentType'; value: string }
+  | { type: 'setCacheControl'; value: string }
+  | { type: 'setCustomKey'; id: string; key: string }
+  | { type: 'setCustomValue'; id: string; value: string }
+  | { type: 'addCustomEntry'; key?: string; value?: string }
+  | { type: 'removeCustomEntry'; id: string }
+  | { type: 'reset' }
+  /** Internal — a successful save makes the draft the new baseline. */
+  | { type: 'commit' };
+
+/** Re-validate the k/v rows: empty keys and duplicate keys error. */
+function validateCustom(custom: CustomMetadataEntry[]): {
+  custom: CustomMetadataEntry[];
+  errorCount: number;
+} {
+  const counts = new Map<string, number>();
+  for (const entry of custom) {
+    counts.set(entry.key, (counts.get(entry.key) ?? 0) + 1);
+  }
+  let errorCount = 0;
+  const next = custom.map((entry) => {
+    let error: string | undefined;
+    if (entry.key.trim() === '') error = 'Key is required';
+    else if ((counts.get(entry.key) ?? 0) > 1) error = 'Duplicate key';
+    if (error) errorCount++;
+    if (error === entry.error) return entry;
+    return { ...entry, error };
+  });
+  return { custom: next, errorCount };
+}
+
+function applyDraft(
+  state: MetadataEditorState,
+  mutate: (draft: MetadataDraft) => MetadataDraft,
+): MetadataEditorState {
+  const mutated = mutate(state.draft);
+  const { custom, errorCount } = validateCustom(mutated.custom);
+  return { ...state, draft: { ...mutated, custom }, errorCount };
+}
+
+/** Pure reducer — exported (with {@link initMetadataEditorState}) so
+ *  the edit state is testable without React, mirroring the document
+ *  editor's reducer/hook split. */
+export function metadataEditorReducer(
+  state: MetadataEditorState,
+  action: MetadataEditorAction,
+): MetadataEditorState {
+  switch (action.type) {
+    case 'setContentType':
+      return applyDraft(state, (d) => ({ ...d, contentType: action.value }));
+    case 'setCacheControl':
+      return applyDraft(state, (d) => ({ ...d, cacheControl: action.value }));
+    case 'setCustomKey':
+      return applyDraft(state, (d) => ({
+        ...d,
+        custom: d.custom.map((e) => (e.id === action.id ? { ...e, key: action.key } : e)),
+      }));
+    case 'setCustomValue':
+      return applyDraft(state, (d) => ({
+        ...d,
+        custom: d.custom.map((e) =>
+          e.id === action.id ? { ...e, value: action.value } : e,
+        ),
+      }));
+    case 'addCustomEntry':
+      return applyDraft(state, (d) => ({
+        ...d,
+        custom: [
+          ...d.custom,
+          { id: crypto.randomUUID(), key: action.key ?? '', value: action.value ?? '' },
+        ],
+      }));
+    case 'removeCustomEntry':
+      return applyDraft(state, (d) => ({
+        ...d,
+        custom: d.custom.filter((e) => e.id !== action.id),
+      }));
+    case 'reset':
+      return {
+        draft: state.initial,
+        initial: state.initial,
+        errorCount: validateCustom(state.initial.custom).errorCount,
+      };
+    case 'commit':
+      return { ...state, initial: state.draft };
+  }
+}
+
+/** Build the edit state from the metadata a `getMetadata` /
+ *  `useStorageObject` read returned. */
+export function initMetadataEditorState(
+  initial: SettableMetadata | undefined,
+): MetadataEditorState {
+  const draft: MetadataDraft = {
+    contentType: initial?.contentType ?? '',
+    cacheControl: initial?.cacheControl ?? '',
+    custom: Object.entries(initial?.customMetadata ?? {}).map(([key, value]) => ({
+      id: crypto.randomUUID(),
+      key,
+      value,
+    })),
+  };
+  const { custom, errorCount } = validateCustom(draft.custom);
+  // One shared object: `isDirty` is `draft !== initial` by reference.
+  const validated: MetadataDraft = { ...draft, custom };
+  return { draft: validated, initial: validated, errorCount };
+}
+
+export interface UseMetadataEditorOptions {
+  /** The metadata being edited — the same shape `useStorageObject`'s
+   *  `metadata` carries. Read once on mount (the editor is a
+   *  stateful workspace, like the document editor); `reset()` +
+   *  remount to re-initialize. */
+  initial?: SettableMetadata;
+}
+
+export interface UseMetadataEditorResult {
+  contentType: string;
+  cacheControl: string;
+  custom: CustomMetadataEntry[];
+  /** Convenience: `errorCount === 0`. */
+  isValid: boolean;
+  /** `true` once any modifying action fired since the last
+   *  `reset`/successful `save`. Reference-compare semantics — manual
+   *  re-entry of the original values does NOT clear it. */
+  isDirty: boolean;
+  errorCount: number;
+  /** Raw dispatch — prefer the named helpers. */
+  dispatch: (action: MetadataEditorAction) => void;
+  setContentType: (value: string) => void;
+  setCacheControl: (value: string) => void;
+  setCustomKey: (id: string, key: string) => void;
+  setCustomValue: (id: string, value: string) => void;
+  addCustomEntry: (key?: string, value?: string) => void;
+  removeCustomEntry: (id: string) => void;
+  /** Restore the initial values. Clears `isDirty`. */
+  reset: () => void;
+  /**
+   * Serialize the draft to an `updateMetadata` patch. Empty
+   * `contentType`/`cacheControl` become `undefined` — which LEAVES
+   * the previous value (the sandbox doesn't model null-clears; see
+   * `pyric/storage`'s `updateMetadata` doc). `customMetadata` is
+   * always included and replaces wholesale, so row removal works.
+   */
+  toPatch: () => SettableMetadata;
+  /**
+   * `updateMetadata(ref(storage, path), toPatch())`. Errors surface
+   * via `saveError` (typed `StorageError`), not throws — resolves
+   * `undefined` on failure or when the draft is invalid. On success
+   * the draft becomes the new baseline (`isDirty` clears) and the
+   * fresh `FullMetadata` is returned.
+   */
+  save: () => Promise<FullMetadata | undefined>;
+  isSaving: boolean;
+  saveError: Error | undefined;
+}
+
+/**
+ * Headless metadata editor — the `useDocumentEditor` reducer pattern
+ * over `updateMetadata`: a pure reducer owns the draft (contentType,
+ * cacheControl, customMetadata k/v rows with stable ids +
+ * empty/duplicate-key validation); the hook adds named dispatch
+ * helpers and the save half.
+ */
+export function useMetadataEditor(
+  storage: FirebaseStorage | null | undefined,
+  path: string | null | undefined,
+  options: UseMetadataEditorOptions = {},
+): UseMetadataEditorResult {
+  // Computed once — the reducer owns the live draft from here on
+  // (same `useRef` seed as `useDocumentEditor`).
+  const initialRef = useRef<MetadataEditorState | null>(null);
+  if (initialRef.current == null) {
+    initialRef.current = initMetadataEditorState(options.initial);
+  }
+  const [state, dispatch] = useReducer(metadataEditorReducer, initialRef.current);
+  const [isSaving, setIsSaving] = useState(false);
+  const [saveError, setSaveError] = useState<Error | undefined>(undefined);
+  // Stale-run protection for overlapping saves (generation token,
+  // house style).
+  const generationRef = useRef(0);
+
+  const setContentType = useCallback(
+    (value: string) => dispatch({ type: 'setContentType', value }),
+    [],
+  );
+  const setCacheControl = useCallback(
+    (value: string) => dispatch({ type: 'setCacheControl', value }),
+    [],
+  );
+  const setCustomKey = useCallback(
+    (id: string, key: string) => dispatch({ type: 'setCustomKey', id, key }),
+    [],
+  );
+  const setCustomValue = useCallback(
+    (id: string, value: string) => dispatch({ type: 'setCustomValue', id, value }),
+    [],
+  );
+  const addCustomEntry = useCallback(
+    (key?: string, value?: string) => dispatch({ type: 'addCustomEntry', key, value }),
+    [],
+  );
+  const removeCustomEntry = useCallback(
+    (id: string) => dispatch({ type: 'removeCustomEntry', id }),
+    [],
+  );
+  const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+
+  const { draft, initial, errorCount } = state;
+
+  const toPatch = useCallback((): SettableMetadata => {
+    return {
+      contentType: draft.contentType.trim() === '' ? undefined : draft.contentType,
+      cacheControl: draft.cacheControl.trim() === '' ? undefined : draft.cacheControl,
+      customMetadata: Object.fromEntries(
+        draft.custom.filter((e) => e.key.trim() !== '').map((e) => [e.key, e.value]),
+      ),
+    };
+  }, [draft]);
+
+  const save = useCallback(async (): Promise<FullMetadata | undefined> => {
+    const myGen = ++generationRef.current;
+    if (storage == null || path == null) {
+      setSaveError(new Error('useMetadataEditor: storage or path is null'));
+      return undefined;
+    }
+    if (errorCount > 0) {
+      setSaveError(new Error('useMetadataEditor: draft has validation errors'));
+      return undefined;
+    }
+    setSaveError(undefined);
+    setIsSaving(true);
+    try {
+      const next = await updateMetadata(
+        refFn(storage, normalizeStoragePath(path)),
+        toPatch(),
+      );
+      if (myGen === generationRef.current) {
+        dispatch({ type: 'commit' });
+      }
+      return next;
+    } catch (e) {
+      if (myGen === generationRef.current) {
+        setSaveError(e instanceof Error ? e : new Error(String(e)));
+      }
+      return undefined;
+    } finally {
+      if (myGen === generationRef.current) setIsSaving(false);
+    }
+  }, [storage, path, errorCount, toPatch]);
+
+  const isDirty = draft !== initial;
+  const isValid = errorCount === 0;
+
+  return useMemo<UseMetadataEditorResult>(
+    () => ({
+      contentType: draft.contentType,
+      cacheControl: draft.cacheControl,
+      custom: draft.custom,
+      isValid,
+      isDirty,
+      errorCount,
+      dispatch,
+      setContentType,
+      setCacheControl,
+      setCustomKey,
+      setCustomValue,
+      addCustomEntry,
+      removeCustomEntry,
+      reset,
+      toPatch,
+      save,
+      isSaving,
+      saveError,
+    }),
+    [
+      draft,
+      isValid,
+      isDirty,
+      errorCount,
+      setContentType,
+      setCacheControl,
+      setCustomKey,
+      setCustomValue,
+      addCustomEntry,
+      removeCustomEntry,
+      reset,
+      toPatch,
+      save,
+      isSaving,
+      saveError,
+    ],
+  );
+}

package/src/storage/hooks/useObjectUpload.ts

@@ -0,0 +1,262 @@
+import { useCallback, useRef, useState } from 'react';
+import type {
+  FirebaseStorage,
+  FullMetadata,
+  SettableMetadata,
+} from 'pyric/storage';
+import { folderPlaceholderRef } from '../folderPlaceholder.js';
+import { useStorageApi } from '../storageApi.js';
+import { normalizeStoragePath } from './usePathState.js';
+import type { UseStorageListResult } from './useStorageList.js';
+
+export type UploadTaskStatus = 'running' | 'success' | 'error';
+
+/**
+ * One file's upload, TASK-SHAPED for resumable forward-compat: the
+ * byte counters and the `onProgress` callback are in the type NOW so
+ * a future `uploadBytesResumable`-backed implementation emits real
+ * intermediate snapshots without a breaking change. Today
+ * (`pyric/storage` has no resumable uploads — COMPAT) a task
+ * completes in one tick: `onProgress` fires once at 0 bytes and once
+ * at `totalBytes`.
+ */
+export interface UploadTask {
+  /** Stable id — key task rows on this, not on `fullPath` (two
+   *  uploads can target the same path). */
+  id: string;
+  /** Bucket-rooted destination path. */
+  fullPath: string;
+  status: UploadTaskStatus;
+  bytesTransferred: number;
+  totalBytes: number;
+  /** Populated on `'success'`. */
+  metadata?: FullMetadata;
+  /** Populated on `'error'` — a typed `StorageError` from the
+   *  sandbox (`.code` is `storage/<code>`, e.g.
+   *  `storage/unauthorized` for a rules-denied write). */
+  error?: Error;
+}
+
+/** Explicit-path upload input. `path` is relative to the hook's
+ *  `path` option (the destination folder). */
+export interface UploadEntry {
+  path: string;
+  data: Blob | Uint8Array | ArrayBuffer;
+  metadata?: SettableMetadata;
+}
+
+/**
+ * `upload()` accepts plain `File`s (destination = the file's
+ * `webkitRelativePath` when present — folder drops keep their
+ * structure — else its `name`) or explicit {@link UploadEntry}s.
+ */
+export type UploadInput = File | UploadEntry;
+
+export interface UseObjectUploadOptions {
+  /** Destination folder, bucket-rooted. Default `''` (root). Wire to
+   *  `usePathState().path` so uploads land in the browsed folder. */
+  path?: string;
+  /**
+   * Optimistic seam from `useStorageList`: each upload inserts its
+   * path immediately and rolls back via `removeItem` on failure.
+   * Caveat: rolling back an upload that was OVERWRITING an existing
+   * object drops that object's row locally (the seam can't tell an
+   * optimistic row from a listed one) — `refresh()` restores server
+   * truth.
+   */
+  list?: Pick<UseStorageListResult, 'insertItem' | 'removeItem'>;
+  /** Task-shaped progress callback (see {@link UploadTask}). */
+  onProgress?: (task: UploadTask) => void;
+  /** Fired once per task reaching `'success'`. */
+  onComplete?: (task: UploadTask) => void;
+  /** Fired once per task reaching `'error'`. */
+  onError?: (task: UploadTask) => void;
+}
+
+export interface UseObjectUploadResult {
+  /** Every task started by this hook instance, oldest first. */
+  tasks: UploadTask[];
+  /** `true` while any task is `'running'`. */
+  isUploading: boolean;
+  /**
+   * Upload one or many files. Tasks run concurrently; the promise
+   * resolves with the settled tasks once ALL finish and never
+   * rejects — per-file failures land on `task.error` (and
+   * `onError`), so one bad file doesn't mask the others.
+   */
+  upload: (input: UploadInput | UploadInput[]) => Promise<UploadTask[]>;
+  /**
+   * Create an empty folder under the hook's `path`: writes the GCS
+   * placeholder convention — a zero-byte object named `<path>/`
+   * (trailing slash). `listAll` hides the placeholder from `items`
+   * at every level (it only surfaces as a prefix), so the folder
+   * appears in the browser with no phantom file inside.
+   *
+   * `ref()` normalizes the trailing slash away, so the placeholder is
+   * written through a structural value-object reference the sandbox
+   * accepts. Throws the underlying error after rolling back the
+   * optimistic prefix insert.
+   *
+   * ALTERNATIVE: when the store must stay free of placeholder
+   * objects (Pyric Studio's choice), use the client-side
+   * pending-prefix mechanism instead — see `pendingPrefixes.ts`
+   * for the reducer and the recorded tradeoff.
+   */
+  createFolder: (name: string) => Promise<void>;
+  /** Drop settled (`success`/`error`) tasks from `tasks`. */
+  clearCompleted: () => void;
+}
+
+function joinPath(base: string, child: string): string {
+  if (base === '') return child;
+  if (child === '') return base;
+  return `${base}/${child}`;
+}
+
+function sizeOf(data: Blob | Uint8Array | ArrayBuffer): number {
+  if (data instanceof Blob) return data.size;
+  return data.byteLength;
+}
+
+function toEntry(input: UploadInput): UploadEntry {
+  if (input instanceof Blob) {
+    // File (the only Blob subtype `UploadInput` admits). Folder
+    // drops carry `webkitRelativePath`; plain picks carry `name`.
+    const file = input as File;
+    const rel = (file as { webkitRelativePath?: string }).webkitRelativePath;
+    return { path: rel || file.name, data: file };
+  }
+  return input;
+}
+
+/**
+ * Multi-file upload over the package's single Storage handle prop.
+ * Headless: returns task state; render it however you like (the
+ * `<UploadDropzone>` component is one producer of `upload()` calls).
+ *
+ * Optimistic-with-rollback: with the `list` seam wired, each upload's
+ * row appears in `useStorageList` immediately and disappears again if
+ * the write fails (typed `StorageError` on `task.error`).
+ */
+export function useObjectUpload(
+  storage: FirebaseStorage | null | undefined,
+  options: UseObjectUploadOptions = {},
+): UseObjectUploadResult {
+  // Injected backend (in-process `pyric/storage` by default, the
+  // SharedWorker client bundle in Studio served mode) — uploads follow
+  // the same seam the browse hooks read through. The worker leg caps a
+  // payload at 8 MiB (base64 `storage.putBytes`); in-process writes are
+  // uncapped. An over-cap file fails as a normal per-file task error.
+  const { ref: refFn, uploadBytes } = useStorageApi();
+  const base = normalizeStoragePath(options.path ?? '');
+  const [tasks, setTasks] = useState<UploadTask[]>([]);
+
+  // Latest-value refs so `upload`/`createFolder` stay referentially
+  // stable across option changes (same pattern as the house hooks'
+  // generation tokens — the callbacks read current options at call
+  // time).
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const patchTask = useCallback((next: UploadTask) => {
+    setTasks((prev) => prev.map((t) => (t.id === next.id ? next : t)));
+  }, []);
+
+  const upload = useCallback(
+    async (input: UploadInput | UploadInput[]): Promise<UploadTask[]> => {
+      if (storage == null) {
+        throw new Error('useObjectUpload: storage handle is null');
+      }
+      const inputs = Array.isArray(input) ? input : [input];
+      const started = inputs.map((raw) => {
+        const entry = toEntry(raw);
+        const task: UploadTask = {
+          id: crypto.randomUUID(),
+          fullPath: joinPath(base, normalizeStoragePath(entry.path)),
+          status: 'running',
+          bytesTransferred: 0,
+          totalBytes: sizeOf(entry.data),
+        };
+        return { task, entry };
+      });
+
+      setTasks((prev) => [...prev, ...started.map((s) => s.task)]);
+      for (const { task } of started) {
+        optionsRef.current.list?.insertItem(task.fullPath);
+        optionsRef.current.onProgress?.(task);
+      }
+
+      return Promise.all(
+        started.map(async ({ task, entry }) => {
+          try {
+            const result = await uploadBytes(
+              refFn(storage, task.fullPath),
+              entry.data,
+              entry.metadata,
+            );
+            const done: UploadTask = {
+              ...task,
+              status: 'success',
+              bytesTransferred: task.totalBytes,
+              metadata: result.metadata,
+            };
+            patchTask(done);
+            optionsRef.current.onProgress?.(done);
+            optionsRef.current.onComplete?.(done);
+            return done;
+          } catch (e) {
+            const failed: UploadTask = {
+              ...task,
+              status: 'error',
+              error: e instanceof Error ? e : new Error(String(e)),
+            };
+            // Roll the optimistic row back before surfacing.
+            optionsRef.current.list?.removeItem(task.fullPath);
+            patchTask(failed);
+            optionsRef.current.onError?.(failed);
+            return failed;
+          }
+        }),
+      );
+    },
+    [storage, base, patchTask, refFn, uploadBytes],
+  );
+
+  const createFolder = useCallback(
+    async (name: string): Promise<void> => {
+      if (storage == null) {
+        throw new Error('useObjectUpload: storage handle is null');
+      }
+      const folderPath = joinPath(base, normalizeStoragePath(name));
+      if (folderPath === '') {
+        throw new Error('createFolder: folder name is empty');
+      }
+      // Trailing slash → the seam inserts a prefix, not an item.
+      optionsRef.current.list?.insertItem(`${folderPath}/`);
+      try {
+        await uploadBytes(
+          folderPlaceholderRef(storage, folderPath),
+          new Blob([]),
+          // Matches the emulator UI's placeholder content type.
+          { contentType: 'text/plain' },
+        );
+      } catch (e) {
+        optionsRef.current.list?.removeItem(folderPath);
+        throw e;
+      }
+    },
+    [storage, base, uploadBytes],
+  );
+
+  const clearCompleted = useCallback(() => {
+    setTasks((prev) => prev.filter((t) => t.status === 'running'));
+  }, []);
+
+  return {
+    tasks,
+    isUploading: tasks.some((t) => t.status === 'running'),
+    upload,
+    createFolder,
+    clearCompleted,
+  };
+}