@mhmo91/schmancy 0.10.15 → 0.10.17

package/skills/schmancy/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/skills/schmancy/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/skills/schmancy/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/skills/schmancy/select.md

@@ -23,7 +23,11 @@
 | multi | boolean | `false` | Enable multi-select mode |
 | hint | string | `''` | Hint text below the select |
 | size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Input height |
-| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'touched'` | When to show validation |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. From `SchmancyFormField`. |
+| validationMessage | string | `''` | Error message — set by `setCustomValidity()` or `<schmancy-form>.setFieldError()`. |
+| error | boolean (read-only) | — | True when invalid AND `_shouldShowError()` gate is open. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
+| readonly | boolean | `false` | Read-only mode. |
 
 ## Events
 | Event | Detail | Description |
@@ -47,3 +51,11 @@
 ```
 
 Children must be `<schmancy-option>` elements with `value` and `label` attributes.
+
+## Form-field contract
+
+Extends `SchmancyFormField()` — auto-discovered by `<schmancy-form>` via `FIELD_CONNECT_EVENT`. Exposes `markTouched()`, `markSubmitted()`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`, `resetForm()`. Multi-select serializes to a comma-joined string for native FormData; `toFormEntries()` emits one `[name, value]` per selection for `<schmancy-form>` consumers.
+
+ARIA combobox attributes (`role="combobox"`, `aria-expanded`, `aria-controls`) plus `aria-invalid` / `aria-required` reflect through `ElementInternals` — target via `:state(invalid)` / `:state(required)` in CSS, not host `[aria-*]` selectors.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/skills/schmancy/switch.md

@@ -17,6 +17,11 @@
 | label | string | `''` | ARIA label on the inner button; also used by axe. |
 | required | boolean | `false` | Must be on for form validity. |
 | disabled | boolean | `false` | Disables interaction. |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. From `SchmancyFormField`. |
+| validationMessage | string | `''` | Error text — default `'This switch is required.'` when required and off. |
+| error | boolean | `false` | Error state (gated by `validateOn`). |
+| hint | string | `undefined` | Helper text. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
 
 ## Events
 | Event | Detail | Description |
@@ -32,10 +37,24 @@
 ## States
 | State | When |
 |-------|------|
-| `:state(checked)` | While the switch is on. Target via `schmancy-switch:state(checked) { … }`. |
+| `:state(checked)`   | switch is on |
+| `:state(touched)`   | user has blurred the host at least once |
+| `:state(dirty)`     | `checked` differs from initial |
+| `:state(submitted)` | parent `<schmancy-form>` has submitted |
+| `:state(invalid)`   | error flag is set (gated by `validateOn`) |
+| `:state(required)`  | required and not disabled |
+| `:state(disabled)`  | disabled |
 
 ## Form association
-Uses `ElementInternals` — participates in `<form>` submission natively. Contributes `name=value` when checked; omitted when unchecked. `formResetCallback` restores the initial `checked` attribute. `formDisabledCallback` propagates `<fieldset disabled>`.
+Extends `SchmancyFormField()` — participates in `<form>` submission natively. FormData contributes `name=value` when checked; omitted when unchecked.
+
+`dirty` is overridden to mean "`checked` diverged from the snapshot taken at first render," not the mixin's value-vs-default. Under default `validateOn: 'dirty'`, an empty-required switch only shows an error after the user toggles it (or submit forces validation), but `internals.checkValidity()` already reports `false` so `<form>.checkValidity()` is correct.
+
+`resetForm()` restores the snapshot taken in `firstUpdated` (the pre-render `checked` value). `formDisabledCallback` propagates `<fieldset disabled>`. 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.
 
 ## Examples
 ```html

package/skills/schmancy/textarea.md

@@ -28,6 +28,11 @@
 | resize | `'none'\|'vertical'\|'horizontal'\|'both'` | `'vertical'` | Resize handle |
 | align | `'left'\|'center'\|'right'` | `'left'` | Text alignment |
 | wrap | `'hard'\|'soft'` | `'soft'` | Text wrapping mode |
+| validateOn | `'always'\|'touched'\|'dirty'\|'submitted'` | `'dirty'` | When validation errors display. From `SchmancyFormField`. |
+| validationMessage | string | `''` | Custom error message. Set via `setCustomValidity()` or by `<schmancy-form>.setFieldError()`. |
+| spellcheck | boolean | `false` | Native spellcheck attribute. |
+| dirname | string | `undefined` | Native dirname for RTL form submission. |
+| touched / dirty / submitted | boolean | — | Validation state from `SchmancyFormField`. |
 
 ## Events
 | Event | Detail | Description |
@@ -46,3 +51,11 @@
 <!-- Fill container -->
 <schmancy-textarea fillHeight label="Content"></schmancy-textarea>
 ```
+
+## Form-field contract
+
+Extends `SchmancyFormField()` — `markTouched()`, `markSubmitted()`, `checkValidity()`, `reportValidity()`, `setCustomValidity()`, `resetForm()` all available; `internals.ariaInvalid` / `ariaRequired` set automatically; `<schmancy-form>` auto-discovers via `FIELD_CONNECT_EVENT`.
+
+Validation message renders in the same supporting slot as `hint`, with `role="alert"` set when `error` is true so AT announces the change.
+
+See `form.md` and `form-ux-rules.md` for the binding 4-phase validation contract.

package/src/button/button.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import './button'
+import '../form/form'
+import '../form/fields/input/input'
+import { expectNoA11yViolations } from '../test-utils/a11y'
+import type { SchmancyFormSubmitDetail } from '../form/form'
+
+const nextUpdate = () => new Promise(r => requestAnimationFrame(() => r(null)))
+
+describe('schmancy-button busy mirror', () => {
+	let host: HTMLDivElement
+
+	beforeEach(() => {
+		host = document.createElement('div')
+		document.body.appendChild(host)
+	})
+
+	afterEach(() => {
+		host.remove()
+	})
+
+	it('mirrors closest <schmancy-form> aria-busy onto a submit button', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-input name="x" value="ok"></schmancy-input>
+				<schmancy-button type="submit">Send</schmancy-button>
+			</schmancy-form>
+		`
+		const form = host.querySelector('schmancy-form') as HTMLElement
+		const btn = host.querySelector('schmancy-button[type=submit]') as HTMLElement
+		await nextUpdate()
+		await nextUpdate()
+
+		expect(btn.hasAttribute('aria-busy')).toBe(false)
+
+		form.setAttribute('aria-busy', 'true')
+		await nextUpdate()
+		await nextUpdate()
+		expect(btn.getAttribute('aria-busy')).toBe('true')
+		expect(btn.matches(':state(submitting)')).toBe(true)
+
+		form.removeAttribute('aria-busy')
+		await nextUpdate()
+		await nextUpdate()
+		expect(btn.hasAttribute('aria-busy')).toBe(false)
+		expect(btn.matches(':state(submitting)')).toBe(false)
+	})
+
+	it('does not mirror busy on non-submit buttons', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-button type="button">Cancel</schmancy-button>
+			</schmancy-form>
+		`
+		const form = host.querySelector('schmancy-form') as HTMLElement
+		const btn = host.querySelector('schmancy-button') as HTMLElement
+		await nextUpdate()
+		await nextUpdate()
+
+		form.setAttribute('aria-busy', 'true')
+		await nextUpdate()
+		await nextUpdate()
+		expect(btn.hasAttribute('aria-busy')).toBe(false)
+		expect(btn.matches(':state(submitting)')).toBe(false)
+	})
+
+	it('has no axe-core a11y violations in busy state', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-input name="x" value="ok"></schmancy-input>
+				<schmancy-button type="submit">Send</schmancy-button>
+			</schmancy-form>
+		`
+		const form = host.querySelector('schmancy-form') as HTMLElement
+		await nextUpdate()
+		await nextUpdate()
+		// Idle baseline.
+		await expectNoA11yViolations(host)
+		// Busy state — button gets aria-busy, must remain focusable + AT-clean.
+		form.setAttribute('aria-busy', 'true')
+		await nextUpdate()
+		await nextUpdate()
+		await expectNoA11yViolations(host)
+	})
+
+	it('drives busy through the awaitable submit lifecycle', async () => {
+		host.innerHTML = `
+			<schmancy-form>
+				<schmancy-input name="x" value="ok"></schmancy-input>
+				<schmancy-button type="submit">Send</schmancy-button>
+			</schmancy-form>
+		`
+		const form = host.querySelector('schmancy-form') as HTMLElement
+		const btn = host.querySelector('schmancy-button[type=submit]') as HTMLElement
+		await nextUpdate()
+		await nextUpdate()
+
+		// Resolve the until-promise after a tick so we can observe the busy window.
+		let resolveSubmit: (() => void) | null = null
+		form.addEventListener('submit', (e: Event) => {
+			const detail = (e as CustomEvent<SchmancyFormSubmitDetail>).detail
+			detail.until(new Promise<void>(res => { resolveSubmit = res }))
+		})
+
+		btn.click()
+		// Wait for the submit microtask + form state flip + MutationObserver tick.
+		await nextUpdate()
+		await nextUpdate()
+		await nextUpdate()
+
+		expect(btn.getAttribute('aria-busy')).toBe('true')
+		expect(btn.matches(':state(submitting)')).toBe(true)
+
+		resolveSubmit!()
+		await nextUpdate()
+		await nextUpdate()
+		await nextUpdate()
+
+		expect(btn.hasAttribute('aria-busy')).toBe(false)
+		expect(btn.matches(':state(submitting)')).toBe(false)
+	})
+})

package/src/button/button.ts

@@ -62,6 +62,13 @@ export class SchmancyButton extends SchmancyElement {
 
 	static formAssociated = true
 	private internals: ElementInternals | undefined
+	/**
+	 * When this button is `type="submit"` and lives inside a <schmancy-form>,
+	 * the observer mirrors the form's `aria-busy` attribute onto this button
+	 * while a submit is in flight. Stays focusable; disabled buttons drop from
+	 * the tab order and are unreachable to AT (WCAG 2.2 AA).
+	 */
+	private _formBusyObserver?: MutationObserver
 
 	constructor() {
 		super()
@@ -99,6 +106,35 @@ export class SchmancyButton extends SchmancyElement {
 		this.disabled = disabled
 	}
 
+	override connectedCallback(): void {
+		super.connectedCallback()
+		// Mirror the closest <schmancy-form>'s aria-busy onto this submit button
+		// so the user gets a visible busy state during async submit handlers.
+		// Schmancy-form sets aria-busy="true" while status === 'submitting'.
+		if (this.type !== 'submit') return
+		const form = this.closest('schmancy-form') as HTMLElement | null
+		if (!form) return
+		const sync = () => {
+			const busy = form.getAttribute('aria-busy') === 'true'
+			if (busy) {
+				this.setAttribute('aria-busy', 'true')
+				this.internals?.states.add('submitting')
+			} else {
+				this.removeAttribute('aria-busy')
+				this.internals?.states.delete('submitting')
+			}
+		}
+		sync()
+		this._formBusyObserver = new MutationObserver(sync)
+		this._formBusyObserver.observe(form, { attributes: true, attributeFilter: ['aria-busy'] })
+	}
+
+	override disconnectedCallback(): void {
+		this._formBusyObserver?.disconnect()
+		this._formBusyObserver = undefined
+		super.disconnectedCallback()
+	}
+
 	@query('[part="base"]', true)
 	private nativeElement!: HTMLElement