@structuralists/scaffolding 0.6.0 → 0.7.0

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+# The same four checks the release job runs post-merge (publish.yml), but on
+# every PR — so merging green is enforced, and the release job's checks are a
+# formality rather than the first place a break surfaces.
+on:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          restore-keys: playwright-${{ runner.os }}-
+
+      - name: Install Playwright chromium
+        run: npx playwright install chromium --with-deps
+
+      - run: bun run typecheck
+      - run: bun run lint
+      - run: bun run test
+      - run: bun run test:storybook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/forms/path/types.test-d.ts

@@ -5,6 +5,7 @@ import type { Cursor, Path, ValueAt } from './types';
 type FlatObj = {
   name: string;
   age: number;
+  active: boolean;
   tags: string[]; // string[] is a FormValueSimple — treated as a leaf
 };
 
@@ -30,7 +31,7 @@ type Mixed = {
 describe('Path<T>', () => {
   it('expands flat object keys to single-step paths', () => {
     type P = Path<FlatObj>;
-    expectTypeOf<P>().toEqualTypeOf<['name'] | ['age'] | ['tags']>();
+    expectTypeOf<P>().toEqualTypeOf<['name'] | ['age'] | ['active'] | ['tags']>();
   });
 
   it('descends into nested objects', () => {
@@ -71,6 +72,7 @@ describe('Path<T>', () => {
   it('produces `never` for FormValueSimple leaves', () => {
     expectTypeOf<Path<string>>().toEqualTypeOf<never>();
     expectTypeOf<Path<number>>().toEqualTypeOf<never>();
+    expectTypeOf<Path<boolean>>().toEqualTypeOf<never>();
     expectTypeOf<Path<string[]>>().toEqualTypeOf<never>();
     expectTypeOf<Path<undefined>>().toEqualTypeOf<never>();
   });
@@ -84,6 +86,7 @@ describe('ValueAt<T, P>', () => {
   it('resolves a single key', () => {
     expectTypeOf<ValueAt<FlatObj, ['name']>>().toEqualTypeOf<string>();
     expectTypeOf<ValueAt<FlatObj, ['age']>>().toEqualTypeOf<number>();
+    expectTypeOf<ValueAt<FlatObj, ['active']>>().toEqualTypeOf<boolean>();
     expectTypeOf<ValueAt<FlatObj, ['tags']>>().toEqualTypeOf<string[]>();
   });
 

package/src/forms/plan.md

@@ -12,9 +12,10 @@ even if the risky type work later stalls, and the risk zone comes last so a
 TS wall can't strand finished work behind it.
 
 1. **Item 7 — Debugger.** Zero type risk, valuable for developing everything
-   after it (watching nested state and structured errors live). ← *current*
+   after it (watching nested state and structured errors live). ✅ *done*
+   (PR #14, released 0.6.0)
 2. **Item 1 — validator arrays per key.** `ExcludedOf<C[number]>` already
-   proven inside `allOf`.
+   proven inside `allOf`. ← *current*
 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.

package/src/forms/useFormState/types.ts

@@ -2,7 +2,7 @@
 // turn, but the cycle never exists at runtime.
 import type { FormDebuggerComponent } from './FormDebugger';
 
-export type FormValueSimple = string | number | bigint | string[] | Set<string> | undefined | null;
+export type FormValueSimple = string | number | bigint | boolean | string[] | Set<string> | undefined | null;
 
 export type FormValuesObject = { [k in string]: FormValue };
 

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

@@ -1,5 +1,6 @@
 import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
 import { useFormState } from './useFormState';
 import { allOf, matches, minLength, notEmpty } from '../validators/validators';
 import { Field } from '../../components/Forms/Field';
@@ -153,6 +154,43 @@ export const SignupForm: Story = {
       <SignupDemo />
     </div>
   ),
+  // Walks the headline flow: errors gated on submit, allOf first-error
+  // progression, live clearing, and the narrowed payload reaching onSubmit.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Errors are gated on submitAttempted — nothing shown initially.
+    await expect(
+      canvas.queryByText("'email' cannot be empty"),
+    ).not.toBeInTheDocument();
+
+    // A failing submit surfaces every constrained field's error.
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign up' }));
+    await expect(canvas.getByText("'email' cannot be empty")).toBeInTheDocument();
+    await expect(
+      canvas.getByText("'displayName' cannot be empty"),
+    ).toBeInTheDocument();
+    await expect(canvas.getByText("'role' cannot be empty")).toBeInTheDocument();
+
+    // allOf progression: notEmpty now passes, matches takes over.
+    await userEvent.type(canvas.getByLabelText(/^Email/), 'not-an-email');
+    await expect(
+      canvas.getByText("'email' must be a valid email"),
+    ).toBeInTheDocument();
+
+    // Fix every field; errors clear live.
+    await userEvent.clear(canvas.getByLabelText(/^Email/));
+    await userEvent.type(canvas.getByLabelText(/^Email/), 'will@example.com');
+    await userEvent.type(canvas.getByLabelText(/^Display name/), 'Will');
+    await userEvent.click(canvas.getByRole('button', { name: 'Role' }));
+    // The option list is portaled — query the document, not the canvas.
+    await userEvent.click(await body.findByRole('option', { name: 'Engineer' }));
+
+    // Valid submit delivers the narrowed payload to onSubmit.
+    await userEvent.click(canvas.getByRole('button', { name: 'Sign up' }));
+    await expect(canvas.getByText(/onSubmit received/)).toBeInTheDocument();
+  },
 };
 
 const LiveValidityDemo = () => {
@@ -193,6 +231,19 @@ export const LiveValidity: Story = {
       <LiveValidityDemo />
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Errors here are live — no submit gating.
+    await expect(canvas.getByText('false')).toBeInTheDocument();
+    await userEvent.type(canvas.getByLabelText(/^Nickname/), 'ab');
+    await expect(
+      canvas.getByText("'nickname' must be at least 3 characters"),
+    ).toBeInTheDocument();
+
+    await userEvent.type(canvas.getByLabelText(/^Nickname/), 'c');
+    await expect(canvas.getByText('true')).toBeInTheDocument();
+  },
 };
 
 type DebuggerDemoValues = {
@@ -300,4 +351,40 @@ export const WithDebugger: Story = {
       <DebuggerDemo />
     </div>
   ),
+  // The Debugger portals to <body>, so its trigger/window are queried on the
+  // document, not the canvas. Exercises open → live update → close, which
+  // also pins the stable-identity guarantee: a remounting Debugger would
+  // lose its open state on the first keystroke.
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    // Closed: trigger only, no window content.
+    await expect(body.queryByText('isValid')).not.toBeInTheDocument();
+
+    // Open: live state, including errors the form itself isn't showing yet
+    // (its display is submit-gated; the debugger sees the raw truth).
+    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"),
+    ).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.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();
+
+    // Close: window unmounts, trigger stays.
+    await userEvent.click(body.getByRole('button', { name: 'signup form' }));
+    await expect(body.queryByText('isValid')).not.toBeInTheDocument();
+  },
 };

package/src/forms/useFormState/useFormState.test-d.ts

@@ -58,6 +58,36 @@ describe('useFormState onSubmit narrowing — inline constraints', () => {
     });
   });
 
+  it('accepts a boolean field and narrows it through a marker excluding undefined', () => {
+    useFormState({
+      initialValues: {
+        agreed: undefined as boolean | undefined,
+        subscribed: false as boolean,
+      },
+      constraints: {
+        // notEmpty's marker excludes null | undefined | '' — on a
+        // boolean | undefined field that refines to plain boolean.
+        agreed: notEmpty('agreed'),
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{
+          agreed: boolean;
+          subscribed: boolean;
+        }>();
+      },
+    });
+  });
+
+  it('rejects a string validator on a boolean field', () => {
+    useFormState({
+      initialValues: { agreed: false },
+      constraints: {
+        // @ts-expect-error minLength validates strings, `agreed` is a boolean
+        agreed: minLength('agreed', 3),
+      },
+    });
+  });
+
   it('rejects constraints for keys not in the form type', () => {
     useFormState({
       initialValues: { a: '' },
@@ -155,6 +185,8 @@ type InsuranceQuoteForm = {
   discountCodes: string[];
   referralSource: string | null;
   notes: string | undefined;
+  agreedToTerms: boolean | undefined;
+  paperlessBilling: boolean;
 };
 
 describe('useFormState narrowing at realistic scale', () => {
@@ -173,17 +205,20 @@ describe('useFormState narrowing at realistic scale', () => {
         startDate: notEmpty('startDate'),
         referralSource: notEmpty('referralSource'),
         notes: minLength('notes', 10),
+        agreedToTerms: notEmpty('agreedToTerms'),
       },
       onSubmit: (values) => {
         // Refined: notEmpty strips null/undefined/'' from the union.
         expectTypeOf(values.firstName).toEqualTypeOf<string>();
         expectTypeOf(values.email).toEqualTypeOf<string>();
         expectTypeOf(values.referralSource).toEqualTypeOf<string>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
         // Constrained but non-refining validators leave the type alone.
         expectTypeOf(values.phone).toEqualTypeOf<string | undefined>();
         expectTypeOf(values.annualIncomeUsd).toEqualTypeOf<number | null>();
         expectTypeOf(values.notes).toEqualTypeOf<string | undefined>();
         // Unconstrained fields — including all nested structure — untouched.
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
         expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
         expectTypeOf(values.drivers).toEqualTypeOf<
           InsuranceQuoteForm['drivers']
@@ -201,9 +236,13 @@ describe('useFormState narrowing at realistic scale', () => {
     expectTypeOf<['homeAddress', 'city']>().toMatchTypeOf<P>();
     expectTypeOf<['drivers', number, 'incidents', number, 'claimAmountUsd']>().toMatchTypeOf<P>();
     expectTypeOf<['vehicles', number, 'garagingAddress', 'postalCode']>().toMatchTypeOf<P>();
+    expectTypeOf<['agreedToTerms']>().toMatchTypeOf<P>();
 
     expectTypeOf<
       ValueAt<InsuranceQuoteForm, ['drivers', number, 'incidents', number, 'claimAmountUsd']>
     >().toEqualTypeOf<number | null>();
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['agreedToTerms']>
+    >().toEqualTypeOf<boolean | undefined>();
   });
 });

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

@@ -108,6 +108,42 @@ describe('useFormState', () => {
     });
   });
 
+  test('a boolean field can be set, validated, and submitted', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues: {
+          email: 'a@b.co' as string | undefined,
+          agreed: false as boolean,
+        },
+        constraints: {
+          agreed: (val) => (val ? null : 'you must agree to the terms'),
+        },
+        onSubmit,
+      }),
+    );
+    expect(result.current.values.agreed).toBe(false);
+    expect(result.current.errors.agreed).toBe('you must agree to the terms');
+    expect(result.current.isValid).toBe(false);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, agreed: true }));
+    });
+    expect(result.current.errors.agreed).toBeUndefined();
+    expect(result.current.isValid).toBe(true);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co', agreed: true });
+  });
+
   test('a failed submit followed by a fix allows the next submit through', () => {
     const onSubmit = mock(() => {});
     const { result } = renderHook(() =>