@repobuddy/storybook 2.20.1 → 2.21.0

package/esm/index.d.ts

@@ -1,5 +1,6 @@
 
 import { UserConfig } from "htmlfy";
+import * as react from "react";
 import { ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { AnyFunction, CreateTuple, IsStringLiteral, Properties, Tail } from "type-plus";
@@ -94,13 +95,7 @@ type StoryCardThemeState = Pick<StoryCardProps, 'status' | 'appearance'> & {
  * @param props - StoryCard component props
  * @returns A section element containing the card content
  */
-declare function StoryCard({
-  status,
-  appearance,
-  className,
-  children,
-  title
-}: StoryCardProps): react_jsx_runtime0.JSX.Element;
+declare const StoryCard: react.NamedExoticComponent<StoryCardProps>;
 //#endregion
 //#region src/decorators/show_doc_source.d.ts
 /**

package/esm/index.js

@@ -1,7 +1,7 @@
 
 import { isRunningInTest } from "@repobuddy/test";
 import { prettify } from "htmlfy";
-import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createContext, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
 import { twJoin, twMerge } from "tailwind-merge";
@@ -48,7 +48,7 @@ function storyCardTheme(state, className) {
 	if (!className) return state.defaultClassName;
 	return twMerge(typeof className === "function" ? className(state) : twJoin(state.defaultClassName, className));
 }
-const storyCardVariants = cva("rbsb:flex rbsb:flex-col rbsb:gap-1 rbsb:py-3 rbsb:px-4 rbsb:rounded rbsb:border rbsb:border-solid rbsb:text-black rbsb:dark:text-gray-100", {
+const storyCardVariants = cva("rbsb:py-3 rbsb:px-4 rbsb:rounded rbsb:border rbsb:border-solid rbsb:text-black rbsb:dark:text-gray-100", {
 	variants: { appearance: {
 		error: "rbsb:bg-red-100 rbsb:dark:bg-red-900 rbsb:border-red-300 rbsb:dark:border-red-700",
 		warn: "rbsb:bg-yellow-100 rbsb:dark:bg-yellow-900 rbsb:border-yellow-300 rbsb:dark:border-yellow-700",
@@ -64,7 +64,7 @@ const storyCardVariants = cva("rbsb:flex rbsb:flex-col rbsb:gap-1 rbsb:py-3 rbsb
 * @param props - StoryCard component props
 * @returns A section element containing the card content
 */
-function StoryCard({ status, appearance, className, children, title }) {
+const StoryCard = memo(function StoryCard({ status, appearance, className, children, title }) {
 	const resolvedAppearance = resolveAppearance(appearance, status);
 	return /* @__PURE__ */ jsxs("section", {
 		className: storyCardTheme({
@@ -77,7 +77,7 @@ function StoryCard({ status, appearance, className, children, title }) {
 			children: title
 		}), children]
 	});
-}
+});
 
 //#endregion
 //#region src/utils/generate_key.ts
@@ -102,15 +102,12 @@ const StoryCardRegistryContext = createContext(null);
 * 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 StoryCardScope = memo(function StoryCardScope(props) {
 	const context = useContext(StoryCardRegistryContext);
-	const collector = /* @__PURE__ */ jsx(StoryCardCollector, {
-		Story,
-		...props
-	});
+	const collector = /* @__PURE__ */ jsx(StoryCardCollector, { ...props });
 	if (context === null) return /* @__PURE__ */ jsx(StoryCardContainer, { children: collector });
 	return collector;
-}
+});
 function StoryCardContainer({ children }) {
 	const [cards, setCards] = useState([]);
 	const contextValue = useMemo(() => ({
@@ -124,6 +121,12 @@ function StoryCardContainer({ children }) {
 		},
 		remove(key) {
 			setCards((cards) => cards.filter((card) => card.key !== key));
+		},
+		update(key, card) {
+			setCards((cards) => cards.map((c) => c.key === key ? {
+				...card,
+				key
+			} : c));
 		}
 	}), []);
 	return /* @__PURE__ */ jsx(StoryCardRegistryContext.Provider, {
@@ -137,26 +140,36 @@ function StoryCardContainer({ children }) {
 		})
 	});
 }
-function StoryCardCollector({ Story, title, status, appearance, className, content }) {
+const StoryCardCollector = memo(function StoryCardCollector({ Story, title, status, appearance, className, content }) {
 	const context = useContext(StoryCardRegistryContext);
 	const cardIdRef = useRef(null);
+	const entry = useMemo(() => ({
+		title,
+		status,
+		appearance,
+		className,
+		content
+	}), [
+		title,
+		status,
+		appearance,
+		className,
+		content
+	]);
 	useLayoutEffect(() => {
-		if (cardIdRef.current === null) cardIdRef.current = context.add({
-			title,
-			status,
-			appearance,
-			className,
-			content
-		});
+		cardIdRef.current = context.add(entry);
 		return () => {
 			if (cardIdRef.current !== null) {
 				context.remove(cardIdRef.current);
 				cardIdRef.current = null;
 			}
 		};
-	}, []);
+	}, [context]);
+	useLayoutEffect(() => {
+		if (cardIdRef.current !== null) context.update(cardIdRef.current, entry);
+	}, [context, entry]);
 	return /* @__PURE__ */ jsx(Story, {});
-}
+}, (prev, next) => prev.Story === next.Story);
 
 //#endregion
 //#region src/decorators/show_doc_source.tsx
@@ -173,6 +186,7 @@ const channel = addons.getChannel();
 * @returns A decorator function that shows the source code of a story above or below the rendered story
 */
 function showDocSource(options) {
+	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters: { docs, darkMode } }) => {
 		const storedItem = window.localStorage.getItem("sb-addon-themes-3");
 		const current = typeof storedItem === "string" ? JSON.parse(storedItem).current : darkMode?.current;
@@ -185,28 +199,39 @@ function showDocSource(options) {
 		const code = typeof options?.source === "function" ? options?.source(originalSource) : options?.source ?? originalSource;
 		const language = code === docs?.source?.originalSource ? void 0 : docs?.source?.language;
 		const isOriginalSource = code === docs?.source?.originalSource;
-		const sourceContent = /* @__PURE__ */ jsx(SyntaxHighlighter, {
+		const sourceContent = useMemo(() => /* @__PURE__ */ jsx(SyntaxHighlighter, {
+			"data-testid": "source-content",
 			language,
 			children: code
-		});
+		}), [code, language]);
 		const showBefore = options?.placement === "before";
-		const sourceCardClassName = (state) => {
+		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]);
 		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(() => ({
+			Story,
+			content: scopeContent,
+			className: sourceCardClassName,
+			appearance: "source"
+		}), [
+			Story,
+			scopeContent,
+			sourceCardClassName
+		]);
+		if (isRunningInTest()) return /* @__PURE__ */ jsx(Story, {});
 		if (showBefore) return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme,
-			children: /* @__PURE__ */ jsx(StoryCardScope, {
-				Story,
-				content: sourceContent,
-				className: sourceCardClassName,
-				appearance: "source"
-			})
+			children: /* @__PURE__ */ jsx(StoryCardScope, { ...scopeProps })
 		});
 		return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme,
@@ -219,7 +244,7 @@ function showDocSource(options) {
 				children: [/* @__PURE__ */ jsx(Story, {}), /* @__PURE__ */ jsx(StoryCard, {
 					className: sourceCardClassName,
 					appearance: "source",
-					children: sourceContent
+					children: /* @__PURE__ */ jsx(DocSourceCard, { children: sourceContent })
 				})]
 			})
 		});
@@ -308,8 +333,8 @@ function showDocSource(options) {
 * - The `status` option is deprecated; use `appearance` instead for the same behavior and additional variants (`source`, `output`).
 */
 function withStoryCard({ title, status, appearance, content: contentProp, className, ...rest } = {}) {
+	if (isRunningInTest()) return (Story) => /* @__PURE__ */ jsx(Story, {});
 	return (Story, { parameters, viewMode }) => {
-		if (viewMode === "docs") return /* @__PURE__ */ jsx(Story, {});
 		const storyCardParam = parameters.storyCard;
 		const finalTitle = title ?? storyCardParam?.title;
 		const finalAppearance = appearance ?? storyCardParam?.appearance ?? status ?? storyCardParam?.status ?? "info";
@@ -317,8 +342,7 @@ function withStoryCard({ title, status, appearance, content: contentProp, classN
 		const finalContent = contentProp ?? storyCardParam?.content;
 		const finalClassName = className ?? storyCardParam?.className;
 		const content = finalContent ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component;
-		if (!content && !finalTitle) return /* @__PURE__ */ jsx(Story, {});
-		return /* @__PURE__ */ jsx(StoryCardScope, {
+		const scopeProps = useMemo(() => ({
 			Story,
 			content,
 			title: finalTitle,
@@ -326,7 +350,18 @@ function withStoryCard({ title, status, appearance, content: contentProp, classN
 			appearance: finalAppearance,
 			className: finalClassName,
 			...rest
-		});
+		}), [
+			Story,
+			content,
+			finalTitle,
+			finalStatus,
+			finalAppearance,
+			finalClassName,
+			rest
+		]);
+		if (viewMode === "docs") return /* @__PURE__ */ jsx(Story, {});
+		if (!content && !finalTitle) return /* @__PURE__ */ jsx(Story, {});
+		return /* @__PURE__ */ jsx(StoryCardScope, { ...scopeProps });
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.20.1",
+  "version": "2.21.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -92,6 +92,7 @@
     "storybook": "^10.2.8",
     "storybook-addon-code-editor": "^6.1.3",
     "storybook-addon-tag-badges": "^3.0.6",
+    "storybook-addon-vis": "^3.1.2",
     "tailwindcss": "^4.1.17",
     "tsdown": "^0.20.0",
     "vite": "^7.3.0",

package/src/components/story_card.tsx

@@ -1,5 +1,5 @@
 import { cva } from 'class-variance-authority'
-import type { ReactNode } from 'react'
+import { memo, type ReactNode } from 'react'
 import { twJoin, twMerge } from 'tailwind-merge'
 
 /**
@@ -67,7 +67,7 @@ function storyCardTheme(state: StoryCardThemeState, className: StoryCardProps['c
 }
 
 const storyCardVariants = cva(
-	'rbsb:flex rbsb:flex-col rbsb:gap-1 rbsb:py-3 rbsb:px-4 rbsb:rounded rbsb:border rbsb:border-solid rbsb:text-black rbsb:dark:text-gray-100',
+	'rbsb:py-3 rbsb:px-4 rbsb:rounded rbsb:border rbsb:border-solid rbsb:text-black rbsb:dark:text-gray-100',
 	{
 		variants: {
 			appearance: {
@@ -90,7 +90,7 @@ const storyCardVariants = cva(
  * @param props - StoryCard component props
  * @returns A section element containing the card content
  */
-export function StoryCard({ status, appearance, className, children, title }: StoryCardProps) {
+export const StoryCard = memo(function StoryCard({ status, appearance, className, children, title }: StoryCardProps) {
 	const resolvedAppearance = resolveAppearance(appearance, status)
 	const state: StoryCardThemeState = {
 		status,
@@ -103,4 +103,4 @@ export function StoryCard({ status, appearance, className, children, title }: St
 			{children}
 		</section>
 	)
-}
+})

package/src/contexts/_story_card_registry_context.tsx

@@ -11,6 +11,7 @@ export type StoryCardEntry = Omit<StoryCardProps, 'children'> & { content?: Reac
 export interface StoryCardRegistryContextValue {
 	add: (card: StoryCardEntry) => string
 	remove: (id: string) => void
+	update: (id: string, card: StoryCardEntry) => void
 }
 
 export const StoryCardRegistryContext = createContext<StoryCardRegistryContextValue | null>(null)

package/src/contexts/_story_card_scope.tsx

@@ -1,4 +1,4 @@
-import { type ComponentType, type ReactNode, useContext, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { type ComponentType, memo, type ReactNode, useContext, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import { StoryCard } from '../components/story_card.js'
 import { generateKey } from '../utils/generate_key.js'
 import {
@@ -13,16 +13,16 @@ 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) {
+export const StoryCardScope = memo(function StoryCardScope(props: StoryCardScopeProps) {
 	const context = useContext(StoryCardRegistryContext)
-	const collector = <StoryCardCollector Story={Story} {...props} />
+	const collector = <StoryCardCollector {...props} />
 
 	if (context === null) {
 		return <StoryCardContainer>{collector}</StoryCardContainer>
 	}
 
 	return collector
-}
+})
 
 function StoryCardContainer({ children }: { children: ReactNode }) {
 	const [cards, setCards] = useState<StoryCardEntryWithKey[]>([])
@@ -36,6 +36,9 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 			},
 			remove(key) {
 				setCards((cards) => cards.filter((card) => card.key !== key))
+			},
+			update(key, card) {
+				setCards((cards) => cards.map((c) => (c.key === key ? { ...card, key } : c)))
 			}
 		}),
 		[]
@@ -59,25 +62,35 @@ type StoryCardEntryWithKey = StoryCardEntry & { key: string }
 
 interface StoryCardCollectorProps extends StoryCardScopeProps {}
 
-function StoryCardCollector({ Story, title, status, appearance, 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)
+const StoryCardCollector = memo(
+	function StoryCardCollector({ Story, title, status, appearance, className, content }: StoryCardCollectorProps) {
+		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, appearance, className, content })
-		}
+		const entry = useMemo(
+			() => ({ title, status, appearance, className, content }),
+			[title, status, appearance, className, content]
+		)
 
-		return () => {
+		// Register on mount, unregister on unmount only
+		useLayoutEffect(() => {
+			cardIdRef.current = context.add(entry)
+			return () => {
+				if (cardIdRef.current !== null) {
+					context.remove(cardIdRef.current)
+					cardIdRef.current = null
+				}
+			}
+		}, [context])
+
+		// Update registry when entry changes (avoids remove+add churn)
+		useLayoutEffect(() => {
 			if (cardIdRef.current !== null) {
-				context.remove(cardIdRef.current)
-				cardIdRef.current = null
+				context.update(cardIdRef.current, entry)
 			}
-		}
-	}, [])
+		}, [context, entry])
 
-	return <Story />
-}
+		return <Story />
+	},
+	(prev, next) => prev.Story === next.Story
+)

package/src/decorators/show_doc_source.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useState } from 'react'
+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'
@@ -32,6 +33,10 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 		placement?: 'before' | 'after' | undefined
 	}
 ): 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')
@@ -55,40 +60,68 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 
 		const isOriginalSource = code === docs?.source?.originalSource
 
-		const sourceContent = <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>
+		const sourceContent = useMemo(
+			() => (
+				<SyntaxHighlighter data-testid="source-content" language={language}>
+					{code}
+				</SyntaxHighlighter>
+			),
+			[code, language]
+		)
 
 		const showBefore = options?.placement === 'before'
 
-		const sourceCardClassName = (
-			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)
-		}
+		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 Story={Story} content={sourceContent} className={sourceCardClassName} appearance="source" />
+					<StoryCardScope {...scopeProps} />
 				</ThemeProvider>
 			)
 		}
 
 		const storyCard = (
 			<StoryCard className={sourceCardClassName} appearance="source">
-				{sourceContent}
+				<DocSourceCard>{sourceContent}</DocSourceCard>
 			</StoryCard>
 		)
 

package/src/decorators/with_story_card.tsx

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

package/styles.css

@@ -68,9 +68,6 @@
   .rbsb\:flex-col {
     flex-direction: column;
   }
-  .rbsb\:gap-1 {
-    gap: calc(var(--rbsb-spacing) * 1);
-  }
   .rbsb\:gap-2 {
     gap: calc(var(--rbsb-spacing) * 2);
   }