tessl/npm-storybook--web-components

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

—

Pending

Overview

Eval results

Files

Framework Integration

Name: tessl/npm-storybook--web-components
Author: tessl

Utility functions for managing custom elements metadata, component validation, and framework configuration. These functions enable Storybook to understand and document web components by processing custom elements manifests and validating component configurations.

Capabilities

Custom Elements Management

Functions for setting and retrieving custom elements metadata used for automatic documentation generation.

/**
 * Sets custom elements metadata globally for documentation generation.
 * @param customElements - Custom elements manifest or metadata object
 */
function setCustomElements(customElements: any): void;

/**
 * Sets custom elements manifest globally (alternative to setCustomElements).
 * @param customElements - Custom elements manifest object
 */
function setCustomElementsManifest(customElements: any): void;

/**
 * Retrieves stored custom elements metadata.
 * @returns Custom elements metadata or manifest, or undefined if not set
 */
function getCustomElements(): any;

Usage:

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

// Set custom elements for automatic docs generation
setCustomElements(customElementsManifest);

// Example manifest structure
const manifest = {
  "version": "experimental",
  "tags": [
    {
      "name": "my-button",
      "description": "A customizable button component",
      "attributes": [
        {
          "name": "label",
          "type": { "text": "string" },
          "description": "Button label text",
          "default": "Click me"
        },
        {
          "name": "variant",
          "type": { "text": "string" },
          "description": "Button style variant",
          "default": "primary"
        }
      ],
      "properties": [
        {
          "name": "disabled",
          "type": { "text": "boolean" },
          "description": "Whether the button is disabled",
          "default": false
        }
      ],
      "events": [
        {
          "name": "click",
          "description": "Fired when button is clicked"
        }
      ],
      "slots": [
        {
          "name": "icon",
          "description": "Slot for button icon"
        }
      ]
    }
  ]
};

setCustomElements(manifest);

Component Validation

Functions for validating component names and metadata structures.

/**
 * Validates if a component tag name is valid for web components.
 * @param tagName - The component tag name to validate
 * @returns true if valid, false if falsy, throws error for invalid types
 * @throws Error if tagName is not a string when truthy
 */
function isValidComponent(tagName: string): boolean;

/**
 * Validates custom elements metadata structure.
 * @param customElements - Custom elements metadata to validate
 * @returns true if valid, false if invalid
 * @throws Error with setup instructions if invalid structure
 */
function isValidMetaData(customElements: any): boolean;

Usage:

import { isValidComponent, isValidMetaData } from "@storybook/web-components";

// Component validation
try {
  const isValid = isValidComponent("my-button");
  console.log("Component is valid:", isValid); // true
  
  const isEmpty = isValidComponent("");
  console.log("Empty component:", isEmpty); // false
  
  // This will throw an error
  isValidComponent(123); // Error: Provided component needs to be a string
} catch (error) {
  console.error(error.message);
}

// Metadata validation
const validManifest = {
  tags: [
    { name: "my-button", description: "A button" }
  ]
};

const validModules = {
  modules: [
    { declarations: [{ tagName: "my-button" }] }
  ]
};

try {
  console.log(isValidMetaData(validManifest)); // true
  console.log(isValidMetaData(validModules)); // true
  console.log(isValidMetaData({})); // false
  
  // This will throw an error
  isValidMetaData({ invalid: "structure" });
} catch (error) {
  console.error(error.message); // Setup instructions
}

Custom Elements Manifest Integration

Setting Up Documentation

To enable automatic documentation generation, you need to provide a custom elements manifest:

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

setCustomElements(customElements);

Generating Custom Elements Manifest

You can generate a custom elements manifest using tools like @custom-elements-manifest/analyzer:

# Install the analyzer
npm install -D @custom-elements-manifest/analyzer

# Generate manifest
npx cem analyze --litelement

# Or add to package.json scripts
{
  "scripts": {
    "analyze": "cem analyze --litelement --outdir ."
  }
}

Manifest Formats

The package supports two manifest formats:

Format 1: Tags-based (experimental)

{
  "version": "experimental",
  "tags": [
    {
      "name": "my-element",
      "description": "Element description",
      "attributes": [...],
      "properties": [...],
      "events": [...],
      "slots": [...],
      "methods": [...],
      "cssProperties": [...],
      "cssParts": [...]
    }
  ]
}

Format 2: Modules-based (v1)

{
  "modules": [
    {
      "declarations": [
        {
          "tagName": "my-element",
          "name": "MyElement",
          "description": "Element description",
          "attributes": [...],
          "members": [...]
        }
      ],
      "exports": [...]
    }
  ]
}

Global Access

The custom elements metadata is stored globally and can be accessed anywhere in your Storybook setup:

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

// In a decorator or story
const customElements = getCustomElements();
if (customElements) {
  // Use the metadata for custom documentation or behavior
}

Integration with Storybook Features

Automatic Args Generation

When custom elements are configured, Storybook automatically generates controls and documentation:

// Story file - no manual argTypes needed
const meta: Meta = {
  title: "Components/MyButton",
  component: "my-button", // Storybook will look up this component in the manifest
};

export default meta;
type Story = StoryObj;

// Controls and docs are automatically generated from the manifest
export const Default: Story = {};

export const Configured: Story = {
  args: {
    label: "Custom Label",
    variant: "secondary",
    disabled: false,
  },
};

Documentation Generation

Custom elements metadata enables rich documentation:

Controls: Automatic control generation for attributes and properties
Args Table: Displays all available props with types and descriptions
Events: Shows available events that can be listened to
Slots: Documents available content slots
CSS Custom Properties: Lists customizable CSS properties
CSS Parts: Shows styleable parts for component customization

Error Handling

The validation functions provide helpful error messages:

// Component validation errors
isValidComponent(null); // returns false
isValidComponent(""); // returns false
isValidComponent(123); // throws: "Provided component needs to be a string. e.g. component: \"my-element\""

// Metadata validation errors
isValidMetaData({}); // throws: "You need to setup valid meta data in your config.js via setCustomElements()..."

Install with Tessl CLI

npx tessl i tessl/npm-storybook--web-components

docs

advanced-functions.md

framework-integration.md

tessl/npm-storybook--web-components