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

package/src/firestore/components/DocumentPreview.tsx

@@ -0,0 +1,265 @@
+import { useMemo, useState, type ReactNode } from 'react';
+import type {
+  CollectionReference,
+  DocumentReference,
+  DocumentSnapshot,
+  Firestore,
+} from 'pyric/firestore';
+import { FieldRenderer } from './FieldRenderer.js';
+import { inferType } from '../types.js';
+import { mergeFieldEditors } from '../fieldEditors/registry.js';
+import type { FieldEditorRegistry } from '../fieldEditors/types.js';
+import { DisplayContextProvider, type DisplayContextValue } from './context.js';
+import { useContainerSize } from '../../primitives/hooks/useContainerSize.js';
+import {
+  useDocumentSubcollections,
+  type ListSubcollections,
+} from '../hooks/useDocumentSubcollections.js';
+
+/**
+ * `DocumentSnapshot.exists` is a method on the firebase/firestore
+ * `QueryDocumentSnapshot` (`.exists()`) and a getter/property on the
+ * Admin chainable adapter. `pyric/firestore` unions the two; this
+ * helper handles either.
+ */
+function snapshotExists(snapshot: DocumentSnapshot): boolean {
+  const e = (snapshot as { exists: boolean | (() => boolean) }).exists;
+  return typeof e === 'function' ? e.call(snapshot) : e;
+}
+
+export interface DocumentPreviewProps {
+  /** Snapshot from `useFirestoreDoc` or `getDoc`. When `null` /
+   *  `undefined`, renders {@link emptyState}. */
+  snapshot: DocumentSnapshot | null | undefined;
+  /** Override or extend the built-in field editors. Merged on top
+   *  of {@link defaultFieldEditors} — only the keys you provide
+   *  override. */
+  fieldEditors?: FieldEditorRegistry;
+  /** Content rendered when the snapshot is missing or
+   *  `!exists()`. Defaults to `null` (renders nothing). */
+  emptyState?: ReactNode;
+  /** Forwarded to the root `<div>`. */
+  className?: string;
+  /**
+   * Fired when a reference field is clicked. When supplied, the
+   * reference Display renders as an interactive `<button>` (with
+   * `data-pyric-clickable`); when omitted, it stays inert as a
+   * `<span>`. Consumers wire navigation here — the library does
+   * not depend on a router.
+   */
+  onReferenceClick?: (ref: DocumentReference) => void;
+  /**
+   * The document's own reference. Required to surface its
+   * subcollections — `DocumentSnapshot` (as typed by `pyric/firestore`)
+   * doesn't expose `.ref`, so the consumer threads the ref it already
+   * holds from fetching the doc. Without it (or without
+   * {@link listSubcollections}) the Subcollections section is omitted.
+   */
+  documentRef?: DocumentReference | null;
+  /**
+   * Firestore handle passed to {@link listSubcollections}. Required
+   * alongside `documentRef` + `listSubcollections` to surface the
+   * Subcollections section (the same explicit-handle shape
+   * `ReferencePicker` uses).
+   */
+  firestore?: Firestore;
+  /**
+   * Injected lister for the document's subcollections. The modular Web
+   * SDK has no client-side `listCollections`; sandbox-backed apps wire
+   * `pyric/sandbox`'s in-process listing, production apps pass a known
+   * list or a server proxy. Same shape `ReferencePicker` /
+   * `useCollectionList` use. Omit to hide the Subcollections section.
+   */
+  listSubcollections?: ListSubcollections;
+  /**
+   * Fired when a subcollection's drill affordance is activated. Receives
+   * the subcollection's `CollectionReference` (its `.path` is the
+   * navigate target). Consumers wire navigation here.
+   */
+  onSubcollectionClick?: (collection: CollectionReference) => void;
+}
+
+/**
+ * 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.
+ */
+export function DocumentPreview({
+  snapshot,
+  fieldEditors,
+  emptyState = null,
+  className,
+  onReferenceClick,
+  documentRef,
+  firestore,
+  listSubcollections,
+  onSubcollectionClick,
+}: DocumentPreviewProps) {
+  const displayCtx = useMemo<DisplayContextValue>(
+    () => ({ onReferenceClick }),
+    [onReferenceClick],
+  );
+  const { ref: rootRef, size } = useContainerSize<HTMLDivElement>();
+
+  if (!snapshot || !snapshotExists(snapshot)) {
+    return <>{emptyState}</>;
+  }
+  const data = snapshot.data() ?? {};
+  const entries = Object.entries(data).sort(([a], [b]) => a.localeCompare(b));
+  const registry = mergeFieldEditors(fieldEditors);
+
+  return (
+    <DisplayContextProvider value={displayCtx}>
+      <div
+        ref={rootRef}
+        className={className}
+        data-pyric-ui="document-preview"
+        data-doc-id={snapshot.id}
+        data-size={size}
+      >
+        {entries.map(([key, value]) => (
+          <FieldEntry key={key} fieldKey={key} value={value} registry={registry} />
+        ))}
+        {firestore && documentRef && listSubcollections ? (
+          <SubcollectionsSection
+            firestore={firestore}
+            documentRef={documentRef}
+            listSubcollections={listSubcollections}
+            onSubcollectionClick={onSubcollectionClick}
+          />
+        ) : null}
+      </div>
+    </DisplayContextProvider>
+  );
+}
+
+/**
+ * One top-level document field. A scalar renders `key  value` in the field grid;
+ * a map/array renders a disclosure (chevron + key) that collapses its value, so
+ * top-level containers toggle just like the nested tree does. A chevron gutter
+ * sits on scalars too (empty) so every key aligns.
+ */
+function FieldEntry({
+  fieldKey,
+  value,
+  registry,
+}: {
+  fieldKey: string;
+  value: unknown;
+  registry: FieldEditorRegistry;
+}) {
+  const type = inferType(value);
+  const nested = type === 'map' || type === 'array';
+  const [expanded, setExpanded] = useState(true);
+
+  if (!nested) {
+    return (
+      <div data-pyric-field-entry data-field-name={fieldKey}>
+        <span data-pyric-field-keycell>
+          <span data-pyric-tree-chevron data-pyric-tree-chevron-empty aria-hidden="true" />
+          <span data-pyric-field-key>{fieldKey}</span>
+        </span>
+        <FieldRenderer value={value} path={fieldKey} fieldEditors={registry} />
+      </div>
+    );
+  }
+
+  return (
+    <div data-pyric-field-entry data-field-name={fieldKey} data-pyric-field-nested>
+      <button
+        type="button"
+        data-pyric-field-keycell
+        data-pyric-field-toggle
+        aria-expanded={expanded}
+        onClick={() => setExpanded((e) => !e)}
+      >
+        <span data-pyric-tree-chevron aria-hidden="true">
+          ›
+        </span>
+        <span data-pyric-field-key>{fieldKey}</span>
+      </button>
+      {expanded ? <FieldRenderer value={value} path={fieldKey} fieldEditors={registry} /> : null}
+    </div>
+  );
+}
+
+interface SubcollectionsSectionProps {
+  firestore: Firestore;
+  documentRef: DocumentReference;
+  listSubcollections: ListSubcollections;
+  onSubcollectionClick?: (collection: CollectionReference) => void;
+}
+
+/**
+ * The "Subcollections" section under a document's fields. Lists the
+ * document's OWN subcollections (name + a drill affordance), mirroring
+ * the `c-data` mock. Reuses the injected-lister pattern; emits the
+ * subcollection ref through {@link onSubcollectionClick} for navigation.
+ *
+ * Renders nothing once loaded if the document has no subcollections —
+ * an empty section is noise. While loading it carries
+ * `data-pyric-loading` so consumers can show a placeholder.
+ */
+function SubcollectionsSection({
+  firestore,
+  documentRef,
+  listSubcollections,
+  onSubcollectionClick,
+}: SubcollectionsSectionProps) {
+  const { subcollections, isLoading } = useDocumentSubcollections({
+    firestore,
+    documentRef,
+    listSubcollections,
+  });
+
+  if (!isLoading && subcollections.length === 0) return null;
+
+  return (
+    <section
+      data-pyric-ui="subcollections"
+      data-pyric-loading={isLoading ? '' : undefined}
+    >
+      <div data-pyric-subcollections-group>Subcollections</div>
+      <ul data-pyric-subcollections-list>
+        {subcollections.map((coll) => (
+          <li
+            key={coll.path}
+            data-pyric-subcollection
+            data-pyric-collection-id={coll.id}
+            data-pyric-collection-path={coll.path}
+          >
+            {onSubcollectionClick ? (
+              <button
+                type="button"
+                data-pyric-subcollection-row
+                data-pyric-clickable
+                onClick={() => onSubcollectionClick(coll)}
+                aria-label={`Open subcollection ${coll.id}`}
+              >
+                <span data-pyric-subcollection-key>{coll.id}</span>
+                <span data-pyric-subcollection-type>subcollection</span>
+                <span data-pyric-subcollection-drill aria-hidden="true">
+                  ›
+                </span>
+              </button>
+            ) : (
+              <div data-pyric-subcollection-row>
+                <span data-pyric-subcollection-key>{coll.id}</span>
+                <span data-pyric-subcollection-type>subcollection</span>
+                <span data-pyric-subcollection-drill aria-hidden="true">
+                  ›
+                </span>
+              </div>
+            )}
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}

package/src/firestore/components/FieldRenderer.tsx

@@ -0,0 +1,25 @@
+import { inferType } from '../types.js';
+import type { FieldEditorRegistry } from '../fieldEditors/types.js';
+
+export interface FieldRendererProps {
+  value: unknown;
+  path?: string;
+  /** Registry to dispatch through. Pass the merged registry — this
+   *  component does not fall back to defaults on its own (to avoid
+   *  a circular import with the editors). `<DocumentPreview>` is
+   *  the entry point that merges user overrides into defaults. */
+  fieldEditors: FieldEditorRegistry;
+}
+
+/**
+ * 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.
+ */
+export function FieldRenderer({ value, path, fieldEditors }: FieldRendererProps) {
+  const type = inferType(value);
+  const contract = fieldEditors[type];
+  if (!contract) return null;
+  const { Display } = contract;
+  return <Display value={value} path={path} fieldEditors={fieldEditors} />;
+}

package/src/firestore/components/QueryBuilder.tsx

@@ -0,0 +1,181 @@
+import {
+  useQueryBuilder,
+  QUERY_OPS,
+  MULTI_VALUE_OPS,
+  type QueryOp,
+  type UseQueryBuilderOptions,
+  type UseQueryBuilderResult,
+} from '../hooks/useQueryBuilder.js';
+
+export interface QueryBuilderProps {
+  /** Drives the hook used internally. Both the state and the
+   *  composed Query are exposed via `onChange`. */
+  initial?: UseQueryBuilderOptions['initial'];
+  /** Fired on every state change with the latest builder API. The
+   *  parent typically calls `builder.buildQuery(collection)` and
+   *  feeds the result into `useDocumentList` / `useFirestoreCollection`. */
+  onChange?: (builder: UseQueryBuilderResult) => void;
+  className?: string;
+}
+
+/**
+ * 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.
+ */
+export function QueryBuilder({ initial, onChange, className }: QueryBuilderProps) {
+  const builder = useQueryBuilder({ initial });
+
+  // Pipe state changes back to the consumer. We don't memoize on
+  // the builder object itself since the hook already memoizes
+  // internally; calling onChange every render is cheap and matches
+  // the `<DocumentEditor>` pattern.
+  if (onChange) onChange(builder);
+
+  return (
+    <div className={className} data-pyric-ui="query-builder">
+      <ul data-pyric-query-conditions>
+        {builder.conditions.map((cond) => (
+          <li key={cond.id} data-pyric-query-condition>
+            <input
+              type="text"
+              value={cond.field}
+              placeholder="field"
+              onChange={(e) =>
+                builder.updateCondition(cond.id, { field: e.target.value })
+              }
+              data-pyric-query-field
+              aria-label="Field"
+            />
+            <select
+              value={cond.op}
+              onChange={(e) =>
+                builder.updateCondition(cond.id, { op: e.target.value as QueryOp })
+              }
+              data-pyric-query-op
+              aria-label="Operator"
+            >
+              {QUERY_OPS.map((op) => (
+                <option key={op} value={op}>
+                  {op}
+                </option>
+              ))}
+            </select>
+            <input
+              type="text"
+              value={stringifyValue(cond.value)}
+              placeholder={MULTI_VALUE_OPS.has(cond.op) ? '[1, 2]' : 'value'}
+              onChange={(e) =>
+                builder.updateCondition(cond.id, { value: parseValue(e.target.value) })
+              }
+              data-pyric-query-value
+              aria-label="Value"
+            />
+            <button
+              type="button"
+              onClick={() => builder.removeCondition(cond.id)}
+              data-pyric-query-remove
+              aria-label="Remove condition"
+            >
+              ×
+            </button>
+          </li>
+        ))}
+      </ul>
+      <button
+        type="button"
+        onClick={() => builder.addCondition()}
+        data-pyric-query-add-condition
+      >
+        + Add condition
+      </button>
+
+      <div data-pyric-query-modifiers>
+        <label data-pyric-query-orderby>
+          <span>orderBy</span>
+          <input
+            type="text"
+            value={builder.orderBy?.field ?? ''}
+            placeholder="field"
+            onChange={(e) => {
+              const field = e.target.value;
+              if (!field) {
+                builder.setOrderBy(undefined);
+              } else {
+                builder.setOrderBy({
+                  field,
+                  direction: builder.orderBy?.direction ?? 'asc',
+                });
+              }
+            }}
+            data-pyric-query-orderby-field
+          />
+          <select
+            value={builder.orderBy?.direction ?? 'asc'}
+            onChange={(e) => {
+              if (!builder.orderBy?.field) return;
+              builder.setOrderBy({
+                field: builder.orderBy.field,
+                direction: e.target.value as 'asc' | 'desc',
+              });
+            }}
+            disabled={!builder.orderBy?.field}
+            data-pyric-query-orderby-direction
+          >
+            <option value="asc">asc</option>
+            <option value="desc">desc</option>
+          </select>
+        </label>
+        <label data-pyric-query-limit>
+          <span>limit</span>
+          <input
+            type="number"
+            min={0}
+            value={builder.limit ?? ''}
+            placeholder="∞"
+            onChange={(e) => {
+              const v = e.target.value;
+              if (!v) {
+                builder.setLimit(undefined);
+              } else {
+                const n = parseInt(v, 10);
+                builder.setLimit(Number.isFinite(n) ? n : undefined);
+              }
+            }}
+            data-pyric-query-limit-input
+          />
+        </label>
+      </div>
+    </div>
+  );
+}
+
+function parseValue(raw: string): unknown {
+  if (raw === '') return '';
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Not JSON — return the raw string. Firestore `where` will
+    // refuse mistyped values at query time; the builder doesn't
+    // gate on type because some workflows (e.g. searching by a
+    // numeric-string id) are deliberate.
+    return raw;
+  }
+}
+
+function stringifyValue(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (v === undefined) return '';
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/firestore/components/ReferencePicker.tsx

@@ -0,0 +1,212 @@
+import { useState } from 'react';
+import type {
+  CollectionReference,
+  DocumentReference,
+  Firestore,
+} from 'pyric/firestore';
+import {
+  useReferencePicker,
+  type BrowseLocation,
+} from '../hooks/useReferencePicker.js';
+
+export interface ReferencePickerProps {
+  firestore: Firestore;
+  /** Initial path text. */
+  initialPath?: string;
+  /**
+   * Lister for subcollections. Required — see
+   * `useReferencePicker` docs for the rationale.
+   */
+  listCollections: (
+    firestore: Firestore,
+    parent: DocumentReference | null,
+  ) => Promise<CollectionReference[]>;
+  /** Fired when the user commits a picked reference (browse pick OR
+   *  a valid manually-typed path with the Commit button). */
+  onPick?: (ref: DocumentReference) => void;
+  /** Forwarded to the root. */
+  className?: string;
+  /** Label for the path text input. Default 'Document path'. */
+  pathLabel?: string;
+}
+
+/**
+ * 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.
+ */
+export function ReferencePicker({
+  firestore,
+  initialPath,
+  listCollections,
+  onPick,
+  className,
+  pathLabel = 'Document path',
+}: ReferencePickerProps) {
+  const picker = useReferencePicker({ firestore, listCollections, initialPath });
+  const [browseOpen, setBrowseOpen] = useState(false);
+
+  return (
+    <div className={className} data-pyric-ui="reference-picker">
+      <label data-pyric-reference-path-label>
+        {pathLabel}
+        <input
+          type="text"
+          value={picker.pathInput}
+          onChange={(e) => picker.setPathInput(e.target.value)}
+          placeholder="users/alice"
+          data-pyric-reference-path-input
+          aria-invalid={picker.error ? 'true' : undefined}
+        />
+      </label>
+      {picker.error ? (
+        <span data-pyric-error-message>{picker.error}</span>
+      ) : null}
+      <div data-pyric-reference-actions>
+        <button
+          type="button"
+          data-pyric-reference-browse-toggle
+          aria-expanded={browseOpen}
+          onClick={() => setBrowseOpen((o) => !o)}
+        >
+          {browseOpen ? 'Close browser' : 'Browse'}
+        </button>
+        <button
+          type="button"
+          data-pyric-reference-commit
+          disabled={!picker.reference}
+          onClick={() => {
+            if (picker.reference) onPick?.(picker.reference);
+          }}
+        >
+          Commit
+        </button>
+      </div>
+      {browseOpen ? (
+        <BrowsePanel
+          browseLocation={picker.browseLocation}
+          canDrillBack={picker.canDrillBack}
+          collections={picker.collections}
+          documents={picker.documents}
+          isLoading={picker.isLoading}
+          drillIntoCollection={picker.drillIntoCollection}
+          drillIntoDocument={picker.drillIntoDocument}
+          drillBack={picker.drillBack}
+          onPick={(ref) => {
+            picker.pick(ref);
+            onPick?.(ref);
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+interface BrowsePanelProps {
+  browseLocation: BrowseLocation;
+  canDrillBack: boolean;
+  collections: CollectionReference[];
+  documents: ReturnType<typeof useReferencePicker>['documents'];
+  isLoading: boolean;
+  drillIntoCollection: (ref: CollectionReference) => void;
+  drillIntoDocument: (ref: DocumentReference) => void;
+  drillBack: () => void;
+  onPick: (ref: DocumentReference) => void;
+}
+
+function BrowsePanel({
+  browseLocation,
+  canDrillBack,
+  collections,
+  documents,
+  isLoading,
+  drillIntoCollection,
+  drillIntoDocument,
+  drillBack,
+  onPick,
+}: BrowsePanelProps) {
+  const here = describeLocation(browseLocation);
+  return (
+    <div
+      data-pyric-ui="reference-browse-panel"
+      data-pyric-loading={isLoading ? '' : undefined}
+    >
+      <div data-pyric-browse-header>
+        <button
+          type="button"
+          data-pyric-browse-back
+          onClick={drillBack}
+          disabled={!canDrillBack}
+          aria-label="Back"
+        >
+          ←
+        </button>
+        <span data-pyric-browse-location>{here}</span>
+      </div>
+      {browseLocation.kind === 'root' || browseLocation.kind === 'document' ? (
+        <ul data-pyric-browse-collections>
+          {collections.map((c) => (
+            <li
+              key={c.path}
+              data-pyric-browse-entry
+              data-pyric-entry-kind="collection"
+              data-pyric-collection-id={c.id}
+            >
+              <button
+                type="button"
+                onClick={() => drillIntoCollection(c)}
+                data-pyric-browse-select
+              >
+                {c.id}/
+              </button>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <ul data-pyric-browse-documents>
+          {documents.map((d) => {
+            const ref = (d as unknown as { ref: DocumentReference }).ref;
+            return (
+              <li
+                key={ref.path}
+                data-pyric-browse-entry
+                data-pyric-entry-kind="document"
+                data-pyric-document-id={d.id}
+              >
+                <button
+                  type="button"
+                  onClick={() => onPick(ref)}
+                  data-pyric-browse-pick
+                >
+                  {d.id}
+                </button>
+                <button
+                  type="button"
+                  onClick={() => drillIntoDocument(ref)}
+                  data-pyric-browse-drill
+                  aria-label="Drill into subcollections"
+                >
+                  →
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function describeLocation(loc: BrowseLocation): string {
+  if (loc.kind === 'root') return '/';
+  if (loc.kind === 'document') return `/${loc.ref.path}`;
+  return `/${loc.ref.path}`;
+}