@chromvoid/headless-ui 0.1.0

package/specs/components/grid.md

@@ -0,0 +1,186 @@
+# Grid Component Contract
+
+## Purpose
+
+`Grid` provides a headless APG-aligned model for interactive tabular data, enabling users to navigate across rows and columns using directional keys.
+
+## Component Files
+
+- `src/grid/index.ts` - model and public `createGrid` API
+- `src/grid/grid.test.ts` - unit behavior tests
+
+## Public API
+
+### `createGrid(options): GridModel`
+
+#### Options (`CreateGridOptions`)
+
+| Option                   | Type                                           | Default             | Description                                      |
+| ------------------------ | ---------------------------------------------- | ------------------- | ------------------------------------------------ |
+| `rows`                   | `readonly GridRow[]`                           | required            | Row definitions (`{ id, index?, disabled? }`)    |
+| `columns`                | `readonly GridColumn[]`                        | required            | Column definitions (`{ id, index?, disabled? }`) |
+| `disabledCells`          | `readonly GridCellId[]`                        | `[]`                | Individually disabled cells                      |
+| `idBase`                 | `string`                                       | `'grid'`            | Prefix for generated DOM ids                     |
+| `ariaLabel`              | `string`                                       | —                   | Static `aria-label` for the grid root            |
+| `ariaLabelledBy`         | `string`                                       | —                   | `aria-labelledby` reference for the grid root    |
+| `focusStrategy`          | `'roving-tabindex' \| 'aria-activedescendant'` | `'roving-tabindex'` | Focus management strategy                        |
+| `selectionMode`          | `'single' \| 'multiple'`                       | `'single'`          | Whether multi-cell selection is allowed          |
+| `selectionFollowsFocus`  | `boolean`                                      | `false`             | Auto-select cell on focus move                   |
+| `totalRowCount`          | `number`                                       | `rows.length`       | Logical row count (for virtualization)           |
+| `totalColumnCount`       | `number`                                       | `columns.length`    | Logical column count (for virtualization)        |
+| `pageSize`               | `number`                                       | `10`                | Rows per page for PageUp/PageDown (minimum 1)    |
+| `initialActiveCellId`    | `GridCellId \| null`                           | `null`              | Initial active cell (normalized on create)       |
+| `initialSelectedCellIds` | `readonly GridCellId[]`                        | `[]`                | Initial selected cells (filtered for validity)   |
+| `isReadOnly`             | `boolean`                                      | `false`             | Marks all cells as `aria-readonly`               |
+
+### State (signal-backed)
+
+- `activeCellId: Atom<GridCellId | null>` - currently focused cell `{ rowId, colId }`, or `null`
+- `selectedCellIds: Atom<Set<string>>` - set of selected cell keys (format: `"rowId::colId"`)
+- `rowCount: Computed<number>` - `max(totalRowCount, rows.length)`
+- `columnCount: Computed<number>` - `max(totalColumnCount, columns.length)`
+
+### Actions
+
+- **focus**: `setActiveCell(cell: GridCellId)` - set active cell (normalizes to nearest valid cell; syncs selection if `selectionFollowsFocus`)
+- **navigation**: `moveUp`, `moveDown`, `moveLeft`, `moveRight`, `moveRowStart`, `moveRowEnd`, `moveGridStart`, `moveGridEnd`, `pageUp`, `pageDown`
+- **selection**: `selectCell(cell)`, `toggleCellSelection(cell)`, `selectRow(rowId)`, `selectColumn(colId)`
+- **keyboard**: `handleKeyDown(event: GridKeyboardEventLike)` - dispatches to navigation/selection actions based on key
+
+### Contracts (ready-to-spread ARIA prop objects)
+
+- `getGridProps(): GridProps`
+- `getRowProps(rowId: string): GridRowProps`
+- `getCellProps(rowId: string, colId: string): GridCellProps`
+
+#### `GridProps`
+
+| Prop                    | Type                  | Notes                                                                    |
+| ----------------------- | --------------------- | ------------------------------------------------------------------------ |
+| `id`                    | `string`              | `"{idBase}-root"`                                                        |
+| `role`                  | `'grid'`              |                                                                          |
+| `tabindex`              | `'0' \| '-1'`         | `'0'` for `aria-activedescendant` strategy, `'-1'` for `roving-tabindex` |
+| `aria-label`            | `string \| undefined` | From options                                                             |
+| `aria-labelledby`       | `string \| undefined` | From options                                                             |
+| `aria-multiselectable`  | `'true' \| 'false'`   | Based on `selectionMode`                                                 |
+| `aria-colcount`         | `number`              | From `columnCount` computed                                              |
+| `aria-rowcount`         | `number`              | From `rowCount` computed                                                 |
+| `aria-activedescendant` | `string \| undefined` | Cell DOM id when using `aria-activedescendant` strategy                  |
+
+#### `GridRowProps`
+
+| Prop            | Type     | Notes                                                            |
+| --------------- | -------- | ---------------------------------------------------------------- |
+| `id`            | `string` | `"{idBase}-row-{rowId}"`                                         |
+| `role`          | `'row'`  |                                                                  |
+| `aria-rowindex` | `number` | 1-based; uses `row.index` if provided, else positional index + 1 |
+
+#### `GridCellProps`
+
+| Prop            | Type                  | Notes                                                                            |
+| --------------- | --------------------- | -------------------------------------------------------------------------------- |
+| `id`            | `string`              | `"{idBase}-cell-{rowId}-{colId}"`                                                |
+| `role`          | `'gridcell'`          |                                                                                  |
+| `tabindex`      | `'0' \| '-1'`         | `'0'` only for active cell in `roving-tabindex` mode (and not disabled)          |
+| `aria-colindex` | `number`              | 1-based; uses `column.index` if provided, else positional index + 1              |
+| `aria-selected` | `'true' \| 'false'`   | Whether cell is in `selectedCellIds`                                             |
+| `aria-readonly` | `'true' \| undefined` | Set when `isReadOnly` option is true                                             |
+| `aria-disabled` | `'true' \| undefined` | Set when cell is disabled (row disabled, column disabled, or in `disabledCells`) |
+| `data-active`   | `'true' \| 'false'`   | Whether cell is the active cell                                                  |
+| `onFocus`       | `() => void`          | Calls `setActiveCell` for this cell                                              |
+
+## APG and A11y Contract
+
+- root role: `grid`
+- row role: `row`
+- cell role: `gridcell`
+- focus strategies:
+  - `roving-tabindex` (default) - active cell gets `tabindex="0"`, all others `tabindex="-1"`
+  - `aria-activedescendant` - grid root gets `tabindex="0"` and `aria-activedescendant` pointing to active cell DOM id
+- required attributes:
+  - root: `aria-label` or `aria-labelledby`, `aria-multiselectable`, `aria-colcount`, `aria-rowcount`
+  - row: `aria-rowindex`
+  - cell: `aria-colindex`, `aria-selected`, `aria-readonly`, `tabindex`
+
+## Keyboard Contract
+
+| Key          | Modifier    | Action                                                                                      |
+| ------------ | ----------- | ------------------------------------------------------------------------------------------- |
+| `ArrowUp`    | —           | `moveUp()`                                                                                  |
+| `ArrowDown`  | —           | `moveDown()`                                                                                |
+| `ArrowLeft`  | —           | `moveLeft()`                                                                                |
+| `ArrowRight` | —           | `moveRight()`                                                                               |
+| `Home`       | —           | `moveRowStart()`                                                                            |
+| `End`        | —           | `moveRowEnd()`                                                                              |
+| `Home`       | Ctrl / Meta | `moveGridStart()`                                                                           |
+| `End`        | Ctrl / Meta | `moveGridEnd()`                                                                             |
+| `PageUp`     | —           | `pageUp()`                                                                                  |
+| `PageDown`   | —           | `pageDown()`                                                                                |
+| `Enter`      | —           | `moveDown()`                                                                                |
+| `Space`      | —           | `toggleCellSelection(activeCell)` (multiple mode) or `selectCell(activeCell)` (single mode) |
+
+## Transitions Table
+
+| Trigger               | Current State              | Action                             | Next State                                                                         |
+| --------------------- | -------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------- |
+| Arrow key             | any active cell            | `moveUp/Down/Left/Right`           | Active cell moves to nearest non-disabled cell in direction; no change at boundary |
+| Home                  | active cell                | `moveRowStart`                     | Active cell moves to first enabled cell in current row                             |
+| End                   | active cell                | `moveRowEnd`                       | Active cell moves to last enabled cell in current row                              |
+| Ctrl+Home             | active cell                | `moveGridStart`                    | Active cell moves to first enabled cell in entire grid                             |
+| Ctrl+End              | active cell                | `moveGridEnd`                      | Active cell moves to last enabled cell in entire grid                              |
+| PageUp                | active cell                | `pageUp`                           | Active cell moves up by `pageSize` rows (clamped), skipping disabled               |
+| PageDown              | active cell                | `pageDown`                         | Active cell moves down by `pageSize` rows (clamped), skipping disabled             |
+| Enter                 | active cell                | `moveDown`                         | Active cell moves to next row (same column)                                        |
+| Space                 | active cell, single mode   | `selectCell(activeCell)`           | `selectedCellIds` set to `{activeCell}`                                            |
+| Space                 | active cell, multiple mode | `toggleCellSelection(activeCell)`  | `selectedCellIds` toggled for active cell                                          |
+| `setActiveCell(cell)` | any                        | normalize + set                    | Active cell set to normalized cell; if `selectionFollowsFocus`, selection synced   |
+| `selectRow(rowId)`    | any                        | select all enabled cells in row    | `selectedCellIds` set to enabled cells in row (single mode: first only)            |
+| `selectColumn(colId)` | any                        | select all enabled cells in column | `selectedCellIds` set to enabled cells in column (single mode: first only)         |
+
+## Invariants
+
+- `activeCellId` must always point to a valid, non-disabled cell if the grid has any enabled cells; `null` only when no enabled cells exist
+- `activeCellId` is normalized on creation: invalid or disabled initial values fall back to the first enabled cell
+- `aria-rowcount` and `aria-colcount` must match the logical dimensions, even if only a subset is rendered (virtualization)
+- Selection state is independent of focus unless `selectionFollowsFocus` is enabled
+- Disabled cells (via row `disabled`, column `disabled`, or `disabledCells`) are always skipped during keyboard navigation
+- `initialSelectedCellIds` are filtered on creation: disabled or non-existent cells are excluded
+- `getRowProps` and `getCellProps` throw `Error` for unknown row/cell ids
+
+## Adapter Expectations
+
+UIKit (or any rendering adapter) must:
+
+1. **Render structure**: create elements for grid root, rows, and cells; spread the prop objects from `getGridProps()`, `getRowProps()`, `getCellProps()` onto the respective elements
+2. **Wire keyboard**: attach a `keydown` listener on the grid root that calls `actions.handleKeyDown(event)` and calls `event.preventDefault()` for handled keys
+3. **Manage DOM focus**: when `activeCellId` changes, call `.focus()` on the corresponding cell element (for `roving-tabindex` strategy) — the headless model sets `tabindex` but does not perform DOM focus
+4. **Subscribe to state**: re-render when `state.activeCellId` or `state.selectedCellIds` change, so that contract prop objects reflect the latest values
+5. **Forward `onFocus`**: the `onFocus` handler in `getCellProps` must be connected to the cell element's `focus` event so that clicking or tabbing into a cell updates the model
+6. **Prevent default**: adapter should `preventDefault()` on keyboard events that the grid handles, to avoid page scroll on arrow/space keys
+
+## Minimum Test Matrix
+
+- 2D navigation (arrows) across rows and columns
+- boundary handling (Home, End, Ctrl+Home, Ctrl+End)
+- skipping disabled cells during navigation
+- multi-selection behavior (if enabled)
+- correct ARIA attribute mapping for virtualized grids
+- focus strategy parity (`roving-tabindex` vs `aria-activedescendant`)
+- Space key selection (single and multiple mode)
+- Enter key navigation
+- `selectionFollowsFocus` behavior
+- initial state normalization (invalid `initialActiveCellId`, disabled cells in `initialSelectedCellIds`)
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom 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)
+
+- cell editing mode (inline inputs)
+- column/row reordering (drag and drop)
+- column resizing
+- context menu integration

package/specs/components/input.md

@@ -0,0 +1,254 @@
+# Input Component Contract
+
+## Purpose
+
+`Input` is a headless APG-aligned contract for a single-line text input control. It manages value state, input type resolution (text, password, email, url, tel, search), disabled/readonly/required semantics, clearable behavior, password visibility toggling, and focus tracking. It provides ready-to-spread ARIA attribute maps for the native input element, the clear button, and the password toggle button.
+
+## Component Files
+
+- `src/input/index.ts` - model and public `createInput` API
+- `src/input/input.test.ts` - unit behavior tests
+
+## Public API
+
+- `createInput(options)`
+  - `options`:
+    - `idBase?`: `string` - base for generated IDs (default: `"input"`)
+    - `value?`: `string` - initial value (default: `""`)
+    - `type?`: `InputType` - initial input type (default: `"text"`)
+    - `disabled?`: `boolean` - initial disabled state (default: `false`)
+    - `readonly?`: `boolean` - initial readonly state (default: `false`)
+    - `required?`: `boolean` - initial required state (default: `false`)
+    - `placeholder?`: `string` - initial placeholder text (default: `""`)
+    - `clearable?`: `boolean` - whether the clear button is available (default: `false`)
+    - `passwordToggle?`: `boolean` - whether the password toggle is available (default: `false`)
+    - `onInput?`: `(value: string) => void` - callback on value change via user action
+    - `onClear?`: `() => void` - callback when the value is cleared
+- **Types**:
+  - `InputType = "text" | "password" | "email" | "url" | "tel" | "search"`
+- `state` (signal-backed):
+  - `value()`: `string` - current input value
+  - `type()`: `InputType` - configured input type
+  - `disabled()`: `boolean` - whether the input is disabled
+  - `readonly()`: `boolean` - whether the input is readonly
+  - `required()`: `boolean` - whether the input is required
+  - `placeholder()`: `string` - placeholder text
+  - `clearable()`: `boolean` - whether the clear button is enabled
+  - `passwordToggle()`: `boolean` - whether the password toggle is enabled
+  - `passwordVisible()`: `boolean` - whether password text is currently revealed
+  - `focused()`: `boolean` - whether the input has focus
+  - `filled()`: `boolean` - **derived**: `true` when `value.length > 0`
+  - `resolvedType()`: `string` - **derived**: the effective `type` attribute for the native `<input>` element; equals `"text"` when `type === "password" && passwordVisible === true`, otherwise equals `type`
+  - `showClearButton()`: `boolean` - **derived**: `true` when `clearable && filled && !disabled && !readonly`
+  - `showPasswordToggle()`: `boolean` - **derived**: `true` when `type === "password" && passwordToggle`
+- `actions`:
+  - `setValue(value: string)`: updates the value; calls `onInput` callback
+  - `setType(type: InputType)`: updates the input type; resets `passwordVisible` to `false`
+  - `setDisabled(disabled: boolean)`: updates disabled state
+  - `setReadonly(readonly: boolean)`: updates readonly state
+  - `setRequired(required: boolean)`: updates required state
+  - `setPlaceholder(placeholder: string)`: updates placeholder text
+  - `setClearable(clearable: boolean)`: updates clearable state
+  - `setPasswordToggle(toggle: boolean)`: updates password toggle state; resets `passwordVisible` to `false` when `toggle` becomes `false`
+  - `togglePasswordVisibility()`: toggles `passwordVisible`; no-op if `type !== "password"` or `passwordToggle === false`
+  - `setFocused(focused: boolean)`: updates focus state
+  - `clear()`: sets value to `""`, calls `onClear` callback; no-op if `disabled` or `readonly`
+  - `handleInput(value: string)`: processes native input event; delegates to `setValue`
+  - `handleKeyDown(event: Pick<KeyboardEvent, "key"> & { preventDefault?: () => void })`: handles `Escape` key to clear (when clearable and filled)
+- `contracts`:
+  - `getInputProps()`: returns attribute map for the native `<input>` element
+  - `getClearButtonProps()`: returns attribute map for the clear button
+  - `getPasswordToggleProps()`: returns attribute map for the password toggle button
+
+## APG and A11y Contract
+
+### Native `<input>` element
+
+- `id`: `"{idBase}-input"`
+- `type`: `resolvedType` (resolved from `type` and `passwordVisible`)
+- `aria-disabled`: `"true"` when `disabled`, otherwise omitted
+- `aria-readonly`: `"true"` when `readonly`, otherwise omitted
+- `aria-required`: `"true"` when `required`, otherwise omitted
+- `aria-invalid`: reserved for future validation integration; omitted by default
+- `placeholder`: current placeholder value, omitted when empty
+- `disabled`: `true` when `disabled` (native attribute for form semantics)
+- `readonly`: `true` when `readonly` (native attribute for form semantics)
+- `tabindex`: `"0"` when interactive, `"-1"` when `disabled`
+- `autocomplete`: `"off"` when `type === "password"` (prevents autofill conflicts with toggle)
+
+### Clear button
+
+- `role`: `"button"`
+- `aria-label`: `"Clear input"` (localizable by adapter)
+- `tabindex`: `"-1"` (not in tab order; activated by Escape key or pointer)
+- `hidden`: `true` when `showClearButton` is `false`
+- `aria-hidden`: `"true"` when `hidden` (prevents screen readers from announcing an unavailable control)
+
+### Password toggle button
+
+- `role`: `"button"`
+- `aria-label`: `"Show password"` when `passwordVisible === false`, `"Hide password"` when `passwordVisible === true`
+- `aria-pressed`: `"true"` when `passwordVisible`, `"false"` otherwise
+- `tabindex`: `"0"` when visible, `"-1"` when hidden
+- `hidden`: `true` when `showPasswordToggle` is `false`
+- `aria-hidden`: `"true"` when `hidden`
+
+## Behavior Contract
+
+### Value management
+
+- Setting a value via `setValue` or `handleInput` updates `state.value` and calls the `onInput` callback.
+- `clear()` sets value to `""`, calls `onClear`, and is a no-op when `disabled` or `readonly`.
+
+### Clearable
+
+- When `clearable` is `true`, the clear button becomes visible if the input is non-empty and not disabled/readonly.
+- Pressing `Escape` while the input is focused clears the value when `clearable && filled` are both true.
+- After clearing, the input retains focus.
+
+### Password toggle
+
+- When `type === "password"` and `passwordToggle === true`, the toggle button is visible.
+- Activating the toggle switches `passwordVisible`, which changes `resolvedType` between `"password"` and `"text"`.
+- `togglePasswordVisibility()` is a no-op when `type !== "password"` or `passwordToggle === false`.
+- Changing `type` away from `"password"` resets `passwordVisible` to `false`.
+- Disabling `passwordToggle` resets `passwordVisible` to `false`.
+
+### Focus management
+
+- `setFocused(true)` / `setFocused(false)` reflect the native focus/blur events.
+- UIKit listens for `focus`/`blur` on the native `<input>` and calls `setFocused`.
+
+### Disabled and readonly
+
+- A disabled input does not respond to `clear()`, `handleInput()`, or keyboard interactions.
+- A readonly input does not respond to `clear()` or `handleInput()`, but retains focus and keyboard navigation.
+- `setValue` bypasses the disabled/readonly guard (controlled/programmatic update).
+
+## Transitions Table
+
+| Event / Action               | Guard                                                | Effect          | Next State                                               |
+| ---------------------------- | ---------------------------------------------------- | --------------- | -------------------------------------------------------- |
+| `handleInput(v)`             | `!disabled && !readonly`                             | `setValue(v)`   | `value = v`; `onInput(v)` called                         |
+| `handleInput(v)`             | `disabled \|\| readonly`                             | --              | no change                                                |
+| `clear()`                    | `!disabled && !readonly`                             | `setValue("")`  | `value = ""`; `onClear()` called                         |
+| `clear()`                    | `disabled \|\| readonly`                             | --              | no change                                                |
+| `keydown Escape`             | `clearable && filled && !disabled && !readonly`      | `clear()`       | `value = ""`; `onClear()` called                         |
+| `keydown Escape`             | `!(clearable && filled) \|\| disabled \|\| readonly` | --              | no change                                                |
+| `togglePasswordVisibility()` | `type === "password" && passwordToggle`              | toggle          | `passwordVisible = !passwordVisible`                     |
+| `togglePasswordVisibility()` | `type !== "password" \|\| !passwordToggle`           | --              | no change                                                |
+| `setValue(v)`                | --                                                   | set value       | `value = v`; `onInput(v)` called                         |
+| `setType(t)`                 | --                                                   | set type        | `type = t`; `passwordVisible = false`                    |
+| `setDisabled(d)`             | --                                                   | set disabled    | `disabled = d`                                           |
+| `setReadonly(r)`             | --                                                   | set readonly    | `readonly = r`                                           |
+| `setRequired(r)`             | --                                                   | set required    | `required = r`                                           |
+| `setPlaceholder(p)`          | --                                                   | set placeholder | `placeholder = p`                                        |
+| `setClearable(c)`            | --                                                   | set clearable   | `clearable = c`                                          |
+| `setPasswordToggle(t)`       | --                                                   | set toggle      | `passwordToggle = t`; if `!t`: `passwordVisible = false` |
+| `setFocused(f)`              | --                                                   | set focused     | `focused = f`                                            |
+
+## Adapter Expectations
+
+UIKit (`cv-input`) binds to the headless contract as follows:
+
+- **Signals read**:
+  - `state.value()` - to reflect the current value and sync with the native `<input>`
+  - `state.disabled()` - to reflect the `disabled` host attribute
+  - `state.readonly()` - to reflect the `readonly` host attribute
+  - `state.required()` - to reflect the `required` host attribute
+  - `state.focused()` - to apply `:focus` / `[focused]` styling on the host
+  - `state.filled()` - to apply `[filled]` styling on the host (e.g., floating label position)
+  - `state.passwordVisible()` - to update the toggle button icon
+  - `state.showClearButton()` - to conditionally render the clear button
+  - `state.showPasswordToggle()` - to conditionally render the password toggle
+  - `state.resolvedType()` - UIKit does NOT recompute this; reads directly from headless
+- **Actions called**:
+  - `actions.setValue(v)` - when syncing attribute/property changes into headless
+  - `actions.setType(t)` - when the `type` attribute changes
+  - `actions.setDisabled(d)` - when the `disabled` attribute changes
+  - `actions.setReadonly(r)` - when the `readonly` attribute changes
+  - `actions.setRequired(r)` - when the `required` attribute changes
+  - `actions.setPlaceholder(p)` - when the `placeholder` attribute changes
+  - `actions.setClearable(c)` - when the `clearable` attribute changes
+  - `actions.setPasswordToggle(t)` - when the `password-toggle` attribute changes
+  - `actions.setFocused(f)` - on native `<input>` `focus`/`blur` events
+  - `actions.handleInput(v)` - on native `<input>` `input` event
+  - `actions.handleKeyDown(e)` - on native `<input>` `keydown` event
+  - `actions.clear()` - on clear button click
+  - `actions.togglePasswordVisibility()` - on password toggle button click
+- **Contracts spread**:
+  - `contracts.getInputProps()` - spread onto the native `<input>` element for `id`, `type`, `aria-disabled`, `aria-readonly`, `aria-required`, `placeholder`, `disabled`, `readonly`, `tabindex`, `autocomplete`
+  - `contracts.getClearButtonProps()` - spread onto the clear button `<button>` for `role`, `aria-label`, `tabindex`, `hidden`, `aria-hidden`
+  - `contracts.getPasswordToggleProps()` - spread onto the toggle button `<button>` for `role`, `aria-label`, `aria-pressed`, `tabindex`, `hidden`, `aria-hidden`
+- **Events dispatched by UIKit**:
+  - `cv-input` CustomEvent on value changes (from user interaction, not programmatic `setValue`)
+  - `cv-clear` CustomEvent when the value is cleared via clear button or Escape key
+
+## Invariants
+
+1. `resolvedType` must equal `"text"` when `type === "password" && passwordVisible === true`; otherwise it must equal `type`.
+2. `filled` must be `true` if and only if `value.length > 0`.
+3. `showClearButton` must be `true` if and only if `clearable && filled && !disabled && !readonly`.
+4. `showPasswordToggle` must be `true` if and only if `type === "password" && passwordToggle`.
+5. `passwordVisible` must be `false` whenever `type !== "password"` or `passwordToggle === false`.
+6. `clear()` must be a no-op when `disabled` or `readonly`.
+7. `togglePasswordVisibility()` must be a no-op when `type !== "password"` or `passwordToggle === false`.
+8. `aria-disabled` on the input must be `"true"` when `disabled` is `true`.
+9. `aria-readonly` on the input must be `"true"` when `readonly` is `true`.
+10. `aria-required` on the input must be `"true"` when `required` is `true`.
+11. The clear button must have `hidden: true` whenever `showClearButton` is `false`.
+12. The password toggle must have `hidden: true` whenever `showPasswordToggle` is `false`.
+13. The password toggle `aria-pressed` must reflect `passwordVisible`.
+14. `tabindex` on the native input must be `"-1"` when `disabled`, `"0"` otherwise.
+15. `onInput` must not be called from `clear()`; `onClear` is called instead.
+16. `setType` must always reset `passwordVisible` to `false`.
+
+## Minimum Test Matrix
+
+- set initial value via options and verify `state.value()`
+- `handleInput(v)` updates value and calls `onInput`
+- `handleInput(v)` is no-op when disabled
+- `handleInput(v)` is no-op when readonly
+- `clear()` sets value to `""` and calls `onClear`
+- `clear()` is no-op when disabled
+- `clear()` is no-op when readonly
+- `Escape` key clears value when clearable and filled
+- `Escape` key does nothing when not clearable
+- `Escape` key does nothing when value is empty
+- `togglePasswordVisibility()` toggles `passwordVisible` when type is password and toggle enabled
+- `togglePasswordVisibility()` is no-op when type is not password
+- `togglePasswordVisibility()` is no-op when password toggle is disabled
+- `resolvedType` returns `"text"` when password is visible
+- `resolvedType` returns `"password"` when password is not visible
+- `setType` resets `passwordVisible` to false
+- `setPasswordToggle(false)` resets `passwordVisible` to false
+- `filled` is true when value is non-empty, false when empty
+- `showClearButton` reflects `clearable && filled && !disabled && !readonly`
+- `showPasswordToggle` reflects `type === "password" && passwordToggle`
+- `getInputProps()` returns correct `aria-disabled`, `aria-readonly`, `aria-required`
+- `getInputProps()` returns `tabindex "-1"` when disabled, `"0"` otherwise
+- `getInputProps()` returns `resolvedType` as the `type` attribute
+- `getClearButtonProps()` returns `hidden: true` when clear button should not show
+- `getClearButtonProps()` returns correct `aria-label`
+- `getPasswordToggleProps()` returns correct `aria-pressed` reflecting visibility
+- `getPasswordToggleProps()` returns correct `aria-label` based on visibility
+- `getPasswordToggleProps()` returns `hidden: true` when toggle should not show
+- `setValue` works even when disabled (programmatic/controlled update)
+- `setFocused` correctly updates focused 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)
+
+- validation / error state management (future `ValidatedInput` or form-level spec)
+- multi-line input / textarea (separate `Textarea` component)
+- input masking or formatting
+- prefix / suffix slot content management (UIKit layout concern)
+- autofill / autocomplete beyond password `autocomplete="off"`
+- native form submission integration (handled by adapters/wrappers)
+- number, date, time, or other non-text input types

package/specs/components/landmarks.md

@@ -0,0 +1,136 @@
+# Landmarks Component Contract
+
+## Purpose
+
+`Landmarks` is a headless contract for defining structural regions of a page to improve navigation for assistive technology users. It ensures that page regions are correctly identified with ARIA roles and accessible labels.
+
+## Component Files
+
+- `src/landmarks/index.ts` - model and public `createLandmark` API
+- `src/landmarks/landmarks.test.ts` - unit behavior tests
+
+## Public API
+
+- `createLandmark(options)`
+  - `options`:
+    - `type`: landmark type (`banner`, `main`, `navigation`, `complementary`, `contentinfo`, `search`, `form`, `region`)
+    - `label?`: string or signal — accessible label text
+    - `labelId?`: string or signal — ID of the labelling element
+    - `idBase?`: string — base id prefix for generated ids (default: `'landmark-{type}'`)
+- `state` (signal-backed):
+  - `type()` — the ARIA landmark role
+  - `label()` — accessible label string, or `null` if not provided
+  - `labelId()` — ID of the labelling element, or `null` if not provided
+- `actions`: none (landmark is a pure semantic wrapper with no state transitions)
+- `contracts`:
+  - `getLandmarkProps()` — returns complete ARIA prop object for the landmark element
+
+## State Signal Surface
+
+| Signal    | Type                   | Derived? | Description                            |
+| --------- | ---------------------- | -------- | -------------------------------------- |
+| `type`    | `Atom<LandmarkType>`   | No       | The ARIA landmark role                 |
+| `label`   | `Atom<string \| null>` | No       | Accessible label text, or `null`       |
+| `labelId` | `Atom<string \| null>` | No       | ID of the labelling element, or `null` |
+
+## APG and A11y Contract
+
+- roles:
+  - `banner` (header)
+  - `main`
+  - `navigation` (nav)
+  - `complementary` (aside)
+  - `contentinfo` (footer)
+  - `search`
+  - `form`
+  - `region`
+- required attributes:
+  - `aria-label` or `aria-labelledby` if multiple landmarks of the same type exist on a page (e.g., multiple `navigation` regions)
+  - `role` attribute if using non-semantic HTML elements
+
+## Behavior Contract
+
+- **Semantic Mapping**:
+  - the component ensures that the correct ARIA role is applied to the element
+  - if a semantic HTML element is used (e.g., `<main>`, `<nav>`), the role is redundant but harmless; if a `<div>` is used, the role is mandatory
+- **Labeling**:
+  - if a `label` is provided, it is applied via `aria-label`
+  - if a `labelId` is provided, it is applied via `aria-labelledby`
+  - if both `label` and `labelId` are provided, `aria-labelledby` takes precedence and `aria-label` is omitted
+- **Static Behavior**:
+  - landmark has no user-driven state transitions; it is a pure semantic wrapper
+  - state is set at creation time and may be updated reactively if atom-backed options are provided
+
+## Contract Prop Shapes
+
+### `getLandmarkProps()`
+
+```ts
+{
+  role: LandmarkType                   // the landmark ARIA role
+  'aria-label'?: string                // present when label is set AND labelId is NOT set
+  'aria-labelledby'?: string           // present when labelId is set (takes precedence over label)
+}
+```
+
+## Transitions Table
+
+| Event / Action           | Current State        | Next State / Effect                                                                |
+| ------------------------ | -------------------- | ---------------------------------------------------------------------------------- |
+| `createLandmark(opts)`   | —                    | `type = opts.type`, `label = opts.label ?? null`, `labelId = opts.labelId ?? null` |
+| atom update on `label`   | `label = oldValue`   | `label = newValue`; `getLandmarkProps()` recomputes                                |
+| atom update on `labelId` | `labelId = oldValue` | `labelId = newValue`; `getLandmarkProps()` recomputes                              |
+
+> No user-driven actions exist. State changes only via reactive atom updates from the consumer.
+
+## Invariants
+
+1. `role` is always one of the eight valid `LandmarkType` values.
+2. When `labelId` is set, `aria-labelledby` is present and `aria-label` is omitted (labelledby takes precedence).
+3. When only `label` is set (no `labelId`), `aria-label` is present.
+4. When neither `label` nor `labelId` is set, neither `aria-label` nor `aria-labelledby` is present.
+5. A page should generally have only one `banner`, `main`, and `contentinfo` landmark.
+6. If multiple landmarks of the same type are used, they **must** have unique labels to be distinguishable by assistive technology (enforced via `findLandmarkUniquenessIssues` and `hasLandmarkUniquenessIssues` utilities).
+
+## Adapter Expectations
+
+UIKit adapters MUST bind to the headless model as follows:
+
+**Signals read (reactive, drive re-renders):**
+
+- `state.type()` — the ARIA landmark role (used to select semantic HTML element or apply role attribute)
+- `state.label()` — accessible label text (synced from the `label` attribute on the host)
+- `state.labelId()` — ID of the labelling element (synced from the `label-id` attribute on the host)
+
+**Actions called:**
+
+- None. Landmark is a pure semantic wrapper with no user-driven state transitions.
+
+**Contracts spread (attribute maps applied directly to DOM elements):**
+
+- `contracts.getLandmarkProps()` — spread onto the root landmark element
+
+**UIKit-only concerns (NOT in headless):**
+
+- `display: block` styling on the host element
+- Attribute-to-signal synchronization (`label` attr to `state.label`, `label-id` attr to `state.labelId`)
+- Choice of semantic HTML element vs `<div>` with explicit `role`
+
+## Minimum Test Matrix
+
+- verify correct role application for each landmark type
+- verify `aria-label` application when provided
+- verify `aria-labelledby` application when provided
+- ensure no role is applied if a semantic element is already sufficient (optional optimization)
+
+## 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)
+
+- automatic landmark detection/audit
+- skip-link generation (handled by a separate utility)