@structuralists/scaffolding 0.4.2 → 0.5.1

package/src/forms/plan.md

@@ -0,0 +1,270 @@
+# Plan: composable, recursive `Validations`
+
+Status: **proposed** — nothing below is built yet. The baseline (flat
+`Validations<T>`, one validator per key, shallow `Refine`) is on
+`forms/useformstate-baseline`.
+
+## Goal
+
+Evolve `Validations<T>` so a constraints object can:
+
+1. hold **multiple validators per key** (an array),
+2. **recurse into nested object** form state,
+3. apply a spec **to each element of a list** (`FormValueList`),
+4. **compose** all of the above freely — while the refinement machinery
+   (`Refinement` markers → `Refine<T, V>` → narrowed `onSubmit`) keeps
+   working at every level.
+
+Plus two items that ride on top, independent of the type work:
+
+5. split the forms area into **'form elements'** and **'form state'**
+   (see the section at the end),
+6. **field binding**: a `getFormFieldPropsAt(path)` helper plus
+   form-element shorthands (`TextInputForForm` style) so wiring a field is
+   one expression (see the section at the end).
+
+## Target grammar
+
+What a key can map to is directed by the *field's* type, never guessed from
+the constraint's shape (see "Disambiguation" below):
+
+```ts
+type FieldValidator<F> = (val: F) => string | null; // possibly & Refinement<X>
+
+type FieldConstraint<F> =
+  // leaf forms — allowed for any field type
+  | FieldValidator<F>
+  | readonly FieldValidator<F>[]
+  // structural forms — allowed only where the field type permits
+  | (F extends FormValuesObject ? Validations<F> : never)
+  | (F extends FormValueList ? ListConstraint<F[number]> : never);
+
+type ListConstraint<Element extends FormValuesObject> = {
+  readonly each: Validations<Element>;
+  // room to grow, e.g.:  readonly self?: readonly FieldValidator<Element[]>[]
+  // for list-level rules (min count, uniqueness) — NOT in scope for v1
+};
+
+type Validations<T extends FormValuesObject> = {
+  readonly [K in keyof T]?: FieldConstraint<T[K]>;
+};
+```
+
+Example of the full composition:
+
+```ts
+useFormState({
+  initialValues: {} as InsuranceQuoteForm,
+  constraints: {
+    email: [notEmpty('email'), matches('email', /@/, 'a valid email')], // (1)
+    homeAddress: {                                                      // (2)
+      city: notEmpty('city'),
+      postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+    },
+    drivers: {                                                          // (3)
+      each: {
+        name: notEmpty('name'),
+        incidents: { each: { date: notEmpty('date') } },                // (4) nested list-in-list
+      },
+    },
+  },
+  onSubmit: (values) => {
+    values.email;                        // string
+    values.homeAddress.city;             // string
+    values.drivers[0].incidents[0].date; // string
+  },
+});
+```
+
+## Refinement through the grammar
+
+`Refine` becomes recursive, mirroring the grammar. Sketch:
+
+```ts
+type ExcludedOf<V> = V extends Refinement<infer X> ? X : never;
+
+type RefineField<F, C> =
+  C extends Refinement<infer X>        ? Exclude<F, X>                 // single marked validator
+  : C extends readonly unknown[]       ? Exclude<F, ExcludedOf<C[number]>> // validator array: union of excludes
+  : C extends { readonly each: infer E } ? F extends FormValueList
+      ? Array<RefineObject<F[number], E>> : F                          // per-element
+  : C extends object                   ? F extends FormValuesObject
+      ? RefineObject<F, C> : F                                         // nested spec
+  : F;                                                                 // bare fn / no marker
+
+type RefineObject<T, V> = { [K in keyof T]: K extends keyof V ? RefineField<T[K], V[K]> : T[K] };
+```
+
+Branch-order constraints discovered in the baseline, which this sketch bakes
+in:
+
+- **Check `Refinement` before `object`** — validator functions are objects.
+- **A bare function** (no marker) falls to the final `F` arm — narrows nothing.
+- The runtime cast in `submit()` stays the same single honest cast: valid ⇒
+  every constrained node passed, at every depth, which is what the recursive
+  `Refine` now encodes.
+
+### Disambiguation
+
+A `FormValuesObject` field could theoretically own a key named `each`, making
+a nested `Validations` look like a `ListConstraint`. This never bites because
+interpretation is **directed by `T`**: for an object-typed field only the
+`Validations<F>` branch is live; for a list-typed field only `ListConstraint`.
+Both the type level (`F extends ...` conditionals) and the runtime walker must
+branch on the *value model*, never on constraint shape alone.
+
+## ⚠️ The recursion budget — the actual risk
+
+The baseline's `Refine` is a single shallow mapped type; this plan makes it
+recursive. Prior explorations of this design died on TS recursion limits with
+realistic state, and a recursive `Refine` is the prime suspect for where that
+happened. Discipline for every phase below:
+
+- **Extend the recursion probe first** (`useFormState.test-d.ts`,
+  `InsuranceQuoteForm`): add the phase's construct at realistic scale *before*
+  implementing, so the failure mode is visible the moment it appears.
+- Watch `tsc` wall-time, not just success — a 10× check-time regression is a
+  failure even if it compiles.
+- If a phase hits the wall, stop and record the ceiling in the learning map
+  before reaching for tricks (interface-based lazy recursion, depth caps).
+
+## Runtime consequences (can't be dodged)
+
+- **The validator walk becomes a tree walk.** Recursion mirrors `read()` in
+  `path/path.ts`; share the traversal or keep them deliberately parallel.
+- **`FormErrors` can no longer be `Partial<Record<keyof T, string>>`.**
+  Decided: errors become a plain list of structured entries,
+
+  ```ts
+  type FormError<T> = { path: Path<T>; error: string };
+  // errors: FormError<T>[]      isValid: errors.length === 0
+  ```
+
+  reusing `path/`'s typed representation (this is the "surfacing per-field
+  errors" role path/ was built for). **We will never expose
+  `'drivers.0.name'`-style serialized-string key derivation.** At the scale
+  these forms operate, a linear scan over `{path, error}[]` is fine. If fast
+  lookup is ever genuinely needed, a string-keyed map is permitted strictly
+  as an *internal* implementation detail — the concatenation scheme must be
+  fully encapsulated and opaque to everything outside it.
+- **`errors` display wiring** in stories/components goes through a typed
+  accessor (e.g. `errorAt(errors, path)` / a cursor-based lookup), never
+  through hand-assembled keys.
+
+## Phases
+
+Each phase lands with: type tests (inline-call context on the chunky form —
+contextual typing differs there, learned the hard way with `allOf`), runtime
+tests, story updates where visible, probe ratchet.
+
+1. **Validator arrays per key.** Pure sugar over `allOf` at the constraint
+   site (`allOf` remains for building reusable composite validators).
+   First-error-wins per field, same as `allOf`. Excludes union via
+   `ExcludedOf<C[number]>`.
+2. **Nested object specs + recursive `Refine`.** The risk phase — the probe
+   ratchet matters most here. Errors become `{path, error}[]` in this phase
+   (nested fields need addresses).
+3. **List `each` specs.** Runtime walks every element; error paths carry the
+   numeric step (`['drivers', 3, 'name']`). Refined element type flows
+   through `Array<...>`.
+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.
+
+## 5. Split forms into 'form elements' and 'form state'
+
+Today the form world lives in two places with unrelated names:
+
+- `src/components/Forms/` — the presentational **elements** (`Input`,
+  `Field`, `Select`, `Button`, `Textarea`, …)
+- `src/forms/` — the **state** layer (`useFormState`, `validations/`,
+  `validators/`, `path/`)
+
+The intent: make that split explicit and named — 'form elements' vs
+'form state' — rather than the current accidental `Forms`-vs-`forms`
+distinction. Recorded as direction; the target layout/naming is an open
+decision (rename in place? move both under one `forms/` umbrella with
+`elements/` and `state/` subtrees?).
+
+Blast radius to account for when this happens (not now):
+
+- the eslint `boundaries` element patterns in `eslint.config.mjs` are keyed
+  to `src/components/<Section>/<Component>/` shapes,
+- barrel exports in `src/index.ts` (all the element components are public),
+- Storybook titles (`Forms/...` prefix) and story globs,
+- forms/CLAUDE.md and this plan's own paths.
+
+Independent of phases 1–4; can land before, between, or after them.
+
+## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands
+
+Today every field is wired by hand in JSX: read `values.x`, spread-update via
+`onValueChanges`, look up the error, gate it on `submitAttempted`. That's
+four decisions per field, all boilerplate. Target usage:
+
+```tsx
+<TextInputForForm formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])} />
+```
+
+### `getFormFieldPropsAt(path)`
+
+A member of the hook's return value (it needs `values`, `errors`, and the
+setter), typed by the `path/` machinery:
+
+```ts
+type FormFieldProps<V> = {
+  value: V;
+  onChange: (val: V) => void;
+  errorMessage: string | undefined; // display-policy-aware (see below)
+  onBlur: () => void;               // feeds touched tracking
+  // room to grow: name/id derivation, disabled, ...
+};
+
+// on FormHelpers<T>:
+getFormFieldPropsAt<P extends Path<T>>(path: P): FormFieldProps<ValueAt<T, P>>;
+```
+
+Consequences this pulls in deliberately:
+
+- **Granular setters via path arrive here** — this retires the "likely
+  remove" todo on `onValueChanges` as the only write path. Writing at a path
+  is the immutable-update mirror of `read()` in `path/path.ts`.
+- **Touched tracking becomes real state** (`onBlur` feeds it). The
+  error-display policy (submitAttempted / touched gating) moves *inside*
+  `errorMessage`, so consuming elements render what they're given and stay
+  policy-free.
+- **`errorMessage` looks up the structured `{path, error}[]` list** by path
+  equality — the typed accessor from the error-model decision, not string
+  keys.
+- Type safety composes end-to-end: `ValueAt<T, P>` types `value`/`onChange`,
+  so binding a `number`-typed path to a text-shaped element is a compile
+  error at the `formFieldProps` prop.
+
+### Element shorthands
+
+Form elements get a form-aware flavor that accepts the bundle as one prop —
+current lean: wrapper components (`TextInputForForm`, `SingleSelectForForm`,
+…) taking `formFieldProps: FormFieldProps<V>` alongside the element's
+presentational props. The alternative is union-typed props on the existing
+elements themselves. **Deciding criterion (per Will): whichever is simpler
+for agents to work with** — wrappers keep each component's prop surface
+small and self-evident, unions avoid a parallel component set; prototype the
+wrapper style first, `TextInputForForm` probably, but not settled.
+
+Placement note: these wrappers are the bridge between 'form elements' and
+'form state', so where they live should fall out of the split in item 5 —
+they are the one layer allowed to know about both sides.
+
+## Open decisions
+
+- **Whole-value + structural constraints on the same key** (e.g. validate
+  `homeAddress` as a unit *and* its fields). Not expressible in this grammar.
+  Recommendation: punt from v1; if needed, later extend the structural forms
+  with a reserved `self` slot rather than overloading arrays.
+- **Array semantics: first-error-wins vs collect-all.** v1: first-error-wins
+  (consistent with `allOf`). Collect-all becomes interesting only when the
+  UI can show multiple messages per field — note the `{path, error}[]` error
+  model already accommodates multiple entries per path when that day comes.
+
+*(Resolved: error path format. Structured `{path, error}[]` with typed
+paths — never exposed serialized-string keys. See "Runtime consequences".)*

package/src/forms/useFormState/types.ts

@@ -6,8 +6,18 @@ export type FormValueList = FormValuesObject[];
 
 export type FormValue = FormValuesObject | FormValueList | FormValueSimple;
 
+export type FormErrors<T extends FormValuesObject> = Partial<
+  Record<keyof T, string>
+>;
+
 export type FormHelpers<T extends FormValuesObject> = {
   values: T;
   // todo: likely remove once other setter are available
   onValueChanges: (val: T | ((prev: T) => T)) => void;
+  // Live-derived from the current values on every render; UIs that only want
+  // errors after a submit attempt gate on `submitAttempted`.
+  errors: FormErrors<T>;
+  isValid: boolean;
+  submitAttempted: boolean;
+  submit: () => void;
 };

package/src/forms/useFormState/useFormState.stories.tsx

@@ -0,0 +1,196 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useFormState } from './useFormState';
+import { allOf, matches, minLength, notEmpty } from '../validators/validators';
+import { Field } from '../../components/Forms/Field';
+import { Input } from '../../components/Forms/Input';
+import { Button } from '../../components/Forms/Button';
+import { SingleSelect } from '../../components/Forms/Select';
+
+const meta: Meta = {
+  title: 'Forms/useFormState',
+};
+
+export default meta;
+type Story = StoryObj;
+
+type SignupFormValues = {
+  email: string | undefined;
+  displayName: string | undefined;
+  role: string | null;
+  inviteCode: string | undefined;
+};
+
+// What onSubmit receives: SignupFormValues with each constrained field
+// narrowed by its validator's refinement. `email`/`displayName` lose
+// `undefined`, `role` loses `null`; `inviteCode` is unconstrained and keeps
+// its full type. The `setSubmitted(vals)` call below only compiles because
+// the hook actually delivers this narrowed type — the story doubles as a
+// compile-time proof of the headline feature.
+type SubmittedValues = {
+  email: string;
+  displayName: string;
+  role: string;
+  inviteCode: string | undefined;
+};
+
+const ROLE_OPTIONS = [
+  { value: 'engineer', label: 'Engineer' },
+  { value: 'designer', label: 'Designer' },
+  { value: 'manager', label: 'Manager' },
+];
+
+const SignupDemo = () => {
+  const [submitted, setSubmitted] = useState<SubmittedValues | null>(null);
+
+  const { values, onValueChanges, errors, submitAttempted, submit } =
+    useFormState({
+      initialValues: {
+        email: undefined,
+        displayName: undefined,
+        role: null,
+        inviteCode: undefined,
+      } as SignupFormValues,
+      constraints: {
+        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        displayName: allOf(notEmpty('displayName'), minLength('displayName', 3)),
+        role: notEmpty('role'),
+      },
+      onSubmit: (vals) => setSubmitted(vals),
+    });
+
+  const shownErrors = submitAttempted ? errors : {};
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <Field label="Email" error={shownErrors.email} htmlFor="signup-email">
+        <Input
+          id="signup-email"
+          type="email"
+          value={values.email ?? ''}
+          onChange={(e) => {
+            const email = e.target.value;
+            onValueChanges((prev) => ({ ...prev, email }));
+          }}
+          placeholder="you@example.com"
+        />
+      </Field>
+
+      <Field
+        label="Display name"
+        hint="At least 3 characters"
+        error={shownErrors.displayName}
+        htmlFor="signup-display-name"
+      >
+        <Input
+          id="signup-display-name"
+          value={values.displayName ?? ''}
+          onChange={(e) => {
+            const displayName = e.target.value;
+            onValueChanges((prev) => ({ ...prev, displayName }));
+          }}
+        />
+      </Field>
+
+      <Field label="Role" error={shownErrors.role}>
+        <SingleSelect
+          options={ROLE_OPTIONS}
+          value={values.role}
+          onChange={(role) => onValueChanges((prev) => ({ ...prev, role }))}
+          placeholder="Pick a role"
+          ariaLabel="Role"
+        />
+      </Field>
+
+      <Field label="Invite code" hint="Optional — no constraint on this field">
+        <Input
+          id="signup-invite-code"
+          value={values.inviteCode ?? ''}
+          onChange={(e) => {
+            const inviteCode = e.target.value;
+            onValueChanges((prev) => ({ ...prev, inviteCode }));
+          }}
+        />
+      </Field>
+
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+        <Button type="submit" variant="primary">
+          Sign up
+        </Button>
+        {submitAttempted && Object.keys(errors).length > 0 && (
+          <span style={{ color: 'var(--ui-danger, #c33)', fontSize: 13 }}>
+            Fix the highlighted fields
+          </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 SignupForm: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <SignupDemo />
+    </div>
+  ),
+};
+
+const LiveValidityDemo = () => {
+  const { values, onValueChanges, errors, isValid } = useFormState({
+    initialValues: { nickname: undefined } as { nickname: string | undefined },
+    constraints: {
+      nickname: allOf(notEmpty('nickname'), minLength('nickname', 3)),
+    },
+  });
+
+  return (
+    <div style={{ maxWidth: 420, display: 'grid', gap: 12 }}>
+      <Field
+        label="Nickname"
+        hint="Errors here are live — not gated on a submit attempt"
+        error={errors.nickname}
+        htmlFor="live-nickname"
+      >
+        <Input
+          id="live-nickname"
+          value={values.nickname ?? ''}
+          onChange={(e) => {
+            const nickname = e.target.value;
+            onValueChanges((prev) => ({ ...prev, nickname }));
+          }}
+        />
+      </Field>
+      <div style={{ fontSize: 13 }}>
+        isValid: <strong>{String(isValid)}</strong>
+      </div>
+    </div>
+  );
+};
+
+export const LiveValidity: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <LiveValidityDemo />
+    </div>
+  ),
+};

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

@@ -0,0 +1,209 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { useFormState } from './useFormState';
+import { allOf, matches, min, minLength, notEmpty } from '../validators/validators';
+import type { Refine, Validations } from '../validations/types';
+import type { Path, ValueAt } from '../path/types';
+
+// These tests exercise the headline feature end-to-end at the hook boundary:
+// the type `onSubmit` receives must be the *refined* form type. The two
+// call-site shapes under test:
+//   1. inline constraints — no ceremony at all; the hook's `const V` type
+//      parameter preserves each validator's Refinement marker
+//   2. pre-built constraints — `as const satisfies Validations<T>` outside
+//      the call
+
+describe('useFormState onSubmit narrowing — inline constraints', () => {
+  it('narrows a refined field and passes others through, with no call-site ceremony', () => {
+    useFormState({
+      initialValues: {
+        a: undefined as string | undefined,
+        b: 0,
+        c: null as string | null,
+      },
+      constraints: {
+        a: notEmpty('a'),
+        c: notEmpty('c'),
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          a: string;
+          b: number;
+          c: string;
+        }>();
+      },
+    });
+  });
+
+  it('bare inline validator functions narrow nothing', () => {
+    useFormState({
+      initialValues: { a: undefined as string | undefined },
+      constraints: {
+        a: (val) => (val ? null : 'required'),
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{ a: string | undefined }>();
+      },
+    });
+  });
+
+  it('without constraints, onSubmit receives the unrefined form type', () => {
+    useFormState({
+      initialValues: { a: undefined as string | undefined, b: 0 },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          a: string | undefined;
+          b: number;
+        }>();
+      },
+    });
+  });
+
+  it('rejects constraints for keys not in the form type', () => {
+    useFormState({
+      initialValues: { a: '' },
+      constraints: {
+        // @ts-expect-error 'nope' is not a field of the form
+        nope: notEmpty('nope'),
+      },
+    });
+  });
+
+  it('rejects a validator whose input is incompatible with the field', () => {
+    useFormState({
+      initialValues: { a: 0 },
+      constraints: {
+        // @ts-expect-error minLength validates strings, `a` is a number
+        a: minLength('a', 3),
+      },
+    });
+  });
+});
+
+describe('useFormState onSubmit narrowing — pre-built constraints', () => {
+  type FormType = {
+    email: string | undefined;
+    nickname: string | undefined;
+  };
+
+  it('preserves refinements from an `as const satisfies` constraints object', () => {
+    const constraints = {
+      email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+    } as const satisfies Validations<FormType>;
+
+    useFormState({
+      initialValues: { email: undefined, nickname: undefined } as FormType,
+      constraints,
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          email: string;
+          nickname: string | undefined;
+        }>();
+      },
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The recursion probe. Prior explorations of this design narrowed fine on
+// trivial examples but hit TS recursion limits on realistic form state. This
+// form type is deliberately chunky — ~30 leaf fields, 3 levels of object
+// nesting, lists of objects with nested objects inside. If the machinery
+// scales, this file typechecks; if it regresses, tsc fails here first.
+// ---------------------------------------------------------------------------
+
+type UsAddress = {
+  line1: string | undefined;
+  line2: string | undefined;
+  city: string | undefined;
+  state: string | undefined;
+  postalCode: string | undefined;
+};
+
+type InsuranceQuoteForm = {
+  firstName: string | undefined;
+  lastName: string | undefined;
+  email: string | undefined;
+  phone: string | undefined;
+  dateOfBirth: string | undefined;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress;
+  employer: string | null;
+  jobTitle: string | null;
+  yearsEmployed: number | null;
+  annualIncomeUsd: number | null;
+  coverageType: string | undefined;
+  deductibleUsd: number | undefined;
+  startDate: string | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    licenseNumber: string | undefined;
+    licenseState: string | undefined;
+    incidents: Array<{
+      date: string | undefined;
+      kind: string | undefined;
+      claimAmountUsd: number | null;
+    }>;
+  }>;
+  vehicles: Array<{
+    vin: string | undefined;
+    year: number | undefined;
+    make: string | undefined;
+    model: string | undefined;
+    primaryDriverName: string | undefined;
+    garagingAddress: UsAddress;
+  }>;
+  discountCodes: string[];
+  referralSource: string | null;
+  notes: string | undefined;
+};
+
+describe('useFormState narrowing at realistic scale', () => {
+  it('narrows constrained fields on a ~30-field, 3-level-deep form', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        firstName: notEmpty('firstName'),
+        lastName: notEmpty('lastName'),
+        email: allOf(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),
+        coverageType: notEmpty('coverageType'),
+        startDate: notEmpty('startDate'),
+        referralSource: notEmpty('referralSource'),
+        notes: minLength('notes', 10),
+      },
+      onSubmit: (values) => {
+        // Refined: notEmpty strips null/undefined/'' from the union.
+        expectTypeOf(values.firstName).toEqualTypeOf<string>();
+        expectTypeOf(values.email).toEqualTypeOf<string>();
+        expectTypeOf(values.referralSource).toEqualTypeOf<string>();
+        // Constrained but non-refining validators leave the type alone.
+        expectTypeOf(values.phone).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.annualIncomeUsd).toEqualTypeOf<number | null>();
+        expectTypeOf(values.notes).toEqualTypeOf<string | undefined>();
+        // Unconstrained fields — including all nested structure — untouched.
+        expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
+        expectTypeOf(values.drivers).toEqualTypeOf<
+          InsuranceQuoteForm['drivers']
+        >();
+        expectTypeOf(values.vehicles[0].garagingAddress).toEqualTypeOf<UsAddress>();
+      },
+    });
+  });
+
+  it('Path<T> still expands on the realistic form type', () => {
+    // Path is the most recursion-prone type in forms/ — its union grows with
+    // every key at every depth. Probe it with deep representative paths
+    // rather than equality on the (huge) full union.
+    type P = Path<InsuranceQuoteForm>;
+    expectTypeOf<['homeAddress', 'city']>().toMatchTypeOf<P>();
+    expectTypeOf<['drivers', number, 'incidents', number, 'claimAmountUsd']>().toMatchTypeOf<P>();
+    expectTypeOf<['vehicles', number, 'garagingAddress', 'postalCode']>().toMatchTypeOf<P>();
+
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['drivers', number, 'incidents', number, 'claimAmountUsd']>
+    >().toEqualTypeOf<number | null>();
+  });
+});