@structuralists/scaffolding 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {
@@ -28,25 +28,25 @@
     "react-router": "^7.0.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.9.0",
-    "@storybook/addon-docs": "^10.3.6",
-    "@storybook/react": "^10.3.6",
-    "@storybook/react-vite": "^10.3.6",
+    "@happy-dom/global-registrator": "^20.10.6",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/react": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
-    "@types/react": "^19.2.14",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/parser": "^8.59.1",
-    "@vitejs/plugin-react": "^6.0.1",
-    "eslint": "^10.3.0",
+    "@typescript-eslint/parser": "^8.62.1",
+    "@vitejs/plugin-react": "^6.0.3",
+    "eslint": "^10.6.0",
     "eslint-plugin-boundaries": "^6.0.2",
-    "eslint-plugin-storybook": "10.3.6",
-    "prettier": "^3.8.3",
-    "react-router": "^7.14.2",
-    "storybook": "^10.3.6",
+    "eslint-plugin-storybook": "10.4.6",
+    "prettier": "^3.9.4",
+    "react-router": "^7.18.1",
+    "storybook": "^10.4.6",
     "typescript": "^6.0.3",
-    "vite": "^8.0.10",
-    "vitest": "^4.1.5"
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
   }
 }

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