@repobuddy/storybook 2.2.1 → 2.3.0

package/esm/index.d.ts

@@ -4,8 +4,8 @@ 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";
+import { IsStringLiteral } from "type-plus";
 export * from "@repobuddy/test";
 
 //#region src/components/show_html.d.ts
@@ -56,9 +56,9 @@ type StoryCardProps = {
    * 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'> & {
+  className?: ((state: Required<Pick<StoryCardProps, 'status'>> & {
     defaultClassName: string;
-  }) => string) | ClassValue | undefined;
+  }) => string) | string | undefined;
   /**
    * Content to display in the card body.
    * Can be any React node (string, JSX, etc.).
@@ -137,6 +137,7 @@ type StoryCardProps = {
  */
 declare function withStoryCard<TRenderer extends Renderer = Renderer>({
   title,
+  status,
   content: contentProp,
   ...rest
 }?: StoryCardProps): DecoratorFunction<TRenderer>;
@@ -645,6 +646,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 +668,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 +685,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, StoryCardProps, StorySortParam, StorybookBuiltInParams, TestParam, Viewport, ViewportParam, defineActionsParam, defineBackgroundsParam, defineDocsParam, defineLayoutParam, defineParameters, defineTestParam, defineViewportParam, showDocSource, whenRunningInTest, withStoryCard };

package/esm/index.js

@@ -150,7 +150,7 @@ 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, content: contentProp, ...rest } = {}) {
+function withStoryCard({ title, status = "info", 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;
@@ -159,6 +159,7 @@ function withStoryCard({ title, content: contentProp, ...rest } = {}) {
 			Story,
 			content,
 			title,
+			status,
 			...rest
 		});
 	};
@@ -176,47 +177,44 @@ function StoryCardContainer({ children }) {
 	const [cards, setCards] = useState([]);
 	const contextValue = useMemo(() => ({
 		addCard(card) {
-			const id = generateKey("story-card");
+			const key = generateKey("story-card");
 			setCards((cards$1) => [...cards$1, {
 				...card,
-				id
+				key
 			}]);
-			return id;
+			return key;
 		},
-		removeCard(id) {
-			setCards((cards$1) => cards$1.filter((card) => card.id !== id));
+		removeCard(key) {
+			setCards((cards$1) => cards$1.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(({ id, status, className, content, title }) => /* @__PURE__ */ jsxs("section", {
+			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]
-			}, id)), children]
+			}, key)), children]
 		})
 	});
 }
-const storyCardTheme = (state, className) => {
+function storyCardTheme(state, className) {
 	const defaultClassName = storyCardVariants(state);
 	if (!className) return defaultClassName;
-	return twMerge(defaultClassName, typeof className === "function" ? className({
+	return 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" }
-});
+	}) : 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);

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

@@ -1,6 +1,7 @@
 
 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];
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -54,14 +54,15 @@
     "@repobuddy/test": "^1.0.0",
     "class-variance-authority": "^0.7.1",
     "htmlfy": "^1.0.0",
-    "tailwind-merge": "^3.4.0"
+    "tailwind-merge": "^3.4.0",
+    "type-plus": "8.0.0-beta.7"
   },
   "devDependencies": {
     "@repobuddy/vitest": "^2.0.0",
     "@storybook-community/storybook-dark-mode": "^7.0.2",
-    "@storybook/addon-docs": "^10.0.7",
-    "@storybook/addon-vitest": "^10.0.7",
-    "@storybook/react-vite": "^10.0.7",
+    "@storybook/addon-docs": "^10.1.10",
+    "@storybook/addon-vitest": "^10.1.10",
+    "@storybook/react-vite": "^10.1.10",
     "@tailwindcss/cli": "^4.1.17",
     "@tailwindcss/vite": "^4.1.17",
     "@vitest/browser": "^4.0.16",
@@ -72,7 +73,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "rimraf": "^6.1.0",
-    "storybook": "^10.0.8",
+    "storybook": "^10.1.10",
     "storybook-addon-tag-badges": "^3.0.2",
     "tailwindcss": "^4.1.17",
     "tsdown": "^0.18.0",
@@ -81,7 +82,7 @@
   },
   "peerDependencies": {
     "@storybook-community/storybook-dark-mode": "^7.0.0",
-    "@storybook/addon-docs": "^10.0.0",
+    "@storybook/addon-docs": "^10.1.10",
     "storybook-addon-tag-badges": "^3.0.2"
   },
   "peerDependenciesMeta": {

package/src/decorators/with_story_card.tsx

@@ -1,5 +1,4 @@
 import { cva } from 'class-variance-authority'
-import type { ClassValue } from 'class-variance-authority/types'
 import {
 	createContext,
 	useContext,
@@ -12,7 +11,8 @@ import {
 } from 'react'
 import type { DecoratorFunction, Renderer } from 'storybook/internal/csf'
 import { twMerge } from 'tailwind-merge'
-import { generateKey } from '../utils/generate_key'
+import type { RequiredPick } from 'type-plus'
+import { generateKey } from '../utils/generate_key.js'
 
 export type StoryCardProps = {
 	/**
@@ -35,8 +35,8 @@ export type StoryCardProps = {
 	 * and should return the final className string.
 	 */
 	className?:
-		| ((state: Pick<StoryCardProps, 'status'> & { defaultClassName: string }) => string)
-		| ClassValue
+		| ((state: Required<Pick<StoryCardProps, 'status'>> & { defaultClassName: string }) => string)
+		| string
 		| undefined
 	/**
 	 * Content to display in the card body.
@@ -117,6 +117,7 @@ export type StoryCardProps = {
  */
 export function withStoryCard<TRenderer extends Renderer = Renderer>({
 	title,
+	status = 'info',
 	content: contentProp,
 	...rest
 }: StoryCardProps = {}): DecoratorFunction<TRenderer> {
@@ -126,11 +127,11 @@ export function withStoryCard<TRenderer extends Renderer = Renderer>({
 		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} />
+		return <StoryCardContainerWrapper Story={Story} content={content} title={title} status={status} {...rest} />
 	}
 }
 
-interface StoryCardContainerWrapperProps extends StoryCardProps {
+interface StoryCardContainerWrapperProps extends RequiredPick<StoryCardProps, 'status'> {
 	Story: ComponentType
 }
 
@@ -146,17 +147,17 @@ function StoryCardContainerWrapper({ Story, ...props }: StoryCardContainerWrappe
 }
 
 function StoryCardContainer({ children }: { children: ReactNode }) {
-	const [cards, setCards] = useState<StoryCardWithId[]>([])
+	const [cards, setCards] = useState<StoryCardWithKey[]>([])
 
 	const contextValue: StoryCardContextValue = useMemo(
 		() => ({
 			addCard(card) {
-				const id = generateKey('story-card')
-				setCards((cards) => [...cards, { ...card, id }])
-				return id
+				const key = generateKey('story-card')
+				setCards((cards) => [...cards, { ...card, key }])
+				return key
 			},
-			removeCard(id) {
-				setCards((cards) => cards.filter((card) => card.id !== id))
+			removeCard(key) {
+				setCards((cards) => cards.filter((card) => card.key !== key))
 			}
 		}),
 		[]
@@ -165,8 +166,8 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 	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)}>
+				{cards.map(({ key, status, className, content, title }) => (
+					<section key={key} className={storyCardTheme({ status }, className)}>
 						{title && <h2 className="text-lg font-bold">{title}</h2>}
 						{content}
 					</section>
@@ -177,15 +178,14 @@ function StoryCardContainer({ children }: { children: ReactNode }) {
 	)
 }
 
-type StoryCardWithId = StoryCardProps & { id: string }
+type StoryCardWithKey = RequiredPick<StoryCardProps, 'status'> & { key: string }
 
-const storyCardTheme = (state: Pick<StoryCardProps, 'status'>, className: StoryCardProps['className']) => {
+function storyCardTheme(state: Required<Pick<StoryCardProps, 'status'>>, className: StoryCardProps['className']) {
 	const defaultClassName = storyCardVariants(state)
 	if (!className) return defaultClassName
-	return twMerge(
-		defaultClassName,
-		typeof className === 'function' ? className({ ...state, defaultClassName }) : className
-	)
+	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', {
@@ -195,13 +195,10 @@ const storyCardVariants = cva('flex flex-col gap-1 py-3 px-4 rounded text-black
 			warn: 'bg-yellow-100 dark:bg-yellow-900',
 			info: 'bg-sky-100 dark:bg-sky-900'
 		}
-	},
-	defaultVariants: {
-		status: 'info'
 	}
 })
 
-interface StoryCardCollectorProps extends StoryCardProps {
+interface StoryCardCollectorProps extends RequiredPick<StoryCardProps, 'status'> {
 	Story: ComponentType
 }
 
@@ -229,7 +226,7 @@ function StoryCardCollector({ Story, title, status, className, content }: StoryC
 }
 
 interface StoryCardContextValue {
-	addCard: (card: StoryCardProps) => string
+	addCard: (card: RequiredPick<StoryCardProps, '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/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