@structuralists/scaffolding 0.11.0 → 0.12.0

package/src/forms/state/validations/walk.test.ts

@@ -5,27 +5,26 @@ const pass = () => null;
 const fail = (message: string) => () => message;
 
 describe('validateEntry — single validator', () => {
-  test('a passing validator yields no error', () => {
-    expect(validateEntry(pass, 'anything', ['a'])).toBeNull();
+  test('a passing validator yields no errors', () => {
+    expect(validateEntry(pass, 'anything', ['a'])).toEqual([]);
   });
 
   test('a failing validator yields its message at the given path', () => {
-    expect(validateEntry(fail('nope'), 'anything', ['a'])).toEqual({
-      path: ['a'],
-      error: 'nope',
-    });
+    expect(validateEntry(fail('nope'), 'anything', ['a'])).toEqual([
+      { path: ['a'], error: 'nope' },
+    ]);
   });
 
   test('the validator receives the field value', () => {
     const spy = mock((val: string) => (val === 'x' ? null : 'expected x'));
-    expect(validateEntry(spy, 'x', ['a'])).toBeNull();
+    expect(validateEntry(spy, 'x', ['a'])).toEqual([]);
     expect(spy).toHaveBeenCalledWith('x');
   });
 });
 
 describe('validateEntry — validator arrays', () => {
-  test('all passing yields no error', () => {
-    expect(validateEntry([pass, pass, pass], 'v', ['a'])).toBeNull();
+  test('all passing yields no errors', () => {
+    expect(validateEntry([pass, pass, pass], 'v', ['a'])).toEqual([]);
   });
 
   test('validators run in array order and the first error wins', () => {
@@ -34,7 +33,7 @@ describe('validateEntry — validator arrays', () => {
       'v',
       ['a'],
     );
-    expect(result).toEqual({ path: ['a'], error: 'second' });
+    expect(result).toEqual([{ path: ['a'], error: 'second' }]);
   });
 
   test('validators after the first failure are not called', () => {
@@ -46,20 +45,18 @@ describe('validateEntry — validator arrays', () => {
   test('every validator before the failure sees the value', () => {
     const first = mock(() => null);
     const second = mock(() => null);
-    expect(validateEntry([first, second], 42, ['n'])).toBeNull();
+    expect(validateEntry([first, second], 42, ['n'])).toEqual([]);
     expect(first).toHaveBeenCalledWith(42);
     expect(second).toHaveBeenCalledWith(42);
   });
 
   test('an empty array passes', () => {
-    expect(validateEntry([], undefined, ['a'])).toBeNull();
+    expect(validateEntry([], undefined, ['a'])).toEqual([]);
   });
 });
 
 describe('validateEntry — path accumulation', () => {
-  test('the error carries the path it was given, verbatim', () => {
-    // Phase 1 paths are single-key; the signature already speaks PathStep[]
-    // so the phases-2/3 {path, error}[] model needs no walk rewrite.
+  test('a leaf error carries the path it was given, verbatim', () => {
     const result = validateEntry(fail('bad date'), undefined, [
       'drivers',
       3,
@@ -67,9 +64,152 @@ describe('validateEntry — path accumulation', () => {
       0,
       'date',
     ]);
-    expect(result).toEqual({
-      path: ['drivers', 3, 'incidents', 0, 'date'],
-      error: 'bad date',
-    });
+    expect(result).toEqual([
+      { path: ['drivers', 3, 'incidents', 0, 'date'], error: 'bad date' },
+    ]);
+  });
+});
+
+describe('validateEntry — nested object specs', () => {
+  test('recurses into a nested spec, extending the path per key', () => {
+    const result = validateEntry(
+      { city: fail('city required') },
+      { city: undefined, line1: '1 Main St' },
+      ['homeAddress'],
+    );
+    expect(result).toEqual([
+      { path: ['homeAddress', 'city'], error: 'city required' },
+    ]);
+  });
+
+  test('a constrained leaf validator receives the leaf value, not the section', () => {
+    const spy = mock((val: string) => (val === 'SF' ? null : 'not SF'));
+    expect(
+      validateEntry({ city: spy }, { city: 'SF' }, ['homeAddress']),
+    ).toEqual([]);
+    expect(spy).toHaveBeenCalledWith('SF');
+  });
+
+  test('specs nest to arbitrary depth, accumulating the full address', () => {
+    const result = validateEntry(
+      { shipping: { address: { postalCode: fail('5 digits') } } },
+      { shipping: { address: { postalCode: 'abc' } } },
+      ['order'],
+    );
+    expect(result).toEqual([
+      {
+        path: ['order', 'shipping', 'address', 'postalCode'],
+        error: '5 digits',
+      },
+    ]);
+  });
+
+  test('sibling results are independent: every failing node gets its own entry', () => {
+    const result = validateEntry(
+      {
+        city: fail('city required'),
+        state: pass,
+        postalCode: fail('postalCode required'),
+      },
+      { city: undefined, state: 'CA', postalCode: undefined },
+      ['homeAddress'],
+    );
+    expect(result).toEqual([
+      { path: ['homeAddress', 'city'], error: 'city required' },
+      { path: ['homeAddress', 'postalCode'], error: 'postalCode required' },
+    ]);
+  });
+
+  test('a failing sibling does not stop validation of the others', () => {
+    const after = mock(() => null);
+    validateEntry(
+      { a: fail('boom'), b: after },
+      { a: 'x', b: 'y' },
+      ['section'],
+    );
+    expect(after).toHaveBeenCalledWith('y');
+  });
+
+  test('leaf and nested constraints mix inside one spec', () => {
+    const result = validateEntry(
+      {
+        name: [pass, fail('name too short')],
+        address: { city: fail('city required') },
+      },
+      { name: 'x', address: { city: undefined } },
+      ['applicant'],
+    );
+    expect(result).toEqual([
+      { path: ['applicant', 'name'], error: 'name too short' },
+      { path: ['applicant', 'address', 'city'], error: 'city required' },
+    ]);
+  });
+
+  test('a null child entry (possible from untyped JS) is skipped', () => {
+    const spec = { city: null } as unknown as {
+      city: (val: unknown) => string | null;
+    };
+    expect(validateEntry(spec, { city: undefined }, ['homeAddress'])).toEqual(
+      [],
+    );
+  });
+});
+
+describe('validateEntry — absent sections are skipped', () => {
+  test('a nested spec on an undefined section validates nothing', () => {
+    // Decided with the phase-2 type spike: the type level refines only the
+    // present branch of a nullable section, so the runtime mirror is to
+    // skip. A "required section" is a leaf validator on the section field.
+    const never = mock(() => 'never reached');
+    expect(validateEntry({ city: never }, undefined, ['mailingAddress'])).toEqual([]);
+    expect(never).not.toHaveBeenCalled();
+  });
+
+  test('a nested spec on a null section validates nothing', () => {
+    expect(validateEntry({ city: fail('x') }, null, ['mailingAddress'])).toEqual([]);
+  });
+
+  test('a leaf validator on an absent section still runs (the "required section" form)', () => {
+    expect(validateEntry(fail('section required'), undefined, ['mailingAddress'])).toEqual([
+      { path: ['mailingAddress'], error: 'section required' },
+    ]);
+  });
+
+  test('a nested spec on a non-object value (shape mismatch from untyped JS) is skipped', () => {
+    expect(validateEntry({ city: fail('x') }, 'not an object', ['homeAddress'])).toEqual([]);
+  });
+});
+
+describe('validateEntry — value-model disambiguation', () => {
+  test('an object value owning a key named `each` is walked as a nested spec', () => {
+    // The value directs interpretation, never the constraint's shape: this
+    // spec has a single key `each`, but the value is a plain object, so
+    // `each` is just a field like any other.
+    const result = validateEntry(
+      { each: fail('audit each required') },
+      { each: undefined, reviewedBy: 'wl' },
+      ['audit'],
+    );
+    expect(result).toEqual([
+      { path: ['audit', 'each'], error: 'audit each required' },
+    ]);
+  });
+});
+
+describe('validateEntry — list `each` specs (runtime pending, phase 3)', () => {
+  test('an `each` spec on a present list throws instead of silently not validating', () => {
+    expect(() =>
+      validateEntry(
+        { each: { name: fail('name required') } },
+        [{ name: undefined }],
+        ['drivers'],
+      ),
+    ).toThrow(/each.*not validated at runtime yet.*drivers/);
+  });
+
+  test('an `each` spec on a null list is skipped — nothing to walk, matching phase-3 semantics', () => {
+    expect(
+      validateEntry({ each: { insurer: fail('x') } }, null, ['pastPolicies']),
+    ).toEqual([]);
   });
 });

package/src/forms/state/validations/walk.ts

@@ -1,11 +1,11 @@
 import type { PathStep } from '../path/types';
 
 // The runtime walk over a constraints object, kept separate from the hook so
-// its semantics are unit-testable without React. Phase 1 grammar is flat —
-// every path has exactly one step — but errors already carry a `PathStep[]`
-// address, which the hook's structured `{path, error}[]` error model
-// (`FormErrors<T>`) consumes directly; the recursive grammar of plan phases
-// 2–3 just hands the walk longer paths, no second rewrite.
+// its semantics are unit-testable without React. The grammar is recursive
+// (nested object specs; list `each` specs arrive at runtime in plan phase 3),
+// so the walk is a tree walk: it accumulates a `PathStep[]` address as it
+// descends, and the hook's structured `{path, error}[]` error model
+// (`FormErrors<T>`) consumes those addresses directly.
 
 export type ValidationError = {
   readonly path: readonly PathStep[];
@@ -21,33 +21,94 @@ type AnyFieldValidator = (val: never) => string | null;
 // The walk's view of one entry in a `Validations<T>` object. This type is
 // what lets the compiler police the walk's assumptions: the error derivation
 // (`useFormState/deriveErrors.ts`) assigns `constraints[key]` to it WITHOUT
-// a cast, so when the grammar grows a form
-// that is neither a function nor an array of them (nested spec, list `each`),
-// that assignment stops compiling and the walk must learn the new form —
-// instead of a stale walk misinterpreting it at runtime.
-export type FlatConstraintEntry =
+// a cast, so if the grammar grows a form the walk doesn't understand, that
+// assignment stops compiling and the walk must learn the new form — instead
+// of a stale walk misinterpreting it at runtime. Both structural grammar
+// forms (a nested `Validations`, a `{ each: … }` list constraint) look the
+// same from here — an object of entries — because disambiguating them is the
+// walk's job, done against the VALUE at the path, never the constraint's
+// shape (see "Disambiguation" in plan.md).
+export type ConstraintEntry =
   | AnyFieldValidator
-  | readonly AnyFieldValidator[];
+  | readonly AnyFieldValidator[]
+  | ConstraintSpec;
 
-// Runs one constraint entry against the field value found at `path`.
-// Semantics for arrays (identical to `allOf`): validators run in array
+type ConstraintSpec = {
+  readonly [key: string]: ConstraintEntry | undefined;
+};
+
+// Runs one constraint entry against the field value found at `path`,
+// returning every failure in the entry's subtree (a structural spec can
+// produce one entry per failing constrained node; sibling results are
+// independent).
+//
+// Leaf semantics for arrays (identical to `allOf`): validators run in array
 // order, first error wins — later validators are not called once one fails.
 // An empty array passes, mirroring its refinement (`Exclude<F, never>`).
+//
+// Structural semantics — interpretation is directed by the value model:
+// - value is an array  ⇒ the spec is a `{ each: … }` list constraint.
+//   Runtime `each` walking is plan phase 3; until it lands the walk THROWS
+//   rather than silently not validating.
+// - value is an object ⇒ the spec is a nested `Validations`: recurse into
+//   each constrained key, extending the path. (An object field owning a key
+//   literally named `each` lands here — the value directs, so its spec is a
+//   nested spec like any other.)
+// - value is absent (null/undefined) ⇒ SKIP: a nested spec on an absent
+//   section validates nothing (decided with the type spike — the type level
+//   refines only the present branch of a nullable section, and this is the
+//   honest runtime mirror). A "required section" is a LEAF validator on the
+//   section field instead. A non-object value (unreachable through the typed
+//   grammar) has nothing to walk either, mirroring read()'s dead-step
+//   semantics.
+// Predicate (not inline checks) because `Array.isArray`'s `arg is any[]`
+// guard cannot remove a READONLY array member from its false branch — the
+// structural-spec arm below needs that removal to type `entry[key]`.
+const isLeafEntry = (
+  entry: ConstraintEntry,
+): entry is AnyFieldValidator | readonly AnyFieldValidator[] =>
+  typeof entry === 'function' || Array.isArray(entry);
+
 export const validateEntry = (
-  entry: FlatConstraintEntry,
+  entry: ConstraintEntry,
   value: unknown,
   path: readonly PathStep[],
-): ValidationError | null => {
-  const validators = typeof entry === 'function' ? [entry] : entry;
-
-  for (const validator of validators) {
-    // Safe: the constraints object was type-checked against the form type
-    // where it was built, so this validator accepts the value at `path`; the
-    // walk just can't see that correlation. Same honest contravariant
-    // widening as `allOf`'s part-call.
-    const error = (validator as (val: unknown) => string | null)(value);
-    if (error != null) return { path, error };
+): ValidationError[] => {
+  if (isLeafEntry(entry)) {
+    const validators = typeof entry === 'function' ? [entry] : entry;
+
+    for (const validator of validators) {
+      // Safe: the constraints object was type-checked against the form type
+      // where it was built, so this validator accepts the value at `path`;
+      // the walk just can't see that correlation. Same honest contravariant
+      // widening as `allOf`'s part-call.
+      const error = (validator as (val: unknown) => string | null)(value);
+      if (error != null) return [{ path, error }];
+    }
+
+    return [];
+  }
+
+  if (value == null || typeof value !== 'object') return [];
+
+  if (Array.isArray(value)) {
+    throw new Error(
+      `list 'each' constraints are not validated at runtime yet (forms plan ` +
+        `phase 3) — constraint at path [${path.join(', ')}]`,
+    );
+  }
+
+  const errors: ValidationError[] = [];
+  for (const key of Object.keys(entry)) {
+    const child = entry[key];
+    if (child == null) continue;
+    errors.push(
+      ...validateEntry(child, (value as Record<string, unknown>)[key], [
+        ...path,
+        key,
+      ]),
+    );
   }
 
-  return null;
+  return errors;
 };

package/tokens.css

@@ -43,6 +43,13 @@
      shadow-soft     — gentler lift (hover elevation, cards)
      backdrop        — modal overlay tint behind dialogs
 
+   JSON syntax (Chrome-inspector-style value coloring in JsonTable)
+     json-key        — object keys / array indices (low salience)
+     json-string     — string leaves (rendered with quotes)
+     json-number     — number leaves
+     json-boolean    — boolean leaves
+     json-nil        — null / undefined leaves
+
    These values are scaffolds, not final design. Revise deliberately.
 --------------------------------------------------------------------------- */
 
@@ -112,6 +119,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.15);
   --ui-shadow-soft: rgba(0, 0, 0, 0.08);
   --ui-backdrop: rgba(30, 28, 25, 0.35);
+
+  --ui-json-key: #6c6761;
+  --ui-json-string: #a05419;
+  --ui-json-number: #4966a9;
+  --ui-json-boolean: #8a35a0;
+  --ui-json-nil: #a74c4c;
 }
 
 /* System preference: dark → fall back to dark-warm when no data-theme is set.
@@ -140,6 +153,12 @@
     --ui-shadow: rgba(0, 0, 0, 0.5);
     --ui-shadow-soft: rgba(0, 0, 0, 0.3);
     --ui-backdrop: rgba(0, 0, 0, 0.55);
+
+    --ui-json-key: #a89f90;
+    --ui-json-string: #e6a268;
+    --ui-json-number: #8aa5d8;
+    --ui-json-boolean: #c98ad5;
+    --ui-json-nil: #f0a39e;
   }
 }
 
@@ -170,6 +189,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.15);
   --ui-shadow-soft: rgba(0, 0, 0, 0.08);
   --ui-backdrop: rgba(30, 28, 25, 0.35);
+
+  --ui-json-key: #6c6761;
+  --ui-json-string: #a05419;
+  --ui-json-number: #4966a9;
+  --ui-json-boolean: #8a35a0;
+  --ui-json-nil: #a74c4c;
 }
 
 [data-theme='light-paper'] {
@@ -195,6 +220,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.12);
   --ui-shadow-soft: rgba(0, 0, 0, 0.06);
   --ui-backdrop: rgba(20, 20, 20, 0.35);
+
+  --ui-json-key: #636360;
+  --ui-json-string: #9b4f16;
+  --ui-json-number: #4461a3;
+  --ui-json-boolean: #8a35a0;
+  --ui-json-nil: #a14747;
 }
 
 [data-theme='light-sepia'] {
@@ -220,6 +251,12 @@
   --ui-shadow: rgba(70, 50, 20, 0.18);
   --ui-shadow-soft: rgba(70, 50, 20, 0.09);
   --ui-backdrop: rgba(50, 35, 15, 0.4);
+
+  --ui-json-key: #6a5e45;
+  --ui-json-string: #954a10;
+  --ui-json-number: #3a5da0;
+  --ui-json-boolean: #7a2a8a;
+  --ui-json-nil: #9a4444;
 }
 
 [data-theme='dark-warm'] {
@@ -245,6 +282,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.5);
   --ui-shadow-soft: rgba(0, 0, 0, 0.3);
   --ui-backdrop: rgba(0, 0, 0, 0.55);
+
+  --ui-json-key: #a89f90;
+  --ui-json-string: #e6a268;
+  --ui-json-number: #8aa5d8;
+  --ui-json-boolean: #c98ad5;
+  --ui-json-nil: #f0a39e;
 }
 
 [data-theme='dark-neutral'] {
@@ -270,6 +313,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.5);
   --ui-shadow-soft: rgba(0, 0, 0, 0.3);
   --ui-backdrop: rgba(0, 0, 0, 0.6);
+
+  --ui-json-key: #a0a0a0;
+  --ui-json-string: #e29964;
+  --ui-json-number: #8ab0e0;
+  --ui-json-boolean: #c990d6;
+  --ui-json-nil: #ea9a9a;
 }
 
 [data-theme='dark-dimmed'] {
@@ -295,6 +344,12 @@
   --ui-shadow: rgba(0, 0, 0, 0.4);
   --ui-shadow-soft: rgba(0, 0, 0, 0.25);
   --ui-backdrop: rgba(0, 0, 0, 0.55);
+
+  --ui-json-key: #8a91a0;
+  --ui-json-string: #d99970;
+  --ui-json-number: #8ab0e0;
+  --ui-json-boolean: #c08adc;
+  --ui-json-nil: #e89898;
 }
 
 /* ---------------------------------------------------------------------------