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

package/src/firestore/hooks/useDocumentList.ts

@@ -0,0 +1,242 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type {
+  CollectionReference,
+  DocumentReference,
+  Query,
+  QueryDocumentSnapshot,
+} from 'pyric/firestore';
+import { useFirestoreApi } from '../firestoreApi.js';
+
+export interface UseDocumentListOptions {
+  collection: CollectionReference;
+  /** Optional filter / sort. If omitted, the raw collection is used. */
+  query?: Query;
+  /** Page size for cursor-based pagination. Default 50. */
+  pageSize?: number;
+  /**
+   * `paged` preserves the historical get-based cursor behavior. `live` keeps
+   * the currently requested window under an `onSnapshot` subscription and
+   * grows that window when `loadMore` is requested. Default `paged`.
+   */
+  mode?: 'paged' | 'live';
+}
+
+export interface UseDocumentListResult {
+  documents: QueryDocumentSnapshot[];
+  isLoading: boolean;
+  error: Error | undefined;
+  /** Identifies the active live subscription. Consumers that diff result
+   * snapshots can include this in their scope so a re-subscription (including
+   * load-more) establishes a silent baseline instead of looking like writes. */
+  subscriptionGeneration: number;
+  /** True if there might be another page. The hook tracks this via
+   *  the last fetch's length === pageSize. */
+  hasMore: boolean;
+  /** Fetch the next page; live mode grows and re-establishes its window. */
+  loadMore: () => void;
+  /** Create a document. If `id` is null, Firestore generates one
+   *  via `addDoc`. With `onExisting: 'fail'` (CREATE semantics, the
+   *  admin `create()` analog) an id that already exists rejects with
+   *  `code: 'already-exists'` instead of silently overwriting —
+   *  checked against the BACKEND (a `getDoc` probe), not any loaded
+   *  page, so it is honest beyond pagination. Default: 'overwrite'
+   *  (plain `setDoc`, the historical behavior). */
+  createDocument: (
+    id: string | null,
+    data: Record<string, unknown>,
+    opts?: { onExisting?: 'overwrite' | 'fail' },
+  ) => Promise<DocumentReference>;
+  deleteDocument: (ref: DocumentReference) => Promise<void>;
+  /** Re-establish the active read/subscription. Useful after the consumer
+   *  mutates data outside this hook. */
+  refresh: () => void;
+}
+
+/**
+ * Paginated document list with two acquisition strategies. The default
+ * `paged` mode uses `startAfter` and accumulates one-shot reads. `live` keeps
+ * the requested prefix under one `onSnapshot` listener; loading more grows
+ * that prefix and establishes a new subscription baseline.
+ */
+export function useDocumentList({
+  collection,
+  query,
+  pageSize = 50,
+  mode = 'paged',
+}: UseDocumentListOptions): UseDocumentListResult {
+  const [documents, setDocuments] = useState<QueryDocumentSnapshot[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [hasMore, setHasMore] = useState(false);
+  const [tick, setTick] = useState(0);
+  const [requestedCount, setRequestedCount] = useState(pageSize);
+  const nextSubscriptionGeneration = useRef(0);
+  const [subscriptionGeneration, setSubscriptionGeneration] = useState(0);
+
+  // The modular fns, injected: in-process `pyric/firestore` by default, or the
+  // SharedWorker client bundle when a consumer (Pyric Studio served mode) wraps
+  // the tree in a `FirestoreApiProvider`. Stable across renders per provider.
+  const {
+    addDoc,
+    deleteDoc,
+    doc: docFn,
+    getDoc,
+    getDocs,
+    limit: limitFn,
+    onSnapshot,
+    query: queryFn,
+    setDoc,
+    startAfter: startAfterFn,
+  } = useFirestoreApi();
+
+  useEffect(() => {
+    setRequestedCount(pageSize);
+  }, [collection, mode, pageSize, query]);
+
+  useEffect(() => {
+    let cancelled = false;
+    if (mode === 'paged') setDocuments([]);
+    setHasMore(false);
+    setIsLoading(true);
+    setError(undefined);
+    const baseQuery = query ?? collection;
+    const fetchCount = mode === 'live' ? requestedCount : pageSize;
+    const pagedQuery = queryFn(baseQuery, limitFn(fetchCount));
+    const accept = (snap: { readonly docs: readonly QueryDocumentSnapshot[] }) => {
+      if (cancelled) return;
+      setDocuments([...snap.docs]);
+      setHasMore(snap.docs.length === fetchCount);
+      setIsLoading(false);
+    };
+    const reject = (e: unknown) => {
+      if (cancelled) return;
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsLoading(false);
+    };
+
+    if (mode === 'live') {
+      const generation = ++nextSubscriptionGeneration.current;
+      const unsubscribe = onSnapshot(
+        pagedQuery,
+        (snap: unknown) => {
+          setSubscriptionGeneration(generation);
+          accept(snap as { readonly docs: readonly QueryDocumentSnapshot[] });
+        },
+        reject,
+      );
+      return () => {
+        cancelled = true;
+        unsubscribe();
+      };
+    }
+
+    getDocs(pagedQuery)
+      .then((snap) => {
+        accept(snap);
+      })
+      .catch(reject);
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    collection,
+    getDocs,
+    limitFn,
+    mode,
+    onSnapshot,
+    pageSize,
+    query,
+    queryFn,
+    requestedCount,
+    tick,
+  ]);
+
+  const loadMore = useCallback(() => {
+    if (!hasMore || isLoading) return;
+    if (mode === 'live') {
+      setIsLoading(true);
+      setRequestedCount((count) => count + pageSize);
+      return;
+    }
+    const last = documents[documents.length - 1];
+    if (!last) return;
+    setIsLoading(true);
+    const baseQuery = query ?? collection;
+    const pagedQuery = queryFn(baseQuery, startAfterFn(last), limitFn(pageSize));
+    getDocs(pagedQuery)
+      .then((snap) => {
+        setDocuments((prev) => [...prev, ...snap.docs]);
+        setHasMore(snap.docs.length === pageSize);
+        setIsLoading(false);
+      })
+      .catch((e) => {
+        setError(e instanceof Error ? e : new Error(String(e)));
+        setIsLoading(false);
+      });
+  }, [
+    collection,
+    documents,
+    getDocs,
+    hasMore,
+    isLoading,
+    limitFn,
+    mode,
+    pageSize,
+    query,
+    queryFn,
+    startAfterFn,
+  ]);
+
+  const createDocument = useCallback<UseDocumentListResult['createDocument']>(
+    async (id, data, opts) => {
+      if (id == null) {
+        const ref = await addDoc(collection, data);
+        if (mode === 'paged') setTick((n) => n + 1);
+        return ref;
+      }
+      const ref = docFn(collection, id);
+      if (opts?.onExisting === 'fail') {
+        // CREATE semantics without a batch/create primitive on FirestoreApi:
+        // probe the backend, then write. The probe is authoritative for the
+        // whole collection (not just a loaded page); the tiny read-then-write
+        // window is acceptable for the dev-sandbox surfaces this backs.
+        const existing = await getDoc(ref);
+        // `exists` is a method on the modular SDK snapshot but a boolean on
+        // some compat-shaped snapshots this bundle may be adapted over.
+        const exists =
+          typeof existing.exists === 'function' ? existing.exists() : Boolean(existing.exists);
+        if (exists) {
+          const err = new Error(`Document "${id}" already exists.`) as Error & { code: string };
+          err.code = 'already-exists';
+          throw err;
+        }
+      }
+      await setDoc(ref, data);
+      if (mode === 'paged') setTick((n) => n + 1);
+      return ref;
+    },
+    [addDoc, collection, docFn, getDoc, mode, setDoc],
+  );
+
+  const deleteDocument = useCallback<UseDocumentListResult['deleteDocument']>(
+    async (ref) => {
+      await deleteDoc(ref);
+      if (mode === 'paged') setTick((n) => n + 1);
+    },
+    [deleteDoc, mode],
+  );
+
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  return {
+    documents,
+    isLoading,
+    error,
+    subscriptionGeneration,
+    hasMore,
+    loadMore,
+    createDocument,
+    deleteDocument,
+    refresh,
+  };
+}

package/src/firestore/hooks/useDocumentSubcollections.ts

@@ -0,0 +1,86 @@
+import { useEffect, useRef, useState } from 'react';
+import type {
+  CollectionReference,
+  DocumentReference,
+  Firestore,
+} from 'pyric/firestore';
+
+/**
+ * Lister for a document's own subcollections. Same injected-lister
+ * shape as `useCollectionList` / `ReferencePicker` use — the modular
+ * Web SDK doesn't expose a native `listCollections` on the client, so
+ * the caller wires it (sandbox in-process listing, a server proxy, or
+ * a known schema list).
+ */
+export type ListSubcollections = (
+  firestore: Firestore,
+  parent: DocumentReference,
+) => Promise<CollectionReference[]>;
+
+export interface UseDocumentSubcollectionsOptions {
+  firestore: Firestore;
+  /** The document whose subcollections to list. When `null`/`undefined`
+   *  the hook stays idle (empty, not loading) — used when the preview
+   *  has no ref to drill from. */
+  documentRef: DocumentReference | null | undefined;
+  listSubcollections: ListSubcollections;
+}
+
+export interface UseDocumentSubcollectionsResult {
+  subcollections: CollectionReference[];
+  isLoading: boolean;
+  error: Error | undefined;
+}
+
+/**
+ * Read a single document's subcollection list. A thin specialization of
+ * the `useCollectionList` pattern, scoped to one parent document and
+ * read-only (no create — that lives in `useCollectionList`).
+ */
+export function useDocumentSubcollections({
+  firestore,
+  documentRef,
+  listSubcollections,
+}: UseDocumentSubcollectionsOptions): UseDocumentSubcollectionsResult {
+  const [subcollections, setSubcollections] = useState<CollectionReference[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  // Stable-ref the injected lister so a fresh closure identity each
+  // render doesn't loop the effect — same pattern as useCollectionList.
+  const listRef = useRef(listSubcollections);
+  listRef.current = listSubcollections;
+
+  // Key the effect on the ref's path (stable across snapshot identity
+  // churn) rather than the ref object, which the SDK may re-create.
+  const path = documentRef?.path;
+
+  useEffect(() => {
+    if (!documentRef) {
+      setSubcollections([]);
+      setIsLoading(false);
+      setError(undefined);
+      return;
+    }
+    let cancelled = false;
+    setIsLoading(true);
+    setError(undefined);
+    listRef.current(firestore, documentRef)
+      .then((list) => {
+        if (cancelled) return;
+        setSubcollections(list);
+        setIsLoading(false);
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setError(e instanceof Error ? e : new Error(String(e)));
+        setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [firestore, path]);
+
+  return { subcollections, isLoading, error };
+}

package/src/firestore/hooks/useFirestoreCollection.ts

@@ -0,0 +1,51 @@
+import { useEffect, useState } from 'react';
+import type { Query, QuerySnapshot } from 'pyric/firestore';
+import { coerceError } from './coerceError.js';
+import type { SubscriptionState } from './useFirestoreDoc.js';
+import { useFirestoreApi } from '../firestoreApi.js';
+
+/**
+ * Subscribe to a Firestore query (a `Query` from `pyric/firestore`'s
+ * modular surface, including any `CollectionReference`, which extends
+ * `Query`). Returns `{ data, error, isLoading }`.
+ *
+ * Null/undefined query short-circuits to idle. Cleanup is automatic
+ * on unmount or query change. `Query` objects don't have a stable
+ * structural identity, so the consumer must memoize at the call site
+ * — pass the same instance across renders to avoid re-subscribing.
+ */
+export function useFirestoreCollection(
+  query: Query | null | undefined,
+): SubscriptionState<QuerySnapshot> {
+  const { onSnapshot } = useFirestoreApi();
+  const [state, setState] = useState<SubscriptionState<QuerySnapshot>>(() => ({
+    data: undefined,
+    error: undefined,
+    isLoading: query != null,
+  }));
+
+  useEffect(() => {
+    if (!query) {
+      setState({ data: undefined, error: undefined, isLoading: false });
+      return;
+    }
+
+    setState((prev) => ({ data: prev.data, error: undefined, isLoading: true }));
+
+    const unsubscribe = onSnapshot(
+      query,
+      (snap) =>
+        setState({ data: snap as QuerySnapshot, error: undefined, isLoading: false }),
+      (err) =>
+        setState({
+          data: undefined,
+          error: coerceError(err),
+          isLoading: false,
+        }),
+    );
+
+    return unsubscribe;
+  }, [onSnapshot, query]);
+
+  return state;
+}

package/src/firestore/hooks/useFirestoreDoc.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react';
+import type { DocumentReference, DocumentSnapshot } from 'pyric/firestore';
+import { coerceError } from './coerceError.js';
+import { useFirestoreApi } from '../firestoreApi.js';
+
+export interface SubscriptionState<T> {
+  data: T | undefined;
+  error: Error | undefined;
+  isLoading: boolean;
+}
+
+/**
+ * Subscribe to a single Firestore document. Returns `{ data, error,
+ * isLoading }`. Null/undefined ref short-circuits to an idle state
+ * (`data: undefined, error: undefined, isLoading: false`) — useful
+ * for conditional rendering before a ref is known.
+ *
+ * Cleanup is automatic on unmount or ref change. Memoize the ref at
+ * the call site; this hook's effect re-runs on identity change.
+ */
+export function useFirestoreDoc(
+  ref: DocumentReference | null | undefined,
+): SubscriptionState<DocumentSnapshot> {
+  const { onSnapshot } = useFirestoreApi();
+  const [state, setState] = useState<SubscriptionState<DocumentSnapshot>>(() => ({
+    data: undefined,
+    error: undefined,
+    isLoading: ref != null,
+  }));
+
+  useEffect(() => {
+    if (!ref) {
+      setState({ data: undefined, error: undefined, isLoading: false });
+      return;
+    }
+
+    setState((prev) => ({ data: prev.data, error: undefined, isLoading: true }));
+
+    const unsubscribe = onSnapshot(
+      ref,
+      (snap) =>
+        setState({ data: snap as DocumentSnapshot, error: undefined, isLoading: false }),
+      (err) =>
+        setState({
+          data: undefined,
+          error: coerceError(err),
+          isLoading: false,
+        }),
+    );
+
+    return unsubscribe;
+  }, [onSnapshot, ref]);
+
+  return state;
+}

package/src/firestore/hooks/useQueryBuilder.ts

@@ -0,0 +1,188 @@
+import { useCallback, useMemo, useState } from 'react';
+import {
+  limit as limitFn,
+  orderBy as orderByFn,
+  query as queryFn,
+  where as whereFn,
+  type CollectionReference,
+  type OrderDirection,
+  type Query,
+  type WhereFilterOp,
+} from 'pyric/firestore';
+
+export type QueryOp = WhereFilterOp;
+
+export const QUERY_OPS: readonly QueryOp[] = [
+  '==',
+  '!=',
+  '<',
+  '<=',
+  '>',
+  '>=',
+  'in',
+  'not-in',
+  'array-contains',
+  'array-contains-any',
+] as const;
+
+/** Ops that accept an array of values. The value editor in the
+ *  bundled <QueryBuilder> parses the input as JSON for these. */
+export const MULTI_VALUE_OPS: ReadonlySet<QueryOp> = new Set<QueryOp>([
+  'in',
+  'not-in',
+  'array-contains-any',
+]);
+
+export interface QueryCondition {
+  id: string;
+  field: string;
+  op: QueryOp;
+  value: unknown;
+}
+
+export interface QueryBuilderState {
+  conditions: QueryCondition[];
+  orderBy?: { field: string; direction: OrderDirection };
+  limit?: number;
+}
+
+export interface QueryBuilderActions {
+  addCondition: (c?: Partial<Omit<QueryCondition, 'id'>>) => void;
+  updateCondition: (
+    id: string,
+    patch: Partial<Omit<QueryCondition, 'id'>>,
+  ) => void;
+  removeCondition: (id: string) => void;
+  setOrderBy: (orderBy?: { field: string; direction: OrderDirection }) => void;
+  setLimit: (limit?: number) => void;
+  reset: () => void;
+  /**
+   * Compose the state into a Firestore `Query`. Returns the base
+   * collection when there are no conditions / orderBy / limit.
+   * Conditions with empty `field` are skipped — the builder UI
+   * lets users add a row before they've filled it in.
+   */
+  buildQuery: (base: CollectionReference | Query) => Query;
+}
+
+export type UseQueryBuilderResult = QueryBuilderState & QueryBuilderActions;
+
+const EMPTY_STATE: QueryBuilderState = { conditions: [] };
+
+export interface UseQueryBuilderOptions {
+  /** Pre-populate the builder. */
+  initial?: Partial<QueryBuilderState>;
+}
+
+/**
+ * Headless query-builder state machine. Single-level — no nested
+ * `and()`/`or()` groups in v1. Consumers compose the state into a
+ * Firestore `Query` via `buildQuery(base)` and feed that into
+ * `useDocumentList` / `useFirestoreCollection`.
+ */
+export function useQueryBuilder(
+  options: UseQueryBuilderOptions = {},
+): UseQueryBuilderResult {
+  const [state, setState] = useState<QueryBuilderState>(() => ({
+    ...EMPTY_STATE,
+    ...options.initial,
+    conditions: options.initial?.conditions ?? [],
+  }));
+
+  const addCondition = useCallback<QueryBuilderActions['addCondition']>((c) => {
+    setState((prev) => ({
+      ...prev,
+      conditions: [
+        ...prev.conditions,
+        {
+          id: crypto.randomUUID(),
+          field: c?.field ?? '',
+          op: c?.op ?? '==',
+          value: c?.value ?? '',
+        },
+      ],
+    }));
+  }, []);
+
+  const updateCondition = useCallback<QueryBuilderActions['updateCondition']>(
+    (id, patch) => {
+      setState((prev) => ({
+        ...prev,
+        conditions: prev.conditions.map((c) =>
+          c.id === id ? { ...c, ...patch } : c,
+        ),
+      }));
+    },
+    [],
+  );
+
+  const removeCondition = useCallback<QueryBuilderActions['removeCondition']>(
+    (id) => {
+      setState((prev) => ({
+        ...prev,
+        conditions: prev.conditions.filter((c) => c.id !== id),
+      }));
+    },
+    [],
+  );
+
+  const setOrderBy = useCallback<QueryBuilderActions['setOrderBy']>((next) => {
+    setState((prev) => ({ ...prev, orderBy: next }));
+  }, []);
+
+  const setLimit = useCallback<QueryBuilderActions['setLimit']>((next) => {
+    setState((prev) => ({ ...prev, limit: next }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setState(EMPTY_STATE);
+  }, []);
+
+  const buildQuery = useCallback<QueryBuilderActions['buildQuery']>(
+    (base) => {
+      const constraints = [] as ReturnType<typeof whereFn>[];
+      const orderByConstraints = [] as ReturnType<typeof orderByFn>[];
+      const limitConstraints = [] as ReturnType<typeof limitFn>[];
+
+      for (const cond of state.conditions) {
+        if (!cond.field) continue;
+        constraints.push(whereFn(cond.field, cond.op, cond.value));
+      }
+      if (state.orderBy && state.orderBy.field) {
+        orderByConstraints.push(
+          orderByFn(state.orderBy.field, state.orderBy.direction),
+        );
+      }
+      if (typeof state.limit === 'number' && state.limit > 0) {
+        limitConstraints.push(limitFn(state.limit));
+      }
+      const all = [...constraints, ...orderByConstraints, ...limitConstraints];
+      if (all.length === 0) return base as Query;
+      return queryFn(base, ...all);
+    },
+    [state],
+  );
+
+  return useMemo(
+    () => ({
+      ...state,
+      addCondition,
+      updateCondition,
+      removeCondition,
+      setOrderBy,
+      setLimit,
+      reset,
+      buildQuery,
+    }),
+    [
+      state,
+      addCondition,
+      updateCondition,
+      removeCondition,
+      setOrderBy,
+      setLimit,
+      reset,
+      buildQuery,
+    ],
+  );
+}

package/src/firestore/hooks/useRecursiveDelete.ts

@@ -0,0 +1,77 @@
+import { useCallback, useRef, useState } from 'react';
+import type { CollectionReference, DocumentReference } from 'pyric/firestore';
+
+export interface RecursiveDeleteProgress {
+  /** Total nodes deleted so far. */
+  deletedCount: number;
+  /** True for the final emission. */
+  done: boolean;
+}
+
+/**
+ * Implementation injected by the consumer. The library doesn't ship
+ * one — sandbox-backed apps usually walk `pyric/sandbox`'s in-process
+ * tree; production apps usually call a Cloud Function. Either way,
+ * `start` returns an async iterator emitting progress.
+ */
+export interface RecursiveDeleteImpl {
+  start: (
+    target: DocumentReference | CollectionReference,
+  ) => AsyncIterableIterator<RecursiveDeleteProgress>;
+}
+
+export interface UseRecursiveDeleteResult {
+  /** Run the delete. Resolves when the iterator signals `done`. */
+  delete: (target: DocumentReference | CollectionReference) => Promise<void>;
+  /** Number of nodes deleted in the current/last run. */
+  progress: number;
+  /** True while an iteration is in flight. */
+  isRunning: boolean;
+  /** Error thrown by the iterator, if any. Cleared at the start of
+   *  the next call. */
+  error: Error | undefined;
+}
+
+/**
+ * Drive a {@link RecursiveDeleteImpl} from a React component. Tracks
+ * progress + running state so the consumer can render a progress
+ * indicator. Errors are caught and surfaced via the returned state,
+ * not thrown.
+ *
+ * Stale-run protection: if the component remounts (or the user
+ * cancels and starts a new run) before a previous iteration
+ * finishes, the older run's progress updates are dropped via a
+ * generation token.
+ */
+export function useRecursiveDelete(
+  impl: RecursiveDeleteImpl,
+): UseRecursiveDeleteResult {
+  const [progress, setProgress] = useState(0);
+  const [isRunning, setIsRunning] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const generationRef = useRef(0);
+
+  const del = useCallback(
+    async (target: DocumentReference | CollectionReference) => {
+      const myGen = ++generationRef.current;
+      setProgress(0);
+      setError(undefined);
+      setIsRunning(true);
+      try {
+        for await (const evt of impl.start(target)) {
+          if (myGen !== generationRef.current) return;
+          setProgress(evt.deletedCount);
+          if (evt.done) break;
+        }
+      } catch (e) {
+        if (myGen !== generationRef.current) return;
+        setError(e instanceof Error ? e : new Error(String(e)));
+      } finally {
+        if (myGen === generationRef.current) setIsRunning(false);
+      }
+    },
+    [impl],
+  );
+
+  return { delete: del, progress, isRunning, error };
+}