npm - @structuralists/scaffolding - Versions diffs - 0.12.0 → 0.13.0 - Mend

@structuralists/scaffolding 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/.storybook/preview.tsx +42 -0
package/AGENTS.md +9 -0
package/README.md +1 -1
package/package.json +1 -1
package/src/forms/CLAUDE.md +15 -9
package/src/forms/plan.md +20 -9
package/src/forms/state/useFormState/deriveErrors.test.ts +39 -4
package/src/forms/state/useFormState/errorAt.test.ts +2 -2
package/src/forms/state/useFormState/useFieldBinding.test.tsx +34 -0
package/src/forms/state/useFormState/useFormState.stories.tsx +182 -0
package/src/forms/state/validations/types.ts +7 -5
package/src/forms/state/validations/walk.test.ts +125 -12
package/src/forms/state/validations/walk.ts +26 -15

package/.storybook/preview.tsx CHANGED Viewed

@@ -1,4 +1,5 @@
 import type { Preview } from '@storybook/react-vite';
+import { useEffect } from 'storybook/preview-api';
 import { MemoryRouter } from 'react-router';
 import * as prettier from 'prettier/standalone';
 import * as babel from 'prettier/plugins/babel';
@@ -11,6 +12,28 @@ import '../tokens.css';
 const formatCache = new Map<string, string>();
 const preview: Preview = {
+  globalTypes: {
+    theme: {
+      description: 'Design-token theme (sets data-theme on <html>)',
+      toolbar: {
+        title: 'Theme',
+        icon: 'paintbrush',
+        items: [
+          { value: 'system', title: 'System (default)' },
+          { value: 'light-warm', title: 'Light / Warm' },
+          { value: 'light-paper', title: 'Light / Paper' },
+          { value: 'light-sepia', title: 'Light / Sepia' },
+          { value: 'dark-warm', title: 'Dark / Warm' },
+          { value: 'dark-neutral', title: 'Dark / Neutral' },
+          { value: 'dark-dimmed', title: 'Dark / Dimmed' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  initialGlobals: {
+    theme: 'system',
+  },
   parameters: {
     layout: 'padded',
@@ -71,6 +94,25 @@ const preview: Preview = {
     }
   },
   decorators: [
+    // Theme toggle: mirrors the toolbar selection onto <html data-theme="…">,
+    // matching how consuming apps select a theme (see tokens.css). 'system'
+    // leaves the attribute unset so the prefers-color-scheme fallback applies —
+    // that is also the initial global, so the vitest story run renders
+    // identically to before the toggle existed.
+    (Story, context) => {
+      const theme = context.globals.theme as string | undefined;
+      useEffect(() => {
+        const root = document.documentElement;
+        if (!theme || theme === 'system') {
+          root.removeAttribute('data-theme');
+        } else {
+          root.setAttribute('data-theme', theme);
+        }
+      }, [theme]);
+      return <Story />;
+    },
     (Story) => (
       <MemoryRouter>
         <Story />

package/AGENTS.md CHANGED Viewed

@@ -54,6 +54,15 @@ Built-in React hooks (`useState`, `useEffect`, etc.) keep their stock
 positional signatures — this rule applies only to hooks defined in this
 package.
+## Storybook theme toggle
+The Storybook toolbar has a Theme control (paintbrush icon) listing all six
+`tokens.css` themes plus "System (default)". It is wired in
+`.storybook/preview.tsx` via `globalTypes` + a global decorator that sets
+`data-theme` on `<html>` — the same mechanism consuming apps use. "System"
+leaves the attribute unset (prefers-color-scheme fallback) and is the initial
+value, so the vitest story run is unaffected by the toggle.
 ## Testing
 ### Story tests (the main gate)

package/README.md CHANGED Viewed

@@ -53,7 +53,7 @@ export const SignupCard = () => {
 };
 ```
-Browse every component (with live controls) in the Storybook: `bun run storybook`.
+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.
 ## Consumer notes

package/package.json CHANGED Viewed

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

package/src/forms/CLAUDE.md CHANGED Viewed

@@ -104,13 +104,17 @@ Grammar doctrine, in force at the type level and in the runtime walk:
 - **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.
+  walk skips — nothing to walk). Same for `each` over a null list; a
+  "required list" is a leaf validator on the list field.
 - **`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.
+- **An `each` spec validates every element.** Failures are addressed with
+  the numeric index step (`['drivers', 3, 'name']`) — the same step
+  semantics as `read()`/`Path`, so `errorAt` and the bindings look element
+  errors up like any other path. Elements fail independently
+  (first-error-wins applies within one field's validator array, not across
+  elements); an empty list passes.
 ## Aggregation: `perField`
@@ -260,9 +264,10 @@ type FormErrors<T> = readonly FormError<T>[];          // isValid === (errors.le
 ```
 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.
+a nested-spec leaf `['homeAddress', 'postalCode']`, a leaf inside a list
+element carries the numeric index step (`['drivers', 3, 'name']`). Sibling
+nodes fail independently — first-error-wins applies *within* one validator
+array, not across fields or list elements.
 Read one field's message with the typed accessor, never by hand-assembled
 keys — serialized path strings (`'drivers.0.name'`) are deliberately not
@@ -507,8 +512,9 @@ precision end-to-end. So we wire it up before adding any consumers.
   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 path (array ⇒ `{ each }`, run against every element with the index
+  as the path step; 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,

package/src/forms/plan.md CHANGED Viewed

@@ -57,6 +57,7 @@ TS wall can't strand finished work behind it.
      identity gate for the default-`V` case.
    - **Phase 2 (nested object specs + recursive `Refine`): ✅ done** — see
      "Phases" below.
+   - **Phase 3 (list `each` runtime): ✅ done** — see "Phases" below.
 ## Goal
@@ -248,6 +249,11 @@ multi-second check time:
   0.87 s, 133,956 instantiations, 57,762 types (+7.1% instantiations over
   post-item-6; matches the spike's equivalent non-stress milestone at
   134,441 almost exactly)
+- post-phase-3 (`each` runtime + the `ListValidation` story with its
+  numeric-path bindings; no new type machinery): check 0.84 s, 136,741
+  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)
 ## Runtime consequences (can't be dodged)
@@ -320,15 +326,20 @@ tests, story updates where visible, probe ratchet.
    predicted — nested errors just carry longer paths). **The `each` TYPE
    arm landed here too** (the spike proved the grammar whole, and carving
    it out of `RefineField` would have been artificial), but the runtime
-   walk for it is phase 3 — until then an `each` constraint on a present
-   list THROWS from the walk (pinned in walk.test.ts) rather than silently
-   not validating; on a null list it skips, which already matches phase-3
-   semantics.
-3. **List `each` specs — runtime.** The walk visits every element; error
-   paths carry the numeric step (`['drivers', 3, 'name']`), replacing the
-   phase-2 throw. (The type level — refined element flowing through
-   `Array<...>` — already landed with phase 2.) Two probes the spike says
-   to keep pinned are already in the phase-2 suite: the `audit`-style
+   walk for it was phase 3 — in the interim an `each` constraint on a
+   present list THREW from the walk (pinned in walk.test.ts) rather than
+   silently not validating; on a null list it skipped, which already
+   matched phase-3 semantics.
+3. **List `each` specs — runtime.** ✅ *done* — the walk visits every
+   element; error paths carry the numeric step (`['drivers', 3, 'name']`),
+   replacing the phase-2 throw. (The type level — refined element flowing
+   through `Array<...>` — already landed with phase 2.) Absent/null list ⇒
+   skip, same decided semantics as absent sections; elements fail
+   independently; walk-level semantics pinned React-free in walk.test.ts,
+   the typed boundary in deriveErrors.test.ts, element errors through
+   `errorMessage` at numeric paths in useFieldBinding.test.tsx, and the
+   visible flow in the `ListValidation` story. Two probes the spike said
+   to keep pinned were already in the phase-2 suite: the `audit`-style
    "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).

package/src/forms/state/useFormState/deriveErrors.test.ts CHANGED Viewed

@@ -75,10 +75,12 @@ describe('deriveFormErrors', () => {
   });
 });
-// The recursive grammar: nested object specs walk the value tree and
-// address failures with real multi-step paths. (List `each` specs are
-// type-level only until plan phase 3 — the walk throws on one; pinned in
-// walk.test.ts.)
+// The recursive grammar: nested object specs and list `each` specs walk the
+// value tree and address failures with real multi-step paths — numeric steps
+// for list elements. Walk-level semantics (element iteration, sibling
+// independence, absent-value skips) are pinned in walk.test.ts; these tests
+// pin the typed boundary: a constraints literal checked against the form
+// type produces `Path<T>`-addressed entries.
 type ProfileForm = {
   email: string | undefined;
@@ -87,12 +89,16 @@ type ProfileForm = {
     postalCode: string | undefined;
   };
   mailingAddress: { city: string | undefined } | undefined;
+  pets: Array<{ name: string | undefined }>;
+  pastPolicies: Array<{ insurer: string | undefined }> | null;
 };
 const emptyProfile: ProfileForm = {
   email: undefined,
   homeAddress: { city: undefined, postalCode: undefined },
   mailingAddress: undefined,
+  pets: [],
+  pastPolicies: null,
 };
 describe('deriveFormErrors — nested object specs', () => {
@@ -168,3 +174,32 @@ describe('deriveFormErrors — nested object specs', () => {
     ]);
   });
 });
+describe('deriveFormErrors — list `each` specs', () => {
+  test('each element failure is addressed with the numeric index step', () => {
+    const profile: ProfileForm = {
+      ...emptyProfile,
+      pets: [{ name: 'Rex' }, { name: undefined }],
+    };
+    const errors = deriveFormErrors(profile, {
+      pets: { each: { name: notEmpty('name') } },
+    });
+    expect(errors).toEqual([
+      { path: ['pets', 1, 'name'], error: "'name' cannot be empty" },
+    ]);
+  });
+  test('an `each` spec on a null list is skipped; a leaf validator is how a list is required', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      pastPolicies: { each: { insurer: notEmpty('insurer') } },
+    });
+    expect(errors).toEqual([]);
+    const required = deriveFormErrors(emptyProfile, {
+      pastPolicies: notEmpty('pastPolicies'),
+    });
+    expect(required).toEqual([
+      { path: ['pastPolicies'], error: "'pastPolicies' cannot be empty" },
+    ]);
+  });
+});

package/src/forms/state/useFormState/errorAt.test.ts CHANGED Viewed

@@ -3,8 +3,8 @@ import { errorAt } from './errorAt';
 import type { FormErrors } from './types';
 // errorAt's equality must be exact over multi-step and numeric-step paths —
-// the recursive grammar produces real multi-step addresses (nested specs
-// today; numeric steps arrive with runtime `each` in plan phase 3).
+// the recursive grammar produces real multi-step addresses (nested specs,
+// and numeric index steps from runtime `each` over list elements).
 type Form = {
   email: string | undefined;
   address: { city: string | undefined };

package/src/forms/state/useFormState/useFieldBinding.test.tsx CHANGED Viewed

@@ -138,6 +138,40 @@ describe('getFormFieldPropsAt — error-display policy', () => {
     ).toBeUndefined();
   });
+  test('element errors from an `each` spec surface at numeric paths, per element', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { pets: { each: { name: notEmpty('name') } } },
+      }),
+    );
+    act(() => {
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).onChange(undefined);
+    });
+    // The raw list addresses the failing element by its index step …
+    expect(result.current.errors).toEqual([
+      { path: ['pets', 1, 'name'], error: "'name' cannot be empty" },
+    ]);
+    // … and errorMessage applies the same display policy at that path.
+    expect(
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).errorMessage,
+    ).toBeUndefined();
+    act(() => {
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).onBlur();
+    });
+    expect(
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).errorMessage,
+    ).toBe("'name' cannot be empty");
+    // The sibling element passed — no error at its own numeric path.
+    expect(
+      result.current.getFormFieldPropsAt(['pets', 0, 'name']).errorMessage,
+    ).toBeUndefined();
+  });
   test('repeat blurs on the same path keep the touched list stable', () => {
     // At the useFieldBinding boundary, where the touched list is returned.
     const { result } = renderHook(() =>

package/src/forms/state/useFormState/useFormState.stories.tsx CHANGED Viewed

@@ -441,6 +441,188 @@ export const FieldBinding: Story = {
   },
 };
+type FleetFormValues = {
+  fleetName: string | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    licenseNumber: string | undefined;
+  }>;
+};
+// What onSubmit receives: the `each` spec refines the ELEMENT type and the
+// refinement flows through Array<...> — every driver's constrained fields
+// lose undefined. The setSubmitted(vals) call compiling is the proof.
+type SubmittedFleet = {
+  fleetName: string;
+  drivers: Array<{ name: string; licenseNumber: string }>;
+};
+// Phase 3 of the recursive grammar: a `{ each: … }` spec validates EVERY
+// list element, and failures are addressed with the numeric index step —
+// ['drivers', 1, 'name'] — the same step semantics the bindings read. Each
+// driver's fields are bound at their numeric paths, so element errors land
+// on exactly the element that failed.
+const ListValidationDemo = () => {
+  const [submitted, setSubmitted] = useState<SubmittedFleet | null>(null);
+  const { values, errors, getFormFieldPropsAt, submit } = useFormState({
+    initialValues: {
+      fleetName: undefined,
+      drivers: [
+        { name: undefined, licenseNumber: undefined },
+        { name: undefined, licenseNumber: undefined },
+      ],
+    } as FleetFormValues,
+    constraints: {
+      fleetName: notEmpty('fleetName'),
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          licenseNumber: [
+            notEmpty('licenseNumber'),
+            minLength('licenseNumber', 5),
+          ],
+        },
+      },
+    },
+    onSubmit: (vals) => setSubmitted(vals),
+  });
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <TextInputForForm
+        label="Fleet name"
+        formFieldProps={getFormFieldPropsAt(['fleetName'])}
+      />
+      {values.drivers.map((_, index) => (
+        // Index keys are fine here: the list is fixed-size. Stable element
+        // keys for editable lists are plan item 8.
+        <fieldset
+          key={index}
+          style={{ display: 'grid', gap: 12, border: '1px solid var(--ui-border, #ddd)', borderRadius: 6, padding: 12 }}
+        >
+          <legend style={{ fontSize: 13, padding: '0 4px' }}>
+            Driver {index + 1}
+          </legend>
+          <TextInputForForm
+            label={`Driver ${index + 1} name`}
+            formFieldProps={getFormFieldPropsAt(['drivers', index, 'name'])}
+          />
+          <TextInputForForm
+            label={`Driver ${index + 1} license`}
+            hint="At least 5 characters"
+            formFieldProps={getFormFieldPropsAt([
+              'drivers',
+              index,
+              'licenseNumber',
+            ])}
+          />
+        </fieldset>
+      ))}
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+        <Button type="submit" variant="primary">
+          Save fleet
+        </Button>
+        {/* errorAt reads one element's raw error at its numeric path — no
+            display gating, the live truth the bindings' errorMessage sits
+            on top of. */}
+        <span style={{ fontSize: 13 }} data-testid="raw-driver-2-name-error">
+          {"raw ['drivers', 1, 'name']: "}
+          {errorAt(errors, ['drivers', 1, 'name']) ?? '—'}
+        </span>
+      </div>
+      {submitted && (
+        <pre
+          style={{
+            background: 'var(--ui-surface-muted, #f4f4f4)',
+            padding: 12,
+            borderRadius: 6,
+            fontSize: 12,
+            margin: 0,
+          }}
+        >
+          {`onSubmit received (narrowed type):\n${JSON.stringify(submitted, null, 2)}`}
+        </pre>
+      )}
+    </form>
+  );
+};
+export const ListValidation: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <ListValidationDemo />
+    </div>
+  ),
+  // Walks the per-element flow: errorAt at a numeric path is live from the
+  // start, element errors surface per element (not per list), fixing one
+  // element leaves its siblings' errors alone, and the refined element type
+  // flows through Array<...> to onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // errorAt is raw truth — the numeric-path lookup sees driver 2's error
+    // before anything is touched or submitted. (Exact-text queries below
+    // don't match this line — its text includes the path prefix.)
+    await expect(
+      canvas.getByTestId('raw-driver-2-name-error'),
+    ).toHaveTextContent("'name' cannot be empty");
+    // The bindings withhold everything until touched/submit-attempted.
+    await expect(
+      canvas.queryAllByText("'name' cannot be empty"),
+    ).toHaveLength(0);
+    // Fix driver 1's name, then submit: every remaining element error
+    // appears at its own element — driver 1 name stays clean.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 name/), 'Ayrton');
+    await userEvent.click(canvas.getByRole('button', { name: 'Save fleet' }));
+    await expect(
+      canvas.getAllByText("'name' cannot be empty"),
+    ).toHaveLength(1); // driver 2's field only — driver 1's name passed
+    await expect(
+      canvas.getAllByText("'licenseNumber' cannot be empty"),
+    ).toHaveLength(2); // both drivers' licenses
+    await expect(
+      canvas.getByText("'fleetName' cannot be empty"),
+    ).toBeInTheDocument();
+    // Validator arrays keep first-error-wins semantics INSIDE an element:
+    // a short license moves that element (and only it) to the minLength
+    // message.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 license/), 'abc');
+    await expect(
+      canvas.getByText("'licenseNumber' must be at least 5 characters"),
+    ).toBeInTheDocument();
+    await expect(
+      canvas.getAllByText("'licenseNumber' cannot be empty"),
+    ).toHaveLength(1); // driver 2 still on notEmpty
+    // Fix everything; the narrowed payload reaches onSubmit.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 license/), 'de');
+    await userEvent.type(canvas.getByLabelText(/^Driver 2 name/), 'Michele');
+    await userEvent.type(
+      canvas.getByLabelText(/^Driver 2 license/),
+      'XK-4471',
+    );
+    await userEvent.type(canvas.getByLabelText(/^Fleet name/), 'Scuderia');
+    // Driver 2's name is fixed — the raw errorAt lookup clears live.
+    await expect(
+      canvas.getByTestId('raw-driver-2-name-error'),
+    ).toHaveTextContent('—');
+    await userEvent.click(canvas.getByRole('button', { name: 'Save fleet' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
+};
 type DebuggerDemoValues = {
   email: string | undefined;
   nickname: string | undefined;

package/src/forms/state/validations/types.ts CHANGED Viewed

@@ -43,11 +43,13 @@ export type FieldConstraint<F> =
   | (F extends FormValuesObject ? Validations<F> : never)
   | (F extends FormValueList ? ListConstraint<F[number]> : never);
-// The constraint form for a list field: a spec applied to each element.
-// NOTE: the type-level grammar admits `each` (proven with the rest of the
-// recursive grammar by the phase-2 type spike), but the runtime walk for it
-// is plan phase 3 — until it lands, an `each` constraint throws a clear
-// error from the walk instead of silently not validating.
+// The constraint form for a list field: a spec applied to each element. At
+// runtime the walk validates EVERY element of a present list against the
+// `each` spec, and each failure carries the numeric index step
+// (`['drivers', 3, 'name']`) — the same step semantics as `read()`/`Path`,
+// so `errorAt` and the bindings look element errors up like any other path.
+// An absent (null/undefined) list has no elements to walk and skips — a
+// "required list" is a leaf validator on the list field instead.
 export type ListConstraint<Element extends FormValuesObject> = {
   readonly each: Validations<Element>;
   // room to grow, e.g. a `self` slot for list-level rules (min count,

package/src/forms/state/validations/walk.test.ts CHANGED Viewed

@@ -196,20 +196,133 @@ describe('validateEntry — value-model disambiguation', () => {
   });
 });
-describe('validateEntry — list `each` specs (runtime pending, phase 3)', () => {
-  test('an `each` spec on a present list throws instead of silently not validating', () => {
-    expect(() =>
-      validateEntry(
-        { each: { name: fail('name required') } },
-        [{ name: undefined }],
-        ['drivers'],
-      ),
-    ).toThrow(/each.*not validated at runtime yet.*drivers/);
-  });
-  test('an `each` spec on a null list is skipped — nothing to walk, matching phase-3 semantics', () => {
+describe('validateEntry — list `each` specs', () => {
+  test('the element spec runs against every element, failures addressed by numeric step', () => {
+    const result = validateEntry(
+      { each: { name: fail('name required') } },
+      [{ name: undefined }, { name: undefined }],
+      ['drivers'],
+    );
+    expect(result).toEqual([
+      { path: ['drivers', 0, 'name'], error: 'name required' },
+      { path: ['drivers', 1, 'name'], error: 'name required' },
+    ]);
+  });
+  test('only failing elements contribute — the numeric step is the element index, not a count', () => {
+    const named = { name: 'ok' };
+    const result = validateEntry(
+      {
+        each: {
+          name: (val: unknown) => (val == null ? 'name required' : null),
+        },
+      },
+      [named, named, named, { name: undefined }],
+      ['drivers'],
+    );
+    expect(result).toEqual([
+      { path: ['drivers', 3, 'name'], error: 'name required' },
+    ]);
+  });
+  test('elements fail independently: a failing element does not stop the others', () => {
+    const spy = mock(() => null);
+    validateEntry(
+      { each: { name: fail('boom'), age: spy } },
+      [{ name: 'a', age: 1 }, { name: 'b', age: 2 }],
+      ['drivers'],
+    );
+    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveBeenCalledWith(1);
+    expect(spy).toHaveBeenCalledWith(2);
+  });
+  test('element validators receive the element field value, not the list', () => {
+    const spy = mock((val: string) => (val === 'Rex' ? null : 'not Rex'));
+    expect(
+      validateEntry({ each: { name: spy } }, [{ name: 'Rex' }], ['pets']),
+    ).toEqual([]);
+    expect(spy).toHaveBeenCalledWith('Rex');
+  });
+  test('an empty list yields no errors', () => {
+    expect(
+      validateEntry({ each: { name: fail('x') } }, [], ['drivers']),
+    ).toEqual([]);
+  });
+  test('an `each` spec on a null list is skipped — nothing to walk', () => {
+    // Same decided semantics as absent sections: the type level refines only
+    // the present branch of a nullable list, so the runtime mirror is to
+    // skip. A "required list" is a leaf validator on the list field.
     expect(
       validateEntry({ each: { insurer: fail('x') } }, null, ['pastPolicies']),
     ).toEqual([]);
   });
+  test('an `each` spec on an undefined list is skipped', () => {
+    const never = mock(() => 'never reached');
+    expect(
+      validateEntry({ each: { insurer: never } }, undefined, ['pastPolicies']),
+    ).toEqual([]);
+    expect(never).not.toHaveBeenCalled();
+  });
+  test('each-in-each: failures at list-in-list depth carry both numeric steps', () => {
+    const result = validateEntry(
+      { each: { incidents: { each: { date: fail('bad date') } } } },
+      [
+        { incidents: [] },
+        { incidents: [{ date: undefined }, { date: undefined }] },
+      ],
+      ['drivers'],
+    );
+    expect(result).toEqual([
+      { path: ['drivers', 1, 'incidents', 0, 'date'], error: 'bad date' },
+      { path: ['drivers', 1, 'incidents', 1, 'date'], error: 'bad date' },
+    ]);
+  });
+  test('a nested object spec inside an each spec extends the address past the index', () => {
+    const result = validateEntry(
+      { each: { garagingAddress: { city: fail('city required') } } },
+      [{ garagingAddress: { city: undefined } }],
+      ['vehicles'],
+    );
+    expect(result).toEqual([
+      {
+        path: ['vehicles', 0, 'garagingAddress', 'city'],
+        error: 'city required',
+      },
+    ]);
+  });
+  test('leaf semantics hold inside elements: validator arrays are first-error-wins per field', () => {
+    const result = validateEntry(
+      { each: { name: [pass, fail('second'), fail('third')] } },
+      [{ name: 'x' }],
+      ['drivers'],
+    );
+    expect(result).toEqual([
+      { path: ['drivers', 0, 'name'], error: 'second' },
+    ]);
+  });
+  test('a whole-list leaf validator on the list field still runs against the list value', () => {
+    // Leaf forms stay legal on structural fields — a validator (array) on a
+    // list field validates the list as a value, no `each` involved.
+    const spy = mock((val: unknown[]) =>
+      val.length > 0 ? null : 'at least one driver',
+    );
+    expect(validateEntry([spy], [], ['drivers'])).toEqual([
+      { path: ['drivers'], error: 'at least one driver' },
+    ]);
+    expect(spy).toHaveBeenCalledWith([]);
+  });
+  test('a spec without `each` on a list value (untyped JS) is skipped, mirroring the null-child skip', () => {
+    expect(
+      validateEntry({ name: fail('x') }, [{ name: undefined }], ['drivers']),
+    ).toEqual([]);
+  });
 });

package/src/forms/state/validations/walk.ts CHANGED Viewed

@@ -2,10 +2,10 @@ import type { PathStep } from '../path/types';
 // The runtime walk over a constraints object, kept separate from the hook so
 // its semantics are unit-testable without React. The grammar is recursive
-// (nested object specs; list `each` specs arrive at runtime in plan phase 3),
-// so the walk is a tree walk: it accumulates a `PathStep[]` address as it
-// descends, and the hook's structured `{path, error}[]` error model
-// (`FormErrors<T>`) consumes those addresses directly.
+// (nested object specs, list `each` specs), so the walk is a tree walk: it
+// accumulates a `PathStep[]` address as it descends, and the hook's
+// structured `{path, error}[]` error model (`FormErrors<T>`) consumes those
+// addresses directly.
 export type ValidationError = {
   readonly path: readonly PathStep[];
@@ -47,18 +47,22 @@ type ConstraintSpec = {
 // An empty array passes, mirroring its refinement (`Exclude<F, never>`).
 //
 // Structural semantics — interpretation is directed by the value model:
-// - value is an array  ⇒ the spec is a `{ each: … }` list constraint.
-//   Runtime `each` walking is plan phase 3; until it lands the walk THROWS
-//   rather than silently not validating.
+// - value is an array  ⇒ the spec is a `{ each: … }` list constraint: the
+//   element spec runs against EVERY element, and each element's failures gain
+//   the numeric index step (`['drivers', 3, 'name']`) — the same step
+//   semantics as `read()`/`Path`, so `errorAt` and the bindings look them up
+//   like any other path. Elements fail independently; an empty list has
+//   nothing to walk and passes.
 // - value is an object ⇒ the spec is a nested `Validations`: recurse into
 //   each constrained key, extending the path. (An object field owning a key
 //   literally named `each` lands here — the value directs, so its spec is a
 //   nested spec like any other.)
 // - value is absent (null/undefined) ⇒ SKIP: a nested spec on an absent
-//   section validates nothing (decided with the type spike — the type level
-//   refines only the present branch of a nullable section, and this is the
-//   honest runtime mirror). A "required section" is a LEAF validator on the
-//   section field instead. A non-object value (unreachable through the typed
+//   section validates nothing, and an `each` spec on an absent list has no
+//   elements to walk (decided with the type spike — the type level refines
+//   only the present branch of a nullable section/list, and this is the
+//   honest runtime mirror). A "required section" or "required list" is a
+//   LEAF validator on the field instead. A non-object value (unreachable through the typed
 //   grammar) has nothing to walk either, mirroring read()'s dead-step
 //   semantics.
 // Predicate (not inline checks) because `Array.isArray`'s `arg is any[]`
@@ -92,10 +96,17 @@ export const validateEntry = (
   if (value == null || typeof value !== 'object') return [];
   if (Array.isArray(value)) {
-    throw new Error(
-      `list 'each' constraints are not validated at runtime yet (forms plan ` +
-        `phase 3) — constraint at path [${path.join(', ')}]`,
-    );
+    // Unreachable through the typed grammar (a list field's only structural
+    // form is `{ each: … }`), so a missing `each` can only come from untyped
+    // JS — nothing to run, mirroring the null-child skip below.
+    const each = entry.each;
+    if (each == null) return [];
+    const errors: ValidationError[] = [];
+    (value as unknown[]).forEach((element, index) => {
+      errors.push(...validateEntry(each, element, [...path, index]));
+    });
+    return errors;
   }
   const errors: ValidationError[] = [];