@repobuddy/storybook 2.11.0 → 2.13.0

package/esm/index.d.ts

@@ -99,11 +99,18 @@ declare function StoryCard({
  * @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 if provided.
- * @returns A decorator function that shows the source code of a story above the rendered story
+ * @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?: string | undefined;
   showOriginalSource?: boolean | undefined;
+  /**
+   * Where to show the source code relative to the story.
+   *
+   * @default 'after'
+   */
+  placement?: 'before' | 'after' | undefined;
 }): DecoratorFunction<TRenderer, TArgs>;
 //#endregion
 //#region src/decorators/with_story_card.d.ts

package/esm/index.js

@@ -71,6 +71,84 @@ function StoryCard({ status, className, children, title }) {
 	});
 }
 
+//#endregion
+//#region src/utils/generate_key.ts
+/**
+* Generates a key for React collections, falling back to a simple counter-based ID if crypto.randomUUID is unavailable.
+* crypto.randomUUID() requires a secure context (HTTPS, localhost, or 127.0.0.1).
+*
+* This can be moved to `@just-web` in the future.
+*/
+function generateKey(prefix) {
+	const randomId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+	return prefix ? `${prefix}-${randomId}` : randomId;
+}
+
+//#endregion
+//#region src/contexts/story_card_registry_context.tsx
+const StoryCardRegistryContext = createContext(null);
+
+//#endregion
+//#region src/contexts/story_card_scope.tsx
+/**
+* Ensures a story-card collection scope: creates the root container when no context exists,
+* otherwise renders the collector so this card participates in the existing scope.
+*/
+function StoryCardScope({ Story, ...props }) {
+	const context = useContext(StoryCardRegistryContext);
+	const collector = /* @__PURE__ */ jsx(StoryCardCollector, {
+		Story,
+		...props
+	});
+	if (context === null) return /* @__PURE__ */ jsx(StoryCardContainer, { children: collector });
+	return collector;
+}
+function StoryCardContainer({ children }) {
+	const [cards, setCards] = useState([]);
+	const contextValue = useMemo(() => ({
+		add(card) {
+			const key = generateKey("story-card");
+			setCards((cards) => [...cards, {
+				...card,
+				key
+			}]);
+			return key;
+		},
+		remove(key) {
+			setCards((cards) => cards.filter((card) => card.key !== key));
+		}
+	}), []);
+	return /* @__PURE__ */ jsx(StoryCardRegistryContext.Provider, {
+		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]
+		})
+	});
+}
+function StoryCardCollector({ Story, title, status, className, content }) {
+	const context = useContext(StoryCardRegistryContext);
+	const cardIdRef = useRef(null);
+	useLayoutEffect(() => {
+		if (cardIdRef.current === null) cardIdRef.current = context.add({
+			title,
+			status,
+			className,
+			content
+		});
+		return () => {
+			if (cardIdRef.current !== null) {
+				context.remove(cardIdRef.current);
+				cardIdRef.current = null;
+			}
+		};
+	}, []);
+	return /* @__PURE__ */ jsx(Story, {});
+}
+
 //#endregion
 //#region src/decorators/show_doc_source.tsx
 const channel = addons.getChannel();
@@ -82,7 +160,8 @@ const channel = addons.getChannel();
 * @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 if provided.
-* @returns A decorator function that shows the source code of a story above the rendered story
+* @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) {
 	return (Story, { parameters: { docs, darkMode } }) => {
@@ -96,12 +175,31 @@ function showDocSource(options) {
 		const code = options?.source ?? (options?.showOriginalSource ? docs?.source?.originalSource : docs?.source?.code ?? docs?.source?.originalSource);
 		const language = code === docs?.source?.originalSource ? void 0 : docs?.source?.language;
 		const isOriginalSource = code === docs?.source?.originalSource;
-		const content = /* @__PURE__ */ jsx(SyntaxHighlighter, {
+		const sourceContent = /* @__PURE__ */ jsx(SyntaxHighlighter, {
 			language,
 			children: code
 		});
+		const showBefore = options?.placement === "before";
+		const sourceCardClassName = (state) => {
+			const modifiedState = {
+				...state,
+				defaultClassName: twJoin(state.defaultClassName, isOriginalSource ? "rbsb:bg-transparent rbsb:dark:bg-transparent" : "rbsb:bg-gray-100 rbsb:dark:bg-gray-900")
+			};
+			const className = options?.className;
+			return typeof className === "function" ? className(modifiedState) : twJoin(modifiedState.defaultClassName, className);
+		};
+		const theme = convert(docs?.theme ?? (isDark ? themes.dark : themes.light));
+		if (showBefore) return /* @__PURE__ */ jsx(ThemeProvider, {
+			theme,
+			children: /* @__PURE__ */ jsx(StoryCardScope, {
+				Story,
+				content: sourceContent,
+				className: sourceCardClassName,
+				status: "info"
+			})
+		});
 		return /* @__PURE__ */ jsx(ThemeProvider, {
-			theme: convert(docs?.theme ?? (isDark ? themes.dark : themes.light)),
+			theme,
 			children: /* @__PURE__ */ jsxs("section", {
 				style: {
 					display: "flex",
@@ -109,34 +207,15 @@ function showDocSource(options) {
 					gap: "1rem"
 				},
 				children: [/* @__PURE__ */ jsx(Story, {}), /* @__PURE__ */ jsx(StoryCard, {
-					className: (state) => {
-						const modifiedState = {
-							...state,
-							defaultClassName: twJoin(state.defaultClassName, isOriginalSource ? "rbsb:bg-transparent rbsb:dark:bg-transparent" : "rbsb:bg-gray-100 rbsb:dark:bg-gray-900")
-						};
-						const className = options?.className;
-						return typeof className === "function" ? className(modifiedState) : twJoin(modifiedState.defaultClassName, className);
-					},
-					children: content
+					className: sourceCardClassName,
+					status: "info",
+					children: sourceContent
 				})]
 			})
 		});
 	};
 }
 
-//#endregion
-//#region src/utils/generate_key.ts
-/**
-* Generates a key for React collections, falling back to a simple counter-based ID if crypto.randomUUID is unavailable.
-* crypto.randomUUID() requires a secure context (HTTPS, localhost, or 127.0.0.1).
-*
-* This can be moved to `@just-web` in the future.
-*/
-function generateKey(prefix) {
-	const randomId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
-	return prefix ? `${prefix}-${randomId}` : randomId;
-}
-
 //#endregion
 //#region src/decorators/with_story_card.tsx
 /**
@@ -227,7 +306,7 @@ function withStoryCard({ title, status, content: contentProp, className, ...rest
 		const finalClassName = className ?? storyCardParam?.className;
 		const content = finalContent ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component;
 		if (!content && !finalTitle) return /* @__PURE__ */ jsx(Story, {});
-		return /* @__PURE__ */ jsx(StoryCardContainerWrapper, {
+		return /* @__PURE__ */ jsx(StoryCardScope, {
 			Story,
 			content,
 			title: finalTitle,
@@ -237,61 +316,6 @@ function withStoryCard({ title, status, content: contentProp, className, ...rest
 		});
 	};
 }
-function StoryCardContainerWrapper({ Story, ...props }) {
-	const context = useContext(StoryCardContext);
-	const collector = /* @__PURE__ */ jsx(StoryCardCollector, {
-		Story,
-		...props
-	});
-	if (context === null) return /* @__PURE__ */ jsx(StoryCardContainer, { children: collector });
-	return collector;
-}
-function StoryCardContainer({ children }) {
-	const [cards, setCards] = useState([]);
-	const contextValue = useMemo(() => ({
-		addCard(card) {
-			const key = generateKey("story-card");
-			setCards((cards) => [...cards, {
-				...card,
-				key
-			}]);
-			return key;
-		},
-		removeCard(key) {
-			setCards((cards) => cards.filter((card) => card.key !== key));
-		}
-	}), []);
-	return /* @__PURE__ */ jsx(StoryCardContext.Provider, {
-		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]
-		})
-	});
-}
-function StoryCardCollector({ Story, title, status, className, content }) {
-	const context = useContext(StoryCardContext);
-	const cardIdRef = useRef(null);
-	useLayoutEffect(() => {
-		if (cardIdRef.current === null) cardIdRef.current = context.addCard({
-			title,
-			status,
-			className,
-			content
-		});
-		return () => {
-			if (cardIdRef.current !== null) {
-				context.removeCard(cardIdRef.current);
-				cardIdRef.current = null;
-			}
-		};
-	}, []);
-	return /* @__PURE__ */ jsx(Story, {});
-}
-const StoryCardContext = createContext(null);
 
 //#endregion
 //#region src/parameters/define_actions_param.ts

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 = 'editor' | 'new' | 'beta' | 'props' | 'deprecated' | 'outdated' | 'danger' | 'todo' | 'code-only' | 'snapshot' | 'unit' | 'integration' | 'keyboard' | 'internal' | 'usecase' | 'version:next';
+type TagNames = 'editor' | 'source' | 'new' | 'beta' | 'props' | 'deprecated' | 'outdated' | 'danger' | 'todo' | 'code-only' | 'snapshot' | 'unit' | 'integration' | 'keyboard' | 'internal' | 'usecase' | 'version:next';
 /**
  * Configuration for story tag badges that appear in the Storybook sidebar.
  * Each badge is associated with a specific tag and displays an emoji with a tooltip.
@@ -37,6 +37,7 @@ declare const outdatedBadge: TagBadgeParameter;
 declare const dangerBadge: TagBadgeParameter;
 declare const todoBadge: TagBadgeParameter;
 declare const codeOnlyBadge: TagBadgeParameter;
+declare const sourceBadge: TagBadgeParameter;
 declare const snapshotBadge: TagBadgeParameter;
 declare const unitBadge: TagBadgeParameter;
 declare const integrationBadge: TagBadgeParameter;
@@ -115,4 +116,4 @@ type StoryObj<TMetaOrCmpOrArgs = Args> = ExtendStoryObj<TMetaOrCmpOrArgs, StoryO
   tag: TagNames;
 }>;
 //#endregion
-export { Meta, StoryObj, TagNames, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, snapshotBadge, tagBadges, todoBadge, unitBadge };
+export { Meta, StoryObj, TagNames, betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, unitBadge };

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

@@ -123,7 +123,20 @@ const codeOnlyBadge = {
 			borderColor: "transparent"
 		},
 		tooltip: "Code Only"
-	}
+	},
+	display: { mdx: false }
+};
+const sourceBadge = {
+	tags: "source",
+	badge: {
+		text: "</>",
+		style: {
+			backgroundColor: "transparent",
+			borderColor: "transparent"
+		},
+		tooltip: "Source Code"
+	},
+	display: { mdx: false }
 };
 const snapshotBadge = {
 	tags: "snapshot",
@@ -150,7 +163,7 @@ const unitBadge = {
 		},
 		tooltip: "Unit Test"
 	},
-	display: { sidebar: false }
+	display: { sidebar: true }
 };
 const integrationBadge = {
 	tags: "integration",
@@ -188,6 +201,7 @@ const internalBadge = {
 };
 const tagBadges = [
 	editorBadge,
+	sourceBadge,
 	unitBadge,
 	integrationBadge,
 	keyboardBadge,
@@ -199,10 +213,10 @@ const tagBadges = [
 	propsBadge,
 	todoBadge,
 	codeOnlyBadge,
+	versionBadge,
 	internalBadge,
-	snapshotBadge,
-	versionBadge
+	snapshotBadge
 ];
 
 //#endregion
-export { betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, snapshotBadge, tagBadges, todoBadge, unitBadge };
+export { betaBadge, codeOnlyBadge, dangerBadge, deprecatedBadge, editorBadge, integrationBadge, internalBadge, keyboardBadge, newBadge, outdatedBadge, propsBadge, snapshotBadge, sourceBadge, tagBadges, todoBadge, unitBadge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",

package/readme.md

@@ -139,6 +139,9 @@ export const preview: Preview = {
 
 [`@repobuddy/storybook`][`@repobuddy/storybook`] uses Tailwind CSS 4 with the prefix `rbsb:` and support `dark` variant.
 
+While we provide a pre-built `@repobuddy/storybook/styles.css` for you,
+it uses the default `dark` variant which is based on the `(prefers-color-scheme: dark)` media query.
+
 Since how to control the dark variant is different in different projects,
 the pre-built `@repobuddy/storybook/styles.css` might not work for you.
 
@@ -149,38 +152,32 @@ you need to separate your tailwind config and import them in your storybook.
 
 ```tsx
 // .storybook/preview.tsx
-import './tailwind.css'
-import './tailwind.repobuddy-storybook.css'
 import '../tailwind.css'
+import './tailwind.repobuddy-storybook.css'
 ```
 
 ```css
-/* .storybook/tailwind.css */
+/* tailwind.css */
+/* add `@repobuddy/storybook/tailwind.css` to a separate layer "repobuddy-storybook" to control the layer order */
+@layer theme, base, repobuddy-storybook, components,  utilities;
+@import "tailwindcss";
 
-/* adding the layer "rbsb" is optional */
-@layer theme, base, components, rbsb, utilities;
-@import "tailwindcss/preflight.css" layer(base);
+@custom-variant dark (&:where(.dark, .dark *));
 ```
 
 ```css
 /* .storybook/tailwind.repobuddy-storybook.css */
-/* adding the layer "rbsb" is optional */
-@import "@repobuddy/storybook/tailwind.css" layer(rbsb);
+@import "@repobuddy/storybook/tailwind.css" layer(repobuddy-storybook);
 
 @source "../node_modules/@repobuddy/storybook/src/**";
 
 @custom-variant dark (&:where(.dark, .dark *));
 ```
 
-```css
-/* tailwind.css */
-@import "tailwindcss/theme.css" layer(theme) prefix(app);
-@import "tailwindcss/utilities.css" layer(utilities) prefix(app);
-
-@custom-variant dark (&:where(.dark, .dark *));
-```
+You may notice that the `@custom-variant dark` is duplicated in both files.
+If you want to avoid this, you can extract it to a separate file and import it in both files.
 
-Note that `@repobuddy/storybook/tailwind` is deprecated in favor of `@repobuddy/storybook/tailwind.css`.
+Also note that `@repobuddy/storybook/tailwind` is deprecated in favor of `@repobuddy/storybook/tailwind.css`.
 That convention better aligns with the Tailwind CSS 4 convention.
 
 [`@repobuddy/storybook`]: https://github.com/repobuddy/storybook

package/src/contexts/story_card_registry_context.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react'
+import { createContext } from 'react'
+import type { RequiredPick } from 'type-plus'
+import type { StoryCardProps } from '../components/story_card.js'
+
+/**
+ * Payload for adding a card to the story card registry.
+ * Matches the shape of card props with `status` required.
+ */
+export type StoryCardEntry = RequiredPick<Omit<StoryCardProps, 'children'> & { content?: ReactNode }, 'status'>
+
+export interface StoryCardRegistryContextValue {
+	add: (card: StoryCardEntry) => string
+	remove: (id: string) => void
+}
+
+export const StoryCardRegistryContext = createContext<StoryCardRegistryContextValue | null>(null)

package/src/contexts/story_card_scope.tsx

@@ -0,0 +1,83 @@
+import { type ComponentType, type ReactNode, useContext, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { StoryCard } from '../components/story_card.js'
+import { generateKey } from '../utils/generate_key.js'
+import {
+	type StoryCardEntry,
+	StoryCardRegistryContext,
+	type StoryCardRegistryContextValue
+} from './story_card_registry_context.js'
+
+export type StoryCardScopeProps = { Story: ComponentType } & StoryCardEntry
+
+/**
+ * Ensures a story-card collection scope: creates the root container when no context exists,
+ * otherwise renders the collector so this card participates in the existing scope.
+ */
+export function StoryCardScope({ Story, ...props }: StoryCardScopeProps) {
+	const context = useContext(StoryCardRegistryContext)
+	const collector = <StoryCardCollector Story={Story} {...props} />
+
+	if (context === null) {
+		return <StoryCardContainer>{collector}</StoryCardContainer>
+	}
+
+	return collector
+}
+
+function StoryCardContainer({ children }: { children: ReactNode }) {
+	const [cards, setCards] = useState<StoryCardEntryWithKey[]>([])
+
+	const contextValue: StoryCardRegistryContextValue = useMemo(
+		() => ({
+			add(card) {
+				const key = generateKey('story-card')
+				setCards((cards) => [...cards, { ...card, key }])
+				return key
+			},
+			remove(key) {
+				setCards((cards) => cards.filter((card) => card.key !== key))
+			}
+		}),
+		[]
+	)
+
+	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}
+			</div>
+		</StoryCardRegistryContext.Provider>
+	)
+}
+
+type StoryCardEntryWithKey = StoryCardEntry & { key: string }
+
+interface StoryCardCollectorProps extends StoryCardScopeProps {}
+
+function StoryCardCollector({ Story, title, status, className, content }: StoryCardCollectorProps) {
+	// StoryCardCollector is an internal component. Context is guaranteed to be not null by `StoryCardContainer`.
+	const context = useContext(StoryCardRegistryContext)!
+	const cardIdRef = useRef<string | null>(null)
+
+	// Collect this card once into the collection
+	useLayoutEffect(() => {
+		// Only add if not already added (handles Strict Mode double-render)
+		if (cardIdRef.current === null) {
+			cardIdRef.current = context.add({ title, status, className, content })
+		}
+
+		return () => {
+			if (cardIdRef.current !== null) {
+				context.remove(cardIdRef.current)
+				cardIdRef.current = null
+			}
+		}
+	}, [])
+
+	return <Story />
+}

package/src/decorators/show_doc_source.tsx

@@ -5,6 +5,7 @@ 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()
 
@@ -16,12 +17,19 @@ const channel = addons.getChannel()
  * @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 if provided.
- * @returns A decorator function that shows the source code of a story above the rendered story
+ * @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 showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(
 	options?: Pick<StoryCardProps, 'className'> & {
 		source?: string | undefined
 		showOriginalSource?: boolean | undefined
+		/**
+		 * Where to show the source code relative to the story.
+		 *
+		 * @default 'after'
+		 */
+		placement?: 'before' | 'after' | undefined
 	}
 ): DecoratorFunction<TRenderer, TArgs> {
 	return (Story, { parameters: { docs, darkMode } }) => {
@@ -46,10 +54,43 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 
 		const isOriginalSource = code === docs?.source?.originalSource
 
-		const content = <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>
+		const sourceContent = <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>
+
+		const showBefore = options?.placement === 'before'
+
+		const sourceCardClassName = (state: Pick<StoryCardProps, 'status'> & { defaultClassName: string }) => {
+			const modifiedState = {
+				...state,
+				defaultClassName: twJoin(
+					state.defaultClassName,
+					isOriginalSource ? 'rbsb:bg-transparent rbsb:dark:bg-transparent' : 'rbsb:bg-gray-100 rbsb:dark:bg-gray-900'
+				)
+			}
+
+			const className = options?.className
+			return typeof className === 'function'
+				? className(modifiedState)
+				: twJoin(modifiedState.defaultClassName, className)
+		}
+
+		const theme = convert(docs?.theme ?? (isDark ? themes.dark : themes.light))
+
+		if (showBefore) {
+			return (
+				<ThemeProvider theme={theme}>
+					<StoryCardScope Story={Story} content={sourceContent} className={sourceCardClassName} status="info" />
+				</ThemeProvider>
+			)
+		}
+
+		const storyCard = (
+			<StoryCard className={sourceCardClassName} status="info">
+				{sourceContent}
+			</StoryCard>
+		)
 
 		return (
-			<ThemeProvider theme={convert(docs?.theme ?? (isDark ? themes.dark : themes.light))}>
+			<ThemeProvider theme={theme}>
 				<section
 					style={{
 						display: 'flex',
@@ -58,26 +99,7 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 					}}
 				>
 					<Story />
-					<StoryCard
-						className={(state) => {
-							const modifiedState = {
-								...state,
-								defaultClassName: twJoin(
-									state.defaultClassName,
-									isOriginalSource
-										? 'rbsb:bg-transparent rbsb:dark:bg-transparent'
-										: 'rbsb:bg-gray-100 rbsb:dark:bg-gray-900'
-								)
-							}
-
-							const className = options?.className
-							return typeof className === 'function'
-								? className(modifiedState)
-								: twJoin(modifiedState.defaultClassName, className)
-						}}
-					>
-						{content}
-					</StoryCard>
+					{storyCard}
 				</section>
 			</ThemeProvider>
 		)

package/src/decorators/with_story_card.tsx

@@ -1,18 +1,8 @@
-import {
-	type ComponentType,
-	createContext,
-	type ReactNode,
-	useContext,
-	useLayoutEffect,
-	useMemo,
-	useRef,
-	useState
-} from 'react'
+import type { ReactNode } from 'react'
 import type { DecoratorFunction, Renderer } from 'storybook/internal/csf'
-import type { RequiredPick } from 'type-plus'
-import { StoryCard, type StoryCardProps } from '../components/story_card.js'
+import type { StoryCardProps } from '../components/story_card.js'
+import { StoryCardScope } from '../contexts/story_card_scope.js'
 import type { StoryCardParam } from '../parameters/define_story_card_param.js'
-import { generateKey } from '../utils/generate_key.js'
 
 export type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
 	/**
@@ -137,7 +127,7 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 		if (!content && !finalTitle) return <Story />
 
 		return (
-			<StoryCardContainerWrapper
+			<StoryCardScope
 				Story={Story}
 				content={content}
 				title={finalTitle}
@@ -148,85 +138,3 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 		)
 	}
 }
-
-interface StoryCardContainerWrapperProps extends RequiredPick<WithStoryCardProps, 'status'> {
-	Story: ComponentType
-}
-
-function StoryCardContainerWrapper({ Story, ...props }: StoryCardContainerWrapperProps) {
-	const context = useContext(StoryCardContext)
-	const collector = <StoryCardCollector Story={Story} {...props} />
-
-	if (context === null) {
-		return <StoryCardContainer>{collector}</StoryCardContainer>
-	}
-
-	return collector
-}
-
-function StoryCardContainer({ children }: { children: ReactNode }) {
-	const [cards, setCards] = useState<StoryCardWithKey[]>([])
-
-	const contextValue: StoryCardContextValue = useMemo(
-		() => ({
-			addCard(card) {
-				const key = generateKey('story-card')
-				setCards((cards) => [...cards, { ...card, key }])
-				return key
-			},
-			removeCard(key) {
-				setCards((cards) => cards.filter((card) => card.key !== key))
-			}
-		}),
-		[]
-	)
-
-	return (
-		<StoryCardContext.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}
-			</div>
-		</StoryCardContext.Provider>
-	)
-}
-
-type StoryCardWithKey = RequiredPick<WithStoryCardProps, 'status'> & { key: string }
-
-interface StoryCardCollectorProps extends RequiredPick<WithStoryCardProps, 'status'> {
-	Story: ComponentType
-}
-
-function StoryCardCollector({ Story, title, status, className, content }: StoryCardCollectorProps) {
-	// StoryCardCollector is an internal component. Context is guaranteed to be not null by `StoryCardContainer`.
-	const context = useContext(StoryCardContext)!
-	const cardIdRef = useRef<string | null>(null)
-
-	// Collect this card once into the collection
-	useLayoutEffect(() => {
-		// Only add if not already added (handles Strict Mode double-render)
-		if (cardIdRef.current === null) {
-			cardIdRef.current = context.addCard({ title, status, className, content })
-		}
-
-		return () => {
-			if (cardIdRef.current !== null) {
-				context.removeCard(cardIdRef.current)
-				cardIdRef.current = null
-			}
-		}
-	}, [])
-
-	return <Story />
-}
-
-interface StoryCardContextValue {
-	addCard: (card: RequiredPick<WithStoryCardProps, 'status'>) => string
-	removeCard: (id: string) => void
-}
-
-const StoryCardContext = createContext<StoryCardContextValue | null>(null)

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

@@ -9,6 +9,7 @@ type TagBadgeParameter = TagBadgeParameters[0]
  */
 export type TagNames =
 	| 'editor'
+	| 'source'
 	| 'new'
 	| 'beta'
 	| 'props'
@@ -155,6 +156,24 @@ export const codeOnlyBadge: TagBadgeParameter = {
 			borderColor: 'transparent'
 		},
 		tooltip: 'Code Only'
+	},
+	display: {
+		mdx: false
+	}
+}
+
+export const sourceBadge: TagBadgeParameter = {
+	tags: 'source',
+	badge: {
+		text: '</>',
+		style: {
+			backgroundColor: 'transparent',
+			borderColor: 'transparent'
+		},
+		tooltip: 'Source Code'
+	},
+	display: {
+		mdx: false
 	}
 }
 
@@ -185,7 +204,7 @@ export const unitBadge: TagBadgeParameter = {
 		tooltip: 'Unit Test'
 	},
 	display: {
-		sidebar: false
+		sidebar: true
 	}
 }
 
@@ -230,6 +249,7 @@ export const internalBadge: TagBadgeParameter = {
 
 export const tagBadges: TagBadgeParameters = [
 	editorBadge,
+	sourceBadge,
 	unitBadge,
 	integrationBadge,
 	keyboardBadge,
@@ -241,7 +261,7 @@ export const tagBadges: TagBadgeParameters = [
 	propsBadge,
 	todoBadge,
 	codeOnlyBadge,
+	versionBadge,
 	internalBadge,
-	snapshotBadge,
-	versionBadge
+	snapshotBadge
 ]