@structuralists/scaffolding 0.10.2 → 0.12.0

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/errorAt.ts

@@ -1,11 +1,12 @@
+import { pathsEqual } from '../path/path';
 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.
+// sanctioned way to read one field's error. Path equality is structural
+// (`pathsEqual`): 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>,
@@ -14,14 +15,9 @@ export const errorAt = <T extends FormValuesObject>(
   // 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])
-    );
-  });
+  const match = errors.find((candidate) =>
+    pathsEqual(candidate.path as readonly PathStep[], steps),
+  );
 
   return match?.error;
 };

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

@@ -1,7 +1,7 @@
 // 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';
+import type { Path, ValueAt } from '../path/types';
 
 export type FormValueSimple = string | number | bigint | boolean | string[] | Set<string> | undefined | null;
 
@@ -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.
@@ -90,6 +90,28 @@ export type FormError<T extends FormValuesObject> = {
 
 export type FormErrors<T extends FormValuesObject> = readonly FormError<T>[];
 
+// What a form-aware element declares it needs from a field binding: it
+// *displays* `Display` and *emits* `Emit`. A `FormFieldProps<V>` is
+// assignable exactly when V sits between them (`Emit ⊆ V ⊆ Display`), which
+// is how "a number-typed path bound to a text-shaped element" becomes a
+// compile error at the `formFieldProps` prop — no generics needed on the
+// wrapper, structural assignability does the checking.
+export type FieldBinding<Display, Emit = Display> = {
+  value: Display;
+  onChange: (val: Emit) => void;
+  // Already display-policy-aware (see `useFieldBinding`): undefined until
+  // the field's error should be SHOWN, so elements render what they're
+  // given and stay policy-free.
+  errorMessage: string | undefined;
+  // Feeds touched tracking; wire it to the element's blur (or, for
+  // commit-style elements like selects, to the commit).
+  onBlur: () => void;
+  // room to grow: name/id derivation, disabled, ...
+};
+
+// The bundle `getFormFieldPropsAt(path)` returns for the field at that path.
+export type FormFieldProps<V> = FieldBinding<V>;
+
 // What the hook publishes (via `useFormDebugger`) to its Debugger after
 // every commit. Snapshots are
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can
@@ -99,11 +121,14 @@ export type FormDebugSnapshot<T extends FormValuesObject> = {
   errors: FormErrors<T>;
   isValid: boolean;
   submitAttempted: boolean;
+  touched: readonly Path<T>[];
 };
 
 export type FormHelpers<T extends FormValuesObject> = {
   values: T;
-  // todo: likely remove once other setter are available
+  // Whole-value replacement. No longer the only write path (field-level
+  // writes go through `getFormFieldPropsAt(path).onChange`); whether this
+  // survives long-term is a separate decision.
   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`.
@@ -111,6 +136,12 @@ export type FormHelpers<T extends FormValuesObject> = {
   isValid: boolean;
   submitAttempted: boolean;
   submit: () => void;
+  // One expression wires a field: value, typed onChange (an immutable write
+  // at the path), display-policy-aware errorMessage, and onBlur (touched
+  // tracking). `ValueAt<T, P>` types value/onChange end-to-end, so binding a
+  // wrong-shaped path to an element fails to compile at the element's
+  // `formFieldProps` prop.
+  getFormFieldPropsAt: <P extends Path<T>>(path: P) => FormFieldProps<ValueAt<T, P>>;
   // Dev-time introspection overlay bound to this form instance: a fixed
   // trigger that opens a window showing the form's live internal state.
   // Render it anywhere (it portals to <body>); omit it and nothing mounts.

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

@@ -0,0 +1,165 @@
+import { describe, test, expect } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFieldBinding } from './useFieldBinding';
+import { useFormState } from './useFormState';
+import { notEmpty } from '../validators/validators';
+
+// Field binding exercised through useFormState — the composition consumers
+// see. Pins the three behaviors item 6 added: granular path writes (the
+// immutable mirror of read()), touched tracking fed by onBlur, and the
+// error-display policy living inside errorMessage.
+
+type Address = { city: string | undefined; zip: string | undefined };
+
+type ProfileForm = {
+  email: string | undefined;
+  homeAddress: Address;
+  mailingAddress: Address | undefined;
+  pets: Array<{ name: string | undefined }>;
+};
+
+const initialValues: ProfileForm = {
+  email: undefined,
+  homeAddress: { city: undefined, zip: undefined },
+  mailingAddress: undefined,
+  pets: [{ name: 'Rex' }, { name: 'Milou' }],
+};
+
+const setup = () =>
+  renderHook(() =>
+    useFormState({
+      initialValues,
+      constraints: { email: notEmpty('email') },
+    }),
+  );
+
+describe('getFormFieldPropsAt — value and writes', () => {
+  test('reads the value at a deep path', () => {
+    const { result } = setup();
+    expect(result.current.getFormFieldPropsAt(['pets', 0, 'name']).value).toBe(
+      'Rex',
+    );
+    expect(
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).value,
+    ).toBeUndefined();
+  });
+
+  test('a path through an absent section reads undefined and writes as a no-op', () => {
+    const { result } = setup();
+    const field = result.current.getFormFieldPropsAt(['mailingAddress', 'city']);
+    expect(field.value).toBeUndefined();
+
+    act(() => {
+      field.onChange('Paris');
+    });
+    // The write mirrored read()'s dead-step semantics: nothing changed.
+    expect(result.current.values).toBe(initialValues);
+  });
+
+  test('onChange writes at the path immutably, preserving sibling identity', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).onChange('Paris');
+    });
+
+    expect(result.current.values.homeAddress.city).toBe('Paris');
+    // Untouched branches keep their identity — only the spine was cloned.
+    expect(result.current.values.pets).toBe(initialValues.pets);
+    expect(result.current.values).not.toBe(initialValues);
+    expect(initialValues.homeAddress.city).toBeUndefined();
+  });
+
+  test('onChange into a list element rewrites only that element', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['pets', 1, 'name']).onChange('Snowy');
+    });
+
+    expect(result.current.values.pets[1].name).toBe('Snowy');
+    expect(result.current.values.pets[0]).toBe(initialValues.pets[0]);
+  });
+});
+
+describe('getFormFieldPropsAt — error-display policy', () => {
+  test('an untouched field shows no error before a submit attempt', () => {
+    const { result } = setup();
+    // The error exists in the raw list …
+    expect(result.current.errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    // … but the binding withholds it until touched or submit-attempted.
+    expect(
+      result.current.getFormFieldPropsAt(['email']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('onBlur marks the field touched and unlocks its error — only its own', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+
+    expect(result.current.getFormFieldPropsAt(['email']).errorMessage).toBe(
+      "'email' cannot be empty",
+    );
+    // Another field stays untouched: same policy, independent state.
+    expect(
+      result.current.getFormFieldPropsAt(['homeAddress', 'city']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('a submit attempt unlocks every field’s error', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.submit();
+    });
+
+    expect(result.current.getFormFieldPropsAt(['email']).errorMessage).toBe(
+      "'email' cannot be empty",
+    );
+  });
+
+  test('a touched field’s error clears once the value is fixed', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onChange('a@b.co');
+    });
+
+    expect(
+      result.current.getFormFieldPropsAt(['email']).errorMessage,
+    ).toBeUndefined();
+  });
+
+  test('repeat blurs on the same path keep the touched list stable', () => {
+    // At the useFieldBinding boundary, where the touched list is returned.
+    const { result } = renderHook(() =>
+      useFieldBinding({
+        values: initialValues,
+        onValueChanges: () => {},
+        errors: [],
+        submitAttempted: false,
+      }),
+    );
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    const touchedAfterFirst = result.current.touched;
+    expect(touchedAfterFirst).toEqual([['email']]);
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['email']).onBlur();
+    });
+    // Re-blurring an already-touched path is a state no-op — the setter
+    // returns the same array, so nothing downstream sees a change.
+    expect(result.current.touched).toBe(touchedAfterFirst);
+  });
+});

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

@@ -0,0 +1,71 @@
+import { useState } from 'react';
+import { errorAt } from './errorAt';
+import type { FormErrors, FormFieldProps, FormValuesObject } from './types';
+import { pathsEqual, read, write } from '../path/path';
+import type { CursorStep, Path, PathStep, ValueAt } from '../path/types';
+
+export type UseFieldBindingArgs<T extends FormValuesObject> = {
+  values: T;
+  onValueChanges: (val: T | ((prev: T) => T)) => void;
+  errors: FormErrors<T>;
+  submitAttempted: boolean;
+};
+
+// Field binding: owns per-field touched state and builds
+// `getFormFieldPropsAt`, the one-expression wiring for a field (see
+// FormHelpers in ./types.ts).
+//
+// THE error-display policy lives here, in `errorMessage`, and nowhere else:
+// a field's error is shown once the field has been touched (blurred at
+// least once) OR a submit has been attempted. Elements render the message
+// they are given and stay policy-free; anything wanting a different policy
+// (e.g. always-live display) reads `errors`/`errorAt` directly instead.
+export const useFieldBinding = <T extends FormValuesObject>(
+  args: UseFieldBindingArgs<T>,
+) => {
+  const { values, onValueChanges, errors, submitAttempted } = args;
+
+  // Same representation as FormErrors: a plain list of typed paths compared
+  // structurally (pathsEqual). At form scale a linear scan is fine.
+  const [touched, setTouched] = useState<readonly Path<T>[]>([]);
+
+  const getFormFieldPropsAt = <P extends Path<T>>(
+    path: P,
+  ): FormFieldProps<ValueAt<T, P>> => {
+    // 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 keySteps: readonly CursorStep[] = steps.map((key) => ({
+      kind: 'key',
+      key,
+    }));
+
+    const isTouched = touched.some((candidate) =>
+      pathsEqual(candidate as readonly PathStep[], steps),
+    );
+
+    return {
+      // read() resolves exactly what ValueAt<T, P> promises — including the
+      // `| undefined` picked up through nullable ancestors — TS just can't
+      // correlate them for generic T. Honest cast, documented in the cast
+      // doctrine (src/forms/CLAUDE.md).
+      value: read(values, keySteps) as ValueAt<T, P>,
+      // write() replaces the value at the path and clones only the spine —
+      // the result is the same T shape. Same honest correlation as `value`.
+      onChange: (val) =>
+        onValueChanges((prev) => write(prev, steps, val) as T),
+      errorMessage:
+        submitAttempted || isTouched ? errorAt(errors, path) : undefined,
+      onBlur: () =>
+        setTouched((prev) =>
+          prev.some((candidate) =>
+            pathsEqual(candidate as readonly PathStep[], steps),
+          )
+            ? prev
+            : [...prev, path],
+        ),
+    };
+  };
+
+  return { touched, getFormFieldPropsAt };
+};

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

@@ -21,6 +21,7 @@ const Host = () => {
       errors: [],
       isValid: true,
       submitAttempted: false,
+      touched: [],
     },
   });
 

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

@@ -9,6 +9,9 @@ import { Field } from '../../elements/Field';
 import { Input } from '../../elements/Input';
 import { Button } from '../../elements/Button';
 import { SingleSelect } from '../../elements/Select';
+import type { SelectOption } from '../../elements/Select';
+import { SingleSelectForForm } from '../bindings/SingleSelectForForm';
+import { TextInputForForm } from '../bindings/TextInputForForm';
 
 const meta: Meta = {
   title: 'Forms/useFormState',
@@ -43,6 +46,10 @@ const ROLE_OPTIONS = [
   { value: 'manager', label: 'Manager' },
 ];
 
+// Deliberately hand-wired — the contrast case for the FieldBinding story
+// below: every field spells out its own read, spread-update, error lookup,
+// and submit gating. `getFormFieldPropsAt` + the ForForm wrappers collapse
+// those four decisions into one expression per field.
 const SignupDemo = () => {
   const [submitted, setSubmitted] = useState<SubmittedValues | null>(null);
 
@@ -259,6 +266,181 @@ export const LiveValidity: Story = {
   },
 };
 
+type CoverageType = 'liability' | 'comprehensive';
+
+type QuoteFormValues = {
+  email: string | undefined;
+  coverageType: CoverageType | null;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+};
+
+// What onSubmit receives: notEmpty strips undefined from email and null
+// 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: { city: string; postalCode: string };
+};
+
+const COVERAGE_OPTIONS: SelectOption<CoverageType>[] = [
+  { value: 'liability', label: 'Liability' },
+  { value: 'comprehensive', label: 'Comprehensive' },
+];
+
+// The item-6 target: one expression wires a field. getFormFieldPropsAt
+// bundles value + typed onChange (an immutable write at the path) +
+// display-policy-aware errorMessage + onBlur, and the ForForm wrappers
+// take the bundle as a single prop. Note the deep paths into homeAddress —
+// no hand-spread updates anywhere.
+const FieldBindingDemo = () => {
+  const [submitted, setSubmitted] = useState<SubmittedQuote | null>(null);
+
+  const { getFormFieldPropsAt, submit } = useFormState({
+    initialValues: {
+      email: undefined,
+      coverageType: null,
+      homeAddress: { city: undefined, postalCode: undefined },
+    } as QuoteFormValues,
+    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),
+  });
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <TextInputForForm
+        label="Email"
+        type="email"
+        placeholder="you@example.com"
+        hint="Blur the empty field to see touched-gated errors"
+        formFieldProps={getFormFieldPropsAt(['email'])}
+      />
+
+      <SingleSelectForForm
+        label="Coverage"
+        options={COVERAGE_OPTIONS}
+        placeholder="Pick a coverage"
+        formFieldProps={getFormFieldPropsAt(['coverageType'])}
+      />
+
+      <TextInputForForm
+        label="City"
+        formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])}
+      />
+
+      <TextInputForForm
+        label="Postal code"
+        formFieldProps={getFormFieldPropsAt(['homeAddress', 'postalCode'])}
+      />
+
+      <div>
+        <Button type="submit" variant="primary">
+          Get quote
+        </Button>
+      </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 FieldBinding: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <FieldBindingDemo />
+    </div>
+  ),
+  // Walks the binding flow: touched/blur gating of errorMessage (before any
+  // submit attempt), deep-path writes through the wrappers, submit-attempt
+  // gating for untouched fields, and the narrowed payload reaching onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Nothing shown initially: the email error exists in the raw list, but
+    // errorMessage withholds it until the field is touched.
+    await expect(
+      canvas.queryByText("'email' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Blurring the empty email field marks it touched — its error appears
+    // without any submit attempt, and only its own.
+    await userEvent.click(canvas.getByLabelText(/^Email/));
+    await userEvent.tab();
+    await expect(canvas.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(
+      canvas.queryByText("'coverageType' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Deep-path writes flow through the wrapper onChange.
+    await userEvent.type(canvas.getByLabelText(/^City/), 'Lyon');
+    await expect(canvas.getByLabelText(/^City/)).toHaveValue('Lyon');
+
+    // 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 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.
+    await userEvent.click(await body.findByRole('option', { name: 'Liability' }));
+    await expect(
+      canvas.queryByText("'coverageType' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // Valid submit delivers the narrowed payload.
+    await userEvent.click(canvas.getByRole('button', { name: 'Get quote' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
+};
+
 type DebuggerDemoValues = {
   email: string | undefined;
   nickname: string | undefined;
@@ -387,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' }));