@structuralists/scaffolding 0.13.0 → 0.15.0

package/.storybook/preview.tsx

@@ -47,6 +47,9 @@ const preview: Preview = {
     options: {
       storySort: {
         order: [
+          // Demo: polished illustrations of what can be built — first thing
+          // a visitor sees.
+          'Demo',
           // Showcase: how the pieces fit together.
           'Composition',
           // Main library, alphabetical.

package/AGENTS.md

@@ -63,6 +63,17 @@ The Storybook toolbar has a Theme control (paintbrush icon) listing all six
 leaves the attribute unset (prefers-color-scheme fallback) and is the initial
 value, so the vitest story run is unaffected by the toggle.
 
+## The Demo section
+
+The first Storybook section (`'Demo'` in `storySort` in
+`.storybook/preview.tsx`) holds polished showcase compositions — full
+mini-apps built entirely from the library's public pieces, not component API
+docs. Demo stories live in `src/storybook/` (like `Composition.stories.tsx`)
+with titles of the form `Demo/<Name>`, keep their datasets deterministic (no
+`Date.now()`/randomness at render), and double as integration tests via
+`play` functions. Don't add new public components for a demo; compose from
+what exists.
+
 ## Testing
 
 ### Story tests (the main gate)

package/README.md

@@ -53,7 +53,7 @@ export const SignupCard = () => {
 };
 ```
 
-Browse every component (with live controls) in the Storybook: `bun run storybook`. The toolbar's Theme control (paintbrush icon) previews any of the themes above — "System (default)" leaves `data-theme` unset, following system preference.
+Browse every component (with live controls) in the Storybook: `bun run storybook`. The sidebar opens with a **Demo** section — full mini-apps (like a CRUD Team Directory) composed entirely from the library's public pieces, showing what an app scaffolded with it looks like. The toolbar's Theme control (paintbrush icon) previews any of the themes above — "System (default)" leaves `data-theme` unset, following system preference.
 
 ## Consumer notes
 

package/package.json

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

package/src/forms/CLAUDE.md

@@ -63,6 +63,14 @@ type FieldConstraint<F> =
   | (F extends FormValueList ? ListConstraint<F[number]> : never); // { each: … }
 ```
 
+Per field type, that comes out as:
+
+| Field type       | Legal constraint forms                                        |
+|------------------|---------------------------------------------------------------|
+| scalar leaf      | validator, validator array                                    |
+| object section   | validator / array (whole-section value), nested `Validations` |
+| list             | validator / array (whole-list value), `{ each: spec }`        |
+
 The array form is the everyday way to stack validators on a field at the
 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:
@@ -126,10 +134,22 @@ const constraints = perField({
 
 `perField` is the entry point that produces a `Validations<FormType>`-shaped
 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.
+admits the full recursive grammar — leaf validators and arrays, nested
+object specs, `each` specs, freely composed. Its own bound is deliberately
+*shape-only* (validators / validator arrays / objects of more of the same):
+perField never sees the form type, so it can only reject obvious garbage;
+the real check — every key a field, every validator input compatible,
+structural forms only where the field type permits — happens at the
+caller's `satisfies Validations<FormType>`. Consequence: wrong-key and
+wrong-shape errors on a perField-built spec anchor at the `satisfies`, not
+at the offending line inside the call.
+
+A pre-built spec is also a legal *nested-spec value*: a
+`perField({...}) satisfies Validations<Section>` object can sit under a
+section key (or an `each` key) of a larger constraints object — building a
+section's spec once and reusing it across sections is the intended
+composition pattern (pinned at ~110-leaf scale in
+`state/useFormState/useFormState.stress.test-d.ts`).
 
 ### The precision-preserving ceremony, by call-site shape
 
@@ -437,6 +457,38 @@ descent into a field.
   real values onto validators except as opaque type tags — anything else
   invites consumers to depend on the runtime shape.
 
+## Probe suites and the recursion budget
+
+The grammar's behavior is pinned by three type-probe tiers (enforced by
+`bun run typecheck`) plus the runtime composition fixture:
+
+- `state/validations/types.test-d.ts` — `Refine`/marker semantics at unit
+  scale: perField precision, union-member soundness, the widening failure
+  modes.
+- `state/useFormState/useFormState.test-d.ts` — the hook boundary at chunky
+  (~30-leaf `InsuranceQuoteForm`) scale: the full grammar inline, boundary
+  regimes (default `V`, literal `initialValues`, `as const satisfies`),
+  union policy, and the negative probes. Authoring gotcha: deep
+  wrong-validator-INPUT rejections (TS2322) anchor at the *outermost*
+  constraint key, so their `@ts-expect-error` sits on the parent/root key's
+  line; wrong-KEY rejections (TS2353) anchor at the leaf.
+- `state/useFormState/useFormState.stress.test-d.ts` — the stress tier
+  (~110-leaf `MegaQuoteForm` with the large spec inline twice, a 12-level
+  nested-spec ladder, a 4-deep `each` ladder, perField pre-built specs at
+  the same scale, deep `Path` bindings). If the recursion budget regresses,
+  tsc slows or fails here first.
+- `state/useFormState/useFormState.composition.test.tsx` — the same deep
+  mixed composition exercised at *runtime* through the real hook: deep error
+  paths, absent-section/null-list skips (and their materialization), deep
+  `getFormFieldPropsAt` writes, whole-value leaf validators on structural
+  fields, submit gating.
+
+Budget baselines live in plan.md's "recursion budget" section. When touching
+the type machinery, run `bunx tsc --noEmit --extendedDiagnostics` and
+compare instantiations against the latest recorded baseline — the failure
+signal is ~10× instantiations or multi-second check time, and regressions
+should be recorded there, not just noticed.
+
 ## Why we're building it this way from the start
 
 The whole carrier-type approach falls apart if it gets retrofitted onto

package/src/forms/plan.md

@@ -1,8 +1,12 @@
 # Plan: composable, recursive `Validations`
 
-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).
+Status: **complete** — all working-order items and phases below are done.
+The baseline (flat `Validations<T>`, one validator per key, shallow `Refine`)
+merged as PR #12 (released 0.5.0); the recursive grammar landed over phases
+1–4 (PRs #18, #24, #25, and the composition-hardening close-out). What
+remains in this file is the record: grammar doctrine, decided semantics,
+recorded budgets, and the deliberately-deferred items (per-field meta
+state / stable keys — section 8 — and the open decisions at the end).
 
 ## Order of operations
 
@@ -42,7 +46,7 @@ TS wall can't strand finished work behind it.
    wrapper-style element shorthands prototyped (`state/bindings/`:
    `TextInputForForm`, `SingleSelectForForm`). Probe ratchet held (see the
    baseline note under the recursion budget).
-6. **Type spike, then items 2/3/4** — the recursion risk zone. ← *current*
+6. **Type spike, then items 2/3/4** — the recursion risk zone. ✅ *done*
    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.
@@ -58,6 +62,7 @@ TS wall can't strand finished work behind it.
    - **Phase 2 (nested object specs + recursive `Refine`): ✅ done** — see
      "Phases" below.
    - **Phase 3 (list `each` runtime): ✅ done** — see "Phases" below.
+   - **Phase 4 (composition hardening): ✅ done** — see "Phases" below.
 
 ## Goal
 
@@ -254,6 +259,15 @@ multi-second check time:
   instantiations, 58,813 types (+1.8% over the pre-phase-3 HEAD at
   134,330/58,034 — mostly the story's new hook call site and deep
   `Path`/`ValueAt` bindings)
+- post-phase-4 / **final** (composition hardening: the stress tier ported
+  against the real hook — mega form with the spec inline twice, both depth
+  ladders, deep bindings — plus perField at the full grammar with its
+  probes, and the runtime composition fixture): check 0.92–0.99 s, 172,040
+  instantiations, 67,889 types (+25.8% instantiations over post-phase-3 —
+  almost entirely the deliberately-heavy stress fixtures, closely matching
+  the spike's measured stress-tier cost of ~28k; check time stays
+  sub-second, exactly as the spike's headroom predicted). This is the
+  standing baseline for future type-machinery work.
 
 ## Runtime consequences (can't be dodged)
 
@@ -343,9 +357,24 @@ tests, story updates where visible, probe ratchet.
    "object field literally named `each`" disambiguation probe, and the
    `each: <bare validator>` negative (rejected by TypeScript's weak-type
    check — an obscure checker rule worth a canary).
-4. **Composition hardening.** Deep mixed fixtures (list-in-object-in-list),
-   `perField` still the entry point for pre-built specs, docs
-   (forms/CLAUDE.md) updated to the new grammar.
+4. **Composition hardening.** ✅ *done* — the closing phase. Deep mixed
+   fixtures: the type spike's stress tier ported against the REAL hook
+   (`useFormState.stress.test-d.ts` — ~110-leaf `MegaQuoteForm` with the
+   large applicant spec inline twice, 12-level nested-spec ladder, 4-deep
+   `each` ladder, deep `Path` bindings), plus a runtime composition fixture
+   through `renderHook` (`useFormState.composition.test.tsx` — deep error
+   paths at two list depths, absent-section/null-list skip *and*
+   materialization, deep `getFormFieldPropsAt` writes, whole-list leaf
+   validators, submit gating end to end). `perField` extended from
+   leaf-forms-only to the full recursive grammar: its bound is a loose
+   recursive shape (validators / arrays / objects of the same — deliberately
+   form-type-agnostic, so the real shape check stays at the caller's
+   `satisfies Validations<T>`), pinned at unit scale in
+   `validations/types.test-d.ts` and at mega scale (one pre-built applicant
+   spec reused across two sections) in the stress file. forms/CLAUDE.md
+   brought fully up to the grammar (constraint-forms-per-field-type table,
+   perField's new reach, probe-suite map). No runtime machinery changed —
+   the deep fixtures flushed out no correctness fixes.
 
 ## 5. Split forms into 'form elements' and 'form state' ✅ done
 

package/src/forms/state/useFormState/useFormState.composition.test.tsx

@@ -0,0 +1,342 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
+import { perField } from '../validations/perField';
+import { matches, min, notEmpty } from '../validators/validators';
+import type { Validations } from '../validations/types';
+
+// The composition-hardening runtime fixture (plan phase 4): a deep mixed
+// form — lists inside objects inside lists, nested specs inside `each`
+// specs, whole-value leaf validators on structural fields, an absent
+// section and a null list — driven through the REAL useFormState at the
+// hook boundary. walk.test.ts pins each construct's semantics React-free;
+// this file pins that they hold composed, end to end, with the constraints
+// pre-built via perField (the phase-4 entry point for pre-built specs).
+
+type UsAddress = {
+  line1: string | undefined;
+  city: string | undefined;
+  postalCode: string | undefined;
+};
+
+type Incident = {
+  date: string | undefined;
+  claimAmountUsd: number | null;
+};
+
+type Driver = {
+  name: string | undefined;
+  incidents: Incident[];
+};
+
+type Vehicle = { vin: string | undefined };
+
+type Applicant = {
+  email: string | undefined;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress | undefined;
+  drivers: Driver[];
+  vehicles: Vehicle[];
+};
+
+type QuoteForm = {
+  primary: Applicant;
+  secondary: Applicant | undefined;
+  household: {
+    members: Array<{ name: string | undefined }>;
+  };
+  quotes: Array<{
+    coverageType: string | undefined;
+    riders: Array<{ code: string | undefined; amountUsd: number | null }>;
+  }>;
+  pastPolicies: Array<{ insurer: string | undefined }> | null;
+  // An object field literally named `each` — the value model, not the
+  // constraint's shape, directs interpretation.
+  audit: { each: string | undefined };
+  agreedToTerms: boolean | undefined;
+};
+
+// One applicant spec, built once via perField and reused for both applicant
+// sections — nested specs, each-in-each, arrays at depth, and a whole-list
+// leaf validator on a structural field (leaf and structural forms are
+// mutually exclusive per key: vehicles validates as a value, drivers per
+// element).
+const applicantSpec = perField({
+  email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+  homeAddress: {
+    city: notEmpty('city'),
+    postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+  },
+  mailingAddress: {
+    city: notEmpty('mailing city'),
+  },
+  drivers: {
+    each: {
+      name: notEmpty('name'),
+      incidents: {
+        each: {
+          date: notEmpty('date'),
+          claimAmountUsd: min('claimAmountUsd', 0),
+        },
+      },
+    },
+  },
+  vehicles: [(val: Vehicle[]) => (val.length > 0 ? null : 'at least one vehicle')],
+}) satisfies Validations<Applicant>;
+
+const constraints = {
+  primary: applicantSpec,
+  secondary: applicantSpec,
+  household: {
+    members: { each: { name: notEmpty('member name') } },
+  },
+  quotes: {
+    each: {
+      coverageType: notEmpty('coverageType'),
+      riders: {
+        each: { code: notEmpty('code'), amountUsd: min('amountUsd', 0) },
+      },
+    },
+  },
+  pastPolicies: {
+    each: { insurer: notEmpty('insurer') },
+  },
+  audit: { each: notEmpty('audit each') },
+  agreedToTerms: notEmpty('agreedToTerms'),
+} as const satisfies Validations<QuoteForm>;
+
+// Mostly-valid deep values with deliberate failures: an each-in-each leaf
+// and its sibling at depth 5, a member name, a rider code at list-in-
+// object-in-list depth, and the `audit.each` disambiguation field. The
+// secondary section is absent and pastPolicies is null — both fully
+// spec'd, both skipped.
+const makeValues = (): QuoteForm => ({
+  primary: {
+    email: 'ada@lovelace.dev',
+    homeAddress: { line1: '1 Main St', city: 'London', postalCode: '12345' },
+    mailingAddress: undefined,
+    drivers: [
+      { name: 'Ada', incidents: [] },
+      { name: 'Grace', incidents: [{ date: undefined, claimAmountUsd: -50 }] },
+    ],
+    vehicles: [{ vin: 'V1' }],
+  },
+  secondary: undefined,
+  household: { members: [{ name: undefined }, { name: 'Linus' }] },
+  quotes: [
+    {
+      coverageType: 'auto',
+      riders: [
+        { code: 'R1', amountUsd: 10 },
+        { code: undefined, amountUsd: null },
+      ],
+    },
+  ],
+  pastPolicies: null,
+  audit: { each: undefined },
+  agreedToTerms: true,
+});
+
+const setup = (onSubmit?: (values: QuoteForm) => void) =>
+  renderHook(() =>
+    useFormState({ initialValues: makeValues(), constraints, onSubmit }),
+  );
+
+describe('useFormState — deep mixed composition at the hook boundary', () => {
+  test('errors carry full structural paths across every grammar construct', () => {
+    const { result } = setup();
+    // The exact list: constraint-key order at each level, elements in list
+    // order, failing nodes only. Absent secondary and null pastPolicies
+    // contribute nothing despite full specs; the whole-list vehicles
+    // validator and every passing leaf contribute nothing.
+    expect(result.current.errors).toEqual([
+      {
+        path: ['primary', 'drivers', 1, 'incidents', 0, 'date'],
+        error: "'date' cannot be empty",
+      },
+      {
+        path: ['primary', 'drivers', 1, 'incidents', 0, 'claimAmountUsd'],
+        error: "'claimAmountUsd' must be at least 0",
+      },
+      {
+        path: ['household', 'members', 0, 'name'],
+        error: "'member name' cannot be empty",
+      },
+      {
+        path: ['quotes', 0, 'riders', 1, 'code'],
+        error: "'code' cannot be empty",
+      },
+      {
+        path: ['audit', 'each'],
+        error: "'audit each' cannot be empty",
+      },
+    ]);
+    expect(result.current.isValid).toBe(false);
+  });
+
+  test('errorAt resolves deep numeric paths and stays empty on skipped subtrees', () => {
+    const { result } = setup();
+    expect(
+      errorAt(result.current.errors, ['primary', 'drivers', 1, 'incidents', 0, 'date']),
+    ).toBe("'date' cannot be empty");
+    expect(errorAt(result.current.errors, ['quotes', 0, 'riders', 1, 'code'])).toBe(
+      "'code' cannot be empty",
+    );
+    // Sibling elements that passed have no entry at their own index.
+    expect(
+      errorAt(result.current.errors, ['quotes', 0, 'riders', 0, 'code']),
+    ).toBeUndefined();
+    // The absent section's constrained leaves have no entries.
+    expect(errorAt(result.current.errors, ['secondary', 'email'])).toBeUndefined();
+  });
+
+  test('a deep fix through getFormFieldPropsAt clears exactly that entry', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'date'])
+        .onChange('2026-01-01');
+    });
+
+    expect(
+      errorAt(result.current.errors, ['primary', 'drivers', 1, 'incidents', 0, 'date']),
+    ).toBeUndefined();
+    // The failing sibling leaf in the same element is untouched …
+    expect(
+      errorAt(result.current.errors, [
+        'primary',
+        'drivers',
+        1,
+        'incidents',
+        0,
+        'claimAmountUsd',
+      ]),
+    ).toBe("'claimAmountUsd' must be at least 0");
+    // … and the write only cloned the spine: the other driver keeps identity.
+    expect(result.current.values.primary.drivers[0]).toEqual({
+      name: 'Ada',
+      incidents: [],
+    });
+  });
+
+  test('a whole-list leaf validator on a structural field runs against the list value', () => {
+    const { result } = setup();
+    expect(errorAt(result.current.errors, ['primary', 'vehicles'])).toBeUndefined();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['primary', 'vehicles']).onChange([]);
+    });
+
+    expect(errorAt(result.current.errors, ['primary', 'vehicles'])).toBe(
+      'at least one vehicle',
+    );
+  });
+
+  test('materializing an absent section brings its whole spec to life', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({
+        ...prev,
+        secondary: {
+          email: undefined,
+          homeAddress: { line1: undefined, city: undefined, postalCode: undefined },
+          mailingAddress: undefined,
+          drivers: [{ name: undefined, incidents: [] }],
+          vehicles: [],
+        },
+      }));
+    });
+
+    expect(errorAt(result.current.errors, ['secondary', 'email'])).toBe(
+      "'email' cannot be empty",
+    );
+    expect(errorAt(result.current.errors, ['secondary', 'homeAddress', 'city'])).toBe(
+      "'city' cannot be empty",
+    );
+    expect(
+      errorAt(result.current.errors, ['secondary', 'drivers', 0, 'name']),
+    ).toBe("'name' cannot be empty");
+    expect(errorAt(result.current.errors, ['secondary', 'vehicles'])).toBe(
+      'at least one vehicle',
+    );
+    // The still-absent nested section inside the materialized one stays
+    // skipped.
+    expect(
+      errorAt(result.current.errors, ['secondary', 'mailingAddress', 'city']),
+    ).toBeUndefined();
+  });
+
+  test('a null list wakes up the same way', () => {
+    const { result } = setup();
+    expect(errorAt(result.current.errors, ['pastPolicies', 0, 'insurer'])).toBeUndefined();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({
+        ...prev,
+        pastPolicies: [{ insurer: 'Acme' }, { insurer: undefined }],
+      }));
+    });
+
+    expect(errorAt(result.current.errors, ['pastPolicies', 0, 'insurer'])).toBeUndefined();
+    expect(errorAt(result.current.errors, ['pastPolicies', 1, 'insurer'])).toBe(
+      "'insurer' cannot be empty",
+    );
+  });
+
+  test('submit is gated on the deep composition and passes the current values through', () => {
+    let submitted: QuoteForm | undefined;
+    const onSubmit = mock((values: QuoteForm) => {
+      submitted = values;
+    });
+    const { result } = setup(onSubmit);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(result.current.submitAttempted).toBe(true);
+
+    // Fix every failing node, one grammar construct at a time.
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'date'])
+        .onChange('2026-01-01');
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'claimAmountUsd'])
+        .onChange(500);
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['household', 'members', 0, 'name'])
+        .onChange('Margaret');
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['quotes', 0, 'riders', 1, 'code'])
+        .onChange('R2');
+    });
+    act(() => {
+      result.current.getFormFieldPropsAt(['audit', 'each']).onChange('reviewed');
+    });
+
+    expect(result.current.errors).toEqual([]);
+    expect(result.current.isValid).toBe(true);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(submitted?.primary.drivers[1].incidents[0]).toEqual({
+      date: '2026-01-01',
+      claimAmountUsd: 500,
+    });
+    expect(submitted?.quotes[0].riders[1].code).toBe('R2');
+    expect(submitted?.secondary).toBeUndefined();
+    expect(submitted?.pastPolicies).toBeNull();
+  });
+});