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

package/src/rtdb/editor.ts

@@ -0,0 +1,79 @@
+/**
+ * Inline value-editor logic (pure): the type select + text input pair used by
+ * the tree's click-to-edit and add-child rows. Four author-facing types cover
+ * every RTDB value: string / number / boolean scalars, and `json` for
+ * objects/arrays/null (or any hand-written literal).
+ */
+
+export type RtdbEditorType = 'string' | 'number' | 'boolean' | 'json';
+
+export const RTDB_EDITOR_TYPES: readonly RtdbEditorType[] = [
+  'string',
+  'number',
+  'boolean',
+  'json',
+];
+
+/** The editor type a value opens under when clicked. */
+export function inferRtdbEditorType(value: unknown): RtdbEditorType {
+  switch (typeof value) {
+    case 'string':
+      return 'string';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    default:
+      return 'json';
+  }
+}
+
+/** Seed the editor's text field from the current value under a type. */
+export function formatRtdbEditorValue(value: unknown, type: RtdbEditorType): string {
+  if (type === 'json') return JSON.stringify(value ?? null);
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/** Why a typed child key is unusable, or `null` when it's fine. RTDB forbids
+ *  `. $ # [ ] /` in keys (a `/` would silently create a nested path). */
+export function rtdbKeyInputError(key: string): string | null {
+  if (key.trim().length === 0) return 'Enter a key.';
+  const bad = key.match(/[.$#[\]/]/);
+  if (bad) return `Keys can't contain "${bad[0]}".`;
+  return null;
+}
+
+export type RtdbEditorResult =
+  | { ok: true; value: unknown }
+  | { ok: false; error: string };
+
+/** Coerce the editor's text under the selected type, or explain why not. */
+export function coerceRtdbEditorValue(type: RtdbEditorType, text: string): RtdbEditorResult {
+  switch (type) {
+    case 'string':
+      return { ok: true, value: text };
+    case 'number': {
+      const trimmed = text.trim();
+      if (trimmed.length === 0) return { ok: false, error: 'Enter a number.' };
+      const n = Number(trimmed);
+      if (Number.isNaN(n)) return { ok: false, error: `"${text}" is not a number.` };
+      return { ok: true, value: n };
+    }
+    case 'boolean': {
+      const t = text.trim().toLowerCase();
+      if (t === 'true') return { ok: true, value: true };
+      if (t === 'false') return { ok: true, value: false };
+      return { ok: false, error: 'Enter true or false.' };
+    }
+    case 'json': {
+      const t = text.trim();
+      if (t.length === 0) return { ok: true, value: null };
+      try {
+        return { ok: true, value: JSON.parse(t) };
+      } catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : 'Invalid JSON.' };
+      }
+    }
+  }
+}

package/src/rtdb/hooks/useRtdbTree.ts

@@ -0,0 +1,137 @@
+import { useCallback, useEffect, useMemo, useReducer } from 'react';
+import type { RtdbApi } from '../rtdbApi.js';
+import {
+  normalizeRtdbPath,
+  rtdbUpdateEntries,
+  rtdbValuesEqual,
+} from '../values.js';
+import {
+  useUpdateHighlights,
+  type UpdateHighlight,
+} from '../../primitives/hooks/useUpdateHighlights.js';
+import {
+  initialRtdbTree,
+  isRtdbPathExpanded,
+  rtdbTreeReducer,
+  rtdbTreeValueAt,
+  rtdbVisibleChildren,
+  type RtdbTreeState,
+  type RtdbVisibleChildren,
+} from '../reducers/tree.js';
+
+/** Console-style child paging (Firebase console shows 50, then "show more"). */
+export const RTDB_DEFAULT_PAGE_SIZE = 50;
+
+export interface UseRtdbTreeOptions {
+  /** Children rendered per level before "show more". Default 50. */
+  pageSize?: number;
+}
+
+/**
+ * Everything a tree view needs: the reducer state plus path-addressed
+ * selectors and the expansion/paging commands. All paths are ABSOLUTE
+ * database paths.
+ */
+export interface RtdbTreeController {
+  state: RtdbTreeState;
+  pageSize: number;
+  valueAt(path: string): unknown;
+  isExpanded(path: string): boolean;
+  childrenAt(path: string): RtdbVisibleChildren;
+  toggle(path: string): void;
+  showMore(path: string): void;
+  updateAt(path: string): UpdateHighlight | undefined;
+}
+
+/**
+ * Live tree state for the RTDB viewer: subscribes to the value at the view
+ * root `path` (realtime — every write re-delivers the subtree) and runs the
+ * expansion/paging reducer over it. See `reducers/tree.ts` for the
+ * one-subscription-per-view-root loading strategy and why expansion is a
+ * pure render toggle rather than a fetch.
+ */
+export function useRtdbTree(
+  api: RtdbApi,
+  path: string,
+  options: UseRtdbTreeOptions = {},
+): RtdbTreeController {
+  const pageSize = options.pageSize ?? RTDB_DEFAULT_PAGE_SIZE;
+  const normalized = normalizeRtdbPath(path);
+  const [state, dispatch] = useReducer(rtdbTreeReducer, normalized, initialRtdbTree);
+  const updateEntries = useMemo(
+    () => rtdbUpdateEntries(state.value, state.path),
+    [state.path, state.value],
+  );
+  const updates = useUpdateHighlights({
+    scope: state.path,
+    entries: updateEntries,
+    equals: rtdbValuesEqual,
+    ready: state.status === 'live',
+  });
+
+  // Keep the reducer's view root in lockstep with the prop BEFORE the
+  // subscription effect below re-runs, so a snapshot for the new root never
+  // lands on the old root's state.
+  if (state.path !== normalized) {
+    dispatch({ type: 'navigate', path: normalized });
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    const unsubscribe = api.subscribeValue(
+      normalized,
+      (value) => {
+        if (!cancelled) dispatch({ type: 'value', path: normalized, value });
+      },
+      (err) => {
+        if (!cancelled) {
+          dispatch({
+            type: 'error',
+            path: normalized,
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    );
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [api, normalized]);
+
+  const valueAt = useCallback(
+    (p: string) => rtdbTreeValueAt(state, p),
+    [state],
+  );
+  const isExpanded = useCallback(
+    (p: string) => isRtdbPathExpanded(state, p),
+    [state],
+  );
+  const childrenAt = useCallback(
+    (p: string) => rtdbVisibleChildren(state, p, pageSize),
+    [state, pageSize],
+  );
+  const toggle = useCallback((p: string) => dispatch({ type: 'toggle', path: p }), []);
+  const showMore = useCallback(
+    (p: string) => dispatch({ type: 'show-more', path: p, pageSize }),
+    [pageSize],
+  );
+  const updateAt = useCallback(
+    (p: string) => updates.get(normalizeRtdbPath(p)),
+    [updates],
+  );
+
+  return useMemo(
+    () => ({
+      state,
+      pageSize,
+      valueAt,
+      isExpanded,
+      childrenAt,
+      toggle,
+      showMore,
+      updateAt,
+    }),
+    [state, pageSize, valueAt, isExpanded, childrenAt, toggle, showMore, updateAt],
+  );
+}

package/src/rtdb/index.ts

@@ -0,0 +1,66 @@
+/**
+ * `@pyric/ui/rtdb` — the headless RTDB data viewer, in the Firebase console /
+ * firebase-tools-ui form: an editable path bar (crumbs + direct path entry)
+ * over an expandable tree with inline add/edit/delete affordances. Follows
+ * this package's firestore/auth/storage split: pure logic + hooks +
+ * unstyled components on `data-*` styling contracts; the consumer (Studio)
+ * brings the CSS and the backend bundle ({@link RtdbApi}).
+ */
+
+// Pure path + value helpers.
+export {
+  normalizeRtdbPath,
+  rtdbPathSegments,
+  joinRtdbPath,
+  parentRtdbPath,
+  relativeRtdbPath,
+  isRtdbObjectValue,
+  hasRtdbChildren,
+  rtdbChildEntries,
+  rtdbValueAt,
+  formatRtdbJson,
+  parseRtdbJson,
+  rtdbValueKind,
+  previewRtdbValue,
+  normalizeRtdbSnapshotValue,
+  formatRtdbValueLabel,
+} from './values.js';
+
+// Path-bar input parsing + crumb derivation.
+export { parseRtdbPathInput, rtdbCrumbs, type RtdbCrumb } from './pathInput.js';
+
+// Inline value-editor logic.
+export {
+  RTDB_EDITOR_TYPES,
+  inferRtdbEditorType,
+  formatRtdbEditorValue,
+  coerceRtdbEditorValue,
+  rtdbKeyInputError,
+  type RtdbEditorType,
+  type RtdbEditorResult,
+} from './editor.js';
+
+// Backend seam.
+export type { RtdbApi } from './rtdbApi.js';
+
+// Tree state (pure reducer + selectors).
+export {
+  initialRtdbTree,
+  rtdbTreeReducer,
+  rtdbTreeValueAt,
+  isRtdbPathExpanded,
+  rtdbVisibleChildren,
+  type RtdbTreeState,
+  type RtdbTreeAction,
+  type RtdbVisibleChildren,
+} from './reducers/tree.js';
+
+// Hook + components.
+export {
+  useRtdbTree,
+  RTDB_DEFAULT_PAGE_SIZE,
+  type UseRtdbTreeOptions,
+  type RtdbTreeController,
+} from './hooks/useRtdbTree.js';
+export { RtdbPathBar, type RtdbPathBarProps } from './components/RtdbPathBar.js';
+export { RtdbTree, type RtdbTreeProps } from './components/RtdbTree.js';

package/src/rtdb/pathInput.ts

@@ -0,0 +1,47 @@
+/**
+ * Editable path-bar logic (pure): parse what a user TYPES OR PASTES into the
+ * path input, and derive the clickable crumb list for display mode. The
+ * interaction form follows the Firebase console / firebase-tools-ui database
+ * viewer's editable breadcrumb bar (clean-room adaptation — behavior only).
+ */
+
+import { normalizeRtdbPath, rtdbPathSegments } from './values.js';
+
+/**
+ * Normalize raw path-input text to a database path. Tolerant of what people
+ * paste into a database URL bar:
+ *   - a plain path, with or without the leading slash (`rooms/r1`, `/rooms`)
+ *   - a full URL (`https://x.firebaseio.com/rooms/r1` → `/rooms/r1`)
+ *   - repeated/trailing slashes, surrounding whitespace
+ *   - a `?query` / `#hash` tail (dropped)
+ * Empty input is the root.
+ */
+export function parseRtdbPathInput(raw: string): string {
+  let text = raw.trim();
+  if (text.length === 0) return '/';
+  // A pasted absolute URL: strip `scheme://host[:port]`.
+  const url = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]+/i.exec(text);
+  if (url) text = text.slice(url[0].length);
+  // Drop a query/hash tail (URL bars carry them; database paths do not).
+  text = text.replace(/[?#].*$/, '');
+  return normalizeRtdbPath(text);
+}
+
+export interface RtdbCrumb {
+  /** The path segment to display. */
+  label: string;
+  /** Absolute database path this crumb navigates to. */
+  path: string;
+}
+
+/**
+ * The non-root crumbs for a path, in order. `'/'` yields `[]` — the root crumb
+ * is the caller's (it carries the database/instance label, not a segment).
+ */
+export function rtdbCrumbs(path: string): RtdbCrumb[] {
+  const segments = rtdbPathSegments(path);
+  return segments.map((label, i) => ({
+    label,
+    path: `/${segments.slice(0, i + 1).join('/')}`,
+  }));
+}

package/src/rtdb/reducers/tree.ts

@@ -0,0 +1,191 @@
+/**
+ * RTDB viewer tree state (pure reducer). The interaction form is the Firebase
+ * console / firebase-tools-ui data viewer: one view root (set by the path
+ * bar), expandable/collapsible descendants, and per-level paging for wide
+ * child lists.
+ *
+ * DATA-LOADING STRATEGY (documented decision): the worker protocol exposes
+ * `rtdb.get` / value subscriptions per PATH but no shallow or depth-limited
+ * reads — a read at a path always ships that path's WHOLE subtree over the
+ * MessagePort. A per-expand fetch would therefore re-ship data the view-root
+ * read already delivered. So the viewer holds ONE live value subscription at
+ * the view root (realtime by construction) and makes RENDERING lazy instead:
+ * nodes below the root start collapsed and mount nothing until expanded, and
+ * an expanded level renders at most `pageSize` children until "show more"
+ * (console-style paging at 50, chosen over virtualization for its simplicity —
+ * it bounds the mounted DOM the same way). Cost is bounded by navigating the
+ * view root deeper, which is the path bar's job.
+ */
+
+import {
+  hasRtdbChildren,
+  normalizeRtdbPath,
+  normalizeRtdbSnapshotValue,
+  relativeRtdbPath,
+  rtdbChildEntries,
+  rtdbValueAt,
+} from '../values.js';
+
+export interface RtdbTreeState {
+  /** The view root — the absolute database path the path bar points at. */
+  path: string;
+  /** `loading` until the first snapshot after a navigate; then `live`. */
+  status: 'loading' | 'live' | 'error';
+  /** The subtree value AT `path` (plain JSON; `null` = nothing there). */
+  value: unknown;
+  error: string | null;
+  /** Expanded descendant paths (absolute). The view root itself is always
+   *  expanded and is never in this set. */
+  expanded: Record<string, true>;
+  /** Per-path shown-children override (absolute path → count). Absent means
+   *  one page. */
+  pages: Record<string, number>;
+}
+
+export type RtdbTreeAction =
+  /** Path bar navigation: reset to a new view root. */
+  | { type: 'navigate'; path: string }
+  /** A value snapshot arrived. `path` is the subscription's view root — a
+   *  snapshot from a superseded subscription (its path no longer the state's)
+   *  is ignored. */
+  | { type: 'value'; path: string; value: unknown }
+  /** The view-root subscription failed (same `path` guard as `value`). */
+  | { type: 'error'; path: string; message: string }
+  | { type: 'toggle'; path: string }
+  | { type: 'expand'; path: string }
+  | { type: 'collapse'; path: string }
+  /** Reveal one more page of children at `path`. */
+  | { type: 'show-more'; path: string; pageSize: number };
+
+export function initialRtdbTree(path: string): RtdbTreeState {
+  return {
+    path: normalizeRtdbPath(path),
+    status: 'loading',
+    value: null,
+    error: null,
+    expanded: {},
+    pages: {},
+  };
+}
+
+/** The subtree value at an ABSOLUTE database path, resolved against the
+ *  loaded view-root value. `null` outside the view root. */
+export function rtdbTreeValueAt(state: RtdbTreeState, path: string): unknown {
+  const rel = relativeRtdbPath(state.path, path);
+  return rel === null ? null : rtdbValueAt(state.value, rel);
+}
+
+/** Is this absolute path expanded? The view root always is. */
+export function isRtdbPathExpanded(state: RtdbTreeState, path: string): boolean {
+  const normalized = normalizeRtdbPath(path);
+  return normalized === state.path || state.expanded[normalized] === true;
+}
+
+export interface RtdbVisibleChildren {
+  /** The children to render, in key order, capped at the shown count. */
+  entries: Array<[string, unknown]>;
+  /** Total direct children at this path. */
+  total: number;
+  /** How many more "show more" would reveal (0 = all shown). */
+  hiddenCount: number;
+}
+
+/** The page-capped child list at an absolute path (console pages at 50). */
+export function rtdbVisibleChildren(
+  state: RtdbTreeState,
+  path: string,
+  pageSize: number,
+): RtdbVisibleChildren {
+  const entries = rtdbChildEntries(rtdbTreeValueAt(state, path));
+  const shown = Math.min(
+    entries.length,
+    state.pages[normalizeRtdbPath(path)] ?? pageSize,
+  );
+  return {
+    entries: entries.slice(0, shown),
+    total: entries.length,
+    hiddenCount: entries.length - shown,
+  };
+}
+
+/** Keep only entries whose path still resolves to a node WITH children under
+ *  the new value — a removed or scalar-ified node can't stay expanded/paged. */
+function pruneByValue<V>(
+  record: Record<string, V>,
+  state: Pick<RtdbTreeState, 'path' | 'value'>,
+): Record<string, V> {
+  const next: Record<string, V> = {};
+  let changed = false;
+  for (const [path, v] of Object.entries(record)) {
+    const rel = relativeRtdbPath(state.path, path);
+    if (rel !== null && hasRtdbChildren(rtdbValueAt(state.value, rel))) {
+      next[path] = v;
+    } else {
+      changed = true;
+    }
+  }
+  return changed ? next : record;
+}
+
+export function rtdbTreeReducer(
+  state: RtdbTreeState,
+  action: RtdbTreeAction,
+): RtdbTreeState {
+  switch (action.type) {
+    case 'navigate': {
+      const path = normalizeRtdbPath(action.path);
+      // Re-navigating to the current root keeps the loaded value + expansion.
+      if (path === state.path) return state;
+      return initialRtdbTree(path);
+    }
+    case 'value': {
+      if (normalizeRtdbPath(action.path) !== state.path) return state;
+      const next: RtdbTreeState = {
+        ...state,
+        status: 'live',
+        // RTDB semantics at the ingestion seam: an empty object IS null (an
+        // empty database reads back as `{}`), so the tree never holds a
+        // childless object that would render as a scalar leaf.
+        value: normalizeRtdbSnapshotValue(action.value),
+        error: null,
+      };
+      // UPDATE-MERGE: a live snapshot keeps expansion/paging for surviving
+      // paths and prunes state for nodes that vanished or became scalars.
+      next.expanded = pruneByValue(state.expanded, next);
+      next.pages = pruneByValue(state.pages, next);
+      return next;
+    }
+    case 'error':
+      if (normalizeRtdbPath(action.path) !== state.path) return state;
+      return { ...state, status: 'error', error: action.message };
+    case 'expand': {
+      const path = normalizeRtdbPath(action.path);
+      if (path === state.path || state.expanded[path]) return state;
+      // LAZY RENDER: expanding only flips the flag — children mount from the
+      // already-loaded subtree (see the data-loading strategy note above).
+      return { ...state, expanded: { ...state.expanded, [path]: true } };
+    }
+    case 'collapse': {
+      const path = normalizeRtdbPath(action.path);
+      if (!state.expanded[path]) return state;
+      const expanded = { ...state.expanded };
+      delete expanded[path];
+      return { ...state, expanded };
+    }
+    case 'toggle': {
+      const path = normalizeRtdbPath(action.path);
+      return rtdbTreeReducer(state, {
+        type: state.expanded[path] ? 'collapse' : 'expand',
+        path,
+      });
+    }
+    case 'show-more': {
+      const path = normalizeRtdbPath(action.path);
+      const shown = state.pages[path] ?? action.pageSize;
+      return {
+        ...state,
+        pages: { ...state.pages, [path]: shown + action.pageSize },
+      };
+    }
+  }
+}

package/src/rtdb/rtdbApi.ts

@@ -0,0 +1,23 @@
+/**
+ * The RTDB backend seam the viewer drives — an EXPLICIT bundle, not a context
+ * default. Unlike Firestore/Auth/Storage there is no in-process handle typed
+ * into `@pyric/ui`, so the consumer constructs the bundle and passes it to the
+ * hook/components directly (Studio wires it to the SharedWorker client's
+ * admin-lens ops; data views are always admin — PRINCIPLES M3).
+ */
+export interface RtdbApi {
+  /** Replace the value at `path` (`null` deletes, RTDB semantics). */
+  set(path: string, value: unknown): Promise<void>;
+  /** Delete the subtree at `path`. */
+  remove(path: string): Promise<void>;
+  /**
+   * Live value subscription at `path`: `next` fires with the subtree's plain
+   * JSON value (`null` when absent) on subscribe and after every change.
+   * Returns the unsubscribe.
+   */
+  subscribeValue(
+    path: string,
+    next: (value: unknown) => void,
+    error?: (err: unknown) => void,
+  ): () => void;
+}