@structuralists/scaffolding 0.11.0 → 0.12.0

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

@@ -44,7 +44,8 @@ describe('FormDebugger', () => {
 
     expect(screen.getByText('isValid')).toBeTruthy();
     expect(screen.getByText('submitAttempted')).toBeTruthy();
-    expect(screen.getByText("'nickname' cannot be empty")).toBeTruthy();
+    // String leaves render with surrounding quotes (Chrome-inspector style).
+    expect(screen.getByText('"\'nickname\' cannot be empty"')).toBeTruthy();
   });
 
   test('the open window live-updates as the form changes', () => {
@@ -57,8 +58,8 @@ describe('FormDebugger', () => {
 
     // The window survived the form re-render (stable component identity —
     // a remount would have reset it to closed) and shows the new state.
-    expect(screen.getByText('will')).toBeTruthy();
-    expect(screen.queryByText("'nickname' cannot be empty")).toBeNull();
+    expect(screen.getByText('"will"')).toBeTruthy();
+    expect(screen.queryByText('"\'nickname\' cannot be empty"')).toBeNull();
   });
 
   test('clicking the trigger again closes the window', () => {

package/src/forms/state/useFormState/deriveErrors.test.ts

@@ -74,3 +74,97 @@ describe('deriveFormErrors', () => {
     expect(deriveFormErrors(emptyForm, constraints)).toEqual([]);
   });
 });
+
+// The recursive grammar: nested object specs walk the value tree and
+// address failures with real multi-step paths. (List `each` specs are
+// type-level only until plan phase 3 — the walk throws on one; pinned in
+// walk.test.ts.)
+
+type ProfileForm = {
+  email: string | undefined;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+  mailingAddress: { city: string | undefined } | undefined;
+};
+
+const emptyProfile: ProfileForm = {
+  email: undefined,
+  homeAddress: { city: undefined, postalCode: undefined },
+  mailingAddress: undefined,
+};
+
+describe('deriveFormErrors — nested object specs', () => {
+  test('a failing nested leaf contributes an entry addressed by its full path', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      homeAddress: { city: notEmpty('city') },
+    });
+    expect(errors).toEqual([
+      { path: ['homeAddress', 'city'], error: "'city' cannot be empty" },
+    ]);
+  });
+
+  test('sibling fields fail independently — one entry per failing node', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      email: notEmpty('email'),
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: notEmpty('postalCode'),
+      },
+    });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+      { path: ['homeAddress', 'city'], error: "'city' cannot be empty" },
+      {
+        path: ['homeAddress', 'postalCode'],
+        error: "'postalCode' cannot be empty",
+      },
+    ]);
+  });
+
+  test('passing nested leaves contribute nothing', () => {
+    const errors = deriveFormErrors(
+      {
+        ...emptyProfile,
+        homeAddress: { city: 'SF', postalCode: '94110' },
+      },
+      {
+        homeAddress: {
+          city: notEmpty('city'),
+          postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+        },
+      },
+    );
+    expect(errors).toEqual([]);
+  });
+
+  test('a nested spec on an absent section is skipped', () => {
+    // Decided with the phase-2 type spike: the honest runtime mirror of the
+    // type level (which refines only the present branch of a nullable
+    // section) is to validate nothing when the section is absent.
+    const errors = deriveFormErrors(emptyProfile, {
+      mailingAddress: { city: notEmpty('city') },
+    });
+    expect(errors).toEqual([]);
+  });
+
+  test('the same nested spec fires once the section is present', () => {
+    const errors = deriveFormErrors(
+      { ...emptyProfile, mailingAddress: { city: undefined } },
+      { mailingAddress: { city: notEmpty('city') } },
+    );
+    expect(errors).toEqual([
+      { path: ['mailingAddress', 'city'], error: "'city' cannot be empty" },
+    ]);
+  });
+
+  test('a required section is a leaf validator on the section field', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      mailingAddress: notEmpty('mailingAddress'),
+    });
+    expect(errors).toEqual([
+      { path: ['mailingAddress'], error: "'mailingAddress' cannot be empty" },
+    ]);
+  });
+});

package/src/forms/state/useFormState/deriveErrors.ts

@@ -1,7 +1,7 @@
 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 { ConstraintEntry } from '../validations/walk';
 import type { FormError, FormValuesObject } from './types';
 
 // The pure half of the hook's error model: current values + constraints in,
@@ -19,16 +19,16 @@ export const deriveFormErrors = <T extends FormValuesObject>(
   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];
+    const entry: ConstraintEntry | 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 });
+    for (const failure of validateEntry(entry, values[key], [key])) {
+      // The walk extends the address it was handed only along keys of specs
+      // type-checked against T's subtree, so every returned path is a valid
+      // Path<T>. TS can't compute Path<T> for an unresolved generic T to
+      // see the correlation, so it 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/state/useFormState/errorAt.test.ts

@@ -2,9 +2,9 @@ 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.
+// errorAt's equality must be exact over multi-step and numeric-step paths —
+// the recursive grammar produces real multi-step addresses (nested specs
+// today; numeric steps arrive with runtime `each` in plan phase 3).
 type Form = {
   email: string | undefined;
   address: { city: string | undefined };

package/src/forms/state/useFormState/inspectable.test.ts

@@ -11,15 +11,15 @@ describe('toInspectable', () => {
     expect(toInspectable(true)).toBe(true);
   });
 
-  test('converts arrays to index-keyed objects', () => {
-    expect(toInspectable(['a', 'b'])).toEqual({ 0: 'a', 1: 'b' });
+  test('keeps arrays as arrays (JsonTable renders them natively)', () => {
+    expect(toInspectable(['a', 'b'])).toEqual(['a', 'b']);
   });
 
-  test('converts arrays of objects recursively', () => {
-    expect(toInspectable([{ name: 'ada' }, { name: 'bo' }])).toEqual({
-      0: { name: 'ada' },
-      1: { name: 'bo' },
-    });
+  test('walks array elements recursively (Sets may hide inside)', () => {
+    expect(toInspectable([{ roles: new Set(['admin']) }, { name: 'bo' }])).toEqual([
+      { roles: 'Set(1) { "admin" }' },
+      { name: 'bo' },
+    ]);
   });
 
   test('renders Sets as a descriptive string leaf', () => {
@@ -35,8 +35,8 @@ describe('toInspectable', () => {
     };
     expect(toInspectable(form)).toEqual({
       email: 'a@b.co',
-      address: { city: undefined, tags: { 0: 'home' } },
-      drivers: { 0: { name: 'ada', incidents: {} } },
+      address: { city: undefined, tags: ['home'] },
+      drivers: [{ name: 'ada', incidents: [] }],
     });
   });
 });

package/src/forms/state/useFormState/inspectable.ts

@@ -1,10 +1,10 @@
 // Converts a form-state snapshot into a shape JsonTable renders without
-// throwing. JsonTable dispatches on "plain object vs leaf": arrays and Sets
-// fall to the leaf renderer, and an array of objects (FormValueList) would
-// throw as a React child. A debugger must render *any* legal form state, so:
+// throwing. JsonTable recurses into plain objects and arrays; everything
+// else falls to the leaf renderer, and a Set there would throw as a React
+// child. A debugger must render *any* legal form state, so:
 //
-//   - arrays  → index-keyed plain objects ({ 0: ..., 1: ... }), recursively
 //   - Sets    → a descriptive string leaf: `Set(2) { "a", "b" }`
+//   - arrays  → walked recursively (a Set may hide inside), kept as arrays
 //   - objects → walked recursively
 //   - leaves  → passed through untouched
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
@@ -20,9 +20,7 @@ export const toInspectable = (value: unknown): unknown => {
   }
 
   if (Array.isArray(value)) {
-    return Object.fromEntries(
-      value.map((element, index) => [index, toInspectable(element)]),
-    );
+    return value.map(toInspectable);
   }
 
   if (isPlainObject(value)) {

package/src/forms/state/useFormState/types.ts

@@ -78,8 +78,8 @@ export type UnionPolicyCheck<T> = HasDisallowedUnion<T> extends true
   : unknown;
 
 // 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
+// by a typed path as deep as the node (root leaves get single-key paths,
+// nested-spec leaves get the full address). 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.

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

@@ -278,13 +278,14 @@ type QuoteFormValues = {
 };
 
 // What onSubmit receives: notEmpty strips undefined from email and null
-// from coverageType. The setSubmitted(vals) call below compiling is the
-// proof that refinement still flows end-to-end when fields are wired
+// from coverageType, and the NESTED spec on homeAddress refines its
+// constrained leaves in place. The setSubmitted(vals) call below compiling
+// is the proof that refinement still flows end-to-end when fields are wired
 // through bindings.
 type SubmittedQuote = {
   email: string;
   coverageType: CoverageType;
-  homeAddress: QuoteFormValues['homeAddress'];
+  homeAddress: { city: string; postalCode: string };
 };
 
 const COVERAGE_OPTIONS: SelectOption<CoverageType>[] = [
@@ -309,6 +310,13 @@ const FieldBindingDemo = () => {
     constraints: {
       email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
       coverageType: notEmpty('coverageType'),
+      // A nested spec: errors inside homeAddress get real multi-step
+      // addresses (['homeAddress', 'postalCode']), which is exactly what the
+      // deep-path bindings below read via errorMessage.
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+      },
     },
     onSubmit: (vals) => setSubmitted(vals),
   });
@@ -401,13 +409,24 @@ export const FieldBinding: Story = {
     await userEvent.type(canvas.getByLabelText(/^City/), 'Lyon');
     await expect(canvas.getByLabelText(/^City/)).toHaveValue('Lyon');
 
-    // A submit attempt unlocks the untouched coverage field's error too.
+    // A submit attempt unlocks the untouched fields' errors too — including
+    // the NESTED postalCode error, addressed ['homeAddress', 'postalCode']
+    // by the recursive walk and surfaced by its deep-path binding.
     await userEvent.click(canvas.getByRole('button', { name: 'Get quote' }));
     await expect(
       canvas.getByText("'coverageType' cannot be empty"),
     ).toBeInTheDocument();
+    await expect(
+      canvas.getByText("'postalCode' cannot be empty"),
+    ).toBeInTheDocument();
+    // The touched City field passed its nested constraint — no error.
+    await expect(canvas.queryByText("'city' cannot be empty")).not.toBeInTheDocument();
 
-    // Fix both fields; committing a select option counts as its touch.
+    // Fix the remaining fields; committing a select option counts as its touch.
+    await userEvent.type(canvas.getByLabelText(/^Postal code/), '69001');
+    await expect(
+      canvas.queryByText("'postalCode' cannot be empty"),
+    ).not.toBeInTheDocument();
     await userEvent.type(canvas.getByLabelText(/^Email/), 'will@example.com');
     await userEvent.click(canvas.getByRole('button', { name: 'Coverage' }));
     // The option list is portaled — query the document, not the canvas.
@@ -550,24 +569,27 @@ export const WithDebugger: Story = {
 
     // Open: live state, including errors the form itself isn't showing yet
     // (its display is submit-gated; the debugger sees the raw truth).
+    // String leaves render with surrounding quotes (Chrome-inspector style).
     await userEvent.click(body.getByRole('button', { name: 'signup form' }));
     await expect(body.getByText('isValid')).toBeInTheDocument();
-    await expect(body.getByText("'email' cannot be empty")).toBeInTheDocument();
     await expect(
-      body.getByText("'nickname' cannot be empty"),
+      body.getByText('"\'email\' cannot be empty"'),
+    ).toBeInTheDocument();
+    await expect(
+      body.getByText('"\'nickname\' cannot be empty"'),
     ).toBeInTheDocument();
 
     // Live update while open: value appears, its error entry drops out.
     await userEvent.type(canvas.getByLabelText(/^Nickname/), 'will');
-    await expect(body.getByText('will')).toBeInTheDocument();
+    await expect(body.getByText('"will"')).toBeInTheDocument();
     await expect(
-      body.queryByText("'nickname' cannot be empty"),
+      body.queryByText('"\'nickname\' cannot be empty"'),
     ).not.toBeInTheDocument();
 
     // List values render in the window (index-keyed).
     await userEvent.type(canvas.getByLabelText(/^Tags/), 'typescript');
     await userEvent.click(canvas.getByRole('button', { name: 'Add' }));
-    await expect(body.getByText('typescript')).toBeInTheDocument();
+    await expect(body.getByText('"typescript"')).toBeInTheDocument();
 
     // Close: window unmounts, trigger stays.
     await userEvent.click(body.getByRole('button', { name: 'signup form' }));