@takazudo/zdtp 0.4.3 → 0.4.4

package/dist/state/persist.d.ts

@@ -11,6 +11,13 @@
  * Framework-agnostic wrt. the setState function: pass any
  * `(updater) => void` that propagates `updater(prev)` to the caller's state.
  * In practice the panel passes Preact's `setState` from `useState`.
+ *
+ * `persistColor`'s updater is `(prev: ColorTweakState) => ColorTweakState`, so
+ * the widened `ColorTweakState.semanticMappings: Record<string, SemanticValue>`
+ * (#459) — including the `{ literal }` / `{ ref }` object variants added for
+ * #462 — already flows through this hook's generic pass-through unchanged; the
+ * actual validating hydrate/round-trip logic for those variants lives in
+ * `tweak-state.ts` (`hydrateSemanticMappings` / `savePersistedState`), not here.
  */
 import { type ColorTweakState, type TabOverrides, type TokenOverrides, type TweakState } from './tweak-state';
 import type { PanelConfig } from '../config/panel-config';

package/dist/state/tweak-state.d.ts

@@ -42,8 +42,11 @@
 import type { ColorRef, ColorScheme } from '../config/color-schemes';
 import type { TokenDef } from '../tokens/manifest';
 import { type ColorClusterDataConfig } from '../config/cluster-config';
+import type { SemanticValue } from '../tokens/tier-model';
+export type { SemanticValue } from '../tokens/tier-model';
 import { type ApplySink, type PanelConfig } from '../config/panel-config';
 export type { ApplySink } from '../config/panel-config';
+import type { TabConfig } from '../tokens/tier-model';
 import { type TabOverrides } from '../apply/tier-resolver';
 export type { BaseRoleKey, ColorClusterDataConfig } from '../config/cluster-config';
 export { resolvePaletteCssVar } from '../config/cluster-config';
@@ -182,9 +185,47 @@ export interface ColorTweakState {
     cursor: number;
     selectionBg: number;
     selectionFg: number;
-    semanticMappings: Record<string, number | 'bg' | 'fg'>;
+    /**
+     * Semantic token name → mapping. Widened from `Record<string, number | 'bg'
+     * | 'fg'>` to `Record<string, SemanticValue>` (#459 S1). This is additive
+     * for readers of the type (every legacy value is still a valid
+     * `SemanticValue`), but it BREAKS any exhaustive `switch`/equality check
+     * written against the old narrow union — callers that pattern-match on a
+     * mapping value must now also handle the new `{ literal }` / `{ ref }`
+     * object variants (see `isIndexMapping` / `isLiteralMapping` /
+     * `isPerModeLiteral` / `isRefMapping` below). `resolveMapping` (exported)
+     * still only resolves the legacy `number | 'bg' | 'fg'` shape — resolving
+     * the new variants is downstream work (#467/#469).
+     */
+    semanticMappings: Record<string, SemanticValue>;
     shikiTheme: string;
 }
+/** True when `v` is a legacy index-style mapping (palette index or bg/fg alias). */
+export declare function isIndexMapping(v: SemanticValue): v is number | 'bg' | 'fg';
+/** True when `v` is either literal-color variant (plain string or light/dark pair). */
+export declare function isLiteralMapping(v: SemanticValue): v is {
+    literal: string;
+} | {
+    literal: {
+        light: string;
+        dark: string;
+    };
+};
+/** True when `v` is specifically the light/dark literal-color variant. */
+export declare function isPerModeLiteral(v: SemanticValue): v is {
+    literal: {
+        light: string;
+        dark: string;
+    };
+};
+/** True when `v` is a cross-tab/tier ramp-item reference. */
+export declare function isRefMapping(v: SemanticValue): v is {
+    ref: {
+        tab?: string;
+        tier: string;
+        item: string;
+    };
+};
 /**
  * Per-token override map. Keys are `TokenDef.id` (e.g. `hsp-sm`); values are
  * raw CSS length strings (e.g. `0.75rem`). Only overridden tokens appear in
@@ -238,6 +279,10 @@ export declare function getActivePrimaryCluster(cfg?: PanelConfig): ColorCluster
  *    slots interpolate. Functional but visually flat; hosts wanting a
  *    designed seed should ship a scheme registry on the cluster and call
  *    `initColorFromScheme(cluster)` instead.
+ *  - A cluster with `paletteSize: 0` (a lone `semantic: true` tier with no
+ *    palette sibling, #458/#466) seeds an EMPTY palette — there is nothing
+ *    to ramp. Forcing a 1-slot grayscale floor here produced a phantom
+ *    `--zudo-stub-p0` swatch/token with no backing tier; see #466.
  *
  * The base-role indices are kept on the state shape for envelope-round-trip
  * compatibility but are inert — `applyColorState` only writes a base role
@@ -331,11 +376,70 @@ export declare function initColorFromScheme(cluster?: ColorClusterDataConfig, cf
  */
 export declare function normalizeSchemePaletteEntry(value: string): string;
 export declare function initColorFromSchemeData(scheme: ColorScheme, cluster?: ColorClusterDataConfig): ColorTweakState;
-/** Resolve a semantic mapping to an actual color (bounds-checked). */
+/**
+ * Resolve a semantic mapping to an actual color (bounds-checked).
+ *
+ * Only handles the legacy `number | 'bg' | 'fg'` index shape — the narrower
+ * type this function accepted before `ColorTweakState.semanticMappings` /
+ * `ColorClusterDataConfig.semanticDefaults` were widened to `SemanticValue`
+ * (#459 S1). Callers holding a `SemanticValue` must narrow with
+ * `isIndexMapping()` first; resolving the `{ literal }` / `{ ref }` variants
+ * is downstream work (#467/#469), not this function's job today.
+ */
 export declare function resolveMapping(mapping: number | 'bg' | 'fg', palette: string[], bgIndex: number, fgIndex: number): string;
 export declare function safeIndex(index: number, len: number): number;
-/** Apply a single `ColorTweakState` to the DOM using the given cluster config. */
-export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink): void;
+/**
+ * The cluster's configured default light/dark mode, or `'light'` when the
+ * cluster declares no `colorMode` (`colorMode === false`).
+ *
+ * This is the single runtime reader of `ClusterPanelSettings.colorMode.defaultMode`
+ * (#472). The field validates but was previously never read at runtime; this
+ * helper (consumed by `resolveSemanticPreviewColor`) gives it a real effect —
+ * it selects which side of a per-mode `{ literal: { light, dark } }` pair is the
+ * fallback when `light-dark()` cannot resolve.
+ */
+export declare function getClusterDefaultMode(cluster: ColorClusterDataConfig): 'light' | 'dark';
+/**
+ * Resolve a per-mode literal to a single concrete CSS color for `mode`.
+ *
+ * Used wherever CSS `light-dark()` cannot be used — a preview swatch, an SSR
+ * seed, or any non-browser consumer that needs one flat value rather than a
+ * `light-dark(...)` function. The emitters (`applyColorState`,
+ * `buildApplyOverrides`) deliberately do NOT call this; they emit
+ * `light-dark()` and let the browser choose.
+ */
+export declare function resolvePerModeLiteral(value: {
+    literal: {
+        light: string;
+        dark: string;
+    };
+}, mode: 'light' | 'dark'): string;
+/**
+ * Resolve a semantic mapping to a single concrete CSS color suitable for a
+ * PREVIEW swatch — a flat value, never a `light-dark()` function. Mirrors the
+ * internal apply-path resolver, except a per-mode `{ literal: { light, dark } }`
+ * value collapses to `getClusterDefaultMode(cluster)`'s side (#472).
+ *
+ * This is the "preview/seed" consumer referenced by #472/#473: the per-mode
+ * editor UI (#473) renders its swatch from this so the user sees the cluster's
+ * default-mode color, while the applied CSS var still emits `light-dark()`.
+ */
+export declare function resolveSemanticPreviewColor(mapping: SemanticValue, state: ColorTweakState, cluster?: ColorClusterDataConfig, currentTab?: TabConfig, tabs?: readonly TabConfig[]): string;
+/**
+ * Apply a single `ColorTweakState` to the DOM using the given cluster config.
+ *
+ * `currentTab` / `tabs` are optional and exist so a cross-tab/tier `{ ref }`
+ * semantic mapping (#468) can resolve: `currentTab` should be the color
+ * TabConfig this cluster was derived from (id `'color'` or
+ * `'color-secondary'`), and `tabs` the panel's full tabs array so a ref
+ * pointing into another tab (e.g. the grouped Palette tab) resolves. Callers
+ * that never hold `{ ref }` mappings (or have no tab context, e.g. most
+ * existing tests) can omit both — `resolveSemanticCssValue` returns `null`
+ * for an unresolvable ref rather than throwing, and this function skips a
+ * `null` (leaving the token at its stylesheet default) rather than painting
+ * a fallback color.
+ */
+export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink, currentTab?: TabConfig, tabs?: readonly TabConfig[]): void;
 /**
  * Apply a `TokenOverrides` map for a given manifest — writes inline
  * `--css-var: value` on `:root` for every overridden token, and removes the
@@ -357,6 +461,15 @@ export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrid
  * When `cfg` is supplied its `applySink` (if any) is used to route all
  * CSS-var writes for this instance. Omitting `cfg` uses the default active
  * config (single-panel path, unchanged behavior).
+ *
+ * `color-scheme` is managed as an AGGREGATE across the primary + secondary
+ * clusters, not per-cluster (#482 D3): `applyColorState` only ever SETS
+ * `color-scheme: light dark` when its OWN cluster needs it, it never clears
+ * it, so demoting the last per-mode-literal row (in either cluster) would
+ * otherwise leave the previous apply's value stale. A naive per-cluster
+ * clear inside `applyColorState` would let a per-mode-free secondary undo
+ * what the primary just required (or vice versa), so the clear-when-neither-
+ * needs-it decision is made here, once, after both clusters have applied.
  */
 export declare function applyFullState(state: TweakState, cfg?: PanelConfig): void;
 /**

package/dist/tabs/color-tab.d.ts

@@ -35,6 +35,7 @@
  * in the panel.
  */
 import { type ColorTweakState } from '../state/tweak-state';
+import { type PanelConfig } from '../config/panel-config';
 import type { TabConfig } from '../tokens/tier-model';
 import type { PersistColor, PersistSecondary } from '../state/persist';
 interface ColorTabProps {
@@ -52,6 +53,17 @@ interface ColorTabProps {
     secondaryTab: TabConfig | null;
     secondaryState: ColorTweakState | null;
     persistSecondary: PersistSecondary;
+    /**
+     * The mounted panel instance's config (multi-instance, #353/#357). When
+     * supplied, cross-tab cluster/ref resolution (cluster derivation, the
+     * grouped ref-or-literal picker's ramp groups, preview resolution, and the
+     * host preset list) reads THIS instance's `tabs` / `colorPresets` rather
+     * than the active default instance — matching the apply path, which
+     * already resolves against `cfg.tabs` via `usePersist` (`applyFullState`,
+     * `state/persist.ts`). Omitted (e.g. a direct test render) →
+     * `getPanelConfig()`, preserving the single-instance path.
+     */
+    instanceConfig?: PanelConfig;
 }
-export default function ColorTab({ tab, state, persistColor, secondaryTab, secondaryState, persistSecondary, }: ColorTabProps): import("preact").JSX.Element;
+export default function ColorTab({ tab, state, persistColor, secondaryTab, secondaryState, persistSecondary, instanceConfig, }: ColorTabProps): import("preact").JSX.Element;
 export {};

package/dist/tabs/generic-tab.d.ts

@@ -28,8 +28,10 @@ export interface GenericTabProps {
      * When an item has no override, its `TierItem.default` is used.
      */
     overrides: TabOverrides;
-    /** Called when the user commits a change to any item. */
-    onChange: (tierId: string, itemId: string, next: string) => void;
+    /** Called when the user commits a change to any item. `next: undefined`
+     *  (only reachable for ref-tier items) means "drop the stored override for
+     *  this item" rather than writing a literal value. */
+    onChange: (tierId: string, itemId: string, next: string | undefined) => void;
 }
 /**
  * Renders a non-reserved tab (any TabConfig whose id is not color/font/

package/dist/testing.js

@@ -1,5 +1,5 @@
-import { _ as r, c as i, f as _, h as n, i as g, b as R, a as p } from "./panel-config-3tBEHjvZ.js";
-import { a as l, b as y, l as O } from "./tweak-state-BEx1SHu7.js";
+import { _ as r, c as i, f as _, h as n, i as g, b as R, a as p } from "./panel-config-CXTCcYQs.js";
+import { a as l, b as y, l as O } from "./tweak-state-BeXkzoj8.js";
 import { F as K, G as E, a as S, S as u } from "./manifest-DCReQE0k.js";
 async function s(a, e) {
   await a.fill(e), await a.dispatchEvent("input");

package/dist/tokens/tier-model.d.ts

@@ -56,6 +56,33 @@ export interface PillSpec {
     value: string;
     customDefault: string;
 }
+/**
+ * A semantic token's mapping value.
+ *
+ * Legacy shape stays valid: a palette index (`number`) or the `'bg'` / `'fg'`
+ * sentinel aliases. New variants (added for #459) let a semantic tier point at
+ * an arbitrary literal color (optionally split light/dark) or reference a ramp
+ * item living in another tab/tier — both resolved downstream by #467/#469.
+ *
+ * Defined here (not in `state/tweak-state.ts`) because `config/cluster-config.ts`
+ * needs it for `ColorClusterDataConfig.semanticDefaults`, and cluster-config.ts
+ * already imports types from this module — keeping the definition here avoids
+ * a new type-only import cycle. `state/tweak-state.ts` re-exports it.
+ */
+export type SemanticValue = number | 'bg' | 'fg' | {
+    literal: string;
+} | {
+    literal: {
+        light: string;
+        dark: string;
+    };
+} | {
+    ref: {
+        tab?: string;
+        tier: string;
+        item: string;
+    };
+};
 export interface TierItem {
     id: string;
     cssVar: string;
@@ -73,6 +100,29 @@ export interface TierConfig {
      *  an item in the tier whose id matches referencesTier. The apply pipeline
      *  emits var(--tier1-cssvar). */
     referencesTier?: string;
+    /**
+     * Marks this tier as a SEMANTIC tier (its items hold `SemanticValue`
+     * mappings, not raw palette entries) so the panel never mistakes it for
+     * the palette tier. Optional and additive — omitting it preserves today's
+     * behavior (palette-tier detection stays structural, via
+     * `resolveColorClusterFromTab`'s `kind: 'color'` check).
+     */
+    semantic?: true;
+    /**
+     * Cross-tab ramp-source declaration for a semantic tier: the ramp tier(s)
+     * this tier's `{ ref }` mappings are allowed to point into. Each entry names
+     * a tier id and an optional tab id (omitted `tab` means "this tab").
+     * `assertValidPanelConfig` validates every declared source up front (the
+     * tab/tier must exist and share this tier's kind); `resolveColorClusterFromTab`
+     * (`config/cluster-config.ts`) uses the allow-list to derive each row's
+     * `SemanticValue`; the grouped `TierRefSelector` picker
+     * (`controls/tier-ref-selector.tsx`) renders one `<optgroup>` per declared
+     * source.
+     */
+    referencesRamps?: readonly {
+        tab?: string;
+        tier: string;
+    }[];
 }
 export interface ColorClusterExtras {
     id: string;