@structuralists/scaffolding 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.6.1",
+  "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.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(() =>