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

@structuralists/scaffolding 0.9.0 → 0.10.0

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 (11) hide show

package/package.json +1 -1
package/src/forms/CLAUDE.md +34 -4
package/src/forms/plan.md +23 -7
package/src/forms/useFormState/errorAt.test.ts +54 -0
package/src/forms/useFormState/errorAt.ts +27 -0
package/src/forms/useFormState/types.ts +15 -5
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 +11 -4
package/src/forms/validations/walk.ts +3 -2

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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
@@ -271,10 +295,16 @@ 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
+  `errors` is the structured `FormErrors<T>` list (see "The error model"),
+  live-derived from current values each render (validators are pure and
+  cheap) with `isValid` its emptiness; `errorAt.ts` holds the typed lookup;
+  `submitAttempted` lets UIs gate error display; and `submit()` performs
+  the one honest *refinement* cast to `Refine<T, V>` — earned because the
+  validators just passed at runtime. The hook's error loop carries one
+  further documented widening (`failure.path as Path<T>`, same species as
+  its `Object.keys` cast): `[key]` is a valid single-key `Path<T>`, but TS
+  cannot compute `Path<T>` for an unresolved generic `T` to see the
+  correlation. `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

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/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,9 +77,18 @@ 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
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can

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

@@ -5,11 +5,12 @@ import { createSnapshotStore } from './snapshotStore';
 import type { SnapshotStore } from './snapshotStore';
 import type {
   FormDebugSnapshot,
-  FormErrors,
+  FormError,
   FormHelpers,
   FormValuesObject,
   UnionPolicyCheck,
 } from './types';
+import type { Path } from '../path/types';
 import type { Refine, Validations } from '../validations/types';
 import { validateEntry } from '../validations/walk';
 import type { FlatConstraintEntry } from '../validations/walk';
@@ -43,7 +44,7 @@ export const useFormState = <
   const [values, onValueChanges] = useState<T>(initialValues);
   const [submitAttempted, setSubmitAttempted] = useState(false);
-  const errors: FormErrors<T> = {};
+  const errors: FormError<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
@@ -51,11 +52,17 @@ export const useFormState = <
       const entry: FlatConstraintEntry | undefined = constraints[key];
       if (entry == null) continue;
       const failure = validateEntry(entry, values[key], [key]);
-      if (failure != null) errors[key] = failure.error;
+      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 });
     }
   }
-  const isValid = Object.keys(errors).length === 0;
+  const isValid = 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

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[];