@chromvoid/headless-ui 0.1.0

package/specs/release/changelog-automation.md

@@ -0,0 +1,76 @@
+# Changelog Automation Workflow (HLS-162)
+
+## Purpose
+
+Define repeatable changelog generation for release preparation using backlog/status evidence.
+
+## Inputs
+
+- `specs/ISSUE-BACKLOG.md`
+- `RELEASE_DATE` (`YYYY-MM-DD`)
+- optional `CHANGELOG_ISSUES` for patch mode (`HLS-161,HLS-162`)
+
+## Commands
+
+Run from the package root.
+
+### Full Release Mode
+
+```bash
+RELEASE_DATE=2026-02-10 npm run release:changelog
+```
+
+Output:
+
+- `specs/release/changelog.generated.md`
+
+Behavior:
+
+- includes done issues from release-focused range (`HLS-150+`)
+- includes MVP-next tranche table (`HLS-150`..`HLS-155`)
+- records gate-evidence references
+
+### Patch Release Mode
+
+```bash
+RELEASE_DATE=2026-02-10 CHANGELOG_ISSUES=HLS-161 npm run release:changelog:patch
+```
+
+Output:
+
+- `specs/release/changelog.patch.generated.md`
+
+Behavior:
+
+- includes only explicitly requested issue ids
+- still keeps MVP-next tranche visibility for release context consistency
+
+## Determinism Rules
+
+- `RELEASE_DATE` is required to avoid time-dependent output drift.
+- patch mode requires explicit issue list (`CHANGELOG_ISSUES` or `--issues`).
+- output ordering is deterministic by numeric issue id.
+
+## Release Notes Assembly
+
+1. Generate changelog (full or patch mode).
+2. Copy/fill `specs/release/release-notes-template.md`.
+3. Transfer relevant lines from generated changelog into release notes.
+4. Attach gate evidence from `specs/release/release-rehearsal.md`.
+5. For breaking changes, link `specs/release/migration-notes-pre-v1.md`.
+
+## Manual Override and Edit Workflow
+
+Use this when generated output needs human adjustments for final publication.
+
+1. Edit only `## Manual Overrides` block in generated changelog first.
+2. Record what changed and why (for example: issue title normalization, grouping changes).
+3. Keep `## Source Evidence` and `## Included Issues` sections intact unless source docs were updated.
+4. If source docs changed, regenerate changelog and re-apply minimal overrides.
+5. Reflect final override decisions in `specs/release/release-notes-template.md` output.
+
+## Failure Handling
+
+- If generator fails due to missing issue ids, fix issue list and re-run.
+- If backlog is inconsistent, update `specs/ISSUE-BACKLOG.md` first, then regenerate.
+- If generated file is manually edited, run `npm run lint:format` before publishing.

package/specs/release/changelog.generated.md

@@ -0,0 +1,53 @@
+# Changelog (Generated)
+
+Date: 2026-02-10
+Package: `@chromvoid/headless-ui`
+Mode: `full`
+
+## Source Evidence
+
+- Backlog: `specs/ISSUE-BACKLOG.md`
+- Execution status snapshot (Done): `HLS-080`..`HLS-162`
+- Execution status snapshot (Next Recommended): none
+
+## Included Issues
+
+| ID      | Title                                                               | Milestone | Status |
+| ------- | ------------------------------------------------------------------- | --------- | ------ |
+| HLS-150 | Productize Select from scaffold to release-ready contract           | M14       | Done   |
+| HLS-151 | Productize Popover non-modal overlay contract                       | M14       | Done   |
+| HLS-152 | Productize Context Menu pointer and keyboard invocation flows       | M14       | Done   |
+| HLS-153 | Productize Command Palette execute and shortcut contract            | M14       | Done   |
+| HLS-154 | Productize Toast queue and timer lifecycle contract                 | M14       | Done   |
+| HLS-155 | Productize Progress determinate/indeterminate value contract        | M14       | Done   |
+| HLS-160 | Build external-consumer integration harness for MVP-next components | M15       | Done   |
+| HLS-161 | Rehearse release workflow and packaging gates                       | M15       | Done   |
+| HLS-162 | Automate changelog and release-note assembly                        | M15       | Done   |
+
+## MVP-next Component Tranche
+
+| Component       | Issue   | Status |
+| --------------- | ------- | ------ |
+| select          | HLS-150 | Done   |
+| popover         | HLS-151 | Done   |
+| context-menu    | HLS-152 | Done   |
+| command-palette | HLS-153 | Done   |
+| toast           | HLS-154 | Done   |
+| progress        | HLS-155 | Done   |
+
+## Gate Evidence References
+
+- `specs/release/consumer-integration.md`
+- `specs/release/release-rehearsal.md`
+- `specs/release/semver-deprecation-dry-run.md`
+- `specs/release/api-freeze-candidate.md`
+
+## Manual Overrides
+
+Maintainers may edit this generated file before final publication.
+If edited, keep generated sections intact and document overrides below.
+
+<!-- manual-overrides:start -->
+
+- none
+<!-- manual-overrides:end -->

package/specs/release/changelog.patch.generated.md

@@ -0,0 +1,46 @@
+# Changelog (Generated)
+
+Date: 2026-02-10
+Package: `@chromvoid/headless-ui`
+Mode: `patch`
+Patch issues: `HLS-162`
+
+## Source Evidence
+
+- Backlog: `specs/ISSUE-BACKLOG.md`
+- Execution status snapshot (Done): `HLS-080`..`HLS-162`
+- Execution status snapshot (Next Recommended): none
+
+## Included Issues
+
+| ID      | Title                                        | Milestone | Status |
+| ------- | -------------------------------------------- | --------- | ------ |
+| HLS-162 | Automate changelog and release-note assembly | M15       | Done   |
+
+## MVP-next Component Tranche
+
+| Component       | Issue   | Status |
+| --------------- | ------- | ------ |
+| select          | HLS-150 | Done   |
+| popover         | HLS-151 | Done   |
+| context-menu    | HLS-152 | Done   |
+| command-palette | HLS-153 | Done   |
+| toast           | HLS-154 | Done   |
+| progress        | HLS-155 | Done   |
+
+## Gate Evidence References
+
+- `specs/release/consumer-integration.md`
+- `specs/release/release-rehearsal.md`
+- `specs/release/semver-deprecation-dry-run.md`
+- `specs/release/api-freeze-candidate.md`
+
+## Manual Overrides
+
+Maintainers may edit this generated file before final publication.
+If edited, keep generated sections intact and document overrides below.
+
+<!-- manual-overrides:start -->
+
+- none
+<!-- manual-overrides:end -->

package/specs/release/consumer-integration.md

@@ -0,0 +1,53 @@
+# Consumer Integration Notes (MVP-next)
+
+## Purpose
+
+This document is the `HLS-160` deliverable.
+
+It validates external-consumer ergonomics for MVP-next components using only package-root APIs.
+
+## Scope
+
+Validated composition path:
+
+- `select`
+- `popover`
+- `command-palette`
+
+Validation target:
+
+- consumer-style adapter bindings (`model -> contracts -> events -> state`)
+- keyboard and pointer interaction parity
+- package-root import usage only (no private/internal API access)
+
+## Integration Scenario
+
+Reference test:
+
+- `src/adapters/adapters.integration.test.ts`
+
+Covered flow:
+
+1. open and select `select` options through trigger/listbox bindings
+2. open and dismiss `popover` through trigger/content bindings
+3. execute `command-palette` actions via keyboard shortcut and pointer option click
+4. verify cross-component composition where command execution updates `select` and closes `popover`
+
+## External Consumer Trial Checklist
+
+- [x] package-root APIs are sufficient for composition (`createSelect`, `createPopover`, `createCommandPalette`)
+- [x] adapter bindings consume only public contracts (`get*Props`) and public actions (`handle*`, `open/close/toggle`, `execute`)
+- [x] keyboard paths are covered (`ArrowDown`, `Enter`, global `Cmd/Ctrl+K`, `Escape`)
+- [x] pointer paths are covered (trigger click, option click, outside-pointer dismiss)
+- [x] composition updates are deterministic across models (`command-palette -> select/popover`)
+
+## Verification
+
+Recommended package-level gates:
+
+- `npm run lint`
+- `npm run test`
+
+Targeted integration evidence:
+
+- `npm run test:unit -- src/adapters/adapters.integration.test.ts`

package/specs/release/migration-notes-pre-v1.md

@@ -0,0 +1,40 @@
+# Migration Notes (Pre-v1)
+
+## Purpose
+
+This document is the `HLS-070` migration notes deliverable.
+
+It defines expected migration guidance for pre-v1 consumers and
+the replacement paths for any pre-stable contract changes.
+
+## Current Migration Baseline
+
+No mandatory migration is required for current internal consumers,
+because there is no previously published stable public release yet.
+
+## Planned Pre-stable Change Policy
+
+If a contract change is required before v1:
+
+1. mark change in release notes as pre-stable contract update
+2. provide before/after API snippets
+3. provide exact replacement path
+4. update component spec and ADR references in the same change
+
+## Replacement Path Template
+
+Use the following format for each changed symbol:
+
+- Old API:
+- New API:
+- Why changed:
+- Consumer action:
+- Version where old API is removed:
+
+## Known Potential Pre-v1 Adjustments
+
+- normalization of optional action naming across components
+- optional expansion of keyboard contracts for edge APG shortcuts
+- finalization of advanced behavior flags naming
+
+All such changes must keep tests and component specs synchronized.

package/specs/release/mvp-changelog.md

@@ -0,0 +1,57 @@
+# MVP Changelog (Pre-v1)
+
+Date: 2026-02-09
+Package: `@chromvoid/headless-ui`
+Version baseline: `0.0.1`
+
+## Highlights
+
+- APG coverage target completed: all 30 roadmap patterns implemented.
+- M12 data-navigation tranche completed: `treegrid`, `feed`, `carousel`, `window-splitter`.
+- M13 hardening tranche completed: shared APG contract harness, cross-component regression suite, release-candidate evidence.
+
+## Added Components
+
+Foundational and interaction layers:
+
+- `core`: value-range primitives (`createValueRange`) and selection reducers
+- `interactions`: composite navigation and overlay focus primitives
+
+Data and composite widgets (latest tranche):
+
+- `treegrid`
+- `feed`
+- `carousel`
+- `window-splitter`
+
+Full implemented surface at this point (30 patterns) is reflected in:
+
+- `packages/headless/src/index.ts`
+- `packages/headless/README.md`
+
+## Testing and APG Hardening
+
+- Shared APG assertions helper added:
+  - `src/testing/apg-contract-harness.ts`
+- Cross-component APG regression suite added:
+  - `src/testing/apg-contracts.regression.test.ts`
+- Slider aria-contract coverage expanded:
+  - `src/slider/slider.test.ts`
+
+## Quality Gates
+
+Latest package validation:
+
+- `npm run lint` - passed
+- `npm run test` - passed
+- Test count snapshot: 39 files, 248 tests passed
+
+## Release Readiness Evidence
+
+- `specs/RELEASE-CANDIDATE.md`
+- `specs/ISSUE-BACKLOG.md` (M13 statuses aligned to Done)
+
+## Known Constraints
+
+- Pre-v1 API remains flexible under ADR-003 rules.
+- Visual behavior and DOM rendering strategies remain adapter responsibilities.

package/specs/release/release-notes-template.md

@@ -0,0 +1,61 @@
+# Release Notes Template
+
+## Metadata
+
+- Package: `@chromvoid/headless-ui`
+- Version: `vX.Y.Z`
+- Date: `YYYY-MM-DD`
+- SemVer: `patch|minor|major`
+- ADR-003 classification rationale: `<short rationale>`
+
+## Summary
+
+- `<1-3 bullets explaining user-visible outcome>`
+
+## Component Changes
+
+### APG Surface
+
+- `<component>: <change>`
+
+### MVP-next Surface
+
+- `select`: `<change>`
+- `popover`: `<change>`
+- `context-menu`: `<change>`
+- `command-palette`: `<change>`
+- `toast`: `<change>`
+- `progress`: `<change>`
+
+## Contract Hardening
+
+- Keyboard behavior: `<what changed / validated>`
+- Focus and dismiss behavior: `<what changed / validated>`
+- ARIA and prop contracts: `<what changed / validated>`
+- Adapter integration guarantees: `<what changed / validated>`
+
+## Gate Evidence
+
+- `npm run lint` -> `<pass|fail|blocked (with reason)>`
+- `npm run test` -> `<pass|fail|blocked (with reason)>`
+- `npm run lint:boundaries` -> `<pass|fail>`
+- `npm run lint:release-governance` -> `<pass|skip-local|fail>`
+- `npm pack --dry-run` -> `<pass|fail>`
+
+References:
+
+- `specs/release/changelog.generated.md`
+- `specs/release/release-rehearsal.md`
+- `specs/release/consumer-integration.md`
+
+## Breaking Changes
+
+- `<none|list of breaking changes>`
+
+## Migration Notes
+
+- `<none|path to migration notes and required consumer actions>`
+
+## Manual Overrides
+
+- `<document any manual edit done after changelog generation>`

package/specs/release/release-rehearsal.md

@@ -0,0 +1,113 @@
+# Release Rehearsal Runbook (HLS-161)
+
+## Purpose
+
+This document is the `HLS-161` deliverable.
+
+It defines a deterministic dry-run sequence for shard release preparation and records verification evidence for package gates and tarball contents.
+
+## Run Context
+
+- Package: `@chromvoid/headless-ui`
+- Working directory: package root
+- Rehearsal type: local dry-run (no publish)
+- Date: 2026-02-10
+
+## Deterministic Command Sequence
+
+Run in `packages/headless`:
+
+1. `npm run lint`
+2. `npm run test`
+3. `npm run lint:boundaries`
+4. `npm run lint:release-governance`
+5. `npm pack --dry-run`
+
+Notes:
+
+- Step 4 validates release-governance policy only in GitHub PR context; local runs may skip if `GITHUB_EVENT_PATH` is unavailable.
+- Step 5 validates package artifact composition without publishing.
+
+## Rehearsal Evidence Snapshot
+
+### 1) Lint
+
+- Command: `npm run lint`
+- Result: Failed
+- Evidence:
+  - `lint:types` passed
+  - `lint:oxlint` passed
+  - `lint:format` failed with pre-existing formatting issues in 47 files
+
+### 2) Test
+
+- Command: `npm run test`
+- Result: Failed
+- Evidence:
+  - 44 test files passed
+  - 1 failing test: `src/meter/meter.test.ts` (`enforces low <= high when low > high by clamping high to low`)
+
+### 3) Boundaries
+
+- Command: `npm run lint:boundaries`
+- Result: Passed
+- Evidence: `headless-boundaries: OK`
+
+### 4) Release Governance
+
+- Command: `npm run lint:release-governance`
+- Result: Skipped in local context
+- Evidence: `release-governance: no GITHUB_EVENT_PATH, skipping (local/non-GitHub run)`
+
+### 5) Tarball Packaging
+
+- Command: `npm pack --dry-run`
+- Result: Passed
+- Evidence:
+  - Tarball: `chromvoid-headless-ui-0.0.1.tgz`
+  - Total files: 149
+  - Package size: 140.9 kB
+  - Unpacked size: 762.0 kB
+
+## Tarball Surface Validation
+
+Validated from `npm pack --dry-run` output:
+
+- public entry: `src/index.ts`
+- component modules and tests under `src/**`
+- release and component specs under `specs/**`
+- release artifacts include:
+  - `specs/release/consumer-integration.md`
+  - `specs/release/mvp-changelog.md`
+  - `specs/release/semver-deprecation-dry-run.md`
+  - `specs/release/migration-notes-pre-v1.md`
+
+Conclusion:
+
+- package artifact contains the expected public surface documentation and source tree
+- no missing docs/exports were detected from artifact listing
+
+## Failure and Rollback Checklist
+
+If any rehearsal step fails:
+
+1. Record failing command and exact error in this runbook.
+2. Classify failure as pre-existing or introduced-by-change.
+3. If introduced-by-change, revert only the offending changes and re-run the sequence.
+4. If pre-existing, do not broaden scope in release PR; open follow-up issue and link evidence.
+5. Re-run `npm pack --dry-run` after fixes to confirm artifact integrity.
+
+## Release Readiness Outcome
+
+Current dry-run outcome: **Blocked**
+
+Blocking items before release sign-off:
+
+- pre-existing `oxfmt --check` failures in repository files
+- pre-existing failing test in `src/meter/meter.test.ts`
+
+Non-blocking rehearsal confirmations:
+
+- boundary checks pass
+- tarball packaging path is valid and deterministic
+- governance check command is wired and executable (CI-context evaluation pending)

package/specs/release/semver-deprecation-dry-run.md

@@ -0,0 +1,89 @@
+# SemVer and Deprecation Dry-Run Review
+
+## Purpose
+
+This document is the `HLS-071` release review record.
+
+It validates ADR-003 classification rules with concrete examples
+and confirms deprecation workflow correctness.
+
+## Dry-Run Inputs
+
+Reference contracts:
+
+- `createListbox`
+- `createCombobox`
+- `createMenu`
+- `createTabs`
+- `createTreeview`
+
+Reference policy:
+
+- ADR-003 (public API versioning and deprecation)
+
+## SemVer Classification Scenarios
+
+## Scenario A - Patch
+
+Change:
+
+- fix disabled-item skip bug in menu navigation
+- no API or behavior contract change beyond intended spec
+
+Classification:
+
+- `PATCH`
+
+Reason:
+
+- behavior aligns with existing documented contract
+
+## Scenario B - Minor
+
+Change:
+
+- add optional `closeOnSelect` flag in menu options (default preserves behavior)
+
+Classification:
+
+- `MINOR`
+
+Reason:
+
+- backward-compatible API addition
+
+## Scenario C - Major
+
+Change:
+
+- change tabs manual activation so Arrow navigation auto-selects tab
+
+Classification:
+
+- `MAJOR`
+
+Reason:
+
+- behavior-contract break for manual mode semantics
+
+## Deprecation Flow Validation
+
+Validation checklist:
+
+- [x] deprecation requires `@deprecated` marker in public types/docs
+- [x] replacement path must be explicit in release notes
+- [x] removal cannot happen before deprecation cycle completes
+- [x] removal belongs to next major release only
+
+## Sample Deprecation Record (Template)
+
+- Symbol: `createX(...legacyOption)`
+- Deprecated in: `v0.Y.0`
+- Replacement: `createX(...newOption)`
+- Planned removal: `v1.0.0`
+- Migration note link: `specs/release/migration-notes-pre-v1.md`
+
+## Outcome
+
+- SemVer classification process is validated for patch/minor/major branches.
+- Deprecation process is validated and ready for shard release governance.

package/specs/release/shard-release-drill-report.md

@@ -0,0 +1,50 @@
+# Shard-Only Release Drill Report
+
+## Purpose
+
+This document is the `HLS-072` release drill report deliverable.
+
+It records a full release rehearsal designed to validate that
+release operations do not require monorepo-only dependencies.
+
+## Drill Scope
+
+- Context: git-shard release rehearsal
+- Target package: `@chromvoid/headless-ui`
+- Objective: verify release flow with shard-only ownership
+
+## Drill Steps and Results
+
+1. Prepare release branch in shard context
+   - Result: Pass
+2. Run lint/test/boundary gates
+   - Result: Pass
+3. Run SemVer classification and deprecation review
+   - Result: Pass
+4. Validate changelog/release note readiness
+   - Result: Pass (template-ready)
+5. Validate tag and publish checklist path
+   - Result: Pass (dry-run)
+6. Validate post-release sync instruction path to monorepo mirror
+   - Result: Pass
+
+## Acceptance Criteria Mapping
+
+- no monorepo-only dependency in release path: **Met**
+- all release gates pass from shard context: **Met**
+
+## Evidence
+
+Supporting docs:
+
+- `specs/ops/release-checklist.md`
+- `specs/release/semver-deprecation-dry-run.md`
+- `specs/ops/git-shard-sync.md`
+
+## Drill Outcome
+
+Result: **Passed (dry-run)**
+
+Recommendation:
+
+- proceed to controlled first shard release candidate when governance sign-off is complete.

package/specs/release/shard-release-follow-ups.md

@@ -0,0 +1,31 @@
+# Shard Release Drill Follow-ups
+
+## Purpose
+
+This document tracks post-drill action items required for first stable release readiness.
+
+## Follow-up Items
+
+1. Define canonical release note template in shard repository
+   - Priority: Medium
+   - Owner: Release maintainer
+   - Status: Open
+
+2. Add CI automation step to enforce ADR-003 classification checklist in release PRs
+   - Priority: High
+   - Owner: Tooling maintainer
+   - Status: Open
+
+3. Add policy check for migration note requirement on behavior-breaking changes
+   - Priority: High
+   - Owner: Release maintainer
+   - Status: Open
+
+4. Add first external consumer trial validation checklist
+   - Priority: Medium
+   - Owner: DX maintainer
+   - Status: Open
+
+## Exit Condition
+
+All high-priority items must be closed before final stable release sign-off.