@repobuddy/storybook 2.1.2 → 2.2.1

package/esm/index.d.ts

@@ -1,7 +1,10 @@
+
 import { UserConfig } from "htmlfy";
+import { ReactNode } from "react";
 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 { ClassValue } from "class-variance-authority/types";
 import { Decorator, Meta, StoryContext, StoryObj, StrictArgs } from "@storybook/react-vite";
 export * from "@repobuddy/test";
 
@@ -32,6 +35,112 @@ declare function ShowHtml({
  */
 declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(): DecoratorFunction<TRenderer, TArgs>;
 //#endregion
+//#region src/decorators/with_story_card.d.ts
+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) | ClassValue | undefined;
+  /**
+   * Content to display in the card body.
+   * Can be any React node (string, JSX, etc.).
+   *
+   * If not provided, the decorator will automatically use:
+   * 1. Story description (`parameters.docs.description.story`)
+   * 2. Component description (`parameters.docs.description.component`)
+   * 3. Nothing (card won't render if no content and no title)
+   */
+  content?: ReactNode | undefined;
+};
+/**
+ * A decorator that adds a card section to display additional information about the story.
+ *
+ * The card is automatically hidden when the story is shown in docs mode.
+ * Multiple decorators can be chained together,
+ * and all cards will be collected and displayed above the story content.
+ *
+ * @returns A Storybook decorator function.
+ *
+ * @example
+ * Basic usage - automatically uses component or story description:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: defineDocsParam({
+ *     description: {
+ *       story: 'This description will be shown in the card'
+ *     }
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
+ * With custom content:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({
+ *       content: <p>This is a custom message displayed in the card.</p>
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * With title and status:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({
+ *       title: 'Important Notice',
+ *       status: 'warn',
+ *       content: <p>Please review this carefully.</p>
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * Multiple cards:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({ title: 'First Card', status: 'info' }),
+ *     withStoryCard({ title: 'Second Card', status: 'warn' })
+ *   ]
+ * }
+ * ```
+ *
+ * @remarks
+ * - The card will not render if both `content` and `title` are missing.
+ * - If `content` is not provided, it will automatically use the story description,
+ *   or fall back to the component description.
+ * - Cards are collected and displayed in the order they are defined in the decorators array.
+ */
+declare function withStoryCard<TRenderer extends Renderer = Renderer>({
+  title,
+  content: contentProp,
+  ...rest
+}?: StoryCardProps): DecoratorFunction<TRenderer>;
+//#endregion
 //#region src/parameters/define_actions_param.d.ts
 interface ActionsParam {
   actions: {
@@ -571,4 +680,4 @@ 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, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest };
+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 };

package/esm/index.js

@@ -1,10 +1,13 @@
+
 import { isRunningInTest } from "@repobuddy/test";
 import { prettify } from "htmlfy";
-import { useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { SyntaxHighlighter } from "storybook/internal/components";
 import { addons } from "storybook/preview-api";
 import { ThemeProvider, convert, themes } from "storybook/theming";
+import { cva } from "class-variance-authority";
+import { twMerge } from "tailwind-merge";
 
 export * from "@repobuddy/test"
 
@@ -67,6 +70,174 @@ function showDocSource() {
 	};
 }
 
+//#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
+/**
+* A decorator that adds a card section to display additional information about the story.
+*
+* The card is automatically hidden when the story is shown in docs mode.
+* Multiple decorators can be chained together,
+* and all cards will be collected and displayed above the story content.
+*
+* @returns A Storybook decorator function.
+*
+* @example
+* Basic usage - automatically uses component or story description:
+* ```tsx
+* export const MyStory: Story = {
+*   parameters: defineDocsParam({
+*     description: {
+*       story: 'This description will be shown in the card'
+*     }
+*   }),
+*   decorators: [withStoryCard()]
+* }
+* ```
+*
+* @example
+* With custom content:
+* ```tsx
+* export const MyStory: Story = {
+*   decorators: [
+*     withStoryCard({
+*       content: <p>This is a custom message displayed in the card.</p>
+*     })
+*   ]
+* }
+* ```
+*
+* @example
+* With title and status:
+* ```tsx
+* export const MyStory: Story = {
+*   decorators: [
+*     withStoryCard({
+*       title: 'Important Notice',
+*       status: 'warn',
+*       content: <p>Please review this carefully.</p>
+*     })
+*   ]
+* }
+* ```
+*
+* @example
+* Multiple cards:
+* ```tsx
+* export const MyStory: Story = {
+*   decorators: [
+*     withStoryCard({ title: 'First Card', status: 'info' }),
+*     withStoryCard({ title: 'Second Card', status: 'warn' })
+*   ]
+* }
+* ```
+*
+* @remarks
+* - The card will not render if both `content` and `title` are missing.
+* - If `content` is not provided, it will automatically use the story description,
+*   or fall back to the component description.
+* - Cards are collected and displayed in the order they are defined in the decorators array.
+*/
+function withStoryCard({ title, content: contentProp, ...rest } = {}) {
+	return (Story, { parameters, viewMode }) => {
+		if (viewMode === "docs") return /* @__PURE__ */ jsx(Story, {});
+		const content = contentProp ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component;
+		if (!content && !title) return /* @__PURE__ */ jsx(Story, {});
+		return /* @__PURE__ */ jsx(StoryCardContainerWrapper, {
+			Story,
+			content,
+			title,
+			...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 id = generateKey("story-card");
+			setCards((cards$1) => [...cards$1, {
+				...card,
+				id
+			}]);
+			return id;
+		},
+		removeCard(id) {
+			setCards((cards$1) => cards$1.filter((card) => card.id !== id));
+		}
+	}), []);
+	return /* @__PURE__ */ jsx(StoryCardContext.Provider, {
+		value: contextValue,
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "flex flex-col gap-2",
+			children: [cards.map(({ id, status, className, content, title }) => /* @__PURE__ */ jsxs("section", {
+				className: storyCardTheme({ status }, className),
+				children: [title && /* @__PURE__ */ jsx("h2", {
+					className: "text-lg font-bold",
+					children: title
+				}), content]
+			}, id)), children]
+		})
+	});
+}
+const storyCardTheme = (state, className) => {
+	const defaultClassName = storyCardVariants(state);
+	if (!className) return defaultClassName;
+	return twMerge(defaultClassName, typeof className === "function" ? className({
+		...state,
+		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" }
+});
+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
 /**
@@ -248,4 +419,4 @@ function whenRunningInTest(decoratorOrHandler) {
 }
 
 //#endregion
-export { ShowHtml, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest };
+export { ShowHtml, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };

package/esm/manager/index.d.ts

@@ -1,3 +1,4 @@
+
 //#region src/manager/brand_title.d.ts
 interface BrandTitleOptions {
   /**

package/esm/manager/index.js

@@ -1,3 +1,4 @@
+
 //#region src/manager/brand_title.ts
 /**
 * Creates a brand title element for the Storybook manager UI.

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

@@ -1,3 +1,4 @@
+
 import { TagBadgeParameters } from "storybook-addon-tag-badges/manager-helpers";
 import { Args, Meta as Meta$1, StoryObj as StoryObj$1 } from "@storybook/react-vite";
 
@@ -6,7 +7,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';
+type TagNames = 'editor' | 'new' | 'beta' | 'props' | 'deprecated' | 'outdated' | 'danger' | 'todo' | 'code-only' | 'snapshot' | 'unit' | 'integration' | 'keyboard' | 'internal' | 'usecase';
 /**
  * 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.

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

@@ -1,3 +1,4 @@
+
 import { defaultConfig } from "storybook-addon-tag-badges/manager-helpers";
 
 //#region src/storybook-addon-tag-badges/tag_badges.ts

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

@@ -1,3 +1,4 @@
+
 import { DocsContextProps } from "@storybook/addon-docs/blocks";
 import { PropsWithChildren } from "react";
 import { ThemeVars } from "storybook/theming";

package/esm/storybook-dark-mode/index.js

@@ -1,3 +1,4 @@
+
 import { DARK_MODE_EVENT_NAME, useDarkMode } from "@storybook-community/storybook-dark-mode";
 import { DocsContainer } from "@storybook/addon-docs/blocks";
 import { useEffect, useState } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -38,44 +38,46 @@
     "./storybook-dark-mode": {
       "types": "./esm/storybook-dark-mode/index.d.ts",
       "default": "./esm/storybook-dark-mode/index.js"
-    }
+    },
+    "./styles.css": "./styles.css"
   },
   "files": [
     "cjs",
     "esm",
     "src",
+    "styles.css",
     "!**/*.{spec,test,unit,accept,integrate,system,perf,stress,study,stories}.*",
     "!**/*.mdx"
   ],
   "dependencies": {
     "@just-web/css": "^0.7.0",
     "@repobuddy/test": "^1.0.0",
-    "@storybook/icons": "^2.0.1",
-    "htmlfy": "^1.0.0"
+    "class-variance-authority": "^0.7.1",
+    "htmlfy": "^1.0.0",
+    "tailwind-merge": "^3.4.0"
   },
   "devDependencies": {
     "@repobuddy/vitest": "^2.0.0",
     "@storybook-community/storybook-dark-mode": "^7.0.2",
     "@storybook/addon-docs": "^10.0.7",
-    "@storybook/addon-themes": "^10.0.7",
     "@storybook/addon-vitest": "^10.0.7",
     "@storybook/react-vite": "^10.0.7",
     "@tailwindcss/cli": "^4.1.17",
     "@tailwindcss/vite": "^4.1.17",
-    "@vitest/browser": "^4.0.9",
-    "@vitest/browser-playwright": "^4.0.9",
-    "@vitest/coverage-v8": "^4.0.9",
+    "@vitest/browser": "^4.0.16",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
     "dedent": "^1.7.0",
-    "ncp": "^2.0.0",
+    "npm-run-all2": "^8.0.4",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "rimraf": "^6.1.0",
     "storybook": "^10.0.8",
     "storybook-addon-tag-badges": "^3.0.2",
     "tailwindcss": "^4.1.17",
-    "tsdown": "^0.16.6",
-    "vite": "^7.2.2",
-    "vitest": "^4.0.9"
+    "tsdown": "^0.18.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   },
   "peerDependencies": {
     "@storybook-community/storybook-dark-mode": "^7.0.0",
@@ -91,7 +93,9 @@
     }
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "run-p build:*",
+    "build:code": "tsdown",
+    "build:css": "tailwindcss -i ./tailwind.css -o ./styles.css",
     "clean": "rimraf .turbo coverage cjs esm storybook-static *.tsbuildinfo",
     "coverage": "vitest run --coverage",
     "sb": "storybook dev -p 6006",
@@ -100,6 +104,7 @@
     "test:dark": "vitest run --config=vitest.config.dark.ts",
     "test:light": "vitest run --config=vitest.config.light.ts",
     "test:theme": "vitest run --config=vitest.config.theme.ts",
+    "test:types": "tsc --noEmit",
     "w": "vitest"
   }
 }

package/readme.md

@@ -4,9 +4,11 @@ Your repository buddy for Storybook.
 
 > [!NOTE]
 >
-> This package supports Storybook 9.x from version `1.0.0`.
+> For Storybook 10, please use version `2.x`.
 >
-> For Storybook 8.x, please use `0.x` version.
+> For Storybook 9, please use version `1.x`.
+>
+> For Storybook 8.x, please use version `0.x`.
 
 ## Install
 
@@ -14,6 +16,8 @@ Your repository buddy for Storybook.
 pnpm add -D @repobuddy/storybook
 ```
 
+If you use the components in the library, import `@repobuddy/storybook/styles.css`.
+
 ## Features
 
 ### Typed Parameters

package/src/decorators/with_story_card.tsx

@@ -0,0 +1,236 @@
+import { cva } from 'class-variance-authority'
+import type { ClassValue } from 'class-variance-authority/types'
+import {
+	createContext,
+	useContext,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+	type ComponentType,
+	type ReactNode
+} from 'react'
+import type { DecoratorFunction, Renderer } from 'storybook/internal/csf'
+import { twMerge } from 'tailwind-merge'
+import { generateKey } from '../utils/generate_key'
+
+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)
+		| ClassValue
+		| undefined
+	/**
+	 * Content to display in the card body.
+	 * Can be any React node (string, JSX, etc.).
+	 *
+	 * If not provided, the decorator will automatically use:
+	 * 1. Story description (`parameters.docs.description.story`)
+	 * 2. Component description (`parameters.docs.description.component`)
+	 * 3. Nothing (card won't render if no content and no title)
+	 */
+	content?: ReactNode | undefined
+}
+
+/**
+ * A decorator that adds a card section to display additional information about the story.
+ *
+ * The card is automatically hidden when the story is shown in docs mode.
+ * Multiple decorators can be chained together,
+ * and all cards will be collected and displayed above the story content.
+ *
+ * @returns A Storybook decorator function.
+ *
+ * @example
+ * Basic usage - automatically uses component or story description:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: defineDocsParam({
+ *     description: {
+ *       story: 'This description will be shown in the card'
+ *     }
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
+ * With custom content:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({
+ *       content: <p>This is a custom message displayed in the card.</p>
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * With title and status:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({
+ *       title: 'Important Notice',
+ *       status: 'warn',
+ *       content: <p>Please review this carefully.</p>
+ *     })
+ *   ]
+ * }
+ * ```
+ *
+ * @example
+ * Multiple cards:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   decorators: [
+ *     withStoryCard({ title: 'First Card', status: 'info' }),
+ *     withStoryCard({ title: 'Second Card', status: 'warn' })
+ *   ]
+ * }
+ * ```
+ *
+ * @remarks
+ * - The card will not render if both `content` and `title` are missing.
+ * - If `content` is not provided, it will automatically use the story description,
+ *   or fall back to the component description.
+ * - Cards are collected and displayed in the order they are defined in the decorators array.
+ */
+export function withStoryCard<TRenderer extends Renderer = Renderer>({
+	title,
+	content: contentProp,
+	...rest
+}: StoryCardProps = {}): DecoratorFunction<TRenderer> {
+	return (Story, { parameters, viewMode }) => {
+		if (viewMode === 'docs') return <Story />
+
+		const content = contentProp ?? parameters.docs?.description?.story ?? parameters.docs?.description?.component
+		if (!content && !title) return <Story />
+
+		return <StoryCardContainerWrapper Story={Story} content={content} title={title} {...rest} />
+	}
+}
+
+interface StoryCardContainerWrapperProps extends StoryCardProps {
+	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<StoryCardWithId[]>([])
+
+	const contextValue: StoryCardContextValue = useMemo(
+		() => ({
+			addCard(card) {
+				const id = generateKey('story-card')
+				setCards((cards) => [...cards, { ...card, id }])
+				return id
+			},
+			removeCard(id) {
+				setCards((cards) => cards.filter((card) => card.id !== id))
+			}
+		}),
+		[]
+	)
+
+	return (
+		<StoryCardContext.Provider value={contextValue}>
+			<div className="flex flex-col gap-2">
+				{cards.map(({ id, status, className, content, title }) => (
+					<section key={id} className={storyCardTheme({ status }, className)}>
+						{title && <h2 className="text-lg font-bold">{title}</h2>}
+						{content}
+					</section>
+				))}
+				{children}
+			</div>
+		</StoryCardContext.Provider>
+	)
+}
+
+type StoryCardWithId = StoryCardProps & { id: string }
+
+const storyCardTheme = (state: Pick<StoryCardProps, 'status'>, className: StoryCardProps['className']) => {
+	const defaultClassName = storyCardVariants(state)
+	if (!className) return defaultClassName
+	return twMerge(
+		defaultClassName,
+		typeof className === 'function' ? className({ ...state, 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'
+	}
+})
+
+interface StoryCardCollectorProps extends StoryCardProps {
+	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: StoryCardProps) => string
+	removeCard: (id: string) => void
+}
+
+const StoryCardContext = createContext<StoryCardContextValue | null>(null)

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from '@repobuddy/test'
 export * from './components/show_html.tsx'
 export * from './decorators/show_doc_source.tsx'
+export * from './decorators/with_story_card.tsx'
 export * from './parameters/define_actions_param.ts'
 export * from './parameters/define_backgrounds_param.ts'
 export * from './parameters/define_docs_param.ts'

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

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

package/src/utils/generate_key.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export function generateKey(prefix?: string | undefined): string {
+	const randomId =
+		typeof crypto !== 'undefined' && crypto.randomUUID
+			? crypto.randomUUID()
+			: `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+
+	return prefix ? `${prefix}-${randomId}` : randomId
+}

package/styles.css

@@ -0,0 +1,344 @@
+/*! tailwindcss v4.1.18 | MIT License | https://tailwindcss.com */
+@layer properties;
+@layer theme, base, components, utilities;
+@layer theme {
+  :root, :host {
+    --color-red-100: oklch(93.6% 0.032 17.717);
+    --color-red-800: oklch(44.4% 0.177 26.899);
+    --color-red-900: oklch(39.6% 0.141 25.723);
+    --color-amber-300: oklch(87.9% 0.169 91.605);
+    --color-amber-900: oklch(41.4% 0.112 45.904);
+    --color-yellow-100: oklch(97.3% 0.071 103.193);
+    --color-yellow-900: oklch(42.1% 0.095 57.708);
+    --color-green-200: oklch(92.5% 0.084 155.995);
+    --color-green-800: oklch(44.8% 0.119 151.328);
+    --color-sky-100: oklch(95.1% 0.026 236.824);
+    --color-sky-500: oklch(68.5% 0.169 237.323);
+    --color-sky-900: oklch(39.1% 0.09 240.876);
+    --color-blue-500: oklch(62.3% 0.214 259.815);
+    --color-rose-400: oklch(71.2% 0.194 13.428);
+    --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-black: #000;
+    --color-white: #fff;
+    --spacing: 0.25rem;
+    --text-lg: 1.125rem;
+    --text-lg--line-height: calc(1.75 / 1.125);
+    --font-weight-extralight: 200;
+    --font-weight-bold: 700;
+    --font-weight-extrabold: 800;
+  }
+}
+@layer utilities {
+  .static {
+    position: static;
+  }
+  .container {
+    width: 100%;
+    @media (width >= 40rem) {
+      max-width: 40rem;
+    }
+    @media (width >= 48rem) {
+      max-width: 48rem;
+    }
+    @media (width >= 64rem) {
+      max-width: 64rem;
+    }
+    @media (width >= 80rem) {
+      max-width: 80rem;
+    }
+    @media (width >= 96rem) {
+      max-width: 96rem;
+    }
+  }
+  .flex {
+    display: flex;
+  }
+  .hidden {
+    display: none;
+  }
+  .inline {
+    display: inline;
+  }
+  .transform {
+    transform: var(--tw-rotate-x,) var(--tw-rotate-y,) var(--tw-rotate-z,) var(--tw-skew-x,) var(--tw-skew-y,);
+  }
+  .flex-col {
+    flex-direction: column;
+  }
+  .gap-1 {
+    gap: calc(var(--spacing) * 1);
+  }
+  .gap-2 {
+    gap: calc(var(--spacing) * 2);
+  }
+  .gap-4 {
+    gap: calc(var(--spacing) * 4);
+  }
+  .rounded {
+    border-radius: 0.25rem;
+  }
+  .border {
+    border-style: var(--tw-border-style);
+    border-width: 1px;
+  }
+  .border-2 {
+    border-style: var(--tw-border-style);
+    border-width: 2px;
+  }
+  .border-blue-500 {
+    border-color: var(--color-blue-500);
+  }
+  .bg-amber-300 {
+    background-color: var(--color-amber-300);
+  }
+  .bg-black {
+    background-color: var(--color-black);
+  }
+  .bg-gray-100 {
+    background-color: var(--color-gray-100);
+  }
+  .bg-green-200 {
+    background-color: var(--color-green-200);
+  }
+  .bg-green-800 {
+    background-color: var(--color-green-800);
+  }
+  .bg-red-100 {
+    background-color: var(--color-red-100);
+  }
+  .bg-red-800 {
+    background-color: var(--color-red-800);
+  }
+  .bg-rose-400 {
+    background-color: var(--color-rose-400);
+  }
+  .bg-sky-100 {
+    background-color: var(--color-sky-100);
+  }
+  .bg-sky-500 {
+    background-color: var(--color-sky-500);
+  }
+  .bg-white {
+    background-color: var(--color-white);
+  }
+  .bg-yellow-100 {
+    background-color: var(--color-yellow-100);
+  }
+  .p-2 {
+    padding: calc(var(--spacing) * 2);
+  }
+  .p-4 {
+    padding: calc(var(--spacing) * 4);
+  }
+  .px-4 {
+    padding-inline: calc(var(--spacing) * 4);
+  }
+  .py-3 {
+    padding-block: calc(var(--spacing) * 3);
+  }
+  .text-lg {
+    font-size: var(--text-lg);
+    line-height: var(--tw-leading, var(--text-lg--line-height));
+  }
+  .font-bold {
+    --tw-font-weight: var(--font-weight-bold);
+    font-weight: var(--font-weight-bold);
+  }
+  .font-extrabold {
+    --tw-font-weight: var(--font-weight-extrabold);
+    font-weight: var(--font-weight-extrabold);
+  }
+  .font-extralight {
+    --tw-font-weight: var(--font-weight-extralight);
+    font-weight: var(--font-weight-extralight);
+  }
+  .text-black {
+    color: var(--color-black);
+  }
+  .text-white {
+    color: var(--color-white);
+  }
+  .shadow-lg {
+    --tw-shadow: 0 10px 15px -3px var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 4px 6px -4px var(--tw-shadow-color, rgb(0 0 0 / 0.1));
+    box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
+  }
+  .dark\:bg-amber-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-amber-900);
+    }
+  }
+  .dark\:bg-black {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-black);
+    }
+  }
+  .dark\:bg-gray-500 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-gray-500);
+    }
+  }
+  .dark\:bg-green-800 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-green-800);
+    }
+  }
+  .dark\:bg-red-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-red-900);
+    }
+  }
+  .dark\:bg-rose-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-rose-900);
+    }
+  }
+  .dark\:bg-sky-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-sky-900);
+    }
+  }
+  .dark\:bg-yellow-900 {
+    &:where(.dark, .dark *) {
+      background-color: var(--color-yellow-900);
+    }
+  }
+  .dark\:font-extrabold {
+    &:where(.dark, .dark *) {
+      --tw-font-weight: var(--font-weight-extrabold);
+      font-weight: var(--font-weight-extrabold);
+    }
+  }
+  .dark\:text-gray-100 {
+    &:where(.dark, .dark *) {
+      color: var(--color-gray-100);
+    }
+  }
+  .dark\:text-white {
+    &:where(.dark, .dark *) {
+      color: var(--color-white);
+    }
+  }
+}
+@property --tw-rotate-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-rotate-z {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-x {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-skew-y {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-border-style {
+  syntax: "*";
+  inherits: false;
+  initial-value: solid;
+}
+@property --tw-font-weight {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-shadow-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-shadow-alpha {
+  syntax: "<percentage>";
+  inherits: false;
+  initial-value: 100%;
+}
+@property --tw-inset-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-inset-shadow-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-inset-shadow-alpha {
+  syntax: "<percentage>";
+  inherits: false;
+  initial-value: 100%;
+}
+@property --tw-ring-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-ring-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-inset-ring-color {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-inset-ring-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@property --tw-ring-inset {
+  syntax: "*";
+  inherits: false;
+}
+@property --tw-ring-offset-width {
+  syntax: "<length>";
+  inherits: false;
+  initial-value: 0px;
+}
+@property --tw-ring-offset-color {
+  syntax: "*";
+  inherits: false;
+  initial-value: #fff;
+}
+@property --tw-ring-offset-shadow {
+  syntax: "*";
+  inherits: false;
+  initial-value: 0 0 #0000;
+}
+@layer properties {
+  @supports ((-webkit-hyphens: none) and (not (margin-trim: inline))) or ((-moz-orient: inline) and (not (color:rgb(from red r g b)))) {
+    *, ::before, ::after, ::backdrop {
+      --tw-rotate-x: initial;
+      --tw-rotate-y: initial;
+      --tw-rotate-z: initial;
+      --tw-skew-x: initial;
+      --tw-skew-y: initial;
+      --tw-border-style: solid;
+      --tw-font-weight: initial;
+      --tw-shadow: 0 0 #0000;
+      --tw-shadow-color: initial;
+      --tw-shadow-alpha: 100%;
+      --tw-inset-shadow: 0 0 #0000;
+      --tw-inset-shadow-color: initial;
+      --tw-inset-shadow-alpha: 100%;
+      --tw-ring-color: initial;
+      --tw-ring-shadow: 0 0 #0000;
+      --tw-inset-ring-color: initial;
+      --tw-inset-ring-shadow: 0 0 #0000;
+      --tw-ring-inset: initial;
+      --tw-ring-offset-width: 0px;
+      --tw-ring-offset-color: #fff;
+      --tw-ring-offset-shadow: 0 0 #0000;
+    }
+  }
+}

package/src/variants/index.ts

@@ -1,3 +0,0 @@
-console.info('variants.index.ts.load')
-
-export const empty = {}

package/src/variants/package.json

@@ -1,3 +0,0 @@
-{
-	"type": "module"
-}

package/src/variants/preset.ts

@@ -1,22 +0,0 @@
-/**
- * User specifies `@repobuddy/storybook/variants/addon` in the `.storybook/main.ts`.
- *
- * Storybook loads it on the server side.
- *
- * It provides a default export (or in CJS, `module.exports =`) that contains:
- *
- * - `managerEntries` a function that returns an array of strings on where to load the manager (on the client side)
- * - `previewAnnotations` a function that returns an array of strings on where to load the preview (on the client side)
- * - `experimental_serverChannel` a function that handles the server-side channel
- */
-
-console.info('variants.preset.js.load')
-
-// export const managerEntries = ['@storybook-community/storybook-dark-mode/manager']
-// const previewAnnotations = (entry = []) => [...entry, require.resolve('@storybook-community/storybook-dark-mode')]
-// const previewAnnotations =  [ require.resolve('@storybook-community/storybook-dark-mode')]
-
-// module.exports = {
-// 	managerEntries,
-// 	// previewAnnotations
-// }