@takazudo/zdtp 0.4.13 → 0.4.15

package/dist/controls/actions-menu-popover.d.ts

@@ -13,6 +13,8 @@ import type { ComponentChildren, JSX } from 'preact';
 export interface ActionsMenuAction {
     label: string;
     onSelect: () => void;
+    disabled?: boolean;
+    disabledReason?: string;
 }
 interface ActionsMenuPopoverProps {
     /** The kebab trigger element — excluded from the outside-click close so its

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

@@ -1,4 +1,4 @@
-import type { JSX } from 'preact';
+import type { JSX, Ref } from 'preact';
 export interface RoleButtonProps {
     children: JSX.Element | JSX.Element[] | string;
     onClick: (e: MouseEvent | KeyboardEvent) => void;
@@ -10,8 +10,11 @@ export interface RoleButtonProps {
     /** Arbitrary extra aria-* props (e.g. aria-haspopup, aria-expanded). */
     ariaProps?: Record<string, string | boolean | undefined>;
     tabIndex?: number;
+    /** Explicit DOM ref for callers that need to anchor a popover. */
+    elementRef?: Ref<HTMLDivElement>;
     id?: string;
     title?: string;
     'aria-label'?: string;
+    'data-testid'?: string;
 }
-export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, id, title, 'aria-label': ariaLabel, }: RoleButtonProps): JSX.Element;
+export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, elementRef, id, title, 'aria-label': ariaLabel, 'data-testid': testId, }: RoleButtonProps): JSX.Element;

package/dist/controls/tooltip.d.ts

@@ -19,10 +19,12 @@ import type { ComponentChildren, JSX } from 'preact';
 /**
  * Opt-in tooltip presentation variant. `'help'` applies the wrapped,
  * bounded-width `.tokenpanel-tooltip--help` class (see panel.css) instead of
- * the default single-line `nowrap` tooltip — used by `controls/help-icon.tsx`
+ * the default token tooltip — used by `controls/help-icon.tsx`
  * for the multi-sentence Literal / Per-mode explainer tips.
  */
 export type TooltipVariant = 'help';
+/** Opt-in horizontal anchor for triggers whose box is wider than its text. */
+export type TooltipAnchor = 'text';
 interface TooltipProviderProps {
     children: ComponentChildren;
 }
@@ -35,15 +37,17 @@ interface TooltipProviderProps {
  */
 export declare function TooltipProvider({ children }: TooltipProviderProps): JSX.Element;
 export interface UseTooltipOptions {
-    /** Opt into a presentation variant — see `TooltipVariant` above. Omit for
-     *  the default single-line `nowrap` tooltip. */
+    /** Opt into a presentation variant — see `TooltipVariant` above. */
     variant?: TooltipVariant;
+    /** Opt into horizontal centering over the trigger's displayed text area. */
+    anchor?: TooltipAnchor;
 }
 /**
  * Returns event handler props to spread onto the tooltip trigger element.
  *
  * @param text - The full text to show in the tooltip.
- * @param opts - Optional presentation variant (see `UseTooltipOptions`).
+ * @param opts - Optional presentation variant and horizontal anchor (see
+ *               `UseTooltipOptions`).
  * @returns An object of `onMouseEnter`, `onMouseLeave`, `onFocusIn`, `onFocusOut`
  *          handlers to spread onto the trigger element, plus imperative
  *          `show`/`hide` escape hatches for callers that need to

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

@@ -0,0 +1,22 @@
+import type { FindTokensForElementResult } from './find-tokens-for-element';
+/** The synthetic tab id used by the transient element-inspect view. */
+export declare const ELEMENT_INSPECT_TAB_ID = "inspect";
+export interface ElementInspectContextValue {
+    /** Whether the picker is armed by the header toggle or the `I` shortcut. */
+    armed: boolean;
+    /** The page element currently pinned for inspection. */
+    pinned: Element | null;
+    /** Scanner output for the pinned element. */
+    result: FindTokensForElementResult | null;
+    /** Arm the picker programmatically. */
+    arm: () => void;
+    /** Disarm the picker without clearing the pinned element. */
+    disarm: () => void;
+    /** Toggle picker arming. */
+    toggle: () => void;
+    /** Pin a host element and refresh its token scan. */
+    pin: (element: Element) => void;
+    /** Clear the pinned element and return to the tab that preceded Inspect. */
+    clear: () => void;
+}
+export declare const ElementInspectContext: import("preact").Context<ElementInspectContextValue | null>;

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

@@ -0,0 +1,17 @@
+import type { ComponentChildren } from 'preact';
+import type { PanelConfig } from '../config/panel-config';
+import type { TweakState } from '../state/tweak-state';
+import type { CommitTweakStateOptions, TweakStateUpdater } from '../state/transaction';
+type CommitTweakState = (reason: string, next: TweakStateUpdater, options?: CommitTweakStateOptions) => void;
+export interface ElementInspectOrchestratorProps {
+    children: ComponentChildren;
+    instanceConfig: PanelConfig;
+    state: TweakState | null;
+    commitTweakState: CommitTweakState;
+    onInspectTabOpen: () => void;
+    onInspectTabClear: () => void;
+    onJumpToColorTab?: () => void;
+    panelOpen?: boolean;
+}
+export declare function ElementInspectOrchestrator({ children, instanceConfig, state, commitTweakState, onInspectTabOpen, onInspectTabClear, onJumpToColorTab, panelOpen, }: ElementInspectOrchestratorProps): import("preact").JSX.Element;
+export {};

package/dist/element-inspect/element-inspect-overlay.d.ts

@@ -0,0 +1,16 @@
+import type { JSX } from 'preact';
+/** Body-level mount used by the picker and the pinned inspect marker. */
+export { ELEMENT_INSPECT_PORTAL_MOUNT_ID } from '../highlight/find-elements';
+/** Class hooks shared by the hover picker and the pinned overlay. */
+export declare const ELEMENT_INSPECT_PICKER_CLASS_NAMES: {
+    readonly box: "tokenpanel-element-inspect-box";
+    readonly label: "tokenpanel-element-inspect-label";
+    readonly labelName: "tokenpanel-element-inspect-label-name";
+    readonly labelSize: "tokenpanel-element-inspect-label-size";
+    readonly inspectingRoot: "tokenpanel-element-inspect-inspecting";
+};
+export interface ElementInspectOverlayProps {
+    pinned: Element | null;
+    onPinnedDetached?: () => void;
+}
+export declare function ElementInspectOverlay({ pinned, onPinnedDetached, }: ElementInspectOverlayProps): JSX.Element | null;

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

@@ -0,0 +1,3 @@
+import type { JSX } from 'preact';
+/** Header control for the element → tokens picker. */
+export declare function ElementInspectToggleButton(): JSX.Element | null;

package/dist/element-inspect/element-inspect-view.d.ts

@@ -0,0 +1,6 @@
+import type { JSX } from 'preact';
+export interface ElementInspectViewProps {
+    /** Invoked when the Color-tab jump link is selected. */
+    onJumpToColorTab: () => void;
+}
+export declare function ElementInspectView({ onJumpToColorTab }: ElementInspectViewProps): JSX.Element;

package/dist/element-inspect/find-tokens-for-element.d.ts

@@ -0,0 +1,23 @@
+import type { TokenAddress, TokenIndex, TokenIndexEntry } from '../utils/token-index';
+export interface ElementTokenMatch {
+    property: string;
+    cssVar: string;
+    expression: string;
+    selector: string;
+    addresses: readonly TokenAddress[];
+    kind: TokenIndexEntry['kind'];
+    changedProperties: readonly string[];
+    confirmed: boolean;
+    inheritedFrom?: Element;
+}
+export interface ElementTokenPropertyGroup {
+    property: string;
+    matches: readonly ElementTokenMatch[];
+}
+export interface FindTokensForElementResult {
+    own: readonly ElementTokenPropertyGroup[];
+    inherited: readonly ElementTokenPropertyGroup[];
+    warnings: readonly string[];
+}
+/** Find manifest-backed token declarations applying to one element. */
+export declare function findTokensForElement(el: Element, index: TokenIndex): FindTokensForElementResult;

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

@@ -0,0 +1,8 @@
+export { findTokensForElement } from './find-tokens-for-element';
+export type { ElementTokenMatch, ElementTokenPropertyGroup, FindTokensForElementResult, } from './find-tokens-for-element';
+export { ElementInspectOrchestrator, type ElementInspectOrchestratorProps, } from './element-inspect-orchestrator';
+export { ElementInspectOverlay, ELEMENT_INSPECT_PORTAL_MOUNT_ID } from './element-inspect-overlay';
+export { ElementInspectToggleButton } from './element-inspect-toggle-button';
+export { ElementInspectView, type ElementInspectViewProps } from './element-inspect-view';
+export { ElementInspectContext, ELEMENT_INSPECT_TAB_ID, } from './element-inspect-context';
+export type { ElementInspectContextValue } from './element-inspect-context';

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

@@ -66,6 +66,7 @@ export interface FindElementsOptions {
      */
     mode?: 'equality' | 'differential';
 }
+export type ProbeTokenKind = NonNullable<FindElementsOptions['kind']> | 'select';
 /**
  * Ids of the singleton portal-mount `<div>`s each overlay appends to
  * document.body. Single source of truth: the orchestrators pass these to
@@ -76,13 +77,23 @@ export interface FindElementsOptions {
 export declare const HIGHLIGHT_PORTAL_MOUNT_ID = "tokenpanel-highlight-mount";
 export declare const ELPATH_PORTAL_MOUNT_ID = "tokenpanel-elpath-mount";
 export declare const DOM_TWEAKER_PORTAL_MOUNT_ID = "tokenpanel-domtweaker-mount";
+export declare const ELEMENT_INSPECT_PORTAL_MOUNT_ID = "tokenpanel-element-inspect-mount";
+/** Attribute on the host-document font specimen portal mount. */
+export declare const ON_PAGE_SPECIMEN_SELECTOR = "[data-zdtp-specimen]";
 /**
  * Selector matching every panel-owned surface that must NEVER be treated as a
- * host element (the shell, modals, and the highlight/element-path/dom-tweaker
- * portal mounts). Exported so picker features can skip the same surfaces when
+ * host element (the shell, modals, and the highlight/chain/element-path/
+ * dom-tweaker portal mounts, including element inspect and the on-page
+ * specimen). Exported so picker features can skip the same surfaces when
  * resolving the element under the cursor.
  */
-export declare const PANEL_EXCLUSION_SELECTOR = ".tokenpanel-shell, [data-design-token-panel-modal], #tokenpanel-highlight-mount, #tokenpanel-elpath-mount, #tokenpanel-domtweaker-mount";
+export declare const PANEL_EXCLUSION_SELECTOR = ".tokenpanel-shell, [data-design-token-panel-modal], .tokenpanel-chain-popover, #tokenpanel-highlight-mount, #tokenpanel-elpath-mount, #tokenpanel-domtweaker-mount, #tokenpanel-element-inspect-mount, [data-zdtp-specimen]";
+/**
+ * Differentially probe one element and report the computed properties that
+ * actually respond to a token. Unlike the whole-document finder, this keeps
+ * property identity so callers can reject losing declarations independently.
+ */
+export declare function probeElementForToken(el: Element, cssVar: string, kind: ProbeTokenKind): string[];
 /**
  * Find all DOM elements whose computed style reflects the given CSS custom
  * property.

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

@@ -14,10 +14,14 @@
  * overlay persists even when the panel is closed.
  */
 import type { ComponentChildren } from 'preact';
+import { type PanelConfig } from '../config/panel-config';
 import type { TierValueKind } from '../tokens/tier-model';
 type ProbeKind = 'color' | 'length' | 'number' | 'text' | 'easing' | 'cursor' | 'content' | 'mask-image';
 export declare function tierKindToProbeKind(t: TierValueKind | undefined): ProbeKind | undefined;
-export declare function HighlightOrchestrator({ children }: {
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+export interface HighlightOrchestratorProps {
+    children?: ComponentChildren;
+    /** Config for the mounted panel instance; omitted for the default path. */
+    instanceConfig?: PanelConfig;
+}
+export declare function HighlightOrchestrator({ children, instanceConfig: instanceConfigProp, }: HighlightOrchestratorProps): import("preact").JSX.Element;
 export {};

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

@@ -14,6 +14,7 @@
  *   outlineWidth → localStorage  (survives full page reload — user width setting kept)
  *   active       → sessionStorage (cleared on reload — inspection set is ephemeral)
  */
+import { type PanelConfig } from '../config/panel-config';
 export interface HighlightSlotSpec {
     color: string;
 }
@@ -73,7 +74,7 @@ export declare function setOutlineWidth(state: HighlightState, width: number): H
  * Migration: existing localStorage `slots` arrays may carry a per-slot
  * `outlineWidth` field — the extra field is simply ignored on load.
  */
-export declare function loadHighlightState(): HighlightState;
+export declare function loadHighlightState(cfg?: PanelConfig): HighlightState;
 /**
  * Persist highlight state to the split storage backends.
  *
@@ -83,4 +84,4 @@ export declare function loadHighlightState(): HighlightState;
  *
  * Gracefully handles environments where storage is unavailable.
  */
-export declare function saveHighlightState(state: HighlightState): void;
+export declare function saveHighlightState(state: HighlightState, cfg?: PanelConfig): void;

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

@@ -12,11 +12,14 @@
  */
 import type { JSX } from 'preact';
 import type { HighlightState, HighlightSlotSpec } from './highlight-state';
+import type { TokenAddress } from '../utils/token-index';
 export interface HighlightContextValue {
     state: HighlightState;
     toggle: (cssVar: string) => void;
     /** Optional — when the orchestrator computes match counts it injects them here for title attributes. */
     matchCounts?: Record<string, number>;
+    /** Lazily probe and cache the number of page elements using one token address. */
+    requestMatchCount?: (address: TokenAddress) => number | undefined;
     /** Optional — orchestrator may expose setSlot for slot colour editing. */
     setSlot?: (index: number, partial: Partial<HighlightSlotSpec>) => void;
     /** Optional — orchestrator may expose setOutlineWidth for global outline width editing. */

package/dist/highlight/walk-css-rules.d.ts

@@ -0,0 +1,2 @@
+/** Walk style rules recursively through grouping rules and CSS nesting. */
+export declare function walkCssRules(rules: CSSRuleList | Iterable<CSSRule>, visit: (rule: CSSStyleRule) => void): void;

package/dist/history/buttons.d.ts

@@ -0,0 +1,28 @@
+import type { TweakHistorySnapshot } from '../state/history';
+export interface HistoryButtonProps {
+    canUndo: boolean;
+    onUndo: () => void;
+}
+/** Undo control shared by the header cluster and the mini pill slot. */
+export declare function HistoryUndoButton({ canUndo, onUndo }: HistoryButtonProps): import("preact").JSX.Element;
+export declare function HistoryRedoButton({ canRedo, onRedo }: {
+    canRedo: boolean;
+    onRedo: () => void;
+}): import("preact").JSX.Element;
+export interface HistoryButtonsProps {
+    history: TweakHistorySnapshot;
+    railOpen: boolean;
+    onUndo: () => void;
+    onRedo: () => void;
+    onToggleRail: () => void;
+}
+/** Register the header right-cluster undo/redo/count/rail controls through S18. */
+export declare function HistoryButtons({ history, railOpen, onUndo, onRedo, onToggleRail, }: HistoryButtonsProps): null;
+export interface HistoryShortcutsProps {
+    enabled: boolean;
+    onUndo: () => void;
+    onRedo: () => void;
+    onFlipSnapshots: () => void;
+}
+/** Register keyboard commands with S18's active-shell dispatcher. */
+export declare function HistoryShortcuts({ enabled, onUndo, onRedo, onFlipSnapshots, }: HistoryShortcutsProps): null;

package/dist/history/index.d.ts

@@ -0,0 +1,3 @@
+export { HistoryButtons, HistoryRedoButton, HistoryShortcuts, HistoryUndoButton, type HistoryButtonProps, type HistoryButtonsProps, type HistoryShortcutsProps, } from './buttons';
+export { HistoryRail, type HistoryRailProps } from './rail';
+export { clearSnapshots, getSnapshotKey, isSnapshotState, loadSnapshot, loadSnapshots, removeSnapshot, restoreSnapshotState, saveSnapshot, storageKey_snapshotA, storageKey_snapshotB, useSnapshots, type SnapshotRestoreResult, type SnapshotSlot, type SnapshotSlots, type TweakSnapshot, } from './snapshots';

package/dist/history/rail.d.ts

@@ -0,0 +1,13 @@
+import type { TweakHistorySnapshot } from '../state/history';
+import type { SnapshotSlot, SnapshotSlots } from './snapshots';
+export interface HistoryRailProps {
+    history: TweakHistorySnapshot;
+    snapshots: SnapshotSlots;
+    selectedSnapshot: SnapshotSlot | null;
+    notice?: string | null;
+    activeIdentity: string;
+    onSaveSnapshot: (slot: SnapshotSlot) => void;
+    onSelectSnapshot: (slot: SnapshotSlot) => void;
+    onJumpTo: (index: number) => void;
+}
+export declare function HistoryRail({ history, snapshots, selectedSnapshot, notice, activeIdentity, onSaveSnapshot, onSelectSnapshot, onJumpTo, }: HistoryRailProps): import("preact").JSX.Element;

package/dist/history/snapshots.d.ts

@@ -0,0 +1,57 @@
+import { storageKey_snapshotA, storageKey_snapshotB, type PanelConfig } from '../config/panel-config';
+import type { TweakState } from '../state/tweak-state';
+export type SnapshotSlot = 'A' | 'B';
+export interface TweakSnapshot {
+    state: TweakState;
+    identity: string;
+    savedAt: number;
+    edits: number;
+}
+export interface SnapshotSlots {
+    A: TweakSnapshot | null;
+    B: TweakSnapshot | null;
+}
+export interface SnapshotRestoreResult {
+    state: TweakState;
+    skippedReason?: string;
+}
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Snapshot payloads are user-editable localStorage data. Keep malformed blobs
+ * from reaching the apply pipeline while allowing additive state slices to
+ * round-trip as the runtime model evolves.
+ */
+export declare function isSnapshotState(value: unknown): value is TweakState;
+/** Return the exact per-instance storage key for a snapshot slot. */
+export declare function getSnapshotKey(slot: SnapshotSlot, cfg: PanelConfig): string;
+/** Read one validated snapshot. Invalid or unavailable storage is treated as empty. */
+export declare function loadSnapshot(slot: SnapshotSlot, cfg: PanelConfig, storage?: StorageLike): TweakSnapshot | null;
+/** Read both A/B slots for one panel instance. */
+export declare function loadSnapshots(cfg: PanelConfig, storage?: StorageLike): SnapshotSlots;
+/** Persist one snapshot slot under `${storagePrefix}-snapshot-a|b`. */
+export declare function saveSnapshot(slot: SnapshotSlot, snapshot: TweakSnapshot, cfg: PanelConfig, storage?: StorageLike): void;
+/** Remove one snapshot slot. */
+export declare function removeSnapshot(slot: SnapshotSlot, cfg: PanelConfig, storage?: StorageLike): void;
+/** Remove both persisted snapshot slots for one panel instance. */
+export declare function clearSnapshots(cfg: PanelConfig, storage?: StorageLike): void;
+/**
+ * Keep color slices tied to the active scheme/mode identity when restoring an
+ * A/B snapshot captured under another identity. Non-color slices remain fully
+ * restorable, including host-coined tab overrides.
+ */
+export declare function restoreSnapshotState(snapshot: TweakSnapshot, current: TweakState, activeIdentity: string, slot?: SnapshotSlot): SnapshotRestoreResult;
+/**
+ * Reactive per-instance snapshot store used by the panel. Selection itself is
+ * intentionally kept by the caller as transient UI state; only A/B payloads
+ * are persisted.
+ */
+export declare function useSnapshots(cfg: PanelConfig): {
+    snapshots: SnapshotSlots;
+    save: (slot: SnapshotSlot, state: TweakState, identity: string, edits: number) => TweakSnapshot;
+    remove: (slot: SnapshotSlot) => void;
+};
+export { storageKey_snapshotA, storageKey_snapshotB };

package/dist/host/host-mutations.d.ts

@@ -0,0 +1,23 @@
+export type DockEdge = 'right' | 'bottom';
+export type DockReflow = 'body-margin' | 'none';
+/**
+ * Claim one host-document dock edge. Returns false when another panel owns it.
+ * Re-claiming the same edge by the same owner updates its size without losing
+ * the declaration snapshot captured by the first claim.
+ */
+export declare function claimHostDock(owner: string, edge: DockEdge, size: number, reflow?: DockReflow, doc?: Document): boolean;
+/**
+ * Claim a host-owned DOM node for one panel owner.
+ *
+ * The node is removed when `releaseHostMutations(owner)` runs.  Keeping this
+ * ownership in the same window-level registry as dock declarations makes the
+ * cleanup path robust when a panel is destroyed or an Astro swap removes the
+ * Preact root before effect cleanups get a chance to run.  Claims are keyed by
+ * owner, rather than by node identity, so a single owner can safely recreate
+ * its portal during a navigation.
+ */
+export declare function claimHostNode(owner: string, node: Element, doc?: Document): void;
+/** Release every edge and host node owned by one panel and restore exact values. */
+export declare function releaseHostMutations(owner: string, targetWindow?: Window): void;
+/** Test-only reset that also restores outstanding declarations. */
+export declare function __resetHostMutationsForTests(targetWindow?: Window): void;