@structuralists/scaffolding 0.11.0 → 0.12.0

package/src/forms/state/useFormState/useFormState.test-d.ts

@@ -310,6 +310,12 @@ type InsuranceQuoteForm = {
   referralSource: string | null;
   notes: string | undefined;
   agreedToTerms: boolean | undefined;
+  // Disambiguation probe: an object field owning a key literally named
+  // `each` must still be treated as a nested object spec (directed by T).
+  audit: {
+    each: string | undefined;
+    reviewedBy: string | undefined;
+  };
   paperlessBilling: boolean;
 };
 
@@ -547,3 +553,433 @@ describe('useFormState narrowing at realistic scale', () => {
     >().toEqualTypeOf<string | null | undefined>();
   });
 });
+
+// ---------------------------------------------------------------------------
+// The recursive grammar (plan phase 2, grammar proven whole by the phase-2
+// type spike): nested object specs, list `each` specs, validator arrays at
+// every level, and the recursive `Refine` — exercised inline at the hook
+// boundary on the chunky form. Ported from the spike's probe suite; the
+// spike's two binding adjustments (value-model-first branch order in
+// `RefineField`, the `Refine` identity gate) are what these probes pin.
+// ---------------------------------------------------------------------------
+
+describe('useFormState — full recursive grammar at InsuranceQuoteForm scale, inline', () => {
+  it('composes leaf/array/nested/each constraints and refines at every depth', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        // -- root leaves, same mix as the flat probe above
+        firstName: notEmpty('firstName'),
+        lastName: [notEmpty('lastName')],
+        email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+        phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+        dateOfBirth: allOf(
+          notEmpty('dateOfBirth'),
+          matches('dateOfBirth', /^\d{4}-\d{2}-\d{2}$/, 'an ISO date'),
+        ),
+        yearsEmployed: min('yearsEmployed', 0),
+        coverageType: [
+          notEmpty('coverageType'),
+          (val) => {
+            expectTypeOf(val).toEqualTypeOf<string | undefined>();
+            return null;
+          },
+        ],
+        agreedToTerms: notEmpty('agreedToTerms'),
+        // -- nested object spec (depth 2), validators + arrays + bare arrow
+        homeAddress: {
+          city: notEmpty('city'),
+          postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+          state: (val) => {
+            expectTypeOf(val).toEqualTypeOf<string | undefined>();
+            return null;
+          },
+        },
+        // -- nested object spec on a NULLABLE section
+        mailingAddress: {
+          city: notEmpty('mailing city'),
+        },
+        coApplicant: {
+          firstName: notEmpty('coApplicant firstName'),
+        },
+        // -- list `each` spec with a nested list `each` inside (the full
+        //    composition case from the plan), plus arrays and bare arrows at
+        //    both list depths
+        drivers: {
+          each: {
+            name: notEmpty('name'),
+            licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+            licenseState: (val) => {
+              expectTypeOf(val).toEqualTypeOf<string | undefined>();
+              return null;
+            },
+            incidents: {
+              each: {
+                date: notEmpty('date'),
+                kind: (val) => {
+                  expectTypeOf(val).toEqualTypeOf<string | undefined>();
+                  return null;
+                },
+                claimAmountUsd: min('claimAmountUsd', 0),
+              },
+            },
+          },
+        },
+        // -- object-in-list: each spec whose element has a nested object spec
+        vehicles: {
+          each: {
+            vin: [notEmpty('vin')],
+            year: min('year', 1900),
+            garagingAddress: {
+              line1: notEmpty('garaging line1'),
+              postalCode: [notEmpty('garaging postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+            },
+          },
+        },
+        // -- each spec on a NULLABLE list
+        pastPolicies: {
+          each: {
+            insurer: notEmpty('insurer'),
+          },
+        },
+        // -- whole-list leaf validator on a list field (leaf forms stay legal
+        //    for structural fields)
+        discountCodes: (val) => {
+          expectTypeOf(val).toEqualTypeOf<string[]>();
+          return null;
+        },
+        // -- object field owning a key named `each`: interpreted as a nested
+        //    object spec because T directs, not the constraint's shape
+        audit: {
+          each: notEmpty('audit each'),
+        },
+      },
+      onSubmit: (values) => {
+        // Root leaves refine exactly as on the flat grammar.
+        expectTypeOf(values.firstName).toEqualTypeOf<string>();
+        expectTypeOf(values.lastName).toEqualTypeOf<string>();
+        expectTypeOf(values.email).toEqualTypeOf<string>();
+        expectTypeOf(values.dateOfBirth).toEqualTypeOf<string>();
+        expectTypeOf(values.coverageType).toEqualTypeOf<string>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
+        expectTypeOf(values.phone).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.yearsEmployed).toEqualTypeOf<number | null>();
+
+        // Nested object spec: constrained leaves refine, siblings pass through.
+        expectTypeOf(values.homeAddress.city).toEqualTypeOf<string>();
+        expectTypeOf(values.homeAddress.postalCode).toEqualTypeOf<string>();
+        expectTypeOf(values.homeAddress.state).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.homeAddress.line1).toEqualTypeOf<string | undefined>();
+
+        // Nullable section: the section stays optional, its constrained leaf
+        // refines inside the present branch.
+        expectTypeOf(values.mailingAddress?.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.mailingAddress?.line1).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.coApplicant?.firstName).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.coApplicant?.sharesResidence).toEqualTypeOf<boolean | undefined>();
+
+        // each: refined element type flows through Array<...>.
+        expectTypeOf(values.drivers[0].name).toEqualTypeOf<string>();
+        expectTypeOf(values.drivers[0].licenseNumber).toEqualTypeOf<string>();
+        expectTypeOf(values.drivers[0].licenseState).toEqualTypeOf<string | undefined>();
+
+        // list-in-list: refinement reaches depth 4.
+        expectTypeOf(values.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+        expectTypeOf(values.drivers[0].incidents[0].kind).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.drivers[0].incidents[0].claimAmountUsd).toEqualTypeOf<number | null>();
+
+        // object-in-list: nested spec inside an each spec.
+        expectTypeOf(values.vehicles[0].vin).toEqualTypeOf<string>();
+        expectTypeOf(values.vehicles[0].garagingAddress.line1).toEqualTypeOf<string>();
+        expectTypeOf(values.vehicles[0].garagingAddress.postalCode).toEqualTypeOf<string>();
+        expectTypeOf(values.vehicles[0].garagingAddress.city).toEqualTypeOf<string | undefined>();
+
+        // Nullable list: `| null` on the list survives, elements refine.
+        expectTypeOf(values.pastPolicies?.[0].insurer).toEqualTypeOf<string | undefined>();
+
+        // Disambiguation: `audit` refined as an object spec despite the
+        // `each` key.
+        expectTypeOf(values.audit.each).toEqualTypeOf<string>();
+        expectTypeOf(values.audit.reviewedBy).toEqualTypeOf<string | undefined>();
+
+        // Unconstrained structure passes through untouched.
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
+        expectTypeOf(values.discountCodes).toEqualTypeOf<string[]>();
+        expectTypeOf(values.deductibleUsd).toEqualTypeOf<number | undefined>();
+      },
+    });
+  });
+});
+
+describe('useFormState — hook-boundary regimes on the recursive grammar', () => {
+  it('without constraints, onSubmit receives the IDENTICAL form type at every depth', () => {
+    // With the default V = Validations<T>, the identity gate on Refine must
+    // short-circuit to T itself — not a union of structurally-identical
+    // mapped copies of each section (the one genuine bug the type spike
+    // found in the plan's sketch; toEqualTypeOf is the strict-identity pin).
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<InsuranceQuoteForm>();
+        expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
+        expectTypeOf(values.drivers).toEqualTypeOf<InsuranceQuoteForm['drivers']>();
+      },
+    });
+  });
+
+  it('infers T from literal initialValues while contextually typing nested constraints', () => {
+    useFormState({
+      initialValues: {
+        name: undefined as string | undefined,
+        home: {
+          city: undefined as string | undefined,
+          zip: undefined as string | undefined,
+        },
+        pets: [] as Array<{ nickname: string | undefined }>,
+      },
+      constraints: {
+        name: notEmpty('name'),
+        home: { city: notEmpty('city') },
+        pets: { each: { nickname: notEmpty('nickname') } },
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values.name).toEqualTypeOf<string>();
+        expectTypeOf(values.home.city).toEqualTypeOf<string>();
+        expectTypeOf(values.home.zip).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.pets[0].nickname).toEqualTypeOf<string>();
+      },
+    });
+  });
+
+  it('preserves refinement markers through a pre-built `as const satisfies` object at full depth', () => {
+    const prebuilt = {
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      homeAddress: {
+        city: notEmpty('city'),
+      },
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          incidents: {
+            each: { date: notEmpty('date') },
+          },
+        },
+      },
+    } as const satisfies Validations<InsuranceQuoteForm>;
+
+    // Direct Refine application, no hook in between.
+    type Submit = Refine<InsuranceQuoteForm, typeof prebuilt>;
+    expectTypeOf<Submit['email']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['homeAddress']['city']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['homeAddress']['line1']>().toEqualTypeOf<string | undefined>();
+    expectTypeOf<Submit['drivers'][number]['name']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['drivers'][number]['incidents'][number]['date']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['drivers'][number]['licenseState']>().toEqualTypeOf<string | undefined>();
+
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: prebuilt,
+      onSubmit: (values) => {
+        expectTypeOf(values.email).toEqualTypeOf<string>();
+        expectTypeOf(values.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+      },
+    });
+  });
+});
+
+declare const cond: boolean;
+
+describe('useFormState — leaf forms on structural fields, and phase-1 soundness at depth', () => {
+  it('contextually types whole-section and whole-list leaf validators', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        // A bare arrow on an OBJECT field is a whole-value validator, not a
+        // nested spec — the leaf forms stay legal for structural fields.
+        homeAddress: (val) => {
+          expectTypeOf(val).toEqualTypeOf<UsAddress>();
+          return null;
+        },
+        mailingAddress: (val) => {
+          expectTypeOf(val).toEqualTypeOf<UsAddress | undefined>();
+          return null;
+        },
+        // Whole-list validator array on a list field.
+        drivers: [
+          (val) => {
+            expectTypeOf(val).toEqualTypeOf<InsuranceQuoteForm['drivers']>();
+            return val.length > 0 ? null : 'at least one driver';
+          },
+        ],
+      },
+      onSubmit: (values) => {
+        // Whole-value leaf validators narrow nothing (no markers here).
+        expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
+        expectTypeOf(values.drivers).toEqualTypeOf<InsuranceQuoteForm['drivers']>();
+      },
+    });
+  });
+
+  it('keeps union-typed constraints per-branch sound inside nested and each specs', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        homeAddress: {
+          // Only one branch runs: distribution must yield the union of the
+          // per-branch refinements, exactly as at the root (phase 1).
+          city: cond ? notEmpty('city') : minLength('city', 2),
+          // Array with a union-typed MEMBER: the member contributes only the
+          // intersection of its branches' excludes (never here — minLength
+          // narrows nothing), so the field must NOT refine.
+          state: [cond ? notEmpty('state') : minLength('state', 2)],
+        },
+        drivers: {
+          each: {
+            name: cond ? notEmpty('name') : minLength('name', 2),
+          },
+        },
+      },
+      onSubmit: (values) => {
+        // string (notEmpty branch) | string | undefined (minLength branch)
+        expectTypeOf(values.homeAddress.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.homeAddress.state).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.drivers[0].name).toEqualTypeOf<string | undefined>();
+      },
+    });
+  });
+});
+
+// Negative probes at depth. Anchor gotcha (from the spike): wrong-KEY
+// rejections are TS2353 excess-property errors anchored at the offending
+// leaf line, but wrong-VALIDATOR-INPUT rejections are TS2322 assignability
+// errors anchored at the OUTERMOST constraint key — their `@ts-expect-error`
+// directives must sit on the parent/root key's line.
+
+describe('useFormState — recursive-grammar negative probes', () => {
+  it('rejects a wrong key inside a nested object spec', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        homeAddress: {
+          // @ts-expect-error 'cityy' is not a field of UsAddress
+          cityy: notEmpty('cityy'),
+        },
+      },
+    });
+  });
+
+  it('rejects a wrong key inside an each spec', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        drivers: {
+          each: {
+            // @ts-expect-error 'nam' is not a field of the driver element
+            nam: notEmpty('nam'),
+          },
+        },
+      },
+    });
+  });
+
+  it('rejects a wrong key inside a list-in-list each spec', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        drivers: {
+          each: {
+            incidents: {
+              each: {
+                // @ts-expect-error 'datee' is not a field of the incident element
+                datee: notEmpty('datee'),
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('rejects a bare object spec (no `each`) on a list field', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        drivers: {
+          // @ts-expect-error a list field takes { each: ... }, not a field
+          // map — EPC anchors at the unknown property
+          name: notEmpty('name'),
+        },
+      },
+    });
+  });
+
+  it('rejects an `each` spec on a plain object field', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        homeAddress: {
+          // @ts-expect-error homeAddress is an object, not a list — no `each`
+          each: { city: notEmpty('city') },
+        },
+      },
+    });
+  });
+
+  it('rejects a nested spec on a scalar leaf', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        email: {
+          // @ts-expect-error email is a scalar; only validators/arrays apply
+          domain: notEmpty('domain'),
+        },
+      },
+    });
+  });
+
+  it('rejects a wrong-input validator inside a nested spec', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        // @ts-expect-error min validates numbers; postalCode is a string —
+        // the TS2322 anchors at the PARENT key, elaboration names postalCode
+        homeAddress: {
+          postalCode: min('postalCode', 0),
+        },
+      },
+    });
+  });
+
+  it('rejects a wrong-input validator in an array at list-in-list depth', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        // @ts-expect-error min validates numbers; date is a string — the
+        // TS2322 anchors at the ROOT constraint key, elaboration walks
+        // each.incidents → each.date down to the parameter mismatch
+        drivers: {
+          each: {
+            incidents: {
+              each: {
+                date: [notEmpty('date'), min('date', 0)],
+              },
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it('rejects a bare validator where an each spec map is required', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        // @ts-expect-error `each` takes a per-field map, not a validator
+        // (rejected by the weak-type check; anchors at the parent key)
+        vehicles: {
+          each: minLength('vehicles', 1),
+        },
+      },
+    });
+  });
+});

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

@@ -40,8 +40,8 @@ describe('useFormState', () => {
         constraints: { email: notEmpty('email') },
       }),
     );
-    // The full structured shape: one entry per failing field, addressed by
-    // a typed path (single-key on the flat grammar).
+    // The full structured shape: one entry per failing constrained node,
+    // addressed by a typed path (single-key for a root leaf).
     expect(result.current.errors).toEqual([
       { path: ['email'], error: "'email' cannot be empty" },
     ]);

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

@@ -1,4 +1,4 @@
-import type { FormValuesObject } from '../useFormState/types';
+import type { FormValueList, FormValuesObject } from '../useFormState/types';
 
 // Phantom marker carried by validators. The runtime value of `__excludes`
 // is meaningless and never read — only its declared type matters. Required
@@ -23,16 +23,39 @@ export type Validator<Input, Excluded = never> =
 // structurally by `Refine<>`.
 export type FieldValidator<F> = (val: F) => string | null;
 
-// What a constraints key may map to — phase 1 of the target grammar (see
-// plan.md): the leaf forms only. A single validator, or an ordered list of
-// validators run first-error-wins (sugar over `allOf` at the constraint
-// site; `allOf` remains for building reusable composite validators). The
-// structural forms (nested `Validations`, list `each`) arrive in phases 2–3.
+// What a constraints key may map to — the full target grammar (see plan.md).
+// The leaf forms (a single validator, or an ordered list run
+// first-error-wins — sugar over `allOf` at the constraint site; `allOf`
+// remains for building reusable composite validators) are legal for ANY
+// field type, structural fields included: a bare arrow on an object field is
+// a whole-section validator. The structural forms are directed by the
+// FIELD's type, never guessed from the constraint's shape (see
+// "Disambiguation" in plan.md): only an object-typed field admits a nested
+// `Validations`, only a list-typed field admits `{ each: … }`. `F` is naked
+// in the conditionals, so nullable sections/lists distribute — for
+// `UsAddress | undefined` the object arm fires for the present member. Do
+// NOT wrap `F` in `NonNullable` "to help": that breaks the distribution and
+// blows the recursion stack (TS2589) — see the maintainer note in
+// src/forms/CLAUDE.md.
 export type FieldConstraint<F> =
   | FieldValidator<F>
-  | readonly FieldValidator<F>[];
+  | readonly FieldValidator<F>[]
+  | (F extends FormValuesObject ? Validations<F> : never)
+  | (F extends FormValueList ? ListConstraint<F[number]> : never);
 
-// The constraint for a per-field validation map.
+// 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.
+export type ListConstraint<Element extends FormValuesObject> = {
+  readonly each: Validations<Element>;
+  // room to grow, e.g. a `self` slot for list-level rules (min count,
+  // uniqueness) — not in scope for v1
+};
+
+// The constraint for a per-field validation map — recursive through nested
+// object specs and list `each` specs.
 export type Validations<T extends FormValuesObject> = {
   readonly [K in keyof T]?: FieldConstraint<T[K]>;
 };
@@ -84,19 +107,56 @@ export type MemberExcludes<C extends readonly unknown[]> = {
 // validator *array* is the opposite regime: every member runs, so the union
 // ACROSS members is earned in a single `Exclude` — but each member's own
 // contribution is per-member sound (`MemberExcludes`): a union-typed member
-// claims only the intersection of its branches' excludes. Branch order
-// matters once the grammar grows structural forms (validator functions are
-// objects) — `Refinement` stays first.
+// claims only the intersection of its branches' excludes.
+//
+// Branch order: `Refinement` first (validator functions are objects — a
+// marked validator must not fall into a structural arm), then arrays, then
+// the structural arms. The structural arms interrogate the VALUE MODEL
+// (`F`) before the constraint's shape, per the disambiguation doctrine: an
+// object field that legitimately owns a key named `each` must be refined as
+// a nested spec, so `F extends FormValueList` is asked before looking for
+// `each`. (`F` also distributes here, which is what carries `| null` /
+// `| undefined` on nullable sections/lists through around the refined
+// interior.) A bare marker-less validator on a structural field lands in
+// `RefineObject<F, C>` with `keyof C` empty, an identity map — refined type
+// structurally unchanged, as a whole-value validator should be.
 type RefineField<F, C> = C extends Refinement<infer Excluded>
   ? Exclude<F, Excluded>
   : C extends readonly unknown[]
     ? Exclude<F, MemberExcludes<C>>
-    : F;
+    : C extends object
+      ? F extends FormValueList
+        ? C extends { readonly each: infer E }
+          ? Array<RefineObject<F[number], E>>
+          : F
+        : F extends FormValuesObject
+          ? RefineObject<F, C>
+          : F
+      : F;
 
-// Applies each field's constraint to the form type: the submit-time type.
-// Singles narrow by their marker, arrays by the union of their members'
-// sound excludes; unconstrained fields and bare (marker-less) validators
-// pass through unchanged. Shallow by design — one mapped type, no recursion.
-export type Refine<T extends FormValuesObject, V extends Validations<T>> = {
+type RefineObject<T, V> = {
   [K in keyof T]: K extends keyof V ? RefineField<T[K], V[K]> : T[K];
 };
+
+// Applies the constraints object to the form type, recursively: the
+// submit-time type. Singles narrow by their marker, arrays by the union of
+// their members' sound excludes, nested/`each` specs recurse; unconstrained
+// fields and bare (marker-less) validators pass through unchanged.
+//
+// The identity gate up front is load-bearing, not an optimization (phase-2
+// type spike, adjustment 2): with constraints omitted, the hook's default
+// `V = Validations<T>` would send `FieldConstraint<F> | undefined` through
+// the distributive walk at every key, and structural fields would come back
+// as unions of structurally-identical mapped COPIES of each section —
+// mutually assignable with `T` but not identity-equal (mangled hover types,
+// fails strict type equality). `Validations<T> extends V` is true exactly
+// when `V` is the default (or an empty/fully-widened literal — where no
+// markers survive anyway), so short-circuit to `T` itself. Any concrete
+// constraints literal is strictly narrower, so the real walk runs. Nested
+// occurrences don't need the gate: for a concrete literal `V`, `keyof V`
+// holds only the keys actually written, so uncovered fields take the `T[K]`
+// arm verbatim at every level.
+export type Refine<
+  T extends FormValuesObject,
+  V extends Validations<T>,
+> = Validations<T> extends V ? T : RefineObject<T, V>;