@adia-ai/web-components 0.5.13 → 0.5.15

package/CHANGELOG.md

@@ -11,6 +11,247 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.15] - 2026-05-16
+
+> **Scope note:** §325 + §326 were originally planned as a separate v0.5.16 cycle (see retired `docs/plans/0.5.16-release-plan.md`); absorbed into v0.5.15 since both landed within the same release window (same-day commits prior to bump). The peer's v0.5.16 plan-doc explicitly anticipated this absorption option ("Hermes's call per `/lockstep-release`"). v0.5.16 plan-doc marked SHIPPED-IN-V0.5.15.
+
+### v0.5.15 §326 — `<swatch-ui>` `[slot="chrome"]` lost in template contexts (FB-37; P1)
+
+Closes FB-37. Pre-§326, `<swatch-ui>` consumed via any `html\`\`` template engine (or any engine that batches child appends separately from element creation) lost its `[slot="chrome"]` children entirely. Root cause: `#stamp()` is gated by a `#stamped` once-only guard + scans `this.children` for chrome slots at `connectedCallback` time. Template engines create the host via `createElement` + connect it FIRST (children empty), then batch-append children AFTER. `#stamp()`'s chrome scan returns `[]`; the `#stamped` guard prevents re-runs; chrome children landed at the END of host's children (after `data-copy`) instead of the canonical sibling-of-tile position. Blocked Tokens Studio's C1.3 dogfood migration (9 failing Playwright tests root-caused to this) — and >95% of AdiaUI consumers using `html\`\`` templates.
+
+#### Fixed — `components/swatch/class.js`
+
+- NEW `#absorbChromeSlot()` helper. Idempotent. Walks `this.children`; for any child with `slot="chrome"` that's not one of the internal stamped elements + not in the canonical position, calls `this.insertBefore(child, this.#badgeEl)` to move it to the slot between `#tileEl` + `#badgeEl`.
+- `#syncCore()` calls `#absorbChromeSlot()` at the top of every render pass. Late-arriving chrome children (template-render path) get picked up on the next reactive cycle; pre-positioned chrome children (static-HTML path) are no-op-moves.
+- `#stamp()`'s once-only eager scan stays intact for the static-HTML path; `#absorbChromeSlot()` is the safety net for late-append.
+
+#### Added — `components/swatch/swatch.test.js`
+
+- 2 NEW vitest cases under "FB-37 / §326":
+  - `absorbs chrome child appended AFTER connectedCallback (template-render path)` — mimics the bug's exact timing (create + connect with empty children → late append → property mutation triggers render → fix picks up the chrome child).
+  - `still handles chrome child appended BEFORE connect (static-HTML path)` — regression check that §314's original behavior still works.
+- Total suite: 6 cases (4 from §325 + 2 from §326).
+
+#### Migration
+
+Consumers using `<swatch-ui>` via `html\`\`` template engines (lit-html, AdiaUI's own `html\`\``, Preact, Vue, etc.) get the §314 chrome-slot feature working as documented in v0.5.13's `swatch.yaml slots:` block. No consumer-side changes required — the §326 fix is invisible to consumers writing canonical templates.
+
+### v0.5.15 §325 — `<swatch-ui>` default-slot wiped by label-attr (FB-36)
+
+Closes FB-36 + FB-36-followup. Pre-§325, `<swatch-ui label="500"><span>tip</span></swatch-ui>` written as indented multi-line HTML dropped the default-slot child entirely; only `label="500"` rendered. Root cause: `#stamp()`'s `Array.from(this.childNodes).filter(...)` captured pure-whitespace text nodes from the indentation; those landed in `#labelEl.firstChild`; `#syncCore()`'s "stale text-node" branch (designed for runtime `el.label = 'X'` mutations on attr-only swatches) then matched the whitespace + did `textContent = this.label`, wiping both the whitespace AND the consumer's `<span>`.
+
+Pre-§325 the yaml spec ("Use the default slot for richer content" — `swatch.yaml:40`) and the implementation contradicted each other; post-§325 they agree.
+
+#### Fixed — `components/swatch/class.js`
+
+- `#stamp()`'s `slotted` filter chain gains `&& !(n.nodeType === 3 && !n.textContent.trim())` — strips pure-whitespace text nodes from the capture. `#labelEl.firstChild` now becomes the consumer's element (or non-whitespace text), so `#syncCore`'s stale-text-node branch fires only for genuinely attr-driven cases.
+
+#### Added — `components/swatch/swatch.test.js`
+
+- NEW 4-case vitest suite covering FB-36's 3 input axes (default-slot present/absent × label-attr present/absent × runtime mutation). Locks the §325 fix structurally — future regressions of any of the 4 paths fail CI.
+
+#### Migration
+
+`<swatch-ui label="500"><span>tip</span></swatch-ui>` now behaves per yaml spec: default-slot wins, label-attr drops. Consumers using the workaround `.label=` property binding (per FB-36-followup) to bypass the bug can switch back to the canonical `[label]` attribute form post-upgrade.
+
+### v0.5.15 §324 — Yaml `enum_descriptions:` codegen extension (v0.6.0 FB-23 §3 retire carry-forward, PATCH-eligible)
+
+Closes the v0.6.0 carry-forward "Codegen yaml `enum:` per-member descriptions (FB-23 §3 retire)" from the RESPONSE-29 carry-forwards table. v0.5.15 ships the additive codegen surface on PATCH cadence; v0.6.0 no longer needs to carry this item.
+
+**The surface change:** `scripts/schemas/component.yaml.schema.json` `Prop` definition gains an optional `enum_descriptions:` object field — when present alongside `enum:`, dts-codegen emits an exported type alias (e.g. `UITextVariant`) above the class declaration with per-variant JSDoc carrying each description. IDE hover surfaces the disambiguation at authoring time without requiring hand-authored .d.ts.
+
+#### Added
+
+- `scripts/schemas/component.yaml.schema.json` — NEW optional `enum_descriptions: { type: object, additionalProperties: { type: string } }` field per prop. Backward-compatible: existing yamls without the field continue to emit inline enum unions.
+- `scripts/build/components.mjs` — forwards `enum_descriptions:` through `compileProp()` into the a2ui.json sidecar.
+- `scripts/build/dts-codegen.mjs` — `emitEnumTypeAlias()` helper detects props with both `enum:` and `enum_descriptions:`; emits a typed union alias `${className}${PascalCase(propName)}` with per-variant JSDoc; class property references the alias instead of inlining the union.
+
+#### Changed — `components/text/text.yaml`
+
+- `variant:` prop gains 12-entry `enum_descriptions:` block (one description per variant). Prop `description:` block also gains the FB-23 §2 ARIA-role disclaimer that previously lived in the hand-authored .d.ts.
+
+#### Changed — `scripts/build/dts-codegen.mjs` `HAND_AUTHORED_DTS`
+
+- `text` removed from skip-list. `text.d.ts` now codegen-driven; per-variant JSDoc surfaces via the new `enum_descriptions:` field. Net effect: 1 of 3 remaining `HAND_AUTHORED_DTS` entries closed (`toast` + `feed` remain — both carry runtime API the yaml shape can't express).
+
+#### Regenerated — `components/text/text.d.ts`
+
+- Replaces hand-authored .d.ts with codegen output. `UITextVariant` type alias preserved as exported type; per-variant JSDoc preserved verbatim. Net result: zero consumer-facing diff in the .d.ts surface; codegen takes over maintenance.
+
+### v0.5.15 §322 — NEW audit slot 32: `check-dead-constants.mjs`
+
+Graduates the FB-35 bug class (declared-but-unread module-level consts) to a CI gate. Walks every `.js` file under `packages/<pkg>/`; extracts SCREAMING_SNAKE_CASE / PascalCase `const NAME = ...;` declarations at module level; flags zero-reference cases. Skips `export const NAME` (consumed externally) + test/spec/examples/config files.
+
+First sweep surfaced + removed 2 real dead constants:
+- `packages/a2ui/validator/validator.js:38` — `WIRING_WEIGHTS` (vestigial from planned weighted-scoring system; safe deletion).
+- `packages/llm/adapters/openai.js:10` — `DEFAULT_MAX_TOKENS = 4096` (replaced by explicit `opts.max_tokens` plumbing).
+
+### v0.5.15 §323 — NEW audit slot 33: `check-hover-guard-discipline.mjs`
+
+Graduates the `analyze-css` bare-`:hover` discipline class to a CI gate. Detects `:hover` rules on host primitives + interactive slots/roles that lack a `:not([disabled])` guard AND set visual properties (background/color/border/box-shadow/etc.). Skips cursor-only / outline-style-only rule bodies.
+
+First sweep surfaced 19 findings across 11 components — all baselined in EXPECTED_DRIFT for cycle-by-cycle close:
+- **Real drift** (rely on `pointer-events: none` for click-suppression but hover styles still apply): action-list (4×), menu (1×), nav-item (2×), nav-group (1×).
+- **Slotted-trigger drift** (mitigated via parent guard rules; cosmetic-OK but worth tightening): select (5×), calendar-picker (1×), range (2×), tag (1×).
+- **Decorative-pop hover** (intentional): avatar (1×). Long-term whitelist candidate.
+- **@scope-Safari-17.x-workaround**: action-list (3 of 4) + nav-item (2) + rating (1) — guard can't live inside @scope; lift alongside the hover rule.
+
+#### Removed — dead module-level constants
+
+- `packages/a2ui/validator/validator.js` — `WIRING_WEIGHTS` constant (zero refs).
+- `packages/llm/adapters/openai.js` — `DEFAULT_MAX_TOKENS` constant (zero refs).
+
+### v0.5.15 §319 — NEW audit slot 29: `check-exports-map-resolves.mjs`
+
+Graduates the FB-32 bug class to a CI gate. Closes the recurring drift where a package.json `exports` map entry resolves (via wildcard expansion or static path) to a file that doesn't exist on disk — consumer TS imports fail with `TS2882` even though Vite/Node can fall through `node_modules/<pkg>/<path>` directly.
+
+#### Added — `scripts/release/check-exports-map-resolves.mjs`
+
+- ~270 LOC. Walks every `packages/<pkg>/package.json` `exports` map. For each STATIC entry, verifies the referenced file path exists. For each WILDCARD entry matching the FB-32 shape (`./X/*` key + `./X/*/*.<ext>` value), enumerates filesystem candidates that would match the wildcard + verifies each resolved path exists.
+- Skips wildcard expansions where an explicit non-wildcard entry overrides the resolution (Node exports-map resolution algorithm precedence).
+- Skips CSS-only / no-JS components (header / footer / section / aside / various web-modules shells) — these intentionally ship no `.js`.
+- Result: 9 packages / 52 static + 39 wildcard exports entries / 59 resolutions verified / 0 unresolved.
+
+### v0.5.15 §320 — NEW audit slot 30: `check-composes-passthrough.mjs`
+
+Graduates the FB-33 bug class to a CI gate. Closes the recurring drift where a form-bearing primitive that programmatically creates ANOTHER form-bearing primitive in its lifecycle (light-DOM composition) doesn't expose / forward the composed primitive's documented prop + event-detail surface.
+
+#### Added — `scripts/release/check-composes-passthrough.mjs`
+
+- ~270 LOC. Static `COMPOSITION_PAIRS` list declares the required pass-through surface per pair. For each pair: verifies composing primitive's yaml `composes:` block lists the composed primitive; verifies yaml `props:` block exposes every required prop; verifies yaml `events:` block declares each event with required detail keys.
+- Initial pair: `color-input → color-picker` (8 props + 12 event-detail keys across `change` + `input`).
+- Adding a new pair: any new primitive that programmatically wraps a form-bearing primitive declares its contract in `COMPOSITION_PAIRS`; the audit fires at PR time.
+- Companion to slot 23 (`check-form-bearing-dts.mjs`): that audit checks .d.ts type-coverage; this audit checks yaml-declared shape.
+
+### v0.5.15 §321 — NEW audit slot 31: `check-token-name-canonical-shape.mjs`
+
+Graduates the stepper / list state-first naming drift class to a CI gate. Closes the recurring drift where a component-local CSS token uses state-first (`--stepper-active-bg`) or color-infix-state (`--link-color-hover`) naming instead of the canonical property-first state-suffix shape (`--<comp>(-<sub>)*-<prop>(-<state>)?`).
+
+#### Added — `scripts/release/check-token-name-canonical-shape.mjs`
+
+- ~210 LOC. Extracts `--<comp>-*` declarations from each component CSS file. Classifies each by segment shape: canonical-prop / canonical-prop-state / canonical-leaf / canonical-domain / drift-state-first / drift-infix-color-state.
+- Vocabularies (PROP_TOKENS + STATE_TOKENS) capture the catalog's recognized property + state terms (bg/fg/border/ring/shadow/color/outline/size + hover/active/selected/disabled/focus/checked/done/...).
+- Result: 92 components / 1809 component-local tokens audited / 0 drift findings.
+- `link.css` `--link-color-hover` not flagged at v0.5.15 ship: `color` is a recognized PROP_TOKEN + `hover` is a recognized STATE_TOKEN — the shape matches canonical. A future, stricter audit (alternative-property-naming) could flag the `color` vs `fg` divergence; deferred to v0.6.0 BREAKING window since link.css's `--link-color-*` are documented public API.
+
+### v0.5.15 §316 — Naming-convention drift fix (stepper + list state-first → property-first)
+
+`<stepper-ui>` and `<list-ui>` declared internal tokens with state-first naming (`--stepper-active-bg`, `--list-selected-fg`, etc.) — the catalog convention is property-first (`--<comp>-{prop}-{state}`). 18 token names renamed; usage sites updated in-place. `<link-ui>` skipped — its `--link-color-*` tokens are documented public API per `link.yaml tokens:` block; renaming is BREAKING and defers to v0.6.0.
+
+#### Changed — `components/stepper/`, `components/list/`
+
+- `stepper.css` — 12 tokens renamed: `--stepper-{active,done}-{bg,border,fg}` + `--stepper-item-{active,done}-{bg,border,fg}` → `--stepper-{bg,border,fg}-{active,done}` + `--stepper-item-{bg,border,fg}-{active,done}`.
+- `list.css` — 3 tokens renamed: `--list-selected-{bg,fg,border}` → `--list-{bg,fg,border}-selected`.
+
+### v0.5.15 §316 — Hand-rolled transition-duration literals → token references (swatch + heatmap + page)
+
+Three components hand-rolled `100ms ease-out` / `120ms ease-out` / `0.1s ease-out` / `150ms ease` instead of routing through the canonical `var(--a-duration-fast)` + `var(--a-easing*)` token chain. Theme designers couldn't swap transition cadence centrally.
+
+#### Changed — `components/swatch/`, `components/heatmap/`, `components/page/`
+
+- `swatch.css:294,311` — `100ms ease-out` + `120ms ease-out` → `var(--a-duration-fast) var(--a-easing-out)`.
+- `heatmap.css:80` — `0.1s ease-out` → `var(--a-duration-fast) var(--a-easing-out)`.
+- `page.css:61` — `150ms ease` → `var(--a-duration-fast) var(--a-easing)`.
+
+### v0.5.15 §317 — NEW audit slot 27: `check-raw-fg-in-component-css.mjs`
+
+Graduates the §313/§315/§316 bug class to a CI gate. Closes the recurring drift class where component CSS rules bypass their own `--<comp>-<family>-<state>` semantic-layer token and reference the raw global `--a-<family>-<state>` token directly. The audit slot found 5 additional bypass instances across the codebase (nav-group + select + toolbar) — all routed through the component-local semantic layer in this commit.
+
+#### Added — `scripts/release/check-raw-fg-in-component-css.mjs`
+
+- ~190 LOC audit script. Parses each `<comp>.css` for the `:where(:scope) { ... }` declaration block + the set of `--<comp>-*` tokens defined therein. Scans the remainder for `<standard-css-property>: var(--a-<family>-<state>?)` usage where the parallel `--<comp>-<family>-<state>?` is defined — emits a finding per bypass.
+- Whitelisted CSS properties: `color`, `background`, `background-color`, `border` (+ all sub-axis variants), `outline`, `fill`, `stroke`, `caret-color`, `accent-color`, `text-decoration-color`, `column-rule-color`.
+- Distinguishes declaration sites (`--<comp>-X: var(--a-X)`) from usage sites mechanically — declaration sites are NOT flagged (those are correct semantic-layer aliasing).
+- Companion to slot 25 (`check-component-css-vs-styles-tokens.mjs`): that audit catches orphan references (`var(--a-X)` where `--a-X` doesn't exist); this audit catches the inverse (`var(--a-X)` where it exists but `--<comp>-X` should be preferred).
+- EXPECTED_FINDINGS baseline: 0 entries at v0.5.15 ship (sweep landed every concrete bypass).
+
+#### Fixed — 5 component CSS bypass sites
+
+- `nav-group.css:243,252` — `background: var(--a-bg-hover)` → `var(--nav-group-bg-hover)`.
+- `select.css:199` — listbox container `color: var(--a-fg)` → `var(--select-fg)`.
+- `select.css:319` — hint slot fallback `var(--a-fg-muted)` → `var(--select-fg-muted)`.
+- `toolbar.css:107` — overflow popover `color: var(--a-fg)` → `var(--toolbar-fg)`.
+
+### v0.5.15 §317 — NEW audit slot 28: `check-form-bearing-events-symmetric.mjs`
+
+Graduates the FB-31/§315 bug class to a CI gate. Closes the recurring drift class where UIFormElement-extending primitives emit only `input` (or only `complete`/`search`/`pick`) without the canonical `change` event with `detail.value`. The audit confirms all 17 form-bearing primitives are now symmetric post-v0.5.14 §315.
+
+#### Added — `scripts/release/check-form-bearing-events-symmetric.mjs`
+
+- ~145 LOC audit script. Walks every `class.js` for classes that `extends UIFormElement`. For each, verifies a `dispatchEvent(new CustomEvent('change', { detail: { value: ... } }))` occurs (statically or via dynamic-name dispatch + nearby `'change'` string literal + `detail = { value: ... }` construction).
+- Heuristic limitations documented: false negatives possible if event name is computed via complex variable assignment; manual review at addition time required.
+- ALLOW_LIST mechanism for primitives where the commit model legitimately omits `change` (none at v0.5.15 ship).
+- Companion to slot 23 (`check-form-bearing-dts.mjs`): that audit verifies typed `<Comp>ChangeEvent` exists in `.d.ts`; this audit verifies the runtime dispatch.
+
+### v0.5.15 §318 — ADR-0028: L3 state-matrix orphan retirement (78 unused tokens deleted)
+
+ADR-0028 ratifies the deletion of 78 orphaned L3 state-matrix tokens from `semantics.css`. The `maintain-tokens` skill audit during v0.5.14 §315 surfaced that 73 of ~80 L3 `--a-{family}-{prop}-{state}` tokens have zero consumers across the entire codebase. The per-primitive `--<comp>-*` token pattern (validated across v0.5.13/14/15 sweeps) is the actual consumer-facing API.
+
+#### Removed — `styles/colors/semantics.css`
+
+- 78 `--a-{accent,primary,brand,info,success,warning,danger,fg,border}-{fg,bg,border}-{active,selected,disabled,invalid}` declarations deleted. ~80 LOC reduction.
+- Token count dropped 1301 → 1217 (-6.5%).
+- Kept (have consumers): `--a-bg-{active,selected,disabled,invalid}`, `--a-fg-{selected,disabled}`, `--a-accent-bg-active`, `--a-primary-bg-active` (transitive via accent-bg-active).
+- Kept (consumer-facing hover state): all `--a-*-hover` variants — hover is the only state where the generic-L3 layer is load-bearing.
+
+#### Added — `.brain/adrs/0028-l3-state-matrix-orphan-retirement.md`
+
+- ADR documents the audit-driven discovery, the retention rationale for the 7 used tokens, the deletion rationale for the 78 orphans, alternatives considered (keep all / delete only family-specific / add audit), and the per-primitive convention as the canonical consumer-facing override surface.
+
+## [0.5.14] - 2026-05-15
+
+### v0.5.14 — Form-control hover-fg token unification (precursor to §315; commit `178418525`)
+
+Form-control primitives diverged on hover-text token routing. `button-ui` correctly used `--a-ui-text-hover` (resolves to `--a-fg-strong` — canonical hover-lift for form-control text); every other form-control primitive used the generic `--a-fg` (no actual lift from default `--a-canvas-text`) — so "hover" had zero text-color effect on `input`/`textarea`/`segment`, and `select-ui`'s listbox/caret hover paths bypassed the `--select-*` token layer entirely with raw `--a-fg-*` references.
+
+#### Fixed — `components/{input,textarea,segment,select}/`
+
+- `input-ui`: `--input-fg-hover: var(--a-fg)` → `var(--a-ui-text-hover)`; `--input-affix-fg-hover: var(--a-fg-subtle)` → `var(--a-ui-text-subtle)`.
+- `textarea-ui`: matching routing on hover/affix-hover.
+- `segment-ui`: same routing change.
+- `select-ui`: listbox + caret + option-hover tokens previously raw `--a-fg-*` references now route through their `--select-*` semantic layer (which itself anchors at `--a-ui-text-*` family).
+
+Net effect: hover-text colors now consistent across all form-control primitives + theme designers can swap them all by changing one semantic token (`--a-ui-text-hover`) at the `--a-ui-*` family root in `semantics.css`.
+
+### v0.5.14 §315 — Drift-class sweep follow-up (`ui-audit-coherence` + `maintain-tokens` + `analyze-css` triple-pass)
+
+Three parallel skill-driven audits surfaced 7 mechanical drift-classes; landed as a single sweep in one commit (`025a981db`). Follow-up to the form-control hover-fg unification at `178418525` — same bug shape (component CSS bypassing its own semantic-layer routing through raw global tokens), broader scope.
+
+#### Fixed — `components/select/`, `components/nav-group/`, `components/chat-thread/chat-input.css`
+
+- `select.css:254,286,293,300` — 4 raw `var(--a-fg-*)` callsites routed through `--select-fg-{muted,fg,muted,muted}` (semantic layer already existed but was bypassed).
+- `nav-group.css:225,234,244,253,286,298` — 6 raw `var(--a-fg-{muted,subtle,strong})` callsites routed through `--nav-group-fg-{muted,muted,hover,selected,muted,muted}`.
+- `chat-input.css:40,50,58` — placeholder/hover/disabled tokens routed through the canonical `--a-ui-text-{placeholder,hover,disabled}` field-family chain instead of the generic `--a-fg-*` family. Continues the v0.5.13 hover-fg unification arc.
+
+#### Fixed — `components/{check,radio,switch,tabs,action-list,calendar-picker,menu}/`
+
+- 6 form-adjacent primitives' `--{comp}-fg-disabled` token routed through canonical `--a-ui-text-disabled` instead of `--a-fg-muted` (the disabled-text version of the v0.5.13 hover-fg drift class).
+- `menu.css:96,99` also fixed `--menu-item-fg-disabled` + `--menu-item-icon-disabled` (the third variant `--a-fg-disabled` shape; same canonical target).
+
+#### Added — `components/otp-input/`, `components/search/`
+
+- `<otp-input-ui>` + `<search-ui>` now dispatch `change` alongside `input` on every value-altering event. Both primitives previously emitted only `input` (the sole exceptions across all UIFormElement-bearing primitives). Closes consumer event-binding gap — `@change=${handler}` now works against every form-bearing tag uniformly.
+- `.d.ts` files gain `OtpInputChangeEvent` + `SearchChangeEvent` type exports (reuse existing detail interfaces; matches v0.5.10 `check-form-bearing-dts` audit convention).
+- yaml `events:` blocks declare the new `change` event with `detail.value`.
+
+#### Fixed — `styles/typography.css`
+
+- `:where(mark)` background reference fixed: `var(--a-highlight-default)` → `var(--a-highlight)` (`--a-highlight-default` token does not exist; pre-fix `<mark>` silently fell back to UA-default highlight). Single-line typo discovered via `maintain-tokens` skill sweep.
+
+#### Fixed — `components/{textarea,upload,option-card,pagination}/` transition consistency
+
+- `textarea.css:76` transition list expanded from `border-color` only → `background + border-color + color + box-shadow` (matches `input-ui`'s 4-property parity; pre-fix hover/focus slammed in instead of easing).
+- `upload.css:64-67` + `option-card.css:102-104` + `pagination.css:71-73` each gain `box-shadow` (and `border-color` for pagination) so focus-ring eases in alongside the other state changes. Cross-primitive hover/focus polish parity restored.
+
+#### Fixed — `components/input/`, `components/select/` `-active` token routing
+
+- `--input-fg-focus: var(--a-fg-strong)` → `var(--a-ui-text-active)` (closes orphan: `--a-ui-text-active` semantic-layer alias existed at `semantics.css:552` with zero consumers).
+- `--select-option-fg-active: var(--a-fg)` → `var(--a-ui-text-active)` (same routing; cross-primitive form-control consistency).
+
+#### Fixed — `components/heatmap/`
+
+- `class.js:disconnected()` now cancels `#raf` via `cancelAnimationFrame()`. Pre-fix the `requestAnimationFrame` handle was stored but never cleaned up on detach — minor memory leak in scroll-heavy demos. ~3 LOC.
+
 ## [0.5.13] - 2026-05-15
 
 ### v0.5.13 §310 — `apcaContrast` soft-clamp constant fix (FEEDBACK-35; P2 correctness)

package/components/action-list/action-list.css

@@ -39,7 +39,7 @@ action-item-ui:hover [slot="icon"] {
     --action-item-fg:              var(--a-fg-subtle);
     --action-item-fg-hover:        var(--a-fg-strong);
     --action-item-bg-hover:        var(--a-bg-muted);
-    --action-item-fg-disabled:     var(--a-fg-muted);
+    --action-item-fg-disabled:     var(--a-ui-text-disabled);
     --action-item-icon-fg:         var(--a-fg-muted);
     --action-item-icon-fg-hover:   var(--a-fg);
     --action-item-danger-fg:       var(--a-danger-bg);

package/components/calendar-picker/calendar-picker.css

@@ -68,7 +68,7 @@
     --calendar-picker-day-bg-selected:        var(--a-accent);
     --calendar-picker-day-fg-selected:        var(--a-accent-fg);
     --calendar-picker-day-fg-outside:         var(--a-fg-muted);
-    --calendar-picker-day-fg-disabled:        var(--a-fg-muted);
+    --calendar-picker-day-fg-disabled:        var(--a-ui-text-disabled);
     --calendar-picker-day-today-border:       var(--a-accent);
     --calendar-picker-day-today-dot-size:     var(--a-space-0-5);
     --calendar-picker-day-today-dot-offset:   var(--a-space-1);

package/components/chat-thread/chat-input.css

@@ -37,7 +37,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
     --chat-input-fg:              var(--a-fg);
     --chat-input-border:          var(--a-border-subtle);
     --chat-input-caret-color:     var(--a-fg-subtle);
-    --chat-input-placeholder-fg:  var(--a-fg-muted);
+    --chat-input-placeholder-fg:  var(--a-ui-text-placeholder);
 
     /* Hover — matches input-ui's affordance (subtle alpha lift on the
        canvas surface + slightly stronger border + brightened fg). The
@@ -47,7 +47,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
        doesn't compound. */
     --chat-input-bg-hover:        var(--a-ui-bg-hover);
     --chat-input-border-hover:    var(--a-ui-border-hover);
-    --chat-input-fg-hover:        var(--a-fg);
+    --chat-input-fg-hover:        var(--a-ui-text-hover);
 
     /* Disabled — host-level chrome (background, border, pointer-events)
        lives on `:scope[disabled]` below. Inner-text disabled color is
@@ -55,7 +55,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
        leak through. */
     --chat-input-bg-disabled:     transparent;
     --chat-input-border-disabled: var(--a-border-subtle);
-    --chat-input-fg-disabled:     var(--a-fg-disabled);
+    --chat-input-fg-disabled:     var(--a-ui-text-disabled);
 
     /* Canonical focus ring — chat-input is a *nested-control host*.
        See semantics.css FOCUS block + the nested-control pattern

package/components/check/check.css

@@ -60,7 +60,7 @@ check-ui[indeterminate] {
     --check-bg-checked-hover: var(--a-primary-hover);
 
     /* ── State: disabled ── */
-    --check-fg-disabled:      var(--a-fg-muted);
+    --check-fg-disabled:      var(--a-ui-text-disabled);
 
     /* ── Check icon (CSS border trick, no SVG) ── */
     --_icon-w:    0;

package/components/heatmap/class.js

@@ -86,6 +86,10 @@ export class UIHeatmap extends UIElement {
     this.removeEventListener('pointerleave', this.#onLeave);
     this.removeEventListener('click', this.#onClick);
     this.#bound = false;
+    if (this.#raf != null) {
+      cancelAnimationFrame(this.#raf);
+      this.#raf = null;
+    }
   }
 
   #raf = null;

package/components/heatmap/heatmap.css

@@ -77,7 +77,7 @@
     min-height: var(--heatmap-cell-min-size);
     aspect-ratio: 1 / 1;
     cursor: default;
-    transition: transform 0.1s ease-out;
+    transition: transform var(--a-duration-fast) var(--a-easing-out);
   }
 
   :scope [data-cell][data-v] {

package/components/input/input.css

@@ -37,9 +37,9 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
 
     /* ── State: hover/focus ── */
     --input-bg-hover:        var(--a-ui-bg-hover);
-    --input-fg-hover:        var(--a-fg);
-    --input-affix-fg-hover:  var(--a-fg-subtle);
-    --input-fg-focus:        var(--a-fg-strong);
+    --input-fg-hover:        var(--a-ui-text-hover);
+    --input-affix-fg-hover:  var(--a-ui-text-subtle);
+    --input-fg-focus:        var(--a-ui-text-active);
 
     /* ── State: disabled ── */
     --input-bg-disabled:     var(--a-ui-bg-disabled);

package/components/list/list.css

@@ -2,9 +2,9 @@
   :where(:scope) {
     /* ── Colors ── */
     --list-divider-color: var(--a-border-subtle);
-    --list-selected-bg:   var(--a-accent-muted);
-    --list-selected-fg:   var(--a-accent-strong);
-    --list-selected-border: var(--a-accent-strong);
+    --list-bg-selected:   var(--a-accent-muted);
+    --list-fg-selected:   var(--a-accent-strong);
+    --list-border-selected: var(--a-accent-strong);
   }
 
   :scope {
@@ -68,9 +68,9 @@
   }
 
   :scope[selectable] > [role="listitem"][aria-selected="true"] {
-    background: var(--list-selected-bg);
-    color: var(--list-selected-fg);
-    border-inline-start-color: var(--list-selected-border);
+    background: var(--list-bg-selected);
+    color: var(--list-fg-selected);
+    border-inline-start-color: var(--list-border-selected);
   }
 
   :scope[selectable] > [role="listitem"]:focus-visible {

package/components/menu/menu.css

@@ -93,10 +93,10 @@ menu-item-ui[variant="danger"]:hover [slot="icon"] {
     --menu-item-fg:             var(--a-fg-subtle);
     --menu-item-fg-hover:       var(--a-fg);
     --menu-item-bg-hover:       var(--a-bg-muted);
-    --menu-item-fg-disabled:    var(--a-fg-disabled);
+    --menu-item-fg-disabled:    var(--a-ui-text-disabled);
     --menu-item-icon-fg:        var(--a-fg-muted);
     --menu-item-icon-fg-hover:  var(--a-fg);
-    --menu-item-icon-disabled:  var(--a-fg-disabled);
+    --menu-item-icon-disabled:  var(--a-ui-text-disabled);
     --menu-item-danger-fg:      var(--a-danger-bg);
     --menu-item-danger-bg:      var(--a-danger-muted);
 

package/components/nav-group/nav-group.css

@@ -222,7 +222,7 @@ nav-group-ui [slot="popover"] {
 nav-group-ui [slot="popover-label"] {
   padding: var(--a-space-1) var(--a-space-2);
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
   font-size: var(--a-ui-tiny);
   text-transform: uppercase;
   letter-spacing: 0.06em;
@@ -231,7 +231,7 @@ nav-group-ui [slot="popover-label"] {
 nav-group-ui [slot="popover"] [role="option"] {
   padding: var(--a-space-1) var(--a-space-2);
   border-radius: var(--a-radius);
-  color: var(--a-fg-subtle);
+  color: var(--nav-group-fg-muted);
   cursor: pointer;
   white-space: nowrap;
   transition:
@@ -240,8 +240,8 @@ nav-group-ui [slot="popover"] [role="option"] {
 }
 
 nav-group-ui [slot="popover"] [role="option"]:hover {
-  background: var(--a-bg-hover);
-  color: var(--a-fg-strong);
+  background: var(--nav-group-bg-hover);
+  color: var(--nav-group-fg-hover);
 }
 
 /* Selected / current option — mirrors the main rail's nav-item selection:
@@ -249,8 +249,8 @@ nav-group-ui [slot="popover"] [role="option"]:hover {
 nav-group-ui [slot="popover"] [role="option"][aria-current="page"],
 nav-group-ui [slot="popover"] [role="option"][aria-selected="true"] {
   position: relative;
-  background: var(--a-bg-hover);
-  color: var(--a-fg-strong);
+  background: var(--nav-group-bg-hover);
+  color: var(--nav-group-fg-selected);
   font-weight: var(--a-weight-medium);
 }
 
@@ -283,7 +283,7 @@ nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] {
   padding: var(--a-space-3) var(--a-space-2) var(--a-space-1);
   font-size: var(--a-kicker-sm, var(--a-ui-tiny));
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
   text-transform: uppercase;
   letter-spacing: 0.06em;
   cursor: default;
@@ -295,7 +295,7 @@ nav-group-ui[variant="section"] > [slot="header"]:focus-visible,
 nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:hover,
 nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:focus-visible {
   background: transparent;
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
 }
 
 nav-group-ui[variant="section"] > [slot="header"] [slot="caret"],

package/components/option-card/option-card.css

@@ -101,7 +101,8 @@ option-card-ui[checked] > [slot="icon"] {
     outline: none;
     transition:
       background var(--option-card-duration) var(--option-card-easing),
-      border-color var(--option-card-duration) var(--option-card-easing);
+      border-color var(--option-card-duration) var(--option-card-easing),
+      box-shadow var(--option-card-duration) var(--option-card-easing);
   }
 
   /* When an icon slot is present, insert a third column for it

package/components/otp-input/class.js

@@ -18,7 +18,7 @@
  * Each digit gets its own input — auto-advances on entry,
  * backs up on delete, distributes pasted values.
  *
- * Events: 'complete' (detail: {value}), 'input'
+ * Events: 'complete' (detail: {value}), 'input' (detail: {value}), 'change' (detail: {value})
  */
 
 import { UIFormElement } from '../../core/form.js';
@@ -107,6 +107,7 @@ export class UIOtpInput extends UIFormElement {
 
     this.#syncCombined();
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     if (input.value && index < this.#inputs.length - 1) {
       this.#inputs[index + 1].focus();
@@ -121,6 +122,7 @@ export class UIOtpInput extends UIFormElement {
       this.#inputs[index - 1].value = '';
       this.#syncCombined();
       this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
     }
   }
 
@@ -132,6 +134,7 @@ export class UIOtpInput extends UIFormElement {
     }
     this.#syncCombined();
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     // Focus last filled or first empty
     const firstEmpty = this.#inputs.findIndex(inp => !inp.value);

package/components/otp-input/otp-input.a2ui.json

@@ -46,6 +46,15 @@
     "category": "input",
     "composes": [],
     "events": {
+      "change": {
+        "description": "Fired alongside `input` on every digit change. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).",
+        "detail": {
+          "value": {
+            "description": "Combined digits at the moment of the change.",
+            "type": "string"
+          }
+        }
+      },
       "complete": {
         "description": "Fired exactly once when the user fills the last digit slot. detail.value is the combined string.",
         "detail": {

package/components/otp-input/otp-input.d.ts

@@ -11,6 +11,8 @@ export interface OtpInputEventDetail {
   value: string;
 }
 export type OtpInputEvent = CustomEvent<OtpInputEventDetail>;
+export type OtpInputInputEvent = CustomEvent<OtpInputEventDetail>;
+export type OtpInputChangeEvent = CustomEvent<OtpInputEventDetail>;
 
 /**
  * Detail payload for the `complete` event — fired exactly once when the
@@ -32,5 +34,6 @@ export class UIOtpInput extends UIFormElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'input', listener: (ev: OtpInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: OtpInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'complete', listener: (ev: OtpInputCompleteEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/otp-input/otp-input.yaml

@@ -36,6 +36,12 @@ events:
       value:
         type: string
         description: Combined digits at the moment of the change.
+  change:
+    description: Fired alongside `input` on every digit change. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).
+    detail:
+      value:
+        type: string
+        description: Combined digits at the moment of the change.
 slots:
   field:
     description: Container for the digit input boxes and optional separator

package/components/page/page.css

@@ -58,7 +58,7 @@
     top: 0;
     z-index: 1;
     background: var(--page-sticky-bg);
-    transition: border-color 150ms ease, box-shadow 150ms ease;
+    transition: border-color var(--a-duration-fast) var(--a-easing), box-shadow var(--a-duration-fast) var(--a-easing);
   }
 
   :scope[data-header-stuck] > :where(header, header-ui) {

package/components/pagination/pagination.css

@@ -70,7 +70,9 @@
     line-height: 1;
     transition:
       background var(--pagination-duration) var(--pagination-easing),
-      color var(--pagination-duration) var(--pagination-easing);
+      border-color var(--pagination-duration) var(--pagination-easing),
+      color var(--pagination-duration) var(--pagination-easing),
+      box-shadow var(--pagination-duration) var(--pagination-easing);
   }
 
   [slot="nav"] button:not([disabled]):hover {

package/components/radio/radio.css

@@ -39,7 +39,7 @@ radio-ui[checked] [slot="dot"]::after {
     --radio-bg-checked-hover: var(--a-primary-hover);
 
     /* ── State: disabled ── */
-    --radio-fg-disabled:      var(--a-fg-muted);
+    --radio-fg-disabled:      var(--a-ui-text-disabled);
 
     /* ── State: focus ── */
     --radio-focus-ring:       var(--a-focus-ring);

package/components/search/class.js

@@ -76,6 +76,7 @@ export class UISearch extends UIFormElement {
     this.value = this.#inputEl.value;
     this.syncValue(this.value);
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     clearTimeout(this.#timer);
     this.#timer = setTimeout(() => {
@@ -106,6 +107,7 @@ export class UISearch extends UIFormElement {
     this.syncValue('');
     this.setAttribute('value', '');
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
     this.dispatchEvent(new CustomEvent('search', {
       bubbles: true,
       detail: { value: '' },

package/components/search/search.a2ui.json

@@ -56,6 +56,15 @@
     "category": "input",
     "composes": [],
     "events": {
+      "change": {
+        "description": "Fired alongside `input` on every keystroke + on clear. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).",
+        "detail": {
+          "value": {
+            "description": "Current search-input value.",
+            "type": "string"
+          }
+        }
+      },
       "clear": {
         "description": "Fired when the clear button is clicked"
       },

package/components/search/search.d.ts

@@ -10,6 +10,7 @@ export interface SearchInputEventDetail {
   value: string;
 }
 export type SearchInputEvent = CustomEvent<SearchInputEventDetail>;
+export type SearchChangeEvent = CustomEvent<SearchInputEventDetail>;
 
 export interface SearchEventDetail {
   value: string;
@@ -31,5 +32,6 @@ export class UISearch extends UIFormElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'input', listener: (ev: SearchInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: SearchInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'search', listener: (ev: SearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }