@pyric/ui 0.1.0-alpha.10

package/dist/firestore/hooks/useDocumentList.js

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useFirestoreApi } from '../firestoreApi.js';
+/**
+ * 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', }) {
+    const [documents, setDocuments] = useState([]);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(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) => {
+            if (cancelled)
+                return;
+            setDocuments([...snap.docs]);
+            setHasMore(snap.docs.length === fetchCount);
+            setIsLoading(false);
+        };
+        const reject = (e) => {
+            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) => {
+                setSubscriptionGeneration(generation);
+                accept(snap);
+            }, 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(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.`);
+                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(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,
+    };
+}
+//# sourceMappingURL=useDocumentList.js.map

package/dist/firestore/hooks/useDocumentList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentList.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useDocumentList.ts"],"names":[],"mappings":"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"}

package/dist/firestore/hooks/useDocumentSubcollections.d.ts

@@ -0,0 +1,29 @@
+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 declare function useDocumentSubcollections({ firestore, documentRef, listSubcollections, }: UseDocumentSubcollectionsOptions): UseDocumentSubcollectionsResult;
+//# sourceMappingURL=useDocumentSubcollections.d.ts.map

package/dist/firestore/hooks/useDocumentSubcollections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentSubcollections.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useDocumentSubcollections.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACV,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,iBAAiB,KACtB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAEpC,MAAM,WAAW,gCAAgC;IAC/C,SAAS,EAAE,SAAS,CAAC;IACrB;;oCAEgC;IAChC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,MAAM,WAAW,+BAA+B;IAC9C,cAAc,EAAE,mBAAmB,EAAE,CAAC;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,SAAS,EACT,WAAW,EACX,kBAAkB,GACnB,EAAE,gCAAgC,GAAG,+BAA+B,CA0CpE"}

package/dist/firestore/hooks/useDocumentSubcollections.js

@@ -0,0 +1,48 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * 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, }) {
+    const [subcollections, setSubcollections] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(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 };
+}
+//# sourceMappingURL=useDocumentSubcollections.js.map

package/dist/firestore/hooks/useDocumentSubcollections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentSubcollections.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useDocumentSubcollections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAkCpD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,SAAS,EACT,WAAW,EACX,kBAAkB,GACe;IACjC,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,GAAG,QAAQ,CAAwB,EAAE,CAAC,CAAC;IAChF,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAoB,SAAS,CAAC,CAAC;IAEjE,kEAAkE;IAClE,sEAAsE;IACtE,MAAM,OAAO,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC3C,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC;IAErC,oEAAoE;IACpE,kEAAkE;IAClE,MAAM,IAAI,GAAG,WAAW,EAAE,IAAI,CAAC;IAE/B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,iBAAiB,CAAC,EAAE,CAAC,CAAC;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,QAAQ,CAAC,SAAS,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpB,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC;aACpC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,IAAI,SAAS;gBAAE,OAAO;YACtB,iBAAiB,CAAC,IAAI,CAAC,CAAC;YACxB,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;YACX,IAAI,SAAS;gBAAE,OAAO;YACtB,QAAQ,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACxD,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;QACL,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;QACF,uDAAuD;IACzD,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;IAEtB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC9C,CAAC"}

package/dist/firestore/hooks/useFirestoreCollection.d.ts

@@ -0,0 +1,14 @@
+import type { Query, QuerySnapshot } from 'pyric/firestore';
+import type { SubscriptionState } from './useFirestoreDoc.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 declare function useFirestoreCollection(query: Query | null | undefined): SubscriptionState<QuerySnapshot>;
+//# sourceMappingURL=useFirestoreCollection.d.ts.map

package/dist/firestore/hooks/useFirestoreCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFirestoreCollection.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useFirestoreCollection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAC9B,iBAAiB,CAAC,aAAa,CAAC,CAgClC"}

package/dist/firestore/hooks/useFirestoreCollection.js

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react';
+import { coerceError } from './coerceError.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) {
+    const { onSnapshot } = useFirestoreApi();
+    const [state, setState] = useState(() => ({
+        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, error: undefined, isLoading: false }), (err) => setState({
+            data: undefined,
+            error: coerceError(err),
+            isLoading: false,
+        }));
+        return unsubscribe;
+    }, [onSnapshot, query]);
+    return state;
+}
+//# sourceMappingURL=useFirestoreCollection.js.map

package/dist/firestore/hooks/useFirestoreCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFirestoreCollection.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useFirestoreCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA+B;IAE/B,MAAM,EAAE,UAAU,EAAE,GAAG,eAAe,EAAE,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAmC,GAAG,EAAE,CAAC,CAAC;QAC1E,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,KAAK,IAAI,IAAI;KACzB,CAAC,CAAC,CAAC;IAEJ,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YAClE,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAE7E,MAAM,WAAW,GAAG,UAAU,CAC5B,KAAK,EACL,CAAC,IAAI,EAAE,EAAE,CACP,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAqB,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAC/E,CAAC,GAAG,EAAE,EAAE,CACN,QAAQ,CAAC;YACP,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;YACvB,SAAS,EAAE,KAAK;SACjB,CAAC,CACL,CAAC;QAEF,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;IAExB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/firestore/hooks/useFirestoreDoc.d.ts

@@ -0,0 +1,17 @@
+import type { DocumentReference, DocumentSnapshot } from 'pyric/firestore';
+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 declare function useFirestoreDoc(ref: DocumentReference | null | undefined): SubscriptionState<DocumentSnapshot>;
+//# sourceMappingURL=useFirestoreDoc.d.ts.map

package/dist/firestore/hooks/useFirestoreDoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFirestoreDoc.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useFirestoreDoc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAI3E,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GACxC,iBAAiB,CAAC,gBAAgB,CAAC,CAgCrC"}

package/dist/firestore/hooks/useFirestoreDoc.js

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react';
+import { coerceError } from './coerceError.js';
+import { useFirestoreApi } from '../firestoreApi.js';
+/**
+ * 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) {
+    const { onSnapshot } = useFirestoreApi();
+    const [state, setState] = useState(() => ({
+        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, error: undefined, isLoading: false }), (err) => setState({
+            data: undefined,
+            error: coerceError(err),
+            isLoading: false,
+        }));
+        return unsubscribe;
+    }, [onSnapshot, ref]);
+    return state;
+}
+//# sourceMappingURL=useFirestoreDoc.js.map

package/dist/firestore/hooks/useFirestoreDoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFirestoreDoc.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useFirestoreDoc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAQrD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAyC;IAEzC,MAAM,EAAE,UAAU,EAAE,GAAG,eAAe,EAAE,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAsC,GAAG,EAAE,CAAC,CAAC;QAC7E,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,GAAG,IAAI,IAAI;KACvB,CAAC,CAAC,CAAC;IAEJ,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YAClE,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAE7E,MAAM,WAAW,GAAG,UAAU,CAC5B,GAAG,EACH,CAAC,IAAI,EAAE,EAAE,CACP,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAwB,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAClF,CAAC,GAAG,EAAE,EAAE,CACN,QAAQ,CAAC;YACP,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC;YACvB,SAAS,EAAE,KAAK;SACjB,CAAC,CACL,CAAC;QAEF,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;IAEtB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/firestore/hooks/useQueryBuilder.d.ts

@@ -0,0 +1,51 @@
+import { type CollectionReference, type OrderDirection, type Query, type WhereFilterOp } from 'pyric/firestore';
+export type QueryOp = WhereFilterOp;
+export declare const QUERY_OPS: readonly QueryOp[];
+/** Ops that accept an array of values. The value editor in the
+ *  bundled <QueryBuilder> parses the input as JSON for these. */
+export declare const MULTI_VALUE_OPS: ReadonlySet<QueryOp>;
+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;
+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 declare function useQueryBuilder(options?: UseQueryBuilderOptions): UseQueryBuilderResult;
+//# sourceMappingURL=useQueryBuilder.d.ts.map

package/dist/firestore/hooks/useQueryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useQueryBuilder.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,OAAO,GAAG,aAAa,CAAC;AAEpC,eAAO,MAAM,SAAS,EAAE,SAAS,OAAO,EAW9B,CAAC;AAEX;iEACiE;AACjE,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,OAAO,CAI/C,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC;IAChE,eAAe,EAAE,CACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,KACvC,IAAI,CAAC;IACV,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,cAAc,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7E,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;;OAKG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,mBAAmB,GAAG,KAAK,KAAK,KAAK,CAAC;CAC1D;AAED,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAI5E,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAuGvB"}

package/dist/firestore/hooks/useQueryBuilder.js

@@ -0,0 +1,110 @@
+import { useCallback, useMemo, useState } from 'react';
+import { limit as limitFn, orderBy as orderByFn, query as queryFn, where as whereFn, } from 'pyric/firestore';
+export const QUERY_OPS = [
+    '==',
+    '!=',
+    '<',
+    '<=',
+    '>',
+    '>=',
+    'in',
+    'not-in',
+    'array-contains',
+    'array-contains-any',
+];
+/** 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 = new Set([
+    'in',
+    'not-in',
+    'array-contains-any',
+]);
+const EMPTY_STATE = { conditions: [] };
+/**
+ * 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 = {}) {
+    const [state, setState] = useState(() => ({
+        ...EMPTY_STATE,
+        ...options.initial,
+        conditions: options.initial?.conditions ?? [],
+    }));
+    const addCondition = useCallback((c) => {
+        setState((prev) => ({
+            ...prev,
+            conditions: [
+                ...prev.conditions,
+                {
+                    id: crypto.randomUUID(),
+                    field: c?.field ?? '',
+                    op: c?.op ?? '==',
+                    value: c?.value ?? '',
+                },
+            ],
+        }));
+    }, []);
+    const updateCondition = useCallback((id, patch) => {
+        setState((prev) => ({
+            ...prev,
+            conditions: prev.conditions.map((c) => c.id === id ? { ...c, ...patch } : c),
+        }));
+    }, []);
+    const removeCondition = useCallback((id) => {
+        setState((prev) => ({
+            ...prev,
+            conditions: prev.conditions.filter((c) => c.id !== id),
+        }));
+    }, []);
+    const setOrderBy = useCallback((next) => {
+        setState((prev) => ({ ...prev, orderBy: next }));
+    }, []);
+    const setLimit = useCallback((next) => {
+        setState((prev) => ({ ...prev, limit: next }));
+    }, []);
+    const reset = useCallback(() => {
+        setState(EMPTY_STATE);
+    }, []);
+    const buildQuery = useCallback((base) => {
+        const constraints = [];
+        const orderByConstraints = [];
+        const limitConstraints = [];
+        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;
+        return queryFn(base, ...all);
+    }, [state]);
+    return useMemo(() => ({
+        ...state,
+        addCondition,
+        updateCondition,
+        removeCondition,
+        setOrderBy,
+        setLimit,
+        reset,
+        buildQuery,
+    }), [
+        state,
+        addCondition,
+        updateCondition,
+        removeCondition,
+        setOrderBy,
+        setLimit,
+        reset,
+        buildQuery,
+    ]);
+}
+//# sourceMappingURL=useQueryBuilder.js.map

package/dist/firestore/hooks/useQueryBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryBuilder.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useQueryBuilder.ts"],"names":[],"mappings":"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"}

package/dist/firestore/hooks/useRecursiveDelete.d.ts

@@ -0,0 +1,40 @@
+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 declare function useRecursiveDelete(impl: RecursiveDeleteImpl): UseRecursiveDeleteResult;
+//# sourceMappingURL=useRecursiveDelete.d.ts.map

package/dist/firestore/hooks/useRecursiveDelete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRecursiveDelete.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useRecursiveDelete.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,CACL,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,KAC5C,qBAAqB,CAAC,uBAAuB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,MAAM,EAAE,CAAC,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;IACnB;yBACqB;IACrB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,GACxB,wBAAwB,CA6B1B"}

package/dist/firestore/hooks/useRecursiveDelete.js

@@ -0,0 +1,44 @@
+import { useCallback, useRef, useState } from 'react';
+/**
+ * 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) {
+    const [progress, setProgress] = useState(0);
+    const [isRunning, setIsRunning] = useState(false);
+    const [error, setError] = useState(undefined);
+    const generationRef = useRef(0);
+    const del = useCallback(async (target) => {
+        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 };
+}
+//# sourceMappingURL=useRecursiveDelete.js.map