@structuralists/scaffolding 0.10.2 → 0.12.0

package/eslint.config.mjs

@@ -132,10 +132,10 @@ export default [{
               "Files inside a primitive folder must not import their own index barrel; import the neighbor directly.",
           },
           // Presentational primitives (components and form elements) must
-          // not reach into the form-state layer. The sanctioned bridge runs
+          // not reach into the form-state layer. The sanctioned bridges run
           // the other way: state's FormDebugger imports the JsonTable barrel
-          // (dev tooling), and the item-6 form-aware wrappers will live with
-          // the state side. State stories may also use element barrels.
+          // (dev tooling), and the form-aware wrappers live on the state
+          // side (state/bindings/). State stories may also use element barrels.
           {
             from: [
               { type: 'primitive' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/components/Json/JsonTable/JsonLeafNode.tsx

@@ -1,36 +1,39 @@
-import { Text } from '../../Content/Text';
+import styles from './styles.module.css';
 
 export type JsonLeafNodeProps = {
   value: unknown;
-  /** When true, render `null` / `undefined` via Text with the monospace font.
-   *  JsonTable sets this on recursive calls so leaves inside a table inherit
-   *  the same font as the surrounding monospace cells (Text otherwise sets
-   *  its own font-family and would break the inheritance). */
-  isMono?: boolean;
 };
 
 /**
- * Renders one value as a leaf — text only, no JSON tree viewer. Handles
- * the primitives React can't render directly (boolean, null, undefined)
- * and lets strings/numbers flow through as JSX children. Anything else
- * (objects, arrays, Dates, Maps, …) currently falls through to `{value}`
- * — that will throw at render time for non-renderable types and is the
- * placeholder until JsonTable grows specialized renderers for them.
+ * Renders one value as a leaf — text only, no JSON tree viewer. Each
+ * primitive type gets a color class so the value reads like Chrome's
+ * inspector: strings in orange (with quotes), numbers in blue, booleans
+ * in purple, `null`/`undefined` in pink. Anything else (objects, arrays,
+ * Dates, Maps, …) currently falls through to `{value}` — that will throw
+ * at render time for non-renderable types and is the placeholder until
+ * JsonTable grows specialized renderers for them.
  */
 export const JsonLeafNode = (props: JsonLeafNodeProps) => {
-  const { value, isMono } = props;
-  const size = isMono ? 'small' : undefined;
+  const { value } = props;
 
   if (value === null) {
-    return <Text isMuted isMono={isMono} size={size}>null</Text>;
+    return <span className={styles.nil}>null</span>;
   }
 
   if (value === undefined) {
-    return <Text isMuted isMono={isMono} size={size}>undefined</Text>;
+    return <span className={styles.nil}>undefined</span>;
   }
 
   if (typeof value === 'boolean') {
-    return <>{String(value)}</>;
+    return <span className={styles.boolean}>{String(value)}</span>;
+  }
+
+  if (typeof value === 'string') {
+    return <span className={styles.string}>{JSON.stringify(value)}</span>;
+  }
+
+  if (typeof value === 'number') {
+    return <span className={styles.number}>{value}</span>;
   }
 
   return <>{value}</>;

package/src/components/Json/JsonTable/JsonTable.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
 import { JsonTable } from './index';
 
 const meta: Meta<typeof JsonTable> = {
@@ -50,3 +51,89 @@ export const PrimitivesAtTopLevel: Story = {
     </div>
   ),
 };
+
+export const ValueColors: Story = {
+  name: 'Value colors per primitive type',
+  render: () => (
+    <JsonTable
+      title="Primitive value colors"
+      value={{
+        aString: 'hello world',
+        anEmptyString: '',
+        aQuotedString: 'say "hi"',
+        aMultilineString: 'line one\nline two',
+        aNumber: 12345,
+        aFloat: 3.14159,
+        aTrue: true,
+        aFalse: false,
+        aNull: null,
+        anUndefined: undefined,
+      }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('"hello world"')).toBeInTheDocument();
+    await expect(canvas.getByText('"say \\"hi\\""')).toBeInTheDocument();
+    await expect(canvas.getByText('"line one\\nline two"')).toBeInTheDocument();
+  },
+};
+
+const deepSample = {
+  id: 'org_8821',
+  name: 'Northwind Logistics',
+  region: 'us-west-2',
+  active: true,
+  founded: 2014,
+  headquarters: {
+    address: {
+      street: '120 Pier Ave',
+      city: 'Seattle',
+      state: 'WA',
+      zip: '98101',
+      coords: { lat: 47.6062, lng: -122.3321 },
+    },
+    capacity: 240,
+    isLeased: false,
+  },
+  teams: [
+    {
+      id: 'team_platform',
+      name: 'Platform',
+      headcount: 12,
+      lead: { id: 'usr_1042', name: 'Alice Park', email: 'alice@northwind.io' },
+      members: [
+        { id: 'usr_1042', name: 'Alice Park', role: 'lead', onCall: true },
+        { id: 'usr_1109', name: 'Ben Ortiz', role: 'engineer', onCall: false },
+        { id: 'usr_1188', name: 'Chen Wu', role: 'engineer', onCall: false },
+      ],
+      tags: ['core', 'oncall', 'sre'],
+    },
+    {
+      id: 'team_data',
+      name: 'Data',
+      headcount: 7,
+      lead: { id: 'usr_1301', name: 'Dana Reyes', email: 'dana@northwind.io' },
+      members: [
+        { id: 'usr_1301', name: 'Dana Reyes', role: 'lead', onCall: false },
+        { id: 'usr_1422', name: 'Evan Liu', role: 'analyst', onCall: false },
+      ],
+      tags: ['analytics', 'etl'],
+    },
+  ],
+  integrations: [
+    { kind: 'slack', enabled: true, channel: '#alerts', retries: 3 },
+    { kind: 'pagerduty', enabled: true, escalation: { primary: 'usr_1042', secondary: null } },
+    { kind: 'jira', enabled: false, project: null },
+  ],
+  flags: {
+    betaFeatures: ['new-dashboard', 'inline-edit'],
+    rateLimits: { rpm: 600, burst: 1200, throttleAfter: null },
+  },
+  notes: undefined,
+};
+
+export const DeepNested: Story = {
+  name: 'Deeply nested (objects + arrays)',
+  render: () => <JsonTable value={deepSample} title="Organization" />,
+};

package/src/components/Json/JsonTable/index.tsx

@@ -13,8 +13,13 @@ import styles from './styles.module.css';
 export const JsonTable = (props: JsonTableProps) => {
   const { value, title, isNested } = props;
 
-  if (isPlainObject(value)) {
-    const entries = Object.entries(value);
+  const isObject = isPlainObject(value);
+  const isArray = Array.isArray(value);
+
+  if (isObject || isArray) {
+    const entries: [string, unknown][] = isArray
+      ? value.map((item, i) => [String(i), item])
+      : Object.entries(value as Record<string, unknown>);
 
     const headerRow = title ? (
       <QuickTableHeaderRow>
@@ -26,12 +31,14 @@ export const JsonTable = (props: JsonTableProps) => {
       <QuickTable headerRow={headerRow} hasColumnDividers hasOuterBorder={!isNested}>
         {entries.map((entry) => {
           const [key, child] = entry;
-          const childIsObject = isPlainObject(child);
+          const childIsContainer = isPlainObject(child) || Array.isArray(child);
 
           return (
             <QuickTableRow key={key}>
-              <QuickTableCell width={1}>{key}</QuickTableCell>
-              <QuickTableCell hasPadding={!childIsObject}>
+              <QuickTableCell width={1}>
+                <span className={styles.key}>{key}</span>
+              </QuickTableCell>
+              <QuickTableCell hasPadding={!childIsContainer}>
                 <JsonTable value={child} title={key} isNested />
               </QuickTableCell>
             </QuickTableRow>
@@ -43,7 +50,7 @@ export const JsonTable = (props: JsonTableProps) => {
     return isNested ? table : <div className={styles.root}>{table}</div>;
   }
 
-  return <JsonLeafNode value={value} isMono={isNested} />;
+  return <JsonLeafNode value={value} />;
 };
 
 export type { JsonTableProps };

package/src/components/Json/JsonTable/styles.module.css

@@ -5,3 +5,23 @@
 .root thead tr {
   border-bottom-color: var(--ui-border-subtle);
 }
+
+.key {
+  color: var(--ui-json-key);
+}
+
+.string {
+  color: var(--ui-json-string);
+}
+
+.number {
+  color: var(--ui-json-number);
+}
+
+.boolean {
+  color: var(--ui-json-boolean);
+}
+
+.nil {
+  color: var(--ui-json-nil);
+}

package/src/components/Json/JsonTable/types.ts

@@ -12,11 +12,9 @@ export type JsonTableProps = {
    *  labeled table. */
   title?: ReactNode;
   /** @internal Set by JsonTable on every recursive call (i.e. when rendering
-   *  a child entry of a parent table). Two effects: (1) on a nested object,
+   *  a child entry of a parent table). On a nested object or array,
    *  suppresses the outer border so the inner table sits flush inside its
-   *  parent cell — whose padding is also dropped at the parent level; (2) on
-   *  a primitive leaf, signals JsonLeafNode to render `null` / `undefined`
-   *  via Text with the monospace font so they inherit the surrounding font
-   *  set by the JsonTable root. Not intended for external callers. */
+   *  parent cell — whose padding is also dropped at the parent level. Not
+   *  intended for external callers. */
   isNested?: boolean;
 };

package/src/forms/CLAUDE.md

@@ -10,10 +10,11 @@ The forms umbrella, split into two named subtrees:
 - `state/` — the strongly-typed React form state hook and its machinery.
   Everything below this heading is about the state layer.
 
-The one sanctioned state→elements-side dependency is the Debugger bridge:
-`state/useFormState/FormDebugger.tsx` imports the `JsonTable` barrel from
-`src/components/Json/` (dev tooling). The item-6 form-aware wrappers will be
-the second bridge, living on the state side.
+Two sanctioned state→elements-side bridges exist, both on the state side:
+the Debugger (`state/useFormState/FormDebugger.tsx` imports the `JsonTable`
+barrel from `src/components/Json/`, dev tooling) and the form-aware element
+wrappers (`state/bindings/` — see "Field binding" below). State files
+importing an element go through its barrel like any external importer.
 
 The headline feature of the state layer is **validation that propagates type
 refinements to the submit handler** — passing the right constraints means the
@@ -49,25 +50,67 @@ function composition.
 
 ## What a constraints key may map to
 
+The grammar is recursive. What a key admits is directed by the *field's*
+type, never guessed from the constraint's shape:
+
 ```ts
 type FieldConstraint<F> =
+  // leaf forms — legal for ANY field type, structural fields included
   | FieldValidator<F>            // one validator
   | readonly FieldValidator<F>[] // several, run in order, first error wins
+  // structural forms — only where the field type permits
+  | (F extends FormValuesObject ? Validations<F> : never)  // nested spec
+  | (F extends FormValueList ? ListConstraint<F[number]> : never); // { each: … }
 ```
 
 The array form is the everyday way to stack validators on a field at the
-constraint site:
+constraint site; a nested spec addresses the fields of an object section;
+`each` applies a spec to every element of a list. All compose freely:
 
 ```ts
 constraints: {
   email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+  homeAddress: {
+    city: notEmpty('city'),
+    postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+  },
+  drivers: {
+    each: {
+      name: notEmpty('name'),
+      incidents: { each: { date: notEmpty('date') } },
+    },
+  },
 }
 ```
 
-Semantics are identical to `allOf` (which remains the tool for building
-*reusable, named* composite validators): validators run in array order,
-the first error is the field's error, and later validators don't run once
-one fails. An empty array passes and narrows nothing.
+Array semantics are identical to `allOf` (which remains the tool for
+building *reusable, named* composite validators): validators run in array
+order, the first error is the field's error, and later validators don't run
+once one fails. An empty array passes and narrows nothing.
+
+Grammar doctrine, in force at the type level and in the runtime walk:
+
+- **Disambiguation is by the value model.** An object field that owns a key
+  literally named `each` still takes a nested spec — for an object-typed
+  field only the `Validations<F>` arm is live, for a list-typed field only
+  `ListConstraint`. Both `RefineField` and the walk interrogate the
+  field/value before the constraint's shape.
+- **Leaf forms stay legal on structural fields.** A bare validator on an
+  object field is a whole-section validator (`mailingAddress:
+  notEmpty(…)` is how "required section" is expressed); a validator array
+  on a list field validates the list as a value. Leaf and structural forms
+  are mutually exclusive per key (recorded open decision — a future `self`
+  slot).
+- **A nested spec on an absent (null/undefined) section validates
+  nothing**, at the type level (only the present branch refines;
+  nullability survives around the refined interior) and at runtime (the
+  walk skips — nothing to walk). Same for `each` over a null list.
+- **`F` stays naked in the structural arms.** Nullable sections/lists work
+  purely by distribution; wrapping the checked type in `NonNullable` breaks
+  it and blows the recursion stack (TS2589).
+- **Runtime status of `each`:** type-level only until plan phase 3. An
+  `each` constraint on a present list makes the walk THROW a clear error
+  instead of silently not validating.
 
 ## Aggregation: `perField`
 
@@ -78,7 +121,11 @@ const constraints = perField({
 ```
 
 `perField` is the entry point that produces a `Validations<FormType>`-shaped
-value while preserving the precise types of each individual validator.
+value while preserving the precise types of each individual validator. It
+currently admits only the leaf forms (a validator or validator array per
+key) — extending it to pre-built nested/`each` specs is plan phase 4
+(composition hardening); until then, write structural constraints inline in
+the `useFormState` call.
 
 ### The precision-preserving ceremony, by call-site shape
 
@@ -136,10 +183,11 @@ unreliable in some intersections.
 
 ## `Refine<FormType, typeof constraints>`
 
-Walks the constraints object, reads each field's validator's
-`__excludes` marker, applies `Exclude<FormType[K], __excludes>`. Fields
-without a constraint pass through unchanged. The result is the type
-handed to `onSubmit`.
+Walks the constraints object recursively, mirroring the grammar: leaves
+apply `Exclude<FormType[K], __excludes>` from their validators' markers,
+nested specs recurse into the section, `each` specs refine the element type
+and flow it through `Array<...>`. Fields without a constraint pass through
+unchanged, at every level. The result is the type handed to `onSubmit`.
 
 ```ts
 type FormType   = { a: string | undefined; b: number };
@@ -147,6 +195,18 @@ type C          = typeof constraints;             // a: notEmpty
 type SubmitType = Refine<FormType, C>;            // { a: string; b: number }
 ```
 
+`Refine` opens with an identity gate — `Validations<T> extends V ? T :
+RefineObject<T, V>` — and the gate is load-bearing, not an optimization:
+with constraints omitted the hook's default `V = Validations<T>` would
+distribute `FieldConstraint<F> | undefined` through the walk at every key
+and hand back unions of structurally-identical mapped *copies* of every
+section — assignable to `T` but not identity-equal (mangled hover types;
+the "without constraints, onSubmit receives the unrefined form type" probe
+fails). Any concrete constraints literal is strictly narrower than
+`Validations<T>`, so the gate stays open and the real walk runs. Nested
+occurrences don't need their own gate: a concrete literal's `keyof V` holds
+only the keys actually written, so uncovered fields take `T[K]` verbatim.
+
 Per-field dispatch lives in `RefineField<F, C>`, whose constraint parameter
 is deliberately **naked** so unions of constraint types distribute. Two
 regimes of "multiple markers per field" follow from that, both sound:
@@ -168,10 +228,17 @@ regimes of "multiple markers per field" follow from that, both sound:
   per-branch refinements* (`Exclude<F, A> | Exclude<F, B>`), never a
   narrowing the running branch didn't earn.
 
-Branch order inside `RefineField`: the `Refinement` check must stay ahead of
-the array check and any future structural (object) check — validator
-functions are objects, and a marked validator must not fall into a
-structural arm.
+Both regimes survive recursion verbatim — the same soundness holds for
+union-typed constraints inside nested and `each` specs (probed at depth in
+`useFormState.test-d.ts`).
+
+Branch order inside `RefineField`: `Refinement` first — validator functions
+are objects, and a marked validator must not fall into a structural arm —
+then arrays, then the structural arms, which interrogate the FIELD type
+before the constraint's shape (`F extends FormValueList` is asked before
+looking for an `each` key, so an object field literally named `each`
+refines as a nested spec). A bare marker-less validator on a structural
+field lands in `RefineObject` with an empty `keyof C` — an identity map.
 
 ## Hook surface
 
@@ -188,10 +255,15 @@ useFormState({
 Validation failures surface as a structured list, not a keyed record:
 
 ```ts
-type FormError<T>  = { path: Path<T>; error: string }; // single-key paths on the flat grammar
+type FormError<T>  = { path: Path<T>; error: string }; // one entry per failing constrained node
 type FormErrors<T> = readonly FormError<T>[];          // isValid === (errors.length === 0)
 ```
 
+Paths are as deep as the failing node: a root leaf contributes `['email']`,
+a nested-spec leaf `['homeAddress', 'postalCode']`. Sibling nodes fail
+independently — first-error-wins applies *within* one validator array, not
+across fields.
+
 Read one field's message with the typed accessor, never by hand-assembled
 keys — serialized path strings (`'drivers.0.name'`) are deliberately not
 exposed:
@@ -201,11 +273,74 @@ errorAt(errors, ['email']); // string | undefined
 ```
 
 `errorAt` (state/useFormState/errorAt.ts) matches by exact structural step
-equality (no prefix matching); with first-error-wins validation there is at
-most one entry per path, and if collect-all ever lands the first entry stays
-the one shown. The path-addressed model is what the recursive grammar
-(errors just carry longer paths) and `getFormFieldPropsAt`'s `errorMessage`
-build on.
+equality (`pathsEqual` in state/path/path.ts — no prefix matching); with
+first-error-wins validation there is at most one entry per path, and if
+collect-all ever lands the first entry stays the one shown. The
+path-addressed model is what the recursive grammar (errors just carry
+longer paths) and `getFormFieldPropsAt`'s `errorMessage` build on. `errorAt`
+is raw truth (no display gating); `errorMessage` is the display-policy-aware
+reading (see "Field binding").
+
+## Field binding: `getFormFieldPropsAt(path)` + `state/bindings/`
+
+One expression wires a field to the form:
+
+```tsx
+<TextInputForForm label="City"
+  formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])} />
+```
+
+`getFormFieldPropsAt` is a member of the hook's return value, typed by the
+`state/path/` machinery:
+
+```ts
+// on FormHelpers<T>:
+getFormFieldPropsAt<P extends Path<T>>(path: P): FormFieldProps<ValueAt<T, P>>;
+
+type FormFieldProps<V> = FieldBinding<V>;
+type FieldBinding<Display, Emit = Display> = {
+  value: Display;                   // read(values, path)
+  onChange: (val: Emit) => void;    // immutable write(values, path, val)
+  errorMessage: string | undefined; // display-policy-aware (below)
+  onBlur: () => void;               // feeds touched tracking
+};
+```
+
+The pieces, and where each one's semantics live:
+
+- **Granular path writes** — `write()` in `state/path/path.ts`, the
+  immutable-update mirror of `read()`: clones only the spine to the written
+  leaf, so untouched siblings keep identity. Dead-step semantics mirror
+  read() returning undefined: writing through an absent/null ancestor, a
+  shape mismatch, or an out-of-bounds index is an identity-preserving no-op
+  — you can't edit a field of an absent section; materialize the section
+  first. (Appending/splicing lists is item-8 territory, not a path write.)
+  `onValueChanges` (whole-value replacement) still exists but is no longer
+  the only write path.
+- **Touched tracking** — real state in `useFieldBinding`: a `Path<T>[]`
+  compared with `pathsEqual`, fed by `onBlur`, visible in the Debugger
+  snapshot. Commit-style elements (selects) call `onBlur` on commit — the
+  commit IS their blur moment.
+- **THE error-display policy** lives inside `errorMessage` and nowhere
+  else: show a field's error once the field is touched OR a submit has been
+  attempted. Elements render what they're given and stay policy-free. A UI
+  wanting a different policy (e.g. always-live) reads `errors`/`errorAt`
+  directly.
+
+### The element wrappers (`state/bindings/`)
+
+The **wrapper style** is the prototyped shorthand (per the plan's deciding
+criterion — simplest for agents to work with): `TextInputForForm` and
+`SingleSelectForForm` compose `Field` (label/hint/error presentation)
+around the element and accept the bundle as one `formFieldProps` prop.
+The wrapper declares what it can display and emit via
+`FieldBinding<Display, Emit>` — e.g. the text input takes
+`FieldBinding<string | null | undefined, string>` — and a
+`FormFieldProps<V>` is assignable exactly when `Emit ⊆ V ⊆ Display`. That
+one structural check is the end-to-end type safety: binding a number- or
+boolean-typed path (or a literal-union field, for free text) to a
+text-shaped element fails to compile at the `formFieldProps` prop, with no
+generics at the use site.
 
 ## Union policy — what form state may hold
 
@@ -309,10 +444,11 @@ precision end-to-end. So we wire it up before adding any consumers.
 
 - `state/useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`.
+  onValueChanges, errors, isValid, submitAttempted, submit,
+  getFormFieldPropsAt, Debugger }`.
   `useFormState.ts` itself is deliberately **plumbing only**: it holds the
-  values `useState` (a bare `useState` today; granular path-based setters
-  are what would earn values state a module of its own), links up the
+  values `useState` (a bare `useState`; the granular path writes layer on
+  top of its setter via `useFieldBinding`), links up the
   modules below, and recomposes their outputs into `FormHelpers<T>`. Each
   slice lives in its own file so it is independently comprehensible and
   unit-testable at its own boundary:
@@ -325,11 +461,19 @@ precision end-to-end. So we wire it up before adding any consumers.
     cheap); `isValid` is its emptiness, derived inline in the hook. Its
     loop delegates per-entry semantics to `state/validations/walk.ts` and
     carries two documented honest widenings: the `Object.keys` cast, and
-    `failure.path as Path<T>` — `[key]` is a valid single-key `Path<T>`,
-    but TS cannot compute `Path<T>` for an unresolved generic `T` to see
-    the correlation. It also hosts the cast-free `FlatConstraintEntry`
+    `failure.path as Path<T>` — the walk extends the `[key]` seed only
+    along keys of specs type-checked against `T`'s subtree, so every
+    returned path is a valid `Path<T>`, but TS cannot compute `Path<T>`
+    for an unresolved generic `T` to see the correlation. It also hosts
+    the cast-free `ConstraintEntry`
     assignment that polices grammar growth (see the `state/validations/` bullet).
   - `errorAt.ts` — the typed error lookup.
+  - `useFieldBinding.ts` — field binding: owns the touched list and builds
+    `getFormFieldPropsAt` (see "Field binding" above — the error-display
+    policy lives here). Two documented honest casts correlate `read()`/
+    `write()` results with `ValueAt<T, P>`/`T` for generic `T`; both are
+    truths the runtime upholds by construction, same family as `errorAt`'s
+    path widening.
   - `useFormSubmit.ts` — submit orchestration: owns `submitAttempted`
     (lets UIs gate error display) and the validity gate in front of
     `onSubmit`; its `submit()` performs the one honest *refinement* cast
@@ -346,27 +490,37 @@ precision end-to-end. So we wire it up before adding any consumers.
     bottom-right, portaled to `<body>`) that opens a live `JsonTable` view
     of the form's internal state. Only an *open* debugger window
     subscribes (`useSyncExternalStore`), so an unused Debugger costs
-    ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
-    can render.
-- `state/path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
-  Will be used for granular setters and for surfacing per-field
-  errors/touched state. Coupled to the form value model intentionally.
+    ~nothing. `inspectable.ts` converts Sets to string leaves `JsonTable`
+    can render (objects and arrays it renders natively).
+- `state/path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`,
+  `read()`), plus `write()` (the immutable-update mirror of `read()` behind
+  granular field writes) and `pathsEqual` (the one definition of structural
+  path equality — `errorAt` and touched tracking both use it). Coupled to
+  the form value model intentionally.
   Union handling is governed by the "Union policy" section above; the
   policy's type-level guts (`IsDisallowedFormUnion`, `UnionPolicyCheck`,
   `DisallowedFormUnion`) live with the value model in `state/useFormState/types.ts`.
-- `state/validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
-  `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the runtime walk the
-  hook delegates to (`validateEntry`). `Validations<T>` accepts bare
-  `(val) => string | null` functions too — they simply narrow nothing.
-  The walk's entry type (`FlatConstraintEntry`) is how the compiler polices
+- `state/validations/` — `perField`, the recursive grammar
+  (`Validations<T>` / `FieldConstraint<F>` / `ListConstraint<E>`),
+  `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the recursive runtime
+  walk the hook delegates to (`validateEntry` — returns every failure in the
+  entry's subtree, addresses accumulated as `PathStep[]`s). `Validations<T>`
+  accepts bare `(val) => string | null` functions too — they simply narrow
+  nothing. The walk disambiguates a structural spec against the VALUE at
+  the path (array ⇒ `{ each }`, which throws until phase 3; object ⇒
+  nested spec; absent ⇒ skip), never against the constraint's shape.
+  The walk's entry type (`ConstraintEntry`) is how the compiler polices
   the error loop in `state/useFormState/deriveErrors.ts`: `constraints[key]` is
   *assigned* to it, never cast,
-  so a grammar form the walk doesn't understand (a nested spec, an `each`)
+  so a grammar form the walk doesn't understand (a future `self` slot, say)
   is a compile error at the assignment — a cast there would silently accept
   new grammar and misinterpret it at runtime (e.g. call an array as a
   function). Keep it cast-free. The one widening cast inside `validateEntry`
   mirrors `allOf`'s part-call: honest contravariant widening of a single,
   already-normalized validator.
+- `state/bindings/` — the form-aware element wrappers (`TextInputForForm`,
+  `SingleSelectForForm`), the second sanctioned state→elements bridge (see
+  "Field binding" above). Element imports go through the element barrels.
 - `state/validators/` — the standard-library validators (`notEmpty`, `minLength`,
   `matches`, `min`) plus `allOf`, which composes validators on one field and
   carries the union of the parts' refinements. `allOf` derives its input type

package/src/forms/elements/Input/index.tsx

@@ -14,6 +14,7 @@ export const Input = (props: InputProps) => {
     value,
     defaultValue,
     onChange,
+    onBlur,
     placeholder,
     required,
     autoFocus,
@@ -29,6 +30,7 @@ export const Input = (props: InputProps) => {
       value={value}
       defaultValue={defaultValue}
       onChange={onChange}
+      onBlur={onBlur}
       placeholder={placeholder}
       required={required}
       autoFocus={autoFocus}

package/src/forms/elements/Input/types.ts

@@ -1,4 +1,4 @@
-import type { ChangeEventHandler } from 'react';
+import type { ChangeEventHandler, FocusEventHandler } from 'react';
 
 export type InputSize = 'small' | 'medium';
 export type InputType = 'text' | 'email' | 'password';
@@ -9,6 +9,7 @@ export type InputProps = {
   value?: string;
   defaultValue?: string;
   onChange?: ChangeEventHandler<HTMLInputElement>;
+  onBlur?: FocusEventHandler<HTMLInputElement>;
   placeholder?: string;
   required?: boolean;
   autoFocus?: boolean;