@takazudo/zdtp 0.6.1 → 0.8.0

package/dist/dashboard/model.d.ts

@@ -1,7 +1,9 @@
 import type { TabConfig } from "../tokens/tier-model.js";
-import type { DashboardMode, DashboardModel } from "./types.js";
+import type { DashboardMode, DashboardModel, DashboardModelOptions } from "./types.js";
 /**
  * Normalize the authored inventory for a static dashboard. Named color schemes,
  * stored changes, editor fallback values and pill.customDefault are not inputs.
  */
+export declare function buildDashboardModel(tabs: readonly TabConfig[], options?: DashboardModelOptions): DashboardModel;
+/** Compatibility for consumers passing the declared mode positionally. */
 export declare function buildDashboardModel(tabs: readonly TabConfig[], mode?: DashboardMode): DashboardModel;

package/dist/dashboard/styles.css

@@ -1,3 +1,41 @@
+/*
+ * Public chrome inputs. Hosts may set these four variables on the dashboard or
+ * on an ancestor. The registered initial values keep the dashboard usable when
+ * no host value is supplied; the `inherit` declarations below preserve an
+ * ancestor override instead of shadowing it.
+ *
+ * --zdtp-dashboard-light-bg: light-mode page and shell background.
+ * --zdtp-dashboard-light-fg: light-mode primary text and foreground.
+ * --zdtp-dashboard-dark-bg: dark-mode page and shell background.
+ * --zdtp-dashboard-dark-fg: dark-mode primary text and foreground.
+ *
+ * All other chrome colors are derived from these inputs with light-dark() and
+ * color-mix().
+ */
+@property --zdtp-dashboard-light-bg {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #f8fafc;
+}
+
+@property --zdtp-dashboard-light-fg {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #182131;
+}
+
+@property --zdtp-dashboard-dark-bg {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #151b24;
+}
+
+@property --zdtp-dashboard-dark-fg {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: #edf2f7;
+}
+
 /* Static dashboard chrome deliberately uses no inventory custom properties.
    The namespace and div/span markup protect documentation hosts from tag resets. */
 .zdtp-dashboard,
@@ -6,13 +44,60 @@
 }
 
 .zdtp-dashboard {
+  /* Keep these inputs inheritable so a wrapper can theme the dashboard. */
+  --zdtp-dashboard-light-bg: inherit;
+  --zdtp-dashboard-light-fg: inherit;
+  --zdtp-dashboard-dark-bg: inherit;
+  --zdtp-dashboard-dark-fg: inherit;
+
+  --zdtp-dashboard-bg: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 0%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 0%)
+  );
+  --zdtp-dashboard-fg: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 100%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 100%)
+  );
+  --zdtp-dashboard-muted: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 58%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 58%)
+  );
+  --zdtp-dashboard-border: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 16%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 22%)
+  );
+  --zdtp-dashboard-card-bg: light-dark(
+    color-mix(in oklab, color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 0%), white 20%),
+    color-mix(in oklab, color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 0%), black 8%)
+  );
+  --zdtp-dashboard-diag-bg: light-dark(#fff5e6, #3b2c18);
+  --zdtp-dashboard-diag-fg: light-dark(#704612, #ffdaa3);
+  --zdtp-dashboard-diag-accent: light-dark(#9d641a, #e4ad5c);
+  --zdtp-dashboard-focus: light-dark(#245caa, #6488b8);
+  --zdtp-dashboard-ruler-major: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 48%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 52%)
+  );
+  --zdtp-dashboard-ruler-minor: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 22%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 26%)
+  );
+  --zdtp-dashboard-bar: light-dark(#526c92, #9dbbe6);
+  --zdtp-dashboard-sample-bg: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 4%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 6%)
+  );
+  --zdtp-dashboard-sample-border: light-dark(
+    color-mix(in oklab, var(--zdtp-dashboard-light-bg, #f8fafc), var(--zdtp-dashboard-light-fg, #182131) 48%),
+    color-mix(in oklab, var(--zdtp-dashboard-dark-bg, #151b24), var(--zdtp-dashboard-dark-fg, #edf2f7) 52%)
+  );
+  --zdtp-dashboard-transparent: transparent;
   min-inline-size: 0;
   max-inline-size: 100%;
-  border: 1px solid #dce1e8;
+  border: 1px solid var(--zdtp-dashboard-border);
   border-radius: 10px;
-  background: #f8fafc;
-  color: #182131;
-  color-scheme: light;
+  background: transparent;
+  color: inherit;
   font: 400 14px/1.5 system-ui, sans-serif;
   letter-spacing: normal;
   text-align: start;
@@ -21,6 +106,15 @@
   overflow-wrap: anywhere;
 }
 
+.zdtp-dashboard[data-chrome='host'] { color-scheme: inherit; }
+
+/* Shell chrome is scoped to the header and the mode-independent region. This
+   leaves a mode-dependent `data-scheme="host"` region able to inherit from the
+   page ancestor, even when the shell itself is fixed to light or dark. */
+.zdtp-dashboard[data-chrome='light'] > .zdtp-dashboard__header { color-scheme: light; }
+.zdtp-dashboard[data-chrome='dark'] > .zdtp-dashboard__header { color-scheme: dark; }
+.zdtp-dashboard[data-chrome='host'] > .zdtp-dashboard__header { color-scheme: inherit; }
+
 .zdtp-dashboard :where(div, span) {
   min-inline-size: 0;
   margin: 0;
@@ -37,9 +131,22 @@
   display: grid;
   gap: 8px;
   padding: 20px;
-  border-block-end: 1px solid #dce1e8;
+  border-block-end: 1px solid var(--zdtp-dashboard-border);
+  background: var(--zdtp-dashboard-bg);
+  color: var(--zdtp-dashboard-fg);
 }
 
+.zdtp-dashboard__region {
+  display: grid;
+  gap: 32px;
+  background: var(--zdtp-dashboard-bg);
+  color: var(--zdtp-dashboard-fg);
+}
+
+.zdtp-dashboard__region[data-scheme='light'] { color-scheme: light; }
+.zdtp-dashboard__region[data-scheme='dark'] { color-scheme: dark; }
+.zdtp-dashboard__region[data-scheme='host'] { color-scheme: inherit; }
+
 .zdtp-dashboard__title {
   font-size: 22px;
   font-weight: 700;
@@ -51,12 +158,12 @@
   flex-wrap: wrap;
   align-items: baseline;
   gap: 4px 16px;
-  color: #536174;
+  color: var(--zdtp-dashboard-muted);
   font-size: 12px;
 }
 
 .zdtp-dashboard__count {
-  color: #182131;
+  color: var(--zdtp-dashboard-fg);
   font-weight: 600;
 }
 
@@ -77,7 +184,7 @@
   align-items: baseline;
   gap: 4px 12px;
   padding-block-end: 8px;
-  border-block-end: 1px solid #dce1e8;
+  border-block-end: 1px solid var(--zdtp-dashboard-border);
 }
 
 .zdtp-dashboard__tab-title {
@@ -86,7 +193,7 @@
 }
 
 .zdtp-dashboard__tab-count {
-  color: #536174;
+  color: var(--zdtp-dashboard-muted);
   font-size: 12px;
 }
 
@@ -108,10 +215,10 @@
 .zdtp-dashboard__token {
   display: flex;
   flex-direction: column;
-  border: 1px solid #dce1e8;
+  border: 1px solid var(--zdtp-dashboard-border);
   border-radius: 6px;
-  background: #fff;
-  color: #182131;
+  background: var(--zdtp-dashboard-card-bg);
+  color: var(--zdtp-dashboard-fg);
 }
 
 .zdtp-dashboard__token-content {
@@ -135,39 +242,40 @@
 
 .zdtp-dashboard__variable,
 .zdtp-dashboard__reference {
-  color: #536174;
+  color: var(--zdtp-dashboard-muted);
 }
 
 .zdtp-dashboard__value {
   padding-block-start: 5px;
-  color: #182131;
+  color: var(--zdtp-dashboard-fg);
 }
 
 .zdtp-dashboard__diagnostic {
   margin-block-start: 3px;
   padding: 8px;
-  border-inline-start: 2px solid #9d641a;
-  background: #fff5e6;
-  color: #704612;
+  border-inline-start: 2px solid var(--zdtp-dashboard-diag-accent);
+  background: var(--zdtp-dashboard-diag-bg);
+  color: var(--zdtp-dashboard-diag-fg);
   font-size: 12px;
 }
 
 .zdtp-dashboard__preview {
   display: flex;
-  align-items: center;
-  padding: 16px;
   block-size: 88px;
-  border-block-end: 1px solid #dce1e8;
+  border-block-end: 1px solid var(--zdtp-dashboard-border);
   border-start-start-radius: 5px;
   border-start-end-radius: 5px;
-  background: #eef1f5;
-  color: #182131;
   overflow: hidden;
 }
 
-.zdtp-dashboard[data-mode='dark'] .zdtp-dashboard__preview {
-  background: #222936;
-  color: #f1f5f9;
+/* The inner well owns specimen paint and mode; borders and scrolling stay outside. */
+.zdtp-dashboard__preview > .zdtp-dashboard__specimen {
+  display: flex;
+  align-items: center;
+  flex: 1;
+  padding: 16px;
+  background: light-dark(#eef1f5, #222936);
+  color: light-dark(#182131, #f1f5f9);
 }
 
 .zdtp-dashboard__sample {
@@ -176,13 +284,9 @@
   max-inline-size: 100%;
 }
 
-.zdtp-dashboard__preview--color {
+.zdtp-dashboard__preview--color > .zdtp-dashboard__specimen {
   padding: 0;
-  background: repeating-conic-gradient(#e2e6eb 0% 25%, #fff 0% 50%) 0 / 16px 16px;
-}
-
-.zdtp-dashboard[data-mode='dark'] .zdtp-dashboard__preview--color {
-  background: repeating-conic-gradient(#3e4652 0% 25%, #252c37 0% 50%) 0 / 16px 16px;
+  background: repeating-conic-gradient(light-dark(#e2e6eb, #3e4652) 0% 25%, light-dark(#fff, #252c37) 0% 50%) 0 / 16px 16px;
 }
 
 .zdtp-dashboard__sample--color {
@@ -192,15 +296,14 @@
 
 .zdtp-dashboard__sample--bar {
   block-size: 16px;
-  background: currentColor;
 }
 
 .zdtp-dashboard__sample--radius,
 .zdtp-dashboard__sample--shadow {
   inline-size: 64px;
   block-size: 48px;
-  background: #fff;
-  border: 1px solid #8290a3;
+  background: var(--zdtp-dashboard-sample-bg);
+  border: 1px solid var(--zdtp-dashboard-sample-border);
 }
 
 .zdtp-dashboard__sample--family,
@@ -214,7 +317,8 @@
 }
 
 .zdtp-dashboard__empty {
-  color: #536174;
+  background: var(--zdtp-dashboard-bg);
+  color: var(--zdtp-dashboard-muted);
 }
 
 /* Wide rows use their embedding width, including narrow documentation columns. */
@@ -232,13 +336,14 @@
   overscroll-behavior-inline: contain;
 }
 .zdtp-dashboard__scroll:focus-visible {
-  outline: 2px solid #245caa;
-  outline-offset: -2px;
+  outline: 2px solid var(--zdtp-dashboard-focus);
+  /* Paint outside the mode-scoped well, against surrounding chrome. */
+  outline-offset: 0;
 }
 .zdtp-dashboard__ruler-wrap { padding: 12px; }
 .zdtp-dashboard__ruler-caption,
 .zdtp-dashboard__preview-unavailable {
-  color: #536174;
+  color: var(--zdtp-dashboard-muted);
   font-size: 12px;
   padding: 12px;
 }
@@ -248,8 +353,8 @@
   block-size: 64px;
   padding-block-start: 36px;
   background:
-    repeating-linear-gradient(to right, #8290a3 0 1px, transparent 1px 64px) left 24px / 100% 12px no-repeat,
-    repeating-linear-gradient(to right, #c4ccd7 0 1px, transparent 1px 8px) left 30px / 100% 6px no-repeat;
+    repeating-linear-gradient(to right, var(--zdtp-dashboard-ruler-major) 0 1px, var(--zdtp-dashboard-transparent) 1px 64px) left 24px / 100% 12px no-repeat,
+    repeating-linear-gradient(to right, var(--zdtp-dashboard-ruler-minor) 0 1px, var(--zdtp-dashboard-transparent) 1px 8px) left 30px / 100% 6px no-repeat;
 }
 .zdtp-dashboard__ruler-origin { position: absolute; inset-block-start: 0; inset-inline-start: 0; font-size: 12px; }
 .zdtp-dashboard__sample--bar {
@@ -257,7 +362,7 @@
   min-inline-size: 0;
   border: 0;
   padding: 0;
-  background: #526c92;
+  background: var(--zdtp-dashboard-bar);
 }
 .zdtp-dashboard__palette {
   display: flex;
@@ -278,11 +383,15 @@
 .zdtp-dashboard__preview--typography {
   display: block;
   block-size: auto;
-  padding: 20px;
   border: 0;
   border-radius: 0;
 }
-.zdtp-dashboard__preview--typography > .zdtp-dashboard__sample {
+.zdtp-dashboard__preview--typography > .zdtp-dashboard__specimen {
+  display: block;
+  padding: 20px;
+  min-block-size: 100%;
+}
+.zdtp-dashboard__preview--typography > .zdtp-dashboard__specimen > .zdtp-dashboard__sample {
   font: 400 18px/1.6 system-ui, sans-serif;
   letter-spacing: normal;
   white-space: pre-wrap;

package/dist/dashboard/token-dashboard.d.ts

@@ -1,12 +1,19 @@
 import type { JSX } from 'preact';
 import type { TabConfig, TierConfig } from "../tokens/tier-model.js";
-import type { DashboardMode } from "./types.js";
+import type { DashboardChrome, DashboardInclude, DashboardMode } from "./types.js";
 /** Visual samples are independent from the panel's editor kind. */
 export type DashboardPreviewKind = NonNullable<TierConfig['preview']> | 'color' | 'shadow' | 'text';
 export interface TokenDashboardProps {
     tabs: readonly TabConfig[];
-    /** Selects declared per-mode defaults. Does not read the host or panel mode. */
+    /** Selects declared per-mode defaults. 'host' follows the inherited CSS
+     * color-scheme without reading browser or panel state. Defaults to 'light'. */
     mode?: DashboardMode;
+    /** Selects visible rows by mode dependence. Defaults to 'all'. */
+    include?: DashboardInclude;
+    /** Selects the shell and mode-independent region's appearance, including
+     * cards, labels, borders, diagnostics and focus/scroll affordances.
+     * 'host' inherits the host's effective color-scheme. Defaults to 'light'. */
+    chrome?: DashboardChrome;
     title?: string;
     /** Static multiline typography specimen. Empty strings are preserved. */
     previewText?: string;
@@ -20,4 +27,4 @@ export interface TokenDashboardProps {
  * server renderer without hydration, browser globals, or panel configuration.
  * Include @takazudo/zdtp/dashboard/styles.css through the host's CSS pipeline.
  */
-export declare function TokenDashboard({ tabs, mode, title, id, previewOverrides, previewText, }: TokenDashboardProps): JSX.Element;
+export declare function TokenDashboard({ tabs, mode, include, chrome, title, id, previewOverrides, previewText, }: TokenDashboardProps): JSX.Element;

package/dist/dashboard/types.d.ts

@@ -1,6 +1,13 @@
 import type { TierConfig, TierValueKind } from "../tokens/tier-model.js";
 /** Internal, render-independent description of declared token defaults. */
-export type DashboardMode = 'light' | 'dark';
+export type DashboardMode = 'light' | 'dark' | 'host';
+export type DashboardInclude = 'all' | 'mode-dependent' | 'mode-independent';
+export interface DashboardModelOptions {
+    mode?: DashboardMode;
+    include?: DashboardInclude;
+}
+/** Appearance of the dashboard chrome, independent of declared token mode. */
+export type DashboardChrome = 'light' | 'dark' | 'host';
 export interface DashboardDiagnostic {
     code: string;
     severity: 'warning' | 'error';
@@ -22,6 +29,13 @@ export interface DashboardRow {
     cssVar: string;
     kind: TierValueKind['kind'];
     source: 'item' | 'base-role';
+    modeDependent: boolean;
+    /** Direct authored pair; reference-derived dependence has no local pair. */
+    sides: {
+        light: string;
+        dark: string;
+    } | null;
+    origin: 'modes' | 'semantic' | 'default' | 'reference' | null;
     defaultValue: string;
     /** Human-readable selected-mode declaration, including explicit semantic overrides. */
     declaredValue: string;
@@ -29,8 +43,9 @@ export interface DashboardRow {
     cssValue: string | null;
     /**
      * Follows direct declared references only, never computes CSS. Expressions
-     * remain expressions. Null means invalid or dependent on unknown context;
-     * the renderer must not show a value preview in that case.
+     * remain expressions. Null means invalid or dependent on unknown context.
+     * In host mode, mode-dependent rows stay null while cssValue retains the
+     * declarations needed for the browser to resolve the inherited scheme.
      */
     resolvedValue: string | null;
     references: DashboardReference[];
@@ -54,7 +69,10 @@ export interface DashboardTab {
 }
 export interface DashboardModel {
     mode: DashboardMode;
+    include: DashboardInclude;
+    /** Visible inventory, with empty tiers and tabs omitted. */
     tabs: DashboardTab[];
+    /** Complete graph, including rows hidden by include. */
     rows: DashboardRow[];
     /** Declare these on each preview scope, never on :root or the document. */
     declarations: Readonly<Record<string, string>>;

package/dist/import-modal.d.ts

@@ -1,40 +1,39 @@
 /**
- * Import modal — accepts a pasted design-tokens JSON document and lifts it
- * into a `TweakState` via `deserialize()`. `deserialize()` validates the
- * `$schema` key against the fixed `SCHEMA_V1`/`SCHEMA_V2`/`SCHEMA_V3`
- * constants exported by the serde — `panelConfig.schemaId` plays no part in
- * that validation; it is a UI-label-only field (#498). This component does
- * not read `schemaId` at all; the hint/placeholder/error copy below names
- * the actual accepted constants directly.
+ * Import modal — accepts a pasted design-tokens JSON document and guides the
+ * user through paste → analyze → scope → load.
  *
- * Ported verbatim from zudo-doc's
- * `src/components/design-token-tweak/import-modal.tsx`. Intentional deltas:
- *  - `deserialize` / `DesignTokenSchemaError` come from this package's serde
- *    (`./utils/design-token-serde`).
- *  - State types import from this package's state envelope.
- *  - Modal class names are derived from `panelConfig.modalClassPrefix` via
- *    `modalClass(...)` so a single config swap re-themes every dialog.
+ * `analyzeDesignTokenJson()` is deliberately state-free, so the first step
+ * can inspect a document without applying values or touching storage. The
+ * selected tabs and mode/merge choices are passed to `deserialize()` only
+ * after the user explicitly chooses Load.
  *
  * Modal lifecycle uses the native `<dialog>` element via `showModal()` /
- * `close()`. Every dismissal path (× button, backdrop click, Escape key, the
- * programmatic "Close" button) routes through `dialog.close()` so the native
- * `close` event — and thus `onClose` — fires exactly once per dismissal.
+ * `close()`. Every dismissal path routes through `dialog.close()` so the
+ * native `close` event — and thus `onClose` — fires exactly once per
+ * dismissal.
  */
 import type { ColorTweakState, TweakState } from "./state/tweak-state.js";
 import { type PanelConfig } from "./config/panel-config.js";
 export interface ImportModalProps {
     onClose: () => void;
     /** Called with the parsed state when the user hits "Load". The caller is
-     *  responsible for applying it to the panel + persisting it. */
+     * responsible for applying it to the panel + persisting it. */
     onLoad: (state: TweakState) => void;
     /** Color baseline filled in for fields absent from the payload. */
     colorDefaults: ColorTweakState;
+    /**
+     * The mounted panel instance's live state. It is used by scoped merge and
+     * one-side imports to preserve values from the instance being edited.
+     * Omitted for backwards-compatible direct renders; serde then falls back to
+     * manifest/default values for those options.
+     */
+    current?: TweakState;
     /**
      * The mounted panel instance's config (multi-instance, #357). When supplied,
-     * the modal derives its modal classes + title id from THIS instance rather
-     * than the active default instance. Omitted (e.g. a direct test render) →
-     * `getPanelConfig()`, preserving the single-panel path.
+     * the modal derives its modal classes + title id and serde lookups from THIS
+     * instance rather than the active default instance. Omitted (e.g. a direct
+     * test render) → `getPanelConfig()`, preserving the single-panel path.
      */
     instanceConfig?: PanelConfig;
 }
-export declare function ImportModal({ onClose, onLoad, colorDefaults, instanceConfig }: ImportModalProps): import("preact").JSX.Element;
+export declare function ImportModal({ onClose, onLoad, colorDefaults, current, instanceConfig, }: ImportModalProps): import("preact").JSX.Element;

package/dist/{index-LYsbHWcy.js → index-BH_IJp9W.js}

@@ -1,7 +1,7 @@
 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-DWs1XPfy.js";
-import { g as vt, m as j } from "./panel-config-Crn5QJGy.js";
+import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-blRjSavc.js";
+import { g as vt, m as j } from "./panel-config-DKfob-1r.js";
 const xt = (e, o) => {
   const t = new Array(e.length + o.length);
   for (let r = 0; r < e.length; r++)