@structuralists/scaffolding 0.13.0 → 0.15.0

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

@@ -0,0 +1,451 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { useFormState } from './useFormState';
+import { perField } from '../validations/perField';
+import { matches, min, minLength, notEmpty } from '../validators/validators';
+import type { FormFieldProps } from './types';
+import type { Refine, Validations } from '../validations/types';
+
+// ---------------------------------------------------------------------------
+// The stress tier (plan phase 4, composition hardening) — the phase-2 type
+// spike's stress fixtures, pinned against the REAL hook. Where
+// useFormState.test-d.ts probes the grammar at chunky (~30-leaf) scale, this
+// file pushes past it to hold the measured headroom: a ~110-leaf form at 5–6
+// levels with the large applicant spec written inline twice, the same spec
+// pre-built ONCE via perField and reused for both applicant sections (the
+// pre-built entry point at realistic scale), a 12-level nested-object spec
+// ladder, a 4-deep list-in-list `each` ladder, and deep Path bindings on the
+// mega form. If the recursion budget regresses, tsc slows or fails here
+// first — watch the instantiation count in the plan's recursion-budget
+// section, not just success.
+// ---------------------------------------------------------------------------
+
+type UsAddress = {
+  line1: string | undefined;
+  line2: string | undefined;
+  city: string | undefined;
+  state: string | undefined;
+  postalCode: string | undefined;
+};
+
+type Incident = {
+  date: string | undefined;
+  kind: string | undefined;
+  claimAmountUsd: number | null;
+};
+
+type Driver = {
+  name: string | undefined;
+  licenseNumber: string | undefined;
+  licenseState: string | undefined;
+  incidents: Incident[];
+};
+
+type Vehicle = {
+  vin: string | undefined;
+  year: number | undefined;
+  make: string | undefined;
+  model: string | undefined;
+  primaryDriverName: string | undefined;
+  garagingAddress: UsAddress;
+};
+
+type Applicant = {
+  firstName: string | undefined;
+  lastName: string | undefined;
+  email: string | undefined;
+  phone: string | undefined;
+  dateOfBirth: string | undefined;
+  employer: string | null;
+  jobTitle: string | null;
+  yearsEmployed: number | null;
+  annualIncomeUsd: number | null;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress | undefined;
+  drivers: Driver[];
+  vehicles: Vehicle[];
+};
+
+type MegaQuoteForm = {
+  primary: Applicant;
+  secondary: Applicant | undefined;
+  household: {
+    address: UsAddress;
+    members: Array<{
+      name: string | undefined;
+      relation: string | undefined;
+      dateOfBirth: string | undefined;
+    }>;
+  };
+  quotes: Array<{
+    coverageType: string | undefined;
+    deductibleUsd: number | undefined;
+    startDate: string | undefined;
+    riders: Array<{
+      code: string | undefined;
+      amountUsd: number | null;
+    }>;
+  }>;
+  referralSource: string | null;
+  notes: string | undefined;
+  agreedToTerms: boolean | undefined;
+  paperlessBilling: boolean;
+};
+
+describe('useFormState stress: ~110-leaf form, large inline spec written twice', () => {
+  it('composes and refines with the applicant spec duplicated inline', () => {
+    useFormState({
+      initialValues: {} as MegaQuoteForm,
+      constraints: {
+        primary: {
+          firstName: notEmpty('firstName'),
+          lastName: [notEmpty('lastName')],
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+          phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+          dateOfBirth: notEmpty('dateOfBirth'),
+          yearsEmployed: min('yearsEmployed', 0),
+          annualIncomeUsd: min('annualIncomeUsd', 0),
+          homeAddress: {
+            line1: notEmpty('line1'),
+            city: notEmpty('city'),
+            postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+          },
+          mailingAddress: {
+            city: notEmpty('mailing city'),
+          },
+          drivers: {
+            each: {
+              name: notEmpty('name'),
+              licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+              incidents: {
+                each: {
+                  date: notEmpty('date'),
+                  claimAmountUsd: min('claimAmountUsd', 0),
+                },
+              },
+            },
+          },
+          vehicles: {
+            each: {
+              vin: [notEmpty('vin')],
+              year: min('year', 1900),
+              garagingAddress: {
+                line1: notEmpty('garaging line1'),
+                postalCode: [notEmpty('garaging postalCode')],
+              },
+            },
+          },
+        },
+        // The same large spec again, on the nullable secondary applicant —
+        // simulates a real page where big sections each get full specs.
+        secondary: {
+          firstName: notEmpty('firstName'),
+          lastName: [notEmpty('lastName')],
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+          phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+          dateOfBirth: notEmpty('dateOfBirth'),
+          yearsEmployed: min('yearsEmployed', 0),
+          annualIncomeUsd: min('annualIncomeUsd', 0),
+          homeAddress: {
+            line1: notEmpty('line1'),
+            city: notEmpty('city'),
+            postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+          },
+          mailingAddress: {
+            city: notEmpty('mailing city'),
+          },
+          drivers: {
+            each: {
+              name: notEmpty('name'),
+              licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+              incidents: {
+                each: {
+                  date: notEmpty('date'),
+                  claimAmountUsd: min('claimAmountUsd', 0),
+                },
+              },
+            },
+          },
+          vehicles: {
+            each: {
+              vin: [notEmpty('vin')],
+              year: min('year', 1900),
+              garagingAddress: {
+                line1: notEmpty('garaging line1'),
+                postalCode: [notEmpty('garaging postalCode')],
+              },
+            },
+          },
+        },
+        household: {
+          address: {
+            city: notEmpty('household city'),
+          },
+          members: {
+            each: {
+              name: notEmpty('member name'),
+              dateOfBirth: notEmpty('member dateOfBirth'),
+            },
+          },
+        },
+        quotes: {
+          each: {
+            coverageType: notEmpty('coverageType'),
+            deductibleUsd: min('deductibleUsd', 0),
+            startDate: notEmpty('startDate'),
+            riders: {
+              each: {
+                code: notEmpty('code'),
+                amountUsd: min('amountUsd', 0),
+              },
+            },
+          },
+        },
+        referralSource: notEmpty('referralSource'),
+        agreedToTerms: notEmpty('agreedToTerms'),
+      },
+      onSubmit: (values) => {
+        // Depth 5–6 refinements on both applicant sections.
+        expectTypeOf(values.primary.email).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.homeAddress.postalCode).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.vehicles[0].garagingAddress.line1).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.drivers[0].licenseState).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.secondary?.homeAddress.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.secondary?.drivers[0].incidents[0].date).toEqualTypeOf<
+          string | undefined
+        >();
+        expectTypeOf(values.household.members[0].name).toEqualTypeOf<string>();
+        expectTypeOf(values.quotes[0].riders[0].code).toEqualTypeOf<string>();
+        expectTypeOf(values.quotes[0].riders[0].amountUsd).toEqualTypeOf<number | null>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
+      },
+    });
+  });
+
+  it('Path machinery holds at mega scale: deep bindings on the hook result', () => {
+    const form = useFormState({ initialValues: {} as MegaQuoteForm });
+
+    expectTypeOf(
+      form.getFormFieldPropsAt(['primary', 'drivers', 0, 'incidents', 0, 'date']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['secondary', 'vehicles', 0, 'garagingAddress', 'postalCode']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['quotes', 0, 'riders', 0, 'amountUsd']),
+    ).toEqualTypeOf<FormFieldProps<number | null>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['household', 'members', 0, 'relation']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+
+    // @ts-expect-error 'drvers' is not a field of the primary applicant
+    form.getFormFieldPropsAt(['primary', 'drvers', 0, 'name']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// perField at realistic scale (plan phase 4): the pre-built entry point on
+// the full recursive grammar — one applicant spec built once, reused for
+// both applicant sections, mixing each-in-each, nested-in-each, and a
+// whole-list leaf validator on a structural field. Before this phase,
+// perField was only ever exercised on a 3-key flat form.
+// ---------------------------------------------------------------------------
+
+describe('useFormState stress: perField pre-built specs at mega scale', () => {
+  it('preserves markers through a perField applicant spec reused across sections', () => {
+    const applicantSpec = perField({
+      firstName: notEmpty('firstName'),
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      yearsEmployed: min('yearsEmployed', 0),
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+      },
+      mailingAddress: {
+        city: notEmpty('mailing city'),
+      },
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+          incidents: {
+            each: {
+              date: notEmpty('date'),
+              claimAmountUsd: min('claimAmountUsd', 0),
+            },
+          },
+        },
+      },
+      // Whole-list leaf validator on a structural field: leaf and structural
+      // forms are mutually exclusive per key, so vehicles takes the
+      // list-as-a-value form while drivers takes `each`.
+      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') },
+        },
+      },
+      agreedToTerms: notEmpty('agreedToTerms'),
+    } as const satisfies Validations<MegaQuoteForm>;
+
+    // Direct Refine application on the composed pre-built object.
+    type Submit = Refine<MegaQuoteForm, typeof constraints>;
+    expectTypeOf<Submit['primary']['email']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['primary']['homeAddress']['postalCode']>().toEqualTypeOf<string>();
+    expectTypeOf<
+      Submit['primary']['drivers'][number]['incidents'][number]['date']
+    >().toEqualTypeOf<string>();
+    expectTypeOf<Submit['primary']['vehicles']>().toEqualTypeOf<Vehicle[]>();
+    expectTypeOf<Submit['secondary']>().toEqualTypeOf<
+      Refine<Applicant, typeof applicantSpec> | undefined
+    >();
+    expectTypeOf<Submit['household']['members'][number]['name']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['quotes']>().toEqualTypeOf<MegaQuoteForm['quotes']>();
+
+    // And through the hook boundary.
+    useFormState({
+      initialValues: {} as MegaQuoteForm,
+      constraints,
+      onSubmit: (values) => {
+        expectTypeOf(values.primary.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+        expectTypeOf(values.secondary?.homeAddress.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
+      },
+    });
+  });
+});
+
+// --- Object-depth ladder: specs 12 levels deep --------------------------------
+
+type L12 = { leaf: string | undefined; tag: string | undefined };
+type L11 = { next: L12; tag: string | undefined };
+type L10 = { next: L11; tag: string | undefined };
+type L9 = { next: L10; tag: string | undefined };
+type L8 = { next: L9; tag: string | undefined };
+type L7 = { next: L8; tag: string | undefined };
+type L6 = { next: L7; tag: string | undefined };
+type L5 = { next: L6; tag: string | undefined };
+type L4 = { next: L5; tag: string | undefined };
+type L3 = { next: L4; tag: string | undefined };
+type L2 = { next: L3; tag: string | undefined };
+type L1 = { next: L2; tag: string | undefined };
+type DeepObjectForm = { root: L1 };
+
+describe('useFormState stress: 12-level nested-object spec ladder', () => {
+  it('refines a leaf 13 levels down, with a validator at every level', () => {
+    useFormState({
+      initialValues: {} as DeepObjectForm,
+      constraints: {
+        root: {
+          tag: notEmpty('t1'),
+          next: {
+            tag: notEmpty('t2'),
+            next: {
+              tag: notEmpty('t3'),
+              next: {
+                tag: notEmpty('t4'),
+                next: {
+                  tag: notEmpty('t5'),
+                  next: {
+                    tag: notEmpty('t6'),
+                    next: {
+                      tag: notEmpty('t7'),
+                      next: {
+                        tag: notEmpty('t8'),
+                        next: {
+                          tag: notEmpty('t9'),
+                          next: {
+                            tag: notEmpty('t10'),
+                            next: {
+                              tag: notEmpty('t11'),
+                              next: {
+                                tag: notEmpty('t12'),
+                                leaf: [notEmpty('leaf'), minLength('leaf', 2)],
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      onSubmit: (values) => {
+        expectTypeOf(
+          values.root.next.next.next.next.next.next.next.next.next.next.next.leaf,
+        ).toEqualTypeOf<string>();
+        expectTypeOf(
+          values.root.next.next.next.next.next.next.next.next.next.next.next.tag,
+        ).toEqualTypeOf<string>();
+        expectTypeOf(values.root.tag).toEqualTypeOf<string>();
+      },
+    });
+  });
+});
+
+// --- List-depth ladder: `each` 4 levels deep ----------------------------------
+
+type DeepListForm = {
+  xs: Array<{
+    label: string | undefined;
+    ys: Array<{
+      label: string | undefined;
+      zs: Array<{
+        label: string | undefined;
+        ws: Array<{
+          v: string | undefined;
+          n: number | null;
+        }>;
+      }>;
+    }>;
+  }>;
+};
+
+describe('useFormState stress: 4-deep list-in-list each ladder', () => {
+  it('refines through four nested each specs', () => {
+    useFormState({
+      initialValues: {} as DeepListForm,
+      constraints: {
+        xs: {
+          each: {
+            label: notEmpty('x label'),
+            ys: {
+              each: {
+                label: notEmpty('y label'),
+                zs: {
+                  each: {
+                    label: notEmpty('z label'),
+                    ws: {
+                      each: {
+                        v: notEmpty('v'),
+                        n: min('n', 0),
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values.xs[0].ys[0].zs[0].ws[0].v).toEqualTypeOf<string>();
+        expectTypeOf(values.xs[0].ys[0].zs[0].ws[0].n).toEqualTypeOf<number | null>();
+        expectTypeOf(values.xs[0].ys[0].zs[0].label).toEqualTypeOf<string>();
+      },
+    });
+  });
+});

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

@@ -1,14 +1,25 @@
+// The loose, form-type-agnostic shape of one constraint: a validator, a
+// validator array, or an object of more of the same — which covers both
+// nested specs and `{ each: … }` (an `each` value is itself a spec object).
+// `(val: never) => …` admits any validator input contravariantly. This bound
+// only rejects obvious garbage (strings, numbers, null values); the real
+// shape check — every key a field, every validator's input compatible,
+// structural forms only where the field type permits — happens at the
+// caller's `satisfies Validations<FormType>`, which is where the form type
+// first enters the picture.
+type LooseFieldConstraint =
+  | ((val: never) => string | null)
+  | readonly ((val: never) => string | null)[]
+  | { readonly [key: string]: LooseFieldConstraint };
+
 // Aggregation entry point for building a `Validations<T>`-shaped constraints
-// object. Runtime identity; the value is in the type: the `const` type
-// parameter freezes each validator's precise type (including `Refinement`
-// markers) instead of letting function types widen. Callers still apply
-// `as const satisfies Validations<FormType>` to shape-check against their
-// form type without losing that precision — see src/forms/CLAUDE.md.
-export const perField = <
-  const V extends Record<
-    string,
-    ((val: never) => string | null) | readonly ((val: never) => string | null)[]
-  >,
->(
+// object — the full recursive grammar (leaf validators and arrays, nested
+// object specs, list `each` specs, freely composed). Runtime identity; the
+// value is in the type: the `const` type parameter freezes each validator's
+// precise type (including `Refinement` markers) instead of letting function
+// types widen. Callers still apply `satisfies Validations<FormType>` to
+// shape-check against their form type without losing that precision — see
+// src/forms/CLAUDE.md.
+export const perField = <const V extends Record<string, LooseFieldConstraint>>(
   validations: V,
 ): V => validations;

package/src/forms/state/validations/types.test-d.ts

@@ -205,6 +205,114 @@ describe('Refine<T, V> — union-typed members inside arrays', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// perField at the recursive grammar (plan phase 4): the pre-built-spec entry
+// point admits the full grammar — nested object specs, list `each` specs,
+// arrays at every level — and preserves refinement markers through all of it.
+// perField's own bound is shape-only (validators / arrays / objects of the
+// same); the form-type shape check happens at `satisfies Validations<T>`.
+// ---------------------------------------------------------------------------
+
+type NestedFormType = {
+  email: string | undefined;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+  mailingAddress: { city: string | undefined } | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    incidents: Array<{ date: string | undefined }>;
+  }>;
+};
+
+describe('perField — recursive grammar', () => {
+  it('preserves markers through nested specs and each-in-each specs', () => {
+    const constraints = perField({
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: [notEmpty('postalCode'), minLength('postalCode', 5)],
+      },
+      mailingAddress: {
+        city: notEmpty('mailing city'),
+      },
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          incidents: { each: { date: notEmpty('date') } },
+        },
+      },
+    }) satisfies Validations<NestedFormType>;
+
+    type Result = Refine<NestedFormType, typeof constraints>;
+    expectTypeOf<Result['email']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['city']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['postalCode']>().toEqualTypeOf<string>();
+    // Nullability survives around the refined interior of a nullable section.
+    expectTypeOf<Result['mailingAddress']>().toEqualTypeOf<
+      { city: string } | undefined
+    >();
+    expectTypeOf<Result['drivers'][number]['name']>().toEqualTypeOf<string>();
+    expectTypeOf<
+      Result['drivers'][number]['incidents'][number]['date']
+    >().toEqualTypeOf<string>();
+  });
+
+  it('a pre-built section spec composes as a nested-spec value', () => {
+    // Building one section's spec via perField and placing it under the
+    // section key in a larger constraints object — the reuse shape phase 4
+    // exists to keep working.
+    const addressSpec = perField({
+      city: notEmpty('city'),
+    }) satisfies Validations<NestedFormType['homeAddress']>;
+
+    const constraints = {
+      homeAddress: addressSpec,
+      mailingAddress: addressSpec,
+    } as const satisfies Validations<NestedFormType>;
+
+    type Result = Refine<NestedFormType, typeof constraints>;
+    expectTypeOf<Result['homeAddress']['city']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['postalCode']>().toEqualTypeOf<
+      string | undefined
+    >();
+    expectTypeOf<Result['mailingAddress']>().toEqualTypeOf<
+      { city: string } | undefined
+    >();
+  });
+
+  it('rejects non-constraint values at the perField call itself', () => {
+    perField({
+      // @ts-expect-error a string is not a validator, array, or spec
+      email: 'not a validator',
+    });
+    perField({
+      // @ts-expect-error garbage stays rejected at depth (the TS2322
+      // anchors at the parent key, same as deep validator-input mismatches)
+      homeAddress: {
+        city: 42,
+      },
+    });
+  });
+
+  it('form-type shape errors surface at the satisfies check', () => {
+    // perField is form-type-agnostic, so a wrong key passes its bound and
+    // is caught where the form type first appears.
+    const wrongKey = perField({
+      homeAddress: { cityy: notEmpty('cityy') },
+    });
+    // @ts-expect-error 'cityy' is not a field of homeAddress
+    wrongKey satisfies Validations<NestedFormType>;
+
+    const eachOnObject = perField({
+      homeAddress: { each: { city: notEmpty('city') } },
+    });
+    // @ts-expect-error an `each` spec is not legal on an object field
+    eachOnObject satisfies Validations<NestedFormType>;
+  });
+});
+
 describe('Refine<T, V> — union-typed single constraints (conditional pick)', () => {
   it('narrows a conditionally-picked validator to the union of branch results', () => {
     // Only ONE branch runs at runtime, so the sound result is the UNION of

package/src/storybook/CLAUDE.md

@@ -23,6 +23,15 @@ What still applies: CSS modules, `--ui-*` tokens, no HTML attribute pass-through
 
 If a story util starts getting reached for by app code, that's a signal to build a real primitive, not to promote the story util. A real `Placeholder` for empty states would be a different primitive with proper typography, icon support, and action slots — not this dashed box. Keep the lanes separate.
 
+## Showcase story files live here too
+
+Besides the utils, this folder hosts the cross-component showcase stories:
+`Composition.stories.tsx` (`Composition/…`) and `Demo.stories.tsx` (`Demo/…`
+— the polished mini-app demos; conventions in the root AGENTS.md "The Demo
+section"). They are ordinary stories, not utils: they compose the library's
+public pieces, keep their datasets deterministic, and carry `play`-function
+integration tests. The relaxed util rules above don't apply to them.
+
 ## Adding a new util
 
 - New folder under `src/_StoryUtils/<Name>/` with `index.tsx`.