@structuralists/scaffolding 0.10.1 → 0.11.0

package/eslint.config.mjs

@@ -7,8 +7,11 @@ import tsParser from '@typescript-eslint/parser';
 // Component primitives live under src/components/<Section>/<Component>/.
 // "Umbrella sections" (Modals, Chat) are themselves the primitive — their
 // sub-folders share internals and must be reached through the section barrel.
-// Plain sections (Layout, Content, Forms, ...) treat each component folder as
-// its own primitive.
+// Plain sections (Layout, Content, ...) treat each component folder as its
+// own primitive. Form elements live under src/forms/elements/<Component>/ and
+// follow the same per-folder primitive shape; the form-state layer
+// (src/forms/state/) is one element with no barrel — its modules import each
+// other file-directly.
 //
 // Three element types so rules can distinguish roles inside a primitive:
 //   - primitive-entry   → the barrel (`<primitive>/index.{ts,tsx}`)
@@ -33,6 +36,34 @@ export default [{
     },
     'boundaries/include': ['src/**/*'],
     'boundaries/elements': [
+      // Form-element primitives (src/forms/elements/<Component>/) — same
+      // shape and rules as plain-section component primitives.
+      {
+        type: 'primitive-entry',
+        pattern: 'src/forms/elements/*/index.{ts,tsx}',
+        mode: 'full',
+        capture: ['name'],
+      },
+      {
+        type: 'primitive-dogfood',
+        pattern: 'src/forms/elements/*/**/*.{stories,test}.{ts,tsx}',
+        mode: 'full',
+        capture: ['name'],
+      },
+      {
+        type: 'primitive',
+        pattern: 'src/forms/elements/*',
+        mode: 'folder',
+        capture: ['name'],
+      },
+      // The form-state layer, as a single element. No barrel: its modules
+      // (useFormState, validations, validators, path) import each other
+      // file-directly by design.
+      {
+        type: 'forms-state',
+        pattern: 'src/forms/state',
+        mode: 'folder',
+      },
       // Plain-section component primitives (depth-3 under src/components)
       {
         type: 'primitive-entry',
@@ -100,6 +131,29 @@ export default [{
             message:
               "Files inside a primitive folder must not import their own index barrel; import the neighbor directly.",
           },
+          // Presentational primitives (components and form elements) must
+          // not reach into the form-state layer. The sanctioned bridges run
+          // the other way: state's FormDebugger imports the JsonTable barrel
+          // (dev tooling), and the form-aware wrappers live on the state
+          // side (state/bindings/). State stories may also use element barrels.
+          {
+            from: [
+              { type: 'primitive' },
+              { type: 'primitive-entry' },
+              { type: 'primitive-dogfood' },
+            ],
+            disallow: [{ to: { type: 'forms-state' } }],
+            message:
+              'Form elements and components must not import the form-state layer; the bridge layer lives on the state side.',
+          },
+          // When state files import a component/element primitive (the
+          // sanctioned bridge direction), they go through its barrel like
+          // any other external importer.
+          {
+            from: [{ type: 'forms-state' }],
+            disallow: [{ to: { type: 'primitive' } }],
+            message: "External imports must go through the folder's index barrel.",
+          },
         ],
       },
     ],

package/package.json

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

package/src/components/Chat/ChatRecipientsHeader/ChatRecipientsHeader.stories.tsx

@@ -3,10 +3,10 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ChatRecipientsHeader } from './index';
 import type { PillComboboxOption } from '../PillCombobox/types';
 import { Stack } from '../../Layout/Stack';
-import { Textarea } from '../../Forms/Textarea';
-import { Input } from '../../Forms/Input';
-import { Field } from '../../Forms/Field';
-import { Button } from '../../Forms/Button';
+import { Textarea } from '../../../forms/elements/Textarea';
+import { Input } from '../../../forms/elements/Input';
+import { Field } from '../../../forms/elements/Field';
+import { Button } from '../../../forms/elements/Button';
 import { MediumModal } from '../../Modals';
 import { Toggle } from '../../../storybook';
 

package/src/components/Layout/Bar/Bar.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Bar } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Debug } from '../Debug';
 
 const meta: Meta<typeof Bar> = {

package/src/components/Layout/Panels/Panels.stories.tsx

@@ -2,7 +2,7 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Panels } from './index';
 import { Bar } from '../Bar';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Text } from '../../Content/Text';
 import { Heading } from '../../Content/Heading';
 import { Stack } from '../Stack';

package/src/components/Layout/Stack/Stack.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Stack } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 
 const meta: Meta<typeof Stack> = {
   title: 'Layout/Stack',

package/src/components/Modals/LargeModal/LargeModal.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { LargeModal } from './index';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Stack } from '../../Layout/Stack';
 import { Text } from '../../Content/Text';
 import { Lorem, Toggle } from '../../../storybook';

package/src/components/Modals/MediumModal/MediumModal.stories.tsx

@@ -1,8 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { MediumModal } from './index';
-import { Button } from '../../Forms/Button';
-import { Field } from '../../Forms/Field';
-import { Input } from '../../Forms/Input';
+import { Button } from '../../../forms/elements/Button';
+import { Field } from '../../../forms/elements/Field';
+import { Input } from '../../../forms/elements/Input';
 import { Stack } from '../../Layout/Stack';
 import { Text } from '../../Content/Text';
 import { Lorem, Toggle } from '../../../storybook';

package/src/components/Modals/internal/ModalHeader.tsx

@@ -1,4 +1,4 @@
-import { IconButton } from '../../Forms/IconButton';
+import { IconButton } from '../../../forms/elements/IconButton';
 import styles from './styles.module.css';
 
 type Props = {

package/src/components/Overlays/Popover/Popover.stories.tsx

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useRef, useState } from 'react';
 import { Popover } from './index';
-import { Button } from '../../Forms/Button';
-import { Input } from '../../Forms/Input';
-import { Field } from '../../Forms/Field';
+import { Button } from '../../../forms/elements/Button';
+import { Input } from '../../../forms/elements/Input';
+import { Field } from '../../../forms/elements/Field';
 import { Text } from '../../Content/Text';
 const meta: Meta<typeof Popover> = {
   title: 'Overlays/Popover',

package/src/components/Overlays/Tooltip/Tooltip.stories.tsx

@@ -1,7 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Tooltip } from './index';
 import type { TooltipPlacement } from './types';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 
 const meta: Meta<typeof Tooltip> = {
   title: 'Overlays/Tooltip',

package/src/components/Tables/BigTable/BigTable.stories.tsx

@@ -17,7 +17,7 @@ import { LinedStack } from '../../Primitives/LinedStack';
 import { LongText } from '../../Primitives/LongText';
 import { Panels } from '../../Layout/Panels';
 import { Bar } from '../../Layout/Bar';
-import { Button } from '../../Forms/Button';
+import { Button } from '../../../forms/elements/Button';
 import { Heading } from '../../Content/Heading';
 import { Stack } from '../../Layout/Stack';
 

package/src/forms/CLAUDE.md

@@ -1,9 +1,25 @@
 # src/forms
 
-Strongly-typed React form state hook. The headline feature is **validation that
-propagates type refinements to the submit handler** — passing the right
-constraints means the submit handler's `values` argument has a tighter type
-than the initial form values.
+The forms umbrella, split into two named subtrees:
+
+- `elements/` — the presentational form elements (`Input`, `Field`, `Select`,
+  `Button`, `Textarea`, …), one component primitive per folder, same shape
+  and eslint-boundaries rules as `src/components/<Section>/<Component>/`.
+  Elements are state-free: they must not import the state layer (enforced by
+  eslint `boundaries`).
+- `state/` — the strongly-typed React form state hook and its machinery.
+  Everything below this heading is about the state layer.
+
+Two sanctioned state→elements-side bridges exist, both on the state side:
+the Debugger (`state/useFormState/FormDebugger.tsx` imports the `JsonTable`
+barrel from `src/components/Json/`, dev tooling) and the form-aware element
+wrappers (`state/bindings/` — see "Field binding" below). State files
+importing an element go through its barrel like any external importer.
+
+The headline feature of the state layer is **validation that propagates type
+refinements to the submit handler** — passing the right constraints means the
+submit handler's `values` argument has a tighter type than the initial form
+values.
 
 ## Mental model
 
@@ -185,12 +201,75 @@ exposed:
 errorAt(errors, ['email']); // string | undefined
 ```
 
-`errorAt` (useFormState/errorAt.ts) matches by exact structural step
-equality (no prefix matching); with first-error-wins validation there is at
-most one entry per path, and if collect-all ever lands the first entry stays
-the one shown. The path-addressed model is what the recursive grammar
-(errors just carry longer paths) and `getFormFieldPropsAt`'s `errorMessage`
-build on.
+`errorAt` (state/useFormState/errorAt.ts) matches by exact structural step
+equality (`pathsEqual` in state/path/path.ts — no prefix matching); with
+first-error-wins validation there is at most one entry per path, and if
+collect-all ever lands the first entry stays the one shown. The
+path-addressed model is what the recursive grammar (errors just carry
+longer paths) and `getFormFieldPropsAt`'s `errorMessage` build on. `errorAt`
+is raw truth (no display gating); `errorMessage` is the display-policy-aware
+reading (see "Field binding").
+
+## Field binding: `getFormFieldPropsAt(path)` + `state/bindings/`
+
+One expression wires a field to the form:
+
+```tsx
+<TextInputForForm label="City"
+  formFieldProps={getFormFieldPropsAt(['homeAddress', 'city'])} />
+```
+
+`getFormFieldPropsAt` is a member of the hook's return value, typed by the
+`state/path/` machinery:
+
+```ts
+// on FormHelpers<T>:
+getFormFieldPropsAt<P extends Path<T>>(path: P): FormFieldProps<ValueAt<T, P>>;
+
+type FormFieldProps<V> = FieldBinding<V>;
+type FieldBinding<Display, Emit = Display> = {
+  value: Display;                   // read(values, path)
+  onChange: (val: Emit) => void;    // immutable write(values, path, val)
+  errorMessage: string | undefined; // display-policy-aware (below)
+  onBlur: () => void;               // feeds touched tracking
+};
+```
+
+The pieces, and where each one's semantics live:
+
+- **Granular path writes** — `write()` in `state/path/path.ts`, the
+  immutable-update mirror of `read()`: clones only the spine to the written
+  leaf, so untouched siblings keep identity. Dead-step semantics mirror
+  read() returning undefined: writing through an absent/null ancestor, a
+  shape mismatch, or an out-of-bounds index is an identity-preserving no-op
+  — you can't edit a field of an absent section; materialize the section
+  first. (Appending/splicing lists is item-8 territory, not a path write.)
+  `onValueChanges` (whole-value replacement) still exists but is no longer
+  the only write path.
+- **Touched tracking** — real state in `useFieldBinding`: a `Path<T>[]`
+  compared with `pathsEqual`, fed by `onBlur`, visible in the Debugger
+  snapshot. Commit-style elements (selects) call `onBlur` on commit — the
+  commit IS their blur moment.
+- **THE error-display policy** lives inside `errorMessage` and nowhere
+  else: show a field's error once the field is touched OR a submit has been
+  attempted. Elements render what they're given and stay policy-free. A UI
+  wanting a different policy (e.g. always-live) reads `errors`/`errorAt`
+  directly.
+
+### The element wrappers (`state/bindings/`)
+
+The **wrapper style** is the prototyped shorthand (per the plan's deciding
+criterion — simplest for agents to work with): `TextInputForForm` and
+`SingleSelectForForm` compose `Field` (label/hint/error presentation)
+around the element and accept the bundle as one `formFieldProps` prop.
+The wrapper declares what it can display and emit via
+`FieldBinding<Display, Emit>` — e.g. the text input takes
+`FieldBinding<string | null | undefined, string>` — and a
+`FormFieldProps<V>` is assignable exactly when `Emit ⊆ V ⊆ Display`. That
+one structural check is the end-to-end type safety: binding a number- or
+boolean-typed path (or a literal-union field, for free text) to a
+text-shaped element fails to compile at the `formFieldProps` prop, with no
+generics at the use site.
 
 ## Union policy — what form state may hold
 
@@ -222,7 +301,7 @@ in three layers:
 1. **At the `useFormState` boundary**: an illegal form type makes the call
    fail with an unsatisfiable `'ERROR: form state disallows unions of
    objects/lists …'` property whose type names the offending keys
-   (`UnionPolicyCheck<T>` in `useFormState/types.ts`).
+   (`UnionPolicyCheck<T>` in `state/useFormState/types.ts`).
 2. **`Path<T>` refuses to descend** into a disallowed union — the field
    stays addressable as a leaf (reading it yields the union, which is
    honest), but no paths below it exist, so `.at(…)`/path literals into it
@@ -292,12 +371,13 @@ precision end-to-end. So we wire it up before adding any consumers.
 
 ## Layout
 
-- `useFormState/` — the hook + the value-model types (`FormValueSimple`,
+- `state/useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
-  onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`.
+  onValueChanges, errors, isValid, submitAttempted, submit,
+  getFormFieldPropsAt, Debugger }`.
   `useFormState.ts` itself is deliberately **plumbing only**: it holds the
-  values `useState` (a bare `useState` today; granular path-based setters
-  are what would earn values state a module of its own), links up the
+  values `useState` (a bare `useState`; the granular path writes layer on
+  top of its setter via `useFieldBinding`), links up the
   modules below, and recomposes their outputs into `FormHelpers<T>`. Each
   slice lives in its own file so it is independently comprehensible and
   unit-testable at its own boundary:
@@ -308,13 +388,19 @@ precision end-to-end. So we wire it up before adding any consumers.
     (React-free) derivation of the structured `FormErrors<T>` list (see
     "The error model"), re-run every render (validators are pure and
     cheap); `isValid` is its emptiness, derived inline in the hook. Its
-    loop delegates per-entry semantics to `validations/walk.ts` and
+    loop delegates per-entry semantics to `state/validations/walk.ts` and
     carries two documented honest widenings: the `Object.keys` cast, and
     `failure.path as Path<T>` — `[key]` is a valid single-key `Path<T>`,
     but TS cannot compute `Path<T>` for an unresolved generic `T` to see
     the correlation. It also hosts the cast-free `FlatConstraintEntry`
-    assignment that polices grammar growth (see the `validations/` bullet).
+    assignment that polices grammar growth (see the `state/validations/` bullet).
   - `errorAt.ts` — the typed error lookup.
+  - `useFieldBinding.ts` — field binding: owns the touched list and builds
+    `getFormFieldPropsAt` (see "Field binding" above — the error-display
+    policy lives here). Two documented honest casts correlate `read()`/
+    `write()` results with `ValueAt<T, P>`/`T` for generic `T`; both are
+    truths the runtime upholds by construction, same family as `errorAt`'s
+    path widening.
   - `useFormSubmit.ts` — submit orchestration: owns `submitAttempted`
     (lets UIs gate error display) and the validity gate in front of
     `onSubmit`; its `submit()` performs the one honest *refinement* cast
@@ -333,18 +419,20 @@ precision end-to-end. So we wire it up before adding any consumers.
     subscribes (`useSyncExternalStore`), so an unused Debugger costs
     ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
     can render.
-- `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
-  Will be used for granular setters and for surfacing per-field
-  errors/touched state. Coupled to the form value model intentionally.
+- `state/path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`,
+  `read()`), plus `write()` (the immutable-update mirror of `read()` behind
+  granular field writes) and `pathsEqual` (the one definition of structural
+  path equality — `errorAt` and touched tracking both use it). Coupled to
+  the form value model intentionally.
   Union handling is governed by the "Union policy" section above; the
   policy's type-level guts (`IsDisallowedFormUnion`, `UnionPolicyCheck`,
-  `DisallowedFormUnion`) live with the value model in `useFormState/types.ts`.
-- `validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
+  `DisallowedFormUnion`) live with the value model in `state/useFormState/types.ts`.
+- `state/validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
   `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the runtime walk the
   hook delegates to (`validateEntry`). `Validations<T>` accepts bare
   `(val) => string | null` functions too — they simply narrow nothing.
   The walk's entry type (`FlatConstraintEntry`) is how the compiler polices
-  the error loop in `useFormState/deriveErrors.ts`: `constraints[key]` is
+  the error loop in `state/useFormState/deriveErrors.ts`: `constraints[key]` is
   *assigned* to it, never cast,
   so a grammar form the walk doesn't understand (a nested spec, an `each`)
   is a compile error at the assignment — a cast there would silently accept
@@ -352,7 +440,10 @@ precision end-to-end. So we wire it up before adding any consumers.
   function). Keep it cast-free. The one widening cast inside `validateEntry`
   mirrors `allOf`'s part-call: honest contravariant widening of a single,
   already-normalized validator.
-- `validators/` — the standard-library validators (`notEmpty`, `minLength`,
+- `state/bindings/` — the form-aware element wrappers (`TextInputForForm`,
+  `SingleSelectForForm`), the second sanctioned state→elements bridge (see
+  "Field binding" above). Element imports go through the element barrels.
+- `state/validators/` — the standard-library validators (`notEmpty`, `minLength`,
   `matches`, `min`) plus `allOf`, which composes validators on one field and
   carries the union of the parts' refinements. `allOf` derives its input type
   as the intersection of the parts' inputs from the const tuple (not a

package/src/{components/Forms → forms/elements}/Button/Button.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Button } from './index';
-import { Stack } from '../../Layout/Stack';
+import { Stack } from '../../../components/Layout/Stack';
 
 const meta: Meta<typeof Button> = {
   title: 'Forms/Button',

package/src/{components/Forms → forms/elements}/IconButton/index.tsx

@@ -1,5 +1,5 @@
 import { cx } from '../../../utils';
-import { Tooltip } from '../../Overlays/Tooltip';
+import { Tooltip } from '../../../components/Overlays/Tooltip';
 import type {
   IconButtonProps,
   IconButtonSize,

package/src/{components/Forms → forms/elements}/Input/index.tsx

@@ -14,6 +14,7 @@ export const Input = (props: InputProps) => {
     value,
     defaultValue,
     onChange,
+    onBlur,
     placeholder,
     required,
     autoFocus,
@@ -29,6 +30,7 @@ export const Input = (props: InputProps) => {
       value={value}
       defaultValue={defaultValue}
       onChange={onChange}
+      onBlur={onBlur}
       placeholder={placeholder}
       required={required}
       autoFocus={autoFocus}

package/src/{components/Forms → forms/elements}/Input/types.ts

@@ -1,4 +1,4 @@
-import type { ChangeEventHandler } from 'react';
+import type { ChangeEventHandler, FocusEventHandler } from 'react';
 
 export type InputSize = 'small' | 'medium';
 export type InputType = 'text' | 'email' | 'password';
@@ -9,6 +9,7 @@ export type InputProps = {
   value?: string;
   defaultValue?: string;
   onChange?: ChangeEventHandler<HTMLInputElement>;
+  onBlur?: FocusEventHandler<HTMLInputElement>;
   placeholder?: string;
   required?: boolean;
   autoFocus?: boolean;

package/src/{components/Forms → forms/elements}/Select/MultiSelect/MultiSelect.stories.tsx

@@ -2,8 +2,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
 import { MultiSelect } from './index';
 import { Field } from '../../Field';
-import { Stack } from '../../../Layout/Stack';
-import { Text } from '../../../Content/Text';
+import { Stack } from '../../../../components/Layout/Stack';
+import { Text } from '../../../../components/Content/Text';
 
 const meta: Meta<typeof MultiSelect> = {
   title: 'Forms/MultiSelect',

package/src/{components/Forms → forms/elements}/Select/MultiSelect/index.tsx

@@ -1,5 +1,5 @@
 import { useRef, useState } from 'react';
-import { Popover } from '../../../Overlays/Popover';
+import { Popover } from '../../../../components/Overlays/Popover';
 import { OptionList } from '../internal/OptionList';
 import { SelectTrigger } from '../internal/SelectTrigger';
 import type { MultiSelectProps } from './types';

package/src/{components/Forms → forms/elements}/Select/SingleSelect/SingleSelect.stories.tsx

@@ -3,9 +3,9 @@ import { useState } from 'react';
 import { SingleSelect } from './index';
 import { Button } from '../../Button';
 import { Field } from '../../Field';
-import { MediumModal } from '../../../Modals';
-import { Stack } from '../../../Layout/Stack';
-import { Text } from '../../../Content/Text';
+import { MediumModal } from '../../../../components/Modals';
+import { Stack } from '../../../../components/Layout/Stack';
+import { Text } from '../../../../components/Content/Text';
 import { Toggle } from '../../../../storybook';
 
 const meta: Meta<typeof SingleSelect> = {

package/src/{components/Forms → forms/elements}/Select/SingleSelect/index.tsx

@@ -1,5 +1,5 @@
 import { useRef, useState } from 'react';
-import { Popover } from '../../../Overlays/Popover';
+import { Popover } from '../../../../components/Overlays/Popover';
 import { OptionList } from '../internal/OptionList';
 import { SelectTrigger } from '../internal/SelectTrigger';
 import type { SingleSelectProps } from './types';