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

package/src/firestore/types.ts

@@ -0,0 +1,231 @@
+import { Timestamp, GeoPoint, Bytes } from 'pyric/firestore';
+
+/**
+ * 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.
+ */
+export type FieldType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'null'
+  | 'timestamp'
+  | 'geopoint'
+  | 'reference'
+  | 'bytes'
+  | 'map'
+  | 'array'
+  | 'vector';
+
+/**
+ * Runtime-classify a value into one of the {@link FieldType}s.
+ *
+ * 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.
+ */
+export function inferType(value: unknown): FieldType {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'string') return 'string';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+
+  // Vector (embedding) before array + map: a vector arrives as one of
+  // several typed shapes (see {@link asVectorView}), one of which is a
+  // plain `{__type__:'__vector__', value}` object. A bare numeric array
+  // is deliberately NOT a vector — only the typed VectorValue / wrapper
+  // / sentinel shapes classify here, so ordinary `number[]` data stays
+  // `array`.
+  if (typeof value === 'object' && asVectorView(value) !== null) return 'vector';
+
+  if (Array.isArray(value)) return 'array';
+
+  // Firestore SDK value types — these are class instances at runtime.
+  // `instanceof` works against the same import pyric/firestore
+  // re-exports (Bytes / GeoPoint from firebase/firestore directly;
+  // Timestamp from either backend's compatible class).
+  if (value instanceof Timestamp) return 'timestamp';
+  if (value instanceof GeoPoint) return 'geopoint';
+  if (value instanceof Bytes) return 'bytes';
+
+  // Serialized Timestamp / GeoPoint: crossing a worker / postMessage boundary
+  // strips the class, leaving plain `{ seconds, nanoseconds }` /
+  // `{ latitude, longitude }`. Detect them structurally (same rationale as
+  // references below) rather than rendering them as maps of internal fields.
+  if (typeof value === 'object' && isTimestampShape(value)) return 'timestamp';
+  if (typeof value === 'object' && isGeoPointShape(value)) return 'geopoint';
+
+  // DocumentReference has no shared class identity across the two
+  // backends (sandbox-chainable vs. firebase/firestore). Use a
+  // structural check on the brand-bearing fields. Any object that
+  // looks reference-shaped (path + firestore handle + id) is
+  // classified as a reference; the alternative is rendering it as
+  // a map of those three fields, which is strictly worse.
+  if (typeof value === 'object' && isDocumentReferenceShape(value)) {
+    return 'reference';
+  }
+
+  if (typeof value === 'object') return 'map';
+
+  // Unreachable for Firestore-shaped data, but TS wants exhaustivity.
+  return 'null';
+}
+
+/**
+ * A serialized Timestamp: exactly `{ seconds, nanoseconds }` (or the firebase
+ * `{ _seconds, _nanoseconds }` variant), both numbers, no other keys. The
+ * "exactly two keys" guard keeps a genuine map that merely contains those
+ * fields from being misclassified.
+ */
+export function isTimestampShape(v: object): boolean {
+  const obj = v as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  if (keys.length !== 2) return false;
+  return (
+    (typeof obj.seconds === 'number' && typeof obj.nanoseconds === 'number') ||
+    (typeof obj._seconds === 'number' && typeof obj._nanoseconds === 'number')
+  );
+}
+
+/** A serialized GeoPoint: exactly `{ latitude, longitude }`, both numbers. The
+ *  GeoPoint display reads `.latitude` / `.longitude`, so the plain shape renders
+ *  unchanged. */
+export function isGeoPointShape(v: object): boolean {
+  const obj = v as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  return keys.length === 2 && typeof obj.latitude === 'number' && typeof obj.longitude === 'number';
+}
+
+function isDocumentReferenceShape(v: object): boolean {
+  const obj = v as Record<string, unknown>;
+  if (typeof obj.path !== 'string' || typeof obj.id !== 'string') return false;
+  // The Web SDK ref exposes a `.firestore` handle; the chainable
+  // (sandbox) ref exposes `.env` instead. Either signals "this is a
+  // ref, not a plain map that happens to have `path` + `id` fields."
+  // Also accept `.type === 'document'` which both backends set on
+  // their ref class instances.
+  const hasFirestore = typeof obj.firestore === 'object' && obj.firestore !== null;
+  const hasEnv = typeof obj.env === 'object' && obj.env !== null;
+  const hasDocBrand = obj.type === 'document';
+  return hasFirestore || hasEnv || hasDocBrand;
+}
+
+/**
+ * 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.
+ */
+export interface VectorView {
+  /** The embedding components. Defensive copy — safe to read freely. */
+  readonly values: number[];
+  /** Number of components. Equivalent to `values.length`; surfaced
+   *  separately because that's what the UI labels (`vector · <dims>`). */
+  readonly dimension: number;
+}
+
+/**
+ * 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 {@link 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.
+ */
+export function asVectorView(value: unknown): VectorView | null {
+  if (value === null || typeof value !== 'object') return null;
+  const obj = value as Record<string, unknown>;
+
+  // (1) pyric Vector wrapper: branded by `typeName === 'vector'` with a
+  // numeric `.value` array. `.dimension` is a getter on the class.
+  if (obj.typeName === 'vector' && isNumberArray(obj.value)) {
+    return freezeView(obj.value as number[]);
+  }
+
+  // (4) wire sentinel: `{ __type__: '__vector__', value: number[] }`.
+  if (obj.__type__ === '__vector__' && isNumberArray(obj.value)) {
+    return freezeView(obj.value as number[]);
+  }
+
+  // (3) firebase-admin VectorValue: internal `_values` array.
+  if (isNumberArray(obj._values)) {
+    return freezeView(obj._values as number[]);
+  }
+
+  // (2) firebase/firestore (web) VectorValue: only a `.toArray()`. Guard
+  // the call so a plain object with an unrelated `toArray` can't throw —
+  // a non-numeric result fails the `isNumberArray` gate below.
+  if (typeof obj.toArray === 'function') {
+    try {
+      const arr = (obj.toArray as () => unknown)();
+      if (isNumberArray(arr)) return freezeView(arr as number[]);
+    } catch {
+      // Not a vector — fall through.
+    }
+  }
+
+  return null;
+}
+
+function isNumberArray(v: unknown): v is number[] {
+  return Array.isArray(v) && v.every((n) => typeof n === 'number');
+}
+
+function freezeView(values: number[]): VectorView {
+  const copy = values.slice();
+  return { values: copy, dimension: copy.length };
+}
+
+/** How many leading components to show in a truncated vector preview. */
+const VECTOR_PREVIEW_COUNT = 4;
+
+/** 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. */
+export function vectorPreview(view: VectorView): string {
+  const head = view.values.slice(0, VECTOR_PREVIEW_COUNT).join(', ');
+  const tail = view.values.length > VECTOR_PREVIEW_COUNT ? ', …' : '';
+  return `vector · ${view.dimension} [${head}${tail}]`;
+}
+
+/** 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. */
+export function truncateVectorsForDisplay(value: unknown): unknown {
+  const view = asVectorView(value);
+  if (view) return vectorPreview(view);
+  if (Array.isArray(value)) return value.map(truncateVectorsForDisplay);
+  if (value && typeof value === 'object') {
+    const proto = Object.getPrototypeOf(value);
+    if (proto === Object.prototype || proto === null) {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        out[k] = truncateVectorsForDisplay(v);
+      }
+      return out;
+    }
+  }
+  return value;
+}

package/src/firestore/validation/ids.ts

@@ -0,0 +1,45 @@
+/**
+ * Firestore collection/document id validation (create-collection /
+ * create-document / JSON-import flows).
+ *
+ * Pure, dependency-free, and deliberately narrow: it mirrors the rules the
+ * real backend enforces (see Firestore's "Rules and limits" docs), so a form
+ * can reject an invalid id BEFORE the write round-trip rather than
+ * surfacing a raw backend error string.
+ *
+ * Rules (both collection and document ids):
+ *   - non-empty
+ *   - no `/` (that's a path separator, not part of an id)
+ *   - not solely `.` or `..`
+ *   - doesn't match `__.*__` (reserved for internal use)
+ *   - at most 1500 bytes (UTF-8) — Firestore caps BOTH collection ids and
+ *     document ids at 1500 bytes ("Rules and limits": "Maximum size for a
+ *     collection ID" / "Maximum size for a document ID", both 1,500 bytes).
+ */
+
+const RESERVED_DUNDER = /^__.*__$/;
+
+/** Shared structural checks common to both collection and document ids. */
+function structuralError(id: string): string | undefined {
+  if (id.length === 0) return 'Cannot be empty';
+  if (id.includes('/')) return 'Cannot contain "/"';
+  if (id === '.' || id === '..') return 'Cannot be "." or ".."';
+  if (RESERVED_DUNDER.test(id)) return 'Cannot match __.*__ (reserved)';
+  if (utf8ByteLength(id) > 1500) return 'Cannot exceed 1500 bytes';
+  return undefined;
+}
+
+/** Validate a collection id. Returns an error message, or `undefined` when valid. */
+export function validateCollectionId(id: string): string | undefined {
+  return structuralError(id);
+}
+
+/** UTF-8 byte length of a string (Firestore's 1500-byte id cap). */
+function utf8ByteLength(s: string): number {
+  return new TextEncoder().encode(s).length;
+}
+
+/** Validate a document id. Returns an error message, or `undefined` when valid. */
+export function validateDocumentId(id: string): string | undefined {
+  return structuralError(id);
+}

package/src/firestore/valueEquality.ts

@@ -0,0 +1,43 @@
+interface FirestoreComparable {
+  isEqual(other: unknown): boolean;
+}
+
+function hasFirestoreEquality(value: unknown): value is FirestoreComparable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'isEqual' in value &&
+    typeof (value as { isEqual?: unknown }).isEqual === 'function'
+  );
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** Firestore-aware structural equality for values delivered by either the
+ * in-process SDK or the SharedWorker serializer. */
+export function firestoreValuesEqual(previous: unknown, next: unknown): boolean {
+  if (Object.is(previous, next)) return true;
+  if (hasFirestoreEquality(previous)) return previous.isEqual(next);
+  if (hasFirestoreEquality(next)) return next.isEqual(previous);
+  if (previous instanceof Uint8Array || next instanceof Uint8Array) {
+    if (!(previous instanceof Uint8Array) || !(next instanceof Uint8Array)) return false;
+    if (previous.length !== next.length) return false;
+    return previous.every((byte, index) => byte === next[index]);
+  }
+  if (Array.isArray(previous) || Array.isArray(next)) {
+    if (!Array.isArray(previous) || !Array.isArray(next)) return false;
+    if (previous.length !== next.length) return false;
+    return previous.every((value, index) => firestoreValuesEqual(value, next[index]));
+  }
+  if (!isPlainRecord(previous) || !isPlainRecord(next)) return false;
+  const previousKeys = Object.keys(previous);
+  const nextKeys = Object.keys(next);
+  if (previousKeys.length !== nextKeys.length) return false;
+  return previousKeys.every(
+    (key) => key in next && firestoreValuesEqual(previous[key], next[key]),
+  );
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Intentionally empty. Consumers import from subpaths:
+//   @pyric/ui/primitives
+//   @pyric/ui/firestore
+//   @pyric/ui/firestore/hooks
+//   @pyric/ui/rtdb
+//
+// This forces deliberate dependency choices — a consumer that only
+// uses `useFirestoreDoc` doesn't pull in any primitive components,
+// and vice versa.
+export {};

package/src/primitives/Badge.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+
+export interface BadgeProps {
+  /** Badge content — usually a short word like "ALLOW" or "GET". */
+  children: ReactNode;
+  /**
+   * Freeform category surfaced as `data-pyric-badge-kind`. The
+   * library doesn't enumerate kinds — the consumer decides what
+   * values exist (`allow`, `deny`, `get`, `update`, …) and styles
+   * them via `[data-pyric-badge-kind="…"]`.
+   */
+  kind?: string;
+  /** Forwarded to the underlying `<span>`. */
+  className?: string;
+  /**
+   * Accessible label. When set, the visible text becomes
+   * `aria-hidden` and screen readers announce this instead — useful
+   * when the badge is a terse glyph but the meaning is longer.
+   */
+  ariaLabel?: string;
+}
+
+/**
+ * Headless pill / tag. Renders an inline `<span>` carrying
+ * `data-pyric-badge` and (when `kind` is set) `data-pyric-badge-kind`
+ * so consumers can style categories with attribute selectors. Ships
+ * no visual styling of its own.
+ */
+export function Badge({ children, kind, className, ariaLabel }: BadgeProps) {
+  return (
+    <span
+      data-pyric-badge=""
+      data-pyric-badge-kind={kind}
+      className={className}
+      aria-label={ariaLabel}
+    >
+      {ariaLabel ? <span aria-hidden="true">{children}</span> : children}
+    </span>
+  );
+}

package/src/primitives/ConfirmDialog.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useRef, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+
+export interface ConfirmDialogProps {
+  /** Controlled open state. */
+  open: boolean;
+  /** Called when the user dismisses via overlay click, Escape, or
+   *  the cancel button. NOT called by `onConfirm`. */
+  onOpenChange: (open: boolean) => void;
+  /** Heading. */
+  title: string;
+  /** Body content — explanation, consequences, paths affected. */
+  body?: ReactNode;
+  /** When `true`, the confirm button carries `data-pyric-destructive`
+   *  so consumers can style it differently (e.g. red). */
+  destructive?: boolean;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  /** Fires when the user presses confirm. The component does NOT
+   *  close itself on confirm — the consumer typically dismisses
+   *  after the destructive action resolves. */
+  onConfirm: () => void;
+  /** Forwarded to the content node so consumers can style. */
+  className?: string;
+}
+
+/**
+ * Headless confirmation dialog. Hand-rolled (we evaluated Radix
+ * Dialog at M4 but Radix's Presence + Portal stack doesn't render
+ * under our bun:test + JSDOM env — see plan section 7 risk #1).
+ *
+ * Provides:
+ *   - Portal to `document.body` (so the dialog can escape parent
+ *     stacking contexts)
+ *   - Escape-to-close
+ *   - Overlay click to close
+ *   - ARIA `role="dialog" aria-modal="true"` wiring
+ *   - Focus restoration to the previously-focused element on close
+ *   - Initial focus on the confirm button when opening
+ *
+ * Ships no visual CSS. Consumers style via the structural
+ * `data-pyric-*` attributes.
+ */
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  body,
+  destructive,
+  confirmLabel = 'Confirm',
+  cancelLabel = 'Cancel',
+  onConfirm,
+  className,
+}: ConfirmDialogProps) {
+  const confirmButtonRef = useRef<HTMLButtonElement | null>(null);
+  const previouslyFocused = useRef<Element | null>(null);
+
+  // Escape-to-close.
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        onOpenChange(false);
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [open, onOpenChange]);
+
+  // Focus management: capture the previously-focused element on
+  // open, restore it on close. Initial focus goes to the confirm
+  // button so destructive actions don't dispatch by accident
+  // (consumers wanting "Cancel" as the default can refocus in an
+  // effect).
+  useEffect(() => {
+    if (!open) return;
+    previouslyFocused.current = document.activeElement;
+    confirmButtonRef.current?.focus();
+    return () => {
+      const prev = previouslyFocused.current as HTMLElement | null;
+      prev?.focus?.();
+    };
+  }, [open]);
+
+  if (!open) return null;
+  if (typeof document === 'undefined') return null;
+
+  return createPortal(
+    <div
+      role="presentation"
+      data-pyric-ui="confirm-portal"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onOpenChange(false);
+      }}
+    >
+      <div data-pyric-ui="confirm-overlay" aria-hidden="true" />
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="pyric-confirm-title"
+        aria-describedby={body ? 'pyric-confirm-body' : undefined}
+        className={className}
+        data-pyric-ui="confirm-dialog"
+        data-pyric-destructive={destructive ? '' : undefined}
+      >
+        <div id="pyric-confirm-title" data-pyric-confirm-title>
+          {title}
+        </div>
+        {body ? (
+          <div id="pyric-confirm-body" data-pyric-confirm-body>
+            {body}
+          </div>
+        ) : null}
+        <div data-pyric-confirm-actions>
+          <button
+            type="button"
+            data-pyric-confirm-cancel
+            onClick={() => onOpenChange(false)}
+          >
+            {cancelLabel}
+          </button>
+          <button
+            ref={confirmButtonRef}
+            type="button"
+            data-pyric-confirm-confirm
+            data-pyric-destructive={destructive ? '' : undefined}
+            onClick={onConfirm}
+          >
+            {confirmLabel}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/src/primitives/CopyButton.tsx

@@ -0,0 +1,62 @@
+import { useState, type ReactNode } from 'react';
+
+export interface CopyButtonProps {
+  /** Text to copy to the clipboard on click. */
+  text: string;
+  /** Optional content to render inside the button. Defaults to a
+   *  short text label that toggles between "Copy" and "Copied". */
+  children?: ReactNode;
+  /** Milliseconds before the `data-copied` state attribute clears.
+   *  Defaults to 2000. */
+  resetMs?: number;
+  /** Forwarded to the underlying `<button>`. Consumers compose
+   *  Tailwind classes, CSS-module classes, or whatever they want. */
+  className?: string;
+  /** Forwarded as the button's accessible label when in the idle
+   *  state. Defaults to "Copy to clipboard". The copied state uses
+   *  a hard-coded "Copied" label so screen readers announce the
+   *  state change consistently. */
+  ariaLabel?: string;
+}
+
+/**
+ * Headless copy-to-clipboard button. Exposes its `copied` state via
+ * the `data-copied` attribute on the underlying `<button>` so
+ * consumers can style the success state with `[data-copied]` (or
+ * `data-[copied]:bg-green-500` in Tailwind's arbitrary-variant
+ * syntax). Ships no visual styling of its own.
+ */
+export function CopyButton({
+  text,
+  children,
+  resetMs = 2000,
+  className,
+  ariaLabel = 'Copy to clipboard',
+}: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+
+  async function handleClick() {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      // Clipboard write can fail (insecure context, denied permission).
+      // The library doesn't surface this here — callers wrap in a
+      // toast / callout if they want feedback.
+      return;
+    }
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), resetMs);
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className={className}
+      data-copied={copied ? '' : undefined}
+      aria-label={copied ? 'Copied' : ariaLabel}
+    >
+      {children ?? (copied ? 'Copied' : 'Copy')}
+    </button>
+  );
+}