@structuralists/scaffolding 0.5.0 → 0.6.0

package/src/forms/plan.md

@@ -1,8 +1,31 @@
 # Plan: composable, recursive `Validations`
 
-Status: **proposed** — nothing below is built yet. The baseline (flat
-`Validations<T>`, one validator per key, shallow `Refine`) is on
-`forms/useformstate-baseline`.
+Status: **in progress** — order of operations below. The baseline (flat
+`Validations<T>`, one validator per key, shallow `Refine`) is **merged to main**
+(PR #12, squashed; released as 0.5.0).
+
+## Order of operations
+
+The items were written unordered. The working order is **low-risk /
+low-coupling first**: each early item is independently mergeable and valuable
+even if the risky type work later stalls, and the risk zone comes last so a
+TS wall can't strand finished work behind it.
+
+1. **Item 7 — Debugger.** Zero type risk, valuable for developing everything
+   after it (watching nested state and structured errors live). ← *current*
+2. **Item 1 — validator arrays per key.** `ExcludedOf<C[number]>` already
+   proven inside `allOf`.
+3. **Error-model swap** to `{path, error}[]` on the *flat* baseline (paths
+   are single-key paths). Doesn't depend on nested constraints; hard
+   prerequisite for item 6; makes phases 2–3 runtime-plumbing-free.
+4. **Item 5 — elements/state split.** Pure churn, no type risk; do it before
+   item 6 so the wrappers land in their final home once.
+5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
+   error model and the split; `Path`/`ValueAt` already validated.
+6. **Type spike, then items 2/3/4** — the recursion risk zone. Throwaway
+   `.test-d.ts` of the full grammar at `InsuranceQuoteForm` scale *before*
+   any runtime work; three outcomes (works / slow / intractable) each with a
+   known response. Worst case, everything above still shipped.
 
 ## Goal
 
@@ -15,13 +38,19 @@ Evolve `Validations<T>` so a constraints object can:
    (`Refinement` markers → `Refine<T, V>` → narrowed `onSubmit`) keeps
    working at every level.
 
-Plus two items that ride on top, independent of the type work:
+Plus four items that ride on top, independent of the type work:
 
 5. split the forms area into **'form elements'** and **'form state'**
    (see the section at the end),
 6. **field binding**: a `getFormFieldPropsAt(path)` helper plus
    form-element shorthands (`TextInputForForm` style) so wiring a field is
-   one expression (see the section at the end).
+   one expression (see the section at the end),
+7. **form `Debugger`**: a dev-time overlay component, returned from the
+   hook, that shows the form's live internal state (see the section at the
+   end),
+8. **per-field meta state**: visited/touched tracking and stable React key
+   generation, plus the open research question of keeping that meta state
+   in sync through array manipulation (see the section at the end).
 
 ## Target grammar
 
@@ -255,6 +284,104 @@ Placement note: these wrappers are the bridge between 'form elements' and
 'form state', so where they live should fall out of the split in item 5 —
 they are the one layer allowed to know about both sides.
 
+## 7. Form `Debugger` — dev-time state introspection
+
+A component for watching a form's internal state live while interacting with
+the form proper, in stories and during development. Two elements:
+
+- **Trigger** — small, `position: fixed`, floats above all content
+  (z-index above everything the library renders).
+- **Window** — opened by the trigger; shows a JSON-ish representation of the
+  form's internal state: `values`, `errors`, `isValid`, `submitAttempted`,
+  and whatever internal state lands later (touched map, etc.).
+  `JsonTable` is the obvious in-house renderer for this.
+
+### Hook plumbing
+
+Each `useFormState` instance binds its internal state to its own debugger
+and returns the component on the hook result:
+
+```tsx
+const { values, submit, Debugger, ... } = useFormState({ ... });
+
+return (
+  <>
+    <form>...</form>
+    <Debugger />   {/* dev/story usage; omit it and nothing renders */}
+  </>
+);
+```
+
+Mechanism sketch — a tiny event-emitter/subscription channel, so the
+form's own render tree never pays for the debugger:
+
+- The hook keeps a small store (current snapshot + subscriber set) in a ref
+  and publishes into it each render — publishing is a no-op when nobody
+  subscribes.
+- `Debugger` is created once per hook instance (stable identity across
+  renders — memoized, not redefined inline, or it remounts every keystroke)
+  and closes over that store. When mounted and open, it subscribes —
+  `useSyncExternalStore` is the natural fit — so state flows hook → store →
+  debugger without threading props or context.
+- Rendering the window is where the debugger pays its cost; a closed
+  trigger is ~free.
+
+### Open questions (for when this is picked up)
+
+- **Snapshot transport**: display-side needs stable snapshots (rendering
+  live mutable refs tears); likely publish a frozen snapshot object per
+  render.
+- **Multiple forms on one screen**: each hook returns its own `Debugger`,
+  so triggers could stack/overlap. May want an instance label prop and/or
+  offset management; punt until it hurts.
+- **Production leakage**: it's dev tooling, but it ships in the library.
+  Decide whether it's tree-shaken naturally (only renders if placed in
+  JSX — probably sufficient) or needs an env gate.
+- **Placement re: item 5 split**: the plumbing is 'form state'; the
+  trigger/window UI is presentational. Like the item-6 wrappers, it's a
+  bridge layer — settle its home when the split lands.
+
+## 8. Per-field meta state: visited tracking + stable React keys
+
+Alongside the *value* tree, the hook needs a parallel *meta* tree — state
+about fields that isn't field data:
+
+- **visited/touched** — has the user interacted with this field yet? Feeds
+  the error-display policy (item 6's `errorMessage` gates on it via
+  `onBlur`).
+- **stable React keys** — list elements need identity that survives
+  reorders/inserts/removals. Index keys break exactly when lists get
+  interesting; the meta layer is the natural place to mint and hold a
+  stable id per element.
+
+### The hard part: array manipulation keeping meta in sync (open research)
+
+When a list is reordered, inserted into, or spliced, per-element meta
+(visited flags, keys) must follow its element — not its index. Two candidate
+approaches, deliberately unresolved until we get there:
+
+- **Owned array operations.** Past projects needed a dedicated set of list
+  manipulation ops (`insertAt`, `removeAt`, `move`, …) that update values
+  and meta in the same motion. Known to work; the cost is that consumers
+  must use *our* ops — raw `onValueChanges` with a hand-spliced array
+  silently desyncs meta.
+- **Identity tracking via Map/WeakMap.** Keep meta keyed by element object
+  identity (`WeakMap<element, meta>`) rather than by path/index, and detect
+  reorders by re-matching identities after each change. Frees consumers to
+  manipulate arrays however they like; open questions are elements that get
+  *replaced* rather than moved (immutable-update styles create new objects
+  on every edit — identity breaks precisely when fields are edited), and
+  primitive-element lists (`string[]`) which have no stable identity at all.
+
+Possibly a hybrid: identity-matching as the default heuristic, owned ops as
+the guaranteed path. **Research topic for when we get here** — record
+findings in the learning map before committing to either.
+
+Sequencing: visited tracking lands with item 6 (its `onBlur` is the write
+path). Keys + array-sync matter from phase 3 (list `each` specs) onward —
+error paths and per-element meta both need element identity once lists are
+editable.
+
 ## Open decisions
 
 - **Whole-value + structural constraints on the same key** (e.g. validate

package/src/forms/useFormState/FormDebugger.module.css

@@ -0,0 +1,41 @@
+.root {
+  position: fixed;
+  right: var(--ui-space-4);
+  bottom: var(--ui-space-4);
+  /* Same z-index tier as every other portal layer (Modal, Popover, Tooltip);
+   * stacking between layers comes from DOM-append order, not z-index. */
+  z-index: 100;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--ui-space-2);
+  font-family: var(--ui-font);
+}
+
+.trigger {
+  padding: var(--ui-space-1) var(--ui-space-3);
+  font-family: var(--ui-font-mono);
+  font-size: var(--ui-text-xsmall);
+  color: var(--ui-foreground);
+  background-color: var(--ui-background-1);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius-large);
+  box-shadow: 0 2px 8px var(--ui-shadow-soft);
+  cursor: pointer;
+  user-select: none;
+}
+
+.trigger:hover {
+  background-color: var(--ui-background-2);
+}
+
+.window {
+  width: 360px;
+  max-height: min(480px, 60vh);
+  overflow: auto;
+  padding: var(--ui-space-2);
+  background-color: var(--ui-background-0);
+  border: 1px solid var(--ui-border);
+  border-radius: var(--ui-radius-large);
+  box-shadow: 0 4px 16px var(--ui-shadow-soft);
+}

package/src/forms/useFormState/FormDebugger.test.tsx

@@ -0,0 +1,74 @@
+import { afterEach, describe, test, expect } from 'bun:test';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+
+// The Debugger portals into document.body, so leftovers from a previous
+// test are visible to `screen` queries — clean up explicitly (bun:test has
+// no global afterEach for RTL's auto-cleanup to hook).
+afterEach(cleanup);
+import { useFormState } from './useFormState';
+import { notEmpty } from '../validators/validators';
+
+type DebugForm = { nickname: string | undefined };
+
+const DebugHost = () => {
+  const { values, onValueChanges, Debugger } = useFormState({
+    initialValues: { nickname: undefined } as DebugForm,
+    constraints: { nickname: notEmpty('nickname') },
+  });
+
+  return (
+    <div>
+      <input
+        aria-label="nickname"
+        value={values.nickname ?? ''}
+        onChange={(e) => {
+          const nickname = e.target.value;
+          onValueChanges((prev) => ({ ...prev, nickname }));
+        }}
+      />
+      <Debugger label="debug me" />
+    </div>
+  );
+};
+
+describe('FormDebugger', () => {
+  test('renders the trigger with the window closed', () => {
+    render(<DebugHost />);
+    expect(screen.getByRole('button', { name: 'debug me' })).toBeTruthy();
+    expect(screen.queryByText('isValid')).toBeNull();
+  });
+
+  test('clicking the trigger opens the window with the current state', () => {
+    render(<DebugHost />);
+    fireEvent.click(screen.getByRole('button', { name: 'debug me' }));
+
+    expect(screen.getByText('isValid')).toBeTruthy();
+    expect(screen.getByText('submitAttempted')).toBeTruthy();
+    expect(screen.getByText("'nickname' cannot be empty")).toBeTruthy();
+  });
+
+  test('the open window live-updates as the form changes', () => {
+    render(<DebugHost />);
+    fireEvent.click(screen.getByRole('button', { name: 'debug me' }));
+
+    fireEvent.change(screen.getByLabelText('nickname'), {
+      target: { value: 'will' },
+    });
+
+    // The window survived the form re-render (stable component identity —
+    // a remount would have reset it to closed) and shows the new state.
+    expect(screen.getByText('will')).toBeTruthy();
+    expect(screen.queryByText("'nickname' cannot be empty")).toBeNull();
+  });
+
+  test('clicking the trigger again closes the window', () => {
+    render(<DebugHost />);
+    const trigger = screen.getByRole('button', { name: 'debug me' });
+
+    fireEvent.click(trigger);
+    expect(screen.getByText('isValid')).toBeTruthy();
+
+    fireEvent.click(trigger);
+    expect(screen.queryByText('isValid')).toBeNull();
+  });
+});

package/src/forms/useFormState/FormDebugger.tsx

@@ -0,0 +1,72 @@
+import { useState, useSyncExternalStore } from 'react';
+import type { ReactElement } from 'react';
+import { createPortal } from 'react-dom';
+import { JsonTable } from '../../components/Json/JsonTable';
+import { toInspectable } from './inspectable';
+import type { SnapshotStore } from './snapshotStore';
+import type { FormDebugSnapshot, FormValuesObject } from './types';
+import styles from './FormDebugger.module.css';
+
+export type FormDebuggerProps = {
+  /** Trigger text. Give each form a distinct label when several debuggers
+   *  are mounted at once — triggers stack in the same corner. */
+  label?: string;
+};
+
+export type FormDebuggerComponent = (props: FormDebuggerProps) => ReactElement;
+
+// Builds the per-hook-instance Debugger component. Called once per
+// `useFormState` instance (from a lazy ref) so the returned component's
+// identity is stable across renders — a component recreated each render
+// would remount, and lose its open/closed state, on every keystroke.
+export const createFormDebugger = <T extends FormValuesObject>(
+  store: SnapshotStore<FormDebugSnapshot<T>>,
+): FormDebuggerComponent => {
+  // The subscription lives in the window, not the trigger: a closed
+  // debugger never re-renders with the form.
+  const DebuggerWindow = (props: { label: string }) => {
+    const { label } = props;
+
+    const snapshot = useSyncExternalStore(
+      store.subscribe,
+      store.getSnapshot,
+      store.getSnapshot,
+    );
+
+    return (
+      <div className={styles.window}>
+        <JsonTable
+          title={label}
+          value={toInspectable({
+            isValid: snapshot.isValid,
+            submitAttempted: snapshot.submitAttempted,
+            values: snapshot.values,
+            errors: snapshot.errors,
+          })}
+        />
+      </div>
+    );
+  };
+
+  const FormDebugger = (props: FormDebuggerProps) => {
+    const { label = 'form state' } = props;
+
+    const [isOpen, setIsOpen] = useState(false);
+
+    return createPortal(
+      <div className={styles.root}>
+        {isOpen && <DebuggerWindow label={label} />}
+        <button
+          type="button"
+          className={styles.trigger}
+          onClick={() => setIsOpen((open) => !open)}
+        >
+          {label}
+        </button>
+      </div>,
+      document.body,
+    );
+  };
+
+  return FormDebugger;
+};

package/src/forms/useFormState/inspectable.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from 'bun:test';
+import { toInspectable } from './inspectable';
+
+describe('toInspectable', () => {
+  test('passes leaves through untouched', () => {
+    expect(toInspectable('hi')).toBe('hi');
+    expect(toInspectable(42)).toBe(42);
+    expect(toInspectable(10n)).toBe(10n);
+    expect(toInspectable(null)).toBeNull();
+    expect(toInspectable(undefined)).toBeUndefined();
+    expect(toInspectable(true)).toBe(true);
+  });
+
+  test('converts arrays to index-keyed objects', () => {
+    expect(toInspectable(['a', 'b'])).toEqual({ 0: 'a', 1: 'b' });
+  });
+
+  test('converts arrays of objects recursively', () => {
+    expect(toInspectable([{ name: 'ada' }, { name: 'bo' }])).toEqual({
+      0: { name: 'ada' },
+      1: { name: 'bo' },
+    });
+  });
+
+  test('renders Sets as a descriptive string leaf', () => {
+    expect(toInspectable(new Set(['a', 'b']))).toBe('Set(2) { "a", "b" }');
+    expect(toInspectable(new Set())).toBe('Set(0) {  }');
+  });
+
+  test('walks nested objects', () => {
+    const form = {
+      email: 'a@b.co',
+      address: { city: undefined, tags: ['home'] },
+      drivers: [{ name: 'ada', incidents: [] }],
+    };
+    expect(toInspectable(form)).toEqual({
+      email: 'a@b.co',
+      address: { city: undefined, tags: { 0: 'home' } },
+      drivers: { 0: { name: 'ada', incidents: {} } },
+    });
+  });
+});

package/src/forms/useFormState/inspectable.ts

@@ -0,0 +1,35 @@
+// Converts a form-state snapshot into a shape JsonTable renders without
+// throwing. JsonTable dispatches on "plain object vs leaf": arrays and Sets
+// fall to the leaf renderer, and an array of objects (FormValueList) would
+// throw as a React child. A debugger must render *any* legal form state, so:
+//
+//   - arrays  → index-keyed plain objects ({ 0: ..., 1: ... }), recursively
+//   - Sets    → a descriptive string leaf: `Set(2) { "a", "b" }`
+//   - objects → walked recursively
+//   - leaves  → passed through untouched
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype ||
+    Object.getPrototypeOf(value) === null);
+
+export const toInspectable = (value: unknown): unknown => {
+  if (value instanceof Set) {
+    const members = [...value].map((member) => JSON.stringify(member));
+    return `Set(${value.size}) { ${members.join(', ')} }`;
+  }
+
+  if (Array.isArray(value)) {
+    return Object.fromEntries(
+      value.map((element, index) => [index, toInspectable(element)]),
+    );
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => [key, toInspectable(child)]),
+    );
+  }
+
+  return value;
+};

package/src/forms/useFormState/snapshotStore.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { createSnapshotStore } from './snapshotStore';
+
+describe('createSnapshotStore', () => {
+  test('getSnapshot returns the initial snapshot', () => {
+    const store = createSnapshotStore({ n: 1 });
+    expect(store.getSnapshot()).toEqual({ n: 1 });
+  });
+
+  test('publish replaces the snapshot and notifies subscribers', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const onChange = mock(() => {});
+    store.subscribe(onChange);
+
+    store.publish({ n: 2 });
+
+    expect(store.getSnapshot()).toEqual({ n: 2 });
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  test('publish keeps the snapshot reference stable between publishes', () => {
+    const store = createSnapshotStore({ n: 1 });
+    store.publish({ n: 2 });
+    expect(store.getSnapshot()).toBe(store.getSnapshot());
+  });
+
+  test('unsubscribe stops notifications', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const onChange = mock(() => {});
+    const unsubscribe = store.subscribe(onChange);
+
+    unsubscribe();
+    store.publish({ n: 2 });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('publish with no subscribers is a no-op notify', () => {
+    const store = createSnapshotStore({ n: 1 });
+    expect(() => store.publish({ n: 2 })).not.toThrow();
+    expect(store.getSnapshot()).toEqual({ n: 2 });
+  });
+
+  test('notifies every subscriber', () => {
+    const store = createSnapshotStore({ n: 1 });
+    const first = mock(() => {});
+    const second = mock(() => {});
+    store.subscribe(first);
+    store.subscribe(second);
+
+    store.publish({ n: 2 });
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

package/src/forms/useFormState/snapshotStore.ts

@@ -0,0 +1,31 @@
+// Minimal external store connecting a hook's per-render state to observers
+// outside its render tree (the form Debugger). Shaped for
+// `useSyncExternalStore`: `subscribe` returns an unsubscribe function and
+// `getSnapshot` must keep returning the same reference until the next
+// `publish` — snapshots are replaced whole, never mutated.
+export type SnapshotStore<Snapshot> = {
+  publish: (next: Snapshot) => void;
+  subscribe: (onChange: () => void) => () => void;
+  getSnapshot: () => Snapshot;
+};
+
+export const createSnapshotStore = <Snapshot,>(
+  initial: Snapshot,
+): SnapshotStore<Snapshot> => {
+  let current = initial;
+  const listeners = new Set<() => void>();
+
+  return {
+    publish: (next) => {
+      current = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (onChange) => {
+      listeners.add(onChange);
+      return () => {
+        listeners.delete(onChange);
+      };
+    },
+    getSnapshot: () => current,
+  };
+};

package/src/forms/useFormState/types.ts

@@ -1,3 +1,7 @@
+// Type-only import; FormDebugger.tsx imports value types from this file in
+// turn, but the cycle never exists at runtime.
+import type { FormDebuggerComponent } from './FormDebugger';
+
 export type FormValueSimple = string | number | bigint | string[] | Set<string> | undefined | null;
 
 export type FormValuesObject = { [k in string]: FormValue };
@@ -10,6 +14,16 @@ export type FormErrors<T extends FormValuesObject> = Partial<
   Record<keyof T, string>
 >;
 
+// What the hook publishes to its Debugger after every commit. Snapshots are
+// replaced whole (never mutated) so `useSyncExternalStore` consumers can
+// rely on reference equality.
+export type FormDebugSnapshot<T extends FormValuesObject> = {
+  values: T;
+  errors: FormErrors<T>;
+  isValid: boolean;
+  submitAttempted: boolean;
+};
+
 export type FormHelpers<T extends FormValuesObject> = {
   values: T;
   // todo: likely remove once other setter are available
@@ -20,4 +34,8 @@ export type FormHelpers<T extends FormValuesObject> = {
   isValid: boolean;
   submitAttempted: boolean;
   submit: () => void;
+  // Dev-time introspection overlay bound to this form instance: a fixed
+  // trigger that opens a window showing the form's live internal state.
+  // Render it anywhere (it portals to <body>); omit it and nothing mounts.
+  Debugger: FormDebuggerComponent;
 };

package/src/forms/useFormState/useFormState.stories.tsx

@@ -194,3 +194,110 @@ export const LiveValidity: Story = {
     </div>
   ),
 };
+
+type DebuggerDemoValues = {
+  email: string | undefined;
+  nickname: string | undefined;
+  tags: string[];
+};
+
+// The Debugger comes off the hook itself — drop it anywhere in the tree and
+// a fixed trigger appears bottom-right; open it and watch values/errors/
+// isValid/submitAttempted update live as you interact with the form.
+const DebuggerDemo = () => {
+  const [tagDraft, setTagDraft] = useState('');
+
+  const { values, onValueChanges, errors, submitAttempted, submit, Debugger } =
+    useFormState({
+      initialValues: {
+        email: undefined,
+        nickname: undefined,
+        tags: [],
+      } as DebuggerDemoValues,
+      constraints: {
+        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        nickname: notEmpty('nickname'),
+      },
+    });
+
+  const shownErrors = submitAttempted ? errors : {};
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <Field label="Email" error={shownErrors.email} htmlFor="debug-email">
+        <Input
+          id="debug-email"
+          type="email"
+          value={values.email ?? ''}
+          onChange={(e) => {
+            const email = e.target.value;
+            onValueChanges((prev) => ({ ...prev, email }));
+          }}
+          placeholder="you@example.com"
+        />
+      </Field>
+
+      <Field label="Nickname" error={shownErrors.nickname} htmlFor="debug-nickname">
+        <Input
+          id="debug-nickname"
+          value={values.nickname ?? ''}
+          onChange={(e) => {
+            const nickname = e.target.value;
+            onValueChanges((prev) => ({ ...prev, nickname }));
+          }}
+        />
+      </Field>
+
+      <Field
+        label="Tags"
+        hint="Unconstrained string[] — shows how the Debugger renders list values"
+        htmlFor="debug-tag-draft"
+      >
+        <div style={{ display: 'flex', gap: 8 }}>
+          <Input
+            id="debug-tag-draft"
+            value={tagDraft}
+            onChange={(e) => setTagDraft(e.target.value)}
+            placeholder="add a tag"
+          />
+          <Button
+            type="button"
+            onClick={() => {
+              if (!tagDraft) return;
+              onValueChanges((prev) => ({ ...prev, tags: [...prev.tags, tagDraft] }));
+              setTagDraft('');
+            }}
+          >
+            Add
+          </Button>
+        </div>
+      </Field>
+
+      {values.tags.length > 0 && (
+        <div style={{ fontSize: 13 }}>tags: {values.tags.join(', ')}</div>
+      )}
+
+      <div>
+        <Button type="submit" variant="primary">
+          Submit
+        </Button>
+      </div>
+
+      <Debugger label="signup form" />
+    </form>
+  );
+};
+
+export const WithDebugger: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <DebuggerDemo />
+    </div>
+  ),
+};