@component-anatomy/storybook 0.3.0 → 0.5.0

package/README.md

@@ -5,7 +5,7 @@ Storybook addon that adds an **Anatomy** panel — an interactive part list sync
 - Hover a part in the panel → the element is highlighted in the canvas
 - Hover a `data-part` element in the canvas → the panel entry activates
 - The same table renders **inside MDX** via `@component-anatomy/storybook/blocks`
-- Works with **Storybook 9 and 10**, any renderer (React, Vue, HTML, Web Components…)
+- Works with **Storybook 10 and 11**, any renderer (React, Vue, HTML, Web Components…) — parts inside open shadow roots included
 
 ## Install
 
@@ -13,6 +13,9 @@ Storybook addon that adds an **Anatomy** panel — an interactive part list sync
 npm install --save-dev @component-anatomy/storybook
 ```
 
+Register the addon in `.storybook/main.ts`. This is what loads the **Anatomy**
+panel into the Storybook manager:
+
 ```ts
 // .storybook/main.ts
 export default {
@@ -20,6 +23,34 @@ export default {
 };
 ```
 
+### If your `preview.ts` uses CSF Next
+
+CSF Next is the default story format in Storybook 11. A `preview.ts` built with
+`definePreview` composes **only** the addons it lists, and Storybook drops the
+preview annotations that `main.ts` would otherwise contribute — so the addon
+also has to be registered there, or the canvas decorator never mounts and the
+panel stays empty:
+
+```ts
+// .storybook/preview.ts
+
+// Replace your-framework with the framework you are using (e.g. react-vite, nextjs-vite)
+import { definePreview } from '@storybook/your-framework';
+import componentAnatomy from '@component-anatomy/storybook';
+
+export default definePreview({
+  // ...rest of preview
+  addons: [componentAnatomy()], // 👈 register the addon here
+});
+```
+
+Registering in both places is correct and safe: the two paths are mutually
+exclusive, so the decorator is composed exactly once either way. A `preview.ts`
+that is still a plain object needs only the `main.ts` entry above.
+
+Doing so also types `parameters.anatomy` across that preview's metas and
+stories, so the shape below is checked for you.
+
 ## Use
 
 Annotate your story's DOM with `data-part` and add the `anatomy` parameter:
@@ -39,6 +70,7 @@ export const Anatomy: Story = {
       theme: { accent: '#0d9488' },   // theme tokens for the canvas overlays
       overlayLabel: true,             // floating name chip
       overlayPadding: 2,              // inflate highlight boxes (px)
+      shadowParts: false,             // also read native `part` attributes in shadow roots
       root: '.my-component',          // narrow the anatomy root (CSS selector)
       disable: false,                 // turn off for a story
     } satisfies AnatomyParameters,
@@ -48,6 +80,8 @@ export const Anatomy: Story = {
 
 Omit `parts` (pass `{}`) and the panel lists parts auto-discovered from `data-part` attributes, with names derived from the ids.
 
+Web components work as they are: parts are found inside open shadow roots, and the panel updates when a component renders them late (Lit, Stencil) or is defined late. Set `shadowParts: true` to read the anatomy a component already exposes for `::part()` (`part="track"`) instead of adding `data-part`. Closed shadow roots can't be reached.
+
 `preset` and `theme` reach the panel and the `<Anatomy>` block too, not just the canvas overlays: the active row is accented with the same color the overlay paints. Where that color would be illegible on Storybook's own panel — `contrast` is black, the manager is dark by default — the table falls back to the most colorful alternative that meets WCAG AA, so `contrast` accents with its yellow on a dark panel and with black on a light one.
 
 Parameters follow Storybook's normal inheritance — project-wide defaults in `.storybook/preview.ts`, per-component in `meta.parameters`, per-story overrides in `story.parameters`.
@@ -113,10 +147,25 @@ Two things worth knowing, for either block:
 
 Several blocks can share one page; each talks only to the story it names.
 
+## Compatibility
+
+| | |
+|---|---|
+| `storybook` | `^10.0.0 \|\| ^11.0.0-0` |
+| `@storybook/addon-docs` | `^10.0.0 \|\| ^11.0.0-0` (optional — only for the MDX blocks) |
+| `react` | `>=18` (optional — only for the MDX blocks) |
+| Node | `>=22.12.0` |
+
+The package is ESM-only, like Storybook itself since 9. Storybook 9 is no
+longer supported: CSF Next registration needs `definePreviewAddon`, which
+Storybook only ships from 9.1 onwards, and the addon is built and tested
+against 10 and 11.
+
 ## Example
 
-A complete Storybook 10 setup with Button/Slider/Tabs stories — and two MDX
-pages using the `<Anatomy>` block — lives in [`examples/storybook`](https://github.com/julien-deramond/component-anatomy/tree/main/examples/storybook), deployed at https://julien-deramond.github.io/component-anatomy/storybook/.
+A complete Storybook 11 setup with Button/Slider/Tabs stories, web components
+(vanilla, Lit, Shoelace, and Ionic built with Stencil) — and two MDX pages using
+the `<Anatomy>` block — lives in [`examples/storybook`](https://github.com/julien-deramond/component-anatomy/tree/main/examples/storybook), deployed at https://julien-deramond.github.io/component-anatomy/storybook/.
 
 ## Docs
 

package/dist/index.d.ts

@@ -1,3 +1,42 @@
+import type { AnatomyParameters } from './types.js';
 export { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';
 export type { AnatomyParameters } from './types.js';
+/**
+ * What this addon contributes to a CSF Next project's type context: a typed
+ * `parameters.anatomy` on every meta and story of a preview that registers it.
+ */
+export type ComponentAnatomyTypes = {
+    parameters: {
+        /** @see {@link AnatomyParameters} */
+        anatomy?: AnatomyParameters;
+    };
+};
+export default _default;
+/**
+ * The addon's preview annotations, for a CSF Next `preview.ts`:
+ *
+ * ```ts
+ * import { definePreview } from '@storybook/your-framework';
+ * import componentAnatomy from '@component-anatomy/storybook';
+ *
+ * export default definePreview({
+ *   addons: [componentAnatomy()],
+ * });
+ * ```
+ *
+ * `.storybook/main.ts` must still list the addon — `addons:
+ * ['@component-anatomy/storybook']` — since that is what loads the manager
+ * panel. What changes under CSF Next is the preview side: a `preview.ts` built
+ * with `definePreview` composes *only* its own `addons`, and Storybook drops
+ * every addon annotation main.ts would otherwise have contributed. Without the
+ * call below, the canvas decorator never mounts and the panel stays empty.
+ *
+ * Registering in both places is safe — the two paths are mutually exclusive,
+ * so the decorator is composed once either way.
+ *
+ * The `./blocks` subpath, not this entry, holds the `<Anatomy>` MDX block: it
+ * needs React and `@storybook/addon-docs`, both optional peers that must not
+ * become load-bearing for a Storybook that only wants the panel.
+ */
+declare function _default(): import("storybook/internal/csf").PreviewAddon<ComponentAnatomyTypes>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE;QACV,qCAAqC;QACrC,OAAO,CAAC,EAAE,iBAAiB,CAAC;KAC7B,CAAC;CACH,CAAC;;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/index.js

@@ -1,3 +1,10 @@
+// src/index.ts
+import { definePreviewAddon } from "storybook/internal/csf";
+
+// src/preview.ts
+import { addons, useEffect } from "storybook/preview-api";
+import { createAnatomy } from "@component-anatomy/core";
+
 // src/constants.ts
 var ADDON_ID = "component-anatomy";
 var PANEL_ID = `${ADDON_ID}/panel`;
@@ -16,10 +23,81 @@ var EVENTS = {
   /** consumers → preview: a panel/block mounted and wants the current part list. */
   PARTS_REQUEST: `${ADDON_ID}/parts-request`
 };
+
+// src/channel.ts
+var matchesStory = (eventStoryId, storyId) => !eventStoryId || !storyId || eventStoryId === storyId;
+
+// src/preview.ts
+var withComponentAnatomy = (storyFn, context) => {
+  const params = context.parameters?.[PARAM_KEY];
+  useEffect(() => {
+    if (!params || params.disable) return;
+    const channel = addons.getChannel();
+    const canvas = context.canvasElement;
+    if (!canvas) return;
+    const storyId = context.id;
+    const root = params.root ? canvas.querySelector(params.root) ?? canvas : canvas;
+    const controller = createAnatomy({
+      root,
+      parts: params.parts,
+      shadowParts: params.shadowParts,
+      preset: params.preset,
+      theme: params.theme,
+      overlay: {
+        label: params.overlayLabel !== false,
+        padding: params.overlayPadding
+      }
+    });
+    const announceParts = () => channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });
+    announceParts();
+    const offChange = controller.on("parts:change", announceParts);
+    const offEnter = controller.on(
+      "part:enter",
+      (partId) => channel.emit(EVENTS.PART_ENTER, { storyId, partId })
+    );
+    const offLeave = controller.on(
+      "part:leave",
+      () => channel.emit(EVENTS.PART_LEAVE, { storyId })
+    );
+    const onHoverItem = (event) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      controller.highlight(event.partId);
+    };
+    const onLeaveItem = (event = {}) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      controller.unhighlight();
+    };
+    const onPartsRequest = (event = {}) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      announceParts();
+    };
+    channel.on(EVENTS.HOVER_ITEM, onHoverItem);
+    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);
+    channel.on(EVENTS.PARTS_REQUEST, onPartsRequest);
+    return () => {
+      channel.off(EVENTS.HOVER_ITEM, onHoverItem);
+      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
+      channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);
+      offChange();
+      offEnter();
+      offLeave();
+      controller.destroy();
+    };
+  }, [context.id]);
+  return storyFn();
+};
+var annotations = {
+  decorators: [withComponentAnatomy]
+};
+var preview_default = annotations;
+
+// src/index.ts
+var index_default = () => definePreviewAddon(preview_default);
 export {
   ADDON_ID,
   EVENTS,
   PANEL_ID,
-  PARAM_KEY
+  PARAM_KEY,
+  index_default as default
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/constants.ts"],
-  "sourcesContent": ["export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/**\n * Channel events used to sync the manager panel \u2014 and the `<Anatomy>` MDX doc\n * block, which runs in the preview iframe \u2014 with the story canvas.\n *\n * Every payload carries the `storyId` it concerns; see `channel.ts` for the\n * payload types and the `matchesStory` filter each listener applies.\n */\nexport const EVENTS = {\n  /** preview \u2192 consumers: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 consumers: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 consumers: resolved part list for a story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** consumers \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** consumers \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** consumers \u2192 preview: a panel/block mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n"],
-  "mappings": ";AAAO,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AASlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;",
+  "sources": ["../src/index.ts", "../src/preview.ts", "../src/constants.ts", "../src/channel.ts"],
+  "sourcesContent": ["import { definePreviewAddon } from 'storybook/internal/csf';\n\nimport annotations from './preview.js';\nimport type { AnatomyParameters } from './types.js';\n\nexport { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';\nexport type { AnatomyParameters } from './types.js';\n\n/**\n * What this addon contributes to a CSF Next project's type context: a typed\n * `parameters.anatomy` on every meta and story of a preview that registers it.\n */\nexport type ComponentAnatomyTypes = {\n  parameters: {\n    /** @see {@link AnatomyParameters} */\n    anatomy?: AnatomyParameters;\n  };\n};\n\n/**\n * The addon's preview annotations, for a CSF Next `preview.ts`:\n *\n * ```ts\n * import { definePreview } from '@storybook/your-framework';\n * import componentAnatomy from '@component-anatomy/storybook';\n *\n * export default definePreview({\n *   addons: [componentAnatomy()],\n * });\n * ```\n *\n * `.storybook/main.ts` must still list the addon \u2014 `addons:\n * ['@component-anatomy/storybook']` \u2014 since that is what loads the manager\n * panel. What changes under CSF Next is the preview side: a `preview.ts` built\n * with `definePreview` composes *only* its own `addons`, and Storybook drops\n * every addon annotation main.ts would otherwise have contributed. Without the\n * call below, the canvas decorator never mounts and the panel stays empty.\n *\n * Registering in both places is safe \u2014 the two paths are mutually exclusive,\n * so the decorator is composed once either way.\n *\n * The `./blocks` subpath, not this entry, holds the `<Anatomy>` MDX block: it\n * needs React and `@storybook/addon-docs`, both optional peers that must not\n * become load-bearing for a Storybook that only wants the panel.\n */\nexport default () => definePreviewAddon<ComponentAnatomyTypes>(annotations);\n", "/**\n * Preview-side (iframe) entry. Registers a global decorator that mounts a\n * component-anatomy controller over the story canvas and syncs hover state\n * with the manager panel \u2014 and with any `<Anatomy>` doc block on the same\n * docs page \u2014 over the addon channel.\n *\n * The decorator runs in docs view too: the docs `Story` block renders each\n * story through `renderStoryToElement`, which sets `context.canvasElement`\n * exactly as it does in story view. That is what makes auto-discovery and\n * hover sync work inside MDX.\n */\nimport { addons, useEffect } from 'storybook/preview-api';\nimport type {\n  ProjectAnnotations,\n  Renderer,\n  PartialStoryFn,\n  StoryContext,\n} from 'storybook/internal/types';\nimport { createAnatomy } from '@component-anatomy/core';\n\nimport { EVENTS, PARAM_KEY } from './constants.js';\nimport { matchesStory } from './channel.js';\nimport type { HoverItemEvent, StoryScopedEvent } from './channel.js';\nimport type { AnatomyParameters } from './types.js';\n\nexport const withComponentAnatomy = (\n  storyFn: PartialStoryFn<Renderer>,\n  context: StoryContext<Renderer>\n) => {\n  const params = context.parameters?.[PARAM_KEY] as AnatomyParameters | undefined;\n\n  useEffect(() => {\n    if (!params || params.disable) return;\n\n    const channel = addons.getChannel();\n    const canvas = context.canvasElement as unknown as HTMLElement;\n    if (!canvas) return;\n\n    const storyId = context.id;\n\n    const root = params.root\n      ? canvas.querySelector<HTMLElement>(params.root) ?? canvas\n      : canvas;\n\n    const controller = createAnatomy({\n      root,\n      parts: params.parts,\n      shadowParts: params.shadowParts,\n      preset: params.preset,\n      theme: params.theme,\n      overlay: {\n        label: params.overlayLabel !== false,\n        padding: params.overlayPadding,\n      },\n    });\n\n    const announceParts = () =>\n      channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });\n\n    announceParts();\n    // Parts can show up after this effect ran: a web component renders its\n    // shadow root asynchronously (Lit, Stencil), or is defined late.\n    const offChange = controller.on('parts:change', announceParts);\n\n    const offEnter = controller.on('part:enter', (partId) =>\n      channel.emit(EVENTS.PART_ENTER, { storyId, partId })\n    );\n    const offLeave = controller.on('part:leave', () =>\n      channel.emit(EVENTS.PART_LEAVE, { storyId })\n    );\n\n    // A docs page mounts several stories at once, so every controller sees\n    // every panel/block event \u2014 only act on the ones addressed to this story.\n    const onHoverItem = (event: HoverItemEvent) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.highlight(event.partId);\n    };\n    const onLeaveItem = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.unhighlight();\n    };\n    const onPartsRequest = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      announceParts();\n    };\n\n    channel.on(EVENTS.HOVER_ITEM, onHoverItem);\n    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);\n    // The panel or block may mount after the story rendered \u2014 let it ask for\n    // the list rather than racing the first announcement.\n    channel.on(EVENTS.PARTS_REQUEST, onPartsRequest);\n\n    return () => {\n      channel.off(EVENTS.HOVER_ITEM, onHoverItem);\n      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);\n      channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);\n      offChange();\n      offEnter();\n      offLeave();\n      controller.destroy();\n    };\n  }, [context.id]);\n\n  return storyFn();\n};\n\nexport const decorators = [withComponentAnatomy];\n\n/**\n * The same annotations as a default export, which is the shape\n * `definePreviewAddon` takes in the package's main entry (see `index.ts`) and\n * the shape a consumer gets from `@component-anatomy/storybook/preview`.\n *\n * Storybook reads `module.default[field] ?? module[field]`, so a preview\n * annotation module that exports both is read exactly once \u2014 the named\n * `decorators` above stays for anyone importing it directly.\n */\nconst annotations: ProjectAnnotations<Renderer> = {\n  decorators: [withComponentAnatomy],\n};\n\nexport default annotations;\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/**\n * Channel events used to sync the manager panel \u2014 and the `<Anatomy>` MDX doc\n * block, which runs in the preview iframe \u2014 with the story canvas.\n *\n * Every payload carries the `storyId` it concerns; see `channel.ts` for the\n * payload types and the `matchesStory` filter each listener applies.\n */\nexport const EVENTS = {\n  /** preview \u2192 consumers: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 consumers: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 consumers: resolved part list for a story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** consumers \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** consumers \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** consumers \u2192 preview: a panel/block mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n", "/**\n * Shared channel payload contract between the preview decorator, the manager\n * panel, and the MDX doc block.\n *\n * Every payload carries the `storyId` it refers to. In story view this is\n * redundant \u2014 only one story is mounted \u2014 but a docs page mounts *many*\n * stories at once, each with its own controller, and each `<Anatomy>` block\n * must talk to exactly one of them. Without addressing, hovering a part in\n * one block highlights the matching part in every other story on the page.\n */\nimport type { AnatomyPartDefinition } from '@component-anatomy/core';\n\n/** preview \u2192 consumers: the resolved part list for one story. */\nexport type PartsEvent = { storyId?: string; parts: AnatomyPartDefinition[] };\n\n/** preview \u2192 consumers: a part became active in that story's canvas. */\nexport type PartEnterEvent = { storyId?: string; partId: string };\n\n/** consumer \u2192 preview: highlight this part in that story's canvas. */\nexport type HoverItemEvent = { storyId?: string; partId: string };\n\n/** Payload for the events that only need to name a story. */\nexport type StoryScopedEvent = { storyId?: string };\n\n/**\n * Whether an event addressed to `eventStoryId` concerns `storyId`.\n *\n * A missing id on *either* side matches everything. That keeps the protocol\n * backward compatible: a manager panel from a newer build still understands\n * an older preview bundle that emits unaddressed events, and vice versa.\n */\nexport const matchesStory = (\n  eventStoryId: string | undefined,\n  storyId: string | undefined\n): boolean => !eventStoryId || !storyId || eventStoryId === storyId;\n"],
+  "mappings": ";AAAA,SAAS,0BAA0B;;;ACWnC,SAAS,QAAQ,iBAAiB;AAOlC,SAAS,qBAAqB;;;AClBvB,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AASlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;;;ACKO,IAAM,eAAe,CAC1B,cACA,YACY,CAAC,gBAAgB,CAAC,WAAW,iBAAiB;;;AFTrD,IAAM,uBAAuB,CAClC,SACA,YACG;AACH,QAAM,SAAS,QAAQ,aAAa,SAAS;AAE7C,YAAU,MAAM;AACd,QAAI,CAAC,UAAU,OAAO,QAAS;AAE/B,UAAM,UAAU,OAAO,WAAW;AAClC,UAAM,SAAS,QAAQ;AACvB,QAAI,CAAC,OAAQ;AAEb,UAAM,UAAU,QAAQ;AAExB,UAAM,OAAO,OAAO,OAChB,OAAO,cAA2B,OAAO,IAAI,KAAK,SAClD;AAEJ,UAAM,aAAa,cAAc;AAAA,MAC/B;AAAA,MACA,OAAO,OAAO;AAAA,MACd,aAAa,OAAO;AAAA,MACpB,QAAQ,OAAO;AAAA,MACf,OAAO,OAAO;AAAA,MACd,SAAS;AAAA,QACP,OAAO,OAAO,iBAAiB;AAAA,QAC/B,SAAS,OAAO;AAAA,MAClB;AAAA,IACF,CAAC;AAED,UAAM,gBAAgB,MACpB,QAAQ,KAAK,OAAO,OAAO,EAAE,SAAS,OAAO,WAAW,SAAS,EAAE,CAAC;AAEtE,kBAAc;AAGd,UAAM,YAAY,WAAW,GAAG,gBAAgB,aAAa;AAE7D,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,CAAC,WAC5C,QAAQ,KAAK,OAAO,YAAY,EAAE,SAAS,OAAO,CAAC;AAAA,IACrD;AACA,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,MAC3C,QAAQ,KAAK,OAAO,YAAY,EAAE,QAAQ,CAAC;AAAA,IAC7C;AAIA,UAAM,cAAc,CAAC,UAA0B;AAC7C,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,UAAU,MAAM,MAAM;AAAA,IACnC;AACA,UAAM,cAAc,CAAC,QAA0B,CAAC,MAAM;AACpD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,YAAY;AAAA,IACzB;AACA,UAAM,iBAAiB,CAAC,QAA0B,CAAC,MAAM;AACvD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,oBAAc;AAAA,IAChB;AAEA,YAAQ,GAAG,OAAO,YAAY,WAAW;AACzC,YAAQ,GAAG,OAAO,YAAY,WAAW;AAGzC,YAAQ,GAAG,OAAO,eAAe,cAAc;AAE/C,WAAO,MAAM;AACX,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,eAAe,cAAc;AAChD,gBAAU;AACV,eAAS;AACT,eAAS;AACT,iBAAW,QAAQ;AAAA,IACrB;AAAA,EACF,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEf,SAAO,QAAQ;AACjB;AAaA,IAAM,cAA4C;AAAA,EAChD,YAAY,CAAC,oBAAoB;AACnC;AAEA,IAAO,kBAAQ;;;AD5Ef,IAAO,gBAAQ,MAAM,mBAA0C,eAAW;",
   "names": []
 }

package/dist/preview.d.ts

@@ -1,4 +1,15 @@
-import type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';
+import type { ProjectAnnotations, Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';
 export declare const withComponentAnatomy: (storyFn: PartialStoryFn<Renderer>, context: StoryContext<Renderer>) => any;
 export declare const decorators: (typeof withComponentAnatomy)[];
+/**
+ * The same annotations as a default export, which is the shape
+ * `definePreviewAddon` takes in the package's main entry (see `index.ts`) and
+ * the shape a consumer gets from `@component-anatomy/storybook/preview`.
+ *
+ * Storybook reads `module.default[field] ?? module[field]`, so a preview
+ * annotation module that exports both is read exactly once — the named
+ * `decorators` above stays for anyone importing it directly.
+ */
+declare const annotations: ProjectAnnotations<Renderer>;
+export default annotations;
 //# sourceMappingURL=preview.d.ts.map

package/dist/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAQvF,eAAO,MAAM,oBAAoB,YACtB,cAAc,CAAC,QAAQ,CAAC,WACxB,YAAY,CAAC,QAAQ,CAAC,QAwEhC,CAAC;AAEF,eAAO,MAAM,UAAU,iCAAyB,CAAC"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,YAAY,EACb,MAAM,0BAA0B,CAAC;AAQlC,eAAO,MAAM,oBAAoB,YACtB,cAAc,CAAC,QAAQ,CAAC,WACxB,YAAY,CAAC,QAAQ,CAAC,QA6EhC,CAAC;AAEF,eAAO,MAAM,UAAU,iCAAyB,CAAC;AAEjD;;;;;;;;GAQG;AACH,QAAA,MAAM,WAAW,EAAE,kBAAkB,CAAC,QAAQ,CAE7C,CAAC;eAEa,WAAW"}

package/dist/preview.js

@@ -37,6 +37,7 @@ var withComponentAnatomy = (storyFn, context) => {
     const controller = createAnatomy({
       root,
       parts: params.parts,
+      shadowParts: params.shadowParts,
       preset: params.preset,
       theme: params.theme,
       overlay: {
@@ -46,6 +47,7 @@ var withComponentAnatomy = (storyFn, context) => {
     });
     const announceParts = () => channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });
     announceParts();
+    const offChange = controller.on("parts:change", announceParts);
     const offEnter = controller.on(
       "part:enter",
       (partId) => channel.emit(EVENTS.PART_ENTER, { storyId, partId })
@@ -73,6 +75,7 @@ var withComponentAnatomy = (storyFn, context) => {
       channel.off(EVENTS.HOVER_ITEM, onHoverItem);
       channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
       channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);
+      offChange();
       offEnter();
       offLeave();
       controller.destroy();
@@ -81,8 +84,13 @@ var withComponentAnatomy = (storyFn, context) => {
   return storyFn();
 };
 var decorators = [withComponentAnatomy];
+var annotations = {
+  decorators: [withComponentAnatomy]
+};
+var preview_default = annotations;
 export {
   decorators,
+  preview_default as default,
   withComponentAnatomy
 };
 //# sourceMappingURL=preview.js.map

package/dist/preview.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/preview.ts", "../src/constants.ts", "../src/channel.ts"],
-  "sourcesContent": ["/**\n * Preview-side (iframe) entry. Registers a global decorator that mounts a\n * component-anatomy controller over the story canvas and syncs hover state\n * with the manager panel \u2014 and with any `<Anatomy>` doc block on the same\n * docs page \u2014 over the addon channel.\n *\n * The decorator runs in docs view too: the docs `Story` block renders each\n * story through `renderStoryToElement`, which sets `context.canvasElement`\n * exactly as it does in story view. That is what makes auto-discovery and\n * hover sync work inside MDX.\n */\nimport { addons, useEffect } from 'storybook/preview-api';\nimport type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';\nimport { createAnatomy } from '@component-anatomy/core';\n\nimport { EVENTS, PARAM_KEY } from './constants.js';\nimport { matchesStory } from './channel.js';\nimport type { HoverItemEvent, StoryScopedEvent } from './channel.js';\nimport type { AnatomyParameters } from './types.js';\n\nexport const withComponentAnatomy = (\n  storyFn: PartialStoryFn<Renderer>,\n  context: StoryContext<Renderer>\n) => {\n  const params = context.parameters?.[PARAM_KEY] as AnatomyParameters | undefined;\n\n  useEffect(() => {\n    if (!params || params.disable) return;\n\n    const channel = addons.getChannel();\n    const canvas = context.canvasElement as unknown as HTMLElement;\n    if (!canvas) return;\n\n    const storyId = context.id;\n\n    const root = params.root\n      ? canvas.querySelector<HTMLElement>(params.root) ?? canvas\n      : canvas;\n\n    const controller = createAnatomy({\n      root,\n      parts: params.parts,\n      preset: params.preset,\n      theme: params.theme,\n      overlay: {\n        label: params.overlayLabel !== false,\n        padding: params.overlayPadding,\n      },\n    });\n\n    const announceParts = () =>\n      channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });\n\n    announceParts();\n\n    const offEnter = controller.on('part:enter', (partId) =>\n      channel.emit(EVENTS.PART_ENTER, { storyId, partId })\n    );\n    const offLeave = controller.on('part:leave', () =>\n      channel.emit(EVENTS.PART_LEAVE, { storyId })\n    );\n\n    // A docs page mounts several stories at once, so every controller sees\n    // every panel/block event \u2014 only act on the ones addressed to this story.\n    const onHoverItem = (event: HoverItemEvent) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.highlight(event.partId);\n    };\n    const onLeaveItem = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.unhighlight();\n    };\n    const onPartsRequest = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      announceParts();\n    };\n\n    channel.on(EVENTS.HOVER_ITEM, onHoverItem);\n    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);\n    // The panel or block may mount after the story rendered \u2014 let it ask for\n    // the list rather than racing the first announcement.\n    channel.on(EVENTS.PARTS_REQUEST, onPartsRequest);\n\n    return () => {\n      channel.off(EVENTS.HOVER_ITEM, onHoverItem);\n      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);\n      channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);\n      offEnter();\n      offLeave();\n      controller.destroy();\n    };\n  }, [context.id]);\n\n  return storyFn();\n};\n\nexport const decorators = [withComponentAnatomy];\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/**\n * Channel events used to sync the manager panel \u2014 and the `<Anatomy>` MDX doc\n * block, which runs in the preview iframe \u2014 with the story canvas.\n *\n * Every payload carries the `storyId` it concerns; see `channel.ts` for the\n * payload types and the `matchesStory` filter each listener applies.\n */\nexport const EVENTS = {\n  /** preview \u2192 consumers: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 consumers: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 consumers: resolved part list for a story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** consumers \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** consumers \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** consumers \u2192 preview: a panel/block mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n", "/**\n * Shared channel payload contract between the preview decorator, the manager\n * panel, and the MDX doc block.\n *\n * Every payload carries the `storyId` it refers to. In story view this is\n * redundant \u2014 only one story is mounted \u2014 but a docs page mounts *many*\n * stories at once, each with its own controller, and each `<Anatomy>` block\n * must talk to exactly one of them. Without addressing, hovering a part in\n * one block highlights the matching part in every other story on the page.\n */\nimport type { AnatomyPartDefinition } from '@component-anatomy/core';\n\n/** preview \u2192 consumers: the resolved part list for one story. */\nexport type PartsEvent = { storyId?: string; parts: AnatomyPartDefinition[] };\n\n/** preview \u2192 consumers: a part became active in that story's canvas. */\nexport type PartEnterEvent = { storyId?: string; partId: string };\n\n/** consumer \u2192 preview: highlight this part in that story's canvas. */\nexport type HoverItemEvent = { storyId?: string; partId: string };\n\n/** Payload for the events that only need to name a story. */\nexport type StoryScopedEvent = { storyId?: string };\n\n/**\n * Whether an event addressed to `eventStoryId` concerns `storyId`.\n *\n * A missing id on *either* side matches everything. That keeps the protocol\n * backward compatible: a manager panel from a newer build still understands\n * an older preview bundle that emits unaddressed events, and vice versa.\n */\nexport const matchesStory = (\n  eventStoryId: string | undefined,\n  storyId: string | undefined\n): boolean => !eventStoryId || !storyId || eventStoryId === storyId;\n"],
-  "mappings": ";AAWA,SAAS,QAAQ,iBAAiB;AAElC,SAAS,qBAAqB;;;ACbvB,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AASlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;;;ACKO,IAAM,eAAe,CAC1B,cACA,YACY,CAAC,gBAAgB,CAAC,WAAW,iBAAiB;;;AFdrD,IAAM,uBAAuB,CAClC,SACA,YACG;AACH,QAAM,SAAS,QAAQ,aAAa,SAAS;AAE7C,YAAU,MAAM;AACd,QAAI,CAAC,UAAU,OAAO,QAAS;AAE/B,UAAM,UAAU,OAAO,WAAW;AAClC,UAAM,SAAS,QAAQ;AACvB,QAAI,CAAC,OAAQ;AAEb,UAAM,UAAU,QAAQ;AAExB,UAAM,OAAO,OAAO,OAChB,OAAO,cAA2B,OAAO,IAAI,KAAK,SAClD;AAEJ,UAAM,aAAa,cAAc;AAAA,MAC/B;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,OAAO,OAAO;AAAA,MACd,SAAS;AAAA,QACP,OAAO,OAAO,iBAAiB;AAAA,QAC/B,SAAS,OAAO;AAAA,MAClB;AAAA,IACF,CAAC;AAED,UAAM,gBAAgB,MACpB,QAAQ,KAAK,OAAO,OAAO,EAAE,SAAS,OAAO,WAAW,SAAS,EAAE,CAAC;AAEtE,kBAAc;AAEd,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,CAAC,WAC5C,QAAQ,KAAK,OAAO,YAAY,EAAE,SAAS,OAAO,CAAC;AAAA,IACrD;AACA,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,MAC3C,QAAQ,KAAK,OAAO,YAAY,EAAE,QAAQ,CAAC;AAAA,IAC7C;AAIA,UAAM,cAAc,CAAC,UAA0B;AAC7C,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,UAAU,MAAM,MAAM;AAAA,IACnC;AACA,UAAM,cAAc,CAAC,QAA0B,CAAC,MAAM;AACpD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,YAAY;AAAA,IACzB;AACA,UAAM,iBAAiB,CAAC,QAA0B,CAAC,MAAM;AACvD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,oBAAc;AAAA,IAChB;AAEA,YAAQ,GAAG,OAAO,YAAY,WAAW;AACzC,YAAQ,GAAG,OAAO,YAAY,WAAW;AAGzC,YAAQ,GAAG,OAAO,eAAe,cAAc;AAE/C,WAAO,MAAM;AACX,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,eAAe,cAAc;AAChD,eAAS;AACT,eAAS;AACT,iBAAW,QAAQ;AAAA,IACrB;AAAA,EACF,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEf,SAAO,QAAQ;AACjB;AAEO,IAAM,aAAa,CAAC,oBAAoB;",
+  "sourcesContent": ["/**\n * Preview-side (iframe) entry. Registers a global decorator that mounts a\n * component-anatomy controller over the story canvas and syncs hover state\n * with the manager panel \u2014 and with any `<Anatomy>` doc block on the same\n * docs page \u2014 over the addon channel.\n *\n * The decorator runs in docs view too: the docs `Story` block renders each\n * story through `renderStoryToElement`, which sets `context.canvasElement`\n * exactly as it does in story view. That is what makes auto-discovery and\n * hover sync work inside MDX.\n */\nimport { addons, useEffect } from 'storybook/preview-api';\nimport type {\n  ProjectAnnotations,\n  Renderer,\n  PartialStoryFn,\n  StoryContext,\n} from 'storybook/internal/types';\nimport { createAnatomy } from '@component-anatomy/core';\n\nimport { EVENTS, PARAM_KEY } from './constants.js';\nimport { matchesStory } from './channel.js';\nimport type { HoverItemEvent, StoryScopedEvent } from './channel.js';\nimport type { AnatomyParameters } from './types.js';\n\nexport const withComponentAnatomy = (\n  storyFn: PartialStoryFn<Renderer>,\n  context: StoryContext<Renderer>\n) => {\n  const params = context.parameters?.[PARAM_KEY] as AnatomyParameters | undefined;\n\n  useEffect(() => {\n    if (!params || params.disable) return;\n\n    const channel = addons.getChannel();\n    const canvas = context.canvasElement as unknown as HTMLElement;\n    if (!canvas) return;\n\n    const storyId = context.id;\n\n    const root = params.root\n      ? canvas.querySelector<HTMLElement>(params.root) ?? canvas\n      : canvas;\n\n    const controller = createAnatomy({\n      root,\n      parts: params.parts,\n      shadowParts: params.shadowParts,\n      preset: params.preset,\n      theme: params.theme,\n      overlay: {\n        label: params.overlayLabel !== false,\n        padding: params.overlayPadding,\n      },\n    });\n\n    const announceParts = () =>\n      channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });\n\n    announceParts();\n    // Parts can show up after this effect ran: a web component renders its\n    // shadow root asynchronously (Lit, Stencil), or is defined late.\n    const offChange = controller.on('parts:change', announceParts);\n\n    const offEnter = controller.on('part:enter', (partId) =>\n      channel.emit(EVENTS.PART_ENTER, { storyId, partId })\n    );\n    const offLeave = controller.on('part:leave', () =>\n      channel.emit(EVENTS.PART_LEAVE, { storyId })\n    );\n\n    // A docs page mounts several stories at once, so every controller sees\n    // every panel/block event \u2014 only act on the ones addressed to this story.\n    const onHoverItem = (event: HoverItemEvent) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.highlight(event.partId);\n    };\n    const onLeaveItem = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      controller.unhighlight();\n    };\n    const onPartsRequest = (event: StoryScopedEvent = {}) => {\n      if (!matchesStory(event?.storyId, storyId)) return;\n      announceParts();\n    };\n\n    channel.on(EVENTS.HOVER_ITEM, onHoverItem);\n    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);\n    // The panel or block may mount after the story rendered \u2014 let it ask for\n    // the list rather than racing the first announcement.\n    channel.on(EVENTS.PARTS_REQUEST, onPartsRequest);\n\n    return () => {\n      channel.off(EVENTS.HOVER_ITEM, onHoverItem);\n      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);\n      channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);\n      offChange();\n      offEnter();\n      offLeave();\n      controller.destroy();\n    };\n  }, [context.id]);\n\n  return storyFn();\n};\n\nexport const decorators = [withComponentAnatomy];\n\n/**\n * The same annotations as a default export, which is the shape\n * `definePreviewAddon` takes in the package's main entry (see `index.ts`) and\n * the shape a consumer gets from `@component-anatomy/storybook/preview`.\n *\n * Storybook reads `module.default[field] ?? module[field]`, so a preview\n * annotation module that exports both is read exactly once \u2014 the named\n * `decorators` above stays for anyone importing it directly.\n */\nconst annotations: ProjectAnnotations<Renderer> = {\n  decorators: [withComponentAnatomy],\n};\n\nexport default annotations;\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/**\n * Channel events used to sync the manager panel \u2014 and the `<Anatomy>` MDX doc\n * block, which runs in the preview iframe \u2014 with the story canvas.\n *\n * Every payload carries the `storyId` it concerns; see `channel.ts` for the\n * payload types and the `matchesStory` filter each listener applies.\n */\nexport const EVENTS = {\n  /** preview \u2192 consumers: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 consumers: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 consumers: resolved part list for a story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** consumers \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** consumers \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** consumers \u2192 preview: a panel/block mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n", "/**\n * Shared channel payload contract between the preview decorator, the manager\n * panel, and the MDX doc block.\n *\n * Every payload carries the `storyId` it refers to. In story view this is\n * redundant \u2014 only one story is mounted \u2014 but a docs page mounts *many*\n * stories at once, each with its own controller, and each `<Anatomy>` block\n * must talk to exactly one of them. Without addressing, hovering a part in\n * one block highlights the matching part in every other story on the page.\n */\nimport type { AnatomyPartDefinition } from '@component-anatomy/core';\n\n/** preview \u2192 consumers: the resolved part list for one story. */\nexport type PartsEvent = { storyId?: string; parts: AnatomyPartDefinition[] };\n\n/** preview \u2192 consumers: a part became active in that story's canvas. */\nexport type PartEnterEvent = { storyId?: string; partId: string };\n\n/** consumer \u2192 preview: highlight this part in that story's canvas. */\nexport type HoverItemEvent = { storyId?: string; partId: string };\n\n/** Payload for the events that only need to name a story. */\nexport type StoryScopedEvent = { storyId?: string };\n\n/**\n * Whether an event addressed to `eventStoryId` concerns `storyId`.\n *\n * A missing id on *either* side matches everything. That keeps the protocol\n * backward compatible: a manager panel from a newer build still understands\n * an older preview bundle that emits unaddressed events, and vice versa.\n */\nexport const matchesStory = (\n  eventStoryId: string | undefined,\n  storyId: string | undefined\n): boolean => !eventStoryId || !storyId || eventStoryId === storyId;\n"],
+  "mappings": ";AAWA,SAAS,QAAQ,iBAAiB;AAOlC,SAAS,qBAAqB;;;AClBvB,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AASlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;;;ACKO,IAAM,eAAe,CAC1B,cACA,YACY,CAAC,gBAAgB,CAAC,WAAW,iBAAiB;;;AFTrD,IAAM,uBAAuB,CAClC,SACA,YACG;AACH,QAAM,SAAS,QAAQ,aAAa,SAAS;AAE7C,YAAU,MAAM;AACd,QAAI,CAAC,UAAU,OAAO,QAAS;AAE/B,UAAM,UAAU,OAAO,WAAW;AAClC,UAAM,SAAS,QAAQ;AACvB,QAAI,CAAC,OAAQ;AAEb,UAAM,UAAU,QAAQ;AAExB,UAAM,OAAO,OAAO,OAChB,OAAO,cAA2B,OAAO,IAAI,KAAK,SAClD;AAEJ,UAAM,aAAa,cAAc;AAAA,MAC/B;AAAA,MACA,OAAO,OAAO;AAAA,MACd,aAAa,OAAO;AAAA,MACpB,QAAQ,OAAO;AAAA,MACf,OAAO,OAAO;AAAA,MACd,SAAS;AAAA,QACP,OAAO,OAAO,iBAAiB;AAAA,QAC/B,SAAS,OAAO;AAAA,MAClB;AAAA,IACF,CAAC;AAED,UAAM,gBAAgB,MACpB,QAAQ,KAAK,OAAO,OAAO,EAAE,SAAS,OAAO,WAAW,SAAS,EAAE,CAAC;AAEtE,kBAAc;AAGd,UAAM,YAAY,WAAW,GAAG,gBAAgB,aAAa;AAE7D,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,CAAC,WAC5C,QAAQ,KAAK,OAAO,YAAY,EAAE,SAAS,OAAO,CAAC;AAAA,IACrD;AACA,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,MAC3C,QAAQ,KAAK,OAAO,YAAY,EAAE,QAAQ,CAAC;AAAA,IAC7C;AAIA,UAAM,cAAc,CAAC,UAA0B;AAC7C,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,UAAU,MAAM,MAAM;AAAA,IACnC;AACA,UAAM,cAAc,CAAC,QAA0B,CAAC,MAAM;AACpD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,iBAAW,YAAY;AAAA,IACzB;AACA,UAAM,iBAAiB,CAAC,QAA0B,CAAC,MAAM;AACvD,UAAI,CAAC,aAAa,OAAO,SAAS,OAAO,EAAG;AAC5C,oBAAc;AAAA,IAChB;AAEA,YAAQ,GAAG,OAAO,YAAY,WAAW;AACzC,YAAQ,GAAG,OAAO,YAAY,WAAW;AAGzC,YAAQ,GAAG,OAAO,eAAe,cAAc;AAE/C,WAAO,MAAM;AACX,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,eAAe,cAAc;AAChD,gBAAU;AACV,eAAS;AACT,eAAS;AACT,iBAAW,QAAQ;AAAA,IACrB;AAAA,EACF,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEf,SAAO,QAAQ;AACjB;AAEO,IAAM,aAAa,CAAC,oBAAoB;AAW/C,IAAM,cAA4C;AAAA,EAChD,YAAY,CAAC,oBAAoB;AACnC;AAEA,IAAO,kBAAQ;",
   "names": []
 }

package/dist/types.d.ts

@@ -17,7 +17,8 @@ import type { AnatomyPartDefinition, AnatomyPresetName, AnatomyTheme } from '@co
 export type AnatomyParameters = {
     /**
      * Part definitions. If omitted, parts are auto-discovered from
-     * `data-part` attributes in the rendered story.
+     * `data-part` attributes in the rendered story, including inside open
+     * shadow roots.
      */
     parts?: AnatomyPartDefinition[];
     /** Named visual preset for the canvas overlays. Default: 'default'. */
@@ -28,6 +29,11 @@ export type AnatomyParameters = {
     overlayLabel?: boolean;
     /** Inflate highlight boxes by N pixels. Default: 0. */
     overlayPadding?: number;
+    /**
+     * Also treat the native `part` attribute (CSS Shadow Parts) on elements
+     * inside a web component's open shadow root as a part id. Default: false.
+     */
+    shadowParts?: boolean;
     /**
      * CSS selector to narrow the anatomy root inside the story canvas.
      * Defaults to the whole canvas element.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAChC,uEAAuE;IACvE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAChC,uEAAuE;IACvE,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@component-anatomy/storybook",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Storybook addon — interactive component anatomy panel synced with the story canvas",
   "license": "MIT",
   "author": "Julien Déramond",
@@ -37,18 +37,23 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     },
     "./blocks": {
       "types": "./dist/blocks.d.ts",
-      "import": "./dist/blocks.js"
+      "default": "./dist/blocks.js"
+    },
+    "./manager": {
+      "types": "./dist/manager.d.ts",
+      "default": "./dist/manager.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.js"
     },
-    "./manager": "./dist/manager.js",
-    "./preview": "./dist/preview.js",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -60,21 +65,21 @@
     "access": "public"
   },
   "dependencies": {
-    "@component-anatomy/core": "^0.1.0"
+    "@component-anatomy/core": "^0.2.0"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^10.5.2",
-    "@types/react": "^19.2.18",
+    "@storybook/addon-docs": "11.0.0-alpha.1",
+    "@types/react": "^19.3.0",
     "esbuild": "^0.28.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "storybook": "^10.5.10",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "storybook": "11.0.0-alpha.1",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@storybook/addon-docs": ">=9.0.0",
+    "@storybook/addon-docs": "^10.0.0 || ^11.0.0-0",
     "react": ">=18",
-    "storybook": ">=9.0.0"
+    "storybook": "^10.0.0 || ^11.0.0-0"
   },
   "peerDependenciesMeta": {
     "@storybook/addon-docs": {
@@ -90,6 +95,6 @@
   "scripts": {
     "build": "node build.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node build.mjs && node ../../scripts/typecheck-fixture.mjs test/consumer-types.ts && node ../../scripts/typecheck-fixture.mjs test/consumer-blocks-types.tsx"
+    "test": "node build.mjs && node ../../scripts/typecheck-fixture.mjs test/consumer-types.ts && node ../../scripts/typecheck-fixture.mjs test/consumer-blocks-types.tsx && node ../../scripts/typecheck-fixture.mjs test/consumer-csf-next-types.ts"
   }
 }

package/src/index.ts

@@ -1,7 +1,46 @@
+import { definePreviewAddon } from 'storybook/internal/csf';
+
+import annotations from './preview.js';
+import type { AnatomyParameters } from './types.js';
+
 export { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';
 export type { AnatomyParameters } from './types.js';
 
-// The `<Anatomy>` doc block lives in the `./blocks` subpath, not here: this
-// entry is loaded at config time by `.storybook/main.ts` (and built to CJS),
-// while the block needs React and `@storybook/addon-docs`, both optional
-// peers that must not become load-bearing for `addons: ['...']` to work.
+/**
+ * What this addon contributes to a CSF Next project's type context: a typed
+ * `parameters.anatomy` on every meta and story of a preview that registers it.
+ */
+export type ComponentAnatomyTypes = {
+  parameters: {
+    /** @see {@link AnatomyParameters} */
+    anatomy?: AnatomyParameters;
+  };
+};
+
+/**
+ * The addon's preview annotations, for a CSF Next `preview.ts`:
+ *
+ * ```ts
+ * import { definePreview } from '@storybook/your-framework';
+ * import componentAnatomy from '@component-anatomy/storybook';
+ *
+ * export default definePreview({
+ *   addons: [componentAnatomy()],
+ * });
+ * ```
+ *
+ * `.storybook/main.ts` must still list the addon — `addons:
+ * ['@component-anatomy/storybook']` — since that is what loads the manager
+ * panel. What changes under CSF Next is the preview side: a `preview.ts` built
+ * with `definePreview` composes *only* its own `addons`, and Storybook drops
+ * every addon annotation main.ts would otherwise have contributed. Without the
+ * call below, the canvas decorator never mounts and the panel stays empty.
+ *
+ * Registering in both places is safe — the two paths are mutually exclusive,
+ * so the decorator is composed once either way.
+ *
+ * The `./blocks` subpath, not this entry, holds the `<Anatomy>` MDX block: it
+ * needs React and `@storybook/addon-docs`, both optional peers that must not
+ * become load-bearing for a Storybook that only wants the panel.
+ */
+export default () => definePreviewAddon<ComponentAnatomyTypes>(annotations);

package/src/preview.ts

@@ -10,7 +10,12 @@
  * hover sync work inside MDX.
  */
 import { addons, useEffect } from 'storybook/preview-api';
-import type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';
+import type {
+  ProjectAnnotations,
+  Renderer,
+  PartialStoryFn,
+  StoryContext,
+} from 'storybook/internal/types';
 import { createAnatomy } from '@component-anatomy/core';
 
 import { EVENTS, PARAM_KEY } from './constants.js';
@@ -40,6 +45,7 @@ export const withComponentAnatomy = (
     const controller = createAnatomy({
       root,
       parts: params.parts,
+      shadowParts: params.shadowParts,
       preset: params.preset,
       theme: params.theme,
       overlay: {
@@ -52,6 +58,9 @@ export const withComponentAnatomy = (
       channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });
 
     announceParts();
+    // Parts can show up after this effect ran: a web component renders its
+    // shadow root asynchronously (Lit, Stencil), or is defined late.
+    const offChange = controller.on('parts:change', announceParts);
 
     const offEnter = controller.on('part:enter', (partId) =>
       channel.emit(EVENTS.PART_ENTER, { storyId, partId })
@@ -85,6 +94,7 @@ export const withComponentAnatomy = (
       channel.off(EVENTS.HOVER_ITEM, onHoverItem);
       channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
       channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);
+      offChange();
       offEnter();
       offLeave();
       controller.destroy();
@@ -95,3 +105,18 @@ export const withComponentAnatomy = (
 };
 
 export const decorators = [withComponentAnatomy];
+
+/**
+ * The same annotations as a default export, which is the shape
+ * `definePreviewAddon` takes in the package's main entry (see `index.ts`) and
+ * the shape a consumer gets from `@component-anatomy/storybook/preview`.
+ *
+ * Storybook reads `module.default[field] ?? module[field]`, so a preview
+ * annotation module that exports both is read exactly once — the named
+ * `decorators` above stays for anyone importing it directly.
+ */
+const annotations: ProjectAnnotations<Renderer> = {
+  decorators: [withComponentAnatomy],
+};
+
+export default annotations;

package/src/types.ts

@@ -22,7 +22,8 @@ import type {
 export type AnatomyParameters = {
   /**
    * Part definitions. If omitted, parts are auto-discovered from
-   * `data-part` attributes in the rendered story.
+   * `data-part` attributes in the rendered story, including inside open
+   * shadow roots.
    */
   parts?: AnatomyPartDefinition[];
   /** Named visual preset for the canvas overlays. Default: 'default'. */
@@ -33,6 +34,11 @@ export type AnatomyParameters = {
   overlayLabel?: boolean;
   /** Inflate highlight boxes by N pixels. Default: 0. */
   overlayPadding?: number;
+  /**
+   * Also treat the native `part` attribute (CSS Shadow Parts) on elements
+   * inside a web component's open shadow root as a part id. Default: false.
+   */
+  shadowParts?: boolean;
   /**
    * CSS selector to narrow the anatomy root inside the story canvas.
    * Defaults to the whole canvas element.

package/dist/index.cjs

@@ -1,48 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  ADDON_ID: () => ADDON_ID,
-  EVENTS: () => EVENTS,
-  PANEL_ID: () => PANEL_ID,
-  PARAM_KEY: () => PARAM_KEY
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/constants.ts
-var ADDON_ID = "component-anatomy";
-var PANEL_ID = `${ADDON_ID}/panel`;
-var PARAM_KEY = "anatomy";
-var EVENTS = {
-  /** preview → consumers: a part became active in the canvas (hover/programmatic). */
-  PART_ENTER: `${ADDON_ID}/part-enter`,
-  /** preview → consumers: no part is active anymore. */
-  PART_LEAVE: `${ADDON_ID}/part-leave`,
-  /** preview → consumers: resolved part list for a story. */
-  PARTS: `${ADDON_ID}/parts`,
-  /** consumers → preview: the user hovers/focuses a panel entry. */
-  HOVER_ITEM: `${ADDON_ID}/hover-item`,
-  /** consumers → preview: the user left a panel entry. */
-  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
-  /** consumers → preview: a panel/block mounted and wants the current part list. */
-  PARTS_REQUEST: `${ADDON_ID}/parts-request`
-};
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/index.ts", "../src/constants.ts"],
-  "sourcesContent": ["export { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';\nexport type { AnatomyParameters } from './types.js';\n\n// The `<Anatomy>` doc block lives in the `./blocks` subpath, not here: this\n// entry is loaded at config time by `.storybook/main.ts` (and built to CJS),\n// while the block needs React and `@storybook/addon-docs`, both optional\n// peers that must not become load-bearing for `addons: ['...']` to work.\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/**\n * Channel events used to sync the manager panel \u2014 and the `<Anatomy>` MDX doc\n * block, which runs in the preview iframe \u2014 with the story canvas.\n *\n * Every payload carries the `storyId` it concerns; see `channel.ts` for the\n * payload types and the `matchesStory` filter each listener applies.\n */\nexport const EVENTS = {\n  /** preview \u2192 consumers: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 consumers: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 consumers: resolved part list for a story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** consumers \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** consumers \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** consumers \u2192 preview: a panel/block mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AASlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;",
-  "names": []
-}