or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-functions.mdframework-integration.mdindex.mdportable-stories.mdstory-types.md
tile.json

tessl/npm-storybook--web-components

Storybook Web Components renderer for developing, documenting, and testing UI components in isolation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/web-components@9.1.x

To install, run

npx @tessl/cli install tessl/npm-storybook--web-components@9.1.0

index.mddocs/

Storybook Web Components

Storybook Web Components renderer enables developing, documenting, and testing UI components in isolation using the Storybook development environment. It provides specialized rendering capabilities for web component technologies including Lit and lit-html, offering integration capabilities for component development workflows with full TypeScript support.

Package Information

  • Package Name: @storybook/web-components
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @storybook/web-components

Core Imports

import type { Meta, StoryObj, StoryFn } from "@storybook/web-components";

For custom elements management:

import { setCustomElements, getCustomElements } from "@storybook/web-components";

For rendering functions:

import { render, renderToCanvas } from "@storybook/web-components";

For portable stories (testing):

import { setProjectAnnotations } from "@storybook/web-components";

Basic Usage

Story Creation

import type { Meta, StoryObj } from "@storybook/web-components";

// Component metadata
const meta: Meta = {
  title: "Example/Button",
  component: "my-button",
  parameters: {
    layout: "centered",
  },
  argTypes: {
    backgroundColor: { control: "color" },
  },
};

export default meta;
type Story = StoryObj;

// Story definition
export const Primary: Story = {
  args: {
    primary: true,
    label: "Button",
  },
};

Custom Elements Integration

import { setCustomElements } from "@storybook/web-components";
import customElements from "./custom-elements.json";

// Configure custom elements for documentation
setCustomElements(customElements);

Architecture

Storybook Web Components renderer is built around several key components:

  • Type System: TypeScript interfaces for type-safe story creation (Meta, StoryFn, StoryObj)
  • Framework Integration: Functions for custom elements metadata management and validation
  • Testing Support: Portable stories API for component testing outside Storybook

Capabilities

Story Creation & Types

Core TypeScript interfaces and types for creating type-safe Storybook stories for web components.

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

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

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

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

type Preview = ProjectAnnotations<WebComponentsRenderer>;

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

type StoryContext<TArgs = StrictArgs> = GenericStoryContext<WebComponentsRenderer, TArgs>;

Story Creation & Types

Framework Integration

Utility functions for managing custom elements metadata, component validation, and framework configuration.

function setCustomElements(customElements: any): void;

function getCustomElements(): any;

function isValidComponent(tagName: string): boolean;

function isValidMetaData(customElements: any): boolean;

function setCustomElementsManifest(customElements: any): void;

Framework Integration

Story Rendering

Core rendering functions for converting story definitions into DOM elements.

function render(
  storyFn: StoryFn<any>,
  context: StoryContext<any>
): string | Node | DocumentFragment | TemplateResult | SVGTemplateResult;

function renderToCanvas(
  content: StoryFnHtmlReturnType,
  canvasElement: HTMLElement
): void;

Portable Stories

Testing utilities for using Storybook stories outside of the Storybook environment, particularly useful for unit testing and integration testing.

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

Portable Stories

Advanced Functions

Internal and advanced utility functions for custom elements metadata processing and documentation generation. These functions are primarily used by Storybook's documentation addon but can be useful for advanced integrations.

function extractArgTypesFromElements(
  tagName: string, 
  customElements: any
): Record<string, any>;

function extractArgTypes(tagName: string): Record<string, any> | undefined;

function extractComponentDescription(tagName: string): string | undefined;

Advanced Functions

Types

interface WebComponentsRenderer extends WebRenderer {
  component: string;
  storyResult: StoryFnHtmlReturnType;
}

type StoryFnHtmlReturnType = 
  | string 
  | Node 
  | DocumentFragment 
  | TemplateResult 
  | SVGTemplateResult;

type Args = Record<string, any>;

type StrictArgs = Record<string, any>;

type ArgTypes = Record<string, any>;

type Parameters = Record<string, any>;

interface WebRenderer {
  name: string;
  render: (context: StoryContext) => any;
}

interface StoryContext<TArgs = StrictArgs> {
  id: string;
  title: string;
  kind: string;
  name: string;
  story: string;
  parameters: Parameters;
  args: TArgs;
  argTypes: ArgTypes;
  globals: Record<string, any>;
  hooks: any;
  loaded: Record<string, any>;
  viewMode: string;
}

type ComponentAnnotations<TRenderer, TArgs = Args> = {
  title?: string;
  component?: TRenderer['component'];
  parameters?: Parameters;
  argTypes?: ArgTypes;
  args?: Partial<TArgs>;
  decorators?: Decorator<TArgs>[];
  loaders?: Loader<TArgs>[];
  render?: StoryFn<TArgs>;
  subcomponents?: Record<string, TRenderer['component']>;
  tags?: string[];
};

type StoryAnnotations<TRenderer, TArgs = Args> = {
  args?: Partial<TArgs>;
  argTypes?: ArgTypes;
  parameters?: Parameters;
  decorators?: Decorator<TArgs>[];
  loaders?: Loader<TArgs>[];
  render?: StoryFn<TArgs>;
  play?: any;
  tags?: string[];
};

type AnnotatedStoryFn<TRenderer, TArgs = Args> = StoryFn<TArgs> & StoryAnnotations<TRenderer, TArgs>;

type ProjectAnnotations<TRenderer> = {
  parameters?: Parameters;
  argTypes?: ArgTypes;
  args?: Args;
  decorators?: Decorator[];
  loaders?: Loader[];
  render?: StoryFn;
  globalTypes?: Record<string, any>;
  tags?: string[];
};

type NamedOrDefaultProjectAnnotations<TRenderer> = 
  | ProjectAnnotations<TRenderer>
  | { default: ProjectAnnotations<TRenderer> };

type NormalizedProjectAnnotations<TRenderer> = ProjectAnnotations<TRenderer> & {
  normalizedParameters: Parameters;
  normalizedArgTypes: ArgTypes;
  normalizedArgs: Args;
};