@pyric/ui 0.1.0-alpha.7

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"useRecursiveDelete.js","sourceRoot":"","sources":["../../../src/firestore/hooks/useRecursiveDelete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAkCtD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAyB;IAEzB,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5C,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;IACjE,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAEhC,MAAM,GAAG,GAAG,WAAW,CACrB,KAAK,EAAE,MAA+C,EAAE,EAAE;QACxD,MAAM,KAAK,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC;QACtC,WAAW,CAAC,CAAC,CAAC,CAAC;QACf,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpB,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3C,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO;oBAAE,OAAO;gBAC5C,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;gBAC9B,IAAI,GAAG,CAAC,IAAI;oBAAE,MAAM;YACtB,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO;gBAAE,OAAO;YAC5C,QAAQ,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,EACD,CAAC,IAAI,CAAC,CACP,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,70 @@
+import { type CollectionReference, type DocumentReference, type Firestore, type QueryDocumentSnapshot } from 'pyric/firestore';
+export type BrowseLocation = {
+    kind: 'root';
+} | {
+    kind: 'document';
+    ref: DocumentReference;
+} | {
+    kind: 'collection';
+    ref: CollectionReference;
+};
+export interface UseReferencePickerOptions {
+    firestore: Firestore;
+    /**
+     * Lister for subcollections under a parent (or root when
+     * `parent == null`). The library does not ship a default — see
+     * `useCollectionList` for the same rationale (the modular Web SDK
+     * can't enumerate collections client-side).
+     */
+    listCollections: (firestore: Firestore, parent: DocumentReference | null) => Promise<CollectionReference[]>;
+    /** Default page size for the document list when browsing inside
+     *  a collection. Default 20. */
+    pageSize?: number;
+    /** Initial value to pre-populate the text input + parse. */
+    initialPath?: string;
+}
+export interface UseReferencePickerResult {
+    /** Current text input value. */
+    pathInput: string;
+    /** Validated `DocumentReference` parsed from `pathInput`, or
+     *  `null` when the path is empty / invalid. */
+    reference: DocumentReference | null;
+    /** Parse error, or `null` when valid. */
+    error: string | null;
+    /** Current browse position in the tree. */
+    browseLocation: BrowseLocation;
+    /** Whether `drillBack` has anywhere to go. */
+    canDrillBack: boolean;
+    /** Collections available at the current browse level. Populated
+     *  when `browseLocation` is `root` or `document`. */
+    collections: CollectionReference[];
+    /** First page of documents in the current collection — populated
+     *  when `browseLocation.kind === 'collection'`. */
+    documents: QueryDocumentSnapshot[];
+    /** True while a fetch is in flight. */
+    isLoading: boolean;
+    /** Set the text-input value. Parses on every change. */
+    setPathInput: (path: string) => void;
+    /** Commit a chosen reference. Updates `pathInput` (and therefore
+     *  the parsed `reference`). */
+    pick: (ref: DocumentReference) => void;
+    /** Drill into a collection — fetches its first page of documents. */
+    drillIntoCollection: (ref: CollectionReference) => void;
+    /** Drill into a document — fetches its subcollections. */
+    drillIntoDocument: (ref: DocumentReference) => void;
+    /** Step back one level. No-op when at root. */
+    drillBack: () => void;
+    /** Clear the path input + reset browse to root. */
+    clear: () => void;
+}
+/**
+ * Picker state machine. Browses a Firestore tree level-by-level
+ * (root → collection → document → collection → ...), maintains a
+ * separately-validated text-input path, and commits a chosen
+ * reference via `pick`.
+ *
+ * Headless — consumers compose the resulting state into their own
+ * UI, or use the bundled `<ReferencePicker>` component.
+ */
+export declare function useReferencePicker({ firestore, listCollections, pageSize, initialPath, }: UseReferencePickerOptions): UseReferencePickerResult;
+//# sourceMappingURL=useReferencePicker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useReferencePicker.d.ts","sourceRoot":"","sources":["../../../src/firestore/hooks/useReferencePicker.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,iBAAiB,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAErD,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB;;;;;OAKG;IACH,eAAe,EAAE,CACf,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,iBAAiB,GAAG,IAAI,KAC7B,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IACpC;oCACgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB;mDAC+C;IAC/C,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,yCAAyC;IACzC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2CAA2C;IAC3C,cAAc,EAAE,cAAc,CAAC;IAC/B,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;IACtB;yDACqD;IACrD,WAAW,EAAE,mBAAmB,EAAE,CAAC;IACnC;uDACmD;IACnD,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,uCAAuC;IACvC,SAAS,EAAE,OAAO,CAAC;IAEnB,wDAAwD;IACxD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;mCAC+B;IAC/B,IAAI,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACvC,qEAAqE;IACrE,mBAAmB,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACxD,0DAA0D;IAC1D,iBAAiB,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACpD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,mDAAmD;IACnD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,SAAS,EACT,eAAe,EACf,QAAa,EACb,WAAgB,GACjB,EAAE,yBAAyB,GAAG,wBAAwB,CAiHtD"}

package/dist/firestore/hooks/useReferencePicker.js

@@ -0,0 +1,140 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { doc as docFn, getDocs, limit as limitFn, query as queryFn, } from 'pyric/firestore';
+function parseReferencePath(firestore, path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return { ref: null, error: null };
+    const segments = trimmed.split('/').filter(Boolean);
+    if (segments.length === 0)
+        return { ref: null, error: 'Empty path' };
+    if (segments.length % 2 !== 0)
+        return { ref: null, error: 'Must point to a document (even segment count)' };
+    try {
+        const ref = docFn(firestore, trimmed);
+        return { ref, error: null };
+    }
+    catch (e) {
+        return {
+            ref: null,
+            error: e instanceof Error ? e.message : 'Invalid path',
+        };
+    }
+}
+const ROOT = { kind: 'root' };
+/**
+ * Picker state machine. Browses a Firestore tree level-by-level
+ * (root → collection → document → collection → ...), maintains a
+ * separately-validated text-input path, and commits a chosen
+ * reference via `pick`.
+ *
+ * Headless — consumers compose the resulting state into their own
+ * UI, or use the bundled `<ReferencePicker>` component.
+ */
+export function useReferencePicker({ firestore, listCollections, pageSize = 20, initialPath = '', }) {
+    const [pathInput, setPathInputState] = useState(initialPath);
+    const [browse, setBrowse] = useState({
+        current: ROOT,
+        history: [],
+    });
+    const [collections, setCollections] = useState([]);
+    const [documents, setDocuments] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const parsed = useMemo(() => parseReferencePath(firestore, pathInput), [firestore, pathInput]);
+    // Keep the injected `listCollections` in a ref so the fetch
+    // effect's deps don't include it. Consumers commonly pass an
+    // inline arrow function whose identity churns on every render;
+    // depending on it would loop the effect forever.
+    const listCollectionsRef = useRef(listCollections);
+    listCollectionsRef.current = listCollections;
+    // Re-fetch contents whenever the browse location changes.
+    useEffect(() => {
+        let cancelled = false;
+        setIsLoading(true);
+        const loc = browse.current;
+        if (loc.kind === 'root' || loc.kind === 'document') {
+            const parent = loc.kind === 'document' ? loc.ref : null;
+            setDocuments([]);
+            listCollectionsRef.current(firestore, parent)
+                .then((cs) => {
+                if (cancelled)
+                    return;
+                setCollections(cs);
+                setIsLoading(false);
+            })
+                .catch(() => {
+                if (cancelled)
+                    return;
+                setCollections([]);
+                setIsLoading(false);
+            });
+        }
+        else {
+            setCollections([]);
+            const pagedQuery = queryFn(loc.ref, limitFn(pageSize));
+            getDocs(pagedQuery)
+                .then((snap) => {
+                if (cancelled)
+                    return;
+                setDocuments([...snap.docs]);
+                setIsLoading(false);
+            })
+                .catch(() => {
+                if (cancelled)
+                    return;
+                setDocuments([]);
+                setIsLoading(false);
+            });
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [browse.current, firestore, pageSize]);
+    const setPathInput = useCallback((path) => {
+        setPathInputState(path);
+    }, []);
+    const pick = useCallback((ref) => {
+        setPathInputState(ref.path);
+    }, []);
+    const drillIntoCollection = useCallback((ref) => {
+        setBrowse((prev) => ({
+            current: { kind: 'collection', ref },
+            history: [...prev.history, prev.current],
+        }));
+    }, []);
+    const drillIntoDocument = useCallback((ref) => {
+        setBrowse((prev) => ({
+            current: { kind: 'document', ref },
+            history: [...prev.history, prev.current],
+        }));
+    }, []);
+    const drillBack = useCallback(() => {
+        setBrowse((prev) => {
+            if (prev.history.length === 0)
+                return prev;
+            const next = prev.history.slice(0, -1);
+            const popped = prev.history[prev.history.length - 1];
+            return { current: popped, history: next };
+        });
+    }, []);
+    const clear = useCallback(() => {
+        setPathInputState('');
+        setBrowse({ current: ROOT, history: [] });
+    }, []);
+    return {
+        pathInput,
+        reference: parsed.ref,
+        error: parsed.error,
+        browseLocation: browse.current,
+        canDrillBack: browse.history.length > 0,
+        collections,
+        documents,
+        isLoading,
+        setPathInput,
+        pick,
+        drillIntoCollection,
+        drillIntoDocument,
+        drillBack,
+        clear,
+    };
+}
+//# sourceMappingURL=useReferencePicker.js.map

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

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

package/dist/firestore/import/parseImport.d.ts

@@ -0,0 +1,55 @@
+/**
+ * JSON import parsing + collision detection for the Firestore "import JSON
+ * into a collection" flow.
+ *
+ * Pure, no React, no I/O: `parseImport` takes the raw pasted/loaded text and
+ * returns the documents it would create plus any per-item errors; the caller
+ * (the Studio pane) owns showing the "will create N documents" preview,
+ * disclosing a collision policy ONLY when {@link detectCollisions} finds an
+ * overlap, and actually writing through the existing Firestore write handle.
+ *
+ * Two accepted shapes:
+ *   1. A map:   `{ "docId": { ...fields }, "docId2": { ...fields } }`
+ *      — each key becomes the document id (validated), each value its data.
+ *   2. An array: `[ { ...fields }, { ...fields } ]`
+ *      — each element becomes a document with `id: null` (auto-id at write
+ *      time), since a bare array carries no natural id.
+ */
+/** One document to create. `id === null` means "let Firestore auto-id it"
+ *  (only produced by the array shape when no `generateId` option is given —
+ *  a map key is always a chosen id). */
+export interface ParsedImportDoc {
+    id: string | null;
+    data: Record<string, unknown>;
+}
+export interface ParseImportOptions {
+    /** When provided, array-shape entries get their auto-id GENERATED AT PARSE
+     *  TIME (instead of `id: null` / addDoc-at-write-time). Fixing ids at parse
+     *  makes a retry after a partial failure idempotent: the same parse's ids
+     *  are reused, so re-running the import cannot duplicate already-written
+     *  docs. Use {@link firestoreAutoId} for prod-parity ids. */
+    generateId?: () => string;
+}
+/** A Firestore-style 20-char auto id (same alphabet/length the SDK uses). */
+export declare function firestoreAutoId(): string;
+export interface ParseImportResult {
+    docs: ParsedImportDoc[];
+    /** Human-readable problems found while parsing. A non-empty `errors` does
+     *  NOT necessarily mean `docs` is empty — the parser is per-item tolerant
+     *  so one bad entry doesn't block the rest; the caller decides whether to
+     *  block on any error or proceed with the valid subset. */
+    errors: string[];
+}
+/**
+ * Parse raw JSON text into the documents it would create. Never throws —
+ * a JSON syntax error or a wrong top-level shape becomes an entry in
+ * `errors` with an empty `docs` array.
+ */
+export declare function parseImport(input: string, options?: ParseImportOptions): ParseImportResult;
+/**
+ * Ids in `docs` (map-shape entries only — `id !== null`) that already exist
+ * in `existingIds`. The UI shows the skip-or-overwrite policy choice ONLY
+ * when this returns a non-empty list.
+ */
+export declare function detectCollisions(existingIds: readonly string[], docs: readonly ParsedImportDoc[]): string[];
+//# sourceMappingURL=parseImport.d.ts.map

package/dist/firestore/import/parseImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseImport.d.ts","sourceRoot":"","sources":["../../../src/firestore/import/parseImport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;wCAEwC;AACxC,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;iEAI6D;IAC7D,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC;CAC3B;AAID,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB;;;+DAG2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CA+C1F;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,MAAM,EAAE,CAOV"}

package/dist/firestore/import/parseImport.js

@@ -0,0 +1,101 @@
+/**
+ * JSON import parsing + collision detection for the Firestore "import JSON
+ * into a collection" flow.
+ *
+ * Pure, no React, no I/O: `parseImport` takes the raw pasted/loaded text and
+ * returns the documents it would create plus any per-item errors; the caller
+ * (the Studio pane) owns showing the "will create N documents" preview,
+ * disclosing a collision policy ONLY when {@link detectCollisions} finds an
+ * overlap, and actually writing through the existing Firestore write handle.
+ *
+ * Two accepted shapes:
+ *   1. A map:   `{ "docId": { ...fields }, "docId2": { ...fields } }`
+ *      — each key becomes the document id (validated), each value its data.
+ *   2. An array: `[ { ...fields }, { ...fields } ]`
+ *      — each element becomes a document with `id: null` (auto-id at write
+ *      time), since a bare array carries no natural id.
+ */
+import { validateDocumentId } from '../validation/ids.js';
+const AUTO_ID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** A Firestore-style 20-char auto id (same alphabet/length the SDK uses). */
+export function firestoreAutoId() {
+    let id = '';
+    for (let i = 0; i < 20; i++) {
+        id += AUTO_ID_ALPHABET.charAt(Math.floor(Math.random() * AUTO_ID_ALPHABET.length));
+    }
+    return id;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Parse raw JSON text into the documents it would create. Never throws —
+ * a JSON syntax error or a wrong top-level shape becomes an entry in
+ * `errors` with an empty `docs` array.
+ */
+export function parseImport(input, options) {
+    const trimmed = input.trim();
+    if (trimmed === '') {
+        return { docs: [], errors: ['Input is empty'] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (e) {
+        return { docs: [], errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`] };
+    }
+    const docs = [];
+    const errors = [];
+    if (Array.isArray(parsed)) {
+        parsed.forEach((item, i) => {
+            if (!isPlainObject(item)) {
+                errors.push(`Item ${i}: expected an object, got ${describeType(item)}`);
+                return;
+            }
+            docs.push({ id: options?.generateId ? options.generateId() : null, data: item });
+        });
+        return { docs, errors };
+    }
+    if (isPlainObject(parsed)) {
+        for (const [key, value] of Object.entries(parsed)) {
+            const idError = validateDocumentId(key);
+            if (idError) {
+                errors.push(`"${key}": invalid document id — ${idError}`);
+                continue;
+            }
+            if (!isPlainObject(value)) {
+                errors.push(`"${key}": expected an object of fields, got ${describeType(value)}`);
+                continue;
+            }
+            docs.push({ id: key, data: value });
+        }
+        return { docs, errors };
+    }
+    return {
+        docs: [],
+        errors: ['Input must be a JSON object mapping docId -> fields, or an array of objects'],
+    };
+}
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value;
+}
+/**
+ * Ids in `docs` (map-shape entries only — `id !== null`) that already exist
+ * in `existingIds`. The UI shows the skip-or-overwrite policy choice ONLY
+ * when this returns a non-empty list.
+ */
+export function detectCollisions(existingIds, docs) {
+    const existing = new Set(existingIds);
+    const collisions = [];
+    for (const doc of docs) {
+        if (doc.id !== null && existing.has(doc.id))
+            collisions.push(doc.id);
+    }
+    return collisions;
+}
+//# sourceMappingURL=parseImport.js.map

package/dist/firestore/import/parseImport.js.map

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

package/dist/firestore/index.d.ts

@@ -0,0 +1,20 @@
+export * from './hooks/index.js';
+export { FirestoreApiProvider, useFirestoreApi, type FirestoreApi, } from './firestoreApi.js';
+export { inferType, asVectorView, vectorPreview, truncateVectorsForDisplay, type FieldType, type VectorView, } from './types.js';
+export { defaultFieldEditors, mergeFieldEditors, } from './fieldEditors/registry.js';
+export type { FieldEditorContract, FieldEditorRegistry, FieldDisplayProps, FieldEditProps, } from './fieldEditors/types.js';
+export { FieldRenderer, type FieldRendererProps } from './components/FieldRenderer.js';
+export { DocumentPreview, type DocumentPreviewProps, } from './components/DocumentPreview.js';
+export type { FieldNode, EditorTree, DocumentEditorAction, DocumentEditorState, } from './reducers/types.js';
+export { validateLeaf, validateTree } from './reducers/validation.js';
+export { treeFromData, treeToData } from './reducers/tree.js';
+export { initState, reducer } from './reducers/documentEditor.js';
+export { DocumentEditor, DocumentEditorRoot, DocumentEditorFields, useDocumentEditorContext, type DocumentEditorRootProps, } from './components/DocumentEditor.js';
+export { CollectionList, type CollectionListProps } from './components/CollectionList.js';
+export { DocumentList, type DocumentListProps } from './components/DocumentList.js';
+export { DeleteWithConfirm, type DeleteWithConfirmProps, } from './components/DeleteWithConfirm.js';
+export { ReferencePicker, type ReferencePickerProps, } from './components/ReferencePicker.js';
+export { QueryBuilder, type QueryBuilderProps, } from './components/QueryBuilder.js';
+export { validateCollectionId, validateDocumentId } from './validation/ids.js';
+export { parseImport, detectCollisions, firestoreAutoId, type ParsedImportDoc, type ParseImportResult, type ParseImportOptions, } from './import/parseImport.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/firestore/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/firestore/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AAIjC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,EACb,yBAAyB,EACzB,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AAGzC,YAAY,EACV,SAAS,EACT,UAAU,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACpF,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAG3C,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,GACvB,MAAM,8BAA8B,CAAC;AAMtC,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,yBAAyB,CAAC"}