@storybook/angular

@storybook/angular

Version 10.2.12
Published 7 hours ago
139 kB
6 dependencies
MIT license

Install

npm i @storybook/angular

yarn add @storybook/angular

pnpm add @storybook/angular

Overview

Storybook for Angular: Develop, document, and test UI components in isolation

Functions

function applicationConfig

applicationConfig: <TArgs = any>(
    config: ApplicationConfig
) => DecoratorFunction<AngularRenderer, TArgs>;

Decorator to set the config options which are available during the application bootstrap operation

function argsToTemplate

argsToTemplate: <A extends Record<string, any>>(
    args: A,
    options?: ArgsToTemplateOptions<keyof A>
) => string;

Converts an object of arguments to a string of property and event bindings and excludes undefined values. Why? Because Angular treats undefined values in property bindings as an actual value and does not apply the default value of the property as soon as the binding is set. This feels counter-intuitive and is a common source of bugs in stories.

Example 1

// component.ts
ㅤ@Component({ selector: 'example' })
 export class ExampleComponent {
  ㅤ@Input() input1: string = 'Default Input1';
  ㅤ@Input() input2: string = 'Default Input2';
  ㅤ@Output() click = new EventEmitter();
 }

// component.stories.ts
import { argsToTemplate } from '@storybook/angular';
export const Input1: Story = {
 render: (args) => ({
   props: args,
   // Problem1: <example [input1]="input1" [input2]="input2" (click)="click($event)"></example>
   // This will set input2 to undefined and the internal default value will not be used.
   // Problem2: <example [input1]="input1" (click)="click($event)"></example>
   // The default value of input2 will be used, but it is not overridable by the user via controls.
   // Solution: Now the controls will be applicable to both input1 and input2, and the default values will be used if the user does not override them.
   template: `<example ${argsToTemplate(args)}"></example>`,
 }),
 args: {
   // In this Story, we want to set the input1 property, and the internal default property of input2 should be used.
   input1: 'Input 1',
   click: { action: 'clicked' },
 },
};

function componentWrapperDecorator

componentWrapperDecorator: <TArgs = any>(
    element: any,
    props?:
        | ICollection
        | ((storyContext: StoryContext$1<AngularRenderer, TArgs>) => ICollection)
) => DecoratorFunction<AngularRenderer, TArgs>;

function definePreview

definePreview: <Addons extends PreviewAddon<never>[]>(
    input: { addons: Addons } & ProjectAnnotations<
        AngularRenderer & InferTypes<Addons>
    >
) => AngularPreview<AngularRenderer & InferTypes<Addons>>;

Creates an Angular-specific preview configuration with CSF factories support.
This function wraps the base definePreview and adds Angular-specific annotations for rendering and documentation. It returns an AngularPreview that provides type-safe meta() and story() factory methods.
Example 1
// .storybook/preview.ts import { definePreview } from '@storybook/angular'; export const preview = definePreview({ addons: [], parameters: { layout: 'centered' }, });

function moduleMetadata

moduleMetadata: <TArgs = any>(
    metadata: Partial<NgModuleMetadata>
) => DecoratorFunction<AngularRenderer, TArgs>;

function setProjectAnnotations

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

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/angular'; import projectAnnotations from './.storybook/preview'; setProjectAnnotations(projectAnnotations);
Parameter projectAnnotations
E.g. (import projectAnnotations from '../.storybook/preview')

Interfaces

interface AngularMeta

interface AngularMeta<
    T extends AngularRenderer,
    MetaInput extends ComponentAnnotations<T>
> extends Meta$1<T, MetaInput> {}

Angular-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): AngularStory<
        T,
        TInput extends () => AngularRenderer['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
    ): AngularStory<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]
    ): AngularStory<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 export const CustomTemplate = meta.story(() => ({ template: '<div>Custom static content</div>', })); // Using an object with render export const WithRender = meta.story({ render: () => ({ template: '<my-component></my-component>' }), });

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: Button, args: { label: 'Hi', disabled: false } }); export const Default = meta.story(); // Valid - all args provided in meta

interface AngularOptions

interface AngularOptions {}

property enableIvy

enableIvy?: boolean;

interface AngularPreview

interface AngularPreview<T extends AddonTypes>
    extends Preview$1<AngularRenderer & T> {}

Angular-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 component, decorators, and any addon types.
Example 1
const meta = preview.meta({ component: ButtonComponent }); export const Primary = meta.story({ args: { label: 'Click me' } });

method meta

meta: {
    <
        C extends abstract new (...args: any) => any,
        Decorators extends DecoratorFunction<AngularRenderer & T, any>,
        TMetaArgs extends Partial<
            Partial<
                TransformInputSignalType<
                    TransformOutputSignalType<
                        TransformEventType<InstanceType<C>>
                    >
                >
            > &
                T['args']
        >
    >(
        meta: {
            component?: C;
            args?: TMetaArgs;
            decorators?: Decorators | Decorators[];
        } & Omit<
            ComponentAnnotations<
                AngularRenderer & T,
                InferComponentArgs<C> & T['args']
            >,
            'decorators' | 'component' | 'args'
        >
    ): AngularMeta<
        InferAngularTypes<T, InferComponentArgs<C>, Decorators>,
        Omit<
            ComponentAnnotations<
                InferAngularTypes<T, InferComponentArgs<C>, Decorators>
            >,
            'args'
        > & { args: {} extends TMetaArgs ? {} : TMetaArgs }
    >;
    <
        TArgs,
        Decorators extends DecoratorFunction<AngularRenderer & T, any>,
        TMetaArgs extends Partial<TArgs & T['args']>
    >(
        meta: {
            render?: ArgsStoryFn<AngularRenderer & T, TArgs & T['args']>;
            args?: TMetaArgs;
            decorators?: Decorators | Decorators[];
        } & Omit<
            ComponentAnnotations<AngularRenderer & T, TArgs & T['args']>,
            'args' | 'decorators' | 'component' | 'render'
        >
    ): AngularMeta<
        InferAngularTypes<T, TArgs, Decorators>,
        Omit<
            ComponentAnnotations<InferAngularTypes<T, TArgs, Decorators>>,
            'args'
        > & { args: {} extends TMetaArgs ? {} : TMetaArgs }
    >;
};

method type

type: <S>() => AngularPreview<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: ButtonComponent, });

interface AngularRenderer

interface AngularRenderer extends WebRenderer {}

property component

component: any;

property storyResult

storyResult: StoryFnAngularReturnType;

interface AngularStory

interface AngularStory<
    T extends AngularRenderer,
    TInput extends StoryAnnotations<T, T['args']>
> extends Story<T, TInput> {}

Angular-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 IStory

interface StoryFnAngularReturnType {}

property applicationConfig

applicationConfig?: ApplicationConfig;

property moduleMetadata

moduleMetadata?: NgModuleMetadata;

property props

props?: ICollection;

property styles

styles?: string[];

property template

template?: string;

property userDefinedTemplate

userDefinedTemplate?: boolean;

Type Aliases

type AngularParameters

type Parameters = Parameters$1 & {
    bootstrapModuleOptions?: unknown;
};

type Decorator

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

type FrameworkOptions

type FrameworkOptions = AngularOptions & {
    builder?: BuilderOptions;
};

type Loader

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

type Meta

type Meta<TArgs = Args> = ComponentAnnotations<
    AngularRenderer,
    TransformComponentType<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<AngularRenderer>;

type StorybookConfig

type StorybookConfig = Omit<
    StorybookConfig$1,
    keyof StorybookConfigWebpack | keyof StorybookConfigFramework
> &
    StorybookConfigWebpack &
    StorybookConfigFramework;

The interface for Storybook configuration in main.ts files.

type StoryContext

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

type StoryFn

type StoryFn<TArgs = Args> = AnnotatedStoryFn<
    AngularRenderer,
    TransformComponentType<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<
    AngularRenderer,
    TransformComponentType<TArgs>
>;

Story object that represents a CSFv3 component example.
See Also
- [Named Story exports](https://storybook.js.org/docs/api/csf#named-story-exports)

type TransformComponentType

type TransformComponentType<T> = TransformInputSignalType<
    TransformOutputSignalType<TransformEventType<T>>
>;

Utility type that transforms InputSignal and EventEmitter types

Namespaces

namespace global

namespace global {}

interface SymbolConstructor

interface SymbolConstructor {}

property observable

readonly observable: symbol;

Package Files (1)

dist/index.d.ts

Dependencies (6)

Dev Dependencies (19)

Peer Dependencies (15)

Badge

To add a badge like this oneto 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/angular.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@storybook/angular)

HTML

<a href="https://www.jsdocs.io/package/@storybook/angular"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 3928 ms.
Missing or incorrect documentation? Open an issue for this package.

@storybook/angular

Install

Overview

Index

Functions

Interfaces

Type Aliases

Namespaces

Functions

function applicationConfig

function argsToTemplate

Example 1

function componentWrapperDecorator

function definePreview

Example 1

function moduleMetadata

function setProjectAnnotations

Parameter projectAnnotations

Interfaces

interface AngularMeta

method story

Example 1

Example 1

Example 1

interface AngularOptions

property enableIvy

interface AngularPreview

Example 1

method meta

method type

Example 1

interface AngularRenderer

property component

property storyResult

interface AngularStory

interface IStory

property applicationConfig

property moduleMetadata

property props

property styles

property template

property userDefinedTemplate

Type Aliases

type AngularParameters

type Decorator

type FrameworkOptions

type Loader

type Meta

See Also

type Preview

type StorybookConfig

type StoryContext

type StoryFn

See Also

type StoryObj

See Also

type TransformComponentType

Namespaces

namespace global

interface SymbolConstructor

property observable

Package Files (1)

Dependencies (6)

Dev Dependencies (19)

Peer Dependencies (15)

Badge