@takazudo/zdtp 0.4.3 → 0.4.5

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

@@ -86,7 +86,12 @@ export interface PanelConfig {
     consoleNamespace: string;
     /** BEM-style prefix used by every modal in the panel (export / import / apply). */
     modalClassPrefix: string;
-    /** `$schema` value emitted into export JSON and required on import. */
+    /**
+     * Schema label surfaced in the Import modal's hint/placeholder/error text
+     * and the Export modal's copy. NOT enforced: `serialize()`/`deserialize()`
+     * always use the fixed `SCHEMA_V1`/`SCHEMA_V2`/`SCHEMA_V3` constants
+     * regardless of this value (#498).
+     */
     schemaId: string;
     /** Default filename base — exports save as `${exportFilenameBase}.json`. */
     exportFilenameBase: string;
@@ -364,6 +369,24 @@ export declare function getPanelConfigByPrefix(prefix: string): PanelConfig | nu
  * instance, parked presets, and parked pre-configure hooks.
  */
 export declare function __resetPanelConfigForTests(): void;
+/**
+ * #501 — record that the panel instance keyed by `prefix` wrote `color-scheme`
+ * to its apply target. Called from the apply path (`applyColorState`) wherever
+ * a per-mode literal forces `color-scheme: light dark`.
+ */
+export declare function markColorSchemeWritten(prefix: string): void;
+/**
+ * #501 — drop the color-scheme ownership claim for `prefix`. Called from the
+ * clear paths after a panel-written `color-scheme` is removed (or found to have
+ * been overwritten by the host — the stale-ownership case).
+ */
+export declare function clearColorSchemeOwnership(prefix: string): void;
+/**
+ * #501 — true when the panel instance keyed by `prefix` is the recorded writer
+ * of the current inline `color-scheme`. Gates the clear paths so the panel
+ * never removes a `color-scheme` it did not write.
+ */
+export declare function ownsColorScheme(prefix: string): boolean;
 export { resolvePrimaryColorCluster, resolveSecondaryColorClusterFromTabs, } from './cluster-config';
 import type { ColorClusterDataConfig } from './cluster-config';
 /**
@@ -391,6 +414,18 @@ export declare function storageKey_stateV2(cfg: PanelConfig): string;
  * this key, then deletes the v2 key.
  */
 export declare function storageKey_stateV3(cfg: PanelConfig): string;
+/**
+ * Storage key for the v4 unified envelope. Upgrades the "global tweak model" to
+ * per-scheme color persistence (#500/#509): the `color` and `secondary` slices
+ * become identity-keyed sub-objects (one slot per resolved scheme/mode), so a
+ * per-scheme color tweak survives a scheme toggle round-trip instead of being
+ * clobbered by the next unrelated edit. Non-color slices stay global. Kept a
+ * SINGLE storage key (not one key per scheme) because the Astro bootstrap must
+ * existence-check persistence before cluster config loads — a per-scheme key
+ * would hit a chicken-and-egg there. v1/v2/v3 migrate into this key on first
+ * load; v4 takes precedence on every subsequent load.
+ */
+export declare function storageKey_stateV4(cfg: PanelConfig): string;
 /** Legacy v1 key (Color-only flat state). Migrated into v2 on first load, then deleted. */
 export declare function storageKey_stateV1(cfg: PanelConfig): string;
 /** Mirror of the panel's `open` boolean (synchronous mount-time read). */

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/export-modal.d.ts

@@ -1,8 +1,10 @@
 /**
  * Export modal — renders the current `TweakState` as a design-tokens JSON
- * document (default schema: `zudo-design-tokens/v1`; configurable via
- * `panelConfig.schemaId`) with a diff-only toggle and a copy-to-clipboard
- * button.
+ * document (`serialize()` emits `SCHEMA_V2` or opportunistically `SCHEMA_V3`
+ * — see `./utils/design-token-serde`; `panelConfig.schemaId` is not read
+ * here or anywhere else in this package — it is a UI-label-only field on
+ * `PanelConfig` that hosts may read via `getDesignTokenSchema()`, #498) with
+ * a diff-only toggle and a copy-to-clipboard button.
  *
  * Ported verbatim from zudo-doc's
  * `src/components/design-token-tweak/export-modal.tsx`. Intentional deltas:

package/dist/import-modal.d.ts

@@ -1,16 +1,16 @@
 /**
- * Import modal — accepts a pasted design-tokens JSON document (default schema:
- * `zudo-design-tokens/v1`; configurable via `panelConfig.schemaId`) and lifts
- * it into a `TweakState` via `deserialize()`. Validation and unknown-token
- * reporting are delegated to serde; this component only renders status
- * feedback and routes the parsed state up to the shell.
+ * 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.
  *
  * Ported verbatim from zudo-doc's
  * `src/components/design-token-tweak/import-modal.tsx`. Intentional deltas:
- *  - `deserialize` / `DesignTokenSchemaError` / `getDesignTokenSchema` come
- *    from this package's serde (`./utils/design-token-serde`); the schema
- *    id is read at render time from `panelConfig.schemaId` instead of
- *    being a module-level constant.
+ *  - `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.

package/dist/index.d.ts

@@ -60,6 +60,8 @@ 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 { SCHEMA_V1, SCHEMA_V2, SCHEMA_V3, } from './utils/design-token-serde';
+export { getClusterDefaultMode, resolvePerModeLiteral, resolveSemanticPreviewColor, } from './state/tweak-state';
 export declare function showDesignTokenPanel(): void;
 export declare function hideDesignTokenPanel(): void;
 export declare function toggleDesignPanel(): void;