@component-anatomy/storybook 0.0.2 → 0.2.0

package/src/constants.ts

@@ -4,18 +4,24 @@ export const PANEL_ID = `${ADDON_ID}/panel`;
 /** Story parameter key: `parameters.anatomy = { ... }` */
 export const PARAM_KEY = 'anatomy';
 
-/** Channel events used to sync the manager panel with the preview iframe. */
+/**
+ * Channel events used to sync the manager panel — and the `<Anatomy>` MDX doc
+ * block, which runs in the preview iframe — with the story canvas.
+ *
+ * Every payload carries the `storyId` it concerns; see `channel.ts` for the
+ * payload types and the `matchesStory` filter each listener applies.
+ */
 export const EVENTS = {
-  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  /** preview → consumers: a part became active in the canvas (hover/programmatic). */
   PART_ENTER: `${ADDON_ID}/part-enter`,
-  /** preview → manager: no part is active anymore. */
+  /** preview → consumers: no part is active anymore. */
   PART_LEAVE: `${ADDON_ID}/part-leave`,
-  /** preview → manager: resolved part list for the current story. */
+  /** preview → consumers: resolved part list for a story. */
   PARTS: `${ADDON_ID}/parts`,
-  /** manager → preview: the user hovers/focuses a panel entry. */
+  /** consumers → preview: the user hovers/focuses a panel entry. */
   HOVER_ITEM: `${ADDON_ID}/hover-item`,
-  /** manager → preview: the user left a panel entry. */
+  /** consumers → preview: the user left a panel entry. */
   LEAVE_ITEM: `${ADDON_ID}/leave-item`,
-  /** manager → preview: the panel mounted and wants the current part list. */
+  /** consumers → preview: a panel/block mounted and wants the current part list. */
   PARTS_REQUEST: `${ADDON_ID}/parts-request`,
 } as const;

package/src/index.ts

@@ -1,2 +1,7 @@
 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.

package/src/preview.ts

@@ -1,13 +1,21 @@
 /**
  * Preview-side (iframe) entry. Registers a global decorator that mounts a
  * component-anatomy controller over the story canvas and syncs hover state
- * with the manager panel over the addon channel.
+ * with the manager panel — and with any `<Anatomy>` doc block on the same
+ * docs page — over the addon channel.
+ *
+ * The decorator runs in docs view too: the docs `Story` block renders each
+ * story through `renderStoryToElement`, which sets `context.canvasElement`
+ * exactly as it does in story view. That is what makes auto-discovery and
+ * hover sync work inside MDX.
  */
 import { addons, useEffect } from 'storybook/preview-api';
 import type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';
 import { createAnatomy } from '@component-anatomy/core';
 
 import { EVENTS, PARAM_KEY } from './constants.js';
+import { matchesStory } from './channel.js';
+import type { HoverItemEvent, StoryScopedEvent } from './channel.js';
 import type { AnatomyParameters } from './types.js';
 
 export const withComponentAnatomy = (
@@ -23,6 +31,8 @@ export const withComponentAnatomy = (
     const canvas = context.canvasElement as unknown as HTMLElement;
     if (!canvas) return;
 
+    const storyId = context.id;
+
     const root = params.root
       ? canvas.querySelector<HTMLElement>(params.root) ?? canvas
       : canvas;
@@ -39,29 +49,42 @@ export const withComponentAnatomy = (
     });
 
     const announceParts = () =>
-      channel.emit(EVENTS.PARTS, { storyId: context.id, parts: controller.getParts() });
+      channel.emit(EVENTS.PARTS, { storyId, parts: controller.getParts() });
 
     announceParts();
 
     const offEnter = controller.on('part:enter', (partId) =>
-      channel.emit(EVENTS.PART_ENTER, { partId })
+      channel.emit(EVENTS.PART_ENTER, { storyId, partId })
     );
     const offLeave = controller.on('part:leave', () =>
-      channel.emit(EVENTS.PART_LEAVE, {})
+      channel.emit(EVENTS.PART_LEAVE, { storyId })
     );
 
-    const onHoverItem = ({ partId }: { partId: string }) => controller.highlight(partId);
-    const onLeaveItem = () => controller.unhighlight();
+    // A docs page mounts several stories at once, so every controller sees
+    // every panel/block event — only act on the ones addressed to this story.
+    const onHoverItem = (event: HoverItemEvent) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      controller.highlight(event.partId);
+    };
+    const onLeaveItem = (event: StoryScopedEvent = {}) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      controller.unhighlight();
+    };
+    const onPartsRequest = (event: StoryScopedEvent = {}) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      announceParts();
+    };
 
     channel.on(EVENTS.HOVER_ITEM, onHoverItem);
     channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);
-    // The panel may mount after the story rendered — let it ask for the list.
-    channel.on(EVENTS.PARTS_REQUEST, announceParts);
+    // The panel or block may mount after the story rendered — let it ask for
+    // the list rather than racing the first announcement.
+    channel.on(EVENTS.PARTS_REQUEST, onPartsRequest);
 
     return () => {
       channel.off(EVENTS.HOVER_ITEM, onHoverItem);
       channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
-      channel.off(EVENTS.PARTS_REQUEST, announceParts);
+      channel.off(EVENTS.PARTS_REQUEST, onPartsRequest);
       offEnter();
       offLeave();
       controller.destroy();