@mhmo91/schmancy 0.10.15 → 0.10.16

package/dist/skills/autocomplete.md

@@ -20,13 +20,18 @@
 | name | string | `''` | Form submission name |
 | required | boolean | `false` | Whether selection is required |
 | multi | boolean | `false` | Enable multi-select with inline chips |
-| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height (M3 sizes 24–56dp). |
 | maxHeight | string | `'300px'` | Max dropdown height |
 | debounceMs | number | `200` | Search debounce in ms |
 | similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
-| error | boolean | `false` | Error state |
-| validationMessage | string | `''` | Validation message |
+| error | boolean | `false` | Error state (gated by `validateOn`). From `SchmancyFormField`. |
+| validationMessage | string | `''` | Validation message. |
 | description | string | `''` | Screen reader description |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. |
+| disabled | boolean | `false` | Disabled state. |
+| hint | string | `undefined` | Helper text below the field. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
+| autocomplete | string | `'off'` | Native autocomplete attribute on inner input. |
 
 ## Events
 | Event | Detail | Description |
@@ -51,3 +56,11 @@
 ```
 
 Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.
+
+## Form-field contract
+
+Extends `SchmancyFormField()`. Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`, `resetForm()` (resets the BehaviorSubjects + clears the input).
+
+Default `validateOn: 'dirty'` — a required-empty autocomplete shows no error until the user types-then-clears or submits. Error UI rendered in a `role="alert"` div linked via `aria-describedby`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/button.md

@@ -40,6 +40,25 @@
 - Hover: luminous glow shadow using primary color
 - Active: spring press `scale(0.97)` / `scale(0.92)` for icon-button
 
+## Submit-state mirroring (`type="submit"` only)
+
+A `<schmancy-button type="submit">` inside a `<schmancy-form>` automatically reflects the form's submit state via a MutationObserver on the form's `aria-busy` attribute:
+
+- While the form's `formSubmitState.status === 'submitting'` (form sets `aria-busy="true"`):
+  - Button mirrors `aria-busy="true"` onto itself.
+  - Broadcasts `:state(submitting)` for CSS targeting.
+  - **Stays focusable** — never gets the `disabled` attribute. Disabled buttons drop from the tab order; AT users would lose their place. WCAG 2.2 AA.
+- Cleared automatically when the form's submit promise settles (success or error).
+
+```css
+schmancy-button:state(submitting) {
+  opacity: 0.6;
+  /* show a spinner via ::before, swap label, etc. */
+}
+```
+
+`schmancy-button` is form-associated (`static formAssociated = true` + `attachInternals()`) — clicking a `type="submit"` inside any `<form>` ancestor (native or schmancy) calls `form.requestSubmit()`. Inside `<schmancy-form>` the click is also intercepted at the form host and bridged across the shadow boundary to the inner shadow-DOM `<form>`.
+
 ## Examples
 ```html
 <!-- Filled primary -->

package/dist/skills/checkbox.md

@@ -18,6 +18,14 @@
 | disabled | boolean | `false` | Whether the checkbox is disabled |
 | required | boolean | `false` | Whether the checkbox is required |
 | size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Checkbox size |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. From `SchmancyFormField`. |
+| validationMessage | string | `''` | Error text — default `'Please check this box if you want to proceed.'` when required and unchecked. |
+| error | boolean | `false` | Error state (gated by `validateOn`). |
+| hint | string | `undefined` | Helper text. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
+
+## Attributes
+- `true-value` — string written to FormData when checked. Default `'on'` (matches native checkbox semantics).
 
 ## Events
 | Event | Detail | Description |
@@ -33,4 +41,15 @@
 <schmancy-checkbox name="terms" required>
   Accept <a href="/terms">terms and conditions</a>
 </schmancy-checkbox>
+
+<!-- Custom FormData string -->
+<schmancy-checkbox name="newsletter" true-value="opt-in"></schmancy-checkbox>
 ```
+
+## Form-field contract
+
+Extends `SchmancyFormField()`. `value` is the boolean state; FormData submission uses the `true-value` attribute (or `'on'`). Validity overrides the mixin's "non-empty value" semantics: required + unchecked → `internals.setValidity({ valueMissing: true })`. ARIA `aria-invalid` / `aria-required` reflect through `ElementInternals`.
+
+Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `setCustomValidity()`, `resetForm()`. Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/date-range.md

@@ -27,6 +27,12 @@
 | collapse | boolean | `false` | Icon-only on mobile |
 | customPresets | array | `[]` | Additional preset ranges |
 | format | string | auto | Date format string |
+| name | string | `''` | Form submission name. From `SchmancyFormField`. |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. |
+| validationMessage | string | `''` | Error message — default `'Please select a date range.'` when required and either bound is empty. |
+| error | boolean | `false` | Error state (gated by `validateOn`). |
+| hint | string | `undefined` | Helper text. |
+| touched / dirty / submitted | boolean | — | Validation state. `dirty` tracks `dateFrom.value` / `dateTo.value` against the snapshots taken at first render. |
 
 ## Events
 | Event | Detail | Description |
@@ -48,3 +54,16 @@
 ```
 
 Built-in presets include Today, Yesterday, This Week, This Month, This Year, and more.
+
+## Form association
+
+Extends `SchmancyFormField()`. Multi-entry FormData contribution:
+- Set `name="dates"` and FormData receives **two** keys: `datesFrom` and `datesTo` (flat suffix shape, no bracket-key encoding).
+- `internals.setFormValue(formData)` accepts a `FormData` object whose entries get appended to the parent form — native `new FormData(form)` sees both keys without consumer-side parsing.
+- `<schmancy-form>`'s registry consumer also sees both keys via `toFormEntries()`.
+
+`resetForm()` restores both `dateFrom.value` and `dateTo.value` to the snapshots captured at first render. Validity: required + either bound empty → `internals.setValidity({ valueMissing: true })`. Order/range constraints (start ≤ end, future-only, etc.) are out of scope — handle those in a domain schema layer.
+
+Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `setCustomValidity()`, `resetForm()`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/form-ux-rules.md

@@ -0,0 +1,55 @@
+# Form UX rules — Revolute pattern → schmancy mixin API
+
+This is the mapping between the Revolute interview-bar form UX (the source-of-truth checklist for state-of-the-art form behaviour) and the `SchmancyFormField()` API that implements each rule. When you hit a UX question, find the rule here and use the named API — don't re-derive from scratch.
+
+## The four-phase validation contract
+
+| Phase | UX rule | Implementation |
+|---|---|---|
+| 1 — Pristine | A field the user hasn't typed in shows no error, even if focused-then-blurred. The autofocus+cancel anti-pattern (focus a required field, click cancel, see "required") is forbidden. | `validateOn: 'dirty'` (default). `_shouldShowError()` returns `false` while `dirty === false`. |
+| 2 — Dirty | User types and blurs → validate the field. Show error only if invalid. Empty required fields blurred-without-typing remain pristine. | `markTouched()` called on blur. Mixin's `willUpdate` sees `touched` change, sees `dirty` is true, calls `checkValidity()` which sets `this.error` because the gate is open. |
+| 3 — Live correction | User returns to a field with an error → re-validate on every keystroke. Error clears immediately when valid. | Mixin's `willUpdate` re-runs `checkValidity()` on every value change while `_shouldShowError()` is true. |
+| 4 — Submit | Submit click → validate **all** fields regardless of dirty. Focus the first invalid field. | `<schmancy-form>` calls `markSubmitted()` on every registered field. `submitted = true` overrides every `validateOn` mode and forces error display. The form then focuses the first field with `error === true`. |
+
+After Phase 4, the field stays in Phase 3 (live re-validation) for the rest of the session because `submitted` persists until `resetForm()`.
+
+## Per-rule cross-reference
+
+| UX rule | API | Notes |
+|---|---|---|
+| Default mode is "errors after the user has interacted" | `validateOn: 'dirty'` | Pristine fields stay clean; submit forces all errors. |
+| Live search shows errors immediately | `validateOn="always"` | Bypass the dirty/touched gate entirely. |
+| Wizard step holds errors until Next | `validateOn="submitted"` | Only `markSubmitted()` opens the gate. |
+| Server-side error → specific field | `form.setFieldError(name, msg)` | RHF `setError` parity. Sets custom validity + marks submitted so the error shows. |
+| Server-side error → form banner | `form.setFormError(msg, code?)` | Flips `formSubmitState` to `{ status: 'error', error: { message, code } }`. Top-of-form banners read this. |
+| Async server-side check gating submit | `e.detail.until(promise)` | Form's `submit` event detail. Submit status reflects the promise outcome (`success` on resolve, `error` on reject). |
+| Submit button must stay focusable while busy | `aria-busy="true"` on the host (auto) + `:state(submitting)` on `<schmancy-button[type=submit]>` (auto) | WCAG 2.2 AA. Disabled buttons drop from the tab order; we never disable. |
+| Screen reader announces invalid fields | `internals.ariaInvalid` (auto) + `internals.ariaRequired` (auto) | Reflected through `ElementInternals` so AT reaches into shadow DOM. Not on the host as `aria-*` attributes. |
+| Reset returns the form to pristine | `<schmancy-button type="reset">` or `form.reset()` | Mixin's `formResetCallback` → `resetForm()` clears `value`, `error`, `validationMessage`, `touched`, `submitted`. |
+| Cross-field rules (password confirm) | `schema` prop with zod `.refine` | Validation seam is the schema, not the mixin. Cross-field violations surface on submit; map to a specific field via `form.setFieldError`. |
+| Server-shape transforms (IBAN uppercase, trim) | `schema` prop with zod `.transform` | Runs during `schema.parse(rawFormData)` in `_onSubmit`. The `data` in the submit event is post-transform. |
+| Multi-entry FormData (date range, tag input) | Override `toFormEntries()` + `internals.setFormValue(formData)` | Flat suffix keys (`${name}From`, `${name}To`) — no bracket-key encoding. Native `new FormData(form)` sees both keys. |
+| Boolean state semantics (checkbox, switch) | Override `checkValidity()` | Required validity is `checked === true`, not the mixin's "non-empty value." |
+| Numeric value (range) | `override value: number` | Narrows the mixin's wide union. Mixin's `dirty` getter uses `value !== _defaultValue` which works for primitives. |
+| Two independent forms on one page | Each `<schmancy-form>` is its own context provider | `<schmancy-context .provides=${[formSubmitState]}>` is rendered inside each form. Submit state is isolated per instance — no cross-contamination. |
+| Nested forms forbidden | `<schmancy-form>` `connectedCallback` checks for an ancestor `schmancy-form` and `console.error`s if found | Nested forms are platform-undefined; we surface the error early. |
+
+## What's NOT in scope
+
+These are deferred to v2 and **not** in the current contract:
+
+- `<schmancy-form-summary>` (top-of-form error banner with anchor links to invalid fields).
+- `validateOn: 'length'` (validate once `value.length === maxlength` — Stripe card-number pattern).
+- Per-field `errorMessages` i18n hook (the default `'This field is required'` is hardcoded English).
+- First-class `useFieldArray` API for dynamic fields.
+- Async-validation helpers (`isValidating`, `runAsyncValidator`, `:state(validating)`).
+- Wizard `clearSubmitted()` (post-submit state currently persists until `resetForm`).
+- Structured `ValidityStateFlags` exposure beyond `valueMissing` + `customError`.
+
+If a consumer needs one of these, file an issue with the use case before adding it — every addition to the binding contract has a propagation cost across all 9 form components.
+
+## See also
+
+- `form.md` — the `<schmancy-form>` API reference.
+- `mixins.md` — `SchmancyFormField()` factory composition.
+- `state.md` — `formSubmitState` singleton + per-form isolation.

package/dist/skills/form.md

@@ -1,49 +1,145 @@
 # schmancy-form
 
-> Form container that collects data from child controls, validates, and emits submit/reset events.
+> Form container with isolated submit state, typed schema seam, and a unified validation UX contract every field implements.
 
 ## Usage
+
 ```html
-<schmancy-form @submit=${(e) => handleSubmit(e.detail)}>
+<schmancy-form @submit=${(e) => handleSubmit(e.detail.data)}>
   <schmancy-input name="email" label="Email" required></schmancy-input>
   <schmancy-button type="submit">Submit</schmancy-button>
 </schmancy-form>
 ```
 
+The submit detail is `{ data, formData, until }`:
+
+```ts
+type SchmancyFormSubmitDetail<T = Record<string, FormDataEntryValue>> = {
+  data: T                                  // typed when `schema` is set
+  formData: FormData                       // raw payload
+  until(p: Promise<unknown>): void         // gate success/error on async outcome
+}
+```
+
 ## Properties
+
 | Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| novalidate | boolean | `false` | Skip validation on submit |
+|---|---|---|---|
+| `schema` | `ParseSchema` (zod / valibot / ArkType compatible) | — | When set, parses raw FormData on submit; `e.detail.data` is typed `z.infer<TSchema>`. |
+| `novalidate` | `boolean` | `true` | Skip native browser validation popups (we control display). |
 
 ## Events
+
 | Event | Detail | Description |
-|-------|--------|-------------|
-| submit | FormData | Form data from all child controls |
-| reset | - | When the form is reset |
+|---|---|---|
+| `submit` | `SchmancyFormSubmitDetail` | Fired after all registered fields pass validation. |
+| `reset` | `CustomEvent` | Fired after the form resets. |
 
 ## Methods
+
 | Method | Returns | Description |
-|--------|---------|-------------|
-| submit() | boolean | Validates and dispatches submit event. Returns false if invalid. |
-| reset() | void | Resets all child controls to default values |
-| getFormData() | FormData | Collects current form data without submitting |
-| reportValidity() | boolean | Checks and shows validation on all controls |
+|---|---|---|
+| `submit()` | `boolean` | Programmatic submission via the inner form's `requestSubmit()`. |
+| `reset()` | `void` | Resets every registered field. |
+| `setFieldError(name, message)` | `boolean` | RHF `setError(name, ...)`-equivalent: maps a server-side error to a specific field. |
+| `setFormError(message, code?)` | `void` | RHF `setError('root.serverError', ...)`-equivalent: structured form-level error. |
+| `getFormData()` | `FormData` | Snapshot of the registered fields' contributed entries. |
+| `reportValidity()` | `boolean` | Checks every registered field. |
+| `checkValidity()` | `boolean` | Same as `reportValidity` without the side effect. |
+
+## Validation UX (binding contract)
+
+Every field that extends `SchmancyFormField()` implements four phases:
+
+| Phase | Trigger | Behaviour |
+|---|---|---|
+| 1 — Pristine | User hasn't changed the field | **No error shown**, ever. `dirty = false` is the gate. |
+| 2 — Dirty | User typed something then blurred | Validate. **Show error only if invalid.** |
+| 3 — Live correction | User returns to a field with an error | Re-validate on every keystroke. Error clears immediately when valid. |
+| 4 — Submit | User clicks submit | Force-validate **all** fields regardless of `dirty`. Focus the first invalid field. |
+
+The default mode is `validateOn="dirty"`. Override per-field for special cases:
+
+```html
+<schmancy-input validateOn="always" ...></schmancy-input>      <!-- live search -->
+<schmancy-input validateOn="submitted" ...></schmancy-input>   <!-- wizard step -->
+```
+
+After a submit attempt, the field stays in live-correction mode (Phase 3) for the rest of the session — `resetForm()` is the only way back.
+
+## Server-side errors
+
+```ts
+async _onSubmit(e: CustomEvent<SchmancyFormSubmitDetail>) {
+  const form = e.target as SchmancyForm
+  e.detail.until(
+    chargeCard(e.detail.data).catch(err => {
+      if (err.code === 'CARD_DECLINED') {
+        form.setFieldError('card', 'Card declined — check the number')
+      } else {
+        form.setFormError(err.message)
+      }
+      throw err   // re-throw so submit-state flips to 'error'
+    }),
+  )
+}
+```
+
+## CSS state hooks (free)
+
+Every field broadcasts these via `:state(...)`:
+
+```css
+schmancy-input:state(invalid)   { --border-color: var(--color-error); }
+schmancy-input:state(dirty)     { --border-color: var(--color-primary); }
+schmancy-input:state(touched)   { /* user blurred at least once */ }
+schmancy-input:state(submitted) { /* post-submit state */ }
+schmancy-input:state(required)  { /* required visual */ }
+
+schmancy-button[type=submit]:state(submitting) { opacity: 0.6; }   /* form busy */
+```
+
+The `<schmancy-form>` host gets `aria-busy="true"` while submitting (WCAG 2.2 AA — disabled submit buttons drop from tab order; we keep them focusable and signal busy via aria).
+
+## Field-author contract
+
+Components that extend `SchmancyFormField()` get FACE wiring, ARIA reflection (`internals.ariaInvalid` / `ariaRequired`), the validation UX state (`touched/dirty/submitted/validateOn`), the `_shouldShowError()` gate, the form-registry composed event (`FIELD_CONNECT_EVENT`), and reset/disabled propagation — all for free.
+
+The component author must wire only two things:
+
+```ts
+// 1. Call markTouched() on blur — tells the mixin the user has left the field
+this.input.addEventListener('blur', () => this.markTouched())
+
+// 2. Call emitChange() when value changes
+this.value = newValue
+this.emitChange({ value: newValue })
+```
+
+Override only when validity semantics differ (checkbox uses `checked`, switch uses `checked`, date-range uses `dateFrom`/`dateTo`) or when FormData contribution is multi-entry (date-range emits `${name}From` and `${name}To`).
+
+## Submit triggers
+
+`<schmancy-form>` listens on its host for `click` on `<button type=submit>` / `<schmancy-button type=submit>` and `keydown.Enter` on registered fields, then calls the inner shadow-DOM form's `requestSubmit()`. This bridges the gap that native form-association cannot cross from light-DOM slotted children to a shadow-DOM `<form>`.
 
 ## Examples
+
 ```html
-<!-- Form with validation -->
-<schmancy-form @submit=${(e) => save(e.detail)} @reset=${() => clearForm()}>
-  <schmancy-input name="name" label="Name" required></schmancy-input>
-  <schmancy-select name="role" label="Role" required>
-    <schmancy-option value="admin" label="Admin"></schmancy-option>
-    <schmancy-option value="user" label="User"></schmancy-option>
-  </schmancy-select>
-  <schmancy-checkbox name="active" label="Active"></schmancy-checkbox>
-  <div class="flex gap-2">
-    <schmancy-button type="submit">Save</schmancy-button>
-    <schmancy-button type="reset">Reset</schmancy-button>
-  </div>
+<!-- Two independent checkout forms — each <schmancy-form> instance has its own
+     isolated submit state via <schmancy-context>; no cross-contamination. -->
+<schmancy-form @submit=${(e) => pay('primary', e)}>
+  <schmancy-input name="card" required></schmancy-input>
+  <schmancy-button type="submit">Pay £50</schmancy-button>
+</schmancy-form>
+
+<schmancy-form @submit=${(e) => pay('backup', e)}>
+  <schmancy-input name="card" required></schmancy-input>
+  <schmancy-button type="submit">Pay £50</schmancy-button>
 </schmancy-form>
 ```
 
-Submit triggers on Enter key in inputs or clicking a submit-type button.
+## See also
+
+- `form-ux-rules.md` — the Revolute UX contract → mixin API mapping.
+- `mixins.md` — `SchmancyFormField()` factory composition.
+- `state.md` — `formSubmitState` + `<schmancy-context>` isolation pattern.

package/dist/skills/input.md

@@ -22,7 +22,10 @@
 | validationMessage | string | `''` | Custom validation message |
 | hint | string | `undefined` | Hint text below the field |
 | size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height (24-56px) |
-| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'touched'` | When to show validation |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When to display validation errors. Default suppresses errors on pristine fields until submit. |
+| touched | boolean (read-only) | `false` | True after first blur — set by `markTouched()`. |
+| dirty | boolean (getter) | — | True when `value` differs from the captured default. |
+| submitted | boolean (read-only) | `false` | Set by `<schmancy-form>` on submit; flips field to live-correction mode. |
 | align | `'left'\|'center'\|'right'` | `'left'` | Text alignment |
 | pattern | string | `undefined` | Regex validation pattern |
 | inputmode | string | `undefined` | Virtual keyboard hint |
@@ -34,9 +37,21 @@
 ## Events
 | Event | Detail | Description |
 |-------|--------|-------------|
-| input | `{ value: string }` | Every keystroke |
-| change | `{ value: string }` | On blur/native change |
-| enter | `{ value: string }` | When Enter key is pressed |
+| input | `{ value: string }` | Every keystroke (bubbles, composed) |
+| change | `{ value: string }` | On blur/native change (bubbles, composed) |
+| enter | `{ value: string }` | Enter key pressed |
+| focus / blur | — | Standard focus events |
+
+## Public API (from `SchmancyFormField`)
+- `markTouched()` / `markSubmitted()` — flip the `_shouldShowError()` gate.
+- `checkValidity()` / `reportValidity()` — return current validity (used by `<schmancy-form>` and native `<form>`).
+- `setCustomValidity(message)` — server-side error path. `<schmancy-form>` calls this from `setFieldError(name, msg)`.
+- `resetForm()` — restores the captured default; clears `error`, `touched`, `submitted`.
+- `internals.ariaInvalid` / `ariaRequired` — set automatically; reaches AT through shadow DOM.
+
+`<schmancy-form>` auto-discovers this field via `FIELD_CONNECT_EVENT` (composed event). No registration needed.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.
 
 ## Examples
 ```html

package/dist/skills/range.md

@@ -20,9 +20,15 @@
 | `min` | number | `0` | Minimum value |
 | `max` | number | `1` | Maximum value |
 | `step` | number | `0.01` | Increment per tick |
-| `value` | number | `0` | Current value |
+| `value` | number | `0` | Current value (narrowed override of the mixin's wide union). |
 | `label` | string | — | Optional label (current value displays on the right) |
 | `disabled` | boolean | `false` | Disabled state (38% opacity) |
+| `name` | string | `''` | Form submission name. From `SchmancyFormField`. |
+| `required` | boolean | `false` | Field must have a value to validate. |
+| `validateOn` | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When errors display. |
+| `validationMessage` | string | `''` | Error message. |
+| `hint` | string | `undefined` | Helper text. |
+| `touched / dirty / submitted` | boolean | — | Validation state from `SchmancyFormField`. |
 
 ## Events
 | Event | Payload | When |
@@ -34,6 +40,14 @@
 - Circular thumb with hover halo (8px primary glow at 12% opacity).
 - Disabled state: 38% opacity, not-allowed cursor.
 
+## Form-field contract
+
+Extends `SchmancyFormField()`. FormData contributes `String(value)` under `name`. `markTouched()` fires on every input event (slider drag), so the field transitions to `touched` immediately on interaction — the `dirty` gate opens once value diverges from the captured default.
+
+Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `setCustomValidity()`, `resetForm()`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.
+
 ## Example — precise float control
 ```html
 <schmancy-range

package/dist/skills/schmancy/autocomplete.md

@@ -20,13 +20,18 @@
 | name | string | `''` | Form submission name |
 | required | boolean | `false` | Whether selection is required |
 | multi | boolean | `false` | Enable multi-select with inline chips |
-| size | `'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height (M3 sizes 24–56dp). |
 | maxHeight | string | `'300px'` | Max dropdown height |
 | debounceMs | number | `200` | Search debounce in ms |
 | similarityThreshold | number | `0.3` | Minimum fuzzy match score (0-1) |
-| error | boolean | `false` | Error state |
-| validationMessage | string | `''` | Validation message |
+| error | boolean | `false` | Error state (gated by `validateOn`). From `SchmancyFormField`. |
+| validationMessage | string | `''` | Validation message. |
 | description | string | `''` | Screen reader description |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. |
+| disabled | boolean | `false` | Disabled state. |
+| hint | string | `undefined` | Helper text below the field. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
+| autocomplete | string | `'off'` | Native autocomplete attribute on inner input. |
 
 ## Events
 | Event | Detail | Description |
@@ -51,3 +56,11 @@
 ```
 
 Children must be `<schmancy-option>` elements. In multi mode, selected items appear as removable chips.
+
+## Form-field contract
+
+Extends `SchmancyFormField()`. Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`, `resetForm()` (resets the BehaviorSubjects + clears the input).
+
+Default `validateOn: 'dirty'` — a required-empty autocomplete shows no error until the user types-then-clears or submits. Error UI rendered in a `role="alert"` div linked via `aria-describedby`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/schmancy/button.md

@@ -40,6 +40,25 @@
 - Hover: luminous glow shadow using primary color
 - Active: spring press `scale(0.97)` / `scale(0.92)` for icon-button
 
+## Submit-state mirroring (`type="submit"` only)
+
+A `<schmancy-button type="submit">` inside a `<schmancy-form>` automatically reflects the form's submit state via a MutationObserver on the form's `aria-busy` attribute:
+
+- While the form's `formSubmitState.status === 'submitting'` (form sets `aria-busy="true"`):
+  - Button mirrors `aria-busy="true"` onto itself.
+  - Broadcasts `:state(submitting)` for CSS targeting.
+  - **Stays focusable** — never gets the `disabled` attribute. Disabled buttons drop from the tab order; AT users would lose their place. WCAG 2.2 AA.
+- Cleared automatically when the form's submit promise settles (success or error).
+
+```css
+schmancy-button:state(submitting) {
+  opacity: 0.6;
+  /* show a spinner via ::before, swap label, etc. */
+}
+```
+
+`schmancy-button` is form-associated (`static formAssociated = true` + `attachInternals()`) — clicking a `type="submit"` inside any `<form>` ancestor (native or schmancy) calls `form.requestSubmit()`. Inside `<schmancy-form>` the click is also intercepted at the form host and bridged across the shadow boundary to the inner shadow-DOM `<form>`.
+
 ## Examples
 ```html
 <!-- Filled primary -->

package/dist/skills/schmancy/checkbox.md

@@ -18,6 +18,14 @@
 | disabled | boolean | `false` | Whether the checkbox is disabled |
 | required | boolean | `false` | Whether the checkbox is required |
 | size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Checkbox size |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. From `SchmancyFormField`. |
+| validationMessage | string | `''` | Error text — default `'Please check this box if you want to proceed.'` when required and unchecked. |
+| error | boolean | `false` | Error state (gated by `validateOn`). |
+| hint | string | `undefined` | Helper text. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
+
+## Attributes
+- `true-value` — string written to FormData when checked. Default `'on'` (matches native checkbox semantics).
 
 ## Events
 | Event | Detail | Description |
@@ -33,4 +41,15 @@
 <schmancy-checkbox name="terms" required>
   Accept <a href="/terms">terms and conditions</a>
 </schmancy-checkbox>
+
+<!-- Custom FormData string -->
+<schmancy-checkbox name="newsletter" true-value="opt-in"></schmancy-checkbox>
 ```
+
+## Form-field contract
+
+Extends `SchmancyFormField()`. `value` is the boolean state; FormData submission uses the `true-value` attribute (or `'on'`). Validity overrides the mixin's "non-empty value" semantics: required + unchecked → `internals.setValidity({ valueMissing: true })`. ARIA `aria-invalid` / `aria-required` reflect through `ElementInternals`.
+
+Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `setCustomValidity()`, `resetForm()`. Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/schmancy/date-range.md

@@ -27,6 +27,12 @@
 | collapse | boolean | `false` | Icon-only on mobile |
 | customPresets | array | `[]` | Additional preset ranges |
 | format | string | auto | Date format string |
+| name | string | `''` | Form submission name. From `SchmancyFormField`. |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. |
+| validationMessage | string | `''` | Error message — default `'Please select a date range.'` when required and either bound is empty. |
+| error | boolean | `false` | Error state (gated by `validateOn`). |
+| hint | string | `undefined` | Helper text. |
+| touched / dirty / submitted | boolean | — | Validation state. `dirty` tracks `dateFrom.value` / `dateTo.value` against the snapshots taken at first render. |
 
 ## Events
 | Event | Detail | Description |
@@ -48,3 +54,16 @@
 ```
 
 Built-in presets include Today, Yesterday, This Week, This Month, This Year, and more.
+
+## Form association
+
+Extends `SchmancyFormField()`. Multi-entry FormData contribution:
+- Set `name="dates"` and FormData receives **two** keys: `datesFrom` and `datesTo` (flat suffix shape, no bracket-key encoding).
+- `internals.setFormValue(formData)` accepts a `FormData` object whose entries get appended to the parent form — native `new FormData(form)` sees both keys without consumer-side parsing.
+- `<schmancy-form>`'s registry consumer also sees both keys via `toFormEntries()`.
+
+`resetForm()` restores both `dateFrom.value` and `dateTo.value` to the snapshots captured at first render. Validity: required + either bound empty → `internals.setValidity({ valueMissing: true })`. Order/range constraints (start ≤ end, future-only, etc.) are out of scope — handle those in a domain schema layer.
+
+Auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Public API: `markTouched()`, `markSubmitted()`, `checkValidity()`, `setCustomValidity()`, `resetForm()`.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/dist/skills/schmancy/form-ux-rules.md

@@ -0,0 +1,55 @@
+# Form UX rules — Revolute pattern → schmancy mixin API
+
+This is the mapping between the Revolute interview-bar form UX (the source-of-truth checklist for state-of-the-art form behaviour) and the `SchmancyFormField()` API that implements each rule. When you hit a UX question, find the rule here and use the named API — don't re-derive from scratch.
+
+## The four-phase validation contract
+
+| Phase | UX rule | Implementation |
+|---|---|---|
+| 1 — Pristine | A field the user hasn't typed in shows no error, even if focused-then-blurred. The autofocus+cancel anti-pattern (focus a required field, click cancel, see "required") is forbidden. | `validateOn: 'dirty'` (default). `_shouldShowError()` returns `false` while `dirty === false`. |
+| 2 — Dirty | User types and blurs → validate the field. Show error only if invalid. Empty required fields blurred-without-typing remain pristine. | `markTouched()` called on blur. Mixin's `willUpdate` sees `touched` change, sees `dirty` is true, calls `checkValidity()` which sets `this.error` because the gate is open. |
+| 3 — Live correction | User returns to a field with an error → re-validate on every keystroke. Error clears immediately when valid. | Mixin's `willUpdate` re-runs `checkValidity()` on every value change while `_shouldShowError()` is true. |
+| 4 — Submit | Submit click → validate **all** fields regardless of dirty. Focus the first invalid field. | `<schmancy-form>` calls `markSubmitted()` on every registered field. `submitted = true` overrides every `validateOn` mode and forces error display. The form then focuses the first field with `error === true`. |
+
+After Phase 4, the field stays in Phase 3 (live re-validation) for the rest of the session because `submitted` persists until `resetForm()`.
+
+## Per-rule cross-reference
+
+| UX rule | API | Notes |
+|---|---|---|
+| Default mode is "errors after the user has interacted" | `validateOn: 'dirty'` | Pristine fields stay clean; submit forces all errors. |
+| Live search shows errors immediately | `validateOn="always"` | Bypass the dirty/touched gate entirely. |
+| Wizard step holds errors until Next | `validateOn="submitted"` | Only `markSubmitted()` opens the gate. |
+| Server-side error → specific field | `form.setFieldError(name, msg)` | RHF `setError` parity. Sets custom validity + marks submitted so the error shows. |
+| Server-side error → form banner | `form.setFormError(msg, code?)` | Flips `formSubmitState` to `{ status: 'error', error: { message, code } }`. Top-of-form banners read this. |
+| Async server-side check gating submit | `e.detail.until(promise)` | Form's `submit` event detail. Submit status reflects the promise outcome (`success` on resolve, `error` on reject). |
+| Submit button must stay focusable while busy | `aria-busy="true"` on the host (auto) + `:state(submitting)` on `<schmancy-button[type=submit]>` (auto) | WCAG 2.2 AA. Disabled buttons drop from the tab order; we never disable. |
+| Screen reader announces invalid fields | `internals.ariaInvalid` (auto) + `internals.ariaRequired` (auto) | Reflected through `ElementInternals` so AT reaches into shadow DOM. Not on the host as `aria-*` attributes. |
+| Reset returns the form to pristine | `<schmancy-button type="reset">` or `form.reset()` | Mixin's `formResetCallback` → `resetForm()` clears `value`, `error`, `validationMessage`, `touched`, `submitted`. |
+| Cross-field rules (password confirm) | `schema` prop with zod `.refine` | Validation seam is the schema, not the mixin. Cross-field violations surface on submit; map to a specific field via `form.setFieldError`. |
+| Server-shape transforms (IBAN uppercase, trim) | `schema` prop with zod `.transform` | Runs during `schema.parse(rawFormData)` in `_onSubmit`. The `data` in the submit event is post-transform. |
+| Multi-entry FormData (date range, tag input) | Override `toFormEntries()` + `internals.setFormValue(formData)` | Flat suffix keys (`${name}From`, `${name}To`) — no bracket-key encoding. Native `new FormData(form)` sees both keys. |
+| Boolean state semantics (checkbox, switch) | Override `checkValidity()` | Required validity is `checked === true`, not the mixin's "non-empty value." |
+| Numeric value (range) | `override value: number` | Narrows the mixin's wide union. Mixin's `dirty` getter uses `value !== _defaultValue` which works for primitives. |
+| Two independent forms on one page | Each `<schmancy-form>` is its own context provider | `<schmancy-context .provides=${[formSubmitState]}>` is rendered inside each form. Submit state is isolated per instance — no cross-contamination. |
+| Nested forms forbidden | `<schmancy-form>` `connectedCallback` checks for an ancestor `schmancy-form` and `console.error`s if found | Nested forms are platform-undefined; we surface the error early. |
+
+## What's NOT in scope
+
+These are deferred to v2 and **not** in the current contract:
+
+- `<schmancy-form-summary>` (top-of-form error banner with anchor links to invalid fields).
+- `validateOn: 'length'` (validate once `value.length === maxlength` — Stripe card-number pattern).
+- Per-field `errorMessages` i18n hook (the default `'This field is required'` is hardcoded English).
+- First-class `useFieldArray` API for dynamic fields.
+- Async-validation helpers (`isValidating`, `runAsyncValidator`, `:state(validating)`).
+- Wizard `clearSubmitted()` (post-submit state currently persists until `resetForm`).
+- Structured `ValidityStateFlags` exposure beyond `valueMissing` + `customError`.
+
+If a consumer needs one of these, file an issue with the use case before adding it — every addition to the binding contract has a propagation cost across all 9 form components.
+
+## See also
+
+- `form.md` — the `<schmancy-form>` API reference.
+- `mixins.md` — `SchmancyFormField()` factory composition.
+- `state.md` — `formSubmitState` singleton + per-form isolation.