@repobuddy/storybook 2.21.1 → 2.23.0

package/esm/index.d.ts

@@ -85,6 +85,10 @@ type StoryCardProps = {
    * Can be any React node (string, JSX, etc.).
    */
   children?: ReactNode | undefined;
+  /**
+   * Test identifier for the card.
+   */
+  'data-testid'?: string | undefined;
 };
 type StoryCardThemeState = Pick<StoryCardProps, 'status' | 'appearance'> & {
   defaultClassName: string;
@@ -97,28 +101,49 @@ 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
 /**
- * A decorator that shows the source code of a story above the rendered story.
+ * 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' | 'data-testid'> & {
+  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 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>({
+  className,
+  placement,
+  showOriginalSource,
+  source,
+  ...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 +960,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

@@ -64,7 +64,7 @@ const storyCardVariants = cva("rbsb:py-3 rbsb:px-4 rbsb:rounded rbsb:border rbsb
 * @param props - StoryCard component props
 * @returns A section element containing the card content
 */
-const StoryCard = memo(function StoryCard({ status, appearance, className, children, title }) {
+const StoryCard = memo(function StoryCard({ status, appearance, className, children, title, ...rest }) {
 	const resolvedAppearance = resolveAppearance(appearance, status);
 	return /* @__PURE__ */ jsxs("section", {
 		className: storyCardTheme({
@@ -72,6 +72,7 @@ const StoryCard = memo(function StoryCard({ status, appearance, className, child
 			appearance: resolvedAppearance,
 			defaultClassName: storyCardVariants({ appearance: resolvedAppearance })
 		}, className),
+		...rest,
 		children: [title && /* @__PURE__ */ jsx("h2", {
 			className: "rbsb:text-lg rbsb:font-bold",
 			children: title
@@ -183,20 +184,20 @@ const StoryCardCollector = memo(function StoryCardCollector({ Story, title, stat
 }, 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({ className, placement, showOriginalSource, source, ...options } = {}) {
 	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters: { docs, darkMode } }) => {
 		const storedItem = window.localStorage.getItem("sb-addon-themes-3");
@@ -206,8 +207,8 @@ function showDocSource(options) {
 			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 originalSource = showOriginalSource ? docs?.source?.originalSource : docs?.source?.code ?? docs?.source?.originalSource;
+		const code = typeof source === "function" ? source(originalSource) : source ?? originalSource;
 		const language = code === docs?.source?.originalSource ? void 0 : docs?.source?.language;
 		const isOriginalSource = code === docs?.source?.originalSource;
 		const sourceContent = useMemo(() => /* @__PURE__ */ jsx(SyntaxHighlighter, {
@@ -215,34 +216,33 @@ function showDocSource(options) {
 			language,
 			children: code
 		}), [code, language]);
-		const showBefore = options?.placement === "before";
+		const showBefore = (placement ?? "before") === "before";
 		const sourceCardClassName = useCallback((state) => {
 			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]);
+		}, [className, isOriginalSource]);
 		const theme = convert(docs?.theme ?? (isDark ? themes.dark : themes.light));
 		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 })
+		});
+		const storyCard = /* @__PURE__ */ jsx(StoryCard, {
+			className: sourceCardClassName,
+			appearance: "source",
+			...options,
+			children: /* @__PURE__ */ jsx(DocSourceCard, { children: sourceContent })
 		});
 		return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme,
@@ -252,16 +252,29 @@ function showDocSource(options) {
 					flexDirection: "column",
 					gap: "1rem"
 				},
-				children: [/* @__PURE__ */ jsx(Story, {}), /* @__PURE__ */ jsx(StoryCard, {
-					className: sourceCardClassName,
-					appearance: "source",
-					children: /* @__PURE__ */ jsx(DocSourceCard, { children: sourceContent })
-				})]
+				children: [/* @__PURE__ */ jsx(Story, {}), storyCard]
 			})
 		});
 	};
 }
 
+//#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
 /**
@@ -596,4 +609,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,12 +1,21 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.21.1",
+  "version": "2.23.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
     "testing",
     "documentation"
   ],
+  "homepage": "https://github.com/repobuddy/storybook",
+  "bugs": {
+    "url": "https://github.com/repobuddy/storybook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/repobuddy/storybook.git",
+    "directory": "libs/storybook"
+  },
   "license": "MIT",
   "author": {
     "name": "Homa Wong",

package/readme.md

@@ -78,30 +78,33 @@ addons.setConfig({
 If you use [`storybook-addon-tag-badges`][`storybook-addon-tag-badges`],
 we provide a different set of badges that uses emojis (order: first match wins):
 
-- 🆕 `new` - Recently added stories
-- 🔴 `alpha` - Features in alpha
-- 🟡 `beta` - Features in beta
-- 🔵 `rc` - Release candidate
-- 🗑️ `deprecated` - Deprecated features
-- ☠️ `remove` or `remove:next` (same) or `remove:<version>` - Will be removed in the next or specified version
-- ⚠️ `outdated` - Stories that need updating
-- 🚨 `danger` - Dangerous or cautionary patterns
-- 🎯 `use-case` - Specific use case or scenario
-- ✨ `example` - Example or demo stories
-- ⌨️ `keyboard` - Keyboard interaction
-- `</>` `source` - Source-code-focused stories
-- `<T>` `type` - TypeScript types (shown in MDX)
-- `ƒ(x)` `func` - Functions (shown in MDX)
-- `var` `var` - Variables (shown in MDX)
-- 🔧 `props` - Props or configuration
-- 📋 `todo` - Todo or incomplete stories
-- 🧪 `unit` - Unit tests
-- 🔗 `integration` - Integration tests (hidden in sidebar)
-- ✏️ `editor` - Live editor stories (with [`storybook-addon-code-editor`][`storybook-addon-code-editor`])
-- 📝 `code-only` - Stories without visual examples (hidden in MDX)
-- Version indicators (unchanged)
-- 🔒 `internal` - Internal or private-use-only stories
-- 📸 `snapshot` - Snapshot tests (toolbar only, not sidebar)
+| Badge   | Tag                                                      | Description                                                                               |
+| :-----  | :------------------------------------------------------- | :---------------------------------------------------------------------------------------- |
+| 🆕      | `new`                                                    | Recently added stories                                                                    |
+| 🔴      | `alpha`                                                  | Features in alpha                                                                         |
+| 🟡      | `beta`                                                   | Features in beta                                                                          |
+| 🔵      | `rc`                                                     | Release candidate                                                                         |
+| 🗑️      | `deprecated`                                             | Deprecated features                                                                       |
+| ☠️      | `remove`<br/>`remove:next` (same)<br/>`remove:<version>` | Will be removed in the next or specified version                                          |
+| ⚠️      | `outdated`                                               | Stories that need updating                                                                |
+| 🚨      | `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)                                                           |
+| `ƒ(x)`  | `func`                                                   | Functions (shown in MDX)                                                                  |
+| `var`   | `var`                                                    | Variables (shown in MDX)                                                                  |
+| 🔧      | `props`                                                  | Props or configuration                                                                    |
+| 📋      | `todo`                                                   | Todo or incomplete stories                                                                |
+| 🧪      | `unit`                                                   | Unit tests                                                                                |
+| 🔗      | `integration`                                            | Integration tests (hidden in sidebar)                                                     |
+| ✏️      | `editor`                                                 | Live editor stories (with [`storybook-addon-code-editor`][`storybook-addon-code-editor`]) |
+| 📝      | `code-only`                                              | Stories without visual examples (hidden in MDX)                                           |
+|         | Version indicators                                       | (unchanged)                                                                               |
+| 🔒      | `internal`                                               | Internal or private-use-only stories                                                      |
+| 📸      | `snapshot`                                               | Snapshot tests (toolbar only, not sidebar)                                                |
 
 To use them, add them to your `.storybook/manager.ts`:
 

package/src/components/story_card.tsx

@@ -48,6 +48,10 @@ export type StoryCardProps = {
 	 * Can be any React node (string, JSX, etc.).
 	 */
 	children?: ReactNode | undefined
+	/**
+	 * Test identifier for the card.
+	 */
+	'data-testid'?: string | undefined
 }
 
 export type StoryCardThemeState = Pick<StoryCardProps, 'status' | 'appearance'> & { defaultClassName: string }
@@ -90,7 +94,14 @@ const storyCardVariants = cva(
  * @param props - StoryCard component props
  * @returns A section element containing the card content
  */
-export const StoryCard = memo(function StoryCard({ status, appearance, className, children, title }: StoryCardProps) {
+export const StoryCard = memo(function StoryCard({
+	status,
+	appearance,
+	className,
+	children,
+	title,
+	...rest
+}: StoryCardProps) {
 	const resolvedAppearance = resolveAppearance(appearance, status)
 	const state: StoryCardThemeState = {
 		status,
@@ -98,7 +109,7 @@ export const StoryCard = memo(function StoryCard({ status, appearance, className
 		defaultClassName: storyCardVariants({ appearance: resolvedAppearance })
 	}
 	return (
-		<section className={storyCardTheme(state, className)}>
+		<section className={storyCardTheme(state, className)} {...rest}>
 			{title && <h2 className="rbsb:text-lg rbsb:font-bold">{title}</h2>}
 			{children}
 		</section>

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,141 @@
+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' | 'data-testid'> & {
+	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>({
+	className,
+	placement,
+	showOriginalSource,
+	source,
+	...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 = showOriginalSource
+			? docs?.source?.originalSource
+			: (docs?.source?.code ?? docs?.source?.originalSource)
+
+		const code = typeof source === 'function' ? source(originalSource) : (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 = (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'
+					)
+				}
+
+				return typeof className === 'function'
+					? className(modifiedState)
+					: twJoin(modifiedState.defaultClassName, className)
+			},
+			[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" {...options}>
+				<DocSourceCard>{sourceContent}</DocSourceCard>
+			</StoryCard>
+		)
+
+		return (
+			<ThemeProvider theme={theme}>
+				<section
+					style={{
+						display: 'flex',
+						flexDirection: 'column',
+						gap: '1rem'
+					}}
+				>
+					<Story />
+					{storyCard}
+				</section>
+			</ThemeProvider>
+		)
+	}
+}

package/src/index.ts

@@ -3,6 +3,7 @@ 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

@@ -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);