npm - @structuralists/scaffolding - Versions diffs - 0.9.0 → 0.10.1 - Mend

@structuralists/scaffolding 0.9.0 → 0.10.1

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

Files changed (18) hide show

package/package.json +1 -1
package/src/forms/CLAUDE.md +65 -14
package/src/forms/plan.md +23 -7
package/src/forms/useFormState/FormDebugger.tsx +2 -1
package/src/forms/useFormState/deriveErrors.test.ts +76 -0
package/src/forms/useFormState/deriveErrors.ts +35 -0
package/src/forms/useFormState/errorAt.test.ts +54 -0
package/src/forms/useFormState/errorAt.ts +27 -0
package/src/forms/useFormState/types.ts +17 -6
package/src/forms/useFormState/useFormDebugger.test.tsx +57 -0
package/src/forms/useFormState/useFormDebugger.ts +38 -0
package/src/forms/useFormState/useFormState.stories.tsx +29 -9
package/src/forms/useFormState/useFormState.test-d.ts +25 -0
package/src/forms/useFormState/useFormState.test.tsx +25 -10
package/src/forms/useFormState/useFormState.ts +20 -53
package/src/forms/useFormState/useFormSubmit.test.tsx +86 -0
package/src/forms/useFormState/useFormSubmit.ts +38 -0
package/src/forms/validations/walk.ts +6 -4

package/package.json CHANGED Viewed

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

package/src/forms/CLAUDE.md CHANGED Viewed

@@ -168,6 +168,30 @@ useFormState({
 });
 ```
+## The error model
+Validation failures surface as a structured list, not a keyed record:
+```ts
+type FormError<T>  = { path: Path<T>; error: string }; // single-key paths on the flat grammar
+type FormErrors<T> = readonly FormError<T>[];          // isValid === (errors.length === 0)
+```
+Read one field's message with the typed accessor, never by hand-assembled
+keys — serialized path strings (`'drivers.0.name'`) are deliberately not
+exposed:
+```ts
+errorAt(errors, ['email']); // string | undefined
+```
+`errorAt` (useFormState/errorAt.ts) matches by exact structural step
+equality (no prefix matching); with first-error-wins validation there is at
+most one entry per path, and if collect-all ever lands the first entry stays
+the one shown. The path-addressed model is what the recursive grammar
+(errors just carry longer paths) and `getFormFieldPropsAt`'s `errorMessage`
+build on.
 ## Union policy — what form state may hold
 The path machinery is load-bearing (structured `{path, error}[]` errors and
@@ -270,19 +294,45 @@ precision end-to-end. So we wire it up before adding any consumers.
 - `useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`;
-  `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. `Debugger` is a per-instance
-  dev-time overlay (fixed trigger, bottom-right, portaled to `<body>`) that
-  opens a live `JsonTable` view of the form's internal state. Plumbing: the
-  hook publishes a `FormDebugSnapshot` into a tiny `snapshotStore` after
-  every commit; only an *open* debugger window subscribes
-  (`useSyncExternalStore`), so an unused Debugger costs ~nothing. The
-  component is created once per hook instance (lazy ref) — its identity must
-  stay stable across renders or it would remount on every keystroke.
-  `inspectable.ts` converts arrays/Sets to shapes `JsonTable` can render.
+  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`.
+  `useFormState.ts` itself is deliberately **plumbing only**: it holds the
+  values `useState` (a bare `useState` today; granular path-based setters
+  are what would earn values state a module of its own), links up the
+  modules below, and recomposes their outputs into `FormHelpers<T>`. Each
+  slice lives in its own file so it is independently comprehensible and
+  unit-testable at its own boundary:
+  - `types.ts` — the value model, the union-policy gate
+    (`UnionPolicyCheck` and friends), the `FormError`/`FormErrors` model,
+    `FormDebugSnapshot`, `FormHelpers`.
+  - `deriveErrors.ts` — `deriveFormErrors(values, constraints)`, the pure
+    (React-free) derivation of the structured `FormErrors<T>` list (see
+    "The error model"), re-run every render (validators are pure and
+    cheap); `isValid` is its emptiness, derived inline in the hook. Its
+    loop delegates per-entry semantics to `validations/walk.ts` and
+    carries two documented honest widenings: the `Object.keys` cast, and
+    `failure.path as Path<T>` — `[key]` is a valid single-key `Path<T>`,
+    but TS cannot compute `Path<T>` for an unresolved generic `T` to see
+    the correlation. It also hosts the cast-free `FlatConstraintEntry`
+    assignment that polices grammar growth (see the `validations/` bullet).
+  - `errorAt.ts` — the typed error lookup.
+  - `useFormSubmit.ts` — submit orchestration: owns `submitAttempted`
+    (lets UIs gate error display) and the validity gate in front of
+    `onSubmit`; its `submit()` performs the one honest *refinement* cast
+    to `Refine<T, V>` — earned because the validators just passed at
+    runtime. `V` is not inferable from `onSubmit`'s parameter position,
+    so `useFormState` applies `<T, V>` explicitly.
+  - `useFormDebugger.ts` — debugger plumbing: creates one `snapshotStore`
+    + one Debugger component per hook instance (lazy ref — the component's
+    identity must stay stable across renders or it would remount, and lose
+    its open/closed state, on every keystroke) and publishes the
+    `FormDebugSnapshot` after every commit.
+  - `FormDebugger.tsx` / `snapshotStore.ts` / `inspectable.ts` — the
+    `Debugger` itself: a per-instance dev-time overlay (fixed trigger,
+    bottom-right, portaled to `<body>`) that opens a live `JsonTable` view
+    of the form's internal state. Only an *open* debugger window
+    subscribes (`useSyncExternalStore`), so an unused Debugger costs
+    ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
+    can render.
 - `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.
@@ -294,7 +344,8 @@ precision end-to-end. So we wire it up before adding any consumers.
   hook delegates to (`validateEntry`). `Validations<T>` accepts bare
   `(val) => string | null` functions too — they simply narrow nothing.
   The walk's entry type (`FlatConstraintEntry`) is how the compiler polices
-  the hook's error loop: `constraints[key]` is *assigned* to it, never cast,
+  the error loop in `useFormState/deriveErrors.ts`: `constraints[key]` is
+  *assigned* to it, never cast,
   so a grammar form the walk doesn't understand (a nested spec, an `each`)
   is a compile error at the assignment — a cast there would silently accept
   new grammar and misinterpret it at runtime (e.g. call an array as a

package/src/forms/plan.md CHANGED Viewed

@@ -22,9 +22,15 @@ TS wall can't strand finished work behind it.
 3. **Error-model swap** to `{path, error}[]` on the *flat* baseline (paths
    are single-key paths). Doesn't depend on nested constraints; hard
    prerequisite for item 6; makes phases 2–3 runtime-plumbing-free.
-   ← *current*
+   ✅ *done* — `FormError<T>`/`FormErrors<T>` (`{ path: Path<T>; error }[]`
+   in useFormState/types.ts), `isValid` derived from emptiness, and the
+   interim consumer accessor is a standalone `errorAt(errors, path)`
+   (useFormState/errorAt.ts) — the smallest surface that keeps stories
+   readable; item 6 folds the same lookup into `getFormFieldPropsAt`'s
+   `errorMessage`. The Debugger needed no change (`toInspectable`
+   index-keys arrays).
 4. **Item 5 — elements/state split.** Pure churn, no type risk; do it before
-   item 6 so the wrappers land in their final home once.
+   item 6 so the wrappers land in their final home once. ← *current*
 5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
    error model and the split; `Path`/`ValueAt` already validated.
 6. **Type spike, then items 2/3/4** — the recursion risk zone. Throwaway
@@ -174,13 +180,19 @@ multi-second check time:
 - post-item-1 soundness fix (per-member-sound `MemberExcludes` in the array
   arm and `allOf`, plus its probes): check 0.77 s, 107,612 instantiations,
   48,507 types (+0.8%)
+- pre-step-3 HEAD (union policy + validator arrays merged, PRs #17/#18):
+  check 0.78 s, 108,978 instantiations, 48,678 types
+- post-step-3 (error-model swap: `Path<T>`-typed `FormError`, `errorAt`,
+  plus probes): check 0.79 s, 113,724 instantiations, 52,294 types
+  (+4.4% instantiations over pre-step-3 HEAD)
 ## 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,
+  ✅ *Landed with working-order step 3* (on the flat baseline, single-key
+  paths). Decided: errors become a plain list of structured entries,
   ```ts
   type FormError<T> = { path: Path<T>; error: string };
@@ -195,8 +207,11 @@ multi-second check time:
   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.
+  accessor, never through hand-assembled keys. ✅ *Decided and landed with
+  step 3*: a standalone `errorAt(errors, path)` (useFormState/errorAt.ts) —
+  structural step-equality lookup, first entry wins. Chosen over a
+  cursor-based lookup as the smallest surface that keeps stories readable
+  on the flat grammar; item 6's `errorMessage` reuses it internally.
 ## Phases
@@ -215,8 +230,9 @@ tests, story updates where visible, probe ratchet.
    *single* constraints (`cond ? v1 : v2`) sound too (union of per-branch
    refinements, pinned in `validations/types.test-d.ts`).
 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).
+   ratchet matters most here. (The `{path, error}[]` error model already
+   landed in working-order step 3 — nested errors just carry longer paths;
+   no error plumbing changes in this phase.)
 3. **List `each` specs.** Runtime walks every element; error paths carry the
    numeric step (`['drivers', 3, 'name']`). Refined element type flows
    through `Array<...>`.

package/src/forms/useFormState/FormDebugger.tsx CHANGED Viewed

@@ -16,7 +16,8 @@ export type FormDebuggerProps = {
 export type FormDebuggerComponent = (props: FormDebuggerProps) => ReactElement;
 // Builds the per-hook-instance Debugger component. Called once per
-// `useFormState` instance (from a lazy ref) so the returned component's
+// `useFormState` instance (from `useFormDebugger`'s lazy ref) so the
+// returned component's
 // identity is stable across renders — a component recreated each render
 // would remount, and lose its open/closed state, on every keystroke.
 export const createFormDebugger = <T extends FormValuesObject>(

package/src/forms/useFormState/deriveErrors.test.ts ADDED Viewed

@@ -0,0 +1,76 @@
+import { describe, test, expect } from 'bun:test';
+import { deriveFormErrors } from './deriveErrors';
+import { matches, notEmpty } from '../validators/validators';
+// Direct, React-free tests of the pure derivation: values + constraints in,
+// structured `{ path, error }[]` out. Hook-level behavior (live re-derivation
+// across renders, submit gating) stays in useFormState.test.tsx.
+type SignupForm = {
+  email: string | undefined;
+  nickname: string | undefined;
+};
+const emptyForm: SignupForm = { email: undefined, nickname: undefined };
+describe('deriveFormErrors', () => {
+  test('no constraints yields no errors', () => {
+    expect(deriveFormErrors(emptyForm, undefined)).toEqual([]);
+  });
+  test('an empty constraints object yields no errors', () => {
+    expect(deriveFormErrors(emptyForm, {})).toEqual([]);
+  });
+  test('a failing field contributes one path-addressed entry', () => {
+    const errors = deriveFormErrors(emptyForm, { email: notEmpty('email') });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+  });
+  test('a passing field contributes nothing', () => {
+    const errors = deriveFormErrors(
+      { email: 'a@b.co', nickname: undefined },
+      { email: notEmpty('email') },
+    );
+    expect(errors).toEqual([]);
+  });
+  test('every failing constrained field gets its own entry', () => {
+    const errors = deriveFormErrors(emptyForm, {
+      email: notEmpty('email'),
+      nickname: notEmpty('nickname'),
+    });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+      { path: ['nickname'], error: "'nickname' cannot be empty" },
+    ]);
+  });
+  test('a validator array runs in order with first-error-wins', () => {
+    const constraints = {
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+    };
+    expect(deriveFormErrors(emptyForm, constraints)).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    expect(
+      deriveFormErrors({ email: 'nope', nickname: undefined }, constraints),
+    ).toEqual([{ path: ['email'], error: "'email' must be a valid email" }]);
+    expect(
+      deriveFormErrors({ email: 'a@b.co', nickname: undefined }, constraints),
+    ).toEqual([]);
+  });
+  test('an empty validator array passes', () => {
+    expect(deriveFormErrors(emptyForm, { email: [] })).toEqual([]);
+  });
+  test('a null constraint entry (possible from untyped JS) is skipped', () => {
+    const constraints = { email: null } as unknown as {
+      email: (val: string | undefined) => string | null;
+    };
+    expect(deriveFormErrors(emptyForm, constraints)).toEqual([]);
+  });
+});

package/src/forms/useFormState/deriveErrors.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import type { Path } from '../path/types';
+import type { Validations } from '../validations/types';
+import { validateEntry } from '../validations/walk';
+import type { FlatConstraintEntry } from '../validations/walk';
+import type { FormError, FormValuesObject } from './types';
+// The pure half of the hook's error model: current values + constraints in,
+// structured `{ path, error }[]` out. Validation is live-derived (validators
+// are pure and cheap), so this runs every render — it must stay free of
+// React and of any per-call state. `isValid` is just this list's emptiness;
+// the hook derives it inline.
+export const deriveFormErrors = <T extends FormValuesObject>(
+  values: T,
+  constraints: Validations<T> | undefined,
+): FormError<T>[] => {
+  const errors: FormError<T>[] = [];
+  if (!constraints) return errors;
+  for (const key of Object.keys(constraints) as (keyof T & string)[]) {
+    // No cast: if the grammar grows a constraint form the walk doesn't
+    // understand, this assignment is the compile error that says so.
+    const entry: FlatConstraintEntry | undefined = constraints[key];
+    if (entry == null) continue;
+    const failure = validateEntry(entry, values[key], [key]);
+    if (failure == null) continue;
+    // The walk returns the address it was handed, and `[key]` — a key of
+    // a constraints object type-checked against T — is a valid single-key
+    // Path<T>. TS can't compute Path<T> for an unresolved generic T, so
+    // the correlation needs the same honest widening as the keys cast
+    // above.
+    errors.push({ path: failure.path as Path<T>, error: failure.error });
+  }
+  return errors;
+};

package/src/forms/useFormState/errorAt.test.ts ADDED Viewed

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'bun:test';
+import { errorAt } from './errorAt';
+import type { FormErrors } from './types';
+// The flat grammar only produces single-key paths today, but errorAt's
+// equality must already be exact over multi-step and numeric-step paths —
+// the recursive grammar (plan phases 2–3) reuses it unchanged.
+type Form = {
+  email: string | undefined;
+  address: { city: string | undefined };
+  tags: Array<{ label: string | undefined }>;
+};
+const errors: FormErrors<Form> = [
+  { path: ['email'], error: "'email' cannot be empty" },
+  { path: ['address', 'city'], error: "'city' cannot be empty" },
+  { path: ['tags', 0, 'label'], error: "'label' cannot be empty" },
+];
+describe('errorAt', () => {
+  test('finds a single-key path', () => {
+    expect(errorAt(errors, ['email'])).toBe("'email' cannot be empty");
+  });
+  test('finds a nested path by exact step equality', () => {
+    expect(errorAt(errors, ['address', 'city'])).toBe(
+      "'city' cannot be empty",
+    );
+  });
+  test('numeric steps participate in equality', () => {
+    expect(errorAt(errors, ['tags', 0, 'label'])).toBe(
+      "'label' cannot be empty",
+    );
+    expect(errorAt(errors, ['tags', 1, 'label'])).toBeUndefined();
+  });
+  test('a prefix of an error path is not a match', () => {
+    expect(errorAt(errors, ['address'])).toBeUndefined();
+    expect(errorAt(errors, ['tags'])).toBeUndefined();
+  });
+  test('returns undefined when the list has no entry for the path', () => {
+    expect(errorAt([], ['email'])).toBeUndefined();
+  });
+  test('first entry wins when a path has several errors', () => {
+    const duplicated: FormErrors<Form> = [
+      { path: ['email'], error: 'first' },
+      { path: ['email'], error: 'second' },
+    ];
+    expect(errorAt(duplicated, ['email'])).toBe('first');
+  });
+});

package/src/forms/useFormState/errorAt.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import type { Path, PathStep } from '../path/types';
+import type { FormErrors, FormValuesObject } from './types';
+// Typed lookup into the structured `{ path, error }[]` error list — the
+// sanctioned way to read one field's error. Path equality is structural:
+// same steps, same order, no prefix matching. With first-error-wins
+// validation there is at most one entry per path today; should collect-all
+// ever land, the first entry stays the one shown.
+export const errorAt = <T extends FormValuesObject>(
+  errors: FormErrors<T>,
+  path: Path<T>,
+): string | undefined => {
+  // Path<T> is always a PathStep tuple; the conditional type just can't
+  // prove it for an unresolved T. Same honest widening as `Cursor.at`.
+  const steps = path as readonly PathStep[];
+  const match = errors.find((candidate) => {
+    const candidateSteps = candidate.path as readonly PathStep[];
+    return (
+      candidateSteps.length === steps.length &&
+      candidateSteps.every((step, index) => step === steps[index])
+    );
+  });
+  return match?.error;
+};

package/src/forms/useFormState/types.ts CHANGED Viewed

@@ -1,6 +1,7 @@
-// Type-only import; FormDebugger.tsx imports value types from this file in
-// turn, but the cycle never exists at runtime.
+// Type-only imports; FormDebugger.tsx and path/types.ts import value types
+// from this file in turn, but the cycles never exist at runtime.
 import type { FormDebuggerComponent } from './FormDebugger';
+import type { Path } from '../path/types';
 export type FormValueSimple = string | number | bigint | boolean | string[] | Set<string> | undefined | null;
@@ -76,11 +77,21 @@ export type UnionPolicyCheck<T> = HasDisallowedUnion<T> extends true
     }
   : unknown;
-export type FormErrors<T extends FormValuesObject> = Partial<
-  Record<keyof T, string>
->;
+// Structured error model: one entry per failing constrained node, addressed
+// by a typed path (single-key paths on the flat grammar; deeper addresses
+// arrive with the recursive grammar). Deliberately a plain list — at form
+// scale a linear scan is fine, and serialized string keys ('drivers.0.name')
+// are never exposed. Read a field's error with `errorAt` (./errorAt.ts),
+// never by hand-assembled keys.
+export type FormError<T extends FormValuesObject> = {
+  readonly path: Path<T>;
+  readonly error: string;
+};
+export type FormErrors<T extends FormValuesObject> = readonly FormError<T>[];
-// What the hook publishes to its Debugger after every commit. Snapshots are
+// What the hook publishes (via `useFormDebugger`) to its Debugger after
+// every commit. Snapshots are
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can
 // rely on reference equality.
 export type FormDebugSnapshot<T extends FormValuesObject> = {

package/src/forms/useFormState/useFormDebugger.test.tsx ADDED Viewed

@@ -0,0 +1,57 @@
+import { afterEach, describe, test, expect } from 'bun:test';
+import { useState } from 'react';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+// The Debugger portals into document.body, so leftovers from a previous
+// test are visible to `screen` queries — clean up explicitly (bun:test has
+// no global afterEach for RTL's auto-cleanup to hook).
+afterEach(cleanup);
+import { useFormDebugger } from './useFormDebugger';
+// The debugger-plumbing boundary in isolation: the hook must hand back a
+// render-stable component wired to the latest published snapshot. The full
+// overlay behavior (open/close, live form wiring) is covered in
+// FormDebugger.test.tsx through useFormState.
+const Host = () => {
+  const [count, setCount] = useState(0);
+  const Debugger = useFormDebugger({
+    snapshot: {
+      values: { count },
+      errors: [],
+      isValid: true,
+      submitAttempted: false,
+    },
+  });
+  return (
+    <div>
+      <button type="button" onClick={() => setCount((prev) => prev + 1)}>
+        inc
+      </button>
+      <Debugger label="dbg" />
+    </div>
+  );
+};
+describe('useFormDebugger', () => {
+  test('returns a Debugger showing the current snapshot', () => {
+    render(<Host />);
+    fireEvent.click(screen.getByRole('button', { name: 'dbg' }));
+    expect(screen.getByText('count')).toBeTruthy();
+    expect(screen.getByText('0')).toBeTruthy();
+  });
+  test('the component identity survives re-renders and shows fresh snapshots', () => {
+    render(<Host />);
+    fireEvent.click(screen.getByRole('button', { name: 'dbg' }));
+    fireEvent.click(screen.getByRole('button', { name: 'inc' }));
+    // The window is still open (a remounted Debugger would have reset to
+    // closed) and reflects the snapshot published after the re-render.
+    expect(screen.getByText('1')).toBeTruthy();
+    expect(screen.queryByText('0')).toBeNull();
+  });
+});

package/src/forms/useFormState/useFormDebugger.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { useEffect, useRef } from 'react';
+import { createFormDebugger } from './FormDebugger';
+import type { FormDebuggerComponent } from './FormDebugger';
+import { createSnapshotStore } from './snapshotStore';
+import type { SnapshotStore } from './snapshotStore';
+import type { FormDebugSnapshot, FormValuesObject } from './types';
+export type UseFormDebuggerArgs<T extends FormValuesObject> = {
+  snapshot: FormDebugSnapshot<T>;
+};
+// Debugger plumbing: one store + one component per hook instance, created
+// lazily on first render. The component's identity must be stable across
+// renders — recreated each render it would remount (and lose its
+// open/closed state) on every keystroke.
+export const useFormDebugger = <T extends FormValuesObject>(
+  args: UseFormDebuggerArgs<T>,
+): FormDebuggerComponent => {
+  const { snapshot } = args;
+  const debugRef = useRef<{
+    store: SnapshotStore<FormDebugSnapshot<T>>;
+    Debugger: FormDebuggerComponent;
+  } | null>(null);
+  if (debugRef.current === null) {
+    const store = createSnapshotStore(snapshot);
+    debugRef.current = { store, Debugger: createFormDebugger(store) };
+  }
+  const { store, Debugger } = debugRef.current;
+  // Publish after every commit. With no debugger window subscribed this is a
+  // field write and an empty notify loop — effectively free.
+  useEffect(() => {
+    store.publish(snapshot);
+  });
+  return Debugger;
+};

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

@@ -2,6 +2,8 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, userEvent, within } from 'storybook/test';
 import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
+import type { FormErrors } from './types';
 import { matches, minLength, notEmpty } from '../validators/validators';
 import { Field } from '../../components/Forms/Field';
 import { Input } from '../../components/Forms/Input';
@@ -62,7 +64,11 @@ const SignupDemo = () => {
       onSubmit: (vals) => setSubmitted(vals),
     });
-  const shownErrors = submitAttempted ? errors : {};
+  // errors is a structured `{ path, error }[]` list; a field's message is
+  // read with the typed `errorAt` accessor, never a hand-assembled key.
+  const shownErrors: FormErrors<SignupFormValues> = submitAttempted
+    ? errors
+    : [];
   return (
     <form
@@ -72,7 +78,11 @@ const SignupDemo = () => {
         submit();
       }}
     >
-      <Field label="Email" error={shownErrors.email} htmlFor="signup-email">
+      <Field
+        label="Email"
+        error={errorAt(shownErrors, ['email'])}
+        htmlFor="signup-email"
+      >
         <Input
           id="signup-email"
           type="email"
@@ -88,7 +98,7 @@ const SignupDemo = () => {
       <Field
         label="Display name"
         hint="At least 3 characters"
-        error={shownErrors.displayName}
+        error={errorAt(shownErrors, ['displayName'])}
         htmlFor="signup-display-name"
       >
         <Input
@@ -101,7 +111,7 @@ const SignupDemo = () => {
         />
       </Field>
-      <Field label="Role" error={shownErrors.role}>
+      <Field label="Role" error={errorAt(shownErrors, ['role'])}>
         <SingleSelect
           options={ROLE_OPTIONS}
           value={values.role}
@@ -126,7 +136,7 @@ const SignupDemo = () => {
         <Button type="submit" variant="primary">
           Sign up
         </Button>
-        {submitAttempted && Object.keys(errors).length > 0 && (
+        {submitAttempted && errors.length > 0 && (
           <span style={{ color: 'var(--ui-danger, #c33)', fontSize: 13 }}>
             Fix the highlighted fields
           </span>
@@ -209,7 +219,7 @@ const LiveValidityDemo = () => {
       <Field
         label="Nickname"
         hint="Errors here are live — not gated on a submit attempt"
-        error={errors.nickname}
+        error={errorAt(errors, ['nickname'])}
         htmlFor="live-nickname"
       >
         <Input
@@ -274,7 +284,9 @@ const DebuggerDemo = () => {
       },
     });
-  const shownErrors = submitAttempted ? errors : {};
+  const shownErrors: FormErrors<DebuggerDemoValues> = submitAttempted
+    ? errors
+    : [];
   return (
     <form
@@ -284,7 +296,11 @@ const DebuggerDemo = () => {
         submit();
       }}
     >
-      <Field label="Email" error={shownErrors.email} htmlFor="debug-email">
+      <Field
+        label="Email"
+        error={errorAt(shownErrors, ['email'])}
+        htmlFor="debug-email"
+      >
         <Input
           id="debug-email"
           type="email"
@@ -297,7 +313,11 @@ const DebuggerDemo = () => {
         />
       </Field>
-      <Field label="Nickname" error={shownErrors.nickname} htmlFor="debug-nickname">
+      <Field
+        label="Nickname"
+        error={errorAt(shownErrors, ['nickname'])}
+        htmlFor="debug-nickname"
+      >
         <Input
           id="debug-nickname"
           value={values.nickname ?? ''}

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

@@ -1,6 +1,8 @@
 import { describe, it, expectTypeOf } from 'vitest';
 import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
 import { allOf, matches, min, minLength, notEmpty } from '../validators/validators';
+import type { FormErrors } from './types';
 import type { Refine, Validations } from '../validations/types';
 import type { Path, ValueAt } from '../path/types';
@@ -400,6 +402,29 @@ describe('useFormState narrowing at realistic scale', () => {
     >().toEqualTypeOf<boolean | undefined>();
   });
+  it('errors are the structured {path, error}[] list, looked up via errorAt', () => {
+    const form = useFormState({ initialValues: {} as InsuranceQuoteForm });
+    expectTypeOf(form.errors).toEqualTypeOf<FormErrors<InsuranceQuoteForm>>();
+    // FormError paths are Path<T>-typed, so entries at any depth are legal
+    // values already — the recursive grammar reuses this model unchanged.
+    const errors: FormErrors<InsuranceQuoteForm> = [
+      { path: ['email'], error: 'x' },
+      { path: ['homeAddress', 'city'], error: 'x' },
+      { path: ['drivers', 0, 'incidents', 1, 'date'], error: 'x' },
+    ];
+    expectTypeOf(errorAt(errors, ['email'])).toEqualTypeOf<
+      string | undefined
+    >();
+    errorAt(errors, ['vehicles', 2, 'garagingAddress', 'postalCode']);
+    // @ts-expect-error 'emial' is not a field of the form
+    errorAt(errors, ['emial']);
+    // @ts-expect-error no paths exist below a scalar leaf
+    errorAt(errors, ['email', 'domain']);
+  });
   it('paths through optional sections and nullable lists resolve, at scale', () => {
     // The latent hole this pins: Path admitted these paths all along, but
     // ValueAt resolved them to `never` because `keyof (Obj | undefined)` is

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

@@ -1,6 +1,7 @@
 import { describe, test, expect, mock } from 'bun:test';
 import { act, renderHook } from '@testing-library/react';
 import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
 import { allOf, matches, notEmpty } from '../validators/validators';
 type SignupForm = {
@@ -39,13 +40,21 @@ describe('useFormState', () => {
         constraints: { email: notEmpty('email') },
       }),
     );
-    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    // The full structured shape: one entry per failing field, addressed by
+    // a typed path (single-key on the flat grammar).
+    expect(result.current.errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    expect(errorAt(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(errorAt(result.current.errors, ['email'])).toBeUndefined();
+    expect(result.current.errors).toEqual([]);
     expect(result.current.isValid).toBe(true);
   });
@@ -56,13 +65,13 @@ describe('useFormState', () => {
         constraints: { email: notEmpty('email') },
       }),
     );
-    expect(result.current.errors.nickname).toBeUndefined();
+    expect(errorAt(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({});
+    expect(result.current.errors).toEqual([]);
   });
   test('submit on an invalid form marks the attempt and skips onSubmit', () => {
@@ -119,17 +128,21 @@ describe('useFormState', () => {
     );
     // Both validators would fail on undefined-adjacent input paths; the
     // FIRST one's message surfaces.
-    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    expect(errorAt(result.current.errors, ['email'])).toBe(
+      "'email' cannot be empty",
+    );
     act(() => {
       result.current.onValueChanges((prev) => ({ ...prev, email: 'nope' }));
     });
-    expect(result.current.errors.email).toBe("'email' must be a valid email");
+    expect(errorAt(result.current.errors, ['email'])).toBe(
+      "'email' must be a valid email",
+    );
     act(() => {
       result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
     });
-    expect(result.current.errors.email).toBeUndefined();
+    expect(errorAt(result.current.errors, ['email'])).toBeUndefined();
     expect(result.current.isValid).toBe(true);
   });
@@ -172,7 +185,9 @@ describe('useFormState', () => {
       }),
     );
     expect(result.current.values.agreed).toBe(false);
-    expect(result.current.errors.agreed).toBe('you must agree to the terms');
+    expect(errorAt(result.current.errors, ['agreed'])).toBe(
+      'you must agree to the terms',
+    );
     expect(result.current.isValid).toBe(false);
     act(() => {
@@ -183,7 +198,7 @@ describe('useFormState', () => {
     act(() => {
       result.current.onValueChanges((prev) => ({ ...prev, agreed: true }));
     });
-    expect(result.current.errors.agreed).toBeUndefined();
+    expect(errorAt(result.current.errors, ['agreed'])).toBeUndefined();
     expect(result.current.isValid).toBe(true);
     act(() => {
@@ -200,7 +215,7 @@ describe('useFormState', () => {
     const { result } = renderHook(() =>
       useFormState({ initialValues, constraints }),
     );
-    expect(result.current.errors).toEqual({});
+    expect(result.current.errors).toEqual([]);
     expect(result.current.isValid).toBe(true);
   });

package/src/forms/useFormState/useFormState.ts CHANGED Viewed

@@ -1,18 +1,13 @@
-import { useEffect, useRef, useState } from 'react';
-import { createFormDebugger } from './FormDebugger';
-import type { FormDebuggerComponent } from './FormDebugger';
-import { createSnapshotStore } from './snapshotStore';
-import type { SnapshotStore } from './snapshotStore';
+import { useState } from 'react';
+import { deriveFormErrors } from './deriveErrors';
 import type {
-  FormDebugSnapshot,
-  FormErrors,
   FormHelpers,
   FormValuesObject,
   UnionPolicyCheck,
 } from './types';
+import { useFormDebugger } from './useFormDebugger';
+import { useFormSubmit } from './useFormSubmit';
 import type { Refine, Validations } from '../validations/types';
-import { validateEntry } from '../validations/walk';
-import type { FlatConstraintEntry } from '../validations/walk';
 // `const V` freezes the inferred type of an inline `constraints` object —
 // each validator's precise type and Refinement marker survive without any
@@ -32,6 +27,11 @@ type Args<T extends FormValuesObject, V extends Validations<T>> = {
   onSubmit?: (values: Refine<T, V>) => void;
 } & UnionPolicyCheck<T>;
+// Plumbing only: each slice of form state lives in its own pure function or
+// focused hook, and this hook just links them up and recomposes their
+// outputs into the `FormHelpers<T>` surface. Values state is the one slice
+// kept inline — today it is a bare `useState`, and the granular setters that
+// would earn it a module of its own arrive with the path-based grammar.
 export const useFormState = <
   T extends FormValuesObject,
   const V extends Validations<T> = Validations<T>,
@@ -41,54 +41,21 @@ export const useFormState = <
   const { initialValues, constraints, onSubmit } = args;
   const [values, onValueChanges] = useState<T>(initialValues);
-  const [submitAttempted, setSubmitAttempted] = useState(false);
-  const errors: FormErrors<T> = {};
-  if (constraints) {
-    for (const key of Object.keys(constraints) as (keyof T & string)[]) {
-      // No cast: if the grammar grows a constraint form the walk doesn't
-      // understand, this assignment is the compile error that says so.
-      const entry: FlatConstraintEntry | undefined = constraints[key];
-      if (entry == null) continue;
-      const failure = validateEntry(entry, values[key], [key]);
-      if (failure != null) errors[key] = failure.error;
-    }
-  }
+  const errors = deriveFormErrors(values, constraints);
+  const isValid = errors.length === 0;
-  const isValid = Object.keys(errors).length === 0;
-  // Debugger plumbing: one store + one component per hook instance, created
-  // lazily on first render. The component's identity must be stable across
-  // renders — recreated each render it would remount (and lose its
-  // open/closed state) on every keystroke.
-  const debugRef = useRef<{
-    store: SnapshotStore<FormDebugSnapshot<T>>;
-    Debugger: FormDebuggerComponent;
-  } | null>(null);
-  if (debugRef.current === null) {
-    const store = createSnapshotStore<FormDebugSnapshot<T>>({
-      values,
-      errors,
-      isValid,
-      submitAttempted,
-    });
-    debugRef.current = { store, Debugger: createFormDebugger(store) };
-  }
-  const { store, Debugger } = debugRef.current;
-  // Publish after every commit. With no debugger window subscribed this is a
-  // field write and an empty notify loop — effectively free.
-  useEffect(() => {
-    store.publish({ values, errors, isValid, submitAttempted });
+  // Explicit type arguments: V rides on `onSubmit`'s parameter type, which
+  // is not an inference site (see useFormSubmit.ts).
+  const { submitAttempted, submit } = useFormSubmit<T, V>({
+    values,
+    isValid,
+    onSubmit,
   });
-  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>);
-  };
+  const Debugger = useFormDebugger({
+    snapshot: { values, errors, isValid, submitAttempted },
+  });
   return {
     values,

package/src/forms/useFormState/useFormSubmit.test.tsx ADDED Viewed

@@ -0,0 +1,86 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormSubmit } from './useFormSubmit';
+// The submit-orchestration boundary in isolation: the attempt flag and the
+// validity gate, driven by whatever `isValid` the caller derived. Full-form
+// behavior (validity flipping as values change) stays in useFormState.test.tsx.
+type Form = { email: string | undefined };
+describe('useFormSubmit', () => {
+  test('starts with submitAttempted false', () => {
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: undefined }, isValid: true }),
+    );
+    expect(result.current.submitAttempted).toBe(false);
+  });
+  test('submit on an invalid form marks the attempt and skips onSubmit', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: undefined }, isValid: false, onSubmit }),
+    );
+    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(() =>
+      useFormSubmit<Form>({ values: { email: 'a@b.co' }, isValid: true, onSubmit }),
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co' });
+  });
+  test('submit without an onSubmit handler is a no-op beyond the flag', () => {
+    const { result } = renderHook(() =>
+      useFormSubmit<Form>({ values: { email: 'a@b.co' }, isValid: true }),
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(result.current.submitAttempted).toBe(true);
+  });
+  test('submitAttempted stays true once validity flips', () => {
+    const onSubmit = mock(() => {});
+    const initialProps: { isValid: boolean; email: string | undefined } = {
+      isValid: false,
+      email: undefined,
+    };
+    const { result, rerender } = renderHook(
+      (props: { isValid: boolean; email: string | undefined }) =>
+        useFormSubmit<Form>({
+          values: { email: props.email },
+          isValid: props.isValid,
+          onSubmit,
+        }),
+      { initialProps },
+    );
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    rerender({ isValid: true, email: 'a@b.co' });
+    expect(result.current.submitAttempted).toBe(true);
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co' });
+  });
+});

package/src/forms/useFormState/useFormSubmit.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import { useState } from 'react';
+import type { Refine, Validations } from '../validations/types';
+import type { FormValuesObject } from './types';
+export type UseFormSubmitArgs<
+  T extends FormValuesObject,
+  V extends Validations<T>,
+> = {
+  values: T;
+  isValid: boolean;
+  onSubmit?: (values: Refine<T, V>) => void;
+};
+// Submit orchestration: owns the `submitAttempted` flag (UIs gate error
+// display on it) and the validity gate in front of `onSubmit`. This is the
+// home of the ONE sanctioned refinement cast (see the cast doctrine in
+// src/forms/CLAUDE.md). `V` is not inferable from `onSubmit`'s parameter
+// position, so `useFormState` applies both type arguments explicitly.
+export const useFormSubmit = <
+  T extends FormValuesObject,
+  V extends Validations<T> = Validations<T>,
+>(
+  args: UseFormSubmitArgs<T, V>,
+) => {
+  const { values, isValid, onSubmit } = args;
+  const [submitAttempted, setSubmitAttempted] = useState(false);
+  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 { submitAttempted, submit };
+};

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

@@ -3,8 +3,9 @@ import type { PathStep } from '../path/types';
 // The runtime walk over a constraints object, kept separate from the hook so
 // its semantics are unit-testable without React. Phase 1 grammar is flat —
 // every path has exactly one step — but errors already carry a `PathStep[]`
-// address so the `{path, error}[]` error model of plan phases 2–3 falls out
-// of this structure instead of forcing a second rewrite.
+// address, which the hook's structured `{path, error}[]` error model
+// (`FormErrors<T>`) consumes directly; the recursive grammar of plan phases
+// 2–3 just hands the walk longer paths, no second rewrite.
 export type ValidationError = {
   readonly path: readonly PathStep[];
@@ -18,8 +19,9 @@ export type ValidationError = {
 type AnyFieldValidator = (val: never) => string | null;
 // The walk's view of one entry in a `Validations<T>` object. This type is
-// what lets the compiler police the walk's assumptions: the hook assigns
-// `constraints[key]` to it WITHOUT a cast, so when the grammar grows a form
+// what lets the compiler police the walk's assumptions: the error derivation
+// (`useFormState/deriveErrors.ts`) assigns `constraints[key]` to it WITHOUT
+// a cast, so when the grammar grows a form
 // that is neither a function nor an array of them (nested spec, list `each`),
 // that assignment stops compiling and the walk must learn the new form —
 // instead of a stale walk misinterpreting it at runtime.