@repobuddy/storybook 2.21.0 → 2.22.0

package/esm/index.d.ts

@@ -9,7 +9,7 @@ import { Args, DecoratorFunction, Renderer } from "storybook/internal/csf";
 import { Decorator, Meta, StoryContext, StoryObj, StrictArgs } from "@storybook/react-vite";
 export * from "@repobuddy/test";
 
-//#region src/arg-types/fn-to-arg-types.d.ts
+//#region src/arg-types/fn-to-arg.types.d.ts
 /**
  * Converts a function's parameter types to `Args` type for Storybook.
  * Each name maps to the parameter type at the same index in F.
@@ -97,28 +97,43 @@ type StoryCardThemeState = Pick<StoryCardProps, 'status' | 'appearance'> & {
  */
 declare const StoryCard: react.NamedExoticComponent<StoryCardProps>;
 //#endregion
-//#region src/decorators/show_doc_source.d.ts
+//#region src/decorators/show_source.d.ts
+/**
+ * Options for the {@link showSource} decorator.
+ *
+ * @property className - Class name to apply to the source card. Can be a string or a function that receives the card state and returns a string.
+ * @property source - Source code to display. A string, or a function `(originalSource) => string` that receives the story's original source and returns the code to show. Defaults to the story's docs source.
+ * @property showOriginalSource - When true, use the story's original (untransformed) source instead of the rendered source.
+ * @property placement - Where to show the source code relative to the story. Defaults to `'before'`.
+ */
+type ShowSourceOptions = Pick<StoryCardProps, 'className'> & {
+  source?: ((source: string | undefined) => string) | string | undefined;
+  showOriginalSource?: boolean | undefined;
+  placement?: 'before' | 'after' | undefined;
+};
 /**
- * A decorator that shows the source code of a story above the rendered story.
+ * A decorator that shows the source code of a story relative to the rendered story.
  * The source code is taken from the story's `parameters.docs.source.code`.
  *
- * @param options - Options for the showDocSource decorator
+ * @param options - Options for the showSource decorator
  * @param options.showOriginalSource - Whether to show the original source code in a card
  * @param options.className - Class name to apply to the card
  * @param options.source - Source code to show. Can be a string, or a function `(originalSource) => string` that receives the story's original source and returns the code to display.
  * @param options.placement - Where to show the source code relative to the story.
  * @returns A decorator function that shows the source code of a story above or below the rendered story
  */
-declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(options?: Pick<StoryCardProps, 'className'> & {
-  source?: ((source: string | undefined) => string) | string | undefined;
-  showOriginalSource?: boolean | undefined;
-  /**
-   * Where to show the source code relative to the story.
-   *
-   * @default 'after'
-   */
-  placement?: 'before' | 'after' | undefined;
-}): DecoratorFunction<TRenderer, TArgs>;
+declare function showSource<TRenderer extends Renderer = Renderer, TArgs = Args>(options?: ShowSourceOptions): DecoratorFunction<TRenderer, TArgs>;
+//#endregion
+//#region src/decorators/show_doc_source.d.ts
+/**
+ * A decorator that shows the source code of a story below the rendered story.
+ * Uses {@link showSource} with `placement: 'after'`.
+ *
+ * @deprecated Use `showSource({ placement: 'after' })` instead.
+ * @param options - Same options as showSource; placement is forced to 'after'
+ * @returns A decorator function that shows the source code below the story
+ */
+declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(options?: ShowSourceOptions): DecoratorFunction<TRenderer, TArgs>;
 //#endregion
 //#region src/decorators/with_story_card.d.ts
 type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
@@ -935,4 +950,4 @@ type ExtendStoryObj<TMetaOrCmpOrArgs, S extends StoryObj<TMetaOrCmpOrArgs>, E ex
   tags?: Array<E['tag'] | (string & {})> | undefined;
 };
 //#endregion
-export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, SourceProps, StoryCard, StoryCardAppearance, StoryCardParam, StoryCardProps, StoryCardStatus, StoryCardThemeState, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };
+export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, ShowSourceOptions, SourceProps, StoryCard, StoryCardAppearance, StoryCardParam, StoryCardProps, StoryCardStatus, StoryCardThemeState, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };

package/esm/index.js

@@ -2,7 +2,7 @@
 import { isRunningInTest } from "@repobuddy/test";
 import { prettify } from "htmlfy";
 import { createContext, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
 import { twJoin, twMerge } from "tailwind-merge";
 import { SyntaxHighlighter } from "storybook/internal/components";
@@ -108,6 +108,17 @@ const StoryCardScope = memo(function StoryCardScope(props) {
 	if (context === null) return /* @__PURE__ */ jsx(StoryCardContainer, { children: collector });
 	return collector;
 });
+/** Renders cards from registry state without re-rendering when only children change (avoids cascade). */
+const StoryCardList = memo(function StoryCardList({ cards }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: cards.map(({ content, key, ...rest }) => /* @__PURE__ */ jsx(StoryCard, {
+		...rest,
+		children: content
+	}, key)) });
+});
+/** Keeps container children from re-rendering when container state (cards) updates. */
+const StableScopeChildren = memo(function StableScopeChildren({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children });
+});
 function StoryCardContainer({ children }) {
 	const [cards, setCards] = useState([]);
 	const contextValue = useMemo(() => ({
@@ -133,13 +144,13 @@ function StoryCardContainer({ children }) {
 		value: contextValue,
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "rbsb:flex rbsb:flex-col rbsb:gap-2",
-			children: [cards.map(({ content, key, ...rest }) => /* @__PURE__ */ jsx(StoryCard, {
-				...rest,
-				children: content
-			}, key)), children]
+			children: [/* @__PURE__ */ jsx(StoryCardList, { cards }), /* @__PURE__ */ jsx(StableScopeChildren, { children })]
 		})
 	});
 }
+function entryPropsEqual(a, b) {
+	return a.Story === b.Story && a.title === b.title && a.status === b.status && a.appearance === b.appearance && a.className === b.className && a.content === b.content;
+}
 const StoryCardCollector = memo(function StoryCardCollector({ Story, title, status, appearance, className, content }) {
 	const context = useContext(StoryCardRegistryContext);
 	const cardIdRef = useRef(null);
@@ -169,23 +180,23 @@ const StoryCardCollector = memo(function StoryCardCollector({ Story, title, stat
 		if (cardIdRef.current !== null) context.update(cardIdRef.current, entry);
 	}, [context, entry]);
 	return /* @__PURE__ */ jsx(Story, {});
-}, (prev, next) => prev.Story === next.Story);
+}, entryPropsEqual);
 
 //#endregion
-//#region src/decorators/show_doc_source.tsx
+//#region src/decorators/show_source.tsx
 const channel = addons.getChannel();
 /**
-* A decorator that shows the source code of a story above the rendered story.
+* A decorator that shows the source code of a story relative to the rendered story.
 * The source code is taken from the story's `parameters.docs.source.code`.
 *
-* @param options - Options for the showDocSource decorator
+* @param options - Options for the showSource decorator
 * @param options.showOriginalSource - Whether to show the original source code in a card
 * @param options.className - Class name to apply to the card
 * @param options.source - Source code to show. Can be a string, or a function `(originalSource) => string` that receives the story's original source and returns the code to display.
 * @param options.placement - Where to show the source code relative to the story.
 * @returns A decorator function that shows the source code of a story above or below the rendered story
 */
-function showDocSource(options) {
+function showSource(options) {
 	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters: { docs, darkMode } }) => {
 		const storedItem = window.localStorage.getItem("sb-addon-themes-3");
@@ -204,7 +215,7 @@ function showDocSource(options) {
 			language,
 			children: code
 		}), [code, language]);
-		const showBefore = options?.placement === "before";
+		const showBefore = (options?.placement ?? "before") === "before";
 		const sourceCardClassName = useCallback((state) => {
 			const modifiedState = {
 				...state,
@@ -217,21 +228,15 @@ function showDocSource(options) {
 		function DocSourceCard({ children }) {
 			return /* @__PURE__ */ jsx("div", { children });
 		}
-		const scopeContent = useMemo(() => /* @__PURE__ */ jsx(DocSourceCard, { children: sourceContent }), [sourceContent]);
-		const scopeProps = useMemo(() => ({
+		if (isRunningInTest()) return /* @__PURE__ */ jsx(Story, {});
+		if (showBefore) return /* @__PURE__ */ jsx(StoryCardScope, {
 			Story,
-			content: scopeContent,
+			content: /* @__PURE__ */ jsx(ThemeProvider, {
+				theme,
+				children: /* @__PURE__ */ jsx(DocSourceCard, { children: sourceContent })
+			}),
 			className: sourceCardClassName,
 			appearance: "source"
-		}), [
-			Story,
-			scopeContent,
-			sourceCardClassName
-		]);
-		if (isRunningInTest()) return /* @__PURE__ */ jsx(Story, {});
-		if (showBefore) return /* @__PURE__ */ jsx(ThemeProvider, {
-			theme,
-			children: /* @__PURE__ */ jsx(StoryCardScope, { ...scopeProps })
 		});
 		return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme,
@@ -251,6 +256,23 @@ function showDocSource(options) {
 	};
 }
 
+//#endregion
+//#region src/decorators/show_doc_source.tsx
+/**
+* A decorator that shows the source code of a story below the rendered story.
+* Uses {@link showSource} with `placement: 'after'`.
+*
+* @deprecated Use `showSource({ placement: 'after' })` instead.
+* @param options - Same options as showSource; placement is forced to 'after'
+* @returns A decorator function that shows the source code below the story
+*/
+function showDocSource(options) {
+	return showSource({
+		placement: "after",
+		...options
+	});
+}
+
 //#endregion
 //#region src/decorators/with_story_card.tsx
 /**
@@ -335,6 +357,7 @@ function showDocSource(options) {
 function withStoryCard({ title, status, appearance, content: contentProp, className, ...rest } = {}) {
 	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters, viewMode }) => {
+		if (viewMode === "docs") return /* @__PURE__ */ jsx(Story, {});
 		const storyCardParam = parameters.storyCard;
 		const finalTitle = title ?? storyCardParam?.title;
 		const finalAppearance = appearance ?? storyCardParam?.appearance ?? status ?? storyCardParam?.status ?? "info";
@@ -342,7 +365,8 @@ function withStoryCard({ title, status, appearance, content: contentProp, classN
 		const finalContent = contentProp ?? storyCardParam?.content;
 		const finalClassName = className ?? storyCardParam?.className;
 		const content = finalContent ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component;
-		const scopeProps = useMemo(() => ({
+		if (!content && !finalTitle) return /* @__PURE__ */ jsx(Story, {});
+		return /* @__PURE__ */ jsx(StoryCardScope, {
 			Story,
 			content,
 			title: finalTitle,
@@ -350,18 +374,7 @@ function withStoryCard({ title, status, appearance, content: contentProp, classN
 			appearance: finalAppearance,
 			className: finalClassName,
 			...rest
-		}), [
-			Story,
-			content,
-			finalTitle,
-			finalStatus,
-			finalAppearance,
-			finalClassName,
-			rest
-		]);
-		if (viewMode === "docs") return /* @__PURE__ */ jsx(Story, {});
-		if (!content && !finalTitle) return /* @__PURE__ */ jsx(Story, {});
-		return /* @__PURE__ */ jsx(StoryCardScope, { ...scopeProps });
+		});
 	};
 }
 
@@ -594,4 +607,4 @@ function whenRunningInTest(decoratorOrHandler) {
 }
 
 //#endregion
-export { ShowHtml, StoryCard, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };
+export { ShowHtml, StoryCard, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCardParam, defineTestParam, defineViewportParam, showDocSource, showSource, whenRunningInTest, withStoryCard };

package/esm/storybook-addon-tag-badges/index.d.ts

@@ -8,7 +8,7 @@ type TagBadgeParameter = TagBadgeParameters[0];
 /**
  * Type representing the names of predefined tags used in Storybook stories.
  */
-type TagNames = '!test' | 'editor' | 'source' | 'type' | '!type' | 'func' | '!func' | 'var' | '!var' | 'new' | 'alpha' | 'beta' | 'rc' | 'props' | 'deprecated' | 'outdated' | 'danger' | 'todo' | 'code-only' | 'snapshot' | '!snapshot' | 'unit' | 'integration' | 'keyboard' | 'internal' | 'usecase' | 'use-case' | 'example' | 'version:next' | 'remove' | 'remove:next' | 'autodocs';
+type TagNames = '!test' | 'editor' | 'source' | 'type' | '!type' | 'func' | '!func' | 'var' | '!var' | 'new' | 'alpha' | 'beta' | 'rc' | 'props' | 'deprecated' | 'outdated' | 'danger' | 'todo' | 'code-only' | 'snapshot' | '!snapshot' | 'unit' | 'integration' | 'keyboard' | 'internal' | 'usecase' | 'use-case' | 'example' | 'perf' | 'version:next' | 'remove' | 'remove:next' | 'autodocs';
 /** Badge (✏️) for stories with a live editor. Shown in sidebar on story and inherited. */
 declare const editorBadge: TagBadgeParameter;
 /** Badge (🆕) for recently added stories. */
@@ -55,12 +55,14 @@ declare const internalBadge: TagBadgeParameter;
 declare const useCaseBadge: TagBadgeParameter;
 /** Badge (✨) for example or demo stories. */
 declare const exampleBadge: TagBadgeParameter;
+/** Badge (⚡) for stories that demonstrate or test performance. */
+declare const perfBadge: TagBadgeParameter;
 /**
  * Configuration for story tag badges that appear in the Storybook sidebar.
  * Each badge is associated with a specific tag and displays an emoji or symbol with a tooltip.
  *
  * Badge order (first match wins): New → Alpha → Beta → RC → Deprecated → Remove → Outdated → Danger → Use Case →
- * Example → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
+ * Example → Perf → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
  * Editor → Code Only → Version → Internal → Snapshot.
  *
  * - 🆕 New - Recently added stories
@@ -73,6 +75,7 @@ declare const exampleBadge: TagBadgeParameter;
  * - 🚨 Danger - Stories demonstrating dangerous patterns
  * - 🎯 Use Case - Stories that demonstrate a specific use case or scenario
  * - ✨ Example - Example or demo stories
+ * - ⚡ Perf - Stories that demonstrate or test performance
  * - ⌨️ Keyboard - Stories that demonstrate or test keyboard interaction
  * - `</>` Source - Source-code-focused stories
  * - `<T>` Type - Stories that showcase or document TypeScript types
@@ -162,4 +165,4 @@ type StoryObj<TMetaOrCmpOrArgs = Args> = ExtendStoryObj<TMetaOrCmpOrArgs, StoryO
   tag: TagNames;
 }>;
 //#endregion
-export { Meta, StoryObj, TagNames, alphaBadge, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, exampleBadge, functionBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, rcBadge, removeBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, typeBadge, unitBadge, useCaseBadge, varBadge };
+export { Meta, StoryObj, TagNames, alphaBadge, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, exampleBadge, functionBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, perfBadge, propsBadge, rcBadge, removeBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, typeBadge, unitBadge, useCaseBadge, varBadge };

package/esm/storybook-addon-tag-badges/index.js

@@ -331,12 +331,28 @@ const exampleBadge = {
 		skipInherited: false
 	} }
 };
+/** Badge (⚡) for stories that demonstrate or test performance. */
+const perfBadge = {
+	tags: "perf",
+	badge: {
+		text: "⚡",
+		style: {
+			backgroundColor: "transparent",
+			borderColor: "transparent"
+		},
+		tooltip: "Performance"
+	},
+	display: { sidebar: {
+		type: "story",
+		skipInherited: false
+	} }
+};
 /**
 * Configuration for story tag badges that appear in the Storybook sidebar.
 * Each badge is associated with a specific tag and displays an emoji or symbol with a tooltip.
 *
 * Badge order (first match wins): New → Alpha → Beta → RC → Deprecated → Remove → Outdated → Danger → Use Case →
-* Example → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
+* Example → Perf → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
 * Editor → Code Only → Version → Internal → Snapshot.
 *
 * - 🆕 New - Recently added stories
@@ -349,6 +365,7 @@ const exampleBadge = {
 * - 🚨 Danger - Stories demonstrating dangerous patterns
 * - 🎯 Use Case - Stories that demonstrate a specific use case or scenario
 * - ✨ Example - Example or demo stories
+* - ⚡ Perf - Stories that demonstrate or test performance
 * - ⌨️ Keyboard - Stories that demonstrate or test keyboard interaction
 * - `</>` Source - Source-code-focused stories
 * - `<T>` Type - Stories that showcase or document TypeScript types
@@ -376,6 +393,7 @@ const tagBadges = [
 	dangerBadge,
 	useCaseBadge,
 	exampleBadge,
+	perfBadge,
 	keyboardBadge,
 	sourceBadge,
 	typeBadge,
@@ -393,4 +411,4 @@ const tagBadges = [
 ];
 
 //#endregion
-export { alphaBadge, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, exampleBadge, functionBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, rcBadge, removeBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, typeBadge, unitBadge, useCaseBadge, varBadge };
+export { alphaBadge, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, exampleBadge, functionBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, perfBadge, propsBadge, rcBadge, removeBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, typeBadge, unitBadge, useCaseBadge, varBadge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -120,7 +120,7 @@
     "build:code": "tsdown",
     "build:css": "tailwindcss -i ./tailwind.css -o ./styles.css",
     "clean": "rimraf .turbo coverage cjs esm storybook-static *.tsbuildinfo",
-    "coverage": "vitest run --coverage",
+    "cov": "vitest run --coverage",
     "sb": "storybook dev -p 6006",
     "sb:build": "storybook build",
     "test": "vitest run",

package/readme.md

@@ -88,6 +88,7 @@ we provide a different set of badges that uses emojis (order: first match wins):
 - 🚨 `danger` - Dangerous or cautionary patterns
 - 🎯 `use-case` - Specific use case or scenario
 - ✨ `example` - Example or demo stories
+- ⚡ `perf` - Performance (stories that demonstrate or test performance)
 - ⌨️ `keyboard` - Keyboard interaction
 - `</>` `source` - Source-code-focused stories
 - `<T>` `type` - TypeScript types (shown in MDX)

package/src/contexts/_story_card_scope.tsx

@@ -24,6 +24,24 @@ export const StoryCardScope = memo(function StoryCardScope(props: StoryCardScope
 	return collector
 })
 
+/** Renders cards from registry state without re-rendering when only children change (avoids cascade). */
+const StoryCardList = memo(function StoryCardList({ cards }: { cards: StoryCardEntryWithKey[] }) {
+	return (
+		<>
+			{cards.map(({ content, key, ...rest }) => (
+				<StoryCard key={key} {...rest}>
+					{content}
+				</StoryCard>
+			))}
+		</>
+	)
+})
+
+/** Keeps container children from re-rendering when container state (cards) updates. */
+const StableScopeChildren = memo(function StableScopeChildren({ children }: { children: ReactNode }) {
+	return <>{children}</>
+})
+
 function StoryCardContainer({ children }: { children: ReactNode }) {
 	const [cards, setCards] = useState<StoryCardEntryWithKey[]>([])
 
@@ -47,12 +65,8 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 	return (
 		<StoryCardRegistryContext.Provider value={contextValue}>
 			<div className="rbsb:flex rbsb:flex-col rbsb:gap-2">
-				{cards.map(({ content, key, ...rest }) => (
-					<StoryCard key={key} {...rest}>
-						{content}
-					</StoryCard>
-				))}
-				{children}
+				<StoryCardList cards={cards} />
+				<StableScopeChildren>{children}</StableScopeChildren>
 			</div>
 		</StoryCardRegistryContext.Provider>
 	)
@@ -62,35 +76,50 @@ type StoryCardEntryWithKey = StoryCardEntry & { key: string }
 
 interface StoryCardCollectorProps extends StoryCardScopeProps {}
 
-const StoryCardCollector = memo(
-	function StoryCardCollector({ Story, title, status, appearance, className, content }: StoryCardCollectorProps) {
-		const context = useContext(StoryCardRegistryContext)!
-		const cardIdRef = useRef<string | null>(null)
-
-		const entry = useMemo(
-			() => ({ title, status, appearance, className, content }),
-			[title, status, appearance, className, content]
-		)
-
-		// Register on mount, unregister on unmount only
-		useLayoutEffect(() => {
-			cardIdRef.current = context.add(entry)
-			return () => {
-				if (cardIdRef.current !== null) {
-					context.remove(cardIdRef.current)
-					cardIdRef.current = null
-				}
-			}
-		}, [context])
+function entryPropsEqual(a: StoryCardCollectorProps, b: StoryCardCollectorProps): boolean {
+	return (
+		a.Story === b.Story &&
+		a.title === b.title &&
+		a.status === b.status &&
+		a.appearance === b.appearance &&
+		a.className === b.className &&
+		a.content === b.content
+	)
+}
+
+const StoryCardCollector = memo(function StoryCardCollector({
+	Story,
+	title,
+	status,
+	appearance,
+	className,
+	content
+}: StoryCardCollectorProps) {
+	const context = useContext(StoryCardRegistryContext)!
+	const cardIdRef = useRef<string | null>(null)
 
-		// Update registry when entry changes (avoids remove+add churn)
-		useLayoutEffect(() => {
+	const entry = useMemo(
+		() => ({ title, status, appearance, className, content }),
+		[title, status, appearance, className, content]
+	)
+
+	// Register on mount, unregister on unmount only
+	useLayoutEffect(() => {
+		cardIdRef.current = context.add(entry)
+		return () => {
 			if (cardIdRef.current !== null) {
-				context.update(cardIdRef.current, entry)
+				context.remove(cardIdRef.current)
+				cardIdRef.current = null
 			}
-		}, [context, entry])
+		}
+	}, [context])
+
+	// Update registry when entry changes (avoids remove+add churn)
+	useLayoutEffect(() => {
+		if (cardIdRef.current !== null) {
+			context.update(cardIdRef.current, entry)
+		}
+	}, [context, entry])
 
-		return <Story />
-	},
-	(prev, next) => prev.Story === next.Story
-)
+	return <Story />
+}, entryPropsEqual)

package/src/decorators/show_doc_source.tsx

@@ -1,143 +1,16 @@
-import { isRunningInTest } from '@repobuddy/test'
-import { type ReactNode, useCallback, useEffect, useMemo, useState } from 'react'
-import { SyntaxHighlighter } from 'storybook/internal/components'
 import type { Args, DecoratorFunction, Renderer } from 'storybook/internal/csf'
-import { addons } from 'storybook/preview-api'
-import { convert, ThemeProvider, themes } from 'storybook/theming'
-import { twJoin } from 'tailwind-merge'
-import { StoryCard, type StoryCardProps } from '../components/story_card'
-import { StoryCardScope } from '../contexts/_story_card_scope'
-
-const channel = addons.getChannel()
+import { type ShowSourceOptions, showSource } from './show_source'
 
 /**
- * A decorator that shows the source code of a story above the rendered story.
- * The source code is taken from the story's `parameters.docs.source.code`.
+ * A decorator that shows the source code of a story below the rendered story.
+ * Uses {@link showSource} with `placement: 'after'`.
  *
- * @param options - Options for the showDocSource decorator
- * @param options.showOriginalSource - Whether to show the original source code in a card
- * @param options.className - Class name to apply to the card
- * @param options.source - Source code to show. Can be a string, or a function `(originalSource) => string` that receives the story's original source and returns the code to display.
- * @param options.placement - Where to show the source code relative to the story.
- * @returns A decorator function that shows the source code of a story above or below the rendered story
+ * @deprecated Use `showSource({ placement: 'after' })` instead.
+ * @param options - Same options as showSource; placement is forced to 'after'
+ * @returns A decorator function that shows the source code below the story
  */
 export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(
-	options?: Pick<StoryCardProps, 'className'> & {
-		source?: ((source: string | undefined) => string) | string | undefined
-		showOriginalSource?: boolean | undefined
-		/**
-		 * Where to show the source code relative to the story.
-		 *
-		 * @default 'after'
-		 */
-		placement?: 'before' | 'after' | undefined
-	}
+	options?: ShowSourceOptions
 ): DecoratorFunction<TRenderer, TArgs> {
-	if (isRunningInTest()) {
-		return (Story) => <Story />
-	}
-
-	return (Story, { parameters: { docs, darkMode } }) => {
-		// This is a workaround to get the current dark mode from `@storybook-community/storybook-dark-mode` without referencing it.
-		const storedItem = window.localStorage.getItem('sb-addon-themes-3')
-		const current = typeof storedItem === 'string' ? JSON.parse(storedItem).current : darkMode?.current
-		const [isDark, setIsDark] = useState((darkMode?.stylePreview && current === 'dark') ?? false)
-
-		useEffect(() => {
-			channel.on('DARK_MODE', setIsDark)
-
-			return () => channel.off('DARK_MODE', setIsDark)
-		}, [])
-
-		const originalSource = options?.showOriginalSource
-			? docs?.source?.originalSource
-			: (docs?.source?.code ?? docs?.source?.originalSource)
-
-		const code =
-			typeof options?.source === 'function' ? options?.source(originalSource) : (options?.source ?? originalSource)
-
-		const language = code === docs?.source?.originalSource ? undefined : docs?.source?.language
-
-		const isOriginalSource = code === docs?.source?.originalSource
-
-		const sourceContent = useMemo(
-			() => (
-				<SyntaxHighlighter data-testid="source-content" language={language}>
-					{code}
-				</SyntaxHighlighter>
-			),
-			[code, language]
-		)
-
-		const showBefore = options?.placement === 'before'
-
-		const sourceCardClassName = useCallback(
-			(state: Pick<StoryCardProps, 'status' | 'appearance'> & { defaultClassName: string }) => {
-				const modifiedState = {
-					...state,
-					defaultClassName: twJoin(
-						state.defaultClassName,
-						isOriginalSource && 'rbsb:bg-transparent rbsb:dark:bg-transparent'
-					)
-				}
-
-				const className = options?.className
-				return typeof className === 'function'
-					? className(modifiedState)
-					: twJoin(modifiedState.defaultClassName, className)
-			},
-			[options?.className, isOriginalSource]
-		)
-
-		const theme = convert(docs?.theme ?? (isDark ? themes.dark : themes.light))
-
-		function DocSourceCard({ children }: { children: ReactNode }) {
-			return <div>{children}</div>
-		}
-
-		const scopeContent = useMemo(() => <DocSourceCard>{sourceContent}</DocSourceCard>, [sourceContent])
-
-		const scopeProps = useMemo(
-			() => ({
-				Story,
-				content: scopeContent,
-				className: sourceCardClassName,
-				appearance: 'source' as const
-			}),
-			[Story, scopeContent, sourceCardClassName]
-		)
-
-		if (isRunningInTest()) {
-			return <Story />
-		}
-
-		if (showBefore) {
-			return (
-				<ThemeProvider theme={theme}>
-					<StoryCardScope {...scopeProps} />
-				</ThemeProvider>
-			)
-		}
-
-		const storyCard = (
-			<StoryCard className={sourceCardClassName} appearance="source">
-				<DocSourceCard>{sourceContent}</DocSourceCard>
-			</StoryCard>
-		)
-
-		return (
-			<ThemeProvider theme={theme}>
-				<section
-					style={{
-						display: 'flex',
-						flexDirection: 'column',
-						gap: '1rem'
-					}}
-				>
-					<Story />
-					{storyCard}
-				</section>
-			</ThemeProvider>
-		)
-	}
+	return showSource({ placement: 'after', ...options })
 }

package/src/decorators/show_source.tsx

@@ -0,0 +1,139 @@
+import { isRunningInTest } from '@repobuddy/test'
+import { type ReactNode, useCallback, useEffect, useMemo, useState } from 'react'
+import { SyntaxHighlighter } from 'storybook/internal/components'
+import type { Args, DecoratorFunction, Renderer } from 'storybook/internal/csf'
+import { addons } from 'storybook/preview-api'
+import { convert, ThemeProvider, themes } from 'storybook/theming'
+import { twJoin } from 'tailwind-merge'
+import { StoryCard, type StoryCardProps } from '../components/story_card'
+import { StoryCardScope } from '../contexts/_story_card_scope'
+
+const channel = addons.getChannel()
+
+/**
+ * Options for the {@link showSource} decorator.
+ *
+ * @property className - Class name to apply to the source card. Can be a string or a function that receives the card state and returns a string.
+ * @property source - Source code to display. A string, or a function `(originalSource) => string` that receives the story's original source and returns the code to show. Defaults to the story's docs source.
+ * @property showOriginalSource - When true, use the story's original (untransformed) source instead of the rendered source.
+ * @property placement - Where to show the source code relative to the story. Defaults to `'before'`.
+ */
+export type ShowSourceOptions = Pick<StoryCardProps, 'className'> & {
+	source?: ((source: string | undefined) => string) | string | undefined
+	showOriginalSource?: boolean | undefined
+	placement?: 'before' | 'after' | undefined
+}
+
+/**
+ * A decorator that shows the source code of a story relative to the rendered story.
+ * The source code is taken from the story's `parameters.docs.source.code`.
+ *
+ * @param options - Options for the showSource decorator
+ * @param options.showOriginalSource - Whether to show the original source code in a card
+ * @param options.className - Class name to apply to the card
+ * @param options.source - Source code to show. Can be a string, or a function `(originalSource) => string` that receives the story's original source and returns the code to display.
+ * @param options.placement - Where to show the source code relative to the story.
+ * @returns A decorator function that shows the source code of a story above or below the rendered story
+ */
+export function showSource<TRenderer extends Renderer = Renderer, TArgs = Args>(
+	options?: ShowSourceOptions
+): DecoratorFunction<TRenderer, TArgs> {
+	if (isRunningInTest()) {
+		return (Story) => <Story />
+	}
+
+	return (Story, { parameters: { docs, darkMode } }) => {
+		// This is a workaround to get the current dark mode from `@storybook-community/storybook-dark-mode` without referencing it.
+		const storedItem = window.localStorage.getItem('sb-addon-themes-3')
+		const current = typeof storedItem === 'string' ? JSON.parse(storedItem).current : darkMode?.current
+		const [isDark, setIsDark] = useState((darkMode?.stylePreview && current === 'dark') ?? false)
+
+		useEffect(() => {
+			channel.on('DARK_MODE', setIsDark)
+
+			return () => channel.off('DARK_MODE', setIsDark)
+		}, [])
+
+		const originalSource = options?.showOriginalSource
+			? docs?.source?.originalSource
+			: (docs?.source?.code ?? docs?.source?.originalSource)
+
+		const code =
+			typeof options?.source === 'function' ? options?.source(originalSource) : (options?.source ?? originalSource)
+
+		const language = code === docs?.source?.originalSource ? undefined : docs?.source?.language
+
+		const isOriginalSource = code === docs?.source?.originalSource
+
+		const sourceContent = useMemo(
+			() => (
+				<SyntaxHighlighter data-testid="source-content" language={language}>
+					{code}
+				</SyntaxHighlighter>
+			),
+			[code, language]
+		)
+
+		const showBefore = (options?.placement ?? 'before') === 'before'
+
+		const sourceCardClassName = useCallback(
+			(state: Pick<StoryCardProps, 'status' | 'appearance'> & { defaultClassName: string }) => {
+				const modifiedState = {
+					...state,
+					defaultClassName: twJoin(
+						state.defaultClassName,
+						isOriginalSource && 'rbsb:bg-transparent rbsb:dark:bg-transparent'
+					)
+				}
+
+				const className = options?.className
+				return typeof className === 'function'
+					? className(modifiedState)
+					: twJoin(modifiedState.defaultClassName, className)
+			},
+			[options?.className, isOriginalSource]
+		)
+
+		const theme = convert(docs?.theme ?? (isDark ? themes.dark : themes.light))
+
+		function DocSourceCard({ children }: { children: ReactNode }) {
+			return <div>{children}</div>
+		}
+
+		if (isRunningInTest()) {
+			return <Story />
+		}
+
+		// For 'before', use StoryCardScope so this card participates in parent scope order.
+		// Wrap content in ThemeProvider so SyntaxHighlighter has theme when rendered by parent.
+		if (showBefore) {
+			const scopeContent = (
+				<ThemeProvider theme={theme}>
+					<DocSourceCard>{sourceContent}</DocSourceCard>
+				</ThemeProvider>
+			)
+			return <StoryCardScope Story={Story} content={scopeContent} className={sourceCardClassName} appearance="source" />
+		}
+
+		const storyCard = (
+			<StoryCard className={sourceCardClassName} appearance="source">
+				<DocSourceCard>{sourceContent}</DocSourceCard>
+			</StoryCard>
+		)
+
+		return (
+			<ThemeProvider theme={theme}>
+				<section
+					style={{
+						display: 'flex',
+						flexDirection: 'column',
+						gap: '1rem'
+					}}
+				>
+					<Story />
+					{storyCard}
+				</section>
+			</ThemeProvider>
+		)
+	}
+}

package/src/decorators/with_story_card.tsx

@@ -1,5 +1,5 @@
 import { isRunningInTest } from '@repobuddy/test'
-import { type ReactNode, useMemo } from 'react'
+import type { ReactNode } from 'react'
 import type { DecoratorFunction, Renderer } from 'storybook/internal/csf'
 import type { StoryCardProps, StoryCardStatus } from '../components/story_card.js'
 import { StoryCardScope } from '../contexts/_story_card_scope.js'
@@ -124,6 +124,8 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 		return (Story) => <Story />
 	}
 	return (Story, { parameters, viewMode }) => {
+		if (viewMode === 'docs') return <Story />
+
 		// Get story card config from parameters if available
 		const storyCardParam = (parameters as Partial<StoryCardParam>).storyCard
 		// Decorator props override parameter values
@@ -137,22 +139,18 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 		// Fallback to docs description if no content provided
 		const content = finalContent ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component
 
-		const scopeProps = useMemo(
-			() => ({
-				Story,
-				content,
-				title: finalTitle,
-				status: finalStatus,
-				appearance: finalAppearance,
-				className: finalClassName,
-				...rest
-			}),
-			[Story, content, finalTitle, finalStatus, finalAppearance, finalClassName, rest]
-		)
-
-		if (viewMode === 'docs') return <Story />
 		if (!content && !finalTitle) return <Story />
 
-		return <StoryCardScope {...scopeProps} />
+		return (
+			<StoryCardScope
+				Story={Story}
+				content={content}
+				title={finalTitle}
+				status={finalStatus}
+				appearance={finalAppearance}
+				className={finalClassName}
+				{...rest}
+			/>
+		)
 	}
 }

package/src/index.ts

@@ -1,8 +1,9 @@
 export * from '@repobuddy/test'
-export type * from './arg-types/fn-to-arg-types.ts'
+export type * from './arg-types/fn-to-arg.types.ts'
 export * from './components/show_html.tsx'
 export * from './components/story_card.tsx'
 export * from './decorators/show_doc_source.tsx'
+export * from './decorators/show_source.tsx'
 export * from './decorators/with_story_card.tsx'
 export * from './parameters/define_actions_param.ts'
 export * from './parameters/define_backgrounds_param.ts'

package/src/storybook-addon-tag-badges/tag_badges.ts

@@ -36,6 +36,7 @@ export type TagNames =
 	| 'usecase'
 	| 'use-case'
 	| 'example'
+	| 'perf'
 	| 'version:next'
 	| 'remove'
 	| 'remove:next'
@@ -413,12 +414,31 @@ export const exampleBadge: TagBadgeParameter = {
 	}
 }
 
+/** Badge (⚡) for stories that demonstrate or test performance. */
+export const perfBadge: TagBadgeParameter = {
+	tags: 'perf',
+	badge: {
+		text: '⚡',
+		style: {
+			backgroundColor: 'transparent',
+			borderColor: 'transparent'
+		},
+		tooltip: 'Performance'
+	},
+	display: {
+		sidebar: {
+			type: 'story',
+			skipInherited: false
+		}
+	}
+}
+
 /**
  * Configuration for story tag badges that appear in the Storybook sidebar.
  * Each badge is associated with a specific tag and displays an emoji or symbol with a tooltip.
  *
  * Badge order (first match wins): New → Alpha → Beta → RC → Deprecated → Remove → Outdated → Danger → Use Case →
- * Example → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
+ * Example → Perf → Keyboard → Source → Type → Function → Var → Props → Todo → Unit → Integration →
  * Editor → Code Only → Version → Internal → Snapshot.
  *
  * - 🆕 New - Recently added stories
@@ -431,6 +451,7 @@ export const exampleBadge: TagBadgeParameter = {
  * - 🚨 Danger - Stories demonstrating dangerous patterns
  * - 🎯 Use Case - Stories that demonstrate a specific use case or scenario
  * - ✨ Example - Example or demo stories
+ * - ⚡ Perf - Stories that demonstrate or test performance
  * - ⌨️ Keyboard - Stories that demonstrate or test keyboard interaction
  * - `</>` Source - Source-code-focused stories
  * - `<T>` Type - Stories that showcase or document TypeScript types
@@ -458,6 +479,7 @@ export const tagBadges: TagBadgeParameters = [
 	dangerBadge,
 	useCaseBadge,
 	exampleBadge,
+	perfBadge,
 	keyboardBadge,
 	sourceBadge,
 	typeBadge,

package/styles.css

@@ -1,4 +1,4 @@
-/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */
+/*! tailwindcss v4.2.0 | MIT License | https://tailwindcss.com */
 @layer properties;
 @layer theme {
   :root, :host {
@@ -33,6 +33,7 @@
     --rbsb-color-blue-500: oklch(62.3% 0.214 259.815);
     --rbsb-color-blue-800: oklch(42.4% 0.199 265.638);
     --rbsb-color-blue-900: oklch(37.9% 0.146 265.522);
+    --rbsb-color-purple-400: oklch(71.4% 0.203 305.504);
     --rbsb-color-purple-500: oklch(62.7% 0.265 303.9);
     --rbsb-color-rose-400: oklch(71.2% 0.194 13.428);
     --rbsb-color-rose-900: oklch(41% 0.159 10.272);
@@ -80,6 +81,9 @@
   .rbsb\:rounded {
     border-radius: 0.25rem;
   }
+  .rbsb\:rounded-full {
+    border-radius: calc(infinity * 1px);
+  }
   .rbsb\:rounded-lg {
     border-radius: var(--rbsb-radius-lg);
   }
@@ -234,6 +238,11 @@
       border-color: var(--rbsb-color-green-700);
     }
   }
+  .rbsb\:dark\:border-purple-400 {
+    @media (prefers-color-scheme: dark) {
+      border-color: var(--rbsb-color-purple-400);
+    }
+  }
   .rbsb\:dark\:border-red-700 {
     @media (prefers-color-scheme: dark) {
       border-color: var(--rbsb-color-red-700);