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

package/src/firestore/fieldEditors/types.ts

@@ -0,0 +1,68 @@
+import type { ComponentType } from 'react';
+import type { FieldType } from '../types.js';
+
+export interface FieldDisplayProps<V = unknown> {
+  /** Value to display. The component's `V` generic narrows this. */
+  value: V;
+  /** Dotted/bracketed path from the document root, e.g. `users.alice`
+   *  or `tags[0]`. Forwarded so consumer styles can target nested
+   *  positions via `[data-field-path="users.alice"]`. */
+  path?: string;
+  /** Recursive editors (Map, Array) need the registry to dispatch
+   *  on their children. Leaf editors (String, Number, …) can ignore
+   *  this prop. Required-but-optional because the consumer of the
+   *  component (`<FieldRenderer>`, `<DocumentPreview>`) always
+   *  threads it through. */
+  fieldEditors?: FieldEditorRegistry;
+}
+
+/**
+ * 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.
+ */
+export interface FieldEditProps<V = unknown> {
+  /** Current value. */
+  value: V;
+  /** Commit a new value. The hook wires this to the reducer's
+   *  `setValue` action. */
+  onChange: (next: V) => void;
+  /** Validation error attached by the reducer. Editors render it
+   *  inline alongside the input. */
+  error?: string;
+  /** Dotted/bracketed path from the document root. */
+  path?: string;
+}
+
+/**
+ * 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.
+ */
+export interface FieldEditorContract<V = unknown> {
+  type: FieldType;
+  Display: ComponentType<FieldDisplayProps<V>>;
+  Edit?: ComponentType<FieldEditProps<V>>;
+}
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type FieldEditorRegistry = Partial<Record<FieldType, FieldEditorContract<any>>>;

package/src/firestore/fieldEditors/vector.tsx

@@ -0,0 +1,142 @@
+import { useState } from 'react';
+import { asVectorView, type VectorView } from '../types.js';
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+/** How many leading components to show in the truncated preview. The
+ *  mock (`c-data.html`) renders four then an ellipsis. */
+const PREVIEW_COUNT = 4;
+
+/**
+ * Render a `[a, b, c, … ]` preview of the first {@link PREVIEW_COUNT}
+ * components. A vector that's already short enough is shown in full
+ * without the trailing ellipsis.
+ */
+function previewText(values: number[]): string {
+  if (values.length <= PREVIEW_COUNT) {
+    return `[${values.join(', ')}]`;
+  }
+  const head = values.slice(0, PREVIEW_COUNT).join(', ');
+  return `[${head}, …]`;
+}
+
+/**
+ * Read view for a vector (embedding). Mirrors the mock: a
+ * `vector · <dims>` type chip plus a truncated value preview. The full
+ * 768-float array is never rendered inline — it's noise and a perf
+ * hazard. `data-dimension` carries the dimension for styling/queries.
+ */
+function VectorDisplay({ value, path }: FieldDisplayProps<unknown>) {
+  const view = asVectorView(value);
+  if (!view) {
+    // Should be unreachable: the renderer only dispatches here when
+    // `inferType` already classified the value as `vector`. Render a
+    // defensive empty marker rather than throwing.
+    return (
+      <span data-pyric-field-type="vector" data-pyric-field-path={path} />
+    );
+  }
+  return (
+    <span
+      data-pyric-field-type="vector"
+      data-pyric-field-path={path}
+      data-dimension={String(view.dimension)}
+    >
+      <span data-pyric-vector-dims>{`vector · ${view.dimension}`}</span>
+      <span data-pyric-vector-preview>{previewText(view.values)}</span>
+    </span>
+  );
+}
+
+/**
+ * Result of parsing the raw-replace textarea. `ok` carries the new
+ * wire-sentinel value to commit; otherwise `error` is a human message.
+ * Exported (and pure) so the parse/validation contract is unit-testable
+ * without the JSDOM text-input event path, which is broken under this
+ * repo's bun:test + JSDOM setup (see DocumentEditor.test.tsx note).
+ */
+export type ParsedVectorInput =
+  | { ok: true; value: { __type__: '__vector__'; value: number[] } }
+  | { ok: false; error: string };
+
+/**
+ * Parse the textarea contents into a wire-sentinel vector, or an error.
+ * Accepts only a JSON array of numbers — the whole-value replace
+ * contract. Anything else (bad JSON, non-array, non-numeric element)
+ * is rejected and the previous value is kept by the caller.
+ */
+export function parseVectorInput(text: string): ParsedVectorInput {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, error: 'Invalid JSON' };
+  }
+  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === 'number')) {
+    return { ok: false, error: 'Expected a JSON array of numbers' };
+  }
+  return { ok: true, value: { __type__: '__vector__', value: parsed } };
+}
+
+/**
+ * Edit affordance for a vector. Deliberately NOT a per-element grid —
+ * a 768-dim embedding isn't hand-tuned float by float. The contract is
+ * "replace the whole value": paste a JSON number array and commit. The
+ * dimension + a note are shown so the editor is honest about what it is.
+ *
+ * On commit, we emit the value back in the same wire-sentinel shape the
+ * read side already understands (`{__type__:'__vector__', value}`), so a
+ * round-trip through `inferType` re-classifies it as `vector`. Invalid
+ * JSON / non-numeric input leaves the previous value in place (same
+ * forgiving stance as the bytes + geopoint editors).
+ */
+function VectorEdit({ value, onChange, error, path }: FieldEditProps<unknown>) {
+  const view = asVectorView(value);
+  const initial = view ? JSON.stringify(view.values) : '[]';
+  const [draft, setDraft] = useState(initial);
+  const [parseError, setParseError] = useState<string | undefined>(undefined);
+
+  const commit = (text: string) => {
+    setDraft(text);
+    const result = parseVectorInput(text);
+    if (!result.ok) {
+      setParseError(result.error);
+      return;
+    }
+    setParseError(undefined);
+    // Re-emit in the wire-sentinel shape so the read side + inferType
+    // recognize it as a vector again without depending on a backend
+    // VectorValue class being importable here.
+    onChange(result.value);
+  };
+
+  const dims = view ? view.dimension : 0;
+  const shown = parseError ?? error;
+
+  return (
+    <label
+      data-pyric-field-type="vector"
+      data-pyric-field-path={path}
+      data-dimension={String(dims)}
+      data-pyric-error={shown ? '' : undefined}
+    >
+      <span data-pyric-vector-dims>{`vector · ${dims}`}</span>
+      <span data-pyric-vector-note>Replace whole. Paste a JSON number array.</span>
+      <textarea
+        data-pyric-vector-raw
+        value={draft}
+        onChange={(e) => commit(e.target.value)}
+        aria-invalid={shown ? 'true' : undefined}
+        aria-label="Vector value (JSON number array)"
+      />
+      {shown ? <span data-pyric-error-message>{shown}</span> : null}
+    </label>
+  );
+}
+
+export const vectorEditor: FieldEditorContract<unknown> = {
+  type: 'vector',
+  Display: VectorDisplay,
+  Edit: VectorEdit,
+};
+
+export type { VectorView };

package/src/firestore/firestoreApi.ts

@@ -0,0 +1,86 @@
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import {
+  addDoc,
+  collection,
+  deleteDoc,
+  doc,
+  getDoc,
+  getDocs,
+  limit,
+  onSnapshot,
+  query,
+  setDoc,
+  startAfter,
+} from 'pyric/firestore';
+
+/**
+ * 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.
+ */
+export type FirestoreApi = Pick<
+  typeof import('pyric/firestore'),
+  | 'addDoc'
+  | 'collection'
+  | 'deleteDoc'
+  | 'doc'
+  | 'getDoc'
+  | 'getDocs'
+  | 'limit'
+  | 'onSnapshot'
+  | 'query'
+  | 'setDoc'
+  | 'startAfter'
+>;
+
+const inProcessFirestoreApi: FirestoreApi = {
+  addDoc,
+  collection,
+  deleteDoc,
+  doc,
+  getDoc,
+  getDocs,
+  limit,
+  onSnapshot,
+  query,
+  setDoc,
+  startAfter,
+};
+
+const FirestoreApiContext = createContext<FirestoreApi>(inProcessFirestoreApi);
+
+/** Read the active Firestore API bundle (defaults to in-process `pyric/firestore`). */
+export function useFirestoreApi(): FirestoreApi {
+  return useContext(FirestoreApiContext);
+}
+
+/**
+ * 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`.
+ */
+export function FirestoreApiProvider({
+  value,
+  children,
+}: {
+  value: FirestoreApi;
+  children: ReactNode;
+}) {
+  return createElement(FirestoreApiContext.Provider, { value }, children);
+}

package/src/firestore/hooks/coerceError.ts

@@ -0,0 +1,34 @@
+/**
+ * Coerce an arbitrary thrown value into an `Error` with a useful
+ * `.message`. The naive `new Error(String(err))` produces the literal
+ * string `"[object Object]"` when `err` is a non-Error object shape
+ * — which is exactly what Firestore's `onSnapshot` error callback
+ * receives for `FirestoreError`-like values (`{ code, message, …}`).
+ *
+ * Strategy:
+ *   - `Error` → returned unchanged.
+ *   - `string` → `new Error(value)`.
+ *   - `{ message }` → `new Error(message)` (preserves Firestore's
+ *     stringified message), with `code` appended when present.
+ *   - anything else → `new Error(JSON.stringify(value))` (no more
+ *     "[object Object]").
+ */
+export function coerceError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  if (typeof value === 'string') return new Error(value);
+  if (value && typeof value === 'object') {
+    const obj = value as { message?: unknown; code?: unknown };
+    const msg = typeof obj.message === 'string' ? obj.message : null;
+    const code = typeof obj.code === 'string' ? obj.code : null;
+    if (msg && code) return new Error(`[${code}] ${msg}`);
+    if (msg) return new Error(msg);
+    if (code) return new Error(code);
+    try {
+      return new Error(JSON.stringify(value));
+    } catch {
+      // Cyclic objects — bail to a type tag rather than crash.
+      return new Error(Object.prototype.toString.call(value));
+    }
+  }
+  return new Error(String(value));
+}

package/src/firestore/hooks/index.ts

@@ -0,0 +1,46 @@
+export { useFirestoreDoc, type SubscriptionState } from './useFirestoreDoc.js';
+export { useFirestoreCollection } from './useFirestoreCollection.js';
+export {
+  useDocumentEditor,
+  type UseDocumentEditorOptions,
+  type UseDocumentEditorResult,
+} from './useDocumentEditor.js';
+export {
+  useCollectionList,
+  type UseCollectionListOptions,
+  type UseCollectionListResult,
+} from './useCollectionList.js';
+export {
+  useDocumentList,
+  type UseDocumentListOptions,
+  type UseDocumentListResult,
+} from './useDocumentList.js';
+export {
+  useDocumentSubcollections,
+  type ListSubcollections,
+  type UseDocumentSubcollectionsOptions,
+  type UseDocumentSubcollectionsResult,
+} from './useDocumentSubcollections.js';
+export {
+  useRecursiveDelete,
+  type RecursiveDeleteImpl,
+  type RecursiveDeleteProgress,
+  type UseRecursiveDeleteResult,
+} from './useRecursiveDelete.js';
+export {
+  useReferencePicker,
+  type BrowseLocation,
+  type UseReferencePickerOptions,
+  type UseReferencePickerResult,
+} from './useReferencePicker.js';
+export {
+  useQueryBuilder,
+  QUERY_OPS,
+  MULTI_VALUE_OPS,
+  type QueryOp,
+  type QueryCondition,
+  type QueryBuilderState,
+  type QueryBuilderActions,
+  type UseQueryBuilderOptions,
+  type UseQueryBuilderResult,
+} from './useQueryBuilder.js';

package/src/firestore/hooks/useCollectionList.ts

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  collection as collFn,
+  doc as docFn,
+  setDoc,
+  type CollectionReference,
+  type DocumentReference,
+  type Firestore,
+} from 'pyric/firestore';
+
+export interface UseCollectionListOptions {
+  firestore: Firestore;
+  /** Parent document, or `null`/`undefined` for root collections. */
+  parent?: DocumentReference | null;
+  /**
+   * Injected collection-listing function. The library doesn't ship
+   * a default — the modular Web SDK doesn't expose `listCollections`
+   * on the client. Sandbox-backed apps usually wire
+   * `pyric/sandbox`'s in-process listing; production apps either
+   * pass a known list (e.g. from a schema) or call a server proxy.
+   */
+  listCollections: (
+    firestore: Firestore,
+    parent: DocumentReference | null | undefined,
+  ) => Promise<CollectionReference[]>;
+}
+
+export interface UseCollectionListResult {
+  collections: CollectionReference[];
+  isLoading: boolean;
+  error: Error | undefined;
+  /** Re-run the listing function. */
+  refresh: () => void;
+  /**
+   * Create a new collection by writing its first document. Firestore
+   * collections don't exist independently of their documents —
+   * `setDoc` on the first child path materializes the collection.
+   */
+  createCollection: (
+    collectionId: string,
+    firstDoc: { id: string; data: Record<string, unknown> },
+  ) => Promise<DocumentReference>;
+}
+
+/**
+ * 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.
+ */
+export function useCollectionList({
+  firestore,
+  parent,
+  listCollections,
+}: UseCollectionListOptions): UseCollectionListResult {
+  const [collections, setCollections] = useState<CollectionReference[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [tick, setTick] = useState(0);
+
+  // Stable-ref the injected lister so re-renders with a fresh
+  // closure identity don't loop the effect — see useReferencePicker
+  // for the same pattern + rationale.
+  const listCollectionsRef = useRef(listCollections);
+  listCollectionsRef.current = listCollections;
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    setError(undefined);
+    listCollectionsRef.current(firestore, parent)
+      .then((list) => {
+        if (cancelled) return;
+        setCollections(list);
+        setIsLoading(false);
+      })
+      .catch((e) => {
+        if (cancelled) return;
+        setError(e instanceof Error ? e : new Error(String(e)));
+        setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [firestore, parent, tick]);
+
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  const createCollection = useCallback<UseCollectionListResult['createCollection']>(
+    async (collectionId, firstDoc) => {
+      const parentColl = parent
+        ? collFn(parent, collectionId)
+        : collFn(firestore, collectionId);
+      const ref = docFn(parentColl, firstDoc.id);
+      await setDoc(ref, firstDoc.data);
+      setTick((n) => n + 1);
+      return ref;
+    },
+    [firestore, parent],
+  );
+
+  return { collections, isLoading, error, refresh, createCollection };
+}

package/src/firestore/hooks/useDocumentEditor.ts

@@ -0,0 +1,161 @@
+import { useCallback, useMemo, useReducer, useRef } from 'react';
+import type { FieldType } from '../types.js';
+import { initState, reducer } from '../reducers/documentEditor.js';
+import { treeToData } from '../reducers/tree.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;
+  /** Replace the editor with a newly delivered snapshot and adopt it as the
+   * clean baseline. Intended for live document viewers. */
+  replaceData: (data: Record<string, unknown>) => 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; 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.
+ */
+export function useDocumentEditor(
+  options: UseDocumentEditorOptions = {},
+): UseDocumentEditorResult {
+  const initial = options.initial ?? {};
+  // `useRef` so the initial snapshot is computed once. The reducer
+  // owns the live tree from there on.
+  const initialRef = useRef<DocumentEditorState | null>(null);
+  if (initialRef.current == null) {
+    initialRef.current = initState(initial);
+  }
+
+  const [state, dispatch] = useReducer(reducer, initialRef.current);
+
+  const setValue = useCallback(
+    (nodeId: string, value: unknown) =>
+      dispatch({ type: 'setValue', nodeId, value }),
+    [],
+  );
+  const setType = useCallback(
+    (nodeId: string, newType: FieldType) =>
+      dispatch({ type: 'setType', nodeId, newType }),
+    [],
+  );
+  const setKey = useCallback(
+    (nodeId: string, key: string) => dispatch({ type: 'setKey', nodeId, key }),
+    [],
+  );
+  const addMapEntry = useCallback(
+    (parentId: string, key: string, childType: FieldType) =>
+      dispatch({ type: 'addMapEntry', parentId, key, childType }),
+    [],
+  );
+  const addArrayEntry = useCallback(
+    (parentId: string, childType: FieldType) =>
+      dispatch({ type: 'addArrayEntry', parentId, childType }),
+    [],
+  );
+  const remove = useCallback(
+    (nodeId: string) => dispatch({ type: 'remove', nodeId }),
+    [],
+  );
+  const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+  const replaceData = useCallback(
+    (data: Record<string, unknown>) => dispatch({ type: 'replaceData', data }),
+    [],
+  );
+  const touch = useCallback(
+    (nodeId: string) => 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<UseDocumentEditorResult>(
+    () => ({
+      ...state,
+      isDirty,
+      isValid,
+      dispatch,
+      setValue,
+      setType,
+      setKey,
+      addMapEntry,
+      addArrayEntry,
+      remove,
+      reset,
+      replaceData,
+      touch,
+      touchAll,
+      toData,
+    }),
+    [
+      state,
+      isDirty,
+      isValid,
+      setValue,
+      setType,
+      setKey,
+      addMapEntry,
+      addArrayEntry,
+      remove,
+      reset,
+      replaceData,
+      touch,
+      touchAll,
+      toData,
+    ],
+  );
+}