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

package/src/storage/hooks/useStorageObject.ts

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type {
+  FirebaseStorage,
+  FullMetadata,
+} from 'pyric/storage';
+import { useStorageApi } from '../storageApi.js';
+import { normalizeStoragePath } from './usePathState.js';
+
+export type StorageObjectStatus = 'idle' | 'loading' | 'success' | 'error';
+
+export interface UseStorageObjectResult {
+  /** Metadata read state. `'idle'` when `storage` or `path` is null. */
+  status: StorageObjectStatus;
+  metadata: FullMetadata | undefined;
+  /** Typed `StorageError` (`storage/object-not-found`,
+   *  `storage/unauthorized`, …). */
+  error: Error | undefined;
+  /** Re-read the metadata (also resets the blob, the object may
+   *  have been overwritten). */
+  refresh: () => void;
+  /** Blob read state. Stays `'idle'` until `loadBlob()`, the blob
+   *  is LAZY; metadata alone never downloads bytes. */
+  blobStatus: StorageObjectStatus;
+  blob: Blob | undefined;
+  /**
+   * `URL.createObjectURL` handle for the loaded blob, used as the local
+   * preview channel. Revoked automatically when the blob is replaced,
+   * the path changes, or the hook unmounts.
+   */
+  blobUrl: string | undefined;
+  blobError: Error | undefined;
+  /** Fetch the bytes via `getBlob`. Subsequent calls re-fetch. */
+  loadBlob: () => void;
+}
+
+interface MetaState {
+  status: StorageObjectStatus;
+  metadata: FullMetadata | undefined;
+  error: Error | undefined;
+}
+
+interface BlobState {
+  status: StorageObjectStatus;
+  blob: Blob | undefined;
+  url: string | undefined;
+  error: Error | undefined;
+}
+
+const IDLE_BLOB: BlobState = {
+  status: 'idle',
+  blob: undefined,
+  url: undefined,
+  error: undefined,
+};
+
+/**
+ * One object's metadata + lazily-loaded bytes, the data source for
+ * `<ObjectInspector>`. Read-via-get like the rest of the storage
+ * half: updates on `refresh`, `path` change, or `loadBlob`.
+ */
+export function useStorageObject(
+  storage: FirebaseStorage | null | undefined,
+  path: string | null | undefined,
+): UseStorageObjectResult {
+  // Injected: in-process `pyric/storage` by default, or the SharedWorker client
+  // bundle in Studio served mode (via StorageApiProvider).
+  const { getBlob, getMetadata, ref: refFn } = useStorageApi();
+  const normalized = path == null ? null : normalizeStoragePath(path);
+  const active = storage != null && normalized != null && normalized !== '';
+
+  const [meta, setMeta] = useState<MetaState>(() => ({
+    status: active ? 'loading' : 'idle',
+    metadata: undefined,
+    error: undefined,
+  }));
+  const [blobState, setBlobState] = useState<BlobState>(IDLE_BLOB);
+  const [tick, setTick] = useState(0);
+  // Generation token: invalidates in-flight blob loads when the
+  // path/storage changes or a newer load starts.
+  const blobGenRef = useRef(0);
+
+  useEffect(() => {
+    // Any identity change drops the previous blob (the URL-revoking
+    // effect below cleans up the old object URL when state resets).
+    blobGenRef.current++;
+    setBlobState(IDLE_BLOB);
+    if (!active) {
+      setMeta({ status: 'idle', metadata: undefined, error: undefined });
+      return;
+    }
+    let cancelled = false;
+    setMeta({ status: 'loading', metadata: undefined, error: undefined });
+    getMetadata(refFn(storage, normalized))
+      .then((metadata) => {
+        if (cancelled) return;
+        setMeta({ status: 'success', metadata, error: undefined });
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setMeta({
+          status: 'error',
+          metadata: undefined,
+          error: e instanceof Error ? e : new Error(String(e)),
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+    // `active` is derived from storage/normalized, not a dep itself.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [storage, normalized, tick]);
+
+  // Blob-URL lifecycle: one effect owns revocation. Runs cleanup when
+  // the url is replaced, reset (path change), or the hook unmounts :
+  // the design plan's "revoke on unmount" requirement.
+  const url = blobState.url;
+  useEffect(() => {
+    if (url === undefined) return;
+    return () => {
+      URL.revokeObjectURL(url);
+    };
+  }, [url]);
+
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  const loadBlob = useCallback(() => {
+    if (storage == null || normalized == null || normalized === '') return;
+    const myGen = ++blobGenRef.current;
+    setBlobState({ status: 'loading', blob: undefined, url: undefined, error: undefined });
+    getBlob(refFn(storage, normalized))
+      .then((blob) => {
+        if (myGen !== blobGenRef.current) return;
+        setBlobState({
+          status: 'success',
+          blob,
+          url: URL.createObjectURL(blob),
+          error: undefined,
+        });
+      })
+      .catch((e) => {
+        if (myGen !== blobGenRef.current) return;
+        setBlobState({
+          status: 'error',
+          blob: undefined,
+          url: undefined,
+          error: e instanceof Error ? e : new Error(String(e)),
+        });
+      });
+  }, [storage, normalized]);
+
+  return {
+    status: meta.status,
+    metadata: meta.metadata,
+    error: meta.error,
+    refresh,
+    blobStatus: blobState.status,
+    blob: blobState.blob,
+    blobUrl: blobState.url,
+    blobError: blobState.error,
+    loadBlob,
+  };
+}

package/src/storage/hooks/useStorageRulesGate.ts

@@ -0,0 +1,270 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  TARGET_SYMBOL,
+  parseStorageRules,
+  evaluateStorageRules,
+  type FirebaseStorage,
+  type StorageAuth,
+  type StorageMethod,
+  type StorageRules,
+} from 'pyric/storage';
+import { normalizeStoragePath } from './usePathState.js';
+
+export type StorageRulesGateStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+/**
+ * Where the active ruleset came from:
+ * - `'option'` — the explicit `rules` option (string or pre-parsed).
+ * - `'sandbox'` — the ruleset deployed on the sandbox handle
+ *   (`getStorageSandbox(ctx, { rules })`), read off the handle's
+ *   `StorageService`.
+ * - `'none'` — no rules reachable. Every verdict allows
+ *   (open-by-default, the same semantics `pyric/storage`'s
+ *   enforcement layer applies when no rules are configured).
+ */
+export type StorageRulesSource = 'option' | 'sandbox' | 'none';
+
+/**
+ * Per-path verdict. `pyric/storage`'s rules subset has exactly two
+ * verbs (`read` | `write` — the granular get/list/create/update/
+ * delete forms are a parser follow-up), so `delete` and `upload` are
+ * DERIVED aliases of `write`: Firebase Storage's `write` permission
+ * governs create, overwrite, AND delete.
+ */
+export interface StorageGateVerdict {
+  read: boolean;
+  write: boolean;
+  /** Derived — always `=== write` under the two-verb subset. */
+  delete: boolean;
+  /** Derived — always `=== write` under the two-verb subset. */
+  upload: boolean;
+  /**
+   * Evaluator reason traces for DENIED verbs (`"no rule matches…"` /
+   * `"match /… : condition false"`); empty arrays when allowed.
+   * Feed into disabled-state tooltips and `data-*-reason` attributes.
+   */
+  reasons: { read: string[]; write: string[] };
+}
+
+export interface UseStorageRulesGateOptions {
+  /**
+   * Path (or paths) to pre-evaluate into `verdicts`, keyed by the
+   * normalized path. Ad-hoc paths (e.g. browser rows) go through
+   * `verdictFor` instead — the two are the same evaluation.
+   */
+  paths?: string | readonly string[];
+  /**
+   * Explicit rules source — raw rules text (parsed here; a malformed
+   * string surfaces as `status: 'error'`) or a pre-parsed
+   * `StorageRules` handle. Overrides the sandbox's deployed ruleset
+   * when both exist.
+   */
+  rules?: string | StorageRules;
+  /**
+   * Identity override. `null` is anonymous; OMIT the field to use
+   * the handle's own identity (the sandbox context's `auth`).
+   */
+  identity?: StorageAuth | null;
+  /**
+   * The about-to-write payload bound to `request.resource` for the
+   * WRITE evaluation — pass `{ size, contentType }` when gating a
+   * specific upload so size/contentType-conditioned rules evaluate
+   * truthfully. When omitted, `request.resource` is unset, which is
+   * exactly DELETE semantics (deletes carry no inbound payload) —
+   * a rule like `request.resource.size < N` then denies, the
+   * conservative answer for uploads.
+   */
+  writeResource?: { size: number; contentType?: string };
+}
+
+export interface UseStorageRulesGateResult {
+  /** `'idle'` only when `storage` is null/undefined. */
+  status: StorageRulesGateStatus;
+  /** Where the active ruleset came from. */
+  source: StorageRulesSource;
+  /** Always false: `pyric/storage` handles are sandbox mirrors. */
+  advisory: boolean;
+  /** The identity the verdicts evaluate under. */
+  identity: StorageAuth | null;
+  /** Pre-evaluated verdicts for `options.paths`, keyed by normalized path. */
+  verdicts: Record<string, StorageGateVerdict>;
+  /**
+   * Evaluate an arbitrary path under the current ruleset + identity.
+   * Pure and synchronous once `status` is `'ready'`; before that
+   * (and whenever no rules are reachable) it returns the allow-all
+   * verdict — the gate FAILS OPEN, because affordances are advisory
+   * and the real enforcement (sandbox throw / server denial) stays
+   * authoritative.
+   */
+  verdictFor: (path: string) => StorageGateVerdict;
+  /** Rules-resolution failure (e.g. a malformed `rules` string). */
+  error: Error | undefined;
+}
+
+/** Shared allow-all verdict — idle/loading/error and rules-less states. */
+const ALLOW_ALL: StorageGateVerdict = Object.freeze({
+  read: true,
+  write: true,
+  delete: true,
+  upload: true,
+  reasons: Object.freeze({
+    read: [] as string[],
+    write: [] as string[],
+  }) as StorageGateVerdict['reasons'],
+});
+
+interface RulesState {
+  status: StorageRulesGateStatus;
+  rules: StorageRules | null;
+  source: StorageRulesSource;
+  error: Error | undefined;
+}
+
+/**
+ * Pre-flight rules evaluation — the M7 differentiator. Evaluates the
+ * current identity against paths BEFORE the click, so components can
+ * annotate denied affordances (`data-pyric-denied`, disabled-with-
+ * reason) instead of letting the user discover a denial via a thrown
+ * `storage/unauthorized`.
+ *
+ * Rules discovery: a sandbox handle carries its deployed ruleset
+ * (`getStorageSandbox(ctx, { rules })` parses it into the handle's
+ * `StorageService`) — the hook reads it through the handle's target,
+ * so sandbox callers pass nothing. Identity likewise defaults to the
+ * handle's `SandboxContext.auth`. An explicit `rules` or `identity`
+ * option overrides the handle when evaluating a what-if scenario.
+ *
+ * Evaluation contract (mirrors `pyric/storage`'s own enforcement):
+ * `resource` (the existing object) is bound as `null` — the gate
+ * pre-evaluates without fetching per-path metadata, matching how the
+ * sandbox enforces `listAll`. Rules conditioned on existing-object
+ * state (`resource.*`) evaluate as if the object doesn't exist; the
+ * common identity/path/payload-shaped rules evaluate exactly.
+ */
+export function useStorageRulesGate(
+  storage: FirebaseStorage | null | undefined,
+  options: UseStorageRulesGateOptions = {},
+): UseStorageRulesGateResult {
+  const { paths, rules: rulesOption, identity: identityOption, writeResource } = options;
+
+  const target = storage == null ? null : storage[TARGET_SYMBOL];
+
+  const [state, setState] = useState<RulesState>(() => ({
+    status: storage == null ? 'idle' : 'loading',
+    rules: null,
+    source: 'none',
+    error: undefined,
+  }));
+
+  useEffect(() => {
+    if (target == null) {
+      setState({ status: 'idle', rules: null, source: 'none', error: undefined });
+      return;
+    }
+    // Explicit option wins for what-if evaluation.
+    if (rulesOption != null) {
+      try {
+        const parsed =
+          typeof rulesOption === 'string' ? parseStorageRules(rulesOption) : rulesOption;
+        setState({ status: 'ready', rules: parsed, source: 'option', error: undefined });
+      } catch (e) {
+        setState({
+          status: 'error',
+          rules: null,
+          source: 'none',
+          error: e instanceof Error ? e : new Error(String(e)),
+        });
+      }
+      return;
+    }
+    let cancelled = false;
+    setState({ status: 'loading', rules: null, source: 'none', error: undefined });
+    target.servicePromise
+      .then((service) => {
+        if (cancelled) return;
+        setState({
+          status: 'ready',
+          rules: service.rules,
+          source: service.rules ? 'sandbox' : 'none',
+          error: undefined,
+        });
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setState({
+          status: 'error',
+          rules: null,
+          source: 'none',
+          error: e instanceof Error ? e : new Error(String(e)),
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [target, rulesOption]);
+
+  // `undefined` means "derive from the handle"; an explicit `null`
+  // means anonymous.
+  const identity: StorageAuth | null =
+    identityOption !== undefined ? identityOption : (target?.context.auth ?? null);
+
+  const { rules, status } = state;
+  const writeSize = writeResource?.size;
+  const writeContentType = writeResource?.contentType;
+
+  const verdictFor = useCallback(
+    (path: string): StorageGateVerdict => {
+      if (rules == null) return ALLOW_ALL;
+      const objectPath = normalizeStoragePath(path);
+      const bucket = target?.bucket ?? 'pyric-default';
+      const rulesPath = objectPath === '' ? `b/${bucket}/o` : `b/${bucket}/o/${objectPath}`;
+      const evaluate = (method: StorageMethod) =>
+        evaluateStorageRules(rules, {
+          request: {
+            auth: identity,
+            method,
+            path: rulesPath,
+            ...(method === 'write' && writeSize !== undefined
+              ? { resource: { size: writeSize, contentType: writeContentType } }
+              : {}),
+          },
+          resource: null,
+        });
+      const read = evaluate('read');
+      const write = evaluate('write');
+      return {
+        read: read.allowed,
+        write: write.allowed,
+        delete: write.allowed,
+        upload: write.allowed,
+        reasons: {
+          read: read.allowed ? [] : read.reasons,
+          write: write.allowed ? [] : write.reasons,
+        },
+      };
+    },
+    [rules, target?.bucket, identity, writeSize, writeContentType],
+  );
+
+  const pathsKey = typeof paths === 'string' ? paths : (paths ?? []).join('\n');
+  const verdicts = useMemo(() => {
+    const list = typeof paths === 'string' ? [paths] : (paths ?? []);
+    const out: Record<string, StorageGateVerdict> = {};
+    for (const p of list) {
+      out[normalizeStoragePath(p)] = verdictFor(p);
+    }
+    return out;
+    // `pathsKey` stands in for the (possibly inline) array identity,
+    // so a fresh-but-equal `paths` array doesn't churn the record.
+  }, [pathsKey, verdictFor]);
+
+  return {
+    status,
+    source: state.source,
+    advisory: false,
+    identity,
+    verdicts,
+    verdictFor,
+    error: state.error,
+  };
+}

package/src/storage/hooks/useStorageSelection.ts

@@ -0,0 +1,90 @@
+import { useCallback, useMemo, useState } from 'react';
+
+/**
+ * What the selection tracks per row — a structural subset of
+ * `StorageListEntry`, so `useStorageList`'s entries pass straight
+ * in. The `kind` decides the delete verb later (object →
+ * `deleteObject`, folder → recursive).
+ */
+export interface StorageSelectionEntry {
+  kind: 'folder' | 'object';
+  fullPath: string;
+}
+
+export interface UseStorageSelectionResult {
+  /** Selected entries in selection order. */
+  selected: StorageSelectionEntry[];
+  size: number;
+  isSelected: (fullPath: string) => boolean;
+  /** Add/remove — the checkbox verb. */
+  toggle: (entry: StorageSelectionEntry) => void;
+  select: (entry: StorageSelectionEntry) => void;
+  deselect: (fullPath: string) => void;
+  /** Replace the selection (e.g. a "select all" over
+   *  `list.entries`). */
+  selectAll: (entries: StorageSelectionEntry[]) => void;
+  clear: () => void;
+}
+
+/**
+ * Multi-select state over storage rows, keyed by `fullPath`.
+ * Deliberately dumb: it doesn't watch the list, so clear it on path
+ * change (or after a bulk op via the delete hook's outcome) — the
+ * consumer owns that policy.
+ */
+export function useStorageSelection(): UseStorageSelectionResult {
+  const [map, setMap] = useState<Map<string, StorageSelectionEntry>>(
+    () => new Map(),
+  );
+
+  const isSelected = useCallback(
+    (fullPath: string) => map.has(fullPath),
+    [map],
+  );
+
+  const select = useCallback((entry: StorageSelectionEntry) => {
+    setMap((prev) => {
+      if (prev.has(entry.fullPath)) return prev;
+      const next = new Map(prev);
+      next.set(entry.fullPath, entry);
+      return next;
+    });
+  }, []);
+
+  const deselect = useCallback((fullPath: string) => {
+    setMap((prev) => {
+      if (!prev.has(fullPath)) return prev;
+      const next = new Map(prev);
+      next.delete(fullPath);
+      return next;
+    });
+  }, []);
+
+  const toggle = useCallback((entry: StorageSelectionEntry) => {
+    setMap((prev) => {
+      const next = new Map(prev);
+      if (next.has(entry.fullPath)) next.delete(entry.fullPath);
+      else next.set(entry.fullPath, entry);
+      return next;
+    });
+  }, []);
+
+  const selectAll = useCallback((entries: StorageSelectionEntry[]) => {
+    setMap(new Map(entries.map((e) => [e.fullPath, e])));
+  }, []);
+
+  const clear = useCallback(() => setMap(new Map()), []);
+
+  const selected = useMemo(() => [...map.values()], [map]);
+
+  return {
+    selected,
+    size: map.size,
+    isSelected,
+    toggle,
+    select,
+    deselect,
+    selectAll,
+    clear,
+  };
+}

package/src/storage/index.ts

@@ -0,0 +1,59 @@
+export * from './hooks/index.js';
+
+// Injectable Storage API bundle (Pyric Studio data-backend swap): defaults to
+// in-process `pyric/storage`; a consumer can provide the SharedWorker client.
+export { StorageApiProvider, useStorageApi, type StorageApi } from './storageApi.js';
+
+// M2: navigation shell
+export {
+  PathBreadcrumb,
+  type PathBreadcrumbProps,
+} from './components/PathBreadcrumb.js';
+export {
+  ObjectBrowser,
+  type ObjectBrowserProps,
+} from './components/ObjectBrowser.js';
+
+// M3: upload
+export {
+  UploadDropzone,
+  type UploadDropzoneProps,
+  type DroppedFile,
+} from './components/UploadDropzone.js';
+export {
+  splitStorageName,
+  parseCopyCounter,
+  resolveCollision,
+  planBatchNames,
+} from './collisionRename.js';
+export {
+  expandPathChain,
+  initialPendingPrefixes,
+  pendingPrefixReducer,
+  pendingChildFolders,
+  isPendingPrefix,
+  folderInputError,
+  type PendingPrefixState,
+  type PendingPrefixAction,
+} from './pendingPrefixes.js';
+
+// M4: inspection, content-type preview registry + inspector
+export {
+  defaultStoragePreviews,
+  imagePreview,
+  textPreview,
+  selectStoragePreview,
+  TEXT_PREVIEW_MAX_BYTES,
+  type StoragePreview,
+  type StoragePreviewContext,
+} from './previews.js';
+export {
+  ObjectInspector,
+  type ObjectInspectorProps,
+} from './components/ObjectInspector.js';
+
+// M6: bulk ops
+export {
+  DeleteSelectionWithConfirm,
+  type DeleteSelectionWithConfirmProps,
+} from './components/DeleteSelectionWithConfirm.js';