@takazudo/zdtp 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,7 +1,23 @@
 # Changelog
 
+## 0.3.0
+
+### Features
+
+- **Multi-instance support.** `configurePanel(config)` now returns a `PanelInstanceHandle` and supports multiple independent panel instances on one page. Calling it with a distinct `storagePrefix` registers a new instance (independent storage keys, DOM root, toggle event, apply target). Calling it again with the same prefix and structurally-equal config is a no-op that returns the same handle (covers Astro view-transition reruns). Calling it with the same prefix but a structurally-different config throws immediately (`RECONFIGURE_RULE = 'reject-with-error'`); call `handle.destroy()` first to re-configure a prefix. Additive and backward-compatible — single-panel hosts observe no change. ([#353](https://github.com/Takazudo/zudo-design-token-panel/issues/353))
+
+- **`PanelInstanceHandle`.** `configurePanel` now returns a handle with `{ instanceId, open(), close(), toggle(), destroy() }`. `instanceId` equals `storagePrefix`. `destroy()` deregisters the instance, unmounts its Preact tree, removes its DOM root, and unbinds its toggle-event listener — freeing the prefix for re-configuration. ([#353](https://github.com/Takazudo/zudo-design-token-panel/issues/353))
+
+- **Per-instance toggle events.** The default instance (the historical `storagePrefix`) keeps `toggle-design-token-panel` unchanged. Any instance with a non-default prefix listens on `config.toggleEvent` when supplied, or `toggle-${storagePrefix}` by default — giving each instance its own independent toggle channel. `PanelConfig.toggleEvent?: string` is a new optional field. ([#354](https://github.com/Takazudo/zudo-design-token-panel/issues/354))
+
+- **`PanelConfig.applySink`.** An optional `{ apply(pairs), clear(names) }` sink routes this instance's CSS-var writes and clears through a caller-supplied object instead of `document.documentElement`. Useful for shadow DOM, iframe, or test-spy contexts. `apply` = upsert; `clear` = remove. Reset sends the full token-name set for the instance to `sink.clear` so the sink target is completely cleaned. Sink errors are non-fatal (`console.warn`). The host owns the sink target's lifecycle. `applySink` carries function references and must not be passed through the Astro inline JSON config. ([#355](https://github.com/Takazudo/zudo-design-token-panel/issues/355))
+
 ## 0.2.3
 
+### Bug Fixes
+
+- A host `color-scheme-changed` event (light/dark toggle) no longer wipes the user's `spacing` / `typography` / `size` tweaks from the live panel. The scheme-change handler now clears only the color cluster's inline `:root` vars and re-seeds only the `color` (and optional `secondary`) slices, leaving the scheme-independent non-color slices — and their applied inline vars — intact. Previously it called the full `clearAppliedStyles()` + `freshTweakState()`, which stripped every spacing/font/size var and emptied those live slices, so the next in-panel edit permanently persisted the loss. A new internal `clearAppliedColorStyles()` performs the color-only clear; full resets (Reset / Apply) keep using `clearAppliedStyles()`. ([#347](https://github.com/Takazudo/zudo-design-token-panel/issues/347))
+
 ### Features
 
 - Make `ColorScheme.shikiTheme` optional so hosts can pass their color-scheme maps without a dummy `shikiTheme` or an `as unknown as` cast — the runtime already falls back to the cluster's `defaultShikiTheme`. The hydrated `ColorTweakState.shikiTheme` stays required (it is always defaulted, and `TweakState` is re-exported, so keeping it required avoids widening the public `state.color.shikiTheme` type). (e057388, fd87423, [#342](https://github.com/Takazudo/zudo-design-token-panel/issues/342))

package/README.md

@@ -432,31 +432,98 @@ The zfb (zudo-front-builder) integration is documented in that project's own rep
 
 ## 5. `configurePanel()` and the `PanelConfig` shape
 
-`configurePanel(config)` is the configure-once init. The Astro host adapter calls it for you (it reads the inline JSON config emitted by `<DesignTokenPanelHost>` and forwards it). For a non-Astro host, you would call `configurePanel(myPanelConfig)` yourself before the panel adapter is dynamically imported.
+`configurePanel(config)` is the multi-instance init. It returns a `PanelInstanceHandle`. The Astro host adapter calls it for you (it reads the inline JSON config emitted by `<DesignTokenPanelHost>` and forwards it). For a non-Astro host, you would call `configurePanel(myPanelConfig)` yourself before the panel adapter is dynamically imported.
 
 ```ts
 import { configurePanel, type PanelConfig } from '@takazudo/zdtp';
 
-configurePanel(myPanelConfig);
+const handle = configurePanel(myPanelConfig);
+// handle.instanceId === myPanelConfig.storagePrefix
+// handle.open() / close() / toggle() / destroy()
 ```
 
 ### 5.1 Behaviour
 
-- **One-shot per page lifecycle.** Calling `configurePanel` twice with identical values is a no-op. Calling it twice with different values throws — silently overwriting a previously-configured cluster mid-session is the failure mode the contract explicitly rules out.
+- **Multi-instance.** Call `configurePanel` with a **distinct** `storagePrefix` to register an independent panel instance (independent storage keys, DOM root, toggle event, and apply target). No throw.
+- **Idempotent for same prefix+config.** Calling `configurePanel` again with the same `storagePrefix` and structurally-equal config values is a no-op and returns the same handle. This covers Astro view-transition reruns that re-parse the inline JSON config.
+- **Same-prefix-different-config THROWS.** Calling `configurePanel` with an already-registered prefix but a different config throws immediately. To re-configure a prefix, call `handle.destroy()` first, then `configurePanel` again.
 - **Synchronous, no I/O.** The call must be cheap enough to run inline at module init.
-- **JSON-serializable input.** Every nested field MUST round-trip through `JSON.stringify` / `JSON.parse` without loss. No function fields, no class instances, no `Symbol` keys, no `undefined`-where-`null`-is-meant. This is the hard precondition for the Astro frontmatter → client island handoff (§8).
+- **JSON-serializable input (except `applySink`).** Every nested field other than `applySink` MUST round-trip through `JSON.stringify` / `JSON.parse` without loss. `applySink` carries function references and must not be passed through the Astro inline JSON config.
 
-### 5.2 Field summary
+### 5.2 `PanelInstanceHandle`
+
+```ts
+export interface PanelInstanceHandle {
+  /** Stable instance id — equal to the instance's `storagePrefix`. */
+  readonly instanceId: string;
+  open(): void;   // show this instance's panel
+  close(): void;  // hide this instance's panel
+  toggle(): void; // toggle open/closed
+  /**
+   * Deregister this instance. Unmounts Preact tree, removes DOM root,
+   * unbinds toggle-event listener. Prefix can then be re-configured.
+   */
+  destroy(): void;
+}
+```
+
+### 5.3 Field summary
 
 | Field                | Type                           | Purpose                                                                                                                                                                |
 | -------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `storagePrefix`      | `string`                       | Base for every derived `localStorage` key. See §9.                                                                                                                     |
+| `storagePrefix`      | `string`                       | Base for every derived `localStorage` key. Also the instance id. See §9.                                                                                               |
 | `consoleNamespace`   | `string`                       | Global object the package installs `showDesignPanel` / `hideDesignPanel` / `toggleDesignPanel` on (e.g. `consoleNamespace: 'myapp'` → `window.myapp.showDesignPanel`). |
 | `modalClassPrefix`   | `string`                       | BEM root class for every modal the panel owns (export, import, apply). Emits `${prefix}__overlay`, `${prefix}__panel`, etc.                                            |
 | `schemaId`           | `string`                       | `$schema` value emitted into export JSON and required on import.                                                                                                       |
 | `exportFilenameBase` | `string`                       | Default download filename base — exports save as `${exportFilenameBase}.json`.                                                                                         |
+| `toggleEvent`        | `string` (optional)            | Window-event name that toggles THIS instance. Defaults to `toggle-${storagePrefix}` for non-default instances; the default instance keeps `toggle-design-token-panel`. |
 | `tabs`               | `readonly TabConfig[]`         | **Required.** Tab strip data — each entry is a tab with one or more `TierConfig` objects. The color tab (id `'color'`) additionally requires `colorExtras`. See §6.    |
 | `colorPresets`       | `Record<string, ColorScheme>` (optional) | Optional named scheme presets surfaced in the Color tab "Scheme..." dropdown. Defaults to `{}`. See §7.5.                                              |
+| `applySink`          | `ApplySink` (optional)         | Optional sink that routes this instance's CSS-var writes off `:root`. See §5.4. Not JSON-serializable — do not include in Astro inline config.                        |
+
+### 5.4 `applySink` — optional write target
+
+When `PanelConfig.applySink` is set for an instance, all CSS-var writes and clears for that instance route through the sink rather than `document.documentElement`. This enables embedding the panel in a shadow root, iframe, or test spy without touching `:root`.
+
+```ts
+export interface ApplySink {
+  /** Upsert the given var name→value pairs on the sink target. */
+  apply(pairs: ReadonlyArray<readonly [string, string]>): void;
+  /** Remove the given var names from the sink target. */
+  clear(names: readonly string[]): void;
+}
+```
+
+Key behaviours:
+
+- `apply` = **upsert**: set each named CSS var on the sink target.
+- `clear` = **remove**: remove each named CSS var from the sink target.
+- **Reset clears the full token set**: when the user clicks Reset, `sink.clear` receives every var the instance can own (not just dirty vars) so the sink target is fully cleaned.
+- **Sink errors are non-fatal**: `console.warn` is emitted and the apply pipeline continues.
+- **The host owns the sink target's lifecycle.** Keep the sink target alive as long as the panel instance is alive.
+- **Not JSON-serializable.** Supply it after `configurePanel` via a custom adapter or by constructing the config object with the sink already attached.
+
+```ts
+// Example: routing to a shadow root
+const shadow = shadowHost.attachShadow({ mode: 'open' });
+
+const handle = configurePanel({
+  storagePrefix: 'myapp-shadow-panel',
+  // ...other required fields...
+  applySink: {
+    apply(pairs) {
+      for (const [name, value] of pairs) {
+        (shadow.host as HTMLElement).style.setProperty(name, value);
+      }
+    },
+    clear(names) {
+      for (const name of names) {
+        (shadow.host as HTMLElement).style.removeProperty(name);
+      }
+    },
+  },
+});
+```
 
 ### 5.3 Mount strategy & auto-mount
 
@@ -577,13 +644,15 @@ The panel walks each `TierItem` on apply:
 
 - If `readonly`, the row is display-only — no writes.
 - For a **base tier item**: if the override map has a non-empty string for
-  `id`, the panel calls `document.documentElement.style.setProperty(item.cssVar, value)`.
-  Otherwise it removes the inline property so the consumer's stylesheet default wins.
+  `id`, the panel writes `item.cssVar` ← value. Otherwise it removes the
+  inline property so the consumer's stylesheet default wins.
 - For a **ref-tier item** (`referencesTier` set): the persisted value is the id
   of an item in the referenced base tier. The apply pipeline emits
   `var(--base-tier-cssvar)` as the written value.
 
-The write target is always `:root`. No shadow DOM, no scoped overrides — the panel ships a global tweak intentionally.
+The default write target is `:root` (`document.documentElement`). An instance
+with `PanelConfig.applySink` set routes writes through the sink instead — see
+§5.4 for the full sink contract.
 
 ---
 
@@ -842,7 +911,9 @@ The `visible` key uses a literal `:` separator, not `-`. Every other derived key
 
 Tweak state is **global**, not scheme-scoped: the keys above are derived only from `storagePrefix` and carry no color-scheme name. A single envelope holds every slice — the `color` slice stores **absolute** colors (palette + role/semantic indices resolved against that palette), while the `spacing` / `typography` / `size` slices store token overrides that are independent of the active scheme.
 
-Because the stored palette is absolute, it cannot simply be re-applied on top of a different scheme. So when the host dispatches a `color-scheme-changed` event (e.g. a light/dark toggle), the panel **re-seeds its live state from the newly active scheme**: it removes the inline `:root` overrides it had applied (`clearAppliedStyles`) and re-initializes the live envelope from that scheme (`freshTweakState`). Palette tweaks are therefore intentionally **not** carried across a scheme switch — the panel adopts the new scheme's palette rather than layering the previous absolute colors on top of it. This is the panel's deliberate global model; it does **not** persist a separate color slice per scheme.
+Because the stored palette is absolute, it cannot simply be re-applied on top of a different scheme. So when the host dispatches a `color-scheme-changed` event (e.g. a light/dark toggle), the panel **re-seeds its live color state from the newly active scheme**: it removes only the inline `:root` color-cluster overrides it had applied (`clearAppliedColorStyles`) and re-initializes only the live `color` (and optional `secondary`) slices from that scheme. Palette tweaks are therefore intentionally **not** carried across a scheme switch — the panel adopts the new scheme's palette rather than layering the previous absolute colors on top of it. This is the panel's deliberate global model; it does **not** persist a separate color slice per scheme.
+
+The `spacing` / `typography` / `size` slices are scheme-INDEPENDENT, so they are deliberately left untouched by the re-seed: their live values and their applied inline `:root` vars survive a scheme toggle (the scheme-change handler narrows the clear to the color cluster(s) for exactly this reason — see #347). A full panel reset (Reset / Apply) still wipes every slice via `clearAppliedStyles`.
 
 Two consequences worth knowing as a host integrator:
 

package/dist/apply-modal.d.ts

@@ -26,6 +26,7 @@
  * the native `close` event exactly once; `onClose` then fires exactly once
  * per dismissal regardless of the path taken.
  */
+import { type PanelConfig } from './config/panel-config';
 import { type ColorTweakState, type TweakState } from './state/tweak-state';
 export interface ApplyModalProps {
     state: TweakState;
@@ -44,6 +45,15 @@ export interface ApplyModalProps {
      * clear any inline-applied styles, and reset in-memory state to empty.
      */
     onApplied: () => void;
+    /**
+     * The mounted panel instance's config (multi-instance, #357). When supplied,
+     * the modal resolves its apply routing / endpoint / secondary cluster / modal
+     * classes from THIS instance rather than the active default instance — so an
+     * Apply on panel A targets A's endpoint+routing, not whichever instance was
+     * configured last. Omitted (e.g. a direct test render) → `getPanelConfig()`,
+     * preserving the single-panel path.
+     */
+    instanceConfig?: PanelConfig;
 }
 export declare function ApplyModal(props: ApplyModalProps): import("preact").JSX.Element;
 //# sourceMappingURL=apply-modal.d.ts.map

package/dist/apply-modal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-modal.d.ts","sourceRoot":"","sources":["../src/apply-modal.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAWH,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAK5E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;OAIG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAmJD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,gCA0YhD"}
+{"version":3,"file":"apply-modal.d.ts","sourceRoot":"","sources":["../src/apply-modal.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAK7B,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;OAIG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AA2JD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,gCAwZhD"}

package/dist/astro/host-adapter.js

@@ -1,34 +1,34 @@
-import { c as u, g as l, a as f, b as p, d as h, e as m } from "../panel-config-DP2_P7dD.js";
-import { Z as w } from "../tweak-state-DSJa5csL.js";
-const r = "tokenpanel-config";
-function P() {
+import { c as f, g as c, a as p, b as h, d as m, e as w } from "../panel-config-BOyB8Egg.js";
+import { Z as P } from "../tweak-state-DMwBHPow.js";
+const i = "tokenpanel-config";
+function y() {
   if (typeof document > "u")
     throw new Error(
       "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
     );
-  const e = document.getElementById(r);
+  const e = document.getElementById(i);
   if (!e)
     throw new Error(
-      `[design-token-panel] Inline config script #${r} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+      `[design-token-panel] Inline config script #${i} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
-  const o = e.textContent ?? "";
+  const t = e.textContent ?? "";
   let n;
   try {
-    n = JSON.parse(o);
-  } catch (t) {
+    n = JSON.parse(t);
+  } catch (o) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${r}: ${t.message}`
+      `[design-token-panel] Failed to parse inline config from #${i}: ${o.message}`
     );
   }
-  return m(n), n;
+  return w(n), n;
 }
-function y(e) {
+function _(e) {
   return e.__zudoDesignTokenPanelAdapter || (e.__zudoDesignTokenPanelAdapter = {}), e.__zudoDesignTokenPanelAdapter;
 }
-function _(e, o) {
-  const n = y(e);
-  let t = n[o];
-  return t || (t = { bound: !1, modulePromise: null }, n[o] = t), t;
+function b(e, t) {
+  const n = _(e);
+  let o = n[t];
+  return o || (o = { bound: !1, modulePromise: null }, n[t] = o), o;
 }
 function k(e) {
   try {
@@ -37,19 +37,19 @@ function k(e) {
     return !1;
   }
 }
-function b(e, o) {
+function C(e, t) {
   try {
     const n = window.localStorage;
-    return n.getItem(o) !== null || n.getItem(e) !== null;
+    return n.getItem(t) !== null || n.getItem(e) !== null;
   } catch {
     return !1;
   }
 }
-async function i(e) {
-  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((o) => {
+async function r(e) {
+  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((t) => {
     try {
-      const n = l(), t = o.__panelConfigForTest();
-      n !== t && console.warn(
+      const n = c(), o = t.__panelConfigForTest();
+      n !== o && console.warn(
         "[design-token-panel] Singleton-sharing check failed: the host adapter and the panel module observed different PanelConfig singletons. This indicates the package's `config/panel-config` module is no longer code-split into a single shared chunk. The panel may behave correctly today, but storage keys / namespaces / branding could diverge between the two surfaces in future bundles."
       );
     } catch (n) {
@@ -57,25 +57,23 @@ async function i(e) {
         "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + n.message
       );
     }
-    return o;
+    return t;
   })), e.modulePromise;
 }
-function T(e, o, n) {
-  const t = e[o] ?? {};
-  t.showDesignPanel = async () => {
-    (await i(n)).showDesignTokenPanel();
-  }, t.hideDesignPanel = async () => {
-    (await i(n)).hideDesignTokenPanel();
-  }, t.toggleDesignPanel = async () => {
-    (await i(n)).toggleDesignPanel();
-  }, e[o] = t;
+function I(e, t, n, o) {
+  const a = e[t] ?? {};
+  a.showDesignPanel = async () => {
+    await r(n), o.open();
+  }, a.hideDesignPanel = async () => {
+    await r(n), o.close();
+  }, a.toggleDesignPanel = async () => {
+    await r(n), o.toggle();
+  }, e[t] = a;
 }
 (function() {
-  const o = P(), n = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...w } };
-  u(n);
-  const t = l(), a = window, s = _(a, t.storagePrefix);
-  if (T(a, t.consoleNamespace, s), s.bound) return;
+  const t = y(), n = t.legacyIdRenameMap ? t : { ...t, legacyIdRenameMap: { ...P } }, o = f(n), a = c(), l = window, s = b(l, a.storagePrefix);
+  if (I(l, a.consoleNamespace, s, o), s.bound) return;
   s.bound = !0;
-  const c = f(t), d = p(t), g = h(t);
-  (k(c) || b(d, g)) && i(s);
+  const d = p(a), g = h(a), u = m(a);
+  (k(d) || C(g, u)) && r(s);
 })();

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-DP2_P7dD.js";
+import { s as t } from "../panel-config-BOyB8Egg.js";
 import { c as d } from "../color-schemes-CgzOBqGO.js";
 import { F as r, G as m, a as g, S as z } from "../manifest-DCReQE0k.js";
 const e = {