@takazudo/zdtp 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -4,10 +4,40 @@ All notable changes to `@takazudo/zdtp` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [0.5.2] - 2026-09-08
+
+### Features
+
+- Header actions now carry a stable `data-zdtp-action` attribute on both affordances — the inline header link and the compact kebab popover — with the ids `export`, `import`, `apply`, and `reset`. The ids are stable across releases; the display labels are not. This gives consumer tests a selector that survives a label change, which is what broke in [#831](https://github.com/Takazudo/zudo-design-token-panel/issues/831). The hook removes the dependence on the label; it does **not** remove the responsive collapse, so a locator still needs to be visibility-qualified and panel-scoped — see the recipe [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/) and `PORTABLE-CONTRACT.md` §7.6. (91916b4, [#840](https://github.com/Takazudo/zudo-design-token-panel/issues/840))
+
+### Fixed
+
+- The popover action items and the header region items are now keyed by their stable action id rather than by their display label. Two actions sharing a label previously produced duplicate keys, so reconciliation could reuse the wrong node and leave an item with a stale handler or `aria-disabled` state. (c3384ae)
+- The 0.5.1 changelog said the old header-action selector "worked through 0.4.14". It worked through **0.5.0** — `v0.4.15` and `v0.5.0` both shipped before the collapse landed. (c3384ae)
+
+### Other Changes
+
+- The documentation site moved to `https://zdtp.zudolab.dev/`, and the playground and minimal example to `https://zdtp-playground.zudolab.dev/` and `https://zdtp-minimal.zudolab.dev/`. The package `homepage` field follows. (0b9e596, ef41bf2, [#835](https://github.com/Takazudo/zudo-design-token-panel/issues/835))
+- The 0.5.1 release notes now flag the header-action collapse as consumer-affecting, with the exact `1135px` container-query threshold and the fact that it measures the shell's content-box inline size rather than the viewport. (6215888, [#841](https://github.com/Takazudo/zudo-design-token-panel/issues/841))
+- New bilingual recipe, [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/), covering both a label-based pattern for existing releases and the id-based pattern from this one. (c701369, [#842](https://github.com/Takazudo/zudo-design-token-panel/issues/842))
+- Twenty dead `*.pages.dev` example-demo links on the Examples page were repointed to their live `zudolab.dev` hosts. (c83ffa3, [#836](https://github.com/Takazudo/zudo-design-token-panel/issues/836))
+
 ## [0.5.1] - 2026-09-06
 
 The panel now fits its token grids, card controls, and header controls at the minimum panel width instead of overflowing. Multiple panels keep stable spawn positions: spawn ordinals are persisted and survive Astro client-side navigation. Eager loading is bounded to state keys the panel can actually read, and the specimen stylesheet gained the boundaries the docs-adoption check required.
 
+### Breaking Changes
+
+- **Narrowed the accepted-key set of `EAGER_LOAD_GATE_STATE_FAMILY.matchesKey`, a public exported API.** 0.5.0 accepted `${storagePrefix}-state` optionally followed by `-v` and one or more digits. 0.5.1 accepts only exact matches against the new `READABLE_STATE_KEY_SUFFIXES` registry — `-state`, `-state-v2`, `-state-v3`, `-state-v4`. So `${storagePrefix}-state` and `${storagePrefix}-state-v2` still match, while `${storagePrefix}-state-v1`, `${storagePrefix}-state-v0`, `${storagePrefix}-state-v01`, and `${storagePrefix}-state-v123` matched in 0.5.0 and do not in 0.5.1. The narrowing is deliberate — the synchronous eager gate must probe only the key versions the loader can actually read — but it is consumer-observable, the TypeScript signature is unchanged so a type check will not surface it, and it should have ridden a minor release rather than this patch. **Migration**: hosts asserting on `-state-vN` keys should derive them from the new `READABLE_STATE_KEY_SUFFIXES` export instead of matching a numeric pattern, so their assertions self-update at the next storage-format bump. (bcc55fd, [#790](https://github.com/Takazudo/zudo-design-token-panel/issues/790), [#793](https://github.com/Takazudo/zudo-design-token-panel/issues/793), [#814](https://github.com/Takazudo/zudo-design-token-panel/issues/814))
+
+- **Header action links now collapse behind the kebab menu at a panel content width of 1135px and below, making previously-clickable controls unreachable by their old selectors.** _(Retroactive correction added 2026-09-08. This behaviour shipped in 0.5.1 but was recorded only under **Fixed**, as `fix(panel): yield header controls before floating panel overflow`; it belongs here.)_ The header action links — Export, Load from JSON…, Apply, Reset — are hidden and served instead from the kebab trigger `.tokenpanel-actions-menu-btn` (`aria-label="Panel actions"`), which opens `.tokenpanel-actions-popover`. The rule is `@container tokenpanel (max-width: 1135px)` against `.tokenpanel-shell` (`container: tokenpanel / inline-size`). Two properties of that threshold matter: it engages at **1135px and below** — exactly 1135px collapses, 1136px does not — and it measures the **shell's own content-box inline size, not the viewport**, so the panel's borders count against the measured width. 1135px is wide enough that an ordinary desktop panel is already past it; a shell at 1024px is not a narrow or mobile case. The surprise is not that a responsive collapse exists but that it engages at a width most people would call desktop. Collapsed links are `display: none` and therefore leave the accessibility tree, so a query that worked through 0.5.0 times out on 0.5.1:
+
+  ```js
+  await page.getByRole('button', { name: 'Reset', exact: true }).click();
+  ```
+
+  Like the `matchesKey` narrowing above, this is consumer-observable, the TypeScript signature is unchanged so a type check will not surface it, and it should have ridden a minor release rather than this patch. **Migration**: open the kebab menu before reaching for an action, or drive the panel at a content width above the threshold — the recipe [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/) covers both, with the boundary arithmetic. A stable `data-zdtp-action` attribute for these controls landed in 0.5.2; it does not exist in 0.5.1. (06cbb0e, [#787](https://github.com/Takazudo/zudo-design-token-panel/issues/787), [#831](https://github.com/Takazudo/zudo-design-token-panel/issues/831))
+
 ### Fixed
 
 - fix: fit token grids and card controls at minimum panel width (8db4235)
@@ -25,7 +55,6 @@ The panel now fits its token grids, card controls, and header controls at the mi
 - Merge branch 'topic/790-storage-bootstrap-confirm' into base/sweep-260906-2-storage-bootstrap (aca17d0)
 - Confirm storage bootstrap regressions (1fdb75e)
 - Merge branch 'topic/790-readable-gate-probe' into base/sweep-260906-2-storage-bootstrap (be49753)
-- Bound eager loading to readable state keys (bcc55fd)
 - Merge branch 'topic/790-astro-ordinal-lifecycle' into base/sweep-260906-2-storage-bootstrap (48a76ab)
 - Keep spawn positions stable across Astro navigation (2a6672b)
 - Merge branch 'topic/790-persisted-spawn-ordinal' into base/sweep-260906-2-storage-bootstrap (03deeaa)

package/PORTABLE-CONTRACT.md

@@ -515,7 +515,7 @@ export interface TierConfig {
 }
 
 For the full `SemanticValue` mapping and emission behavior, see the maintained
-[Color-cluster reference](https://zudo-design-token-panel.takazudomodular.com/docs/reference/color-cluster/).
+[Color-cluster reference](https://zdtp.zudolab.dev/docs/reference/color-cluster/).
 
 /**
  * Color-cluster extras — the non-tier fields required for the color tab.
@@ -1515,6 +1515,47 @@ pipeline:
 </script>
 ```
 
+### 7.6 `data-zdtp-action` — stable header-action DOM hook
+
+The four header actions carry a stable per-action attribute so a consumer test
+can select one without matching its display label:
+
+```html
+<div role="button" class="tokenpanel-action-link" data-zdtp-action="export">Export</div>
+```
+
+| Action label      | `data-zdtp-action` |
+| ----------------- | ------------------ |
+| `Export`          | `export`           |
+| `Load from JSON…` | `import`           |
+| `Apply`           | `apply`            |
+| `Reset`           | `reset`            |
+
+**The ids are stable; the labels are not.** Labels are display strings and may
+change at any minor version (note the ellipsis in `Load from JSON…`, which is
+`…` U+2026, not three periods). Select on the attribute, never on the text.
+
+Both affordances emit it with identical values: the header row and the compact
+kebab popover that takes over visually below the header's container-query
+threshold.
+
+**The hook does not remove the visibility branch.** `ShellHeader` *always*
+renders the header action row; the container query only hides it with
+`display: none`. So while the compact popover is open, `[data-zdtp-action="reset"]`
+matches **two** elements — the hidden header control and the popover item. A
+bare attribute selector is therefore not unambiguous at narrow widths; qualify
+it by visibility (Playwright's `:visible` / `.filter({ visible: true })`, or a
+non-zero bounding box) to land on exactly one.
+
+Scope — this hook covers the header actions and their compact popover only,
+which means every layout sharing `ShellHeader`: floating, right-docked, and
+bottom-docked. Deliberately **not** covered:
+
+- The **command palette**, which renders its own Export / Import / Apply entries
+  and whose reset entries are per-tab (`Reset {tab.label}`), not the header's
+  reset-all.
+- **Mini mode**, which renders Apply and has no header.
+
 ---
 
 ## 8. Storage-key continuity & migration paths
@@ -1660,6 +1701,28 @@ Items this contract deliberately does NOT pin down:
 
 ---
 
+## 11. Versioning & compatibility
+
+The package is pre-1.0 (`0.x`). This section states what a consumer may rely
+on across a release bump.
+
+- **The versioning promise.** On 0.x, patch releases preserve documented
+  public contracts and accepted consumer inputs. Consumer-breaking contract
+  changes, including input narrowing, require a minor release. Patches remain
+  free to fix bugs, and a bug fix can change observable behavior; the promise
+  only bounds what a patch may take *away* from a consumer.
+- **How breaking changes are signalled.** A consumer-breaking contract change
+  gets its own heading in the release notes, with a migration pointer naming
+  the new adoption path.
+- **What consumers should do.** A host mirroring the eager-load gate should
+  derive its checks from the exported registries
+  (`READABLE_STATE_KEY_SUFFIXES`, `EAGER_LOAD_GATE_KEY_SUFFIXES`) documented
+  in §6.2, rather than matching a pattern of its own — that way the host's
+  assertions self-update on the next storage-format bump instead of silently
+  drifting from the package's actual behavior.
+
+---
+
 ## Appendix A — section index
 
 Cross-reference table — what each section pins down.
@@ -1688,7 +1751,9 @@ Cross-reference table — what each section pins down.
 | Modal class prefix and `data-design-token-panel-modal` selector contract                    | §7.3          |
 | Self-contained panel chrome palette (no host theme reads)                                  | §7.4          |
 | Host-adapter side-effect import (paired-unit obligation)                                    | §7.5          |
+| `data-zdtp-action` stable header-action hook (ids stable, labels not; two matches while the compact popover is open) | §7.6 |
 | v4 envelope precedence, v1/v2/v3 storage migration, and typography-id rename map             | §2, §8.3, §8.4 |
 | JSON export/import schemas v1/v2/v3 (serde)                                                  | §9            |
 | Out-of-scope / deferred concerns                                                            | §10           |
+| Versioning promise, breaking-change signalling, and consumer guidance for mirroring the eager-load gate registries | §11 |
 | Feature walkthrough and shortcut table                                                     | [Panel UX tour](/docs/recipes/panel-ux-tour) |

package/dist/controls/actions-menu-popover.d.ts

@@ -11,6 +11,10 @@
  */
 import type { ComponentChildren, JSX } from 'preact';
 export interface ActionsMenuAction {
+    /** Stable action id, emitted as `data-zdtp-action` on the rendered item.
+     *  Required so the DOM hook can never silently go missing; labels are
+     *  display strings and must not be used as the key (PORTABLE-CONTRACT §7.6). */
+    id: string;
     label: string;
     onSelect: () => void;
     disabled?: boolean;

package/dist/controls/role-button.d.ts

@@ -16,5 +16,8 @@ export interface RoleButtonProps {
     title?: string;
     'aria-label'?: string;
     'data-testid'?: string;
+    /** Stable per-action DOM hook for consumer tests (see PORTABLE-CONTRACT §7.6).
+     *  Keyed on an action id, never on the display label. */
+    'data-zdtp-action'?: string;
 }
-export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, elementRef, id, title, 'aria-label': ariaLabel, 'data-testid': testId, }: RoleButtonProps): JSX.Element;
+export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, elementRef, id, title, 'aria-label': ariaLabel, 'data-testid': testId, 'data-zdtp-action': zdtpAction, }: RoleButtonProps): JSX.Element;

package/dist/{index-RLAXfjv2.js → index-CAQf4HKm.js}

@@ -1,6 +1,6 @@
 import { jsx as y, jsxs as K, Fragment as kt } from "preact/jsx-runtime";
 import { useEffect as P, useState as Y, useRef as O, useMemo as J, useCallback as X } from "preact/hooks";
-import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-D4NR_eYT.js";
+import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-ChsJ5u4d.js";
 import { g as vt, m as j } from "./panel-config-CqbuB0nh.js";
 const xt = (e, o) => {
   const t = new Array(e.length + o.length);