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

package/src/firestore/components/TreeEntry.tsx

@@ -0,0 +1,58 @@
+import { useState } from 'react';
+import { inferType } from '../types.js';
+import { FieldRenderer } from './FieldRenderer.js';
+import type { FieldEditorRegistry } from '../fieldEditors/types.js';
+
+/**
+ * One row of the read-only value tree. A scalar renders `key: value` inline; a
+ * map/array renders a disclosure chevron + key that toggles its nested tree
+ * (collapsible, default expanded). Shared by the map + array displays so both
+ * lists and objects get the same chevron behavior.
+ */
+export function TreeEntry({
+  label,
+  value,
+  path,
+  fieldEditors,
+  kind,
+}: {
+  label: string;
+  value: unknown;
+  path: string;
+  fieldEditors: FieldEditorRegistry;
+  kind: 'key' | 'index';
+}) {
+  const type = inferType(value);
+  const nested = type === 'map' || type === 'array';
+  const [expanded, setExpanded] = useState(true);
+  const labelAttr = kind === 'key' ? { 'data-pyric-tree-key': '' } : { 'data-pyric-tree-index': '' };
+  // Stable targeting hook for the entry (map key / array index).
+  const entryAttr = kind === 'key' ? { 'data-field-name': label } : { 'data-field-index': label };
+
+  if (!nested) {
+    return (
+      <li data-pyric-tree-entry {...entryAttr}>
+        <span data-pyric-tree-chevron data-pyric-tree-chevron-empty aria-hidden="true" />
+        <span {...labelAttr}>{label}</span>
+        <FieldRenderer value={value} path={path} fieldEditors={fieldEditors} />
+      </li>
+    );
+  }
+
+  return (
+    <li data-pyric-tree-entry data-pyric-tree-nested {...entryAttr}>
+      <button
+        type="button"
+        data-pyric-tree-toggle
+        aria-expanded={expanded}
+        onClick={() => setExpanded((e) => !e)}
+      >
+        <span data-pyric-tree-chevron aria-hidden="true">
+          ›
+        </span>
+        <span {...labelAttr}>{label}</span>
+      </button>
+      {expanded ? <FieldRenderer value={value} path={path} fieldEditors={fieldEditors} /> : null}
+    </li>
+  );
+}

package/src/firestore/components/context.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+import type { DocumentReference } from 'pyric/firestore';
+
+/**
+ * Cross-cutting display context threaded into individual field
+ * editors. Today it carries:
+ *
+ *   - `onReferenceClick` — fires when the reference Display
+ *     component is activated. Consumers wire navigation here.
+ *
+ * Read by the per-type Display components via `useDisplayContext`.
+ * Set by `<DocumentPreview>`'s wrapper. Editors that don't need it
+ * (string, number, …) simply ignore the context.
+ */
+export interface DisplayContextValue {
+  onReferenceClick?: (ref: DocumentReference) => void;
+}
+
+const Ctx = createContext<DisplayContextValue>({});
+
+export const DisplayContextProvider = Ctx.Provider;
+
+export function useDisplayContext(): DisplayContextValue {
+  return useContext(Ctx);
+}

package/src/firestore/fieldEditors/array.tsx

@@ -0,0 +1,30 @@
+import { TreeEntry } from '../components/TreeEntry.js';
+import type { FieldEditorContract, FieldDisplayProps } from './types.js';
+
+/**
+ * Read-only array renderer as an indented tree: each element is `index value`
+ * inline for scalars, or a collapsible disclosure (chevron + index) whose
+ * nested tree indents below for maps/arrays (so arrays-of-maps render through
+ * the same recursion). {@link TreeEntry} owns the collapse state + chevron.
+ */
+function ArrayDisplay({ value, path, fieldEditors }: FieldDisplayProps<unknown[]>) {
+  return (
+    <ul data-pyric-field-type="array" data-pyric-tree data-pyric-field-path={path}>
+      {value.map((item, i) => (
+        <TreeEntry
+          key={i}
+          label={String(i)}
+          value={item}
+          path={path ? `${path}[${i}]` : `[${i}]`}
+          fieldEditors={fieldEditors ?? {}}
+          kind="index"
+        />
+      ))}
+    </ul>
+  );
+}
+
+export const arrayEditor: FieldEditorContract<unknown[]> = {
+  type: 'array',
+  Display: ArrayDisplay,
+};

package/src/firestore/fieldEditors/boolean.tsx

@@ -0,0 +1,39 @@
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function BooleanDisplay({ value, path }: FieldDisplayProps<boolean>) {
+  return (
+    <span
+      data-pyric-field-type="boolean"
+      data-pyric-field-path={path}
+      data-value={value ? 'true' : 'false'}
+    >
+      {value ? 'true' : 'false'}
+    </span>
+  );
+}
+
+function BooleanEdit({ value, onChange, path }: FieldEditProps<boolean>) {
+  return (
+    <span
+      data-pyric-field-type="boolean"
+      data-pyric-field-path={path}
+      data-value={value ? 'true' : 'false'}
+    >
+      <select
+        value={value ? 'true' : 'false'}
+        onChange={(e) => onChange(e.target.value === 'true')}
+        aria-label="Boolean value"
+        data-pyric-boolean-select
+      >
+        <option value="true">true</option>
+        <option value="false">false</option>
+      </select>
+    </span>
+  );
+}
+
+export const booleanEditor: FieldEditorContract<boolean> = {
+  type: 'boolean',
+  Display: BooleanDisplay,
+  Edit: BooleanEdit,
+};

package/src/firestore/fieldEditors/bytes.tsx

@@ -0,0 +1,53 @@
+import { Bytes } from 'pyric/firestore';
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function BytesDisplay({ value, path }: FieldDisplayProps<Bytes>) {
+  const b64 = value.toBase64();
+  return (
+    <code
+      data-pyric-field-type="bytes"
+      data-pyric-field-path={path}
+      data-byte-length={String(value.toUint8Array().byteLength)}
+    >
+      {b64}
+    </code>
+  );
+}
+
+/**
+ * Base64 textarea. Anything that's not legal base64 produces a
+ * thrown error when passed to `Bytes.fromBase64String`; we swallow
+ * it and leave the old value in place. The validator surfaces the
+ * stale state by not flagging it (the underlying Bytes is still
+ * valid), so consumers wanting stricter feedback need to swap the
+ * editor.
+ */
+function BytesEdit({ value, onChange, error, path }: FieldEditProps<Bytes>) {
+  return (
+    <label
+      data-pyric-field-type="bytes"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <textarea
+        value={value.toBase64()}
+        onChange={(e) => {
+          try {
+            onChange(Bytes.fromBase64String(e.target.value));
+          } catch {
+            // Invalid base64 — keep the previous value. The user
+            // sees the bad text in the textarea until they fix it.
+          }
+        }}
+        aria-invalid={error ? 'true' : undefined}
+      />
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </label>
+  );
+}
+
+export const bytesEditor: FieldEditorContract<Bytes> = {
+  type: 'bytes',
+  Display: BytesDisplay,
+  Edit: BytesEdit,
+};

package/src/firestore/fieldEditors/geopoint.tsx

@@ -0,0 +1,71 @@
+import { GeoPoint } from 'pyric/firestore';
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function GeoPointDisplay({ value, path }: FieldDisplayProps<GeoPoint>) {
+  return (
+    <span
+      data-pyric-field-type="geopoint"
+      data-pyric-field-path={path}
+      data-lat={String(value.latitude)}
+      data-lng={String(value.longitude)}
+    >
+      {value.latitude}, {value.longitude}
+    </span>
+  );
+}
+
+function GeoPointEdit({ value, onChange, error, path }: FieldEditProps<GeoPoint>) {
+  return (
+    <span
+      data-pyric-field-type="geopoint"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <label>
+        <input
+          type="number"
+          step="any"
+          min={-90}
+          max={90}
+          value={value.latitude}
+          onChange={(e) => {
+            const lat = parseFloat(e.target.value);
+            try {
+              onChange(new GeoPoint(lat, value.longitude));
+            } catch {
+              // GeoPoint constructor throws on out-of-range. Leave
+              // the previous value in place; the validator will
+              // surface the issue on next render.
+            }
+          }}
+          aria-label="Latitude"
+        />
+      </label>
+      <label>
+        <input
+          type="number"
+          step="any"
+          min={-180}
+          max={180}
+          value={value.longitude}
+          onChange={(e) => {
+            const lng = parseFloat(e.target.value);
+            try {
+              onChange(new GeoPoint(value.latitude, lng));
+            } catch {
+              // see above
+            }
+          }}
+          aria-label="Longitude"
+        />
+      </label>
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </span>
+  );
+}
+
+export const geopointEditor: FieldEditorContract<GeoPoint> = {
+  type: 'geopoint',
+  Display: GeoPointDisplay,
+  Edit: GeoPointEdit,
+};

package/src/firestore/fieldEditors/map.tsx

@@ -0,0 +1,33 @@
+import { TreeEntry } from '../components/TreeEntry.js';
+import type { FieldEditorContract, FieldDisplayProps } from './types.js';
+
+/**
+ * Read-only map renderer as an indented tree (not a key/value grid): each entry
+ * is `key: value` inline for scalars, or a collapsible disclosure (chevron +
+ * key) whose nested tree indents below for maps/arrays. {@link TreeEntry} owns
+ * the per-node collapse state + chevron.
+ */
+function MapDisplay({ value, path, fieldEditors }: FieldDisplayProps<Record<string, unknown>>) {
+  // Lexicographic key order so fields render in a stable sequence regardless of
+  // JS object enumeration order (matches firebase-tools-ui).
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  return (
+    <ul data-pyric-field-type="map" data-pyric-tree data-pyric-field-path={path}>
+      {entries.map(([key, childValue]) => (
+        <TreeEntry
+          key={key}
+          label={key}
+          value={childValue}
+          path={path ? `${path}.${key}` : key}
+          fieldEditors={fieldEditors ?? {}}
+          kind="key"
+        />
+      ))}
+    </ul>
+  );
+}
+
+export const mapEditor: FieldEditorContract<Record<string, unknown>> = {
+  type: 'map',
+  Display: MapDisplay,
+};

package/src/firestore/fieldEditors/null.tsx

@@ -0,0 +1,27 @@
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function NullDisplay({ path }: FieldDisplayProps<null>) {
+  return (
+    <span data-pyric-field-type="null" data-pyric-field-path={path}>
+      null
+    </span>
+  );
+}
+
+// `null` has no editable surface — the user changes the type if they
+// want a value. The Edit component renders a placeholder so the
+// editor still emits a slot at the right path. Consumers style it
+// however they like (e.g. ghost text).
+function NullEdit({ path }: FieldEditProps<null>) {
+  return (
+    <span data-pyric-field-type="null" data-pyric-field-path={path}>
+      null
+    </span>
+  );
+}
+
+export const nullEditor: FieldEditorContract<null> = {
+  type: 'null',
+  Display: NullDisplay,
+  Edit: NullEdit,
+};

package/src/firestore/fieldEditors/number.tsx

@@ -0,0 +1,43 @@
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function NumberDisplay({ value, path }: FieldDisplayProps<number>) {
+  return (
+    <span data-pyric-field-type="number" data-pyric-field-path={path}>
+      {String(value)}
+    </span>
+  );
+}
+
+function NumberEdit({ value, onChange, error, path }: FieldEditProps<number>) {
+  return (
+    <label
+      data-pyric-field-type="number"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <input
+        type="number"
+        // Render NaN as empty so the input doesn't show literally
+        // "NaN" — the underlying value still carries it until the
+        // user types something valid.
+        value={Number.isFinite(value) ? value : ''}
+        onChange={(e) => {
+          const raw = e.target.value;
+          // Empty input commits NaN so the reducer's validator
+          // flags it; this keeps the editor's UI in sync with the
+          // underlying value rather than swallowing the change.
+          const parsed = raw === '' ? Number.NaN : parseFloat(raw);
+          onChange(parsed);
+        }}
+        aria-invalid={error ? 'true' : undefined}
+      />
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </label>
+  );
+}
+
+export const numberEditor: FieldEditorContract<number> = {
+  type: 'number',
+  Display: NumberDisplay,
+  Edit: NumberEdit,
+};

package/src/firestore/fieldEditors/reference.tsx

@@ -0,0 +1,87 @@
+import type { DocumentReference } from 'pyric/firestore';
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+import { useDisplayContext } from '../components/context.js';
+
+function ReferenceDisplay({ value, path }: FieldDisplayProps<DocumentReference>) {
+  // Clickable when a consumer has wired `onReferenceClick` via the
+  // `<DocumentPreview onReferenceClick={…}>` prop. Otherwise renders
+  // as plain text — staying headless and avoiding fake interactivity.
+  const { onReferenceClick } = useDisplayContext();
+  if (onReferenceClick) {
+    return (
+      <button
+        type="button"
+        onClick={() => onReferenceClick(value)}
+        data-pyric-field-type="reference"
+        data-pyric-field-path={path}
+        data-target-path={value.path}
+        data-pyric-clickable=""
+      >
+        {value.path}
+      </button>
+    );
+  }
+  return (
+    <span
+      data-pyric-field-type="reference"
+      data-pyric-field-path={path}
+      data-target-path={value.path}
+    >
+      {value.path}
+    </span>
+  );
+}
+
+/**
+ * Text-input reference editor. M3 only — the M5 `<ReferencePicker>`
+ * replaces this with a popover that browses the data plane. The
+ * editor commits a "ref-shaped" stand-in object (matching the
+ * structural check in `inferType` + `validateLeaf`) so the value
+ * flows through the reducer without needing a live Firestore handle
+ * at this layer.
+ */
+function ReferenceEdit({ value, onChange, error, path }: FieldEditProps<DocumentReference>) {
+  return (
+    <label
+      data-pyric-field-type="reference"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <input
+        type="text"
+        value={value.path}
+        placeholder="users/alice"
+        onChange={(e) => {
+          const nextPath = e.target.value;
+          const segments = nextPath.split('/').filter(Boolean);
+          const id = segments[segments.length - 1] ?? '';
+          // Build a ref-shaped stand-in. Real refs are constructed
+          // by `<ReferencePicker>` (M5) once it can talk to a
+          // Firestore handle.
+          // Preserve the existing firestore handle if the current
+          // value already carries one (so it can be wired back when
+          // the M5 picker arrives). Cast through `unknown` because
+          // the pyric/firestore type union doesn't expose
+          // `.firestore` uniformly across chainable + modular.
+          const existingFirestore =
+            (value as unknown as { firestore?: unknown }).firestore ?? {};
+          const stand = {
+            path: nextPath,
+            id,
+            firestore: existingFirestore,
+            type: 'document',
+          } as unknown as DocumentReference;
+          onChange(stand);
+        }}
+        aria-invalid={error ? 'true' : undefined}
+      />
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </label>
+  );
+}
+
+export const referenceEditor: FieldEditorContract<DocumentReference> = {
+  type: 'reference',
+  Display: ReferenceDisplay,
+  Edit: ReferenceEdit,
+};

package/src/firestore/fieldEditors/registry.ts

@@ -0,0 +1,45 @@
+import { stringEditor } from './string.js';
+import { numberEditor } from './number.js';
+import { booleanEditor } from './boolean.js';
+import { nullEditor } from './null.js';
+import { timestampEditor } from './timestamp.js';
+import { geopointEditor } from './geopoint.js';
+import { referenceEditor } from './reference.js';
+import { bytesEditor } from './bytes.js';
+import { mapEditor } from './map.js';
+import { arrayEditor } from './array.js';
+import { vectorEditor } from './vector.js';
+import type { FieldEditorRegistry } from './types.js';
+
+/**
+ * Default registry. Covers every {@link 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.
+ */
+export const defaultFieldEditors: FieldEditorRegistry = {
+  string: stringEditor,
+  number: numberEditor,
+  boolean: booleanEditor,
+  null: nullEditor,
+  timestamp: timestampEditor,
+  geopoint: geopointEditor,
+  reference: referenceEditor,
+  bytes: bytesEditor,
+  map: mapEditor,
+  array: arrayEditor,
+  vector: vectorEditor,
+};
+
+/**
+ * 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.
+ */
+export function mergeFieldEditors(
+  override: FieldEditorRegistry | undefined,
+): FieldEditorRegistry {
+  if (!override) return defaultFieldEditors;
+  return { ...defaultFieldEditors, ...override };
+}

package/src/firestore/fieldEditors/string.tsx

@@ -0,0 +1,33 @@
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+function StringDisplay({ value, path }: FieldDisplayProps<string>) {
+  return (
+    <span data-pyric-field-type="string" data-pyric-field-path={path}>
+      {value}
+    </span>
+  );
+}
+
+function StringEdit({ value, onChange, error, path }: FieldEditProps<string>) {
+  return (
+    <label
+      data-pyric-field-type="string"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <input
+        type="text"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        aria-invalid={error ? 'true' : undefined}
+      />
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </label>
+  );
+}
+
+export const stringEditor: FieldEditorContract<string> = {
+  type: 'string',
+  Display: StringDisplay,
+  Edit: StringEdit,
+};

package/src/firestore/fieldEditors/timestamp.tsx

@@ -0,0 +1,75 @@
+import { Timestamp } from 'pyric/firestore';
+import type { FieldEditorContract, FieldDisplayProps, FieldEditProps } from './types.js';
+
+/**
+ * Coerce a Timestamp value to a Date. Real instances use `.toDate()`; a value
+ * that crossed a worker / postMessage boundary arrives as a plain
+ * `{ seconds, nanoseconds }` (or `{ _seconds, _nanoseconds }`) and is rebuilt
+ * here, so the display + editor work in both in-process and served modes.
+ */
+function coerceDate(value: unknown): Date {
+  if (value instanceof Timestamp) return value.toDate();
+  const o = value as Record<string, number> | null;
+  const seconds = o ? (o.seconds ?? o._seconds) : undefined;
+  const nanoseconds = o ? (o.nanoseconds ?? o._nanoseconds ?? 0) : 0;
+  if (typeof seconds === 'number') return new Date(seconds * 1000 + Math.floor(nanoseconds / 1e6));
+  return new Date(NaN);
+}
+
+function TimestampDisplay({ value, path }: FieldDisplayProps<Timestamp>) {
+  const date = coerceDate(value);
+  const iso = Number.isNaN(date.getTime()) ? '' : date.toISOString();
+  return (
+    <time
+      dateTime={iso}
+      data-pyric-field-type="timestamp"
+      data-pyric-field-path={path}
+    >
+      {iso}
+    </time>
+  );
+}
+
+/**
+ * Native `<input type="datetime-local">` for editing. The element
+ * speaks local time (no zone offset); we convert to/from a UTC
+ * `Timestamp` at the boundary so the underlying value stays
+ * timezone-correct.
+ */
+function TimestampEdit({ value, onChange, error, path }: FieldEditProps<Timestamp>) {
+  // Convert the value to the `YYYY-MM-DDTHH:MM` shape <input
+  // datetime-local> wants. Seconds and millis aren't part of the
+  // native input precision; round-trips through this editor lose
+  // sub-minute resolution intentionally — consumers needing higher
+  // fidelity should swap the editor out via the registry.
+  const dt = coerceDate(value);
+  const local = new Date(dt.getTime() - dt.getTimezoneOffset() * 60_000);
+  const inputValue = Number.isNaN(local.getTime()) ? '' : local.toISOString().slice(0, 16);
+
+  return (
+    <label
+      data-pyric-field-type="timestamp"
+      data-pyric-field-path={path}
+      data-pyric-error={error ? '' : undefined}
+    >
+      <input
+        type="datetime-local"
+        value={inputValue}
+        onChange={(e) => {
+          const next = e.target.value;
+          if (!next) return;
+          const localDate = new Date(next);
+          onChange(Timestamp.fromDate(localDate));
+        }}
+        aria-invalid={error ? 'true' : undefined}
+      />
+      {error ? <span data-pyric-error-message>{error}</span> : null}
+    </label>
+  );
+}
+
+export const timestampEditor: FieldEditorContract<Timestamp> = {
+  type: 'timestamp',
+  Display: TimestampDisplay,
+  Edit: TimestampEdit,
+};