@takazudo/zdtp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ 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.
 
+## [Unreleased]
+
+No unreleased changes yet.
+
+## [0.7.0] - 2026-09-09
+
+### Breaking Changes
+
+- feat(dashboard): separate chrome theme from specimen mode (84d4d8a). `TokenDashboard` no longer derives its chrome appearance from `mode`: with `mode="dark"` the inventory scope previously carried `color-scheme: dark`, and now only `.zdtp-dashboard__specimen` does, with chrome defaulting to light. **Migration**: pass the new `chrome="dark"` prop alongside `mode="dark"` to restore the previous dark chrome, or `chrome="host"` to inherit the host's effective color scheme.
+
+### Features
+
+- feat: resolve CSS color expressions in host context ([#919](https://github.com/Takazudo/zudo-design-token-panel/issues/919)) (30dbabc)
+- feat: require explicit conversion before editing color expressions (ffad163)
+
+### Fixed
+
+- Fix invalid CSS color probe fallback (a1d468f)
+- Reject unchanged invalid color declarations before measurement (27fbc70)
+
+### Other Changes
+
+- docs(dashboard): document host chrome and add static theme examples (1b8e26d)
+- docs(dashboard): document chrome contract (83778e8)
+- test: cover dashboard chrome themes in browser (5682c72)
+- test: strengthen dashboard specimen isolation assertions (cc62be6)
+- test: prove dashboard host chrome from packed consumer (7a251f0)
+- test(evidence): record dashboard chrome integration proof (690af1f)
+- test: wire semantic expression picker modes (90af515)
+- Cover empty CSS color resolution (18f45ba)
+- docs: record reference-aware color picker fix (b1bb048)
+- test: record reference-aware picker confirmation (045603b)
+- docs: correct picker evidence provenance (89e0322)
+
+## [0.6.1] - 2026-09-08
+
+### Features
+
+- feat: model declared token defaults for static dashboards (422643b)
+- feat: expose a static Preact token dashboard (5b6c0f8)
+- feat(playground): add static token dashboard demo and docs (2edd98b)
+- feat(dashboard): render rulers, palette strips and wide type specimens (7cdf01f)
+
+### Fixed
+
+- fix: preserve semantic literals alongside legacy palette references (b813c8a)
+
+### Other Changes
+
+- test: account for standalone dashboard stylesheet delivery (a00541a)
+- test: verify packed dashboard SSR and public stylesheet consumption (6cd8157)
+- test: cover static dashboard list-view geometry in browser (e07d69e)
+- chore: normalize dashboard browser test file mode (0ec8217)
+- docs: demonstrate dashboard rulers ramps and reading specimens (859d3a4)
+- test: verify packed dashboard list views and preview text (7ebf4cf)
+- test: prove isolated dashboard package consumption (fdb3906)
+- fix(test): compare Preact package identity across module conditions (bb280ee)
+- Fix static browser harness loading and polling (3fe6203)
+
 ## [0.6.0] - 2026-09-08
 
 ### Breaking Changes

package/PORTABLE-CONTRACT.md

@@ -1741,6 +1741,117 @@ on across a release bump.
 
 ---
 
+## 12. Static token dashboard
+
+This entry is available from v0.6.1. The `chrome` prop is **unreleased (next
+release)** and is not supported in v0.6.1. It does not change the
+`configurePanel` or persistence contracts above.
+
+`@takazudo/zdtp/dashboard` exports the Preact `TokenDashboard` component and
+`TokenDashboardProps`, `DashboardMode`, `DashboardChrome`,
+`DashboardPreviewKind`, `TabConfig`, `TierConfig`, and `TierItem` types. The
+internal value model is not a public API.
+
+```ts
+export type DashboardMode = 'light' | 'dark';
+export type DashboardChrome = 'light' | 'dark' | 'host';
+export type DashboardPreviewKind =
+  | 'bar' | 'size' | 'line-height' | 'family' | 'weight' | 'radius' | 'duration'
+  | 'color' | 'shadow' | 'text';
+
+export interface TokenDashboardProps {
+  tabs: readonly TabConfig[];
+  mode?: DashboardMode; // default: light
+  chrome?: DashboardChrome; // default: light; unreleased (next release)
+  title?: string; // default: Token dashboard
+  previewText?: string; // static typography passage; default English/Japanese prose
+  id?: string; // optional root ID; caller owns uniqueness
+  previewOverrides?: Readonly<Record<string, DashboardPreviewKind>>;
+}
+```
+
+### Rendering and package boundary
+
+- Ordinary Preact rendering and server rendering are supported. The component
+  has no browser-global, panel-runtime, persistence, host-adapter, bin-server,
+  or browser Tailwind compiler dependency. No hydration is required.
+- `@takazudo/zdtp/dashboard/styles.css` is a separate public asset. Dashboard
+  JavaScript has no CSS side-effect import; the host must include this asset
+  through its CSS build or a static stylesheet link. It is not appended to the
+  existing panel stylesheet, which is unnecessary for a dashboard-only page.
+- The dashboard root's chrome appearance follows `chrome`: `light` and `dark`
+  fix the shell scheme, while `host` inherits the host's effective
+  `color-scheme` and requires the host to set it on an ancestor. The dashboard
+  uses no media query, so an explicit application theme takes precedence over
+  the OS preference. Inventory specimens retain their own `color-scheme` from
+  `mode`, which also selects declared per-mode defaults. Chrome and specimens
+  are independent; chrome uses package-owned CSS custom properties and never
+  reads inventory variables. The component never writes to `:root` or host
+  state.
+- Tabs, tiers, and rows render in input order. All token rows remain visible;
+  no collapsed sections or automatic IDs are introduced. Empty input is valid.
+  Notes-only tabs are omitted, and arbitrary notes HTML is never injected.
+
+### Layouts for spacing, color, and typography
+
+Spacing (`bar`) uses wide rows with aligned ruler origins. Nonnegative `px` or
+`rem` lengths, unitless zero, and resolved direct local aliases get an actual-size
+sample. Ticks mark 8 CSS px, with major ticks every 64 CSS px. The browser sizes
+`rem` against the host root font size; the dashboard does not assume a conversion.
+Large lengths scroll inside the focusable ruler instead of shrinking or clamping.
+Zero has zero width. Negative lengths, `em`, percentages, `calc()` and other
+unsupported expressions retain their declaration with a ruler-unavailable
+explanation. Missing references also retain their diagnostics.
+
+A nonsemantic, non-reference tier whose source items are all colors becomes a
+discrete palette strip. Stops stay in declared order, with every label and value
+visible; narrow containers scroll horizontally. Grouping uses tier structure,
+not name matching or generated intermediate colors. Semantic and reference tiers
+keep independent color samples. Per-variable preview overrides remain authoritative
+and retain each token's slot and order, including mixed overrides within a strip.
+
+`size`, `family`, `weight`, and `line-height` use wide, multiline specimens with
+auto height outside palette strips. Overrides inside a palette retain their stop slot. The baseline is 18px text with 1.6 line height; each sample changes
+only its intended property. A resolved `previewBase` can supply the font size of
+a line-height sample. Font families use locally available fonts and their CSS
+fallbacks; the dashboard does not download fonts.
+
+`previewText` supplies one static passage for all typography samples in an
+instance. Its default is longer English/Japanese prose. Newlines and white space
+are preserved, text is escaped, and an explicit empty string stays empty.
+Long text wraps; unusually large glyphs can scroll locally without scaling.
+There is no built-in editable text workbench or connection to panel state.
+
+### Values and previews
+
+- Inputs describe **declared defaults**: item defaults, selected-mode
+  `colorExtras.semanticDefaults`, and explicit `colorExtras.baseDefaults` for
+  base-role rows. Named presets, panel initialization, and saved/current panel
+  state are not applied. Pill rows preserve `item.default`, not `customDefault`.
+- Reference tiers, cross-tab ramps, aliases, and legacy palette indices resolve
+  against actual declared IDs and `cssVar` names. Rows retain declared values
+  and display CSS/reference text. Missing/ambiguous mappings, duplicate
+  variables, cycles, and unsafe declarations remain visible with diagnostics
+  and no misleading sample.
+- CSS expressions remain expressions. Resolution is not universal CSS grammar
+  validation or browser computed-style inspection. External dependencies may
+  be context-dependent; unresolved dependencies suppress samples and expose
+  diagnostics. Browser layout, units, and available fonts affect previews.
+- Preview choice is `previewOverrides[cssVar]`, then `TierConfig.preview`, then
+  color for color-editor rows or text for other rows. `duration` and `text`
+  display values without animated/visual samples. A resolved `previewBase`
+  token can supply font size for a line-height sample. Subsets must include
+  referenced tiers to retain resolved samples.
+- Preact escapes text. URL/mask assets and unsafe resource-bearing expressions
+  are not automatically loaded through samples.
+
+Keep shared token definitions in a build-safe data module using type-only
+imports. Pass the same tabs to `PanelConfig` and `TokenDashboard`; no automatic
+state synchronization follows from sharing them. A React adapter and an
+HTML-export function or CLI are outside this checkpoint.
+
+---
+
 ## Appendix A — section index
 
 Cross-reference table — what each section pins down.
@@ -1772,6 +1883,7 @@ Cross-reference table — what each section pins down.
 | `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            |
+| Static Preact dashboard props, defaults, previews, isolation, and CSS export | §12 |
 | 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/README.md

@@ -32,12 +32,105 @@ The authoritative API spec is [`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md).
   partial reconciliation, and JSON export/import when disk apply is not
   configured.
 - Owner autoload for developer-only loading across page visits.
+- A separate Preact `TokenDashboard` for a static, read-only token inventory
+  (available from v0.6.1).
 
 See the [Panel UX tour](/docs/recipes/panel-ux-tour) for a feature-by-feature
 walkthrough and the shortcut table.
 
 ---
 
+## Static token dashboard
+
+Import `TokenDashboard` from `@takazudo/zdtp/dashboard` to render the same tab
+manifest on a plain page. This entry is available from v0.6.1. The `chrome`
+prop is **unreleased (next release)** and is not supported in v0.6.1. The [live workspace demo](https://zdtp-playground.zudolab.dev/dashboard/)
+shows both modes and a compact embedded instance.
+
+```tsx
+import { TokenDashboard } from '@takazudo/zdtp/dashboard';
+import { tokenTabs } from './token-tabs'; // Shared data module; type-only imports.
+
+export default function TokenPage() {
+  return <TokenDashboard tabs={tokenTabs} mode="light" title="Site tokens" />;
+}
+```
+
+For example, keep the definitions in a module that is safe to import at build time:
+
+```ts
+// token-tabs.ts — data only; safe to import during a site build.
+import type { TabConfig } from '@takazudo/zdtp/dashboard';
+
+export const tokenTabs: readonly TabConfig[] = [{
+  id: 'space',
+  label: 'Spacing',
+  tiers: [{
+    id: 'scale',
+    label: 'Scale',
+    preview: 'bar',
+    items: [{
+      id: 'space-md',
+      cssVar: '--site-space-md',
+      label: 'Medium',
+      default: '1rem',
+      type: { kind: 'length', step: 0.25, unit: 'rem' },
+    }],
+  }],
+}];
+```
+
+Also pass `tokenTabs` as `tabs` in your panel's config. Keep panel initialization
+and browser/storage code out of this data module.
+The component requires Preact and can render during the host's static build
+without hydration; no panel initialization is needed.
+
+Include **`@takazudo/zdtp/dashboard/styles.css`** separately. The dashboard JS
+does not import CSS and does not need the panel stylesheet. A CSS-emitting
+bundler can import this asset from its layout; strict static hosts should use
+a supported global CSS `@import` or copy the resolved public export to their
+public assets directory and add a stylesheet link. The
+[static dashboard recipe](https://zdtp.zudolab.dev/docs/recipes/static-token-dashboard/)
+provides complete data and CSS-copy examples.
+
+Optional props are `mode` (`light` by default), `chrome` (`light` by default;
+**unreleased for the next release**), `title`, caller-owned unique `id`,
+`previewText`, and `previewOverrides` keyed by CSS variable (for example, a
+text-editor shadow can use `'shadow'`). Existing `TierConfig.preview` metadata is reused.
+
+`chrome="light"` and `chrome="dark"` fix the dashboard shell appearance;
+`chrome="host"` inherits the host's effective `color-scheme` and requires the
+host to set it on an ancestor. Chrome is independent of `mode`: `mode` selects
+declared per-mode defaults and each specimen's own `color-scheme`, while chrome
+uses package-owned CSS custom properties and never reads inventory variables.
+The dashboard uses no media query, so an explicit application theme wins over
+the OS preference.
+
+Spacing uses actual-size rulers with local scrolling. Nonnegative px/rem, zero,
+and resolved direct aliases are supported; other lengths keep a readable fallback.
+Color-only nonsemantic, non-reference tiers form discrete strips in source order.
+Typography uses wide multiline specimens; `previewText` supplies your static
+passage (default: English/Japanese prose; an explicit empty string stays empty).
+The baseline is 18px/1.6, with only the intended property changed and resolved
+`previewBase` honored for line-height. Fonts use local availability and CSS
+fallbacks. There is no editable text workbench.
+
+The inventory uses **declared defaults**: item defaults, per-mode
+`semanticDefaults`, and explicit base-role `baseDefaults`. It does not apply
+named color presets, panel initialization, or persisted edits. CSS expressions
+remain expressions; samples depend on browser layout and available fonts.
+Missing/context-dependent references and invalid declarations remain readable
+with diagnostics rather than misleading samples. The dashboard root's chrome
+scheme follows `chrome`, while each specimen's `color-scheme` follows `mode`;
+both are local to the instance, and the component never writes to `:root`.
+Arbitrary notes HTML and URL/mask assets are not rendered or loaded.
+
+This checkpoint provides a Preact component. An HTML-export API/CLI, React
+adapter, and automatic panel-state synchronization are outside its scope.
+See [`PORTABLE-CONTRACT.md` §12](./PORTABLE-CONTRACT.md#12-static-token-dashboard).
+
+---
+
 ## 0. Architecture at a glance
 
 The design-token panel is a browser-based UI that writes token overrides to

package/dist/astro/host-adapter.js

@@ -1,5 +1,5 @@
 import { c as y, g as m, a as w, b, i as P } from "../panel-config-Crn5QJGy.js";
-import { g, Z as A } from "../tweak-state-Dzr5kDhX.js";
+import { g, Z as A } from "../tweak-state-Dhjqig0C.js";
 import { s as D, l as E, a as _, i as c, r as f, c as k, b as S, d } from "../autoload-state-CGnis85c.js";
 import { READABLE_STATE_KEY_SUFFIXES as T } from "../constants.js";
 const u = "tokenpanel-config";

package/dist/components/color-picker/color-field.d.ts

@@ -18,6 +18,8 @@ export interface ColorFieldProps {
      * with the native <input type="color"> path).
      */
     valueFormat?: ColorPickerValueFormat;
+    /** Host color scheme used to resolve CSS expressions. */
+    resolveMode?: 'light' | 'dark';
     /** Display label shown in the picker header and aria-label. */
     label: string;
     /** Optional CSS custom property name (e.g. `--my-color`). Used for aria-label. */
@@ -33,5 +35,5 @@ export interface ColorFieldProps {
  *
  * Readonly items show the swatch but do not open the picker on interaction.
  */
-export declare function ColorField({ value, onChange, valueFormat, label, cssVar, readonly: isReadonly, }: ColorFieldProps): import("preact").JSX.Element;
+export declare function ColorField({ value, onChange, valueFormat, resolveMode, label, cssVar, readonly: isReadonly, }: ColorFieldProps): import("preact").JSX.Element;
 export default ColorField;

package/dist/components/color-picker/color-picker.d.ts

@@ -48,6 +48,8 @@ export interface ColorPickerProps {
      * with existing callers that pass no value).
      */
     valueFormat?: ColorPickerValueFormat;
+    /** Host color scheme used to resolve CSS expressions. */
+    resolveMode?: 'light' | 'dark';
     /** Optional label rendered in the picker header. */
     label?: string;
     /**
@@ -93,5 +95,5 @@ export declare function usePopoverClose(containerRef: React.RefObject<HTMLElemen
  * The parent renders `{isOpen && <ColorPicker ... />}`. This component does
  * NOT render a trigger swatch and does NOT use createPortal.
  */
-export declare function ColorPicker({ color, onChange, valueFormat, label, defaultMode, anchorRef, onClose, }: ColorPickerProps): JSX.Element;
+export declare function ColorPicker({ color, onChange, valueFormat, resolveMode, label, defaultMode, anchorRef, onClose, }: ColorPickerProps): JSX.Element;
 export default ColorPicker;

package/dist/components/color-picker/custom-slider.d.ts

@@ -12,6 +12,7 @@ export interface SliderConfig {
     format: (v: number) => string;
 }
 export interface CustomSliderProps {
+    disabled?: boolean;
     config: SliderConfig;
     value: number;
     /** CSS gradient string applied to the track div's background. */
@@ -20,5 +21,5 @@ export interface CustomSliderProps {
     onDragStart: () => void;
     onDragEnd: () => void;
 }
-export declare function CustomSlider({ config, value, gradient, onChange, onDragStart, onDragEnd, }: CustomSliderProps): JSX.Element;
+export declare function CustomSlider({ disabled, config, value, gradient, onChange, onDragStart, onDragEnd, }: CustomSliderProps): JSX.Element;
 export default CustomSlider;

package/dist/dashboard/index.d.ts

@@ -0,0 +1,4 @@
+export { TokenDashboard } from "./token-dashboard.js";
+export type { TokenDashboardProps, DashboardPreviewKind } from "./token-dashboard.js";
+export type { DashboardMode, DashboardChrome } from "./types.js";
+export type { TabConfig, TierConfig, TierItem } from "../tokens/tier-model.js";