@chromvoid/headless-ui 0.1.0

package/specs/components/spinbutton.md

@@ -0,0 +1,140 @@
+# Spinbutton Component Contract
+
+## Purpose
+
+`Spinbutton` provides a headless APG-aligned model for a numeric input that allows users to select a value by typing or using increment/decrement controls.
+
+It handles numeric normalization (snap-to-step), optional range constraints, keyboard-driven value adjustments, and ARIA contracts.
+
+## Component Files
+
+- `src/spinbutton/index.ts` - model and public `createSpinbutton` API
+- `src/spinbutton/spinbutton.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSpinbutton(options)`
+- `CreateSpinbuttonOptions`:
+  - `idBase?: string`
+  - `value?: number`
+  - `min?: number`
+  - `max?: number`
+  - `step?: number`
+  - `largeStep?: number`
+  - `isDisabled?: boolean`
+  - `isReadOnly?: boolean`
+  - `ariaLabel?: string`
+  - `ariaLabelledBy?: string`
+  - `ariaDescribedBy?: string`
+  - `formatValueText?: (value: number) => string`
+  - `onValueChange?: (value: number) => void`
+- `state` (signal-backed):
+  - `value()`: `number`
+  - `min()`: `number | undefined`
+  - `max()`: `number | undefined`
+  - `step()`: `number`
+  - `largeStep()`: `number`
+  - `isDisabled()`: `boolean`
+  - `isReadOnly()`: `boolean`
+  - `hasMin()`: `boolean`
+  - `hasMax()`: `boolean`
+- `actions`:
+  - `setValue(value)`: sets the value with clamping and snapping
+  - `increment()`, `decrement()`
+  - `incrementLarge()`, `decrementLarge()`
+  - `setFirst()`, `setLast()`
+  - `setDisabled(value)`, `setReadOnly(value)`
+  - `handleKeyDown(event)`
+- `contracts`:
+  - `getSpinbuttonProps()`
+  - `getIncrementButtonProps()`
+  - `getDecrementButtonProps()`
+
+Range semantics:
+
+- `min` / `max` are optional; when both are absent the model is truly unbounded.
+- When both `min` and `max` are provided in reverse order, they are normalized so `min <= max`.
+- Step snapping is anchored to `min` when provided, otherwise to `0`.
+
+## APG and A11y Contract
+
+- role: `spinbutton`
+- `aria-valuenow`: current numeric value
+- `aria-valuemin`: minimum value (if defined)
+- `aria-valuemax`: maximum value (if defined)
+- `aria-valuetext`: optional string representation
+- `aria-disabled`: boolean
+- `aria-readonly`: boolean
+- increment/decrement button contracts expose `aria-disabled` when interaction is blocked by disabled/read-only state or by reaching a corresponding range boundary.
+
+## Behavior Contract
+
+- `ArrowUp` increments the value by `step`.
+- `ArrowDown` decrements the value by `step`.
+- `PageUp` increments the value by a larger step (default 10 \* `step`).
+- `PageDown` decrements the value by a larger step.
+- `Home` sets the value to `min` (if defined).
+- `End` sets the value to `max` (if defined).
+- Snapping to `step` occurs on all value changes (`nearest` strategy).
+- `PageUp` / `PageDown` always apply `largeStep`; range boundaries only clamp when they exist.
+
+## Transition Table
+
+| Trigger                    | Guard                                  | Action                         | Next Value                            |
+| -------------------------- | -------------------------------------- | ------------------------------ | ------------------------------------- |
+| `setValue(v)`              | `!isDisabled && !isReadOnly`           | snap + optional clamp + commit | constrained `v`                       |
+| `increment()`              | `!isDisabled && !isReadOnly`           | step up                        | `value + step` (clamped/snapped)      |
+| `decrement()`              | `!isDisabled && !isReadOnly`           | step down                      | `value - step` (clamped/snapped)      |
+| `incrementLarge()`         | `!isDisabled && !isReadOnly`           | large-step up                  | `value + largeStep` (clamped/snapped) |
+| `decrementLarge()`         | `!isDisabled && !isReadOnly`           | large-step down                | `value - largeStep` (clamped/snapped) |
+| `setFirst()`               | `!isDisabled && !isReadOnly && hasMin` | jump to min                    | `min`                                 |
+| `setLast()`                | `!isDisabled && !isReadOnly && hasMax` | jump to max                    | `max`                                 |
+| `handleKeyDown(ArrowUp)`   | handled key                            | `increment()`                  | stepped up value                      |
+| `handleKeyDown(ArrowDown)` | handled key                            | `decrement()`                  | stepped down value                    |
+| `handleKeyDown(PageUp)`    | handled key                            | `incrementLarge()`             | large-stepped value                   |
+| `handleKeyDown(PageDown)`  | handled key                            | `decrementLarge()`             | large-stepped value                   |
+| `handleKeyDown(Home)`      | handled key                            | `setFirst()`                   | min or unchanged                      |
+| `handleKeyDown(End)`       | handled key                            | `setLast()`                    | max or unchanged                      |
+
+## Invariants
+
+- If `min` and `max` are defined, `min <= value <= max`.
+- If `min` is undefined and `max` is undefined, value is unbounded.
+- `step > 0`.
+- `largeStep > 0`.
+- Disabled or Read-only states prevent value changes via actions.
+
+## Adapter Expectations
+
+- UIKit reads these signals directly: `state.value`, `state.min`, `state.max`, `state.step`, `state.largeStep`, `state.isDisabled`, `state.isReadOnly`, `state.hasMin`, `state.hasMax`.
+- UIKit calls only actions for mutations: `setValue`, `increment`, `decrement`, `incrementLarge`, `decrementLarge`, `setFirst`, `setLast`, `setDisabled`, `setReadOnly`, `handleKeyDown`.
+- UIKit spreads contract outputs without recomputation:
+  - `contracts.getSpinbuttonProps()` on the focusable spinbutton root.
+  - `contracts.getIncrementButtonProps()` on increment control.
+  - `contracts.getDecrementButtonProps()` on decrement control.
+- UIKit may keep transient text input state, but committed numeric state MUST come from headless `state.value()`.
+- UIKit must not reconstruct ARIA values (`aria-valuenow`, bounds, disabled/readonly) from parallel state.
+
+## Minimum Test Matrix
+
+- increment/decrement behavior
+- large step (PageUp/PageDown) behavior
+- Home/End behavior with defined/undefined boundaries
+- value clamping and snapping
+- unbounded behavior when no bounds are defined
+- boundary-specific disabled semantics for increment/decrement button contracts
+- disabled and read-only state enforcement
+- keyboard interaction parity with APG
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings.
+- **Independence**: No imports from @project/_, apps/_, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- non-numeric spinbuttons (e.g., days of the week)
+- custom string parsing (handled by adapters)
+- acceleration (increasing step size when holding buttons)

package/specs/components/spinner.md

@@ -0,0 +1,132 @@
+# Spinner Component Contract
+
+## Purpose
+
+`Spinner` is a headless contract for an indeterminate-only loading indicator. It provides ARIA semantics for a progressbar with no determinate value, ensuring assistive technology correctly announces an ongoing loading state.
+
+## Component Files
+
+- `src/spinner/index.ts` - model and public `createSpinner` API
+- `src/spinner/spinner.test.ts` - unit behavior tests
+
+## Options (`CreateSpinnerOptions`)
+
+| Option  | Type     | Default     | Description                                                        |
+| ------- | -------- | ----------- | ------------------------------------------------------------------ |
+| `label` | `string` | `'Loading'` | Accessible name for the spinner, announced by assistive technology |
+
+## Public API
+
+### `createSpinner(options?: CreateSpinnerOptions): SpinnerModel`
+
+### State (signal-backed)
+
+| Signal    | Type           | Description                             |
+| --------- | -------------- | --------------------------------------- |
+| `label()` | `Atom<string>` | Current accessible name for the spinner |
+
+### Actions
+
+| Action     | Signature                 | Description                  |
+| ---------- | ------------------------- | ---------------------------- |
+| `setLabel` | `(value: string) => void` | Updates the accessible label |
+
+### Contracts
+
+| Contract            | Return type    | Description                                                |
+| ------------------- | -------------- | ---------------------------------------------------------- |
+| `getSpinnerProps()` | `SpinnerProps` | Ready-to-spread ARIA attribute map for the spinner element |
+
+#### `SpinnerProps` Shape
+
+```ts
+{
+  role: 'progressbar'
+  'aria-label': string   // from state.label()
+}
+```
+
+Note: `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` are intentionally omitted because the spinner is always indeterminate.
+
+## APG and A11y Contract
+
+- `role="progressbar"` - indicates a loading process
+- Indeterminate mode only: `aria-valuenow` is never present, signaling to assistive technology that progress is unknown
+- `aria-label` provides the accessible name (defaults to `"Loading"`)
+- Non-interactive: no keyboard interaction, no `tabindex`, no focus management
+- Sizing is controlled entirely via CSS `font-size` on the host element (UIKit concern)
+
+## Keyboard Contract
+
+Spinner is not keyboard-interactive. No keyboard handling is needed.
+
+## Behavior Contract
+
+- The spinner is always indeterminate; there is no determinate mode.
+- `label` defaults to `"Loading"` and can be updated programmatically via `setLabel`.
+- The headless layer does not manage visual rendering (SVG circles, animation). That is a UIKit concern.
+
+## Transitions Table
+
+| Trigger               | Precondition | State Change | Contract Effect                                       |
+| --------------------- | ------------ | ------------ | ----------------------------------------------------- |
+| `actions.setLabel(v)` | any          | `label` = v  | `getSpinnerProps()` updates `aria-label` to new value |
+
+## Invariants
+
+- `role` must always be `'progressbar'`.
+- `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` must never be present in `getSpinnerProps()`.
+- `aria-label` must always be a non-empty string; defaults to `"Loading"` if no label is provided.
+- Spinner must never produce `tabindex`, keyboard event handlers, or focus-related attributes.
+
+## Adapter Expectations
+
+This section defines what UIKit (`cv-spinner`) binds to from the headless model.
+
+### Signals read by adapter
+
+| Signal          | UIKit usage                                                  |
+| --------------- | ------------------------------------------------------------ |
+| `state.label()` | Not read directly; consumed via `getSpinnerProps()` contract |
+
+### Actions called by adapter
+
+| Action                | UIKit trigger                                               |
+| --------------------- | ----------------------------------------------------------- |
+| `actions.setLabel(v)` | When `label` attribute/property changes on the host element |
+
+### Contracts spread by adapter
+
+| Contract            | Target element                       | Notes                                                  |
+| ------------------- | ------------------------------------ | ------------------------------------------------------ |
+| `getSpinnerProps()` | Root spinner element (`part="base"`) | Spread as attributes; provides `role` and `aria-label` |
+
+### Options passed through from UIKit attributes
+
+| UIKit attribute | Headless option | Notes                           |
+| --------------- | --------------- | ------------------------------- |
+| `label`         | `label`         | String, defaults to `"Loading"` |
+
+## Minimum Test Matrix
+
+- default state: `label` is `"Loading"`
+- `getSpinnerProps()` returns `{ role: 'progressbar', 'aria-label': 'Loading' }` with defaults
+- `getSpinnerProps()` never includes `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, or `aria-valuetext`
+- `setLabel` updates `aria-label` in contract output
+- custom `label` option is reflected in initial `getSpinnerProps()`
+- spinner never produces `tabindex` or keyboard handler attributes
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Layering**: `core -> interactions -> a11y-contracts -> adapters`; adapters remain thin mappings.
+- **Independence**: No imports from `@project/*`, `apps/*`, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- Determinate/progress mode (use `Progress` component instead)
+- Size attribute (sizing is handled via CSS `font-size`)
+- SVG rendering and animation (UIKit concern)
+- Color/variant theming (UIKit concern)
+- Overlay/backdrop integration

package/specs/components/switch.md

@@ -0,0 +1,175 @@
+# Switch Component Contract
+
+## Purpose
+
+`Switch` provides a headless APG-aligned model for a toggle control that represents a strictly binary on/off state.
+
+While functionally similar to a checkbox, it follows distinct APG keyboard and semantic conventions: the `switch` role uses `aria-checked` (not `aria-pressed`), and both `Space` and `Enter` toggle the state (checkbox only requires `Space`).
+
+## Component Files
+
+- `src/switch/index.ts` - model and public `createSwitch` API
+- `src/switch/switch.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSwitch(options)`
+- `state` (signal-backed):
+  - `isOn()`: `boolean`
+  - `isDisabled()`: `boolean`
+- `actions`:
+  - `toggle()`: toggles the on/off state (no-op if disabled)
+  - `setOn(value: boolean)`: explicitly sets the on state; fires `onCheckedChange` callback
+  - `setDisabled(value: boolean)`: explicitly sets the disabled state
+  - `handleClick()`: delegates to `toggle()`
+  - `handleKeyDown(event)`: handles keyboard interaction (`Space`, `Enter`)
+- `contracts`:
+  - `getSwitchProps()`: returns complete ARIA and event handler attribute map for the switch element
+
+## CreateSwitchOptions
+
+| Option            | Type                       | Default    | Description                                                   |
+| ----------------- | -------------------------- | ---------- | ------------------------------------------------------------- |
+| `idBase`          | `string`                   | `'switch'` | Base id prefix for generated ids                              |
+| `isOn`            | `boolean`                  | `false`    | Initial on/off state                                          |
+| `isDisabled`      | `boolean`                  | `false`    | Initial disabled state                                        |
+| `ariaLabelledBy`  | `string`                   | —          | Id reference for external label (`aria-labelledby`)           |
+| `ariaDescribedBy` | `string`                   | —          | Id reference for help text / description (`aria-describedby`) |
+| `onCheckedChange` | `(value: boolean) => void` | —          | Callback fired when `isOn` changes via `setOn`                |
+
+## State Signal Surface
+
+| Signal       | Type            | Derived? | Description                             |
+| ------------ | --------------- | -------- | --------------------------------------- |
+| `isOn`       | `Atom<boolean>` | No       | Single source of truth for on/off state |
+| `isDisabled` | `Atom<boolean>` | No       | Whether user interaction is blocked     |
+
+## APG and A11y Contract
+
+- role: `switch` (strictly binary; no indeterminate/mixed state)
+- `aria-checked`: `"true" | "false"` (reflects `isOn` state)
+- `aria-disabled`: `"true" | "false"` (reflects `isDisabled` state)
+- `tabindex`: `"0"` when enabled, `"-1"` when disabled
+- linkage:
+  - `aria-labelledby`: optional, references an external label element
+  - `aria-describedby`: optional, references help text or description element
+
+## Keyboard Contract
+
+| Key     | Action                                          |
+| ------- | ----------------------------------------------- |
+| `Space` | Toggle the `isOn` state; calls `preventDefault` |
+| `Enter` | Toggle the `isOn` state; calls `preventDefault` |
+
+All keyboard actions are no-ops when `isDisabled` is `true`.
+
+## Behavior Contract
+
+- `Space` key toggles the on/off state.
+- `Enter` key toggles the on/off state (specific to `switch` pattern in APG; checkbox only requires `Space`).
+- `Click` interaction toggles the on/off state.
+- Disabled switches do not respond to any toggle actions (`toggle`, `handleClick`, `handleKeyDown`).
+- Unrelated keys (anything other than `Space` or `Enter`) are ignored; `preventDefault` is NOT called.
+
+## Contract Prop Shapes
+
+### `getSwitchProps()`
+
+```ts
+{
+  id: string                          // '{idBase}-root'
+  role: 'switch'
+  tabindex: '0' | '-1'               // '-1' when disabled
+  'aria-checked': 'true' | 'false'   // reflects isOn
+  'aria-disabled': 'true' | 'false'  // reflects isDisabled
+  'aria-labelledby'?: string          // present when ariaLabelledBy option is set
+  'aria-describedby'?: string         // present when ariaDescribedBy option is set
+  onClick: () => void                 // calls handleClick
+  onKeyDown: (event) => void          // calls handleKeyDown
+}
+```
+
+## Transitions Table
+
+| Event / Action         | Current State     | Next State / Effect                          |
+| ---------------------- | ----------------- | -------------------------------------------- |
+| `toggle()`             | `isOn=false`      | `isOn=true`; fires `onCheckedChange(true)`   |
+| `toggle()`             | `isOn=true`       | `isOn=false`; fires `onCheckedChange(false)` |
+| `toggle()`             | `isDisabled=true` | no-op                                        |
+| `setOn(value)`         | any               | `isOn=value`; fires `onCheckedChange(value)` |
+| `setDisabled(value)`   | any               | `isDisabled=value`                           |
+| `handleClick()`        | any               | delegates to `toggle()`                      |
+| `handleKeyDown(Space)` | not disabled      | delegates to `toggle()`; `preventDefault`    |
+| `handleKeyDown(Enter)` | not disabled      | delegates to `toggle()`; `preventDefault`    |
+| `handleKeyDown(other)` | any               | no-op; no `preventDefault`                   |
+| `handleKeyDown(any)`   | `isDisabled=true` | no-op; no `preventDefault`                   |
+
+## Invariants
+
+1. `isOn` is always a `boolean` (strictly binary; no third state).
+2. A disabled switch cannot be toggled via `toggle()`, `handleClick()`, or `handleKeyDown()`.
+3. `aria-checked` is `"true"` when `isOn` is `true`, and `"false"` otherwise.
+4. `aria-disabled` is `"true"` when `isDisabled` is `true`, and `"false"` otherwise.
+5. `tabindex` is `"0"` when enabled, `"-1"` when disabled.
+6. `aria-labelledby` is present in props only when `ariaLabelledBy` option is provided.
+7. `aria-describedby` is present in props only when `ariaDescribedBy` option is provided.
+8. `getSwitchProps()` always returns a complete, ready-to-spread attribute object.
+
+## Adapter Expectations
+
+UIKit adapter (`cv-switch`) will:
+
+**Signals read (reactive, drive re-renders):**
+
+- `state.isOn()` — whether the switch is on or off
+- `state.isDisabled()` — whether user interaction is blocked
+
+**Actions called (event handlers, never mutate state directly):**
+
+- `actions.toggle()` — toggle on/off
+- `actions.setOn(value)` — programmatic state set
+- `actions.setDisabled(value)` — update disabled state
+- `actions.handleClick()` — on switch click
+- `actions.handleKeyDown(event)` — on switch keydown
+
+**Contracts spread (attribute maps applied directly to DOM elements):**
+
+- `contracts.getSwitchProps()` — spread onto the switch host element
+
+**UIKit-only concerns (NOT in headless):**
+
+- Toggled/untoggled content slots (on/off icons/text inside the track) — purely visual, no state or ARIA changes
+- Help text slot rendering — headless provides `aria-describedby` linkage via `ariaDescribedBy` option; UIKit renders the visible help text element and generates the matching id
+- CSS custom properties, animations, and size variants
+- `help-text` attribute and slot
+- Lifecycle events (`cv-change`, etc.)
+
+## Minimum Test Matrix
+
+- toggle behavior (off -> on -> off)
+- keyboard `Space` interaction
+- keyboard `Enter` interaction
+- click interaction
+- disabled state prevents state changes via all interaction paths (`toggle`, `handleClick`, `handleKeyDown`)
+- correct `aria-checked` mapping (`"true"` / `"false"`)
+- correct `aria-disabled` mapping
+- correct `tabindex` mapping (enabled vs disabled)
+- `aria-labelledby` and `aria-describedby` presence in contract props
+- `onCheckedChange` callback fires on state transitions
+- `preventDefault` called on `Space` and `Enter`
+- `preventDefault` NOT called on unrelated keys
+- unrelated keys do not toggle state
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings.
+- **Independence**: No imports from @project/_, apps/_, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- indeterminate state (not applicable to `switch` role)
+- native form submission integration (handled by adapters/wrappers)
+- toggled/untoggled content slots (UIKit visual concern)
+- help text rendering (UIKit visual concern; headless provides `aria-describedby` linkage only)