Logo for jsDocs.io

@storybook/web-components

  • Version 10.2.13
  • Published
  • 61.4 kB
  • 3 dependencies
  • MIT license

Install

npm i @storybook/web-components
yarn add @storybook/web-components
pnpm add @storybook/web-components

Overview

Storybook Web Components renderer: Develop, document, and test UI components in isolation

Index

Functions

Interfaces

Type Aliases

Namespaces

Functions

function getCustomElements

getCustomElements: () => any;

    function isValidComponent

    isValidComponent: (tagName: string) => boolean;

      function isValidMetaData

      isValidMetaData: (customElements: any) => boolean;

        function setCustomElements

        setCustomElements: (customElements: any) => void;

        • Parameter customElements

          any for now as spec is not super stable yet

        function setCustomElementsManifest

        setCustomElementsManifest: (customElements: any) => void;

          function setProjectAnnotations

          setProjectAnnotations: (
              projectAnnotations:
                  | NamedOrDefaultProjectAnnotations<any>
                  | NamedOrDefaultProjectAnnotations<any>[]
          ) => NormalizedProjectAnnotations<WebComponentsRenderer>;

          • Function that sets the globalConfig of your storybook. The global config is the preview module of your .storybook folder.

            It should be run a single time, so that your global config (e.g. decorators) is applied to your stories when using composeStories or composeStory.

            Example:

            // setup-file.js
            import { setProjectAnnotations } from '@storybook/web-components';
            import projectAnnotations from './.storybook/preview';
            

            setProjectAnnotations(projectAnnotations);

            Parameter projectAnnotations

            E.g. (import projectAnnotations from '../.storybook/preview')

          Interfaces

          interface WebComponentsMeta

          interface WebComponentsMeta<
              T extends WebComponentsTypes,
              MetaInput extends ComponentAnnotations<T>
          > extends Meta$1<T, MetaInput> {}

          • Web Components-specific Meta interface returned by preview.meta().

            Provides the story() method to create individual stories with proper type inference. Args provided in meta become optional in stories, while missing required args must be provided at the story level.

          method story

          story: {
              <TInput extends unknown>(story: TInput): WebComponentsStory<
                  T,
                  TInput extends () => WebComponentsTypes['storyResult']
                      ? { render: TInput }
                      : TInput
              >;
              <
                  TInput extends StoryAnnotations<
                      T,
                      T['args'],
                      Simplify<
                          Except<T['args'], keyof T['args'] & keyof MetaInput['args']> &
                              Partial<
                                  Pick<
                                      T['args'],
                                      keyof T['args'] & keyof MetaInput['args']
                                  >
                              >,
                          {}
                      >
                  >
              >(
                  story: TInput
              ): WebComponentsStory<T, TInput>;
              (
                  ..._args: Partial<T['args']> extends Simplify<
                      Except<T['args'], keyof T['args'] & keyof MetaInput['args']> &
                          Partial<
                              Pick<T['args'], keyof T['args'] & keyof MetaInput['args']>
                          >,
                      {}
                  >
                      ? []
                      : [never]
              ): WebComponentsStory<T, {}>;
          };

          • Creates a story with a custom render function that takes no args.

            This overload allows you to define a story using just a render function or an object with a render function that doesn't depend on args. Since the render function doesn't use args, no args need to be provided regardless of what's required by the component.

            Example 1

            // Using just a render function with lit-html
            export const CustomTemplate = meta.story(() => html`<div>Custom content</div>`);
            

            // Using an object with render
            export const WithRender = meta.story({
              render: () => html`<my-element></my-element>`,
            });

          • Creates a story with custom configuration including args, decorators, or other annotations.

            This is the primary overload for defining stories. Args that were already provided in meta become optional, while any remaining required args must be specified here.

            Example 1

            // Provide required args not in meta
            export const Primary = meta.story({
              args: { label: 'Click me', disabled: false },
            });
            

            // Override meta args and add story-specific configuration
            export const Disabled = meta.story({
              args: { disabled: true },
              decorators: [withCustomWrapper],
            });

          • Creates a story with no additional configuration.

            This overload is only available when all required args have been provided in meta. The conditional type Partial<T['args']> extends SetOptional<...> checks if the remaining required args (after accounting for args provided in meta) are all optional. If so, the function accepts zero arguments []. Otherwise, it requires [never] which makes this overload unmatchable, forcing the user to provide args.

            Example 1

            // When meta provides all required args, story() can be called with no arguments
            const meta = preview.meta({ component: 'my-button', args: { label: 'Hi' } });
            export const Default = meta.story(); // Valid - all args provided in meta

          interface WebComponentsPreview

          interface WebComponentsPreview<T extends AddonTypes>
              extends Preview$1<WebComponentsTypes & T> {}

          • Web Components-specific Preview interface that provides type-safe CSF factory methods.

            Use preview.meta() to create a meta configuration for a component, and then meta.story() to create individual stories. The type system will infer args from the HTMLElement type when using a tag name as the component.

            Example 1

            const meta = preview.meta({ component: 'my-button' });
            export const Primary = meta.story({ args: { label: 'Click me' } });

          method meta

          meta: {
              <
                  C extends keyof HTMLElementTagNameMap,
                  Decorators extends DecoratorFunction<WebComponentsTypes & T, any>,
                  TMetaArgs extends Partial<HTMLElementTagNameMap[C]> &
                      Record<`${string}-${string}`, unknown> &
                      Partial<T['args']>
              >(
                  meta: {
                      component?: C;
                      args?: TMetaArgs;
                      decorators?: Decorators | Decorators[];
                  } & Omit<
                      ComponentAnnotations<
                          WebComponentsTypes & T,
                          InferArgsFromComponent<C> & T['args']
                      >,
                      'decorators' | 'component' | 'args'
                  >
              ): WebComponentsMeta<
                  InferWebComponentsTypes<T, InferArgsFromComponent<C>, Decorators>,
                  Omit<
                      ComponentAnnotations<
                          InferWebComponentsTypes<T, InferArgsFromComponent<C>, Decorators>
                      >,
                      'args'
                  > & { args: {} extends TMetaArgs ? {} : TMetaArgs }
              >;
              <
                  TArgs,
                  Decorators extends DecoratorFunction<WebComponentsTypes & T, any>,
                  TMetaArgs extends Partial<TArgs>
              >(
                  meta: {
                      render?: ArgsStoryFn<WebComponentsTypes & T, TArgs>;
                      args?: TMetaArgs;
                      decorators?: Decorators | Decorators[];
                  } & Omit<
                      ComponentAnnotations<WebComponentsTypes & T, TArgs & T['args']>,
                      'args' | 'decorators' | 'component' | 'render'
                  >
              ): WebComponentsMeta<
                  InferWebComponentsTypes<T, TArgs, Decorators>,
                  Omit<
                      ComponentAnnotations<InferWebComponentsTypes<T, TArgs, Decorators>>,
                      'args'
                  > & { args: {} extends TMetaArgs ? {} : TMetaArgs }
              >;
          };

            method type

            type: <S>() => WebComponentsPreview<T & S>;

            • Narrows the type of the preview to include additional type information. This is useful when you need to add args that aren't inferred from the component.

              Example 1

              const meta = preview.type<{ args: { theme: 'light' | 'dark' } }>().meta({
                component: 'my-button',
              });

            interface WebComponentsRenderer

            interface WebComponentsRenderer extends WebRenderer {}

              property component

              component: string;

                property storyResult

                storyResult: StoryFnHtmlReturnType;

                  interface WebComponentsStory

                  interface WebComponentsStory<
                      T extends WebComponentsTypes,
                      TInput extends StoryAnnotations<T, T['args']>
                  > extends Story<T, TInput> {}

                  • Web Components-specific Story interface returned by meta.story().

                    Represents a single story with its configuration and provides access to the composed story for testing via story.run().

                  interface WebComponentsTypes

                  interface WebComponentsTypes extends WebComponentsRenderer {}

                    Type Aliases

                    type Decorator

                    type Decorator<TArgs = StrictArgs> = DecoratorFunction<WebComponentsRenderer, TArgs>;

                      type Loader

                      type Loader<TArgs = StrictArgs> = LoaderFunction<WebComponentsRenderer, TArgs>;

                        type Meta

                        type Meta<TArgs = Args> = ComponentAnnotations<WebComponentsRenderer, TArgs>;

                        • Metadata to configure the stories for a component.

                          See Also

                          • [Default export](https://storybook.js.org/docs/api/csf#default-export)

                        type Preview

                        type Preview = ProjectAnnotations<WebComponentsRenderer>;

                          type StoryContext

                          type StoryContext<TArgs = StrictArgs> = StoryContext$1<WebComponentsRenderer, TArgs>;

                            type StoryFn

                            type StoryFn<TArgs = Args> = AnnotatedStoryFn<WebComponentsRenderer, TArgs>;

                            • Story function that represents a CSFv2 component example.

                              See Also

                              • [Named Story exports](https://storybook.js.org/docs/api/csf#named-story-exports)

                            type StoryObj

                            type StoryObj<TArgs = Args> = StoryAnnotations<WebComponentsRenderer, TArgs>;

                            • Story object that represents a CSFv3 component example.

                              See Also

                              • [Named Story exports](https://storybook.js.org/docs/api/csf#named-story-exports)

                            Namespaces

                            namespace global

                            namespace global {}

                              interface SymbolConstructor

                              interface SymbolConstructor {}

                                property observable

                                readonly observable: symbol;

                                  Package Files (1)

                                  Dependencies (3)

                                  Dev Dependencies (8)

                                  Peer Dependencies (2)

                                  Badge

                                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@storybook/web-components.

                                  • Markdown
                                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@storybook/web-components)
                                  • HTML
                                    <a href="https://www.jsdocs.io/package/@storybook/web-components"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>