@structuralists/scaffolding 0.11.0 → 0.13.0

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.
@@ -422,6 +441,188 @@ export const FieldBinding: Story = {
   },
 };
 
+type FleetFormValues = {
+  fleetName: string | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    licenseNumber: string | undefined;
+  }>;
+};
+
+// What onSubmit receives: the `each` spec refines the ELEMENT type and the
+// refinement flows through Array<...> — every driver's constrained fields
+// lose undefined. The setSubmitted(vals) call compiling is the proof.
+type SubmittedFleet = {
+  fleetName: string;
+  drivers: Array<{ name: string; licenseNumber: string }>;
+};
+
+// Phase 3 of the recursive grammar: a `{ each: … }` spec validates EVERY
+// list element, and failures are addressed with the numeric index step —
+// ['drivers', 1, 'name'] — the same step semantics the bindings read. Each
+// driver's fields are bound at their numeric paths, so element errors land
+// on exactly the element that failed.
+const ListValidationDemo = () => {
+  const [submitted, setSubmitted] = useState<SubmittedFleet | null>(null);
+
+  const { values, errors, getFormFieldPropsAt, submit } = useFormState({
+    initialValues: {
+      fleetName: undefined,
+      drivers: [
+        { name: undefined, licenseNumber: undefined },
+        { name: undefined, licenseNumber: undefined },
+      ],
+    } as FleetFormValues,
+    constraints: {
+      fleetName: notEmpty('fleetName'),
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          licenseNumber: [
+            notEmpty('licenseNumber'),
+            minLength('licenseNumber', 5),
+          ],
+        },
+      },
+    },
+    onSubmit: (vals) => setSubmitted(vals),
+  });
+
+  return (
+    <form
+      style={{ maxWidth: 420, display: 'grid', gap: 16 }}
+      onSubmit={(e) => {
+        e.preventDefault();
+        submit();
+      }}
+    >
+      <TextInputForForm
+        label="Fleet name"
+        formFieldProps={getFormFieldPropsAt(['fleetName'])}
+      />
+
+      {values.drivers.map((_, index) => (
+        // Index keys are fine here: the list is fixed-size. Stable element
+        // keys for editable lists are plan item 8.
+        <fieldset
+          key={index}
+          style={{ display: 'grid', gap: 12, border: '1px solid var(--ui-border, #ddd)', borderRadius: 6, padding: 12 }}
+        >
+          <legend style={{ fontSize: 13, padding: '0 4px' }}>
+            Driver {index + 1}
+          </legend>
+          <TextInputForForm
+            label={`Driver ${index + 1} name`}
+            formFieldProps={getFormFieldPropsAt(['drivers', index, 'name'])}
+          />
+          <TextInputForForm
+            label={`Driver ${index + 1} license`}
+            hint="At least 5 characters"
+            formFieldProps={getFormFieldPropsAt([
+              'drivers',
+              index,
+              'licenseNumber',
+            ])}
+          />
+        </fieldset>
+      ))}
+
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+        <Button type="submit" variant="primary">
+          Save fleet
+        </Button>
+        {/* errorAt reads one element's raw error at its numeric path — no
+            display gating, the live truth the bindings' errorMessage sits
+            on top of. */}
+        <span style={{ fontSize: 13 }} data-testid="raw-driver-2-name-error">
+          {"raw ['drivers', 1, 'name']: "}
+          {errorAt(errors, ['drivers', 1, 'name']) ?? '—'}
+        </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 ListValidation: Story = {
+  render: () => (
+    <div style={{ padding: 24, fontFamily: 'var(--ui-font)' }}>
+      <ListValidationDemo />
+    </div>
+  ),
+  // Walks the per-element flow: errorAt at a numeric path is live from the
+  // start, element errors surface per element (not per list), fixing one
+  // element leaves its siblings' errors alone, and the refined element type
+  // flows through Array<...> to onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // errorAt is raw truth — the numeric-path lookup sees driver 2's error
+    // before anything is touched or submitted. (Exact-text queries below
+    // don't match this line — its text includes the path prefix.)
+    await expect(
+      canvas.getByTestId('raw-driver-2-name-error'),
+    ).toHaveTextContent("'name' cannot be empty");
+    // The bindings withhold everything until touched/submit-attempted.
+    await expect(
+      canvas.queryAllByText("'name' cannot be empty"),
+    ).toHaveLength(0);
+
+    // Fix driver 1's name, then submit: every remaining element error
+    // appears at its own element — driver 1 name stays clean.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 name/), 'Ayrton');
+    await userEvent.click(canvas.getByRole('button', { name: 'Save fleet' }));
+    await expect(
+      canvas.getAllByText("'name' cannot be empty"),
+    ).toHaveLength(1); // driver 2's field only — driver 1's name passed
+    await expect(
+      canvas.getAllByText("'licenseNumber' cannot be empty"),
+    ).toHaveLength(2); // both drivers' licenses
+    await expect(
+      canvas.getByText("'fleetName' cannot be empty"),
+    ).toBeInTheDocument();
+
+    // Validator arrays keep first-error-wins semantics INSIDE an element:
+    // a short license moves that element (and only it) to the minLength
+    // message.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 license/), 'abc');
+    await expect(
+      canvas.getByText("'licenseNumber' must be at least 5 characters"),
+    ).toBeInTheDocument();
+    await expect(
+      canvas.getAllByText("'licenseNumber' cannot be empty"),
+    ).toHaveLength(1); // driver 2 still on notEmpty
+
+    // Fix everything; the narrowed payload reaches onSubmit.
+    await userEvent.type(canvas.getByLabelText(/^Driver 1 license/), 'de');
+    await userEvent.type(canvas.getByLabelText(/^Driver 2 name/), 'Michele');
+    await userEvent.type(
+      canvas.getByLabelText(/^Driver 2 license/),
+      'XK-4471',
+    );
+    await userEvent.type(canvas.getByLabelText(/^Fleet name/), 'Scuderia');
+    // Driver 2's name is fixed — the raw errorAt lookup clears live.
+    await expect(
+      canvas.getByTestId('raw-driver-2-name-error'),
+    ).toHaveTextContent('—');
+    await userEvent.click(canvas.getByRole('button', { name: 'Save fleet' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
+};
+
 type DebuggerDemoValues = {
   email: string | undefined;
   nickname: string | undefined;
@@ -550,24 +751,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' }));