@repobuddy/storybook 2.7.0 → 2.9.0

package/esm/index.d.ts

@@ -41,6 +41,13 @@ declare function ShowHtml({
 }: ShowHtmlProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/components/story_card.d.ts
+/**
+ * Visual status of the card, affecting its background color.
+ * - `'error'`: Red background (rbsb:bg-red-100 rbsb:dark:bg-red-900)
+ * - `'warn'`: Yellow background (rbsb:bg-yellow-100 rbsb:dark:bg-yellow-900)
+ * - `'info'`: Blue background (rbsb:bg-sky-100 rbsb:dark:bg-sky-900) - default
+ */
+type StoryCardStatus = 'error' | 'warn' | 'info' | undefined;
 type StoryCardProps = {
   /**
    * Optional title displayed as a heading in the card.
@@ -53,7 +60,7 @@ type StoryCardProps = {
    * - `'warn'`: Yellow background (rbsb:bg-yellow-100 rbsb:dark:bg-yellow-900)
    * - `'info'`: Blue background (rbsb:bg-sky-100 rbsb:dark:bg-sky-900) - default
    */
-  status?: 'error' | 'warn' | 'info' | undefined;
+  status?: StoryCardStatus;
   /**
    * Additional CSS classes or a function to compute classes.
    *
@@ -70,6 +77,18 @@ type StoryCardProps = {
    */
   children?: ReactNode | undefined;
 };
+/**
+ * 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
+ */
+declare function StoryCard({
+  status,
+  className,
+  children,
+  title
+}: StoryCardProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/decorators/show_doc_source.d.ts
 /**
@@ -133,6 +152,19 @@ type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
  * ```
  *
  * @example
+ * Using defineStoryCard parameter:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: defineStoryCard({
+ *     title: 'Important Notice',
+ *     status: 'warn',
+ *     content: <p>Please review this carefully.</p>
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
  * With custom content:
  * ```tsx
  * export const MyStory: Story = {
@@ -179,6 +211,7 @@ declare function withStoryCard<TRenderer extends Renderer = Renderer>({
   title,
   status,
   content: contentProp,
+  className,
   ...rest
 }?: WithStoryCardProps): DecoratorFunction<TRenderer>;
 //#endregion
@@ -673,6 +706,87 @@ type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsPar
  */
 declare function defineParameters<P extends Record<string, any>>(param: P & StorybookBuiltInParams, ...rest: Array<StorybookBuiltInParams>): StorybookBuiltInParams;
 //#endregion
+//#region src/parameters/define_story_card_param.d.ts
+interface StoryCardParam {
+  storyCard: {
+    /**
+     * 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
+     * - `'warn'`: Yellow background
+     * - `'info'`: Blue background - default
+     */
+    status?: StoryCardStatus;
+    /**
+     * 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.).
+     *
+     * 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;
+  };
+}
+/**
+ * Defines story card parameters for Storybook stories.
+ *
+ * These parameters can be consumed by the `withStoryCard` decorator
+ * to automatically configure story cards without passing props directly.
+ *
+ * @param storyCard - Configuration for story card parameters
+ * @returns An object containing the story card parameter configuration
+ *
+ * @example
+ * ```tsx
+ * import { defineStoryCard, withStoryCard } from '@repobuddy/storybook'
+ *
+ * export const MyStory: Story = {
+ *   parameters: defineStoryCard({
+ *     title: 'Important Notice',
+ *     status: 'warn',
+ *     content: <p>Please review this carefully.</p>
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
+ * With automatic content from story description:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: {
+ *     ...defineDocsParam({
+ *       description: {
+ *         story: 'This description will be shown in the card'
+ *       }
+ *     }),
+ *     ...defineStoryCard({
+ *       title: 'Story Information',
+ *       status: 'info'
+ *     })
+ *   },
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ */
+declare function defineStoryCard(storyCard: StoryCardParam['storyCard']): StoryCardParam;
+//#endregion
 //#region src/testing/decorators/when_running_in_test.d.ts
 /**
  * executes the specified decorator or handler if the code is running in test.
@@ -800,4 +914,4 @@ type ExtendsStoryObj<S extends {
   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, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, SourceProps, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };
+export { ActionsParam, BackgroundsParam, DocsParam, ExtendMeta, ExtendStoryObj, ExtendsMeta, ExtendsStoryObj, FnToArgTypes, GlobalApiBackgroundsParam, GlobalApiViewportParam, LayoutParam, ShowHtml, ShowHtmlProps, SourceProps, StoryCard, StoryCardParam, StoryCardProps, StoryCardStatus, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, WithStoryCardProps, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCard, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };

package/esm/index.js

@@ -3,11 +3,11 @@ import { isRunningInTest } from "@repobuddy/test";
 import { prettify } from "htmlfy";
 import { createContext, 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";
 import { SyntaxHighlighter } from "storybook/internal/components";
 import { addons } from "storybook/preview-api";
 import { ThemeProvider, convert, themes } from "storybook/theming";
-import { twJoin, twMerge } from "tailwind-merge";
-import { cva } from "class-variance-authority";
 
 export * from "@repobuddy/test"
 
@@ -162,6 +162,19 @@ function generateKey(prefix) {
 * ```
 *
 * @example
+* Using defineStoryCard parameter:
+* ```tsx
+* export const MyStory: Story = {
+*   parameters: defineStoryCard({
+*     title: 'Important Notice',
+*     status: 'warn',
+*     content: <p>Please review this carefully.</p>
+*   }),
+*   decorators: [withStoryCard()]
+* }
+* ```
+*
+* @example
 * With custom content:
 * ```tsx
 * export const MyStory: Story = {
@@ -204,16 +217,22 @@ function generateKey(prefix) {
 *   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, status = "info", content: contentProp, ...rest } = {}) {
+function withStoryCard({ title, status, content: contentProp, className, ...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, {});
+		const storyCardParam = parameters.storyCard;
+		const finalTitle = title ?? storyCardParam?.title;
+		const finalStatus = status ?? storyCardParam?.status ?? "info";
+		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(StoryCardContainerWrapper, {
 			Story,
 			content,
-			title,
-			status,
+			title: finalTitle,
+			status: finalStatus,
+			className: finalClassName,
 			...rest
 		});
 	};
@@ -384,6 +403,54 @@ function defineParameters(param, ...rest) {
 	return rest.reduce((acc, param) => Object.assign(acc, param), param);
 }
 
+//#endregion
+//#region src/parameters/define_story_card_param.ts
+/**
+* Defines story card parameters for Storybook stories.
+*
+* These parameters can be consumed by the `withStoryCard` decorator
+* to automatically configure story cards without passing props directly.
+*
+* @param storyCard - Configuration for story card parameters
+* @returns An object containing the story card parameter configuration
+*
+* @example
+* ```tsx
+* import { defineStoryCard, withStoryCard } from '@repobuddy/storybook'
+*
+* export const MyStory: Story = {
+*   parameters: defineStoryCard({
+*     title: 'Important Notice',
+*     status: 'warn',
+*     content: <p>Please review this carefully.</p>
+*   }),
+*   decorators: [withStoryCard()]
+* }
+* ```
+*
+* @example
+* With automatic content from story description:
+* ```tsx
+* export const MyStory: Story = {
+*   parameters: {
+*     ...defineDocsParam({
+*       description: {
+*         story: 'This description will be shown in the card'
+*       }
+*     }),
+*     ...defineStoryCard({
+*       title: 'Story Information',
+*       status: 'info'
+*     })
+*   },
+*   decorators: [withStoryCard()]
+* }
+* ```
+*/
+function defineStoryCard(storyCard) {
+	return { storyCard };
+}
+
 //#endregion
 //#region src/parameters/define_test_param.ts
 /**
@@ -455,4 +522,4 @@ function whenRunningInTest(decoratorOrHandler) {
 }
 
 //#endregion
-export { ShowHtml, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };
+export { ShowHtml, StoryCard, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineStoryCard, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -60,9 +60,9 @@
   "devDependencies": {
     "@repobuddy/vitest": "^2.0.0",
     "@storybook-community/storybook-dark-mode": "^7.0.2",
-    "@storybook/addon-docs": "^10.1.10",
+    "@storybook/addon-docs": "^10.2.4",
     "@storybook/addon-vitest": "^10.1.10",
-    "@storybook/react-vite": "^10.1.10",
+    "@storybook/react-vite": "^10.2.4",
     "@tailwindcss/cli": "^4.1.17",
     "@tailwindcss/vite": "^4.1.17",
     "@vitest/browser": "^4.0.16",
@@ -82,7 +82,7 @@
   },
   "peerDependencies": {
     "@storybook-community/storybook-dark-mode": "^7.0.0",
-    "@storybook/addon-docs": "^10.1.10",
+    "@storybook/addon-docs": "^10.2.4",
     "storybook-addon-tag-badges": "^3.0.2"
   },
   "peerDependenciesMeta": {

package/src/components/story_card.tsx

@@ -2,6 +2,14 @@ import { cva } from 'class-variance-authority'
 import type { ReactNode } from 'react'
 import { twJoin, twMerge } from 'tailwind-merge'
 
+/**
+ * Visual status of the card, affecting its background color.
+ * - `'error'`: Red background (rbsb:bg-red-100 rbsb:dark:bg-red-900)
+ * - `'warn'`: Yellow background (rbsb:bg-yellow-100 rbsb:dark:bg-yellow-900)
+ * - `'info'`: Blue background (rbsb:bg-sky-100 rbsb:dark:bg-sky-900) - default
+ */
+export type StoryCardStatus = 'error' | 'warn' | 'info' | undefined
+
 export type StoryCardProps = {
 	/**
 	 * Optional title displayed as a heading in the card.
@@ -14,7 +22,7 @@ export type StoryCardProps = {
 	 * - `'warn'`: Yellow background (rbsb:bg-yellow-100 rbsb:dark:bg-yellow-900)
 	 * - `'info'`: Blue background (rbsb:bg-sky-100 rbsb:dark:bg-sky-900) - default
 	 */
-	status?: 'error' | 'warn' | 'info' | undefined
+	status?: StoryCardStatus
 	/**
 	 * Additional CSS classes or a function to compute classes.
 	 *

package/src/decorators/with_story_card.tsx

@@ -11,6 +11,7 @@ import {
 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 { StoryCardParam } from '../parameters/define_story_card_param.js'
 import { generateKey } from '../utils/generate_key.js'
 
 export type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'> & {
@@ -57,6 +58,19 @@ export type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'>
  * ```
  *
  * @example
+ * Using defineStoryCard parameter:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: defineStoryCard({
+ *     title: 'Important Notice',
+ *     status: 'warn',
+ *     content: <p>Please review this carefully.</p>
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
  * With custom content:
  * ```tsx
  * export const MyStory: Story = {
@@ -101,17 +115,37 @@ export type WithStoryCardProps = Omit<StoryCardProps, 'children' | 'className'>
  */
 export function withStoryCard<TRenderer extends Renderer = Renderer>({
 	title,
-	status = 'info',
+	status,
 	content: contentProp,
+	className,
 	...rest
 }: WithStoryCardProps = {}): 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} status={status} {...rest} />
+		// Get story card config from parameters if available
+		const storyCardParam = (parameters as Partial<StoryCardParam>).storyCard
+		// Decorator props override parameter values
+		// Use parameters as fallback when decorator props are not provided
+		const finalTitle = title ?? storyCardParam?.title
+		const finalStatus = status ?? storyCardParam?.status ?? 'info'
+		const finalContent = contentProp ?? storyCardParam?.content
+		const finalClassName = className ?? storyCardParam?.className
+
+		// 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 (
+			<StoryCardContainerWrapper
+				Story={Story}
+				content={content}
+				title={finalTitle}
+				status={finalStatus}
+				className={finalClassName}
+				{...rest}
+			/>
+		)
 	}
 }
 

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from '@repobuddy/test'
 export type * from './arg-types/fn-to-arg-types.ts'
 export * from './components/show_html.tsx'
+export * from './components/story_card.tsx'
 export * from './decorators/show_doc_source.tsx'
 export * from './decorators/with_story_card.tsx'
 export * from './parameters/define_actions_param.ts'
@@ -8,6 +9,7 @@ export * from './parameters/define_backgrounds_param.ts'
 export * from './parameters/define_docs_param.ts'
 export * from './parameters/define_layout_param.ts'
 export * from './parameters/define_parameters.ts'
+export * from './parameters/define_story_card_param.ts'
 export * from './parameters/define_test_param.ts'
 export * from './parameters/define_viewport_param.ts'
 export * from './parameters/story_sort.ts'

package/src/parameters/define_story_card_param.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from 'react'
+import type { StoryCardProps, StoryCardStatus } from '../components/story_card.js'
+
+export interface StoryCardParam {
+	storyCard: {
+		/**
+		 * 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
+		 * - `'warn'`: Yellow background
+		 * - `'info'`: Blue background - default
+		 */
+		status?: StoryCardStatus
+		/**
+		 * 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.).
+		 *
+		 * 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
+	}
+}
+
+/**
+ * Defines story card parameters for Storybook stories.
+ *
+ * These parameters can be consumed by the `withStoryCard` decorator
+ * to automatically configure story cards without passing props directly.
+ *
+ * @param storyCard - Configuration for story card parameters
+ * @returns An object containing the story card parameter configuration
+ *
+ * @example
+ * ```tsx
+ * import { defineStoryCard, withStoryCard } from '@repobuddy/storybook'
+ *
+ * export const MyStory: Story = {
+ *   parameters: defineStoryCard({
+ *     title: 'Important Notice',
+ *     status: 'warn',
+ *     content: <p>Please review this carefully.</p>
+ *   }),
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ *
+ * @example
+ * With automatic content from story description:
+ * ```tsx
+ * export const MyStory: Story = {
+ *   parameters: {
+ *     ...defineDocsParam({
+ *       description: {
+ *         story: 'This description will be shown in the card'
+ *       }
+ *     }),
+ *     ...defineStoryCard({
+ *       title: 'Story Information',
+ *       status: 'info'
+ *     })
+ *   },
+ *   decorators: [withStoryCard()]
+ * }
+ * ```
+ */
+export function defineStoryCard(storyCard: StoryCardParam['storyCard']): StoryCardParam {
+	return { storyCard }
+}

package/styles.css

@@ -4,13 +4,16 @@
 @layer theme {
   :root, :host {
     --rbsb-color-red-100: oklch(93.6% 0.032 17.717);
+    --rbsb-color-red-500: oklch(63.7% 0.237 25.331);
     --rbsb-color-red-800: oklch(44.4% 0.177 26.899);
     --rbsb-color-red-900: oklch(39.6% 0.141 25.723);
     --rbsb-color-amber-300: oklch(87.9% 0.169 91.605);
     --rbsb-color-amber-900: oklch(41.4% 0.112 45.904);
     --rbsb-color-yellow-100: oklch(97.3% 0.071 103.193);
+    --rbsb-color-yellow-500: oklch(79.5% 0.184 86.047);
     --rbsb-color-yellow-900: oklch(42.1% 0.095 57.708);
     --rbsb-color-green-200: oklch(92.5% 0.084 155.995);
+    --rbsb-color-green-500: oklch(72.3% 0.219 149.579);
     --rbsb-color-green-800: oklch(44.8% 0.119 151.328);
     --rbsb-color-sky-100: oklch(95.1% 0.026 236.824);
     --rbsb-color-sky-500: oklch(68.5% 0.169 237.323);
@@ -37,9 +40,18 @@
   }
 }
 @layer utilities {
+  .rbsb\:ml-4 {
+    margin-left: calc(var(--rbsb-spacing) * 4);
+  }
   .rbsb\:flex {
     display: flex;
   }
+  .rbsb\:list-inside {
+    list-style-position: inside;
+  }
+  .rbsb\:list-disc {
+    list-style-type: disc;
+  }
   .rbsb\:flex-col {
     flex-direction: column;
   }
@@ -52,6 +64,9 @@
   .rbsb\:gap-4 {
     gap: calc(var(--rbsb-spacing) * 4);
   }
+  .rbsb\:self-start {
+    align-self: flex-start;
+  }
   .rbsb\:rounded {
     border-radius: 0.25rem;
   }
@@ -65,9 +80,24 @@
   .rbsb\:border-blue-500 {
     border-color: var(--rbsb-color-blue-500);
   }
+  .rbsb\:border-gray-500 {
+    border-color: var(--rbsb-color-gray-500);
+  }
+  .rbsb\:border-green-500 {
+    border-color: var(--rbsb-color-green-500);
+  }
   .rbsb\:border-purple-500 {
     border-color: var(--rbsb-color-purple-500);
   }
+  .rbsb\:border-red-500 {
+    border-color: var(--rbsb-color-red-500);
+  }
+  .rbsb\:border-sky-500 {
+    border-color: var(--rbsb-color-sky-500);
+  }
+  .rbsb\:border-yellow-500 {
+    border-color: var(--rbsb-color-yellow-500);
+  }
   .rbsb\:bg-amber-300 {
     background-color: var(--rbsb-color-amber-300);
   }
@@ -116,6 +146,9 @@
   .rbsb\:px-4 {
     padding-inline: calc(var(--rbsb-spacing) * 4);
   }
+  .rbsb\:py-2 {
+    padding-block: calc(var(--rbsb-spacing) * 2);
+  }
   .rbsb\:py-3 {
     padding-block: calc(var(--rbsb-spacing) * 3);
   }