@chromvoid/headless-ui 0.1.0

package/specs/components/popover.md

@@ -0,0 +1,252 @@
+# Popover Component Contract
+
+## Purpose
+
+`Popover` provides a headless APG-aligned non-modal overlay model for contextual content linked to a trigger. Supports progressive enhancement via the native HTML Popover API when available, with automatic fallback to manual visibility management.
+
+## Component Files
+
+- `src/popover/index.ts` - model and public `createPopover` API
+- `src/popover/popover.test.ts` - unit behavior tests
+
+## Public API
+
+- `createPopover(options)`
+- `state` (signal-backed):
+  - `isOpen()` — current visibility state
+  - `triggerId()` — active trigger identifier
+  - `openedBy()` — open source (`keyboard`, `pointer`, `programmatic`)
+  - `restoreTargetId()` — focus restore target after close
+  - `lastDismissIntent()` — latest close intent
+  - `isInteractive()` — computed: mirrors `isOpen`
+  - `useNativePopover()` — whether native Popover API is active
+- `actions`:
+  - `setTriggerId(id)`
+  - `open(source)`
+  - `close(intent)`
+  - `toggle(source)`
+  - `handleTriggerKeyDown(event)`
+  - `handleContentKeyDown(event)`
+  - `handleOutsidePointer()`
+  - `handleOutsideFocus()`
+  - `handleNativeToggle(newState)` — sync headless state when native popover fires `toggle` event
+- `contracts`:
+  - `getTriggerProps()`
+  - `getContentProps()`
+
+## CreatePopoverOptions
+
+| Option                  | Type             | Default              | Description                                 |
+| ----------------------- | ---------------- | -------------------- | ------------------------------------------- |
+| `idBase`                | `string`         | `'popover'`          | Base id prefix for all generated ids        |
+| `initialOpen`           | `boolean`        | `false`              | Whether the popover starts open             |
+| `initialTriggerId`      | `string \| null` | `'{idBase}-trigger'` | Trigger element id                          |
+| `ariaLabel`             | `string`         | —                    | Content `aria-label`                        |
+| `ariaLabelledBy`        | `string`         | —                    | Content `aria-labelledby`                   |
+| `closeOnEscape`         | `boolean`        | `true`               | Whether Escape key closes the popover       |
+| `closeOnOutsidePointer` | `boolean`        | `true`               | Whether clicking outside closes the popover |
+| `closeOnOutsideFocus`   | `boolean`        | `true`               | Whether focusing outside closes the popover |
+| `useNativePopover`      | `boolean`        | `false`              | Enable native HTML Popover API integration  |
+
+## State Signal Surface
+
+| Signal              | Type                                 | Derived? | Description                               |
+| ------------------- | ------------------------------------ | -------- | ----------------------------------------- |
+| `isOpen`            | `Atom<boolean>`                      | No       | Single source of truth for visibility     |
+| `triggerId`         | `Atom<string \| null>`               | No       | Active trigger element id                 |
+| `openedBy`          | `Atom<PopoverOpenSource \| null>`    | No       | How the popover was opened                |
+| `restoreTargetId`   | `Atom<string \| null>`               | No       | Element id to return focus to after close |
+| `lastDismissIntent` | `Atom<PopoverDismissIntent \| null>` | No       | Most recent dismiss intent                |
+| `isInteractive`     | `Computed<boolean>`                  | Yes      | `isOpen()` — always mirrors open state    |
+| `useNativePopover`  | `Atom<boolean>`                      | No       | Whether native Popover API mode is active |
+
+## APG and A11y Contract
+
+- trigger role: `button`
+- trigger attributes:
+  - `aria-haspopup="dialog"`
+  - `aria-expanded` — reflects `isOpen`
+  - `aria-controls` — points to content id
+  - when native popover is active: `popovertarget` — points to content id
+- content role: `dialog`
+- content attributes:
+  - `aria-modal="false"`
+  - `aria-label` or `aria-labelledby`
+  - `hidden` — reflects `!isOpen` (manual mode only)
+  - when native popover is active: `popover="manual"` — native popover attribute
+
+## Keyboard Contract
+
+- trigger keys `Enter`, `Space`, `ArrowDown`: toggle popover
+- content key `Escape`: dismiss popover (unless `closeOnEscape` is disabled)
+
+## Behavior Contract
+
+- `Popover` composes `overlay-focus` in non-trapping mode (`trapFocus=false`).
+- dismiss intents and open sources are captured as part of model state.
+- outside pointer and outside focus closing are independently configurable.
+- focus restore target is synchronized through overlay state.
+
+### Native Popover API Integration
+
+When `useNativePopover` is `true`:
+
+- **Content contract** includes `popover: 'manual'` attribute. The `manual` type is used because the headless layer manages all open/close logic; `auto` type is not used because it would cause the browser to close the popover independently from the headless state.
+- **Content contract** omits `hidden` attribute — native popover manages visibility via the popover attribute.
+- **Trigger contract** includes `popovertarget` attribute pointing to content id, and `popovertargetaction: 'toggle'`.
+- **Adapter hook**: The adapter (UIKit) is responsible for calling `showPopover()` / `hidePopover()` on the content DOM element when `isOpen` changes. The headless layer provides the state; the adapter applies the DOM side effect.
+- **`handleNativeToggle(newState)`**: When the native popover fires a `toggle` event (e.g., browser-initiated close), the adapter calls this action to synchronize headless state. `newState` is `'open'` or `'closed'`.
+- **Light-dismiss**: With `popover="manual"`, light-dismiss is NOT handled by the browser. The headless layer's `handleOutsidePointer` / `handleOutsideFocus` / `handleContentKeyDown` actions handle all dismiss behavior, keeping behavior consistent between native and manual modes.
+
+When `useNativePopover` is `false` (default):
+
+- Content uses `hidden` attribute for visibility.
+- No `popover` or `popovertarget` attributes emitted.
+- Outside dismiss is handled via document-level listeners in the adapter (same as current behavior).
+
+## Contract Prop Shapes
+
+### `getTriggerProps()`
+
+```ts
+{
+  id: string                          // trigger element id
+  role: 'button'
+  tabindex: '0'
+  'aria-haspopup': 'dialog'
+  'aria-expanded': 'true' | 'false'   // reflects isOpen
+  'aria-controls': string             // points to content id
+  popovertarget?: string              // content id (only when useNativePopover)
+  popovertargetaction?: 'toggle'      // (only when useNativePopover)
+  onClick: () => void
+  onKeyDown: (event) => void
+}
+```
+
+### `getContentProps()`
+
+```ts
+{
+  id: string                          // content element id
+  role: 'dialog'
+  tabindex: '-1'
+  'aria-modal': 'false'
+  'aria-label'?: string               // from options
+  'aria-labelledby'?: string          // from options
+  hidden?: boolean                    // !isOpen (only when NOT useNativePopover)
+  popover?: 'manual'                  // (only when useNativePopover)
+  onKeyDown: (event) => void
+  onPointerDownOutside: () => void
+  onFocusOutside: () => void
+}
+```
+
+## Transitions Table
+
+| Event / Action                                | Current State                                   | Next State / Effect                                     |
+| --------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------- |
+| `open(source)`                                | `isOpen = false`                                | `isOpen = true`; restore target cleared; `openedBy` set |
+| `close(intent)`                               | `isOpen = true`                                 | `isOpen = false`; `restoreTargetId` set to trigger id   |
+| `close(intent)`                               | `isOpen = false`                                | `lastDismissIntent` updated; no visibility change       |
+| `toggle(source)`                              | `isOpen = false`                                | calls `open(source)`                                    |
+| `toggle(source)`                              | `isOpen = true`                                 | calls `close('programmatic')`                           |
+| `handleTriggerKeyDown(Enter/Space/ArrowDown)` | any                                             | calls `toggle('keyboard')`                              |
+| `handleTriggerKeyDown(other key)`             | any                                             | no-op                                                   |
+| `handleContentKeyDown(Escape)`                | `isOpen = true`, `closeOnEscape = true`         | calls `close('escape')`                                 |
+| `handleContentKeyDown(Escape)`                | `closeOnEscape = false`                         | no-op                                                   |
+| `handleOutsidePointer()`                      | `isOpen = true`, `closeOnOutsidePointer = true` | calls `close('outside-pointer')`                        |
+| `handleOutsidePointer()`                      | `closeOnOutsidePointer = false`                 | no-op                                                   |
+| `handleOutsideFocus()`                        | `isOpen = true`, `closeOnOutsideFocus = true`   | calls `close('outside-focus')`                          |
+| `handleOutsideFocus()`                        | `closeOnOutsideFocus = false`                   | no-op                                                   |
+| `setTriggerId(id)`                            | any                                             | trigger id updated; affects future `restoreTargetId`    |
+| `handleNativeToggle('closed')`                | `isOpen = true`                                 | calls `close('programmatic')` to sync state             |
+| `handleNativeToggle('open')`                  | `isOpen = false`                                | calls `open('programmatic')` to sync state              |
+| `handleNativeToggle(same state)`              | any                                             | no-op (already in sync)                                 |
+
+### Derived state reactions
+
+| State Change | `isInteractive` |
+| ------------ | --------------- |
+| open         | `true`          |
+| closed       | `false`         |
+
+## Invariants
+
+1. `isInteractive` must mirror `isOpen` — always derived, never set directly.
+2. `aria-expanded` must always reflect `isOpen`.
+3. Trigger `aria-controls` must match content `id`.
+4. `lastDismissIntent` and `restoreTargetId` are updated on dismiss paths.
+5. `isOpen` is the single source of truth for visibility.
+6. Closing the popover must set `restoreTargetId` to the trigger element id for focus restoration.
+7. When `useNativePopover` is `true`, content props must include `popover: 'manual'` and must NOT include `hidden`.
+8. When `useNativePopover` is `false`, content props must include `hidden` and must NOT include `popover`.
+9. `handleNativeToggle` must be idempotent — calling it with the current state must be a no-op.
+
+## Adapter Expectations
+
+UIKit adapters MUST bind to the headless model as follows:
+
+**Signals read (reactive, drive re-renders):**
+
+- `state.isOpen()` — whether the popover is visible
+- `state.triggerId()` — trigger element id
+- `state.openedBy()` — how the popover was opened
+- `state.restoreTargetId()` — element id to focus after close
+- `state.lastDismissIntent()` — most recent dismiss intent
+- `state.isInteractive()` — whether the popover content is interactive
+- `state.useNativePopover()` — whether native Popover API mode is active
+
+**Actions called (event handlers, never mutate state directly):**
+
+- `actions.open(source?)` / `actions.close(intent?)` — programmatic open/close
+- `actions.toggle(source?)` — toggle open state
+- `actions.setTriggerId(id)` — set custom trigger element id
+- `actions.handleTriggerKeyDown(event)` — on trigger keydown
+- `actions.handleContentKeyDown(event)` — on content keydown (Escape handling)
+- `actions.handleOutsidePointer()` — on pointer outside the popover
+- `actions.handleOutsideFocus()` — on focus outside the popover
+- `actions.handleNativeToggle(newState)` — sync state from native `toggle` event
+
+**Contracts spread (attribute maps applied directly to DOM elements):**
+
+- `contracts.getTriggerProps()` — spread onto the trigger button element (includes `popovertarget` when native)
+- `contracts.getContentProps()` — spread onto the popover content panel (includes `popover="manual"` when native, `hidden` when manual)
+
+**UIKit-only concerns (NOT in headless):**
+
+- Calling `showPopover()` / `hidePopover()` on the content DOM element (when `useNativePopover` is active)
+- Listening for native `toggle` / `beforetoggle` events on the content element and calling `handleNativeToggle`
+- Document-level `pointerdown` and `focusin` listeners for outside dismiss
+- CSS transitions, animations, placement, arrow rendering
+- Focus restoration DOM side effect (reading `restoreTargetId` and calling `element.focus()`)
+- Lifecycle events (`toggle`, `beforetoggle` naming per design decision #4)
+
+## Minimum Test Matrix
+
+- trigger keyboard open (`Enter`, `Space`, `ArrowDown`) and escape close
+- role and aria linkage (`aria-controls` matches content `id`)
+- `aria-expanded` reflects `isOpen`
+- outside pointer close policy enable/disable
+- outside focus close policy enable/disable
+- dismiss intent and restore-target synchronization
+- `useNativePopover = true`: content props include `popover: 'manual'`, no `hidden`
+- `useNativePopover = true`: trigger props include `popovertarget`
+- `useNativePopover = false`: content props include `hidden`, no `popover`
+- `handleNativeToggle('closed')` syncs state from open to closed
+- `handleNativeToggle('open')` syncs state from closed to open
+- `handleNativeToggle` is idempotent when state is already in sync
+
+## 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)
+
+- collision/placement engine
+- nested popover orchestration
+- modal focus trapping behavior
+- portal/layer manager concerns (adapter-level)
+- `popover="auto"` type (headless manages all dismiss logic; `manual` is used exclusively)

package/specs/components/progress.md

@@ -0,0 +1,188 @@
+# Progress Component Contract
+
+## Purpose
+
+`Progress` provides a headless progressbar model for determinate and indeterminate loading states.
+
+## Component Files
+
+- `src/progress/index.ts` - model and public `createProgress` API
+- `src/progress/progress.test.ts` - unit behavior tests
+
+## Options (`CreateProgressOptions`)
+
+| Option            | Type                                     | Default      | Description                                                                                               |
+| ----------------- | ---------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| `idBase`          | `string`                                 | `'progress'` | Prefix for atom debug names and generated element IDs                                                     |
+| `value`           | `number`                                 | `min`        | Initial value; clamped and snapped to range                                                               |
+| `min`             | `number`                                 | `0`          | Minimum value                                                                                             |
+| `max`             | `number`                                 | `100`        | Maximum value                                                                                             |
+| `step`            | `number`                                 | `1`          | Step size for `increment()`/`decrement()` (delegated to `createValueRange`)                               |
+| `isIndeterminate` | `boolean`                                | `false`      | Whether to start in indeterminate mode                                                                    |
+| `valueText`       | `string \| undefined`                    | `undefined`  | Static override for `aria-valuetext`; takes precedence over `formatValueText` and the percentage fallback |
+| `ariaLabel`       | `string \| undefined`                    | `undefined`  | Passed through to `aria-label`                                                                            |
+| `ariaLabelledBy`  | `string \| undefined`                    | `undefined`  | Passed through to `aria-labelledby`                                                                       |
+| `ariaDescribedBy` | `string \| undefined`                    | `undefined`  | Passed through to `aria-describedby`                                                                      |
+| `formatValueText` | `(value: number) => string \| undefined` | `undefined`  | Custom formatter for `aria-valuetext`; used when `valueText` is not set                                   |
+| `onValueChange`   | `(value: number) => void \| undefined`   | `undefined`  | Called when `value` actually changes (after clamping)                                                     |
+
+## Public API
+
+### `createProgress(options): ProgressModel`
+
+### State (signal-backed)
+
+| Signal              | Type                | Description                                    |
+| ------------------- | ------------------- | ---------------------------------------------- |
+| `value()`           | `Atom<number>`      | Current value, clamped to `[min, max]`         |
+| `min()`             | `Atom<number>`      | Minimum boundary                               |
+| `max()`             | `Atom<number>`      | Maximum boundary                               |
+| `percentage()`      | `Computed<number>`  | Derived: `((value - min) / (max - min)) * 100` |
+| `isIndeterminate()` | `Atom<boolean>`     | Whether progress is in indeterminate mode      |
+| `isComplete()`      | `Computed<boolean>` | Derived: `!isIndeterminate && value >= max`    |
+
+### Actions
+
+| Action             | Signature                  | Description                                                               |
+| ------------------ | -------------------------- | ------------------------------------------------------------------------- |
+| `setValue`         | `(value: number) => void`  | Set value; clamped to range, fires `onValueChange` on actual change       |
+| `increment`        | `() => void`               | Increase value by `step`; clamped, fires `onValueChange` on actual change |
+| `decrement`        | `() => void`               | Decrease value by `step`; clamped, fires `onValueChange` on actual change |
+| `setIndeterminate` | `(value: boolean) => void` | Switch between determinate and indeterminate modes                        |
+
+### Contracts
+
+| Contract             | Return type     | Description                                                    |
+| -------------------- | --------------- | -------------------------------------------------------------- |
+| `getProgressProps()` | `ProgressProps` | Ready-to-spread ARIA attribute map for the progressbar element |
+
+#### `ProgressProps` shape
+
+```ts
+{
+  id: string                     // `${idBase}-root`
+  role: 'progressbar'
+  'aria-valuenow'?: string       // present only in determinate mode
+  'aria-valuemin'?: string       // present only in determinate mode
+  'aria-valuemax'?: string       // present only in determinate mode
+  'aria-valuetext'?: string      // present only in determinate mode (see resolution order below)
+  'aria-label'?: string          // from options.ariaLabel
+  'aria-labelledby'?: string     // from options.ariaLabelledBy
+  'aria-describedby'?: string    // from options.ariaDescribedBy
+}
+```
+
+`aria-valuetext` resolution order (determinate mode only):
+
+1. `options.valueText` if set (static string override)
+2. `options.formatValueText(value)` if provided
+3. Rounded percentage fallback: `"${Math.round(percentage)}%"`
+
+## APG and A11y Contract
+
+- role: `progressbar`
+- determinate mode attributes:
+  - `aria-valuenow`
+  - `aria-valuemin`
+  - `aria-valuemax`
+  - `aria-valuetext` (static override, custom formatter, or percentage fallback)
+- indeterminate mode:
+  - omit `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`
+- labeling:
+  - `aria-label` or `aria-labelledby`
+  - optional `aria-describedby`
+
+## Keyboard Contract
+
+- `Progress` is not keyboard-interactive as a widget role.
+- `increment`/`decrement` actions are programmatic state APIs.
+
+## Behavior Contract
+
+- Value handling is delegated to `createValueRange` for clamping and step behavior.
+- `onValueChange` fires only when value actually changes (after clamping).
+- Completion state is computed as `!isIndeterminate && value >= max`.
+
+## Transitions Table
+
+| Trigger                           | Precondition  | State change                            | Side effect                                |
+| --------------------------------- | ------------- | --------------------------------------- | ------------------------------------------ |
+| `actions.setValue(v)`             | any           | `value` = clamp(v, min, max)            | `onValueChange` if value changed           |
+| `actions.increment()`             | any           | `value` = clamp(value + step, min, max) | `onValueChange` if value changed           |
+| `actions.decrement()`             | any           | `value` = clamp(value - step, min, max) | `onValueChange` if value changed           |
+| `actions.setIndeterminate(true)`  | determinate   | `isIndeterminate` = true                | `isComplete` recomputes to false           |
+| `actions.setIndeterminate(false)` | indeterminate | `isIndeterminate` = false               | `isComplete` recomputes based on value/max |
+
+## Invariants
+
+- `value` must remain clamped to `[min, max]`.
+- `isComplete` must be `false` whenever `isIndeterminate` is `true`.
+- ARIA value attributes (`aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`) must be present only in determinate mode.
+- `aria-valuetext` resolution order: `valueText` > `formatValueText(value)` > rounded percentage string.
+- `percentage` must equal `0` when `min === max`.
+
+## Adapter Expectations
+
+This section defines what UIKit (`cv-progress`) binds to from the headless model.
+
+### Signals read by adapter
+
+| Signal                    | UIKit usage                                                        |
+| ------------------------- | ------------------------------------------------------------------ |
+| `state.value()`           | Not read directly; consumed via contracts                          |
+| `state.percentage()`      | Sets `--cv-progress-value` CSS custom property for indicator width |
+| `state.isIndeterminate()` | Sets `indeterminate` attribute on host for CSS animation switching |
+| `state.isComplete()`      | Sets `complete` attribute on host for visual feedback              |
+
+### Actions called by adapter
+
+| Action                        | UIKit trigger                                                       |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `actions.setValue(v)`         | When `value` attribute/property changes on the host element         |
+| `actions.setIndeterminate(v)` | When `indeterminate` attribute/property changes on the host element |
+
+Note: `increment()` and `decrement()` are available for programmatic use but have no direct DOM event trigger in UIKit.
+
+### Contracts spread by adapter
+
+| Contract             | Target element                           | Notes                                                     |
+| -------------------- | ---------------------------------------- | --------------------------------------------------------- |
+| `getProgressProps()` | Root progressbar element (`part="base"`) | Spread as attributes; provides `role`, `aria-*`, and `id` |
+
+### Options passed through from UIKit attributes
+
+| UIKit attribute    | Headless option   | Notes                                       |
+| ------------------ | ----------------- | ------------------------------------------- |
+| `value`            | `value`           | Numeric, synced via `setValue` action       |
+| `min`              | `min`             | Numeric                                     |
+| `max`              | `max`             | Numeric                                     |
+| `indeterminate`    | `isIndeterminate` | Boolean attribute                           |
+| `value-text`       | `valueText`       | Static string override for `aria-valuetext` |
+| `aria-label`       | `ariaLabel`       | Labeling                                    |
+| `aria-labelledby`  | `ariaLabelledBy`  | Labeling                                    |
+| `aria-describedby` | `ariaDescribedBy` | Labeling                                    |
+
+## Minimum Test Matrix
+
+- determinate aria value contract
+- indeterminate aria omission contract
+- `valueText` static override takes precedence over formatter and percentage
+- `formatValueText` custom formatter produces expected `aria-valuetext`
+- increment/decrement with clamping
+- completion-state transitions
+- `onValueChange` callback behavior
+- `setIndeterminate` toggles aria attribute presence
+
+## 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)
+
+- buffer/secondary-progress tracks
+- animated interpolation and transitions
+- cancellation/error state orchestration
+- adapter-level rendering and styling concerns

package/specs/components/radio-group.md

@@ -0,0 +1,151 @@
+# Radio Group Component Contract
+
+## Purpose
+
+`RadioGroup` provides a headless APG-aligned model for a set of checkable buttons where only one can be checked at a time.
+
+It handles roving tabindex, arrow-key navigation with automatic selection, and group-level state management.
+
+## Component Files
+
+- `src/radio-group/index.ts` - model and public `createRadioGroup` API
+- `src/radio-group/radio-group.test.ts` - unit behavior tests
+
+## Public API
+
+- `createRadioGroup(options)`
+  - `items`: `readonly RadioGroupItem[]` — radio definitions
+  - `idBase?`: `string` — prefix for generated ids
+  - `orientation?`: `'horizontal' | 'vertical'` — navigation axis (default `'horizontal'`)
+  - `isDisabled?`: `boolean` — initial group-level disabled state
+  - `ariaLabel?`: `string` — accessible label for the group
+  - `ariaLabelledBy?`: `string` — id reference for external label
+  - `initialValue?`: `string | null` — initially checked radio id
+  - `initialActiveId?`: `string | null` — initially focused radio id
+- `RadioGroupItem`:
+  - `id`: `string` — unique identifier
+  - `disabled?`: `boolean` — per-item disabled state
+  - `describedBy?`: `string` — id reference for description element (`aria-describedby`)
+
+### State (signal-backed)
+
+- `value()`: `string | null` — id of the checked radio
+- `activeId()`: `string | null` — id of the focused radio (roving tabindex target)
+- `isDisabled()`: `boolean` — group-level disabled state
+- `orientation`: `'horizontal' | 'vertical'` — navigation orientation (static after creation)
+
+### Actions
+
+- `select(id)`: checks the radio with the given id (no-op if disabled or id is not enabled)
+- `moveNext()`: moves focus and selection to the next enabled radio
+- `movePrev()`: moves focus and selection to the previous enabled radio
+- `moveFirst()`: moves focus and selection to the first enabled radio
+- `moveLast()`: moves focus and selection to the last enabled radio
+- `handleKeyDown(event)`: delegates to navigation/selection based on key
+- `setDisabled(value)`: updates group-level disabled state
+
+### Contracts
+
+- `getRootProps()` — returns `RadioGroupRootProps`:
+  - `role`: `'radiogroup'`
+  - `aria-label?`: `string`
+  - `aria-labelledby?`: `string`
+  - `aria-disabled?`: `'true'` (present only when disabled)
+  - `aria-orientation`: `'horizontal' | 'vertical'`
+  - `onKeyDown`: keyboard handler
+
+- `getRadioProps(id)` — returns `RadioProps`:
+  - `id`: `string` (generated: `{idBase}-radio-{id}`)
+  - `role`: `'radio'`
+  - `tabindex`: `'0' | '-1'` (roving tabindex)
+  - `aria-checked`: `'true' | 'false'`
+  - `aria-disabled?`: `'true'` (present when group or item is disabled)
+  - `aria-describedby?`: `string` (present when item has `describedBy`)
+  - `data-active`: `'true' | 'false'` (tracks focus, not selection)
+  - `onClick`: click handler
+  - `onKeyDown`: keyboard handler
+
+## APG and A11y Contract
+
+- root role: `radiogroup`
+- item role: `radio`
+- `aria-checked`: `"true" | "false"` on each radio
+- `aria-disabled`: on root (when entire group disabled) or individual radios
+- `aria-describedby`: on individual radios when description content is associated
+- `aria-orientation`: on root, reflects navigation axis
+- focus strategy: `roving-tabindex`
+  - only the active radio (checked, or first enabled when none checked) is in the tab sequence.
+  - if no radio is checked, the first enabled radio is in the tab sequence.
+- linkage: root supports `aria-label` and `aria-labelledby`
+
+## Behavior Contract
+
+- `ArrowDown` / `ArrowRight` moves focus to the next radio and checks it.
+- `ArrowUp` / `ArrowLeft` moves focus to the previous radio and checks it.
+- Navigation wraps around from last to first and vice versa.
+- `Home` moves focus and selection to the first enabled radio.
+- `End` moves focus and selection to the last enabled radio.
+- `Space` checks the focused radio if not already checked.
+- Disabled radios are skipped during arrow navigation.
+- If a radio is disabled, it cannot be checked.
+- When the entire group is disabled, all keyboard and click actions are no-ops.
+
+## Transitions
+
+| Event / Action                   | Current State         | Next State                    | Notes                                          |
+| -------------------------------- | --------------------- | ----------------------------- | ---------------------------------------------- |
+| `select(id)`                     | `value=X, activeId=Y` | `value=id, activeId=id`       | No-op if `isDisabled` or item disabled         |
+| `moveNext()`                     | `activeId=current`    | `value=next, activeId=next`   | Wraps; skips disabled; no-op if group disabled |
+| `movePrev()`                     | `activeId=current`    | `value=prev, activeId=prev`   | Wraps; skips disabled; no-op if group disabled |
+| `moveFirst()`                    | any                   | `value=first, activeId=first` | First enabled item; no-op if group disabled    |
+| `moveLast()`                     | any                   | `value=last, activeId=last`   | Last enabled item; no-op if group disabled     |
+| `handleKeyDown(ArrowRight/Down)` | any                   | delegates to `moveNext()`     |                                                |
+| `handleKeyDown(ArrowLeft/Up)`    | any                   | delegates to `movePrev()`     |                                                |
+| `handleKeyDown(Home)`            | any                   | delegates to `moveFirst()`    |                                                |
+| `handleKeyDown(End)`             | any                   | delegates to `moveLast()`     |                                                |
+| `handleKeyDown(Space)`           | `activeId=id`         | `value=id`                    | Selects focused radio; no-op if group disabled |
+| `setDisabled(v)`                 | `isDisabled=old`      | `isDisabled=v`                | Does not change value or activeId              |
+
+## Invariants
+
+- At most one radio can be checked at any time.
+- `activeId` must always be an enabled radio id (unless no enabled radios exist).
+- `value` and `activeId` are synchronized during arrow navigation (selection follows focus).
+- `value` is `null` or an enabled radio id.
+- `getRadioProps(id)` throws for unknown ids.
+- When `isDisabled` is `true`, `getRootProps()` includes `aria-disabled="true"`.
+- `tabindex="0"` is assigned to exactly one radio (the active one) when it is enabled; all others get `"-1"`.
+
+## Minimum Test Matrix
+
+- single selection behavior (checking one unchecks the previous)
+- arrow navigation with automatic selection and wrapping
+- skipping disabled radios during navigation
+- Home/End key behavior
+- initial state with no selection (first radio is tabbable)
+- initial state with selection (selected radio is tabbable)
+- group-level disabled blocks all interactions
+- `aria-describedby` present when item has `describedBy`
+
+## Adapter Expectations
+
+UIKit adapter (`cv-radio-group` + `cv-radio`) will:
+
+- **Read**: `state.value`, `state.activeId`, `state.isDisabled`, `state.orientation`
+- **Call**: `actions.select`, `actions.moveNext`, `actions.movePrev`, `actions.moveFirst`, `actions.moveLast`, `actions.handleKeyDown`, `actions.setDisabled`
+- **Spread**: `contracts.getRootProps()` onto the radio-group host/container, `contracts.getRadioProps(id)` onto each radio element
+- **Size** (`small | medium | large`): UIKit-only visual concern; does not affect headless contracts
+- **Description slot**: UIKit renders a secondary text slot; headless provides `aria-describedby` linkage via `RadioGroupItem.describedBy`
+
+## 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)
+
+- nested radio groups
+- manual activation mode (where arrows move focus but not selection)
+- native form submission integration (handled by adapters/wrappers)