@takazudo/zdtp 0.4.2 → 0.4.4

package/dist/controls/dismiss-layer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Dismiss-layer stack — shared Escape arbitration for the panel's layered
+ * popovers (#446).
+ *
+ * Problem it solves
+ * -----------------
+ * The panel stacks several dismissable surfaces on top of each other:
+ * a ColorPicker popover, the HighlightSettingsPopover (which can itself host a
+ * nested ColorPicker), and the PaletteSelector listbox — plus the panel shell
+ * underneath. Each surface used to register its OWN `document` keydown listener
+ * that closed it on Escape. Because they were all bound to `document`, a single
+ * Escape fired EVERY listener at once: the popover closed AND the panel torn
+ * down, and with a nested picker all three layers collapsed on one keypress.
+ *
+ * The fix is a single, shared arbiter. Every dismissable JS-managed popover
+ * registers a layer here instead of adding its own key listener. One
+ * capture-phase `keydown` listener on `document` routes Escape to exactly ONE
+ * layer — the topmost — and marks the event handled via `preventDefault()`.
+ * Base surfaces that keep their own listener (the panel shell) bail when they
+ * see `event.defaultPrevented`, so one Escape never closes two layers.
+ *
+ * Native `<dialog>` modals (Export / Import / Apply) are intentionally NOT
+ * layers here: the browser already gives them their own top-layer Escape
+ * handling. The panel guards against those separately via its modal-open flags.
+ *
+ * Topmost selection
+ * -----------------
+ * "Topmost" is resolved by DOM depth, not registration order: the layer whose
+ * element is the deepest descendant wins (a nested popover's container is a DOM
+ * descendant of its host popover's container). This is robust regardless of the
+ * order in which effects register the layers (child effects run before parent
+ * effects in Preact), which matters for the ColorPicker-inside-
+ * HighlightSettingsPopover case. When elements are unrelated or unavailable it
+ * falls back to the most-recently-registered layer.
+ */
+export interface DismissLayerOptions {
+    /**
+     * Invoked when this layer is the topmost and Escape is pressed. Should close
+     * the layer (and may restore focus to its trigger).
+     */
+    onEscape: () => void;
+    /**
+     * Returns the layer's root element, used to resolve DOM depth when several
+     * layers are open at once. May return null before the element mounts.
+     */
+    getElement: () => HTMLElement | null;
+}
+/**
+ * Register a dismiss layer. Returns an unregister function to call on unmount.
+ */
+export declare function pushDismissLayer(options: DismissLayerOptions): () => void;
+/** Number of currently-registered layers (test/introspection helper). */
+export declare function dismissLayerCount(): number;
+/** Clear all registered layers. Test-only reset between cases. */
+export declare function __resetDismissLayersForTests(): void;

package/dist/controls/pill-slider-row.d.ts

@@ -34,4 +34,3 @@ export interface PillSliderRowProps {
 declare function PillSliderRow({ token, value, onChange }: PillSliderRowProps): import("preact").JSX.Element;
 declare const _default: typeof PillSliderRow;
 export default _default;
-//# sourceMappingURL=pill-slider-row.d.ts.map

package/dist/controls/role-button.d.ts

@@ -15,4 +15,3 @@ export interface RoleButtonProps {
     'aria-label'?: string;
 }
 export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, id, title, 'aria-label': ariaLabel, }: RoleButtonProps): JSX.Element;
-//# sourceMappingURL=role-button.d.ts.map

package/dist/controls/sanitize-css-value.d.ts

@@ -19,4 +19,3 @@
  * guards the **exported** CSS snippet and keeps stored state tidy.
  */
 export declare function sanitizeCssValue(input: string): string;
-//# sourceMappingURL=sanitize-css-value.d.ts.map

package/dist/controls/select-row.d.ts

@@ -23,4 +23,3 @@ export interface SelectRowProps {
 declare function SelectRow({ token, value, onChange }: SelectRowProps): import("preact").JSX.Element;
 declare const _default: typeof SelectRow;
 export default _default;
-//# sourceMappingURL=select-row.d.ts.map

package/dist/controls/slider-row.d.ts

@@ -27,4 +27,3 @@ export interface SliderRowProps {
 declare function SliderRow({ token, value, onChange }: SliderRowProps): import("preact").JSX.Element;
 declare const _default: typeof SliderRow;
 export default _default;
-//# sourceMappingURL=slider-row.d.ts.map

package/dist/controls/text-row.d.ts

@@ -25,4 +25,3 @@ export interface TextRowProps {
 declare function TextRow({ token, value, onChange }: TextRowProps): import("preact").JSX.Element;
 declare const _default: typeof TextRow;
 export default _default;
-//# sourceMappingURL=text-row.d.ts.map

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

@@ -1,39 +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;
-//# sourceMappingURL=tier-ref-selector.d.ts.map

package/dist/controls/token-label.d.ts

@@ -14,4 +14,3 @@ export interface TokenLabelProps {
 declare function TokenLabelInner({ cssVar, label, className }: TokenLabelProps): import("preact").JSX.Element;
 export declare const TokenLabel: typeof TokenLabelInner;
 export default TokenLabel;
-//# sourceMappingURL=token-label.d.ts.map

package/dist/controls/tooltip.d.ts

@@ -41,4 +41,3 @@ export declare function useTooltip(text: string): {
     onFocusOut: JSX.FocusEventHandler<HTMLElement>;
 };
 export {};
-//# sourceMappingURL=tooltip.d.ts.map

package/dist/controls/use-dialog-backdrop-close.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useDialogBackdropClose — gesture-aware backdrop dismissal for native
+ * `<dialog>` modals (#446, finding F14).
+ *
+ * The naive backdrop check tests only the *click* coordinates against the
+ * dialog rect: `if (clientX < rect.left || ...) dialog.close()`. That misfires
+ * on a text-selection drag — when the user presses inside a selectable region
+ * (the export JSON block, the import textarea, the apply preview) and releases
+ * on the backdrop, Chrome synthesizes the `click` on the common ancestor (the
+ * `<dialog>` itself) using the mouseup coordinates, which land outside the rect.
+ * The modal then closes and the user's unsaved input (e.g. pasted JSON) is lost.
+ *
+ * The fix tracks where the gesture STARTED. A backdrop dismissal fires only when
+ * BOTH the mousedown and the click landed outside the dialog's content rect, so
+ * a drag that began inside the dialog never dismisses it.
+ *
+ * This is a hook so the mousedown-origin ref is per-modal-instance; the returned
+ * handlers are spread onto the `<dialog>` element.
+ */
+import type { JSX } from 'preact';
+export interface DialogBackdropHandlers {
+    onMouseDown: (e: JSX.TargetedMouseEvent<HTMLDialogElement>) => void;
+    onClick: (e: JSX.TargetedMouseEvent<HTMLDialogElement>) => void;
+}
+/**
+ * @param dialogRef  ref to the `<dialog>` element.
+ * @param onBackdrop invoked for a genuine backdrop dismissal (a press+release
+ *                   that both land outside the dialog's content rect).
+ */
+export declare function useDialogBackdropClose(dialogRef: {
+    current: HTMLDialogElement | null;
+}, onBackdrop: () => void): DialogBackdropHandlers;

package/dist/element-path/build-element-path.d.ts

@@ -83,4 +83,3 @@ export declare function buildElementPath(el: Element): ElementPathResult;
 export declare function formatElementPath(result: ElementPathResult): string;
 /** Convenience: build + format in one call. */
 export declare function buildElementPathString(el: Element): string;
-//# sourceMappingURL=build-element-path.d.ts.map

package/dist/element-path/element-path-context.d.ts

@@ -15,4 +15,3 @@ export interface ElementPathContextValue {
     toggle: () => void;
 }
 export declare const ElementPathContext: import("preact").Context<ElementPathContextValue | null>;
-//# sourceMappingURL=element-path-context.d.ts.map

package/dist/element-path/element-path-orchestrator.d.ts

@@ -15,4 +15,3 @@ import type { ComponentChildren } from 'preact';
 export declare function ElementPathOrchestrator({ children }: {
     children: ComponentChildren;
 }): import("preact").JSX.Element;
-//# sourceMappingURL=element-path-orchestrator.d.ts.map

package/dist/element-path/element-path-state.d.ts

@@ -18,4 +18,3 @@ import type { PanelConfig } from '../config/panel-config';
 export declare function loadElementPathEnabled(cfg?: PanelConfig): boolean;
 /** Persist the enabled flag to localStorage. Degrades silently when storage is unavailable. */
 export declare function saveElementPathEnabled(enabled: boolean, cfg?: PanelConfig): void;
-//# sourceMappingURL=element-path-state.d.ts.map

package/dist/element-path/element-path-toast.d.ts

@@ -26,4 +26,3 @@ export interface ElementPathToastProps {
     ok: boolean;
 }
 export declare function ElementPathToast({ message, ok }: ElementPathToastProps): JSX.Element | null;
-//# sourceMappingURL=element-path-toast.d.ts.map

package/dist/element-path/element-path-toggle-button.d.ts

@@ -11,4 +11,3 @@
  */
 import type { JSX } from 'preact';
 export declare function ElementPathToggleButton(): JSX.Element | null;
-//# sourceMappingURL=element-path-toggle-button.d.ts.map

package/dist/element-path/index.d.ts

@@ -12,4 +12,3 @@ export type { ElementPathContextValue } from './element-path-context';
 export { buildElementPath, buildElementPathString, formatElementPath, buildUniqueSelector, buildBreadcrumb, } from './build-element-path';
 export type { ElementPathResult } from './build-element-path';
 export { loadElementPathEnabled, saveElementPathEnabled } from './element-path-state';
-//# sourceMappingURL=index.d.ts.map

package/dist/element-path/inspector-overlay.d.ts

@@ -24,4 +24,3 @@ export interface InspectorOverlayProps {
     enabled: boolean;
 }
 export declare function InspectorOverlay({ enabled }: InspectorOverlayProps): JSX.Element | null;
-//# sourceMappingURL=inspector-overlay.d.ts.map

package/dist/export-modal.d.ts

@@ -38,4 +38,3 @@ export interface ExportModalProps {
     instanceConfig?: PanelConfig;
 }
 export declare function ExportModal({ onClose, state, colorDefaults, instanceConfig }: ExportModalProps): import("preact").JSX.Element;
-//# sourceMappingURL=export-modal.d.ts.map

package/dist/highlight/find-elements.d.ts

@@ -126,4 +126,3 @@ export declare const PANEL_EXCLUSION_SELECTOR = ".tokenpanel-shell, [data-design
  *   causing equality mode to miss `font-size` consumers.
  */
 export declare function findElementsUsingToken(cssVar: string, options?: FindElementsOptions): FindElementsResult;
-//# sourceMappingURL=find-elements.d.ts.map

package/dist/highlight/highlight-orchestrator.d.ts

@@ -21,4 +21,3 @@ export declare function HighlightOrchestrator({ children }: {
     children: ComponentChildren;
 }): import("preact").JSX.Element;
 export {};
-//# sourceMappingURL=highlight-orchestrator.d.ts.map

package/dist/highlight/highlight-overlay.d.ts

@@ -40,4 +40,3 @@ export interface HighlightOverlayProps {
     items: ReadonlyArray<HighlightOverlayItem>;
 }
 export declare function HighlightOverlay({ items }: HighlightOverlayProps): JSX.Element | null;
-//# sourceMappingURL=highlight-overlay.d.ts.map

package/dist/highlight/highlight-settings-popover.d.ts

@@ -22,4 +22,3 @@ interface HighlightSettingsPopoverProps {
 }
 export declare function HighlightSettingsPopover({ anchorRef, onClose, }: HighlightSettingsPopoverProps): JSX.Element | null;
 export {};
-//# sourceMappingURL=highlight-settings-popover.d.ts.map

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

@@ -84,4 +84,3 @@ export declare function loadHighlightState(): HighlightState;
  * Gracefully handles environments where storage is unavailable.
  */
 export declare function saveHighlightState(state: HighlightState): void;
-//# sourceMappingURL=highlight-state.d.ts.map

package/dist/highlight/highlight-toggle-button.d.ts

@@ -31,4 +31,3 @@ export interface HighlightToggleButtonProps {
     cssVar: string;
 }
 export declare function HighlightToggleButton({ cssVar }: HighlightToggleButtonProps): JSX.Element | null;
-//# sourceMappingURL=highlight-toggle-button.d.ts.map

package/dist/import-modal.d.ts

@@ -38,4 +38,3 @@ export interface ImportModalProps {
     instanceConfig?: PanelConfig;
 }
 export declare function ImportModal({ onClose, onLoad, colorDefaults, instanceConfig }: ImportModalProps): import("preact").JSX.Element;
-//# sourceMappingURL=import-modal.d.ts.map

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;
@@ -150,4 +151,3 @@ export interface LifecycleAdapter {
  * No-op outside a browser context (SSR-safe).
  */
 export declare function setLifecycleAdapter(adapter: LifecycleAdapter | null): void;
-//# sourceMappingURL=index.d.ts.map