@pyric/ui/firestore

Interfaces

CollectionListProps

Properties

DeleteWithConfirmProps

Properties

DocumentEditorRootProps

Properties

DocumentEditorState

Reducer state. tree is the live document under edit; initial is the snapshot the editor was constructed from (used to implement reset and isDirty).

Extended by

• UseDocumentEditorResult

Properties

DocumentListProps

Properties

DocumentPreviewProps

Properties

EditorTree

Normalized tree of nodes. nodes is the lookup; childIds is the ordered child list per parent. The root node is itself a map node (its children are the document’s top-level fields).

Properties

FieldDisplayProps

Type Parameters

Properties

FieldEditorContract

Contract for one Firestore value type. Display (read-mode) is required; Edit + validate + defaultValue are required for leaf types that participate in M3’s editor. Map/array contracts supply only Display — their edit affordances come from the <DocumentEditor> compound component.

Type Parameters

Properties

FieldEditProps

Props passed to a per-type Edit component. The leaf editors (string, number, …) consume this directly. Map/array editing is handled by the <DocumentEditor> compound component itself, not by individual editors — Firestore’s container shapes are special enough that pushing them through the registry costs more than it’s worth.

Type Parameters

Properties

FieldNode

One node in the normalized editor tree. Every Firestore field — leaf or container — is a node with a uuid, a parent pointer, a type, and a value. Containers (map, array) carry no value of their own; their children represent the value.

Properties

FieldRendererProps

Properties

ParsedImportDoc

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).

Properties

ParseImportOptions

Properties

ParseImportResult

Properties

QueryBuilderActions

Properties

QueryBuilderProps

Properties

QueryBuilderState

Properties

QueryCondition

Properties

RecursiveDeleteImpl

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.

Properties

RecursiveDeleteProgress

Properties

ReferencePickerProps

Properties

SubscriptionState

Type Parameters

Properties

UseCollectionListOptions

Properties

UseCollectionListResult

Properties

UseDocumentEditorOptions

Properties

UseDocumentEditorResult

Reducer state. tree is the live document under edit; initial is the snapshot the editor was constructed from (used to implement reset and isDirty).

Extends

• DocumentEditorState

Properties

UseDocumentListOptions

Properties

UseDocumentListResult

Properties

UseDocumentSubcollectionsOptions

Properties

UseDocumentSubcollectionsResult

Properties

UseQueryBuilderOptions

Properties

UseRecursiveDeleteResult

Properties

UseReferencePickerOptions

Properties

UseReferencePickerResult

Properties

VectorView

Normalized read-side view of a Firestore vector (embedding) value. Editors and the renderer work against this rather than the raw shape so they don’t have to care which backend produced the value.

Properties

Type Aliases

BrowseLocation

type BrowseLocation =
  | {
  kind: "root";
}
  | {
  kind: "document";
  ref: DocumentReference;
}
  | {
  kind: "collection";
  ref: CollectionReference;
};

DocumentEditorAction

type DocumentEditorAction =
  | {
  nodeId: string;
  type: "setValue";
  value: unknown;
}
  | {
  newType: FieldType;
  nodeId: string;
  type: "setType";
}
  | {
  key: string;
  nodeId: string;
  type: "setKey";
}
  | {
  childType: FieldType;
  key: string;
  parentId: string;
  type: "addMapEntry";
}
  | {
  childType: FieldType;
  parentId: string;
  type: "addArrayEntry";
}
  | {
  nodeId: string;
  type: "remove";
}
  | {
  type: "reset";
}
  | {
  data: Record<string, unknown>;
  type: "replaceData";
}
  | {
  nodeId: string;
  type: "touch";
}
  | {
  type: "touchAll";
};

Discriminated union of every action the reducer accepts. Each action carries a type discriminator plus the data the reducer needs to apply it.

Type Declaration

{
  nodeId: string;
  type: "setValue";
  value: unknown;
}

nodeId

nodeId: string;

type

type: "setValue";

value

value: unknown;

{
  newType: FieldType;
  nodeId: string;
  type: "setType";
}

newType

newType: FieldType;

nodeId

nodeId: string;

type

type: "setType";

{
  key: string;
  nodeId: string;
  type: "setKey";
}

key

key: string;

nodeId

nodeId: string;

type

type: "setKey";

{
  childType: FieldType;
  key: string;
  parentId: string;
  type: "addMapEntry";
}

childType

childType: FieldType;

key

key: string;

parentId

parentId: string;

type

type: "addMapEntry";

{
  childType: FieldType;
  parentId: string;
  type: "addArrayEntry";
}

childType

childType: FieldType;

parentId

parentId: string;

type

type: "addArrayEntry";

{
  nodeId: string;
  type: "remove";
}

nodeId

nodeId: string;

type

type: "remove";

{
  type: "reset";
}

type

type: "reset";

{
  data: Record<string, unknown>;
  type: "replaceData";
}

data

data: Record<string, unknown>;

type

type: "replaceData";

{
  nodeId: string;
  type: "touch";
}

nodeId

nodeId: string;

type

type: "touch";

Mark one node touched (dispatched on blur). Doesn’t change any value — only gates error display for consumers that check it.

{
  type: "touchAll";
}

type

type: "touchAll";

Mark every node touched (dispatched on a submit attempt), so errors that were hidden pre-interaction all surface at once.

FieldEditorRegistry

type FieldEditorRegistry = Partial<Record<FieldType, FieldEditorContract<any>>>;

Map of field-type to editor contract. Partial<…> so consumers can override one type without re-supplying the rest — the merge happens at the <DocumentPreview> boundary.

The stored value type is FieldEditorContract<any> rather than FieldEditorContract<unknown> because each per-type contract narrows its generic (e.g., FieldEditorContract<Timestamp> for timestamp) and TypeScript’s ComponentType is invariant in props. any at the registry layer means the type-safety lives at the per-contract definition site, not in the dispatch map. FieldRenderer narrows back from unknown -> the right contract via inferType at dispatch time.

FieldType

type FieldType =
  | "string"
  | "number"
  | "boolean"
  | "null"
  | "timestamp"
  | "geopoint"
  | "reference"
  | "bytes"
  | "map"
  | "array"
  | "vector";

The set of value types @pyric/ui knows how to display + edit. Maps 1:1 to Firestore’s serializable value shapes; consumers can extend the registry but the built-in editors cover these.

FirestoreApi

type FirestoreApi = Pick<pyric-firestore-reference-api,
  | "addDoc"
  | "collection"
  | "deleteDoc"
  | "doc"
  | "getDoc"
  | "getDocs"
  | "limit"
  | "onSnapshot"
  | "query"
  | "setDoc"
| "startAfter">;

The modular Firestore functions the data hooks call, as an INJECTABLE bundle.

WHY: the hooks default to the in-process pyric/firestore API, but Pyric Studio’s served mode drives the SAME ops over a SharedWorker via a PARALLEL modular client (@pyric/cli/serve/worker: its own collection/getDocs/… over a MessagePort, and a ClientDb that is not a pyric/firestore Firestore). Statically importing the in-process fns hardwires the hooks to the in-page sandbox; reading them from this context lets a consumer inject the worker client’s fns so the hooks operate on the live worker backend without the hooks (or the components) knowing which backend they hit.

The bundle is typed to the in-process signatures. A worker bundle is adapted (cast) to this shape at the Studio boundary: the worker handles + snapshots are runtime-compatible at the surface the hooks use (.id / .data() / .docs / .ref), which is the contract function-injection relies on.

Default = the real pyric/firestore fns, so every existing consumer (the dev-seed review build, tests, any app embedding @pyric/ui) is unchanged: no provider needed unless you are swapping the backend.

ListSubcollections()

type ListSubcollections = (firestore: Firestore, parent: DocumentReference) => Promise<CollectionReference[]>;

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).

Parameters

Returns

Promise<CollectionReference[]>

QueryOp

type QueryOp = WhereFilterOp;

UseQueryBuilderResult

type UseQueryBuilderResult = QueryBuilderState & QueryBuilderActions;

Variables

defaultFieldEditors

const defaultFieldEditors: FieldEditorRegistry;

Default registry. Covers every FieldType. Consumers extend or override by passing their own (partial) registry into <DocumentPreview> / <FieldRenderer> — the components merge overrides into these defaults so a consumer can swap just one editor without re-declaring the rest.

DocumentEditor

const DocumentEditor: {
  Fields: typeof DocumentEditorFields;
  Root: typeof DocumentEditorRoot;
};

Compound root export. Consumers pattern-match via dot access:

<DocumentEditor.Root initial={data} onChange={…}> <DocumentEditor.Fields /> </DocumentEditor.Root>

Type Declaration

Fields

Fields: typeof DocumentEditorFields;

Root

Root: typeof DocumentEditorRoot;

MULTI_VALUE_OPS

const MULTI_VALUE_OPS: ReadonlySet<QueryOp>;

Ops that accept an array of values. The value editor in the bundled parses the input as JSON for these.

QUERY_OPS

const QUERY_OPS: readonly QueryOp[];

Functions

asVectorView()

function asVectorView(value: unknown): VectorView;

Detect + normalize a Firestore vector value, or return null if the value isn’t a vector. Vectors reach @pyric/ui in several runtime shapes depending on the backend the snapshot came from — there is no single VectorValue class pyric/firestore re-exports, so we match structurally (the same strategy isDocumentReferenceShape uses for refs):

1. pyric Vector wrapper — frozen .value: number[] array plus a .dimension getter (sandbox / rules-side reads).
2. firebase/firestore (web) VectorValue — exposes .toArray() and nothing else publicly.
3. firebase-admin VectorValue — internal ._values: number[] (also a .toArray()).
4. wire sentinel — { __type__: '__vector__', value: number[] }, the plain-object encoded form a discover crawler / seed emits.

A bare number[] is intentionally NOT a vector — those stay array. Only the typed/branded shapes above match.

Parameters

Returns

VectorView

CollectionList()

function CollectionList(__namedParameters: CollectionListProps): Element;

Headless collection list. Takes a pre-fetched array of references (from useCollectionList) plus a select callback. Renders one row per collection with data-pyric-collection-id for styling and testing. The library does not own the data fetch — the hook does — so this component is a thin presentational layer.

Parameters

Returns

Element

DeleteWithConfirm()

function DeleteWithConfirm(__namedParameters: DeleteWithConfirmProps): Element;

Composition that wires useConfirm + useRecursiveDelete. Requires a <ConfirmProvider> ancestor.

The default trigger renders a plain <button> carrying the destructive intent (the consumer styles via [data-pyric-destructive]). Consumers wanting different chrome pass renderTrigger.

Parameters

Returns

Element

detectCollisions()

function detectCollisions(existingIds: readonly string[], docs: readonly ParsedImportDoc[]): string[];

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.

Parameters

Returns

string[]

DocumentEditorFields()

function DocumentEditorFields(): Element;

Renders the top-level fields of the document. For finer control, a consumer can call useDocumentEditorContext() and render the tree themselves.

Returns

Element

DocumentEditorRoot()

function DocumentEditorRoot(__namedParameters: DocumentEditorRootProps): Element;

Wires the useDocumentEditor hook + field-editor registry into a React context so <DocumentEditor.Fields> and <DocumentEditor.AddField> can render the tree without prop drilling.

Pattern: hook + compound component. Consumers wanting full control over the layout call useDocumentEditor directly and render their own tree; consumers wanting the default rendering use this.

Parameters

Returns

Element

DocumentList()

function DocumentList(__namedParameters: DocumentListProps): Element;

Headless document list. Below virtualizeThreshold, renders a plain <ul>; above it, switches to TanStack-Virtual via <VirtualList> so 10k-doc collections don’t bloat the DOM.

The hook owns pagination state; this component just renders. The Load More button only renders when hasMore is true AND onLoadMore is provided. Consumers wanting infinite scroll trigger onLoadMore from a sentinel IntersectionObserver in their own code — the component doesn’t bake that policy in.

Parameters

Returns

Element

DocumentPreview()

function DocumentPreview(__namedParameters: DocumentPreviewProps): Element;

Read-only renderer for a Firestore document. Iterates top-level fields in lexicographic order; each field dispatches through the field-editor registry on its inferred type.

Headless — no shipped CSS. Consumers style via className on the root and [data-pyric-field-type] / [data-pyric-field-path] attribute selectors on the per-field nodes.

Editing arrives in M3 (<DocumentEditor>). M2 only displays.

Parameters

Returns

Element

FieldRenderer()

function FieldRenderer(__namedParameters: FieldRendererProps): Element;

Dispatches a single value to its registered display component. Recursive editors (Map, Array) re-enter through this component for their children, threading the same registry.

Parameters

Returns

Element

FirestoreApiProvider()

function FirestoreApiProvider(__namedParameters: {
  children: ReactNode;
  value: FirestoreApi;
}): FunctionComponentElement<ProviderProps<FirestoreApi>>;

Provide a Firestore API bundle to the subtree. Pyric Studio wraps its data surface with this, supplying the in-process bundle for dev-seed review and the SharedWorker client bundle under pyric dev --ui.

Parameters

Returns

FunctionComponentElement<ProviderProps<FirestoreApi>>

firestoreAutoId()

function firestoreAutoId(): string;

A Firestore-style 20-char auto id (same alphabet/length the SDK uses).

Returns

string

firestoreValuesEqual()

function firestoreValuesEqual(previous: unknown, next: unknown): boolean;

Firestore-aware structural equality for values delivered by either the in-process SDK or the SharedWorker serializer.

Parameters

Returns

boolean

inferType()

function inferType(value: unknown): FieldType;

Runtime-classify a value into one of the FieldTypes.

The discrimination order matters:

• null checked before typeof === 'object' (null is an object)
• vector (a typed embedding wrapper) checked before Array.isArray and before generic objects — its wire-sentinel shape is a plain object, and a bare number[] must stay array, not vector
• Array.isArray checked before generic objects
• Firestore special types (Timestamp/GeoPoint/Bytes/DocumentRef) checked before falling through to map

undefined values aren’t legal Firestore field values; we coerce them to 'null' rather than throw — the caller can decide whether to display or filter.

Parameters

Returns

FieldType

initState()

function initState(initial: Record<string, unknown>): DocumentEditorState;

Initial state factory. Builds tree + initial snapshot + error count.

Parameters

Returns

DocumentEditorState

mergeFieldEditors()

function mergeFieldEditors(override: Partial<Record<FieldType, FieldEditorContract<any>>>): FieldEditorRegistry;

Merge a consumer-supplied registry over the defaults. undefined input returns the defaults as-is. Used internally by <DocumentPreview> so consumers don’t have to spread manually.

Parameters

Returns

FieldEditorRegistry

parseImport()

function parseImport(input: string, options?: ParseImportOptions): ParseImportResult;

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.

Parameters

Returns

ParseImportResult

QueryBuilder()

function QueryBuilder(__namedParameters: QueryBuilderProps): Element;

Default visible composition over useQueryBuilder. Renders the condition list + orderBy + limit form. Headless — every node carries data-pyric-* for styling.

Values are JSON-parsed on input. 42, "text", true, null, and [1, 2, 3] (for in/not-in/array-contains-any) all work; raw strings that aren’t JSON-parsable fall through as-is. For non-JSON Firestore values (Timestamp, GeoPoint, Reference, Bytes), consumers either use the hook directly with their own value editors or swap the rendered component out.

Parameters

Returns

Element

reducer()

function reducer(state: DocumentEditorState, action: DocumentEditorAction): DocumentEditorState;

Pure reducer. Every action returns a fresh state — no in-place mutation of state.tree. Validation re-runs after the structural change so errorCount is always current. Container nodes (map / array) ignore actions that don’t apply to them rather than throwing; the components only render valid affordances per type.

Parameters

Returns

DocumentEditorState

ReferencePicker()

function ReferencePicker(__namedParameters: ReferencePickerProps): Element;

Visible reference picker — text input + browseable panel.

Two ways to commit a reference:

1. Type a path, then click Commit (enabled only when the path parses to a valid DocumentReference).
2. Drill into a collection in the panel and click a document row.

Either path fires onPick(ref). Headless — emits structural data-pyric-* for styling.

Parameters

Returns

Element

treeFromData()

function treeFromData(data: Record<string, unknown>): EditorTree;

Build a normalized editor tree from a Firestore-shaped object. The root node is a virtual map that holds the document’s top-level fields. Order of children mirrors Object.entries (the renderer is responsible for any sort it wants).

Parameters

Returns

EditorTree

treeToData()

function treeToData(tree: EditorTree): Record<string, unknown>;

Serialize a tree back to a Firestore-shaped object. Leaf values pass through unchanged (so a Timestamp round-trips as the same Timestamp instance). Maps recurse with their sorted keys; arrays recurse in childIds order.

Parameters

Returns

Record<string, unknown>

truncateVectorsForDisplay()

function truncateVectorsForDisplay(value: unknown): unknown;

Deep-replace any vector-shaped value with a compact preview STRING, so the result can be JSON.stringify’d / formatted without dumping full embeddings. Recurses plain objects + arrays; class instances (Timestamp/GeoPoint) and scalars pass through untouched. Vector instances/sentinels are caught first.

Parameters

Returns

unknown

useCollectionList()

function useCollectionList(__namedParameters: UseCollectionListOptions): UseCollectionListResult;

Operational read + create for collections under a parent (or root). Listing is injected because the modular Web SDK doesn’t expose a native listCollections on the client — see options docs.

Parameters

Returns

UseCollectionListResult

useDocumentEditor()

function useDocumentEditor(options?: UseDocumentEditorOptions): UseDocumentEditorResult;

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; live viewers explicitly call replaceData() when a newer snapshot should become the clean baseline. This matches the firebase-tools-ui pattern of treating the editor as a stateful workspace while still allowing snapshot-driven reconciliation.

Parameters

Returns

UseDocumentEditorResult

useDocumentEditorContext()

function useDocumentEditorContext(): UseDocumentEditorResult;

Read access to the underlying editor state from inside a Root.

Returns

UseDocumentEditorResult

useDocumentList()

function useDocumentList(__namedParameters: UseDocumentListOptions): UseDocumentListResult;

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.

Parameters

Returns

UseDocumentListResult

useDocumentSubcollections()

function useDocumentSubcollections(__namedParameters: UseDocumentSubcollectionsOptions): UseDocumentSubcollectionsResult;

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).

Parameters

Returns

UseDocumentSubcollectionsResult

useFirestoreApi()

function useFirestoreApi(): FirestoreApi;

Read the active Firestore API bundle (defaults to in-process pyric/firestore).

Returns

FirestoreApi

useFirestoreCollection()

function useFirestoreCollection(query: Query<DocumentData>): SubscriptionState<QuerySnapshot<DocumentData>>;

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.

Parameters

Returns

SubscriptionState<QuerySnapshot<DocumentData>>

useFirestoreDoc()

function useFirestoreDoc(ref: DocumentReference<DocumentData>): SubscriptionState<DocumentSnapshot<DocumentData>>;

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.

Parameters

Returns

SubscriptionState<DocumentSnapshot<DocumentData>>

useQueryBuilder()

function useQueryBuilder(options?: UseQueryBuilderOptions): UseQueryBuilderResult;

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.

Parameters

Returns

UseQueryBuilderResult

useRecursiveDelete()

function useRecursiveDelete(impl: RecursiveDeleteImpl): UseRecursiveDeleteResult;

Drive a 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.

Parameters

Returns

UseRecursiveDeleteResult

useReferencePicker()

function useReferencePicker(__namedParameters: UseReferencePickerOptions): UseReferencePickerResult;

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.

Parameters

Returns

UseReferencePickerResult

validateCollectionId()

function validateCollectionId(id: string): string;

Validate a collection id. Returns an error message, or undefined when valid.

Parameters

Returns

string

validateDocumentId()

function validateDocumentId(id: string): string;

Validate a document id. Returns an error message, or undefined when valid.

Parameters

Returns

string

validateLeaf()

function validateLeaf(type: FieldType, value: unknown): string;

Per-type leaf validator. Returns an error message when the value doesn’t satisfy the type’s constraints, undefined when valid.

map and array aren’t validated here — their integrity comes from their children + (for maps) sibling-key uniqueness, which is enforced in validateTree.

Parameters

Returns

string

validateTree()

function validateTree(tree: EditorTree): {
  errorCount: number;
  tree: EditorTree;
};

Walk the tree, attach an error to each node, and return the mutated tree along with the total error count. The function does not mutate the input; it returns a fresh tree.

Per-leaf errors come from validateLeaf. Map nodes additionally surface duplicate-key + empty-key errors on the offending children (not on the parent).

Parameters

Returns

{
  errorCount: number;
  tree: EditorTree;
}

errorCount

errorCount: number;

tree

tree: EditorTree;

vectorPreview()

function vectorPreview(view: VectorView): string;

Compact, display-safe rendering of a vector: vector · <dim> [a, b, c, …]. So a real embedding never dumps its full array into a diff, a rules trace, or a debugger panel.

Parameters

Returns

string