@takazudo/zdtp 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.4.4
+
+### Features
+
+- **Ramp-native Tier-2 color editor.** The Color tab gained a semantic-value tier model — a `semantic: true` tier holds `SemanticValue` mappings (palette index, literal OKLCH, per-mode `light-dark()` literal, or a cross-tab ramp `{ ref }`) instead of raw palette entries, and can ship as a lone semantic tier with no palette tier at all ([#459](https://github.com/Takazudo/zudo-design-token-panel/issues/459), closes [#458](https://github.com/Takazudo/zudo-design-token-panel/issues/458)) ([8ed93e1](https://github.com/Takazudo/zudo-design-token-panel/pull/476))
+- Add semantic-tier marker + `SemanticValue` union (S1) ([#460](https://github.com/Takazudo/zudo-design-token-panel/pull/460)) (d7aa526)
+- serde `SCHEMA_V3` object leaves for `SemanticValue` variants (S5) ([#462](https://github.com/Takazudo/zudo-design-token-panel/pull/462)) (0185477)
+- Render literal semantic rows as editable OKLCH swatches (S3) ([#464](https://github.com/Takazudo/zudo-design-token-panel/pull/464)) (d8bceb3)
+- Emit literal semantic values verbatim in both emitters (S4) ([#465](https://github.com/Takazudo/zudo-design-token-panel/pull/465)) (5961ed7)
+- Cross-tab ref resolution + tabs-array cluster-bridge signature (S7a) ([#467](https://github.com/Takazudo/zudo-design-token-panel/pull/467)) (35ef368)
+- Emit cross-tab semantic refs as `var(--target)` in both emitters (S7b) ([#468](https://github.com/Takazudo/zudo-design-token-panel/pull/468)) (ea2aa8a)
+- Validate cross-tab ramp-source declarations (S8) ([#469](https://github.com/Takazudo/zudo-design-token-panel/pull/469)) (8558269)
+- Grouped ref-or-literal picker + wire color-tab semantic rows (S9) ([#470](https://github.com/Takazudo/zudo-design-token-panel/pull/470)) (3d5e5f7)
+- Per-mode literal `light-dark()` emission + `defaultMode` runtime (S11) ([#472](https://github.com/Takazudo/zudo-design-token-panel/pull/472)) (3a05623)
+- Per-mode light/dark literal editor UI (S12) ([#473](https://github.com/Takazudo/zudo-design-token-panel/pull/473)) (1828458)
+
+### Fixed
+
+- Seed Scheme preset load against the instance cluster, not the global default ([#491](https://github.com/Takazudo/zudo-design-token-panel/issues/491) audit) (a1b0dd8)
+- Thread `instanceConfig` into `ColorTab` for multi-instance ref resolution ([#491](https://github.com/Takazudo/zudo-design-token-panel/issues/491)) (66447ec)
+- Validate semantic marker shape + mixed-order palette-pick regression tests ([#487](https://github.com/Takazudo/zudo-design-token-panel/pull/487)) (0ebcc6e)
+- Scheme/preset load is a no-op for a palette-less color cluster ([#488](https://github.com/Takazudo/zudo-design-token-panel/pull/488)) (23d61ba)
+- Color-scheme lifecycle asymmetries in the applied-state ([#482](https://github.com/Takazudo/zudo-design-token-panel/pull/482)) (ef686fc)
+- serde robustness — order-independent ref diff, stale-ref warning, integer index leaves (c0b4356)
+- Restore legacy index-0 fallback + detect named-color literals ([#483](https://github.com/Takazudo/zudo-design-token-panel/pull/483)) (4f66b7d)
+- Show a disabled unresolved placeholder for a dangling `TierRefSelector` ref ([#484](https://github.com/Takazudo/zudo-design-token-panel/issues/484)) (a4c222b)
+- Thread owning color tab into `buildApplyOverrides` for secondary-cluster refs (D1) ([#481](https://github.com/Takazudo/zudo-design-token-panel/pull/481)) (60cbb7a)
+- Skip an unresolvable semantic `{ ref }` in the DOM emitter too (87131ee)
+- Drop phantom grayscale swatch for palette-less semantic tier ([#466](https://github.com/Takazudo/zudo-design-token-panel/pull/466) follow-up) (c955616)
+- Derive semantic maps for a palette-less semantic tier (S2b) ([#463](https://github.com/Takazudo/zudo-design-token-panel/pull/463)) (7d617d1)
+- Honor semantic-tier marker in palette detection + F4 (S2a) ([#461](https://github.com/Takazudo/zudo-design-token-panel/pull/461)) (ecb4482)
+
+### Other Changes
+
+- Eliminate intermittent vitest unhandled-error flake ([#494](https://github.com/Takazudo/zudo-design-token-panel/issues/494)) (ab60f91)
+- e2e confirm per-mode literal `light-dark()` + clear color-scheme on reset (S13) ([#474](https://github.com/Takazudo/zudo-design-token-panel/pull/474)) (a215c88)
+- e2e confirm cross-tab semantic ref cascade (S10) ([#471](https://github.com/Takazudo/zudo-design-token-panel/pull/471)) (235bb30)
+- e2e confirm lone literal semantic tier unblocks [#458](https://github.com/Takazudo/zudo-design-token-panel/issues/458) (S6) ([#466](https://github.com/Takazudo/zudo-design-token-panel/pull/466)) (8fb5136)
+- docs: translate token-manifest reference page to Japanese ([#490](https://github.com/Takazudo/zudo-design-token-panel/issues/490), [#478](https://github.com/Takazudo/zudo-design-token-panel/issues/478)) (7bcd835)
+- docs: translate color-cluster reference to Japanese ([#489](https://github.com/Takazudo/zudo-design-token-panel/issues/489), [#478](https://github.com/Takazudo/zudo-design-token-panel/issues/478)) (e033410)
+- docs: fix EN documentation drift from [#459](https://github.com/Takazudo/zudo-design-token-panel/issues/459) (referencesRamps, bridge signature, color-scheme caveat) (a7d8709)
+- docs: document ramp-native Tier-2 editor + example manifest + cascade test (S14) ([#475](https://github.com/Takazudo/zudo-design-token-panel/pull/475)) (136bcf6)
+- docs: fix broken `SemanticValue` heading anchor (drop em-dash from slug) (ef3cd91)
+- chore(deps): bump `@takazudo/zudo-doc` and `zudo-doc-history-server` to `^2.5.1` (d6c05dd)
+- chore(doc): sync generated `claude/index.mdx` with build output (d763238)
+
 ## 0.4.3
 
 ### Features

package/dist/apply/build-apply-overrides.d.ts

@@ -30,9 +30,17 @@
  *   - Palette slots (resolved via `resolvePaletteCssVar(cluster, i)`) —
  *     EMITTED as the stored color value (hex, or `oklch(...)` for
  *     oklch-format palettes).
- *   - Semantic tokens (`cluster.semanticCssNames` entries) — EMITTED as
- *     `var(--<paletteSlotName>)` so the rewrite preserves the indirection
- *     that the hand-authored CSS relies on.
+ *   - Semantic tokens (`cluster.semanticCssNames` entries) — a legacy
+ *     index/`bg`/`fg` mapping is EMITTED as `var(--<paletteSlotName>)` so the
+ *     rewrite preserves the indirection that the hand-authored CSS relies on.
+ *     A single-mode `{ literal: string }` mapping (#465) is instead EMITTED
+ *     VERBATIM as the literal CSS value — there is no palette slot to
+ *     reference. A cross-tab/tier `{ ref }` mapping (#468) is resolved via
+ *     `resolveRefToCssVar` against the panel's full `tabs` array and EMITTED
+ *     as `var(--<resolved-target>)`. Per-mode `{ literal: { light, dark } }`
+ *     (#472) is EMITTED as `light-dark(<light>, <dark>)`, byte-identical to
+ *     the DOM emitter (the required `color-scheme: light dark` is NOT settable
+ *     via this pipeline — see the per-mode branch below for why).
  *   - Base roles (`cluster.baseRoles` entries) — NOT emitted. They do not
  *     belong to the apply pipeline's rewrite scope.
  *   - Spacing / typography / size — EMITTED when the corresponding
@@ -68,5 +76,13 @@ import type { TabConfig } from '../tokens/tier-model';
  *
  * `tabs` defaults to the active panel config's tab list. Injected by tests so
  * non-color token resolution works without a live panel config singleton.
+ *
+ * `currentTab` is the color TabConfig `state.color`'s semantic mappings live
+ * on — needed so a cross-tab/tier `{ ref }` mapping (#468) with an omitted
+ * `ref.tab` resolves against the RIGHT tab. Defaults to the `'color'` tab
+ * (primary-cluster behavior, unchanged). Secondary-cluster callers MUST pass
+ * the `'color-secondary'` tab explicitly — mirroring the DOM emitter's
+ * `applyFullState`/`applyColorState` `currentTab` threading
+ * (`state/tweak-state.ts`).
  */
-export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[]): Record<string, string>;
+export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[], currentTab?: TabConfig | undefined): Record<string, string>;

package/dist/apply/tier-resolver.d.ts

@@ -72,3 +72,31 @@ export declare function resolveTierItemValue(tab: TabConfig, tierId: string, ite
  * - Ref     → returns `var(--targetCssVar)` (e.g. `var(--zfb-easing-ease-in)`).
  */
 export declare function emitTierItemCssValue(resolved: ResolvedTierItem): string;
+/**
+ * A `SemanticValue`'s cross-tab ramp reference: names a target ramp item by
+ * `{ tab?, tier, item }`. An omitted `tab` means "the current tab" (intra-tab,
+ * back-compat). Mirrors the `{ ref }` variant of `SemanticValue` in
+ * `tokens/tier-model.ts`.
+ */
+export type CrossTabRef = {
+    tab?: string;
+    tier: string;
+    item: string;
+};
+/**
+ * Resolve a `{ tab?, tier, item }` reference to the target item's `cssVar`
+ * so a downstream emitter (#468) can write `var(--target-cssvar)`.
+ *
+ * Resolution:
+ *   - `tab` omitted (or equal to `currentTab.id`) → resolve within
+ *     `currentTab` (intra-tab; keeps a lone-tab caller working with the
+ *     default `tabs = [currentTab]`).
+ *   - `tab` set → look the target tab up by id in `tabs` (the panel config's
+ *     full tabs array), then find `tier` in it, then `item` in that tier.
+ *
+ * Throws `TierResolverError` with a precise message when the target tab, tier,
+ * or item does not exist. This is the single reachable cross-tab lookup path;
+ * #468 wraps the returned cssVar in `var(...)` and #469 validates source
+ * declarations up front.
+ */
+export declare function resolveRefToCssVar(ref: CrossTabRef, currentTab: TabConfig, tabs?: readonly TabConfig[]): string;

package/dist/astro/host-adapter.js

@@ -1,6 +1,6 @@
-import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-3tBEHjvZ.js";
-import { g as d, Z as b } from "../tweak-state-BEx1SHu7.js";
-import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-B1MWY_Pp.js";
+import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-CXTCcYQs.js";
+import { g as d, Z as b } from "../tweak-state-BeXkzoj8.js";
+import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-CmhI7q9j.js";
 const l = "tokenpanel-config";
 function E() {
   if (typeof document > "u")

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-3tBEHjvZ.js";
+import { s as t } from "../panel-config-CXTCcYQs.js";
 import { c as d } from "../color-schemes-CgzOBqGO.js";
 import { F as r, G as m, a as g, S as z } from "../manifest-DCReQE0k.js";
 const e = {

package/dist/{autoload-state-B1MWY_Pp.js → autoload-state-CmhI7q9j.js}

@@ -1,4 +1,4 @@
-import { g as a, j as o } from "./panel-config-3tBEHjvZ.js";
+import { g as a, j as o } from "./panel-config-CXTCcYQs.js";
 function n(e = a()) {
   return `${e.storagePrefix}-elpath-enabled`;
 }

package/dist/config/cluster-config.d.ts

@@ -21,6 +21,8 @@
  * `panelConfig.colorCluster`.
  */
 import type { ColorScheme } from './color-schemes';
+import type { SemanticValue } from '../tokens/tier-model';
+export type { SemanticValue } from '../tokens/tier-model';
 /**
  * Base-role keys that a cluster may declare. Subset is allowed (a cluster may
  * ship zero base roles when its design system doesn't expose them as tokens).
@@ -76,8 +78,16 @@ export interface ColorClusterDataConfig {
      * `--brand-p{n}`, `--demo-palette-{n}`.
      */
     paletteCssVarTemplate: string;
-    /** Semantic token name → default palette index. */
-    semanticDefaults: Record<string, number>;
+    /**
+     * Semantic token name → default mapping. Historically always a palette
+     * index (`number`); widened to `SemanticValue` (#459) so a default can also
+     * be a literal color or a cross-tab ramp reference. `resolveColorClusterFromTab`
+     * now derives the `{ literal }` / best-effort `{ ref }` variants too (#463)
+     * for a `semantic: true` tier; actually resolving a `{ ref }` against the
+     * ramp tier it names (rendering + apply) is still downstream work
+     * (#467/#469).
+     */
+    semanticDefaults: Record<string, SemanticValue>;
     /** Semantic token name → CSS custom-property name. */
     semanticCssNames: Record<string, string>;
     /** Fallback indices used when a scheme doesn't declare a base role. */
@@ -104,23 +114,36 @@ import type { TabConfig } from '../tokens/tier-model';
 /**
  * Derive a `ColorClusterDataConfig` from a color `TabConfig`.
  *
- * - Palette items: the first tier whose items all have `kind: 'color'`.
- *   Each item's `cssVar` becomes a palette slot; `paletteCssVarTemplate` is
- *   synthesised as `"{item.cssVar}"` with `{n}` replaced by the slot index.
- *   Because item cssVars are explicit (e.g. `--zfb-palette-0`) rather
- *   than template-based, we derive the template from the first item by
- *   replacing the terminal digit sequence with `{n}`.
+ * - Palette items: the first tier whose items all have `kind: 'color'` and
+ *   are not `semantic: true`. Each item's `cssVar` becomes a palette slot;
+ *   `paletteCssVarTemplate` is synthesised as `"{item.cssVar}"` with `{n}`
+ *   replaced by the slot index. Because item cssVars are explicit (e.g.
+ *   `--zfb-palette-0`) rather than template-based, we derive the template
+ *   from the first item by replacing the terminal digit sequence with `{n}`.
  *
- * - Semantic items: the first tier with `referencesTier` set pointing at the
- *   palette tier. Each item's `id` → `cssVar` mapping becomes `semanticCssNames`;
- *   the item's `default` (a palette item id) is looked up to produce the index
- *   for `semanticDefaults`.
+ * - Semantic items: either the first tier with `referencesTier` set pointing
+ *   at the palette tier (legacy shape), or a tier explicitly marked
+ *   `semantic: true` (#461) — the latter may have no palette sibling at all.
+ *   Each item's `id` → `cssVar` mapping becomes `semanticCssNames`; the
+ *   item's `default` is resolved to a `SemanticValue` by
+ *   `deriveSemanticValue` (palette index / literal / ramp-ref — see there).
+ *
+ * - A tab with a semantic tier but NO palette tier still produces a usable
+ *   cluster: `paletteSize` is `0` (the palette-driven UI has nothing to
+ *   render) but `semanticDefaults`/`semanticCssNames` are populated from the
+ *   semantic tier so the Semantic Tokens section isn't left empty (#463).
  *
  * - Metadata comes from `tab.colorExtras` (required on a color tab).
  *
+ * `tabs` is the panel config's full tabs array, used to resolve a semantic
+ * tier's cross-tab `{ ref }` mappings against a ramp tier living in ANOTHER
+ * tab (typically the grouped Palette tab). It defaults to `[tab]` so an
+ * existing single-argument call still works — intra-tab refs resolve, and a
+ * cross-tab ramp declaration falls back to its best-effort shape (#467).
+ *
  * Returns `undefined` when the tab has no `colorExtras` (not a color tab).
  */
-export declare function resolveColorClusterFromTab(tab: TabConfig): ColorClusterDataConfig | undefined;
+export declare function resolveColorClusterFromTab(tab: TabConfig, tabs?: readonly TabConfig[]): ColorClusterDataConfig | undefined;
 /**
  * Find the primary color tab (id 'color') in the host's tabs array and
  * derive its `ColorClusterDataConfig`. Returns `undefined` when no color tab

package/dist/controls/tier-ref-selector.d.ts

@@ -1,38 +1,82 @@
 import type { TabConfig } from '../tokens/tier-model';
 /**
- * Sentinel string passed to `onChange` when the user picks "Literal...".
- * The parent component interprets this as a request to flip the item back
- * into its kind-specific editor (slider / text / select) writing a literal
- * CSS override.
+ * Names one item in a (possibly cross-tab) tier. `tab` omitted means "the tab
+ * `TierRefSelector` itself renders in" — the intra-tab case used by the
+ * font/spacing/size/generic-tab consumers, whose refs never cross tabs.
  */
-export declare const TIER_REF_LITERAL_SIGNAL: "__literal__";
+export interface TierRefTarget {
+    tab?: string;
+    tier: string;
+    item: string;
+}
+/**
+ * The value `TierRefSelector` reads and writes. Mirrors the `{ ref } | {
+ * literal }` variants of `SemanticValue` (`tokens/tier-model.ts`) — including
+ * the per-mode `{ literal: { light, dark } }` shape (#472/#473) — so the
+ * Color tab can pass a semantic mapping straight through. Flat/intra-tab
+ * consumers (font/spacing/size/generic-tab) wrap their bare `TokenOverrides`
+ * string into `{ ref: { tier, item } }` at the call site, and unwrap a
+ * `{ literal }` response back into "drop the override" — see those tabs'
+ * `onChange` handlers. Those flat consumers never produce a per-mode literal.
+ */
+export type TierRefSelectorValue = {
+    ref: TierRefTarget;
+} | {
+    literal: string;
+} | {
+    literal: {
+        light: string;
+        dark: string;
+    };
+};
 export interface TierRefSelectorProps {
-    /** Full tab config — needed to look up the referenced tier and its items. */
+    /** The tab this row belongs to — provides the semantic/reference tier
+     *  config and doubles as the default "current tab" for intra-tab refs. */
     tab: TabConfig;
-    /** The tier whose item is being edited (the "semantic" / reference tier). */
+    /**
+     * Full panel tabs array, needed to resolve a grouped tier's cross-tab ramp
+     * sources. Defaults to `[tab]` — fine for intra-tab (flat) callers, which
+     * never reference another tab.
+     */
+    tabs?: readonly TabConfig[];
+    /** The tier whose item is being edited (the semantic / reference tier). */
     tierId: string;
     /** The item being edited within `tierId`. */
     itemId: string;
+    /** Current value — a ramp/ref target, or a literal color/CSS string. */
+    value: TierRefSelectorValue;
     /**
-     * The current stored value for this item — an item id within the
-     * referenced (tier-1) tier. Empty string or an unrecognised id is treated
-     * as "pick the first item" (mirrors resolver fallback).
+     * Called when the user commits a selection or edits the literal value.
+     *
+     * - Picking a ramp/ref option: `onChange(itemId, { ref: {...} })`
+     * - Picking "Literal…" or editing the literal swatch (grouped mode only):
+     *   `onChange(itemId, { literal: <value> })`
      */
-    value: string;
+    onChange: (itemId: string, next: TierRefSelectorValue) => void;
     /**
-     * Called when the user commits a selection.
-     *
-     * - Picking a tier-1 item: `onChange(itemId, selectedRefItemId)`
-     * - Picking "Literal...": `onChange(itemId, TIER_REF_LITERAL_SIGNAL)`
+     * Returns the resolved (override-aware) preview string for a ramp/ref
+     * target. Each option label is formatted as `${item.cssVar} (${truncated
+     * preview})`. Falls back to the target item's manifest `default` when
+     * omitted.
+     */
+    previewValueFor?: (ref: TierRefTarget) => string;
+    /**
+     * Friendly label used for the literal-mode `ColorField` editor (grouped
+     * mode only) and the select's `aria-label`. Defaults to `itemId`.
+     */
+    label?: string;
+    /**
+     * The row's own cssVar — threaded into the literal-mode `ColorField`
+     * editor for its `aria-label`, matching `SemanticLiteralRow`'s convention.
      */
-    onChange: (itemId: string, next: string) => void;
+    cssVar?: string;
     /**
-     * Returns the resolved (override-aware) preview string for a tier-1 item id.
-     * Each option label is formatted as `${item.cssVar} (${truncated preview})`.
-     * Pass a wrapper around resolveTierItemValue using the current tweak-state map.
+     * The cluster's `getClusterDefaultMode()` result (#472) — used only when
+     * the user collapses a per-mode literal back to single-mode, to pick which
+     * side (`light` or `dark`) survives. Defaults to `'light'`.
      */
-    previewValueFor: (refItemId: string) => string;
+    defaultMode?: 'light' | 'dark';
 }
-declare function TierRefSelector({ tab, tierId, itemId, value, onChange, previewValueFor }: TierRefSelectorProps): import("preact").JSX.Element;
+declare function TierRefSelector({ tab, tabs, tierId, itemId, value, onChange, previewValueFor, label, cssVar, defaultMode, }: TierRefSelectorProps): import("preact").JSX.Element;
 declare const _default: typeof TierRefSelector;
 export default _default;

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export type { TierValueKind, PillSpec, TierItem, TierConfig, TabConfig, ColorClu
 export { isLengthKind, isNumberKind, isSelectKind, isTextKind, isColorKind, isCursorKind, isContentKind, isMaskImageKind, } from './tokens/tier-model';
 export type { TweakState } from './state/tweak-state';
 export { emptyOverrides } from './state/tweak-state';
+export { getClusterDefaultMode, resolvePerModeLiteral, resolveSemanticPreviewColor, } from './state/tweak-state';
 export declare function showDesignTokenPanel(): void;
 export declare function hideDesignTokenPanel(): void;
 export declare function toggleDesignPanel(): void;