@repobuddy/storybook 2.21.1 → 2.22.0

package/esm/index.d.ts

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

@@ -183,20 +183,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(options) {
 	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters: { docs, darkMode } }) => {
 		const storedItem = window.localStorage.getItem("sb-addon-themes-3");
@@ -215,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,
@@ -228,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,
@@ -262,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
 /**
@@ -596,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.1",
+  "version": "2.22.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",

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