@takazudo/zdtp 0.4.4 → 0.4.6

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). */
@@ -455,6 +490,38 @@ export declare function openStateChangedEventName(cfg: PanelConfig): string;
 export declare function modalClass(cfg: PanelConfig, suffix: string): string;
 /** Default download filename for export. */
 export declare function exportFilename(cfg: PanelConfig): string;
+/** Shape of the fixed-name global alias installed at `window.zdtp`. */
+export interface ZdtpGlobalApi {
+    show: () => void | Promise<void>;
+    hide: () => void | Promise<void>;
+    toggle: () => void | Promise<void>;
+}
+/**
+ * Install `window.zdtp = { show, hide, toggle }`, the fixed-name console
+ * sugar for the common single-panel case (issue #523).
+ *
+ * Guard rules:
+ *  - A pre-existing `window.zdtp` WITHOUT this package's marker is assumed to
+ *    be host-defined — never overwritten. Logs a `console.warn` so the host
+ *    can see why `zdtp.show()` did not appear.
+ *  - A pre-existing `window.zdtp` WITH the marker means this package already
+ *    installed the alias (from the other call site, or an earlier run of this
+ *    same one). First install wins — the call is a silent no-op. In the Astro
+ *    flow this manifests as "the adapter wins": its bootstrap script always
+ *    runs (and installs the alias) before the panel module's lazy dynamic
+ *    import can resolve and reach the package-root install site.
+ *
+ * `show` / `hide` / `toggle` are caller-supplied closures, so which instance
+ * they target is up to the caller — the package-root install site (below,
+ * `index.tsx`) wraps `showDesignTokenPanel()` etc., which re-resolve
+ * `getPanelConfig()` (the CURRENT default instance) on every call; the Astro
+ * host-adapter install site instead binds to the specific `PanelInstanceHandle`
+ * captured at its own install time, which does NOT track a later change of
+ * default (see PORTABLE-CONTRACT.md §6.5 for the full nuance). Either way,
+ * for a multi-instance page use `configurePanel(cfg).open()` etc. on the
+ * specific instance's own handle instead of relying on this alias.
+ */
+export declare function installZdtpGlobalAlias(api: ZdtpGlobalApi): void;
 /**
  * Runtime validation at the host-adapter trust boundary. The Astro inline
  * `<script type="application/json">` payload is untrusted-by-the-types:

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

@@ -0,0 +1,26 @@
+/**
+ * ActionsMenuPopover — narrow-panel replacement for the header action links
+ * (Export / Load from JSON… / Apply / Reset), collapsed behind the kebab
+ * trigger below the panel's <480px container-query breakpoint (#518).
+ *
+ * A PLAIN popover of ordinary action RoleButtons, NOT an ARIA menu:
+ * role="menu"/menuitem demands arrow-key navigation and focus management,
+ * and RoleButton hardcodes role="button" — so this follows the existing
+ * gear-settings popover's dialog + outside-click/Escape wiring instead
+ * (usePopoverClose, shared with highlight/highlight-settings-popover.tsx).
+ */
+import type { JSX } from 'preact';
+export interface ActionsMenuAction {
+    label: string;
+    onSelect: () => void;
+}
+interface ActionsMenuPopoverProps {
+    /** The kebab trigger element — excluded from the outside-click close so its
+     *  own click-to-toggle isn't raced by the popover's pointerdown listener
+     *  (mirrors the gear button / HighlightSettingsPopover pairing). */
+    anchorRef: React.RefObject<HTMLElement | null>;
+    actions: readonly ActionsMenuAction[];
+    onClose: () => void;
+}
+export declare function ActionsMenuPopover({ anchorRef, actions, onClose, }: ActionsMenuPopoverProps): JSX.Element;
+export {};

package/dist/controls/help-icon.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HelpIcon — small round "?" badge that explains a nearby control via the
+ * shared `.tokenpanel-tooltip--help` variant (issue #520).
+ *
+ * Chrome-button policy (CLAUDE.md): implemented as
+ * `<div role="button" tabIndex={0}>` with explicit Enter/Space handling —
+ * never a native `<button>`.
+ *
+ * Behavior:
+ *  - Hover / focus shows the help tooltip transiently, same as any other
+ *    `useTooltip` trigger.
+ *  - Click (or Enter/Space) PINS the tooltip open — touch devices have no
+ *    hover, so a tap must be able to reveal and hold the tip. A second
+ *    activation, or pressing Escape anywhere on the page, unpins it.
+ *
+ * Callers place this as a SIBLING of the control it explains (e.g. after a
+ * `<select>`, or after a `<label>` wrapping a checkbox) — never nested
+ * inside a `<label>`, where a click would also toggle the label's own
+ * control.
+ *
+ * Known trade-off: `tooltip.tsx` renders a single shared tooltip DOM node,
+ * so pinning icon A then hovering/pinning icon B silently replaces A's
+ * visible content with B's — A's `pinned`/`is-pinned` state persists until
+ * A is next clicked or Escape is pressed, even though its tooltip is no
+ * longer the one on screen. Acceptable for this panel's single-tooltip
+ * architecture; not worth a cross-instance pin registry for a "?" hint.
+ * The same applies to a panel/window resize: `tooltip.tsx` hides the shared
+ * tooltip on resize (its ResizeObserver + window-resize handlers), but this
+ * component's local `pinned` state only clears on click/Escape — so after a
+ * resize the icon may briefly keep `is-pinned`/`aria-pressed` with no tooltip
+ * visible until the next activation. Same accepted single-tooltip trade-off.
+ */
+import type { JSX } from 'preact';
+export declare const LITERAL_HELP_TEXT = "Literal sets a fixed color just for this token \u2014 it won't update if you edit a palette/ramp swatch later. Pick a ramp option to keep it linked live.";
+export declare const PER_MODE_HELP_TEXT = "Per-mode gives this token two colors \u2014 one for light mode, one for dark. The browser picks the right one automatically via CSS light-dark().";
+export interface HelpIconProps {
+    /** The help text shown in the tooltip (wrapped, multi-line). */
+    text: string;
+    /** Accessible name for the icon itself (e.g. "Literal help", "Surface per-mode help"). */
+    ariaLabel: string;
+}
+export declare function HelpIcon({ text, ariaLabel }: HelpIconProps): JSX.Element;
+export default HelpIcon;

package/dist/controls/tooltip.d.ts

@@ -16,6 +16,13 @@
  *   <div {...tooltipProps}>...</div>
  */
 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`
+ * for the multi-sentence Literal / Per-mode explainer tips.
+ */
+export type TooltipVariant = 'help';
 interface TooltipProviderProps {
     children: ComponentChildren;
 }
@@ -27,17 +34,28 @@ interface TooltipProviderProps {
  * tooltip globally.
  */
 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. */
+    variant?: TooltipVariant;
+}
 /**
  * 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`).
  * @returns An object of `onMouseEnter`, `onMouseLeave`, `onFocusIn`, `onFocusOut`
- *          handlers to spread onto the trigger element.
+ *          handlers to spread onto the trigger element, plus imperative
+ *          `show`/`hide` escape hatches for callers that need to
+ *          show/keep-open the tooltip outside of a raw hover/focus event
+ *          (e.g. `controls/help-icon.tsx`'s click-to-pin behavior).
  */
-export declare function useTooltip(text: string): {
+export declare function useTooltip(text: string, opts?: UseTooltipOptions): {
     onMouseEnter: JSX.MouseEventHandler<HTMLElement>;
     onMouseLeave: JSX.MouseEventHandler<HTMLElement>;
     onFocusIn: JSX.FocusEventHandler<HTMLElement>;
     onFocusOut: JSX.FocusEventHandler<HTMLElement>;
+    show: (el: HTMLElement) => void;
+    hide: (el: HTMLElement) => void;
 };
 export {};

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

@@ -56,10 +56,11 @@ export type { ColorClusterConfig } from './state/tweak-state';
 export { ZDTP_LEGACY_TYPOGRAPHY_RENAME_MAP } from './state/tweak-state';
 export type { ColorScheme, ColorRef } from './config/color-schemes';
 export type { TokenManifest, TokenDef } from './tokens/manifest';
-export type { TierValueKind, PillSpec, TierItem, TierConfig, TabConfig, ColorClusterExtras, } from './tokens/tier-model';
+export type { TierValueKind, PillSpec, TierItem, TierConfig, TabConfig, ColorClusterExtras, NotesExtras, } from './tokens/tier-model';
 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;