@repobuddy/storybook 2.2.2 → 2.4.0

package/esm/index.d.ts

@@ -5,6 +5,7 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { ClassNameProps, StyleProps } from "@just-web/css";
 import { Args, DecoratorFunction, Renderer } from "storybook/internal/csf";
 import { Decorator, Meta, StoryContext, StoryObj, StrictArgs } from "@storybook/react-vite";
+import { IsStringLiteral } from "type-plus";
 export * from "@repobuddy/test";
 
 //#region src/components/show_html.d.ts
@@ -32,9 +33,11 @@ declare function ShowHtml({
  * 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`.
  */
-declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(): DecoratorFunction<TRenderer, TArgs>;
+declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(options?: {
+  showOriginalSource?: boolean | undefined;
+}): DecoratorFunction<TRenderer, TArgs>;
 //#endregion
-//#region src/decorators/with_story_card.d.ts
+//#region src/components/story_card.d.ts
 type StoryCardProps = {
   /**
    * Optional title displayed as a heading in the card.
@@ -55,7 +58,26 @@ type StoryCardProps = {
    * If a function is provided, it receives the card state and default className,
    * and should return the final className string.
    */
-  className?: ((state: Required<Pick<StoryCardProps, 'status'>> & {
+  className?: ((state: Pick<StoryCardProps, 'status'> & {
+    defaultClassName: string;
+  }) => string) | string | undefined;
+  /**
+   * Content to display in the card body.
+   * Can be any React node (string, JSX, etc.).
+   */
+  children?: ReactNode | undefined;
+};
+//#endregion
+//#region src/decorators/with_story_card.d.ts
+type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
+  /**
+   * Additional CSS classes or a function to compute classes.
+   *
+   * If a string is provided, it will be merged with the default classes.
+   * If a function is provided, it receives the card state and default className,
+   * and should return the final className string.
+   */
+  className?: ((state: Pick<StoryCardProps, 'status'> & {
     defaultClassName: string;
   }) => string) | string | undefined;
   /**
@@ -139,7 +161,7 @@ declare function withStoryCard<TRenderer extends Renderer = Renderer>({
   status,
   content: contentProp,
   ...rest
-}?: StoryCardProps): DecoratorFunction<TRenderer>;
+}?: WithStoryCardProps): DecoratorFunction<TRenderer>;
 //#endregion
 //#region src/parameters/define_actions_param.d.ts
 interface ActionsParam {
@@ -645,6 +667,8 @@ declare function whenRunningInTest<TArgs = StrictArgs>(decoratorOrHandler: ((...
  * @template M - The base Meta type
  * @template E - The extension type containing tagType
  *
+ * @deprecated use `import { ExtendsMeta } from '@repobuddy/storybook'` instead.
+ *
  * @example
  * ```ts
  * // Create a generic Meta type for a project
@@ -665,6 +689,8 @@ type ExtendMeta<TCmpOrArgs, M extends Meta<TCmpOrArgs>, E extends {
  * @template S - The base StoryObj type
  * @template E - The extension type containing tagType
  *
+ * @deprecated use `import { ExtendsStoryObj } from '@repobuddy/storybook'` instead.
+ *
  * @example
  * ```ts
  * // Create a generic StoryObj type for a project
@@ -680,4 +706,79 @@ type ExtendStoryObj<TMetaOrCmpOrArgs, S extends StoryObj<TMetaOrCmpOrArgs>, E ex
   tags?: Array<E['tag'] | (string & {})> | undefined;
 };
 //#endregion
-export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, SourceProps, StoryCardProps, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };
+//#region src/types/_extract_string_literals.d.ts
+type ExtractStringLiterals<T> = T extends any ? (string extends T ? never : T) : never;
+//#endregion
+//#region src/types/extends_meta.d.ts
+/**
+ * Extends the Storybook Meta type with custom tag types.
+ *
+ * This utility type allows you to extend the `tags` property of a Storybook Meta type
+ * with custom string literal types while preserving existing tag types from the base Meta.
+ *
+ * @template M - The base Meta type to extend
+ * @template E - The extension type containing a `tag` property with the custom tag types
+ *
+ * @example
+ * ```ts
+ * import type { ExtendsMeta } from '@repobuddy/storybook'
+ * import type { Args, Meta as M } from '@storybook/your-framework'
+ *
+ * // Create a generic Meta type for your project
+ * type Meta<TCmpOrArgs = Args> = ExtendsMeta<
+ *   M<TCmpOrArgs>,
+ *   { tag: 'new' | 'beta' | 'deprecated' }
+ * >
+ *
+ * // Use in component stories
+ * const meta: Meta<typeof Component> = {
+ *   tags: ['new'], // <--- gets auto-completion for 'new' | 'beta' | 'deprecated'
+ *   // ...
+ * }
+ * ```
+ */
+type ExtendsMeta<M extends {
+  tags?: string[] | undefined;
+}, E extends {
+  tag: string;
+}> = Omit<M, 'tags'> & {
+  tags?: ExtractStringLiterals<NonNullable<M['tags']>[number]> extends infer MT ? IsStringLiteral<MT> extends true ? Array<(string & {}) | MT | E['tag']> | undefined : Array<(string & {}) | E['tag']> | undefined : never;
+};
+//#endregion
+//#region src/types/extends_story_obj.d.ts
+/**
+ * Extends the Storybook StoryObj type with custom tag types.
+ *
+ * This utility type allows you to extend the `tags` property of a Storybook StoryObj type
+ * with custom string literal types while preserving existing tag types from the base StoryObj.
+ *
+ * @template S - The base StoryObj type to extend (must have an optional `tags` property)
+ * @template E - The extension type containing a `tag` property with the custom tag types
+ *
+ * @example
+ * ```ts
+ * import type { ExtendsStoryObj } from '@repobuddy/storybook'
+ * import type { Args, StoryObj as S } from '@storybook/your-framework'
+ *
+ * // Create a generic StoryObj type for your project
+ * type StoryObj<TCmpOrArgs = Args> = ExtendsStoryObj<
+ *   S<TCmpOrArgs>,
+ *   { tag: 'new' | 'beta' | 'deprecated' }
+ * >
+ *
+ * // Use in component stories
+ * const story: StoryObj<typeof Component> = {
+ *   tags: ['new'], // <--- gets auto-completion for 'new' | 'beta' | 'deprecated'
+ *   // ...
+ * }
+ * ```
+ */
+type ExtendsStoryObj<S extends {
+  tags?: string[] | undefined;
+}, E extends {
+  tag: string;
+}> = Omit<S, 'tags'> & {
+  tags?: ExtractStringLiterals<NonNullable<S['tags']>[number]> extends infer MT ? IsStringLiteral<MT> extends true ? Array<(string & {}) | MT | E['tag']> | undefined : Array<(string & {}) | E['tag']> | undefined : never;
+};
+//#endregion
+export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, SourceProps, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };

package/esm/index.js

@@ -37,6 +37,40 @@ function ShowHtml({ selector = "[data-testid=\"subject\"]", config, ...props })
 	});
 }
 
+//#endregion
+//#region src/components/story_card.tsx
+function storyCardTheme(state, className) {
+	const defaultClassName = storyCardVariants(state);
+	if (!className) return defaultClassName;
+	return typeof className === "function" ? className({
+		...state,
+		defaultClassName
+	}) : twMerge(defaultClassName, className);
+}
+const storyCardVariants = cva("flex flex-col gap-1 py-3 px-4 rounded text-black dark:text-gray-100", {
+	variants: { status: {
+		error: "bg-red-100 dark:bg-red-900",
+		warn: "bg-yellow-100 dark:bg-yellow-900",
+		info: "bg-sky-100 dark:bg-sky-900"
+	} },
+	defaultVariants: { status: "info" }
+});
+/**
+* A card component that displays information with optional title and status styling.
+*
+* @param props - StoryCard component props
+* @returns A section element containing the card content
+*/
+function StoryCard({ status, className, children, title }) {
+	return /* @__PURE__ */ jsxs("section", {
+		className: storyCardTheme({ status }, className),
+		children: [title && /* @__PURE__ */ jsx("h2", {
+			className: "text-lg font-bold",
+			children: title
+		}), children]
+	});
+}
+
 //#endregion
 //#region src/decorators/show_doc_source.tsx
 const channel = addons.getChannel();
@@ -44,7 +78,7 @@ const channel = addons.getChannel();
 * 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`.
 */
-function showDocSource() {
+function showDocSource(options) {
 	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;
@@ -53,6 +87,13 @@ function showDocSource() {
 			channel.on("DARK_MODE", setIsDark);
 			return () => channel.off("DARK_MODE", setIsDark);
 		}, []);
+		const code = 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, {
+			language,
+			children: code
+		});
 		return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme: convert(docs?.theme ?? (isDark ? themes.dark : themes.light)),
 			children: /* @__PURE__ */ jsxs("section", {
@@ -61,10 +102,10 @@ function showDocSource() {
 					flexDirection: "column",
 					gap: "1rem"
 				},
-				children: [/* @__PURE__ */ jsx(SyntaxHighlighter, {
-					language: docs?.source?.language,
-					children: docs?.source?.code
-				}), /* @__PURE__ */ jsx(Story, {})]
+				children: [/* @__PURE__ */ jsx(Story, {}), isOriginalSource ? /* @__PURE__ */ jsx(StoryCard, {
+					className: "bg-gray-100 dark:bg-gray-900",
+					children: content
+				}) : content]
 			})
 		});
 	};
@@ -178,43 +219,27 @@ function StoryCardContainer({ children }) {
 	const contextValue = useMemo(() => ({
 		addCard(card) {
 			const key = generateKey("story-card");
-			setCards((cards$1) => [...cards$1, {
+			setCards((cards) => [...cards, {
 				...card,
 				key
 			}]);
 			return key;
 		},
 		removeCard(key) {
-			setCards((cards$1) => cards$1.filter((card) => card.key !== key));
+			setCards((cards) => cards.filter((card) => card.key !== key));
 		}
 	}), []);
 	return /* @__PURE__ */ jsx(StoryCardContext.Provider, {
 		value: contextValue,
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "flex flex-col gap-2",
-			children: [cards.map(({ key, status, className, content, title }) => /* @__PURE__ */ jsxs("section", {
-				className: storyCardTheme({ status }, className),
-				children: [title && /* @__PURE__ */ jsx("h2", {
-					className: "text-lg font-bold",
-					children: title
-				}), content]
+			children: [cards.map(({ content, key, ...rest }) => /* @__PURE__ */ jsx(StoryCard, {
+				...rest,
+				children: content
 			}, key)), children]
 		})
 	});
 }
-function storyCardTheme(state, className) {
-	const defaultClassName = storyCardVariants(state);
-	if (!className) return defaultClassName;
-	return typeof className === "function" ? className({
-		...state,
-		defaultClassName
-	}) : twMerge(defaultClassName, className);
-}
-const storyCardVariants = cva("flex flex-col gap-1 py-3 px-4 rounded text-black dark:text-gray-100", { variants: { status: {
-	error: "bg-red-100 dark:bg-red-900",
-	warn: "bg-yellow-100 dark:bg-yellow-900",
-	info: "bg-sky-100 dark:bg-sky-900"
-} } });
 function StoryCardCollector({ Story, title, status, className, content }) {
 	const context = useContext(StoryCardContext);
 	const cardIdRef = useRef(null);
@@ -343,7 +368,7 @@ const defineLayoutParam = (layout) => ({ layout });
 * ```
 */
 function defineParameters(param, ...rest) {
-	return rest.reduce((acc, param$1) => Object.assign(acc, param$1), param);
+	return rest.reduce((acc, param) => Object.assign(acc, param), param);
 }
 
 //#endregion

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

@@ -1,13 +1,14 @@
 
 import { TagBadgeParameters } from "storybook-addon-tag-badges/manager-helpers";
 import { Args, Meta as Meta$1, StoryObj as StoryObj$1 } from "@storybook/react-vite";
+import { IsStringLiteral } from "type-plus";
 
 //#region src/storybook-addon-tag-badges/tag_badges.d.ts
 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';
+type TagNames = 'editor' | '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.
@@ -44,32 +45,14 @@ declare const internalBadge: TagBadgeParameter;
 declare const tagBadges: TagBadgeParameters;
 //#endregion
 //#region src/types.d.ts
-/**
- * Extends the Storybook Meta type with custom tag types
- * @template TCmpOrArgs - The component or args type
- * @template M - The base Meta type
- * @template E - The extension type containing tagType
- *
- * @example
- * ```ts
- * // Create a generic Meta type for a project
- * type Meta<TCmpOrArgs = Args> = ExtendMeta<TCmpOrArgs, Meta<TCmpOrArgs>, { tagType: 'tag1' | 'tag2' }>
- *
- * // Create a specific Meta type for a component
- * type Meta = ExtendMeta<typeof Component, Meta<typeof Component>, { tagType: 'tag1' | 'tag2' }>
- * ```
- */
-type ExtendMeta<TCmpOrArgs, M extends Meta$1<TCmpOrArgs>, E extends {
-  tag: string;
-}> = Omit<M, 'tags'> & {
-  tags?: Array<E['tag'] | (string & {})> | undefined;
-};
 /**
  * Extends the Storybook StoryObj type with custom tag types
  * @template TMetaOrCmpOrArgs - The meta, component or args type
  * @template S - The base StoryObj type
  * @template E - The extension type containing tagType
  *
+ * @deprecated use `import { ExtendsStoryObj } from '@repobuddy/storybook'` instead.
+ *
  * @example
  * ```ts
  * // Create a generic StoryObj type for a project
@@ -85,8 +68,47 @@ type ExtendStoryObj<TMetaOrCmpOrArgs, S extends StoryObj$1<TMetaOrCmpOrArgs>, E
   tags?: Array<E['tag'] | (string & {})> | undefined;
 };
 //#endregion
+//#region src/types/_extract_string_literals.d.ts
+type ExtractStringLiterals<T> = T extends any ? (string extends T ? never : T) : never;
+//#endregion
+//#region src/types/extends_meta.d.ts
+/**
+ * Extends the Storybook Meta type with custom tag types.
+ *
+ * This utility type allows you to extend the `tags` property of a Storybook Meta type
+ * with custom string literal types while preserving existing tag types from the base Meta.
+ *
+ * @template M - The base Meta type to extend
+ * @template E - The extension type containing a `tag` property with the custom tag types
+ *
+ * @example
+ * ```ts
+ * import type { ExtendsMeta } from '@repobuddy/storybook'
+ * import type { Args, Meta as M } from '@storybook/your-framework'
+ *
+ * // Create a generic Meta type for your project
+ * type Meta<TCmpOrArgs = Args> = ExtendsMeta<
+ *   M<TCmpOrArgs>,
+ *   { tag: 'new' | 'beta' | 'deprecated' }
+ * >
+ *
+ * // Use in component stories
+ * const meta: Meta<typeof Component> = {
+ *   tags: ['new'], // <--- gets auto-completion for 'new' | 'beta' | 'deprecated'
+ *   // ...
+ * }
+ * ```
+ */
+type ExtendsMeta<M extends {
+  tags?: string[] | undefined;
+}, E extends {
+  tag: string;
+}> = Omit<M, 'tags'> & {
+  tags?: ExtractStringLiterals<NonNullable<M['tags']>[number]> extends infer MT ? IsStringLiteral<MT> extends true ? Array<(string & {}) | MT | E['tag']> | undefined : Array<(string & {}) | E['tag']> | undefined : never;
+};
+//#endregion
 //#region src/storybook-addon-tag-badges/types.d.ts
-type Meta<TCmpOrArgs = Args> = ExtendMeta<TCmpOrArgs, Meta$1<TCmpOrArgs>, {
+type Meta<TCmpOrArgs = Args> = ExtendsMeta<Meta$1<TCmpOrArgs>, {
   tag: TagNames;
 }>;
 type StoryObj<TMetaOrCmpOrArgs = Args> = ExtendStoryObj<TMetaOrCmpOrArgs, StoryObj$1<TMetaOrCmpOrArgs>, {

package/esm/storybook-dark-mode/index.d.ts

@@ -7,7 +7,6 @@ import { CSSProperties } from "@just-web/css";
 import { DecoratorFunction } from "storybook/internal/types";
 
 //#region src/storybook-dark-mode/dark_mode_docs_container.d.ts
-
 /**
  * Creates a `DocsContainer` for `storybook` that works with `@storybook-community/storybook-dark-mode`.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -50,7 +50,7 @@
     "!**/*.mdx"
   ],
   "dependencies": {
-    "@just-web/css": "^0.7.0",
+    "@just-web/css": "^0.8.0",
     "@repobuddy/test": "^1.0.0",
     "class-variance-authority": "^0.7.1",
     "htmlfy": "^1.0.0",
@@ -76,7 +76,7 @@
     "storybook": "^10.1.10",
     "storybook-addon-tag-badges": "^3.0.2",
     "tailwindcss": "^4.1.17",
-    "tsdown": "^0.18.0",
+    "tsdown": "^0.20.0",
     "vite": "^7.3.0",
     "vitest": "^4.0.16"
   },

package/src/components/story_card.tsx

@@ -0,0 +1,67 @@
+import { cva } from 'class-variance-authority'
+import type { ReactNode } from 'react'
+import { twMerge } from 'tailwind-merge'
+
+export type StoryCardProps = {
+	/**
+	 * Optional title displayed as a heading in the card.
+	 * Can be any React node (string, JSX, etc.).
+	 */
+	title?: ReactNode | undefined
+	/**
+	 * Visual status of the card, affecting its background color.
+	 * - `'error'`: Red background (bg-red-100 dark:bg-red-900)
+	 * - `'warn'`: Yellow background (bg-yellow-100 dark:bg-yellow-900)
+	 * - `'info'`: Blue background (bg-sky-100 dark:bg-sky-900) - default
+	 */
+	status?: 'error' | 'warn' | 'info' | undefined
+	/**
+	 * Additional CSS classes or a function to compute classes.
+	 *
+	 * If a string is provided, it will be merged with the default classes.
+	 * If a function is provided, it receives the card state and default className,
+	 * and should return the final className string.
+	 */
+	className?: ((state: Pick<StoryCardProps, 'status'> & { defaultClassName: string }) => string) | string | undefined
+	/**
+	 * Content to display in the card body.
+	 * Can be any React node (string, JSX, etc.).
+	 */
+	children?: ReactNode | undefined
+}
+
+function storyCardTheme(state: Pick<StoryCardProps, 'status'>, className: StoryCardProps['className']) {
+	const defaultClassName = storyCardVariants(state)
+	if (!className) return defaultClassName
+	return typeof className === 'function'
+		? className({ ...state, defaultClassName })
+		: twMerge(defaultClassName, className)
+}
+
+const storyCardVariants = cva('flex flex-col gap-1 py-3 px-4 rounded text-black dark:text-gray-100', {
+	variants: {
+		status: {
+			error: 'bg-red-100 dark:bg-red-900',
+			warn: 'bg-yellow-100 dark:bg-yellow-900',
+			info: 'bg-sky-100 dark:bg-sky-900'
+		}
+	},
+	defaultVariants: {
+		status: 'info'
+	}
+})
+
+/**
+ * A card component that displays information with optional title and status styling.
+ *
+ * @param props - StoryCard component props
+ * @returns A section element containing the card content
+ */
+export function StoryCard({ status, className, children, title }: StoryCardProps) {
+	return (
+		<section className={storyCardTheme({ status }, className)}>
+			{title && <h2 className="text-lg font-bold">{title}</h2>}
+			{children}
+		</section>
+	)
+}

package/src/decorators/show_doc_source.tsx

@@ -3,6 +3,7 @@ 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 { StoryCard } from '../components/story_card'
 
 const channel = addons.getChannel()
 
@@ -10,10 +11,9 @@ const channel = addons.getChannel()
  * 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`.
  */
-export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(): DecoratorFunction<
-	TRenderer,
-	TArgs
-> {
+export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(options?: {
+	showOriginalSource?: boolean | undefined
+}): DecoratorFunction<TRenderer, TArgs> {
 	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')
@@ -26,6 +26,16 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 			return () => channel.off('DARK_MODE', setIsDark)
 		}, [])
 
+		const code = options?.showOriginalSource
+			? docs?.source?.originalSource
+			: (docs?.source?.code ?? docs?.source?.originalSource)
+
+		const language = code === docs?.source?.originalSource ? undefined : docs?.source?.language
+
+		const isOriginalSource = code === docs?.source?.originalSource
+
+		const content = <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>
+
 		return (
 			<ThemeProvider theme={convert(docs?.theme ?? (isDark ? themes.dark : themes.light))}>
 				<section
@@ -35,8 +45,8 @@ export function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Arg
 						gap: '1rem'
 					}}
 				>
-					<SyntaxHighlighter language={docs?.source?.language}>{docs?.source?.code}</SyntaxHighlighter>
 					<Story />
+					{isOriginalSource ? <StoryCard className="bg-gray-100 dark:bg-gray-900">{content}</StoryCard> : content}
 				</section>
 			</ThemeProvider>
 		)

package/src/decorators/with_story_card.tsx

@@ -1,4 +1,3 @@
-import { cva } from 'class-variance-authority'
 import {
 	createContext,
 	useContext,
@@ -10,23 +9,11 @@ import {
 	type ReactNode
 } from 'react'
 import type { DecoratorFunction, Renderer } from 'storybook/internal/csf'
-import { twMerge } from 'tailwind-merge'
 import type { RequiredPick } from 'type-plus'
+import { StoryCard, type StoryCardProps } from '../components/story_card.js'
 import { generateKey } from '../utils/generate_key.js'
 
-export type StoryCardProps = {
-	/**
-	 * Optional title displayed as a heading in the card.
-	 * Can be any React node (string, JSX, etc.).
-	 */
-	title?: ReactNode | undefined
-	/**
-	 * Visual status of the card, affecting its background color.
-	 * - `'error'`: Red background (bg-red-100 dark:bg-red-900)
-	 * - `'warn'`: Yellow background (bg-yellow-100 dark:bg-yellow-900)
-	 * - `'info'`: Blue background (bg-sky-100 dark:bg-sky-900) - default
-	 */
-	status?: 'error' | 'warn' | 'info' | undefined
+export type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
 	/**
 	 * Additional CSS classes or a function to compute classes.
 	 *
@@ -34,10 +21,7 @@ export type StoryCardProps = {
 	 * If a function is provided, it receives the card state and default className,
 	 * and should return the final className string.
 	 */
-	className?:
-		| ((state: Required<Pick<StoryCardProps, 'status'>> & { defaultClassName: string }) => string)
-		| string
-		| undefined
+	className?: ((state: Pick<StoryCardProps, 'status'> & { defaultClassName: string }) => string) | string | undefined
 	/**
 	 * Content to display in the card body.
 	 * Can be any React node (string, JSX, etc.).
@@ -120,7 +104,7 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 	status = 'info',
 	content: contentProp,
 	...rest
-}: StoryCardProps = {}): DecoratorFunction<TRenderer> {
+}: WithStoryCardProps = {}): DecoratorFunction<TRenderer> {
 	return (Story, { parameters, viewMode }) => {
 		if (viewMode === 'docs') return <Story />
 
@@ -131,7 +115,7 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 	}
 }
 
-interface StoryCardContainerWrapperProps extends RequiredPick<StoryCardProps, 'status'> {
+interface StoryCardContainerWrapperProps extends RequiredPick<WithStoryCardProps, 'status'> {
 	Story: ComponentType
 }
 
@@ -166,11 +150,10 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 	return (
 		<StoryCardContext.Provider value={contextValue}>
 			<div className="flex flex-col gap-2">
-				{cards.map(({ key, status, className, content, title }) => (
-					<section key={key} className={storyCardTheme({ status }, className)}>
-						{title && <h2 className="text-lg font-bold">{title}</h2>}
+				{cards.map(({ content, key, ...rest }) => (
+					<StoryCard key={key} {...rest}>
 						{content}
-					</section>
+					</StoryCard>
 				))}
 				{children}
 			</div>
@@ -178,27 +161,9 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 	)
 }
 
-type StoryCardWithKey = RequiredPick<StoryCardProps, 'status'> & { key: string }
-
-function storyCardTheme(state: Required<Pick<StoryCardProps, 'status'>>, className: StoryCardProps['className']) {
-	const defaultClassName = storyCardVariants(state)
-	if (!className) return defaultClassName
-	return typeof className === 'function'
-		? className({ ...state, defaultClassName })
-		: twMerge(defaultClassName, className)
-}
-
-const storyCardVariants = cva('flex flex-col gap-1 py-3 px-4 rounded text-black dark:text-gray-100', {
-	variants: {
-		status: {
-			error: 'bg-red-100 dark:bg-red-900',
-			warn: 'bg-yellow-100 dark:bg-yellow-900',
-			info: 'bg-sky-100 dark:bg-sky-900'
-		}
-	}
-})
+type StoryCardWithKey = RequiredPick<WithStoryCardProps, 'status'> & { key: string }
 
-interface StoryCardCollectorProps extends RequiredPick<StoryCardProps, 'status'> {
+interface StoryCardCollectorProps extends RequiredPick<WithStoryCardProps, 'status'> {
 	Story: ComponentType
 }
 
@@ -226,7 +191,7 @@ function StoryCardCollector({ Story, title, status, className, content }: StoryC
 }
 
 interface StoryCardContextValue {
-	addCard: (card: RequiredPick<StoryCardProps, 'status'>) => string
+	addCard: (card: RequiredPick<WithStoryCardProps, 'status'>) => string
 	removeCard: (id: string) => void
 }
 

package/src/index.ts

@@ -12,3 +12,5 @@ export * from './parameters/define_viewport_param.ts'
 export * from './parameters/story_sort.ts'
 export * from './testing/decorators/when_running_in_test.tsx'
 export type * from './types.ts'
+export * from './types/extends_meta.ts'
+export * from './types/extends_story_obj.ts'

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

@@ -23,6 +23,7 @@ export type TagNames =
 	| 'keyboard'
 	| 'internal'
 	| 'usecase'
+	| 'version:next'
 
 /**
  * Configuration for story tag badges that appear in the Storybook sidebar.

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

@@ -1,8 +1,9 @@
 import type { Args, Meta as M, StoryObj as SBO } from '@storybook/react-vite'
-import type { ExtendMeta, ExtendStoryObj } from '../types.js'
+import type { ExtendStoryObj } from '../types.js'
+import type { ExtendsMeta } from '../types/extends_meta.js'
 import type { TagNames } from './tag_badges.js'
 
-export type Meta<TCmpOrArgs = Args> = ExtendMeta<TCmpOrArgs, M<TCmpOrArgs>, { tag: TagNames }>
+export type Meta<TCmpOrArgs = Args> = ExtendsMeta<M<TCmpOrArgs>, { tag: TagNames }>
 
 export type StoryObj<TMetaOrCmpOrArgs = Args> = ExtendStoryObj<
 	TMetaOrCmpOrArgs,

package/src/types/_extract_string_literals.ts

@@ -0,0 +1 @@
+export type ExtractStringLiterals<T> = T extends any ? (string extends T ? never : T) : never

package/src/types/extends_meta.ts

@@ -0,0 +1,37 @@
+import type { IsStringLiteral } from 'type-plus'
+import type { ExtractStringLiterals } from './_extract_string_literals.js'
+
+/**
+ * Extends the Storybook Meta type with custom tag types.
+ *
+ * This utility type allows you to extend the `tags` property of a Storybook Meta type
+ * with custom string literal types while preserving existing tag types from the base Meta.
+ *
+ * @template M - The base Meta type to extend
+ * @template E - The extension type containing a `tag` property with the custom tag types
+ *
+ * @example
+ * ```ts
+ * import type { ExtendsMeta } from '@repobuddy/storybook'
+ * import type { Args, Meta as M } from '@storybook/your-framework'
+ *
+ * // Create a generic Meta type for your project
+ * type Meta<TCmpOrArgs = Args> = ExtendsMeta<
+ *   M<TCmpOrArgs>,
+ *   { tag: 'new' | 'beta' | 'deprecated' }
+ * >
+ *
+ * // Use in component stories
+ * const meta: Meta<typeof Component> = {
+ *   tags: ['new'], // <--- gets auto-completion for 'new' | 'beta' | 'deprecated'
+ *   // ...
+ * }
+ * ```
+ */
+export type ExtendsMeta<M extends { tags?: string[] | undefined }, E extends { tag: string }> = Omit<M, 'tags'> & {
+	tags?: ExtractStringLiterals<NonNullable<M['tags']>[number]> extends infer MT
+		? IsStringLiteral<MT> extends true
+			? Array<(string & {}) | MT | E['tag']> | undefined
+			: Array<(string & {}) | E['tag']> | undefined
+		: never
+}

package/src/types/extends_story_obj.ts

@@ -0,0 +1,42 @@
+import type { IsStringLiteral } from 'type-plus'
+import type { ExtractStringLiterals } from './_extract_string_literals.js'
+
+/**
+ * Extends the Storybook StoryObj type with custom tag types.
+ *
+ * This utility type allows you to extend the `tags` property of a Storybook StoryObj type
+ * with custom string literal types while preserving existing tag types from the base StoryObj.
+ *
+ * @template S - The base StoryObj type to extend (must have an optional `tags` property)
+ * @template E - The extension type containing a `tag` property with the custom tag types
+ *
+ * @example
+ * ```ts
+ * import type { ExtendsStoryObj } from '@repobuddy/storybook'
+ * import type { Args, StoryObj as S } from '@storybook/your-framework'
+ *
+ * // Create a generic StoryObj type for your project
+ * type StoryObj<TCmpOrArgs = Args> = ExtendsStoryObj<
+ *   S<TCmpOrArgs>,
+ *   { tag: 'new' | 'beta' | 'deprecated' }
+ * >
+ *
+ * // Use in component stories
+ * const story: StoryObj<typeof Component> = {
+ *   tags: ['new'], // <--- gets auto-completion for 'new' | 'beta' | 'deprecated'
+ *   // ...
+ * }
+ * ```
+ */
+export type ExtendsStoryObj<
+	S extends { tags?: string[] | undefined },
+	E extends {
+		tag: string
+	}
+> = Omit<S, 'tags'> & {
+	tags?: ExtractStringLiterals<NonNullable<S['tags']>[number]> extends infer MT
+		? IsStringLiteral<MT> extends true
+			? Array<(string & {}) | MT | E['tag']> | undefined
+			: Array<(string & {}) | E['tag']> | undefined
+		: never
+}

package/src/types.ts

@@ -6,6 +6,8 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
  * @template M - The base Meta type
  * @template E - The extension type containing tagType
  *
+ * @deprecated use `import { ExtendsMeta } from '@repobuddy/storybook'` instead.
+ *
  * @example
  * ```ts
  * // Create a generic Meta type for a project
@@ -31,6 +33,8 @@ export type ExtendMeta<
  * @template S - The base StoryObj type
  * @template E - The extension type containing tagType
  *
+ * @deprecated use `import { ExtendsStoryObj } from '@repobuddy/storybook'` instead.
+ *
  * @example
  * ```ts
  * // Create a generic StoryObj type for a project

package/styles.css

@@ -20,6 +20,7 @@
     --color-rose-900: oklch(41% 0.159 10.272);
     --color-gray-100: oklch(96.7% 0.003 264.542);
     --color-gray-500: oklch(55.1% 0.027 264.364);
+    --color-gray-900: oklch(21% 0.034 264.665);
     --color-black: #000;
     --color-white: #fff;
     --spacing: 0.25rem;
@@ -179,6 +180,11 @@
       background-color: var(--color-gray-500);
     }
   }
+  .dark\:bg-gray-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-gray-900);
+    }
+  }
   .dark\:bg-green-800 {
     &:where(.dark, .dark *) {
       background-color: var(--color-green-800);