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

package/src/firestore/hooks/useReferencePicker.ts

@@ -0,0 +1,228 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  doc as docFn,
+  getDocs,
+  limit as limitFn,
+  query as queryFn,
+  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;
+}
+
+interface BrowseState {
+  current: BrowseLocation;
+  history: BrowseLocation[];
+}
+
+function parseReferencePath(
+  firestore: Firestore,
+  path: string,
+): { ref: DocumentReference | null; error: string | null } {
+  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) as DocumentReference;
+    return { ref, error: null };
+  } catch (e) {
+    return {
+      ref: null,
+      error: e instanceof Error ? e.message : 'Invalid path',
+    };
+  }
+}
+
+const ROOT: BrowseLocation = { 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 = '',
+}: UseReferencePickerOptions): UseReferencePickerResult {
+  const [pathInput, setPathInputState] = useState(initialPath);
+  const [browse, setBrowse] = useState<BrowseState>({
+    current: ROOT,
+    history: [],
+  });
+  const [collections, setCollections] = useState<CollectionReference[]>([]);
+  const [documents, setDocuments] = useState<QueryDocumentSnapshot[]>([]);
+  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: string) => {
+    setPathInputState(path);
+  }, []);
+
+  const pick = useCallback((ref: DocumentReference) => {
+    setPathInputState(ref.path);
+  }, []);
+
+  const drillIntoCollection = useCallback((ref: CollectionReference) => {
+    setBrowse((prev) => ({
+      current: { kind: 'collection', ref },
+      history: [...prev.history, prev.current],
+    }));
+  }, []);
+
+  const drillIntoDocument = useCallback((ref: DocumentReference) => {
+    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,
+  };
+}

package/src/firestore/import/parseImport.ts

@@ -0,0 +1,137 @@
+/**
+ * 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';
+
+/** 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;
+}
+
+const AUTO_ID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/** A Firestore-style 20-char auto id (same alphabet/length the SDK uses). */
+export function firestoreAutoId(): string {
+  let id = '';
+  for (let i = 0; i < 20; i++) {
+    id += AUTO_ID_ALPHABET.charAt(Math.floor(Math.random() * AUTO_ID_ALPHABET.length));
+  }
+  return id;
+}
+
+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[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  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: string, options?: ParseImportOptions): ParseImportResult {
+  const trimmed = input.trim();
+  if (trimmed === '') {
+    return { docs: [], errors: ['Input is empty'] };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (e) {
+    return { docs: [], errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`] };
+  }
+
+  const docs: ParsedImportDoc[] = [];
+  const errors: string[] = [];
+
+  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: unknown): string {
+  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: readonly string[],
+  docs: readonly ParsedImportDoc[],
+): string[] {
+  const existing = new Set(existingIds);
+  const collisions: string[] = [];
+  for (const doc of docs) {
+    if (doc.id !== null && existing.has(doc.id)) collisions.push(doc.id);
+  }
+  return collisions;
+}

package/src/firestore/index.ts

@@ -0,0 +1,87 @@
+export * from './hooks/index.js';
+
+// Injectable Firestore API bundle (Pyric Studio data-backend swap): defaults to
+// in-process `pyric/firestore`; a consumer can provide the SharedWorker client.
+export {
+  FirestoreApiProvider,
+  useFirestoreApi,
+  type FirestoreApi,
+} from './firestoreApi.js';
+
+// M2: read-only display surface
+export {
+  inferType,
+  asVectorView,
+  vectorPreview,
+  truncateVectorsForDisplay,
+  type FieldType,
+  type VectorView,
+} from './types.js';
+export { firestoreValuesEqual } from './valueEquality.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';
+
+// M3: editor surface
+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';
+
+// M4: operational read/write + admin ops
+export { CollectionList, type CollectionListProps } from './components/CollectionList.js';
+export { DocumentList, type DocumentListProps } from './components/DocumentList.js';
+export {
+  DeleteWithConfirm,
+  type DeleteWithConfirmProps,
+} from './components/DeleteWithConfirm.js';
+
+// M5: improvements over firebase-tools-ui
+export {
+  ReferencePicker,
+  type ReferencePickerProps,
+} from './components/ReferencePicker.js';
+
+// M6: query builder + virtualization
+export {
+  QueryBuilder,
+  type QueryBuilderProps,
+} from './components/QueryBuilder.js';
+
+// M7: create-collection / create-document / JSON-import — pure, tested logic.
+// Presentational wiring lives in the consumer (Pyric Studio's FirestorePane)
+// over these + the existing DocumentEditor/hooks, per the disclosure-over-
+// modals design principles.
+export { validateCollectionId, validateDocumentId } from './validation/ids.js';
+export {
+  parseImport,
+  detectCollisions,
+  firestoreAutoId,
+  type ParsedImportDoc,
+  type ParseImportResult,
+  type ParseImportOptions,
+} from './import/parseImport.js';

package/src/firestore/reducers/defaults.ts

@@ -0,0 +1,38 @@
+import { Timestamp, GeoPoint, Bytes } from 'pyric/firestore';
+import type { FieldType } from '../types.js';
+
+/**
+ * Default value used when a new field of this type is added (or
+ * when an existing field's type is switched). The reducer applies
+ * these so a fresh node always starts in a valid state for its type
+ * — except that map/array start empty (children come from add
+ * actions).
+ */
+export function defaultValueFor(type: FieldType): unknown {
+  switch (type) {
+    case 'string':
+      return '';
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    case 'null':
+      return null;
+    case 'timestamp':
+      return Timestamp.now();
+    case 'geopoint':
+      return new GeoPoint(0, 0);
+    case 'reference':
+      // No default — a fresh reference is invalid until the user
+      // sets a path. The validator will surface that.
+      return { path: '', id: '', firestore: {} };
+    case 'bytes':
+      return Bytes.fromUint8Array(new Uint8Array());
+    case 'vector':
+      // The wire-sentinel both inferType and the vector editor speak.
+      return { __type__: '__vector__', value: [] };
+    case 'map':
+    case 'array':
+      return undefined; // children carry the value
+  }
+}