@chromvoid/headless-ui 0.1.0

package/specs/components/select.md

@@ -0,0 +1,144 @@
+# Select Component Contract
+
+## Purpose
+
+`Select` provides a headless single- or multi-selection model composed from trigger + listbox behavior, following the W3C APG Select-Only Combobox pattern.
+
+## Component Files
+
+- `src/select/index.ts` - model and public `createSelect` API
+- `src/select/select.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSelect(options)`
+  - `options` — `readonly ListboxOption[]`
+  - `idBase` — optional id prefix
+  - `ariaLabel` — optional accessible label
+  - `initialOpen` — optional initial popup state
+  - `initialSelectedId` — optional initial selected id (single convenience)
+  - `initialSelectedIds` — optional initial selected ids array
+  - `selectionMode` — `'single'` (default) or `'multiple'`
+  - `closeOnSelect` — close popup on selection (default `true`)
+  - `placeholder` — fallback value text
+  - `disabled` — initial disabled state (default `false`)
+  - `required` — initial required state (default `false`)
+  - `onSelectedIdChange` — callback on first-selected-id change
+- `state` (signal-backed):
+  - `isOpen()` - popup visibility
+  - `activeId()` - currently focused option id
+  - `selectedIds()` - selected ids array
+  - `selectedId()` - computed first selected id
+  - `selectedLabel()` - computed first selected label
+  - `selectedLabels()` - computed ordered labels for all selected ids
+  - `restoreTargetId()` - trigger restore target after close
+  - `disabled()` - whether the select is disabled
+  - `required()` - whether the select is required
+- `actions`:
+  - `open`, `close`, `toggle`
+  - `select(id)` — in single mode calls `selectOnly`; in multiple mode calls `toggleSelected`
+  - `clear()`
+  - `setDisabled(value)` — update disabled state
+  - `setRequired(value)` — update required state
+  - `handleTriggerKeyDown`
+  - `handleListboxKeyDown`
+- `contracts`:
+  - `getTriggerProps()` — returns combobox ARIA props including `aria-activedescendant` when open
+  - `getListboxProps()` — includes `aria-multiselectable: 'true'` when `selectionMode='multiple'`
+  - `getOptionProps(id)`
+  - `getValueText()` — single: first label; multiple: comma-joined labels; fallback: placeholder
+
+## APG and A11y Contract
+
+Follows the W3C APG Select-Only Combobox pattern. DOM focus stays on the trigger; visual focus is managed via `aria-activedescendant`.
+
+- trigger role: `combobox`
+- trigger attributes:
+  - `aria-haspopup="listbox"`
+  - `aria-expanded`
+  - `aria-controls`
+  - `aria-activedescendant` — references the active option DOM id when open
+  - `aria-disabled` — when `disabled` is `true`
+  - `aria-required` — when `required` is `true`
+  - `aria-label` — optional accessible label
+- popup role: `listbox`
+- popup attributes:
+  - `aria-multiselectable` (when `selectionMode='multiple'`)
+  - `hidden`
+- option role: `option`
+- option attributes:
+  - `aria-selected`
+  - `aria-disabled` (when disabled)
+
+## Keyboard Contract
+
+- trigger (closed):
+  - `ArrowDown` / `Home`: open and focus first option
+  - `ArrowUp` / `End`: open and focus last option
+  - `Enter` / `Space`: toggle popup
+- listbox (open — DOM focus remains on trigger, visual focus via `aria-activedescendant`):
+  - `ArrowDown` / `ArrowUp` / `Home` / `End`: navigation delegated to listbox keyboard contract
+  - `Enter` / `Space`: select active option (single: `selectOnly`; multiple: `toggleSelected`)
+  - `Escape` / `Tab`: close and restore focus target
+- when disabled: all keyboard handlers are no-ops
+
+## Behavior Contract
+
+- `Select` reuses `createListbox` with configurable `selectionMode`.
+- Opening behavior chooses initial focus strategy (`selected`, `first`, `last`).
+- `select(id)` in single mode calls `selectOnly`; in multiple mode calls `toggleSelected`.
+- Selection callback `onSelectedIdChange` fires only on actual first-selected-id changes.
+- `getValueText()` returns comma-joined labels in multiple mode, first label in single mode, fallback placeholder, or empty string.
+- When `disabled` is `true`, all interaction actions (`open`, `close`, `toggle`, `select`, `clear`, keyboard handlers) are no-ops.
+- `disabled` and `required` are mutable via `setDisabled`/`setRequired` actions for dynamic updates.
+
+## Invariants
+
+- `selectedId` must equal `selectedIds[0]` when present.
+- `selectedLabel` must resolve from `selectedId` and option map.
+- `selectedLabels` must resolve from `selectedIds` and option map, preserving order.
+- Trigger `data-selected-id` / `data-selected-label` must reflect computed selection state.
+- Close path must set `restoreTargetId` to trigger id.
+- When open, trigger `aria-activedescendant` must reference the active option DOM id.
+- When disabled, `aria-disabled="true"` must be present on trigger props.
+- When required, `aria-required="true"` must be present on trigger props.
+
+## Minimum Test Matrix
+
+- trigger keyboard open/close flow
+- trigger/listbox role and `aria-controls` linkage (trigger role is `combobox`)
+- trigger `aria-activedescendant` references active option when open
+- active option selection with `Enter`
+- selected state and value text synchronization
+- open-on-arrow-up path focusing last option
+- multi-select toggle via `select()` — `selectedIds` grows/shrinks
+- multi-select `getValueText()` — comma-joined labels
+- multi-select `getListboxProps()` — `aria-multiselectable: 'true'`
+- multi-select + `closeOnSelect: false` — popup stays open
+- `selectedLabels` computed — returns ordered labels
+- disabled blocks all interactions (open, select, keyboard)
+- disabled `getTriggerProps()` includes `aria-disabled: 'true'`
+- required `getTriggerProps()` includes `aria-required: 'true'`
+- `clear()` is no-op when disabled
+
+## Adapter Expectations
+
+UIKit adapter will:
+
+- Read: `state.isOpen`, `state.activeId`, `state.selectedId`, `state.selectedLabel`, `state.selectedIds`, `state.selectedLabels`, `state.disabled`, `state.required`, `state.restoreTargetId`
+- Call: `actions.open`, `actions.close`, `actions.toggle`, `actions.select`, `actions.clear`, `actions.setDisabled`, `actions.setRequired`, `actions.handleTriggerKeyDown`, `actions.handleListboxKeyDown`
+- Spread: `contracts.getTriggerProps()` onto trigger element, `contracts.getListboxProps()` onto listbox container, `contracts.getOptionProps(id)` onto each option
+- Display: `contracts.getValueText()` as trigger display text
+
+## 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)
+
+- async option loading and virtualization
+- option grouping and section headers (visual-only, UIKit concern)
+- native `<select>` form submission parity edge cases

package/specs/components/sidebar.md

@@ -0,0 +1,321 @@
+# Sidebar Component Contract
+
+## Purpose
+
+`Sidebar` is a headless contract for a persistent layout panel that lives at the inline-start edge of the viewport. Unlike `Drawer`, which is an overlay dialog, `Sidebar` is always in the DOM/layout flow. It supports two modes:
+
+1. **Desktop (persistent)** — a fixed panel that can be **expanded** (full width with labels) or **collapsed** (narrow icon rail). Not an overlay; no backdrop, no focus trap, no scroll lock.
+2. **Mobile (overlay)** — below a configurable breakpoint the sidebar switches to a modal overlay (backdrop, focus trap, Escape dismissal), delegating to `createDialog` internally for that behavior.
+
+### How it differs from Drawer
+
+| Concern            | Drawer                                      | Sidebar                                                  |
+| ------------------ | ------------------------------------------- | -------------------------------------------------------- |
+| Presence in layout | Overlay only; removed from flow when closed | Always in DOM/layout flow (desktop)                      |
+| Placement          | Any edge (`start`, `end`, `top`, `bottom`)  | Inline-start only                                        |
+| Collapsed state    | N/A                                         | Collapses to icon rail                                   |
+| Responsive mode    | N/A (always overlay)                        | Auto-switches between persistent panel and modal overlay |
+| Dialog delegation  | Always                                      | Mobile overlay mode only                                 |
+
+## Component Files
+
+- `src/sidebar/index.ts` - model and public `createSidebar` API
+- `src/sidebar/sidebar.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSidebar(options)`
+- `state` (signal-backed):
+  - `expanded()` — whether the sidebar is in full-width mode (`true`) or icon-rail mode (`false`)
+  - `overlayOpen()` — whether the mobile overlay is open (only meaningful when `mobile` is `true`)
+  - `mobile()` — whether the sidebar is in mobile/overlay mode
+  - `isFocusTrapped()` — computed: `true` when `mobile && overlayOpen` (delegated from dialog)
+  - `shouldLockScroll()` — computed: `true` when `mobile && overlayOpen` (delegated from dialog)
+  - `restoreTargetId()` — element id to return focus to on overlay close (delegated from dialog)
+  - `initialFocusTargetId()` — id of element to focus when overlay opens (delegated from dialog)
+- `actions`:
+  - `toggle()` — in desktop mode, toggles `expanded`; in mobile mode, toggles `overlayOpen`
+  - `expand()` — sets `expanded` to `true` (desktop mode only, no-op in mobile)
+  - `collapse()` — sets `expanded` to `false` (desktop mode only, no-op in mobile)
+  - `openOverlay()` — opens the mobile overlay (no-op if not in mobile mode)
+  - `closeOverlay(intent?)` — closes the mobile overlay (no-op if not in mobile mode)
+  - `setMobile(value)` — switches between desktop and mobile mode; when switching to desktop, closes overlay; when switching to mobile, collapses sidebar
+  - `handleKeyDown(event)` — Escape handling for mobile overlay (delegated from dialog)
+  - `handleOutsidePointer()` — outside click handling for mobile overlay (delegated from dialog)
+  - `handleOutsideFocus()` — outside focus handling for mobile overlay (delegated from dialog)
+- `contracts`:
+  - `getSidebarProps()` — props for the sidebar container element
+  - `getToggleProps()` — props for the expand/collapse toggle button
+  - `getOverlayProps()` — props for the mobile overlay backdrop
+  - `getRailProps()` — props for the collapsed rail container
+
+## CreateSidebarOptions
+
+| Option                  | Type                          | Default                | Description                                        |
+| ----------------------- | ----------------------------- | ---------------------- | -------------------------------------------------- |
+| `id`                    | `string`                      | `'sidebar'`            | Base id prefix for all generated ids               |
+| `defaultExpanded`       | `boolean`                     | `true`                 | Whether the sidebar starts expanded (desktop mode) |
+| `onExpandedChange`      | `(expanded: boolean) => void` | ---                    | Callback fired when `expanded` state changes       |
+| `closeOnEscape`         | `boolean`                     | `true`                 | Whether Escape key closes mobile overlay           |
+| `closeOnOutsidePointer` | `boolean`                     | `true`                 | Whether clicking outside closes mobile overlay     |
+| `initialFocusId`        | `string`                      | ---                    | Id of element to focus when mobile overlay opens   |
+| `ariaLabel`             | `string`                      | `'Sidebar navigation'` | Accessible label for the sidebar landmark          |
+
+## State Signal Surface
+
+| Signal                 | Type                   | Derived? | Source  | Description                                                      |
+| ---------------------- | ---------------------- | -------- | ------- | ---------------------------------------------------------------- |
+| `expanded`             | `Atom<boolean>`        | No       | sidebar | Whether sidebar shows full width (`true`) or icon rail (`false`) |
+| `overlayOpen`          | `Atom<boolean>`        | No       | dialog  | Whether mobile overlay is visible                                |
+| `mobile`               | `Atom<boolean>`        | No       | sidebar | Whether in mobile/overlay mode                                   |
+| `isFocusTrapped`       | `Computed<boolean>`    | Yes      | dialog  | `mobile() && overlayOpen()`                                      |
+| `shouldLockScroll`     | `Computed<boolean>`    | Yes      | dialog  | `mobile() && overlayOpen()`                                      |
+| `restoreTargetId`      | `Atom<string \| null>` | No       | dialog  | Element id to return focus to after overlay close                |
+| `initialFocusTargetId` | `Atom<string \| null>` | No       | dialog  | Id of element to receive focus when overlay opens                |
+
+## APG and A11y Contract
+
+### Desktop (persistent) mode
+
+- Sidebar container: `role="navigation"`, `aria-label`
+- No dialog semantics; the sidebar is a landmark, not an overlay
+- Toggle button: `aria-expanded`, `aria-controls` pointing to sidebar id
+- Rail state communicated via `data-collapsed="true|false"` on sidebar container
+
+### Mobile (overlay) mode
+
+- Overlay container: `role="dialog"`, `aria-modal="true"`, `aria-label`
+- Focus trap within the overlay panel
+- Escape key dismisses the overlay
+- Backdrop click dismisses the overlay
+- Return focus to toggle button on close
+- Initial focus on first focusable element or `initialFocusId` target
+
+## Behavior Contract
+
+### Desktop mode (`mobile: false`)
+
+- Sidebar is always visible in the layout, either expanded or collapsed to rail
+- `toggle()` switches between expanded and collapsed (icon rail)
+- `expand()` sets `expanded = true`; `collapse()` sets `expanded = false`
+- No focus trap, no scroll lock, no backdrop
+- `overlayOpen` is always `false` in desktop mode
+- `onExpandedChange` fires when `expanded` transitions
+
+### Mobile mode (`mobile: true`)
+
+- Sidebar is hidden by default; `overlayOpen` controls visibility
+- `toggle()` toggles `overlayOpen`
+- `expand()` and `collapse()` are no-ops
+- When `overlayOpen = true`: focus trap, scroll lock, backdrop visible
+- Escape key closes overlay (configurable via `closeOnEscape`)
+- Outside pointer closes overlay (configurable via `closeOnOutsidePointer`)
+- Focus returns to toggle button on close
+
+### Mode switching (`setMobile`)
+
+- `setMobile(true)`: closes any expanded state, sidebar enters overlay mode (closed by default)
+- `setMobile(false)`: closes overlay if open, sidebar enters persistent mode with `expanded = defaultExpanded`
+
+## Contract Prop Shapes
+
+### `getSidebarProps()`
+
+Props for the sidebar container element.
+
+```ts
+// Desktop mode:
+{
+  id: string                           // `${id}-panel`
+  role: 'navigation'
+  'aria-label': string
+  'data-collapsed': 'true' | 'false'  // reflects !expanded
+  'data-mobile': 'true' | 'false'
+}
+
+// Mobile mode (when overlayOpen):
+{
+  id: string                           // `${id}-panel`
+  role: 'dialog'
+  'aria-modal': 'true'
+  'aria-label': string
+  'data-collapsed': 'false'
+  'data-mobile': 'true'
+  'data-initial-focus'?: string
+  onKeyDown: (event) => void
+}
+```
+
+### `getToggleProps()`
+
+Props for the expand/collapse toggle button.
+
+```ts
+{
+  id: string                           // `${id}-toggle`
+  role: 'button'
+  tabindex: '0'
+  'aria-expanded': 'true' | 'false'   // desktop: reflects expanded; mobile: reflects overlayOpen
+  'aria-controls': string             // `${id}-panel`
+  'aria-label': string                // 'Expand sidebar' | 'Collapse sidebar' | 'Open sidebar' | 'Close sidebar'
+  onClick: () => void
+}
+```
+
+### `getOverlayProps()`
+
+Props for the mobile overlay backdrop. Only meaningful in mobile mode.
+
+```ts
+{
+  id: string                           // `${id}-overlay`
+  hidden: boolean                      // !overlayOpen || !mobile
+  'data-open': 'true' | 'false'
+  onPointerDownOutside: () => void
+  onFocusOutside: () => void
+}
+```
+
+### `getRailProps()`
+
+Props for the collapsed rail container. Only meaningful in desktop mode.
+
+```ts
+{
+  id: string                           // `${id}-rail`
+  role: 'navigation'
+  'aria-label': string
+  'data-visible': 'true' | 'false'    // reflects !expanded && !mobile
+}
+```
+
+## Transitions Table
+
+| Event / Action           | Current State                                                         | Next State / Effect                                                   |
+| ------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `toggle()`               | `mobile = false`, `expanded = false`                                  | `expanded = true`; fire `onExpandedChange(true)`                      |
+| `toggle()`               | `mobile = false`, `expanded = true`                                   | `expanded = false`; fire `onExpandedChange(false)`                    |
+| `toggle()`               | `mobile = true`, `overlayOpen = false`                                | `overlayOpen = true`; focus management begins                         |
+| `toggle()`               | `mobile = true`, `overlayOpen = true`                                 | `overlayOpen = false`; focus returns to toggle                        |
+| `expand()`               | `mobile = false`, `expanded = false`                                  | `expanded = true`; fire `onExpandedChange(true)`                      |
+| `expand()`               | `mobile = false`, `expanded = true`                                   | no-op                                                                 |
+| `expand()`               | `mobile = true`                                                       | no-op                                                                 |
+| `collapse()`             | `mobile = false`, `expanded = true`                                   | `expanded = false`; fire `onExpandedChange(false)`                    |
+| `collapse()`             | `mobile = false`, `expanded = false`                                  | no-op                                                                 |
+| `collapse()`             | `mobile = true`                                                       | no-op                                                                 |
+| `openOverlay()`          | `mobile = true`, `overlayOpen = false`                                | `overlayOpen = true`; focus management begins                         |
+| `openOverlay()`          | `mobile = true`, `overlayOpen = true`                                 | no-op                                                                 |
+| `openOverlay()`          | `mobile = false`                                                      | no-op                                                                 |
+| `closeOverlay(intent)`   | `mobile = true`, `overlayOpen = true`                                 | `overlayOpen = false`; focus returns to toggle                        |
+| `closeOverlay(intent)`   | `mobile = true`, `overlayOpen = false`                                | no-op                                                                 |
+| `closeOverlay(intent)`   | `mobile = false`                                                      | no-op                                                                 |
+| `setMobile(true)`        | `mobile = false`                                                      | `mobile = true`; `overlayOpen = false`                                |
+| `setMobile(false)`       | `mobile = true`                                                       | `mobile = false`; `overlayOpen = false`; `expanded = defaultExpanded` |
+| `setMobile(value)`       | `mobile = value`                                                      | no-op                                                                 |
+| `handleKeyDown(Escape)`  | `mobile = true`, `overlayOpen = true`, `closeOnEscape = true`         | `closeOverlay('escape')`                                              |
+| `handleKeyDown(Escape)`  | `mobile = false` OR `closeOnEscape = false`                           | no-op                                                                 |
+| `handleOutsidePointer()` | `mobile = true`, `overlayOpen = true`, `closeOnOutsidePointer = true` | `closeOverlay('outside-pointer')`                                     |
+| `handleOutsidePointer()` | `mobile = false` OR `closeOnOutsidePointer = false`                   | no-op                                                                 |
+| `handleOutsideFocus()`   | `mobile = true`, `overlayOpen = true`                                 | `closeOverlay('outside-focus')`                                       |
+
+### Derived state reactions
+
+| State Change                | `isFocusTrapped` | `shouldLockScroll` |
+| --------------------------- | ---------------- | ------------------ |
+| desktop, any expanded       | `false`          | `false`            |
+| mobile, overlayOpen = true  | `true`           | `true`             |
+| mobile, overlayOpen = false | `false`          | `false`            |
+
+## Invariants
+
+1. `expanded` and `overlayOpen` are independent signals; `expanded` governs desktop rail/full, `overlayOpen` governs mobile visibility.
+2. When `mobile = false`, `overlayOpen` must be `false`. Switching to desktop mode force-closes the overlay.
+3. When `mobile = true`, `expand()` and `collapse()` are no-ops; `expanded` value is irrelevant to rendering.
+4. When `mobile = false`, `openOverlay()` and `closeOverlay()` are no-ops.
+5. `getSidebarProps()` must return `role="navigation"` in desktop mode and `role="dialog"` with `aria-modal="true"` in mobile overlay mode (when open).
+6. `getToggleProps()` must always include `aria-expanded` reflecting the appropriate state (`expanded` in desktop, `overlayOpen` in mobile).
+7. `getOverlayProps().hidden` must be `true` whenever `mobile = false` or `overlayOpen = false`.
+8. `getRailProps()['data-visible']` must be `'true'` only when `!expanded && !mobile`.
+9. `setMobile(false)` must restore `expanded` to `defaultExpanded`.
+10. Focus trap and scroll lock must only be active when `mobile = true` AND `overlayOpen = true`.
+11. The sidebar must compose `createDialog` for mobile overlay mode; no duplication of dialog internals.
+12. `onExpandedChange` must fire only on actual transitions of `expanded`, not on no-ops or mobile mode changes.
+
+## Adapter Expectations
+
+UIKit adapters MUST bind to the headless model as follows:
+
+**Signals read (reactive, drive re-renders):**
+
+- `state.expanded()` — whether full-width or icon rail (desktop)
+- `state.overlayOpen()` — whether mobile overlay is visible
+- `state.mobile()` — whether in mobile/overlay mode
+- `state.isFocusTrapped()` — whether focus trap should be active
+- `state.shouldLockScroll()` — whether body scroll lock should be active
+- `state.restoreTargetId()` — element id to focus after overlay close
+- `state.initialFocusTargetId()` — element id to focus on overlay open
+
+**Actions called (event handlers, never mutate state directly):**
+
+- `actions.toggle()` — toggle expand/collapse (desktop) or open/close (mobile)
+- `actions.expand()` — expand sidebar (desktop only)
+- `actions.collapse()` — collapse to rail (desktop only)
+- `actions.openOverlay()` — open mobile overlay
+- `actions.closeOverlay(intent?)` — close mobile overlay
+- `actions.setMobile(value)` — switch between desktop/mobile mode (typically driven by a media query observer)
+- `actions.handleKeyDown(event)` — Escape handling for mobile overlay
+- `actions.handleOutsidePointer()` — outside click for mobile overlay
+- `actions.handleOutsideFocus()` — outside focus for mobile overlay
+
+**Contracts spread (attribute maps applied directly to DOM elements):**
+
+- `contracts.getSidebarProps()` — spread onto the sidebar panel element (role switches between `navigation` and `dialog` based on mode)
+- `contracts.getToggleProps()` — spread onto the toggle button element
+- `contracts.getOverlayProps()` — spread onto the mobile backdrop element
+- `contracts.getRailProps()` — spread onto the collapsed rail element
+
+**UIKit-only concerns (NOT in headless):**
+
+- Lifecycle events (`cv-expand`, `cv-collapse`, `cv-overlay-open`, `cv-overlay-close`)
+- CSS transitions for expand/collapse and slide-in overlay animations
+- Backdrop rendering and styling
+- Scroll lock implementation (headless provides the signal, UIKit applies the side effect)
+- Focus trap implementation (headless provides the signal, UIKit manages DOM focus)
+- Media query observer for automatic `setMobile()` calls based on breakpoint
+- Icon-only rendering logic for rail mode
+
+## Minimum Test Matrix
+
+- Default state: `expanded = true`, `overlayOpen = false`, `mobile = false`
+- `toggle()` in desktop mode toggles `expanded`
+- `toggle()` in mobile mode toggles `overlayOpen`
+- `expand()` and `collapse()` work in desktop, no-op in mobile
+- `openOverlay()` and `closeOverlay()` work in mobile, no-op in desktop
+- `setMobile(true)` closes overlay, switches mode
+- `setMobile(false)` closes overlay, restores `expanded` to `defaultExpanded`
+- `getSidebarProps()` returns `role="navigation"` in desktop, `role="dialog"` in mobile overlay
+- `getToggleProps()` returns correct `aria-expanded` for each mode
+- `getOverlayProps().hidden` is `true` in desktop mode
+- `getRailProps()['data-visible']` is `'true'` only when collapsed in desktop mode
+- Escape key closes mobile overlay (when enabled)
+- Outside pointer closes mobile overlay (when enabled)
+- `onExpandedChange` fires on expand/collapse transitions only
+- `isFocusTrapped` and `shouldLockScroll` are `true` only when mobile overlay is open
+- Custom `id` propagates to all generated ids
+- `defaultExpanded: false` starts sidebar collapsed
+
+## 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.
+- **Composition**: `createSidebar` composes `createDialog` for mobile overlay mode; no duplication of dialog internals.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- Inline-end placement (right sidebar in LTR)
+- Nested sidebars or multiple sidebar instances
+- Swipe-to-dismiss gesture handling for mobile overlay
+- Complex animations/transitions (CSS/JS animations are UIKit concerns)
+- Resizable sidebar (drag to resize width)

package/specs/components/slider-multi-thumb.md

@@ -0,0 +1,78 @@
+# Multi-Thumb Slider Component Contract
+
+## Purpose
+
+`SliderMultiThumb` provides a headless APG-aligned model for a range input with multiple handles (thumbs), typically used for selecting a sub-range (e.g., price range).
+
+It handles multi-value state, thumb collision/crossing prevention, and independent keyboard navigation for each thumb.
+
+## Component Files
+
+- `src/slider-multi-thumb/index.ts` - model and public `createSliderMultiThumb` API
+- `src/slider-multi-thumb/slider-multi-thumb.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSliderMultiThumb(options)`
+- `state` (signal-backed):
+  - `values()`: `number[]`
+  - `min()`: `number`
+  - `max()`: `number`
+  - `step()`: `number`
+  - `activeThumbIndex()`: `number | null`
+  - `isDisabled()`: `boolean`
+- `actions`:
+  - `setValue(index, value)`: sets a specific thumb's value
+  - `increment(index)`, `decrement(index)`
+  - `incrementLarge(index)`, `decrementLarge(index)`
+  - `handleKeyDown(index, event)`
+- `contracts`:
+  - `getRootProps()`
+  - `getThumbProps(index)`
+  - `getTrackProps()`
+
+## APG and A11y Contract
+
+- each thumb role: `slider`
+- `aria-valuenow`: current value of the specific thumb
+- `aria-valuemin`: minimum possible value for this thumb (often constrained by adjacent thumbs)
+- `aria-valuemax`: maximum possible value for this thumb
+- `aria-orientation`: `"horizontal" | "vertical"`
+- `tabindex`: `0` on each thumb
+- linkage: each thumb should have an `aria-label` or `aria-labelledby` identifying its purpose (e.g., "Minimum price", "Maximum price")
+
+## Behavior Contract
+
+- Keyboard interactions (`Arrows`, `PageUp/Down`, `Home`, `End`) apply to the currently focused thumb.
+- Thumbs are constrained by the global `min` and `max`.
+- By default, thumbs cannot cross each other (e.g., `values[0] <= values[1]`).
+- Moving a thumb to its limit (adjacent thumb or range boundary) stops the movement.
+- Optional "push" behavior: moving one thumb can push adjacent thumbs if they collide (out of scope for baseline).
+
+## Invariants
+
+- `min <= values[i] <= max` for all `i`.
+- `values[i] <= values[i+1]` (non-crossing invariant).
+- `activeThumbIndex` refers to the thumb that last received focus or interaction.
+
+## Minimum Test Matrix
+
+- independent thumb movement via keyboard
+- collision prevention (thumb 0 cannot exceed thumb 1)
+- boundary constraints (min/max)
+- Home/End behavior for each thumb (Home on thumb 1 moves it to thumb 0's value or min)
+- snapping to step for all thumbs
+- correct `aria-valuemin/max` updates when adjacent thumbs move
+
+## 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)
+
+- crossing thumbs (where `values[0] > values[1]` is allowed)
+- dynamic thumb addition/removal
+- non-linear scales

package/specs/components/slider.md

@@ -0,0 +1,84 @@
+# Slider Component Contract
+
+## Purpose
+
+`Slider` provides a headless APG-aligned model for an input where the user selects a value from within a given range.
+
+It handles range constraints, step increments, and standard keyboard navigation for single-thumb sliders.
+
+## Component Files
+
+- `src/slider/index.ts` - model and public `createSlider` API
+- `src/slider/slider.test.ts` - unit behavior tests
+
+## Public API
+
+- `createSlider(options)`
+- `state` (signal-backed):
+  - `value()`: `number`
+  - `min()`: `number`
+  - `max()`: `number`
+  - `step()`: `number`
+  - `percentage()`: `number` (0 to 100)
+  - `isDisabled()`: `boolean`
+- `actions`:
+  - `setValue(value)`: sets the value within constraints
+  - `increment()`, `decrement()`
+  - `incrementLarge()`, `decrementLarge()`
+  - `setFirst()`, `setLast()`
+  - `handleKeyDown(event)`
+- `contracts`:
+  - `getRootProps()`
+  - `getThumbProps()`
+  - `getTrackProps()`
+
+## APG and A11y Contract
+
+- thumb role: `slider`
+- `aria-valuenow`: current value
+- `aria-valuemin`: minimum value
+- `aria-valuemax`: maximum value
+- `aria-valuetext`: optional string representation of the value
+- `aria-orientation`: `"horizontal" | "vertical"`
+- `aria-disabled`: boolean
+- `tabindex`: `0` on the thumb
+
+## Behavior Contract
+
+- `ArrowRight` / `ArrowUp` increments the value by `step`.
+- `ArrowLeft` / `ArrowDown` decrements the value by `step`.
+- `PageUp` increments the value by a larger step (default 10% of range).
+- `PageDown` decrements the value by a larger step.
+- `Home` sets the value to `min`.
+- `End` sets the value to `max`.
+- Values are always clamped between `min` and `max`.
+- Values are always snapped to the nearest `step` increment.
+
+## Invariants
+
+- `min <= value <= max`
+- `min < max`
+- `step > 0`
+
+## Minimum Test Matrix
+
+- value clamping at min/max boundaries
+- step increment/decrement behavior
+- large step (PageUp/PageDown) behavior
+- Home/End key behavior
+- vertical orientation keyboard parity
+- snapping to nearest step on manual `setValue`
+- disabled state prevents value changes
+
+## 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)
+
+- multiple thumbs (see `SliderMultiThumb` spec)
+- non-linear scales (logarithmic, etc.)
+- inverted ranges (max < min)