@repobuddy/storybook 0.3.1 → 0.4.0

package/esm/decorators/show_doc_source.d.ts

@@ -1,2 +1,6 @@
 import type { Args, DecoratorFunction, Renderer } from 'storybook/internal/csf';
+/**
+ * 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 declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(): DecoratorFunction<TRenderer, TArgs>;

package/esm/decorators/show_doc_source.js

@@ -1,4 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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() {
     return (Story, { parameters }) => {
         return (_jsxs("section", { style: {

package/esm/decorators/when_running_in_test.d.ts

@@ -0,0 +1,5 @@
+import type { Decorator, StrictArgs } from '@storybook/react';
+/**
+ * executes the specified decorator or handler if the code is running in test.
+ */
+export declare function whenRunningInTest<TArgs = StrictArgs>(decoratorOrHandler: ((...args: Parameters<Decorator<TArgs>>) => ReturnType<Decorator<TArgs>> | undefined | void) | (() => ReturnType<Decorator<TArgs>> | undefined | void)): Decorator<TArgs>;

package/esm/decorators/when_running_in_test.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ctx } from "./when_running_in_text.ctx.js";
+/**
+ * executes the specified decorator or handler if the code is running in test.
+ */
+export function whenRunningInTest(decoratorOrHandler) {
+    return function RunInTest(Story, context) {
+        return ctx.isRunningInTest() ? (decoratorOrHandler(Story, context) ?? _jsx(Story, {})) : _jsx(Story, {});
+    };
+}

package/esm/decorators/when_running_in_text.ctx.d.ts

@@ -0,0 +1,4 @@
+import { isRunningInTest } from '@repobuddy/vitest';
+export declare const ctx: {
+    isRunningInTest: typeof isRunningInTest;
+};

package/esm/decorators/when_running_in_text.ctx.js

@@ -0,0 +1,4 @@
+import { isRunningInTest } from '@repobuddy/vitest';
+export const ctx = {
+    isRunningInTest
+};

package/esm/index.d.ts

@@ -1,4 +1,5 @@
 export * from './decorators/show_doc_source.tsx';
+export * from './decorators/when_running_in_test.tsx';
 export * from './parameters/define_actions_param.ts';
 export * from './parameters/define_backgrounds_param.ts';
 export * from './parameters/define_docs_param.ts';

package/esm/index.js

@@ -1,4 +1,5 @@
 export * from "./decorators/show_doc_source.js";
+export * from "./decorators/when_running_in_test.js";
 export * from "./parameters/define_actions_param.js";
 export * from "./parameters/define_backgrounds_param.js";
 export * from "./parameters/define_docs_param.js";

package/esm/manager/tag_badges.d.ts

@@ -1,2 +1,19 @@
 import { type TagBadgeParameters } from 'storybook-addon-tag-badges';
+/**
+ * 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.
+ *
+ * The badges help visually identify stories with certain characteristics:
+ * - 🆕 New - Recently added stories
+ * - 🅱️ Beta - Stories for features in beta
+ * - 🪦 Deprecated - Stories for deprecated features
+ * - ⚠️ Outdated - Stories that need updating
+ * - 🚨 Danger - Stories demonstrating dangerous patterns
+ * - 📋 Todo - Stories marked as todo/incomplete
+ * - 📝 Code Only - Stories without visual examples
+ * - 🧪 Unit - Stories with unit tests
+ * - 🔄 Integration - Stories with integration tests
+ *
+ * Also includes the default version badge from `storybook-addon-tag-badges`.
+ */
 export declare const tagBadges: TagBadgeParameters;

package/esm/manager/tag_badges.js

@@ -1,5 +1,22 @@
 import { defaultConfig } from 'storybook-addon-tag-badges';
 const [, , , , , , versionBadge] = defaultConfig;
+/**
+ * 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.
+ *
+ * The badges help visually identify stories with certain characteristics:
+ * - 🆕 New - Recently added stories
+ * - 🅱️ Beta - Stories for features in beta
+ * - 🪦 Deprecated - Stories for deprecated features
+ * - ⚠️ Outdated - Stories that need updating
+ * - 🚨 Danger - Stories demonstrating dangerous patterns
+ * - 📋 Todo - Stories marked as todo/incomplete
+ * - 📝 Code Only - Stories without visual examples
+ * - 🧪 Unit - Stories with unit tests
+ * - 🔄 Integration - Stories with integration tests
+ *
+ * Also includes the default version badge from `storybook-addon-tag-badges`.
+ */
 export const tagBadges = [
     {
         tags: 'new',

package/esm/parameters/define_backgrounds_param.d.ts

@@ -36,4 +36,10 @@ export interface GlobalApiBackgroundsParam {
         [k: string]: unknown;
     };
 }
+/**
+ * Defines backgrounds parameters for Storybook stories.
+ *
+ * @param backgrounds - The backgrounds configuration
+ * @returns An object containing the backgrounds parameter configuration
+ */
 export declare const defineBackgroundsParam: (backgrounds: BackgroundsParam["backgrounds"] | GlobalApiBackgroundsParam["backgrounds"]) => BackgroundsParam;

package/esm/parameters/define_backgrounds_param.js

@@ -1,3 +1,9 @@
+/**
+ * Defines backgrounds parameters for Storybook stories.
+ *
+ * @param backgrounds - The backgrounds configuration
+ * @returns An object containing the backgrounds parameter configuration
+ */
 export const defineBackgroundsParam = (backgrounds) => ({
     backgrounds
 });

package/esm/parameters/define_docs_param.d.ts

@@ -178,4 +178,31 @@ export interface DocsParam {
         [k: string]: unknown;
     };
 }
+/**
+ * Defines docs parameters for Storybook stories.
+ *
+ * @param docs - Configuration for docs parameters including options for:
+ * - Controls display and sorting
+ * - Story rendering (autoplay, height, inline vs iframe)
+ * - And other docs-related settings
+ * @returns An object containing the docs parameter configuration
+ *
+ * @example
+ * ```ts
+ * import { defineDocsParam } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineDocsParam({
+ *     controls: {
+ *       sort: 'alpha',
+ *       exclude: ['internal*']
+ *     },
+ *     story: {
+ *       inline: true,
+ *       height: '400px'
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export declare function defineDocsParam(docs: DocsParam['docs']): DocsParam['docs'];

package/esm/parameters/define_docs_param.js

@@ -1,3 +1,30 @@
+/**
+ * Defines docs parameters for Storybook stories.
+ *
+ * @param docs - Configuration for docs parameters including options for:
+ * - Controls display and sorting
+ * - Story rendering (autoplay, height, inline vs iframe)
+ * - And other docs-related settings
+ * @returns An object containing the docs parameter configuration
+ *
+ * @example
+ * ```ts
+ * import { defineDocsParam } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineDocsParam({
+ *     controls: {
+ *       sort: 'alpha',
+ *       exclude: ['internal*']
+ *     },
+ *     story: {
+ *       inline: true,
+ *       height: '400px'
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export function defineDocsParam(docs) {
     return { docs };
 }

package/esm/parameters/define_layout_param.d.ts

@@ -11,9 +11,7 @@ export interface LayoutParam {
  * @example
  * ```ts
  * export const MyStory = {
- *   parameters: {
- *     ...defineLayoutParam('centered')
- *   }
+ *   parameters: defineLayoutParam('centered')
  * }
  * ```
  */

package/esm/parameters/define_layout_param.js

@@ -8,9 +8,7 @@
  * @example
  * ```ts
  * export const MyStory = {
- *   parameters: {
- *     ...defineLayoutParam('centered')
- *   }
+ *   parameters: defineLayoutParam('centered')
  * }
  * ```
  */

package/esm/parameters/define_parameters.d.ts

@@ -5,4 +5,33 @@ import type { StorySortParam } from './define_story_sort.ts';
 import type { TestParam } from './define_test_param.ts';
 import type { ViewportParam } from './define_viewport_param.ts';
 export type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsParam> & Partial<DocsParam> & Partial<LayoutParam> & Partial<StorySortParam> & Partial<TestParam> & Partial<ViewportParam>;
+/**
+ * Defines parameters for Storybook stories, combining built-in parameters with custom ones.
+ *
+ * @param parameters - Configuration object containing both built-in Storybook parameters and custom parameters
+ * @returns The combined parameters object
+ *
+ * @example
+ * ```ts
+ * import { defineParameters } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineParameters({
+ *     // Built-in parameters
+ *     layout: 'centered',
+ *     backgrounds: {
+ *       default: 'light',
+ *       values: [
+ *         { name: 'light', value: '#ffffff' },
+ *         { name: 'dark', value: '#333333' }
+ *       ]
+ *     },
+ *     // Custom parameters
+ *     myCustomParam: {
+ *       someValue: true
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export declare function defineParameters<P extends Record<string, any>>(parameters: P & StorybookBuiltInParams): P & StorybookBuiltInParams;

package/esm/parameters/define_parameters.js

@@ -1,3 +1,32 @@
+/**
+ * Defines parameters for Storybook stories, combining built-in parameters with custom ones.
+ *
+ * @param parameters - Configuration object containing both built-in Storybook parameters and custom parameters
+ * @returns The combined parameters object
+ *
+ * @example
+ * ```ts
+ * import { defineParameters } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineParameters({
+ *     // Built-in parameters
+ *     layout: 'centered',
+ *     backgrounds: {
+ *       default: 'light',
+ *       values: [
+ *         { name: 'light', value: '#ffffff' },
+ *         { name: 'dark', value: '#333333' }
+ *       ]
+ *     },
+ *     // Custom parameters
+ *     myCustomParam: {
+ *       someValue: true
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export function defineParameters(parameters) {
     return parameters;
 }

package/esm/parameters/define_viewport_param.d.ts

@@ -48,4 +48,31 @@ export interface GlobalApiViewportParam {
         disabled?: boolean | undefined;
     };
 }
+/**
+ * Defines viewport parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/docs/api/parameters#viewport
+ *
+ * @param viewport - Configuration for viewport parameters including:
+ * - viewports: Custom viewport definitions
+ * - defaultViewport: The default viewport to use
+ * - defaultOrientation: Default orientation (landscape/portrait)
+ * - disabled: Whether viewport controls are disabled
+ * @returns An object containing the viewport parameter configuration
+ *
+ * @example
+ * ```ts
+ * defineViewportParam({
+ *   viewports: {
+ *     mobile: {
+ *       name: 'Mobile',
+ *       styles: { width: '320px', height: '568px' },
+ *       type: 'mobile'
+ *     }
+ *   },
+ *   defaultViewport: 'mobile',
+ *   defaultOrientation: 'portrait'
+ * })
+ * ```
+ */
 export declare function defineViewportParam(viewport: ViewportParam['viewport'] | GlobalApiViewportParam['viewport']): ViewportParam;

package/esm/parameters/define_viewport_param.js

@@ -1,3 +1,30 @@
+/**
+ * Defines viewport parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/docs/api/parameters#viewport
+ *
+ * @param viewport - Configuration for viewport parameters including:
+ * - viewports: Custom viewport definitions
+ * - defaultViewport: The default viewport to use
+ * - defaultOrientation: Default orientation (landscape/portrait)
+ * - disabled: Whether viewport controls are disabled
+ * @returns An object containing the viewport parameter configuration
+ *
+ * @example
+ * ```ts
+ * defineViewportParam({
+ *   viewports: {
+ *     mobile: {
+ *       name: 'Mobile',
+ *       styles: { width: '320px', height: '568px' },
+ *       type: 'mobile'
+ *     }
+ *   },
+ *   defaultViewport: 'mobile',
+ *   defaultOrientation: 'portrait'
+ * })
+ * ```
+ */
 export function defineViewportParam(viewport) {
     return { viewport };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repobuddy/storybook",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Storybook repo buddy",
   "keywords": [
     "storybook",
@@ -22,6 +22,10 @@
     "./manager": {
       "types": "./esm/manager.d.ts",
       "default": "./esm/manager.js"
+    },
+    "./testing": {
+      "types": "./esm/testing.d.ts",
+      "default": "./esm/testing.js"
     }
   },
   "files": [
@@ -29,6 +33,9 @@
     "src",
     "!**/*.{spec,test,unit,accept,integrate,system,perf,stress,study,stories}.*"
   ],
+  "dependencies": {
+    "@repobuddy/vitest": "^1.2.0"
+  },
   "devDependencies": {
     "@storybook/addon-essentials": "^8.6.12",
     "@storybook/addon-storysource": "^8.6.12",

package/src/decorators/show_doc_source.tsx

@@ -1,5 +1,9 @@
 import type { Args, DecoratorFunction, Renderer } from 'storybook/internal/csf'
 
+/**
+ * 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

package/src/decorators/when_running_in_test.tsx

@@ -0,0 +1,16 @@
+import type { Decorator, StrictArgs } from '@storybook/react'
+import { ctx } from './when_running_in_text.ctx.ts'
+
+/**
+ * executes the specified decorator or handler if the code is running in test.
+ */
+export function whenRunningInTest<TArgs = StrictArgs>(
+	decoratorOrHandler: // biome-ignore lint/suspicious/noConfusingVoidType: on purpose
+		| ((...args: Parameters<Decorator<TArgs>>) => ReturnType<Decorator<TArgs>> | undefined | void)
+		// biome-ignore lint/suspicious/noConfusingVoidType: on purpose
+		| (() => ReturnType<Decorator<TArgs>> | undefined | void)
+): Decorator<TArgs> {
+	return function RunInTest(Story, context) {
+		return ctx.isRunningInTest() ? (decoratorOrHandler(Story, context) ?? <Story />) : <Story />
+	}
+}

package/src/decorators/when_running_in_text.ctx.ts

@@ -0,0 +1,5 @@
+import { isRunningInTest } from '@repobuddy/vitest'
+
+export const ctx = {
+	isRunningInTest
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './decorators/show_doc_source.tsx'
+export * from './decorators/when_running_in_test.tsx'
 export * from './parameters/define_actions_param.ts'
 export * from './parameters/define_backgrounds_param.ts'
 export * from './parameters/define_docs_param.ts'

package/src/manager/tag_badges.ts

@@ -2,6 +2,23 @@ import { type TagBadgeParameters, defaultConfig } from 'storybook-addon-tag-badg
 
 const [, , , , , , versionBadge] = defaultConfig
 
+/**
+ * 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.
+ *
+ * The badges help visually identify stories with certain characteristics:
+ * - 🆕 New - Recently added stories
+ * - 🅱️ Beta - Stories for features in beta
+ * - 🪦 Deprecated - Stories for deprecated features
+ * - ⚠️ Outdated - Stories that need updating
+ * - 🚨 Danger - Stories demonstrating dangerous patterns
+ * - 📋 Todo - Stories marked as todo/incomplete
+ * - 📝 Code Only - Stories without visual examples
+ * - 🧪 Unit - Stories with unit tests
+ * - 🔄 Integration - Stories with integration tests
+ *
+ * Also includes the default version badge from `storybook-addon-tag-badges`.
+ */
 export const tagBadges: TagBadgeParameters = [
 	{
 		tags: 'new',

package/src/parameters/define_backgrounds_param.ts

@@ -41,6 +41,12 @@ export interface GlobalApiBackgroundsParam {
 	}
 }
 
+/**
+ * Defines backgrounds parameters for Storybook stories.
+ *
+ * @param backgrounds - The backgrounds configuration
+ * @returns An object containing the backgrounds parameter configuration
+ */
 export const defineBackgroundsParam = (
 	backgrounds: BackgroundsParam['backgrounds'] | GlobalApiBackgroundsParam['backgrounds']
 ): BackgroundsParam => ({

package/src/parameters/define_docs_param.ts

@@ -201,6 +201,33 @@ export interface DocsParam {
 	}
 }
 
+/**
+ * Defines docs parameters for Storybook stories.
+ *
+ * @param docs - Configuration for docs parameters including options for:
+ * - Controls display and sorting
+ * - Story rendering (autoplay, height, inline vs iframe)
+ * - And other docs-related settings
+ * @returns An object containing the docs parameter configuration
+ *
+ * @example
+ * ```ts
+ * import { defineDocsParam } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineDocsParam({
+ *     controls: {
+ *       sort: 'alpha',
+ *       exclude: ['internal*']
+ *     },
+ *     story: {
+ *       inline: true,
+ *       height: '400px'
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export function defineDocsParam(docs: DocsParam['docs']): DocsParam['docs'] {
 	return { docs }
 }

package/src/parameters/define_layout_param.ts

@@ -12,9 +12,7 @@ export interface LayoutParam {
  * @example
  * ```ts
  * export const MyStory = {
- *   parameters: {
- *     ...defineLayoutParam('centered')
- *   }
+ *   parameters: defineLayoutParam('centered')
  * }
  * ```
  */

package/src/parameters/define_parameters.ts

@@ -12,6 +12,35 @@ export type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgro
 	Partial<TestParam> &
 	Partial<ViewportParam>
 
+/**
+ * Defines parameters for Storybook stories, combining built-in parameters with custom ones.
+ *
+ * @param parameters - Configuration object containing both built-in Storybook parameters and custom parameters
+ * @returns The combined parameters object
+ *
+ * @example
+ * ```ts
+ * import { defineParameters } from '@repobuddy/storybook'
+ *
+ * export default {
+ *   parameters: defineParameters({
+ *     // Built-in parameters
+ *     layout: 'centered',
+ *     backgrounds: {
+ *       default: 'light',
+ *       values: [
+ *         { name: 'light', value: '#ffffff' },
+ *         { name: 'dark', value: '#333333' }
+ *       ]
+ *     },
+ *     // Custom parameters
+ *     myCustomParam: {
+ *       someValue: true
+ *     }
+ *   })
+ * }
+ * ```
+ */
 export function defineParameters<P extends Record<string, any>>(parameters: P & StorybookBuiltInParams) {
 	return parameters
 }

package/src/parameters/define_viewport_param.ts

@@ -51,6 +51,33 @@ export interface GlobalApiViewportParam {
 	}
 }
 
+/**
+ * Defines viewport parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/docs/api/parameters#viewport
+ *
+ * @param viewport - Configuration for viewport parameters including:
+ * - viewports: Custom viewport definitions
+ * - defaultViewport: The default viewport to use
+ * - defaultOrientation: Default orientation (landscape/portrait)
+ * - disabled: Whether viewport controls are disabled
+ * @returns An object containing the viewport parameter configuration
+ *
+ * @example
+ * ```ts
+ * defineViewportParam({
+ *   viewports: {
+ *     mobile: {
+ *       name: 'Mobile',
+ *       styles: { width: '320px', height: '568px' },
+ *       type: 'mobile'
+ *     }
+ *   },
+ *   defaultViewport: 'mobile',
+ *   defaultOrientation: 'portrait'
+ * })
+ * ```
+ */
 export function defineViewportParam(
 	viewport: ViewportParam['viewport'] | GlobalApiViewportParam['viewport']
 ): ViewportParam {

package/esm/testing/index.d.ts

@@ -1 +0,0 @@
-export * from './it.ts';

package/esm/testing/index.js

@@ -1 +0,0 @@
-export * from "./it.js";

package/esm/testing/it.d.ts

@@ -1,6 +0,0 @@
-import type { Args, Renderer, StoryAnnotations } from 'storybook/internal/csf';
-export type ItObj<TRenderer extends Renderer, TArgs extends Args> = StoryAnnotations<TRenderer, TArgs>;
-export declare function it<TRenderer extends Renderer, TArgs extends Args>(description: string, story: StoryAnnotations<TRenderer, TArgs>): StoryAnnotations<TRenderer, TArgs>;
-export declare namespace it {
-    var skip: <TRenderer extends Renderer, TArgs extends Args>(description: string, story: StoryAnnotations<TRenderer, TArgs>) => StoryAnnotations<TRenderer, TArgs>;
-}

package/esm/testing/it.js

@@ -1,19 +0,0 @@
-export function it(description, story) {
-    const { play, ...rest } = story;
-    return {
-        ...rest,
-        async play(context) {
-            await context.step(description, async () => {
-                await play?.(context);
-            });
-        }
-    };
-}
-// does not work
-it.skip = (description, story) => {
-    const { tags = [], ...rest } = story;
-    return it(description, {
-        tags: [...tags, '!test'],
-        ...rest
-    });
-};

package/src/testing/index.ts

@@ -1 +0,0 @@
-export * from './it.ts'

package/src/testing/it.ts

@@ -1,30 +0,0 @@
-import type { Args, Renderer, StoryAnnotations } from 'storybook/internal/csf'
-
-export type ItObj<TRenderer extends Renderer, TArgs extends Args> = StoryAnnotations<TRenderer, TArgs>
-
-export function it<TRenderer extends Renderer, TArgs extends Args>(
-	description: string,
-	story: StoryAnnotations<TRenderer, TArgs>
-): StoryAnnotations<TRenderer, TArgs> {
-	const { play, ...rest } = story
-	return {
-		...rest,
-		async play(context) {
-			await context.step(description, async () => {
-				await play?.(context)
-			})
-		}
-	}
-}
-
-// does not work
-it.skip = <TRenderer extends Renderer, TArgs extends Args>(
-	description: string,
-	story: StoryAnnotations<TRenderer, TArgs>
-) => {
-	const { tags = [], ...rest } = story
-	return it(description, {
-		tags: [...tags, '!test'],
-		...rest
-	})
-}