@structuralists/scaffolding 0.4.2 → 0.5.0

package/package.json

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

package/src/forms/CLAUDE.md

@@ -35,24 +35,36 @@ function composition.
 
 ```ts
 const constraints = perField({
-  a: (val: string | undefined) => !val ? "'a' cannot be empty" : null,
-}) as const satisfies Validations<FormType>;
+  a: (val: string | undefined) => (!val ? "'a' cannot be empty" : null),
+}) satisfies Validations<FormType>;
 ```
 
 `perField` is the entry point that produces a `Validations<FormType>`-shaped
 value while preserving the precise types of each individual validator.
 
-### Why `as const satisfies` (both required)
-
-- **`as const`** freezes the object's literal type — including each
-  validator's specific function type and any refinement markers attached
-  to it. Without `as const`, function types widen, markers are lost,
-  `Refine<>` has nothing to walk.
-- **`satisfies Validations<FormType>`** checks shape against `FormType`
-  (every key valid, every validator's input compatible) without widening
-  the inferred type the way an annotation `: Validations<FormType>` would.
-
-The combination = "type-check this shape, but don't lose any precision."
+### The precision-preserving ceremony, by call-site shape
+
+The enemy is widening: if the constraints object's inferred type loses each
+validator's specific function type, the refinement markers are lost and
+`Refine<>` has nothing to walk. What prevents widening depends on where the
+constraints object is written:
+
+- **Inline in the `useFormState` call — no ceremony at all.** The hook's
+  `const V extends Validations<T>` type parameter freezes the literal type,
+  and the generic bound shape-checks against the form type. This is the
+  everyday path.
+- **Pre-built via `perField` — add `satisfies Validations<FormType>`.**
+  `perField`'s own `const` type parameter plays the freezing role (`as const`
+  cannot be applied to a call expression — TS1355), and `satisfies` checks
+  shape against `FormType` (every key valid, every validator's input
+  compatible) without widening the way an annotation
+  `: Validations<FormType>` would.
+- **Pre-built as a bare object literal — `as const satisfies
+  Validations<FormType>`,** both parts required: `as const` freezes,
+  `satisfies` checks.
+
+Never *annotate* a constraints binding (`: Validations<FormType>`) — that is
+the widening failure mode all three patterns exist to avoid.
 
 ## Standard-library validators carry refinements
 
@@ -134,11 +146,22 @@ precision end-to-end. So we wire it up before adding any consumers.
 ## Layout
 
 - `useFormState/` — the hook + the value-model types (`FormValueSimple`,
-  `FormValuesObject`, `FormValueList`).
+  `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
+  onValueChanges, errors, isValid, submitAttempted, submit }`; `errors` is
+  live-derived from current values each render (validators are pure and
+  cheap), `submitAttempted` lets UIs gate error display, and `submit()`
+  performs the one honest cast to `Refine<T, V>` — earned because the
+  validators just passed at runtime.
 - `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
   Will be used for granular setters and for surfacing per-field
   errors/touched state. Coupled to the form value model intentionally.
-- (planned) `validations/` — `perField`, `Validations<T>`, `Refine<T,V>`,
-  `Refinement<>` infra.
-- (planned) `validators/` — the standard-library validators
-  (`notEmpty`, `oneOf`, `matches`, …) each carrying its own refinement.
+- `validations/` — `perField`, `Validations<T>`, `Refine<T,V>`,
+  `Refinement<>` infra. `Validations<T>` accepts bare
+  `(val) => string | null` functions too — they simply narrow nothing.
+- `validators/` — the standard-library validators (`notEmpty`, `minLength`,
+  `matches`, `min`) plus `allOf`, which composes validators on one field and
+  carries the union of the parts' refinements. `allOf` derives its input type
+  as the intersection of the parts' inputs from the const tuple (not a
+  standalone inferred type parameter — that breaks without an outer
+  contextual type, e.g. inside inline constraints). `oneOf` is deferred:
+  exclusion-only markers can't express keep-only narrowing yet.

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>();
+  });
+});

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

@@ -0,0 +1,134 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormState } from './useFormState';
+import { allOf, matches, notEmpty } from '../validators/validators';
+
+type SignupForm = {
+  email: string | undefined;
+  nickname: string | undefined;
+};
+
+const initialValues: SignupForm = { email: undefined, nickname: undefined };
+
+describe('useFormState', () => {
+  test('exposes initial values', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.values).toEqual(initialValues);
+  });
+
+  test('onValueChanges accepts a replacement object', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: 'will' });
+    });
+    expect(result.current.values.email).toBe('a@b.co');
+  });
+
+  test('onValueChanges accepts an updater function', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, nickname: 'will' }));
+    });
+    expect(result.current.values).toEqual({ email: undefined, nickname: 'will' });
+  });
+
+  test('errors are derived live from the current values', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    expect(result.current.isValid).toBe(false);
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    expect(result.current.errors.email).toBeUndefined();
+    expect(result.current.isValid).toBe(true);
+  });
+
+  test('fields without constraints never produce errors', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+      }),
+    );
+    expect(result.current.errors.nickname).toBeUndefined();
+  });
+
+  test('a form without constraints is always valid', () => {
+    const { result } = renderHook(() => useFormState({ initialValues }));
+    expect(result.current.isValid).toBe(true);
+    expect(result.current.errors).toEqual({});
+  });
+
+  test('submit on an invalid form marks the attempt and skips onSubmit', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+    expect(result.current.submitAttempted).toBe(false);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  test('submit on a valid form calls onSubmit with the current values', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: {
+          email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: undefined });
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'a@b.co',
+      nickname: undefined,
+    });
+  });
+
+  test('a failed submit followed by a fix allows the next submit through', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: { email: notEmpty('email') },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+});

package/src/forms/useFormState/useFormState.ts

@@ -1,14 +1,50 @@
 import { useState } from 'react';
-import type { FormHelpers, FormValuesObject } from './types';
+import type { FormErrors, FormHelpers, FormValuesObject } from './types';
+import type { Refine, Validations } from '../validations/types';
 
-type Args<T extends FormValuesObject> = {
+// `const V` freezes the inferred type of an inline `constraints` object —
+// each validator's precise type and Refinement marker survive without any
+// `as const` at the call site. Constraint objects built outside the call
+// still need `as const satisfies Validations<T>` (see src/forms/CLAUDE.md).
+type Args<T extends FormValuesObject, V extends Validations<T>> = {
   initialValues: T;
+  constraints?: V;
+  onSubmit?: (values: Refine<T, V>) => void;
 };
 
-export const useFormState = <T extends FormValuesObject>(args: Args<T>): FormHelpers<T> => {
-  const { initialValues } = args;
+export const useFormState = <
+  T extends FormValuesObject,
+  const V extends Validations<T> = Validations<T>,
+>(
+  args: Args<T, V>,
+): FormHelpers<T> => {
+  const { initialValues, constraints, onSubmit } = args;
 
   const [values, onValueChanges] = useState<T>(initialValues);
+  const [submitAttempted, setSubmitAttempted] = useState(false);
 
-  return { values, onValueChanges };
+  const errors: FormErrors<T> = {};
+  if (constraints) {
+    for (const key of Object.keys(constraints) as (keyof T & string)[]) {
+      // Field type and validator input are correlated per key, but TS can't
+      // track that through the union of keys — widen the input to unknown.
+      const validator = constraints[key] as
+        | ((val: unknown) => string | null)
+        | undefined;
+      const error = validator?.(values[key]);
+      if (error != null) errors[key] = error;
+    }
+  }
+
+  const isValid = Object.keys(errors).length === 0;
+
+  const submit = () => {
+    setSubmitAttempted(true);
+    if (!isValid) return;
+    // Every constrained field's validator just passed at runtime — exactly
+    // the guarantee Refine<T, V> encodes.
+    onSubmit?.(values as Refine<T, V>);
+  };
+
+  return { values, onValueChanges, errors, isValid, submitAttempted, submit };
 };

package/src/forms/validations/perField.ts

@@ -0,0 +1,11 @@
+// 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>,
+>(
+  validations: V,
+): V => validations;

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

@@ -1,5 +1,7 @@
 import { describe, it, expectTypeOf } from 'vitest';
-import type { Refinement, Validator } from './types';
+import { perField } from './perField';
+import { allOf, matches, minLength, notEmpty } from '../validators/validators';
+import type { Refine, Refinement, Validations, Validator } from './types';
 
 describe('Validator<Input, Excluded>', () => {
   it('preserves the input type as the call parameter', () => {
@@ -24,3 +26,74 @@ describe('Validator<Input, Excluded>', () => {
     expectTypeOf<Extracted>().toBeNever();
   });
 });
+
+type FormType = {
+  a: string | undefined;
+  b: number;
+  c: string | null;
+};
+
+describe('Refine<T, V>', () => {
+  it('narrows fields whose validator carries a refinement', () => {
+    const constraints = {
+      a: notEmpty('a'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string | null;
+    }>();
+  });
+
+  it('preserves precision through perField without as const', () => {
+    const constraints = perField({
+      a: notEmpty('a'),
+      c: notEmpty('c'),
+    }) satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string;
+    }>();
+  });
+
+  it('bare validator functions narrow nothing', () => {
+    const constraints = {
+      a: (val: string | undefined) => (val ? null : 'required'),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('a constraints object widened by annotation refines nothing', () => {
+    // Annotating with `: Validations<FormType>` (instead of `satisfies`)
+    // widens every validator to a bare function — markers are lost. This is
+    // the failure mode the `as const satisfies` / const-generic patterns exist
+    // to prevent.
+    const constraints: Validations<FormType> = { a: notEmpty('a') };
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('allOf carries the union of its parts’ refinements', () => {
+    const constraints = {
+      a: allOf(notEmpty('a'), minLength('a', 3), matches('a', /^\S+$/, 'no spaces')),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('an empty constraints object leaves the form type unchanged', () => {
+    const constraints = {} as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+});

package/src/forms/validations/types.ts

@@ -1,3 +1,5 @@
+import type { 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
 // (not optional) so validators can't accidentally drop the marker, and so
@@ -13,3 +15,24 @@ export type Refinement<Excluded = never> = {
 // validates at runtime; it just doesn't shrink the field's submit type).
 export type Validator<Input, Excluded = never> =
   ((val: Input) => string | null) & Refinement<Excluded>;
+
+// The constraint for a per-field validation map. Deliberately does NOT demand
+// the `Refinement` marker: a bare `(val) => string | null` is a legal
+// constraint that narrows nothing. Markers on standard-library validators
+// ride along in the *inferred* type of a concrete constraints object and are
+// recovered structurally by `Refine<>`.
+export type Validations<T extends FormValuesObject> = {
+  readonly [K in keyof T]?: (val: T[K]) => string | null;
+};
+
+// Applies each field's validator marker to the form type: the submit-time
+// type. Fields whose validator carries `Refinement<X>` become
+// `Exclude<T[K], X>`; 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>> = {
+  [K in keyof T]: K extends keyof V
+    ? V[K] extends Refinement<infer Excluded>
+      ? Exclude<T[K], Excluded>
+      : T[K]
+    : T[K];
+};

package/src/forms/validators/validators.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from 'bun:test';
+import { allOf, matches, min, minLength, notEmpty } from './validators';
+
+describe('notEmpty', () => {
+  const validator = notEmpty('email');
+
+  test('rejects null, undefined, and the empty string', () => {
+    expect(validator(null)).toBe("'email' cannot be empty");
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('')).toBe("'email' cannot be empty");
+  });
+
+  test('passes any other value', () => {
+    expect(validator('a@b.co')).toBeNull();
+    expect(validator(0)).toBeNull();
+    expect(validator(' ')).toBeNull();
+  });
+});
+
+describe('minLength', () => {
+  const validator = minLength('nickname', 3);
+
+  test('rejects strings shorter than the minimum', () => {
+    expect(validator('ab')).toBe("'nickname' must be at least 3 characters");
+  });
+
+  test('passes strings at or above the minimum', () => {
+    expect(validator('abc')).toBeNull();
+    expect(validator('abcd')).toBeNull();
+  });
+
+  test('passes nullish and empty values — requiredness is notEmpty’s job', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('matches', () => {
+  const validator = matches('email', /@/, 'a valid email');
+
+  test('rejects values that fail the pattern', () => {
+    expect(validator('not-an-email')).toBe("'email' must be a valid email");
+  });
+
+  test('passes values matching the pattern', () => {
+    expect(validator('a@b.co')).toBeNull();
+  });
+
+  test('passes nullish and empty values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+    expect(validator('')).toBeNull();
+  });
+});
+
+describe('min', () => {
+  const validator = min('age', 18);
+
+  test('rejects numbers below the minimum', () => {
+    expect(validator(17)).toBe("'age' must be at least 18");
+  });
+
+  test('passes numbers at or above the minimum', () => {
+    expect(validator(18)).toBeNull();
+    expect(validator(99)).toBeNull();
+  });
+
+  test('passes nullish values', () => {
+    expect(validator(null)).toBeNull();
+    expect(validator(undefined)).toBeNull();
+  });
+});
+
+describe('allOf', () => {
+  const validator = allOf(
+    notEmpty('email'),
+    minLength('email', 6),
+    matches('email', /@/, 'a valid email'),
+  );
+
+  test('returns the first failing part’s error', () => {
+    expect(validator(undefined)).toBe("'email' cannot be empty");
+    expect(validator('a@b')).toBe("'email' must be at least 6 characters");
+    expect(validator('abcdefg')).toBe("'email' must be a valid email");
+  });
+
+  test('passes when every part passes', () => {
+    expect(validator('a@b.com')).toBeNull();
+  });
+
+  test('accepts bare validator functions alongside marked ones', () => {
+    const noAdmin = (val: string | null | undefined) =>
+      val === 'admin' ? 'reserved' : null;
+    const composed = allOf(notEmpty('name'), noAdmin);
+    expect(composed('admin')).toBe('reserved');
+    expect(composed('will')).toBeNull();
+  });
+});

package/src/forms/validators/validators.ts

@@ -0,0 +1,95 @@
+import type { Refinement, Validator } from '../validations/types';
+
+// Standard-library validators. Each one declares its refinement explicitly —
+// `Validator<Input, Excluded>` — even when it narrows nothing (`never`).
+// The marker is attached with `Object.assign(fn, {} as Refinement<X>)`: a
+// pure type-level tag, never read at runtime.
+
+// Rules out null, undefined, and the empty string. The only refining
+// validator in the baseline set: submit-time type becomes
+// `Exclude<FieldType, null | undefined | ''>`.
+export const notEmpty = (
+  fieldName: string,
+): Validator<unknown, null | undefined | ''> =>
+  Object.assign(
+    (val: unknown) =>
+      val == null || val === '' ? `'${fieldName}' cannot be empty` : null,
+    {} as Refinement<null | undefined | ''>,
+  );
+
+// Minimum string length. Nullish and empty values pass — requiredness is
+// notEmpty's job; compose via allOf. Narrows nothing: TypeScript has no type
+// for "string of at least n characters".
+export const minLength = (
+  fieldName: string,
+  min: number,
+): Validator<string | null | undefined> =>
+  Object.assign(
+    (val: string | null | undefined) =>
+      val != null && val !== '' && val.length < min
+        ? `'${fieldName}' must be at least ${min} characters`
+        : null,
+    {} as Refinement,
+  );
+
+// Regex test. Nullish and empty values pass (compose with notEmpty for
+// requiredness). Narrows nothing.
+export const matches = (
+  fieldName: string,
+  pattern: RegExp,
+  description: string,
+): Validator<string | null | undefined> =>
+  Object.assign(
+    (val: string | null | undefined) =>
+      val != null && val !== '' && !pattern.test(val)
+        ? `'${fieldName}' must be ${description}`
+        : null,
+    {} as Refinement,
+  );
+
+// Minimum numeric value. Nullish passes. Narrows nothing.
+export const min = (
+  fieldName: string,
+  minimum: number,
+): Validator<number | null | undefined> =>
+  Object.assign(
+    (val: number | null | undefined) =>
+      val != null && val < minimum
+        ? `'${fieldName}' must be at least ${minimum}`
+        : null,
+    {} as Refinement,
+  );
+
+type ExcludedOf<V> = V extends Refinement<infer Excluded> ? Excluded : never;
+
+// The composed input is the *intersection* of the parts' inputs: a value the
+// composite accepts must be acceptable to every part. Inferring `I` from the
+// union of function types puts it in contravariant position, which is what
+// makes TS produce the intersection. Computing it this way — rather than as
+// a standalone `Input` type parameter inferred from the arguments — matters:
+// a separate parameter resolves from whichever argument TS visits first
+// (e.g. `unknown` from notEmpty) and then rejects narrower siblings when the
+// call has no outer contextual type, as inside an inline constraints object.
+type InputOf<Validators extends readonly ((val: never) => string | null)[]> =
+  Validators[number] extends (val: infer I) => string | null ? I : never;
+
+// Composes validators on one field: first error wins. The refinement is the
+// union of the parts' refinements — running all of them earns all of their
+// narrowings. `const Validators` keeps each member's precise type so
+// `ExcludedOf` can extract markers; bare functions contribute `never`.
+export const allOf = <
+  const Validators extends readonly ((val: never) => string | null)[],
+>(
+  ...validators: Validators
+): Validator<InputOf<Validators>, ExcludedOf<Validators[number]>> =>
+  Object.assign(
+    (val: InputOf<Validators>) => {
+      for (const validator of validators) {
+        // Safe: each part's declared input is a supertype of the intersection.
+        const error = (validator as (v: unknown) => string | null)(val);
+        if (error != null) return error;
+      }
+      return null;
+    },
+    {} as Refinement<ExcludedOf<Validators[number]>>,
+  );