@chromvoid/headless-ui 0.1.0

package/specs/ADR-003-public-api-versioning.md

@@ -0,0 +1,136 @@
+# ADR-003: Public API Versioning and Evolution Policy
+
+> **Status**: Draft
+> **Version**: 2026-02-08-r3
+> **Date**: 2026-02-08
+> **Authors**: Team ChromVoid
+> **Related Documents**:
+>
+> - [ADR-001-headless-architecture](./ADR-001-headless-architecture.md) - API baseline
+> - [ADR-002-repo-release-model](./ADR-002-repo-release-model.md) - release ownership
+
+## Context
+
+The package is distributed as an independent public library.
+Its API must evolve predictably for external consumers and remain stable across internal refactors.
+
+## Problem
+
+Without a formal policy:
+
+- safe vs breaking changes are inconsistently classified;
+- deprecation becomes ad-hoc;
+- consumers cannot plan upgrades confidently.
+
+## Goals
+
+1. Define SemVer policy.
+2. Define what counts as public API.
+3. Define a required deprecation flow.
+4. Make breaking changes explicit and planned.
+
+## Non-Goals
+
+- Changelog template details.
+- Release cadence policy.
+
+## Decision
+
+### 1. Public API Definition
+
+Public API includes only items exported from package root exports (`.`):
+
+- `createX` factories;
+- documented `actions`, `selectors`, and `state` contracts;
+- `get*Props` accessibility contracts;
+- documented public types.
+
+Anything not exported from root entrypoint is private implementation detail.
+
+### 2. SemVer Rules
+
+Pre-v1 policy (`0.x`):
+
+- `PATCH`: bug fix with no intentional contract reshape.
+- `MINOR`: additions and allowed contract redesign when it improves consumer DX.
+- all intentional breaking changes in `0.x` MUST include explicit migration notes.
+
+Post-v1 policy (`>=1.0.0`):
+
+- `PATCH`: bug fix with no public API contract change.
+- `MINOR`: backward-compatible additions.
+- `MAJOR`: any breaking runtime, type-level, or behavior-contract change.
+
+### 3. Deprecation Rules
+
+For each public API scheduled for removal:
+
+1. add `@deprecated` annotation in types and docs;
+2. publish release notes with migration path;
+3. keep at least one `MINOR` release cycle before removal;
+4. remove only in the next `MAJOR` release.
+
+Pre-v1 exception (`0.x`):
+
+- if rapid API redesign is needed for better consumer ergonomics, hard deprecation cycles may be shortened,
+  but migration notes are still mandatory.
+
+### 4. Behavior Compatibility
+
+Breaking change includes behavior contracts, not only signatures:
+
+- keyboard semantics;
+- focus and selection invariants;
+- ARIA contract shape.
+
+Any incompatible APG contract change requires `MAJOR`.
+
+### 5. Release Classification Checklist
+
+Before release, classify each change across:
+
+1. API shape (`createX`, options, return contracts)
+2. Type compatibility
+3. Behavior compatibility (APG, focus, keyboard)
+4. Migration requirements
+
+For post-v1 releases, if at least one item is incompatible, release must be `MAJOR`.
+
+For pre-v1 releases, incompatible changes are allowed in `MINOR`, but require migration notes and explicit release annotation.
+
+## Alternatives
+
+### A. Informal versioning only
+
+**Rejected**:
+
+- unpredictable for consumers;
+- high risk of accidental breaking releases.
+
+### B. Freeze API until 1.0
+
+**Rejected**:
+
+- blocks practical evolution;
+- does not fit early contract formation stage.
+
+## Consequences
+
+### Positive
+
+- clearer upgrade expectations;
+- fewer consumer regressions;
+- better external ecosystem trust.
+
+### Negative
+
+- stricter release review discipline required;
+- more documentation overhead for deprecations.
+
+## Change History
+
+| Date       | Change                                                                       |
+| ---------- | ---------------------------------------------------------------------------- |
+| 2026-02-08 | Initial draft created (r1)                                                   |
+| 2026-02-08 | Rewritten to full English and clarified release checklist (r2)               |
+| 2026-02-08 | Added pre-v1 DX-first versioning policy and migration-note requirements (r3) |

package/specs/ADR-004-focus-selection-policy.md

@@ -0,0 +1,117 @@
+# ADR-004: Shared Focus/Selection Policy and APG Strategy
+
+> **Status**: Draft
+> **Version**: 2026-02-08-r2
+> **Date**: 2026-02-08
+> **Authors**: Team ChromVoid
+> **Related Documents**:
+>
+> - [ADR-001-headless-architecture](./ADR-001-headless-architecture.md) - layers and API shape
+> - [WAI-ARIA APG Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) - listbox baseline behavior
+> - [WAI-ARIA APG Keyboard Interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) - keyboard and focus rules
+
+## Context
+
+The headless package must provide predictable APG-conformant behavior contracts.
+Main risk: inconsistent interpretation of focus, selection, and keyboard behavior across components.
+
+## Problem
+
+Without a shared policy:
+
+- one component may treat focus as selection while another does not;
+- keymaps drift between components;
+- `roving-tabindex` and `aria-activedescendant` are chosen ad-hoc;
+- accessibility regressions become more likely.
+
+## Goals
+
+1. Define shared focus and selection invariants.
+2. Define focus-strategy decision criteria.
+3. Standardize baseline keyboard behavior.
+4. Keep `get*Props()` contracts APG-conformant.
+
+## Non-Goals
+
+- Full keymap catalog for every future component.
+- Visual focus ring styling and presentation design.
+
+## Decision
+
+### 1. State Invariants
+
+1. `focus` and `selection` are independent states.
+2. Single-select may enable selection-follows-focus only as explicit option.
+3. Multi-select must not clear selection during standard arrow navigation.
+4. Active item (`activeId`) must always be valid option id or `null`.
+
+### 2. Focus Strategy Choice
+
+Supported strategies:
+
+- `roving-tabindex`
+- `aria-activedescendant`
+
+Selection rules:
+
+- use `roving-tabindex` by default for non-virtualized collections;
+- use `aria-activedescendant` when DOM focus must stay on root/control, or when virtualized behavior requires stable focus anchor;
+- strategy selection must be explicit in `createX(options)`.
+
+### 3. Baseline Keyboard Contract
+
+Required baseline, when applicable for a given pattern:
+
+- `ArrowUp/ArrowDown` (or horizontal equivalent): focus navigation;
+- `Home/End`: move to first/last item;
+- `Space`: toggle/select action according to APG;
+- `Enter`: activate action for activation-capable patterns;
+- `Escape`: dismiss/reset action for open/overlay-capable patterns.
+
+### 4. APG Props Contract
+
+`getRootProps()` and `getItemProps()` MUST:
+
+- provide correct `role` values;
+- provide `aria-selected` for selectable options;
+- provide `tabindex` or `aria-activedescendant` based on chosen strategy;
+- avoid any presentation logic.
+
+### 5. Compatibility Rule
+
+Focus/selection/keyboard semantic changes are behavior-breaking
+if they change observable contract behavior for consumers.
+
+## Alternatives
+
+### A. Support only one focus strategy
+
+**Rejected**:
+
+- does not cover all widget classes and virtualization cases.
+
+### B. Define policy per component without shared ADR
+
+**Rejected**:
+
+- leads to contract drift and inconsistent accessibility behavior.
+
+## Consequences
+
+### Positive
+
+- unified behavior model across components;
+- fewer APG regressions;
+- more predictable consumer integrations.
+
+### Negative
+
+- higher entry bar for new component implementations;
+- stricter keyboard/focus test matrix required.
+
+## Change History
+
+| Date       | Change                                                      |
+| ---------- | ----------------------------------------------------------- |
+| 2026-02-08 | Initial draft created (r1)                                  |
+| 2026-02-08 | Rewritten to full English and clarified strategy rules (r2) |

package/specs/IMPLEMENTATION-ROADMAP.md

@@ -0,0 +1,237 @@
+# Headless Components Implementation and Testing Roadmap
+
+## Scope
+
+This roadmap defines the next component implementations for `@chromvoid/headless-ui`
+and the required testing strategy for each component.
+
+The package remains independent and APG-driven, with one component per directory
+and one component spec per file.
+
+## Ground Rules
+
+- one component per directory: `src/<component>/`
+- one component spec: `specs/components/<component>.md`
+- TDD-first workflow (red -> green -> refactor)
+- APG behavior contracts are part of the public API
+- no internal monorepo imports (`@project/*`, `apps/*`)
+
+## Delivery Waves
+
+## APG Full Coverage Target (30 patterns)
+
+Source of truth: `https://www.w3.org/WAI/ARIA/apg/patterns/`
+
+Current status in this package:
+
+- implemented: Listbox, Combobox, Menu and Menubar (menu), Tabs, Tree View
+- planned: all remaining APG patterns below
+
+Patterns to cover in roadmap scope:
+
+1. Accordion (Sections With Show/Hide Functionality)
+2. Alert
+3. Alert and Message Dialogs
+4. Breadcrumb
+5. Button
+6. Carousel (Slide Show or Image Rotator)
+7. Checkbox
+8. Combobox
+9. Dialog (Modal)
+10. Disclosure (Show/Hide)
+11. Feed
+12. Grid (Interactive Tabular Data and Layout Containers)
+13. Landmarks
+14. Link
+15. Listbox
+16. Menu and Menubar
+17. Menu Button
+18. Meter
+19. Radio Group
+20. Slider
+21. Slider (Multi-Thumb)
+22. Spinbutton
+23. Switch
+24. Table
+25. Tabs
+26. Toolbar
+27. Tooltip
+28. Tree View
+29. Treegrid
+30. Window Splitter
+
+## Wave 1: Stabilization of Implemented Complex Widgets
+
+### Components
+
+- Listbox
+- Combobox
+- Menu and Menubar
+- Tabs
+- Tree View
+
+### Planned Work
+
+1. complete APG edge-case coverage for keyboard matrices and disabled-item invariants
+2. normalize public APIs and naming across implemented widgets
+3. align each implemented widget spec with latest APG wording and links
+
+### Required Tests
+
+- full keyboard matrix parity against APG contracts
+- id/reference integrity (`aria-controls`, `aria-labelledby`, `aria-activedescendant`)
+- regression tests for previously fixed interaction bugs
+
+## Wave 2: Core Form and Command Widgets
+
+### Components
+
+- Button
+- Checkbox
+- Radio Group
+- Switch
+- Slider
+- Slider (Multi-Thumb)
+- Spinbutton
+- Meter
+- Link
+
+### Planned Work
+
+1. implement per-pattern state models and headless prop contracts in `src/<component>/index.ts`
+2. add one APG-focused spec per component in `specs/components/<component>.md`
+3. extract reusable value-range and toggle primitives in shared core layers
+
+### Required Tests
+
+- value boundaries, stepping rules, and min/max clamping where applicable
+- selection/toggle semantics and role/state attributes
+- pointer + keyboard parity and disabled behavior
+
+## Wave 3: Disclosure, Overlay, and Messaging Patterns
+
+### Components
+
+- Disclosure (Show/Hide)
+- Accordion (Sections With Show/Hide Functionality)
+- Dialog (Modal)
+- Alert and Message Dialogs
+- Alert
+- Tooltip
+- Toolbar
+- Menu Button
+
+### Planned Work
+
+1. implement overlay and dismiss primitives reusable by dialog, alertdialog, tooltip, and menu button
+2. model focus entry/exit rules and restore-focus contracts
+3. define interaction boundaries for modal/non-modal behavior and announcement semantics
+
+### Required Tests
+
+- focus trapping/restore and escape/outside-intent close paths
+- heading/description/id linkage guarantees
+- non-interruptive vs interruptive announcement behavior (`alert` vs `alertdialog`)
+
+## Wave 4: Data Navigation and Collection Patterns
+
+### Components
+
+- Grid (Interactive Tabular Data and Layout Containers)
+- Treegrid
+- Table
+- Feed
+- Carousel (Slide Show or Image Rotator)
+- Window Splitter
+
+### Planned Work
+
+1. implement row/cell navigation engines and hierarchical grid contracts
+2. define static vs interactive tabular APIs (`table` vs `grid`/`treegrid`)
+3. implement region/slide control contracts for carousel and pane size contracts for window splitter
+
+### Required Tests
+
+- directional navigation and edit/interaction mode transitions
+- row/column/level metadata correctness where required
+- resize boundary behavior and persisted pane ratio contracts for splitter
+
+## Wave 5: Structural Navigation and Page Semantics
+
+### Components
+
+- Breadcrumb
+- Landmarks
+
+### Planned Work
+
+1. provide headless helpers for landmark role assignment and labeling contracts
+2. provide breadcrumb generation helpers with current-page semantics
+
+### Required Tests
+
+- semantic role/label correctness and uniqueness constraints
+- current-item semantics (`aria-current`) and link structure invariants
+
+## Wave 6: MVP-next Extension Components
+
+### Components
+
+- Select
+- Popover
+- Context Menu
+- Command Palette
+- Toast
+- Progress
+
+### Planned Work
+
+1. productize scaffold components into stable public contracts and expand behavior documentation parity
+2. enforce deterministic state transitions for open/close, execute, queue timing, and value semantics
+3. add explicit dependency sequencing to minimize churn in shared overlay/selection primitives
+
+### Required Tests
+
+- source/intent tracking for open, close, and dismiss behavior where applicable
+- keyboard invocation and command execution parity (`Enter`, `Space`, shortcut toggles)
+- queue/timer lifecycle correctness for toast pause/resume with remaining-duration preservation
+- determinate/indeterminate aria contract integrity for progress
+- regression tests for focus restore and target linkage contracts
+
+## Shared Testing Blueprint (applies to every component)
+
+For each component, the test suite must include:
+
+1. state transition tests
+2. keyboard contract tests
+3. accessibility props contract tests
+4. disabled and edge-case invariant tests
+5. regression tests for previously fixed bugs
+
+Suggested local layout:
+
+- `src/<component>/index.ts`
+- `src/<component>/<component>.test.ts`
+- optional split: `src/<component>/<component>.keyboard.test.ts` (when keyboard matrix grows)
+
+## Definition of Done per Component
+
+A component is done when:
+
+1. component spec exists and is up to date
+2. public API exported via `src/index.ts`
+3. APG contract covered by tests
+4. `npm run lint` passes
+5. `npm run test` passes
+6. boundary check remains green
+
+## Execution Order (recommended)
+
+1. Stabilization of implemented complex widgets
+2. Core form and command widgets
+3. Disclosure, overlay, and messaging patterns
+4. Data navigation and collection patterns
+5. Structural navigation and page semantics
+6. MVP-next extension components
+
+This order prioritizes reusable interaction primitives, keeps risk low for already-shipped widgets, and expands APG coverage to all listed patterns.