@pyric/ui 0.1.0-alpha.7

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

@@ -0,0 +1,58 @@
+import type { FieldType } from '../types.js';
+import type { DocumentEditorAction, DocumentEditorState } from '../reducers/types.js';
+export interface UseDocumentEditorOptions {
+    /** Initial document data — the same shape a `DocumentSnapshot.data()`
+     *  call returns. */
+    initial?: Record<string, unknown>;
+}
+export interface UseDocumentEditorResult extends DocumentEditorState {
+    /** Convenience: `errorCount === 0`. */
+    isValid: boolean;
+    /** `true` once any modifying action has fired since the last
+     *  `reset`. Cleared by `reset`. Does NOT clear when the user
+     *  manually re-enters the original values — checking that would
+     *  require a full serialization comparison on every dispatch. */
+    isDirty: boolean;
+    /** Raw dispatch — drops to the reducer-action surface. Prefer the
+     *  named helpers below. */
+    dispatch: (action: DocumentEditorAction) => void;
+    /** Update a leaf value. */
+    setValue: (nodeId: string, value: unknown) => void;
+    /** Switch a node's type. Map/array nodes drop their children. */
+    setType: (nodeId: string, newType: FieldType) => void;
+    /** Set a map-child's key. */
+    setKey: (nodeId: string, key: string) => void;
+    /** Append a child to a map. */
+    addMapEntry: (parentId: string, key: string, childType: FieldType) => void;
+    /** Append a child to an array. Nested arrays are silently
+     *  rejected by the reducer (Firestore disallows them). */
+    addArrayEntry: (parentId: string, childType: FieldType) => void;
+    /** Remove a node (and all its descendants). Removing the root is
+     *  a no-op. */
+    remove: (nodeId: string) => void;
+    /** Restore the tree to its initial state. Clears `isDirty`. */
+    reset: () => void;
+    /** Mark one node touched (dispatch on blur). Gates error display —
+     *  a freshly-added row stays quiet until the user leaves it. */
+    touch: (nodeId: string) => void;
+    /** Mark every node touched (dispatch on a submit attempt) so any
+     *  hidden errors surface at once. */
+    touchAll: () => void;
+    /** Serialize the tree back to a Firestore-shaped object suitable
+     *  for `setDoc` / `updateDoc`. */
+    toData: () => Record<string, unknown>;
+}
+/**
+ * Headless document editor. Owns the entire edit state for one
+ * document via a pure reducer. Consumers either render the bundled
+ * `<DocumentEditor>` compound component over this hook, or render
+ * their own tree using the returned state.
+ *
+ * The hook builds its tree from `initial` on first mount. Changing
+ * `initial` later does NOT rebuild the tree — call `reset()` and
+ * re-initialize if you need that semantics (or remount the hook).
+ * This matches the firebase-tools-ui pattern of treating the
+ * editor as a stateful workspace.
+ */
+export declare function useDocumentEditor(options?: UseDocumentEditorOptions): UseDocumentEditorResult;
+//# sourceMappingURL=useDocumentEditor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentEditor.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useDocumentEditor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,wBAAwB;IACvC;wBACoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB;;;qEAGiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB;+BAC2B;IAC3B,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACjD,2BAA2B;IAC3B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,iEAAiE;IACjE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,KAAK,IAAI,CAAC;IACtD,6BAA6B;IAC7B,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,+BAA+B;IAC/B,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAC3E;8DAC0D;IAC1D,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;IAChE;mBACe;IACf,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;oEACgE;IAChE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;yCACqC;IACrC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;sCACkC;IAClC,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAoFzB"}

package/dist/firestore/hooks/useDocumentEditor.js

@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useReducer, useRef } from 'react';
+import { initState, reducer } from '../reducers/documentEditor.js';
+import { treeToData } from '../reducers/tree.js';
+/**
+ * Headless document editor. Owns the entire edit state for one
+ * document via a pure reducer. Consumers either render the bundled
+ * `<DocumentEditor>` compound component over this hook, or render
+ * their own tree using the returned state.
+ *
+ * The hook builds its tree from `initial` on first mount. Changing
+ * `initial` later does NOT rebuild the tree — call `reset()` and
+ * re-initialize if you need that semantics (or remount the hook).
+ * This matches the firebase-tools-ui pattern of treating the
+ * editor as a stateful workspace.
+ */
+export function useDocumentEditor(options = {}) {
+    const initial = options.initial ?? {};
+    // `useRef` so the initial snapshot is computed once. The reducer
+    // owns the live tree from there on.
+    const initialRef = useRef(null);
+    if (initialRef.current == null) {
+        initialRef.current = initState(initial);
+    }
+    const [state, dispatch] = useReducer(reducer, initialRef.current);
+    const setValue = useCallback((nodeId, value) => dispatch({ type: 'setValue', nodeId, value }), []);
+    const setType = useCallback((nodeId, newType) => dispatch({ type: 'setType', nodeId, newType }), []);
+    const setKey = useCallback((nodeId, key) => dispatch({ type: 'setKey', nodeId, key }), []);
+    const addMapEntry = useCallback((parentId, key, childType) => dispatch({ type: 'addMapEntry', parentId, key, childType }), []);
+    const addArrayEntry = useCallback((parentId, childType) => dispatch({ type: 'addArrayEntry', parentId, childType }), []);
+    const remove = useCallback((nodeId) => dispatch({ type: 'remove', nodeId }), []);
+    const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+    const touch = useCallback((nodeId) => dispatch({ type: 'touch', nodeId }), []);
+    const touchAll = useCallback(() => dispatch({ type: 'touchAll' }), []);
+    const toData = useCallback(() => treeToData(state.tree), [state.tree]);
+    const isDirty = state.tree !== state.initial;
+    const isValid = state.errorCount === 0;
+    return useMemo(() => ({
+        ...state,
+        isDirty,
+        isValid,
+        dispatch,
+        setValue,
+        setType,
+        setKey,
+        addMapEntry,
+        addArrayEntry,
+        remove,
+        reset,
+        touch,
+        touchAll,
+        toData,
+    }), [
+        state,
+        isDirty,
+        isValid,
+        setValue,
+        setType,
+        setKey,
+        addMapEntry,
+        addArrayEntry,
+        remove,
+        reset,
+        touch,
+        touchAll,
+        toData,
+    ]);
+}
+//# sourceMappingURL=useDocumentEditor.js.map

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

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

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

@@ -0,0 +1,45 @@
+import type { CollectionReference, DocumentReference, Query, QueryDocumentSnapshot } from 'pyric/firestore';
+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;
+}
+export interface UseDocumentListResult {
+    documents: QueryDocumentSnapshot[];
+    isLoading: boolean;
+    error: Error | undefined;
+    /** True if there might be another page. The hook tracks this via
+     *  the last fetch's length === pageSize. */
+    hasMore: boolean;
+    /** Fetch the next page and append. */
+    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>;
+    /** Reset pagination and re-fetch from the first page. Useful after
+     *  the consumer mutates data outside this hook. */
+    refresh: () => void;
+}
+/**
+ * Cursor-based paginated document list. Uses `startAfter` against
+ * the last fetched snapshot — the consumer never sees cursor
+ * mechanics. `documents` accumulates across pages.
+ *
+ * Note: this is read-via-get, not realtime. The list updates on
+ * `loadMore` / `createDocument` / `deleteDocument` / `refresh`.
+ * Realtime subscriptions for a collection live in
+ * `useFirestoreCollection`; combining the two (paginated + realtime)
+ * is non-trivial and deferred — see design rationale section M6.
+ */
+export declare function useDocumentList({ collection, query, pageSize, }: UseDocumentListOptions): UseDocumentListResult;
+//# sourceMappingURL=useDocumentList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useDocumentList.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useDocumentList.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,EACL,qBAAqB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,mBAAmB,CAAC;IAChC,sEAAsE;IACtE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB;gDAC4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;qDAMiD;IACjD,cAAc,EAAE,CACd,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;KAAE,KACzC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChC,cAAc,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;uDACmD;IACnD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAC9B,UAAU,EACV,KAAK,EACL,QAAa,GACd,EAAE,sBAAsB,GAAG,qBAAqB,CAqHhD"}

package/dist/firestore/hooks/useDocumentList.js

@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useFirestoreApi } from '../firestoreApi.js';
+/**
+ * Cursor-based paginated document list. Uses `startAfter` against
+ * the last fetched snapshot — the consumer never sees cursor
+ * mechanics. `documents` accumulates across pages.
+ *
+ * Note: this is read-via-get, not realtime. The list updates on
+ * `loadMore` / `createDocument` / `deleteDocument` / `refresh`.
+ * Realtime subscriptions for a collection live in
+ * `useFirestoreCollection`; combining the two (paginated + realtime)
+ * is non-trivial and deferred — see design rationale section M6.
+ */
+export function useDocumentList({ collection, query, pageSize = 50, }) {
+    const [documents, setDocuments] = useState([]);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(undefined);
+    const [hasMore, setHasMore] = useState(false);
+    const [tick, setTick] = 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, query: queryFn, setDoc, startAfter: startAfterFn, } = useFirestoreApi();
+    useEffect(() => {
+        let cancelled = false;
+        setDocuments([]);
+        setHasMore(false);
+        setIsLoading(true);
+        setError(undefined);
+        const baseQuery = query ?? collection;
+        const pagedQuery = queryFn(baseQuery, limitFn(pageSize));
+        getDocs(pagedQuery)
+            .then((snap) => {
+            if (cancelled)
+                return;
+            setDocuments([...snap.docs]);
+            setHasMore(snap.docs.length === pageSize);
+            setIsLoading(false);
+        })
+            .catch((e) => {
+            if (cancelled)
+                return;
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setIsLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [collection, query, pageSize, tick]);
+    const loadMore = useCallback(() => {
+        if (!hasMore || isLoading)
+            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, query, pageSize, documents, hasMore, isLoading]);
+    const createDocument = useCallback(async (id, data, opts) => {
+        if (id == null) {
+            const ref = await addDoc(collection, data);
+            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);
+        setTick((n) => n + 1);
+        return ref;
+    }, [collection]);
+    const deleteDocument = useCallback(async (ref) => {
+        await deleteDoc(ref);
+        setTick((n) => n + 1);
+    }, []);
+    const refresh = useCallback(() => setTick((n) => n + 1), []);
+    return {
+        documents,
+        isLoading,
+        error,
+        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, type 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,EAEL,KAAK,KAAK,EACV,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAC9B,iBAAiB,CAAC,aAAa,CAAC,CA+BlC"}

package/dist/firestore/hooks/useFirestoreCollection.js

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react';
+import { onSnapshot, } from 'pyric/firestore';
+import { coerceError } from './coerceError.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 [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;
+    }, [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;AAC5C,OAAO,EACL,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA+B;IAE/B,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,KAAK,CAAC,CAAC,CAAC;IAEZ,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,17 @@
+import { type DocumentReference, type 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,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,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,CA+BrC"}

package/dist/firestore/hooks/useFirestoreDoc.js

@@ -0,0 +1,34 @@
+import { useEffect, useState } from 'react';
+import { onSnapshot, } from 'pyric/firestore';
+import { coerceError } from './coerceError.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 [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;
+    }, [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;AAC5C,OAAO,EACL,UAAU,GAGX,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQ/C;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAyC;IAEzC,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,GAAG,CAAC,CAAC,CAAC;IAEV,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"}