@repobuddy/storybook 2.0.1 → 2.1.1

package/esm/index.d.ts

@@ -1,13 +1,574 @@
-export * from '@repobuddy/test';
-export * from './components/show_html.tsx';
-export * from './decorators/show_doc_source.tsx';
-export * from './parameters/define_actions_param.ts';
-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_test_param.ts';
-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';
+import { UserConfig } from "htmlfy";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { ClassNameProps, StyleProps } from "@just-web/css";
+import { Args, DecoratorFunction, Renderer } from "storybook/internal/csf";
+import { Decorator, Meta, StoryContext, StoryObj, StrictArgs } from "@storybook/react-vite";
+export * from "@repobuddy/test";
+
+//#region src/components/show_html.d.ts
+type ShowHtmlProps = ClassNameProps & StyleProps & {
+  selector?: string | undefined;
+  config?: UserConfig | undefined;
+};
+/**
+ * A component that displays the HTML of a subject element.
+ * Uses `htmlfy` internally to format and prettify the HTML output.
+ *
+ * @param selector - CSS selector to find the subject element. Defaults to '[data-testid="subject"]'
+ * @param config - Configuration options passed to htmlfy's prettify function
+ * @param props - Additional props (className, style) passed to the pre element
+ * @returns A pre element containing the formatted HTML
+ */
+declare function ShowHtml({
+  selector,
+  config,
+  ...props
+}: ShowHtmlProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/decorators/show_doc_source.d.ts
+/**
+ * A decorator that shows the source code of a story above the rendered story.
+ * The source code is taken from the story's `parameters.docs.source.code`.
+ */
+declare function showDocSource<TRenderer extends Renderer = Renderer, TArgs = Args>(): DecoratorFunction<TRenderer, TArgs>;
+//#endregion
+//#region src/parameters/define_actions_param.d.ts
+interface ActionsParam {
+  actions: {
+    argTypesRegex?: string | undefined;
+    disable?: boolean | undefined;
+    handles?: string[] | undefined;
+    [k: string]: unknown;
+  };
+}
+/**
+ * Defines actions parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/docs/essentials/actions#parameters
+ *
+ * @param actions - Configuration for actions parameters
+ * @returns An object containing the actions parameter configuration
+ */
+declare function defineActionsParam(actions: ActionsParam['actions']): {
+  actions: {
+    [k: string]: unknown;
+    argTypesRegex?: string | undefined;
+    disable?: boolean | undefined;
+    handles?: string[] | undefined;
+  };
+};
+//#endregion
+//#region src/parameters/define_backgrounds_param.d.ts
+interface BackgroundsParam {
+  backgrounds: {
+    default?: string | undefined;
+    values?: Array<{
+      name: string;
+      value: string;
+    }>;
+    disable?: boolean | undefined;
+    grid?: {
+      cellAmount?: number | undefined;
+      cellSize?: number | undefined;
+      disable?: boolean | undefined;
+      offsetX?: number | undefined;
+      offsetY?: number | undefined;
+      opacity?: number | undefined;
+    } | undefined;
+    [k: string]: unknown;
+  };
+}
+interface GlobalApiBackgroundsParam {
+  backgrounds: {
+    default?: string | undefined;
+    options?: Array<{
+      name: string;
+      value: string;
+    }>;
+    disabled?: boolean | undefined;
+    grid?: {
+      cellAmount?: number | undefined;
+      cellSize?: number | undefined;
+      disable?: boolean | undefined;
+      offsetX?: number | undefined;
+      offsetY?: number | undefined;
+      opacity?: number | undefined;
+    } | undefined;
+    [k: string]: unknown;
+  };
+}
+/**
+ * Defines backgrounds parameters for Storybook stories.
+ *
+ * @param backgrounds - The backgrounds configuration
+ * @returns An object containing the backgrounds parameter configuration
+ */
+declare const defineBackgroundsParam: (backgrounds: BackgroundsParam["backgrounds"] | GlobalApiBackgroundsParam["backgrounds"]) => BackgroundsParam;
+//#endregion
+//#region src/parameters/define_docs_param.d.ts
+declare global {
+  namespace JSX {
+    interface Element {}
+  }
+}
+interface SourceProps {
+  /**
+   * Provides the source code to be rendered.
+   *
+   * This is useful when the story contains extra code that would be confusing in the docs.
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#code
+   */
+  code?: string | undefined;
+  /**
+   * Specifies whether the source code should be rendered in dark mode.
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#dark
+   */
+  dark?: boolean | undefined;
+  /**
+   * Specifies whether decorators should be excluded from the source code.
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#excludedecorators
+   *
+   * Note: Has no effect in React.
+   * @see https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#parameter-docssourceexcludedecorators-has-no-effect-in-react
+   */
+  excludeDecorators?: boolean | undefined;
+  /**
+   * Specifies the language of the source code.
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#language
+   */
+  language?: string | undefined;
+  /**
+   * A function to dynamically transform the source before being rendered,
+   * based on the original source and any story context necessary.
+   * The returned string is displayed as-is.
+   *
+   * If both code and transform are specified, transform will be ignored.
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#transform
+   */
+  transform?: ((code: string, storyContext: StoryContext) => string) | undefined;
+  /**
+   * Specifies how the source code is rendered.
+   *
+   * - auto: Same as dynamic, if the story's render function accepts args inputs and dynamic is supported by the framework in use; otherwise same as code
+   * - code: Renders the value of code prop, otherwise renders static story source
+   * - dynamic: Renders the story source with dynamically updated arg values
+   *
+   * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source#type
+   */
+  type?: 'auto' | 'code' | 'dynamic' | undefined;
+}
+interface DocsParam {
+  docs: {
+    argTypes?: {
+      /**
+       * Specifies which controls to exclude from the args table.
+       * Any controls whose names match the regex or are part of the array will be left out.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#exclude
+       */
+      exclude?: string[] | RegExp | undefined;
+      /**
+       * Specifies which controls to include in the args table.
+       * Any controls whose names don't match the regex or are not part of the array will be left out.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#include
+       */
+      include?: string[] | RegExp | undefined;
+      /**
+       * Specifies how the arg types are sorted.
+       *
+       * - none: Unsorted, displayed in the same order the arg types are processed in
+       * - alpha: Sorted alphabetically, by the arg type's name
+       * - requiredFirst: Same as alpha, with any required arg types displayed first
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#sort
+       */
+      sort?: 'alpha' | 'requiredFirst' | 'none' | undefined;
+    } | undefined;
+    description?: {
+      /**
+       * `docs.description.story` can be used to describe the story in doc.
+       */
+      story?: string | undefined;
+      /**
+       * `docs.description.component` can be used to describe the component in meta.
+       * It has no effect on the stories.
+       */
+      component?: string | undefined;
+    } | undefined;
+    /**
+     * Determines whether to show the code panel.
+     *
+     * @see https://storybook.js.org/docs/writing-docs/code-panel
+     */
+    codePanel?: boolean | undefined;
+    source?: SourceProps | undefined;
+    canvas?: {
+      /**
+       * Provides any additional custom actions to show in the bottom right corner.
+       * These are simple buttons that do anything you specify in the onClick function.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#additionalactions
+       */
+      additionalActions?: Array<{
+        title: string | JSX.Element;
+        className?: string;
+        onClick: () => void;
+        disabled?: boolean;
+      }> | undefined;
+      /**
+       * Provides HTML class(es) to the preview element, for custom styling.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#classname
+       */
+      className?: string | undefined;
+      /**
+       * Specifies how the canvas should layout the story.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#layout
+       */
+      layout?: 'centered' | 'padded' | 'fullscreen' | undefined;
+      /**
+       * Specifies the initial state of the source panel.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#sourcestate
+       */
+      sourceState?: 'hidden' | 'shown' | 'none' | undefined;
+      /**
+       * Determines whether to render a toolbar containing tools to interact with the story.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas#withtoolbar
+       */
+      withToolbar?: boolean | undefined;
+    } | undefined;
+    controls?: {
+      /**
+       * Specifies which controls to exclude from the args table.
+       * Any controls whose names match the regex or are part of the array will be left out.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-controls#exclude
+       */
+      exclude?: string[] | RegExp | undefined;
+      /**
+       * Specifies which controls to include in the args table.
+       * Any controls whose names don't match the regex or are not part of the array will be left out.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-controls#include
+       */
+      include?: string[] | RegExp | undefined;
+      /**
+       *
+       * Specifies how the controls are sorted.
+       *
+       * - none: Unsorted, displayed in the same order the controls are processed in
+       * - alpha: Sorted alphabetically, by the arg type's name
+       * - requiredFirst: Same as alpha, with any required controls displayed first
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-controls#sort
+       */
+      sort?: 'alpha' | 'requiredFirst' | 'none' | undefined;
+    } | undefined;
+    story?: {
+      /**
+       * Specifies whether the story should be autoplayed.
+       *
+       * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-story#autoplay
+       */
+      autoplay?: boolean | undefined;
+      /**
+       * Set a minimum height (note for an iframe this is the actual height) when rendering a story in an iframe or inline.
+       * This overrides parameters.docs.story.iframeHeight for iframes.
+       */
+      height?: string | undefined;
+      /**
+       * Determines whether the story is rendered inline (in the same browser frame as the other docs content) or in an iframe.
+       */
+      inline?: boolean | undefined;
+    } | undefined;
+    [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'
+ *     }
+ *   })
+ * }
+ * ```
+ */
+declare function defineDocsParam(docs: DocsParam['docs']): DocsParam['docs'];
+//#endregion
+//#region src/parameters/define_layout_param.d.ts
+interface LayoutParam {
+  layout: 'padded' | 'fullscreen' | 'centered';
+}
+/**
+ * Helper function to define the layout parameter for a story
+ *
+ * @see https://storybook.js.org/docs/api/parameters#layout
+ *
+ * @param layout - The layout type to use ('padded', 'fullscreen', or 'centered')
+ * @returns An object containing the layout parameter
+ * @example
+ * ```ts
+ * export const MyStory = {
+ *   parameters: defineLayoutParam('centered')
+ * }
+ * ```
+ */
+declare const defineLayoutParam: (layout: LayoutParam["layout"]) => {
+  layout: "padded" | "fullscreen" | "centered";
+};
+//#endregion
+//#region src/parameters/define_test_param.d.ts
+interface TestParam {
+  test: {
+    clearMocks?: boolean | undefined;
+    mockReset?: boolean | undefined;
+    restoreMocks?: boolean | undefined;
+    dangerouslyIgnoreUnhandledErrors?: boolean | undefined;
+    [k: string]: unknown;
+  };
+}
+/**
+ * Defines test parameters for Storybook stories.
+ *
+ * @see https://storybook.js.org/docs/api/parameters#test
+ *
+ * @param test - Configuration for test parameters
+ * @returns An object containing the test parameter configuration
+ *
+ * @example
+ * defineTestParam({
+ *   clearMocks: true,
+ *   mockReset: true,
+ *   restoreMocks: true,
+ *   dangerouslyIgnoreUnhandledErrors: true
+ * })
+ */
+declare function defineTestParam(test: TestParam['test']): {
+  test: {
+    [k: string]: unknown;
+    clearMocks?: boolean | undefined;
+    mockReset?: boolean | undefined;
+    restoreMocks?: boolean | undefined;
+    dangerouslyIgnoreUnhandledErrors?: boolean | undefined;
+  };
+};
+//#endregion
+//#region src/parameters/define_viewport_param.d.ts
+interface ViewportParam {
+  viewport: {
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#viewports
+     */
+    viewports?: Record<string, Viewport> | undefined;
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#defaultorientation
+     */
+    defaultOrientation?: 'landscape' | 'portrait' | undefined;
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#defaultviewport
+     */
+    defaultViewport?: string | undefined;
+    /**
+     * Disables the viewport parameter.
+     * @deprecated Use `disabled` instead.
+     */
+    disable?: boolean | undefined;
+    [k: string]: unknown;
+  };
+}
+interface Viewport {
+  name: string;
+  styles: {
+    width: string;
+    height: string;
+  };
+  type: 'mobile' | 'tablet' | 'desktop';
+}
+interface GlobalApiViewportParam {
+  viewport: {
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#viewports
+     */
+    options?: Record<string, Viewport> | undefined;
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#defaultviewport
+     */
+    defaultViewport?: string | undefined;
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#defaultorientation
+     */
+    defaultOrientation?: 'landscape' | 'portrait' | undefined;
+    /**
+     * @see https://storybook.js.org/docs/essentials/viewport#disable
+     */
+    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'
+ * })
+ * ```
+ */
+declare function defineViewportParam(viewport: ViewportParam['viewport'] | GlobalApiViewportParam['viewport']): ViewportParam;
+//#endregion
+//#region src/parameters/story_sort.d.ts
+type StorySortConfig = {
+  includeNames?: boolean;
+  locales?: string;
+  method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
+  order?: string[];
+  [k: string]: unknown;
+};
+type Story = {
+  id: string;
+  importPath: string;
+  name: string;
+  title: string;
+};
+type StorySortFn = (a: Story, b: Story) => number;
+/**
+ * Interface for story sorting parameters in Storybook.
+ * Used to define how stories should be sorted in the navigation sidebar.
+ */
+interface StorySortParam {
+  /**
+   * Configuration for story sorting. Can be either:
+   * - A StorySortConfig object specifying sort method and options
+   * - A custom sorting function that takes two stories and returns their sort order
+   */
+  storySort: StorySortConfig | StorySortFn;
+}
+//#endregion
+//#region src/parameters/define_parameters.d.ts
+type StorybookBuiltInParams = Partial<BackgroundsParam | GlobalApiBackgroundsParam> & Partial<DocsParam> & Partial<LayoutParam> & Partial<TestParam> & Partial<ViewportParam> & {
+  options?: StorySortParam & Record<string, any>;
+} & Record<string, any>;
+/**
+ * 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
+ *     }
+ *   })
+ * }
+ * ```
+ */
+declare function defineParameters<P extends Record<string, any>>(param: P & StorybookBuiltInParams, ...rest: Array<StorybookBuiltInParams>): StorybookBuiltInParams;
+//#endregion
+//#region src/testing/decorators/when_running_in_test.d.ts
+/**
+ * executes the specified decorator or handler if the code is running in test.
+ */
+declare function whenRunningInTest<TArgs = StrictArgs>(decoratorOrHandler: ((...args: Parameters<Decorator<TArgs>>) => ReturnType<Decorator<TArgs>> | undefined | void) | (() => ReturnType<Decorator<TArgs>> | undefined | void)): Decorator<TArgs>;
+//#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<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
+ *
+ * @example
+ * ```ts
+ * // Create a generic StoryObj type for a project
+ * type StoryObj<TMetaOrCmpOrArgs = Args> = ExtendStoryObj<TMetaOrCmpOrArgs, StoryObj<TMetaOrCmpOrArgs>, { tagType: 'tag1' | 'tag2' }>
+ *
+ * // Create a specific StoryObj type for a component
+ * type StoryObj = ExtendStoryObj<typeof Component, StoryObj<typeof Component>, { tagType: 'tag1' | 'tag2' }>
+ * ```
+ */
+type ExtendStoryObj<TMetaOrCmpOrArgs, S extends StoryObj<TMetaOrCmpOrArgs>, E extends {
+  tag: string;
+}> = Omit<S, 'tags'> & {
+  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 };