tessl/npm-storybook--web-components

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

—

Pending

Overview

Eval results

Files

Advanced Functions

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

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.

Core Imports

import { 
  extractArgTypesFromElements, 
  extractArgTypes, 
  extractComponentDescription 
} from "@storybook/web-components";

Capabilities

Documentation Generation

Functions for extracting component information from custom elements manifests for documentation purposes.

/**
 * Extracts arg types from custom elements manifest for a specific component.
 * @param tagName - The component tag name to extract arg types for
 * @param customElements - Custom elements manifest object
 * @returns Extracted arg types configuration object
 */
function extractArgTypesFromElements(
  tagName: string, 
  customElements: CustomElements
): Record<string, any>;

/**
 * Extracts arg types for a component from the global custom elements manifest.
 * @param tagName - The component tag name to extract arg types for
 * @returns Extracted arg types configuration object, or undefined if not found
 */
function extractArgTypes(tagName: string): Record<string, any> | undefined;

/**
 * Extracts component description from custom elements manifest.
 * @param tagName - The component tag name to get description for
 * @returns Component description string, or undefined if not found
 */
function extractComponentDescription(tagName: string): string | undefined;

Usage Patterns

Custom Documentation Integration

These functions are useful when building custom documentation tools or integrations:

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

// Get component information for custom docs
const componentInfo = {
  tagName: "my-button",
  description: extractComponentDescription("my-button"),
  argTypes: extractArgTypes("my-button"),
};

console.log(componentInfo);
// {
//   tagName: "my-button",
//   description: "A customizable button component",
//   argTypes: {
//     label: { control: "text", description: "Button label text" },
//     variant: { control: "select", options: ["primary", "secondary"] }
//   }
// }

Manual Arg Types Processing

When you need to process custom elements manifest data manually:

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

// Extract arg types from a specific manifest (not global)
const argTypes = extractArgTypesFromElements("my-component", customElementsManifest);

// Use the extracted arg types in your own story configuration
const meta: Meta = {
  title: "Components/MyComponent",
  component: "my-component",
  argTypes, // Use the manually extracted arg types
};

Component Validation Workflow

Combine these functions with validation functions for comprehensive component checking:

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

function validateAndDescribeComponent(tagName: string) {
  // First validate the component name
  if (!isValidComponent(tagName)) {
    throw new Error(`Invalid component: ${tagName}`);
  }
  
  // Extract documentation information
  const description = extractComponentDescription(tagName);
  const argTypes = extractArgTypes(tagName);
  
  if (!description || !argTypes) {
    console.warn(`Limited documentation available for ${tagName}`);
  }
  
  return {
    tagName,
    description: description || "No description available",
    argTypes: argTypes || {},
    hasDocumentation: !!(description && argTypes),
  };
}

// Use in component discovery
const componentInfo = validateAndDescribeComponent("my-button");

Integration with Storybook Features

Automatic Documentation

These functions power Storybook's automatic documentation generation:

Args Table: Uses extractArgTypes to populate the props table
Component Description: Uses extractComponentDescription for component docs
Controls: Uses arg types to generate appropriate control types

Custom Addons

When building custom Storybook addons that need component metadata:

// In a custom addon
import { extractArgTypes, extractComponentDescription } from "@storybook/web-components";

export const myAddon = (context) => {
  const { component } = context.parameters;
  
  if (typeof component === "string") {
    const argTypes = extractArgTypes(component);
    const description = extractComponentDescription(component);
    
    // Use the extracted information in your addon logic
    return {
      argTypes,
      description,
      // ... other addon functionality
    };
  }
};

Custom Elements Manifest Format

These functions work with both supported manifest formats:

Tags-based Format (Experimental)

{
  "version": "experimental",
  "tags": [
    {
      "name": "my-element",
      "description": "Element description",
      "attributes": [
        {
          "name": "label",
          "type": { "text": "string" },
          "description": "Button label"
        }
      ]
    }
  ]
}

Modules-based Format (v1)

{
  "modules": [
    {
      "declarations": [
        {
          "tagName": "my-element",
          "description": "Element description",
          "attributes": [
            {
              "name": "label",
              "type": { "text": "string" },
              "description": "Button label"
            }
          ]
        }
      ]
    }
  ]
}

Error Handling

These functions are designed to be resilient:

// Functions return undefined for missing components
const argTypes = extractArgTypes("non-existent-component");
console.log(argTypes); // undefined

const description = extractComponentDescription("non-existent-component");
console.log(description); // undefined

// They don't throw errors, allowing graceful degradation

Performance Considerations

These functions read from the global custom elements manifest
Results are not cached, so consider caching in performance-critical scenarios
The manifest is parsed each time, so avoid calling repeatedly in tight loops

// Good: Cache results when processing multiple components
const componentsInfo = componentList.map(tagName => ({
  tagName,
  argTypes: extractArgTypes(tagName),
  description: extractComponentDescription(tagName),
}));

// Less optimal: Repeated calls in a loop without caching
componentList.forEach(tagName => {
  const argTypes = extractArgTypes(tagName); // Repeated manifest parsing
  // ... process each component
});

Install with Tessl CLI

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

docs

advanced-functions.md

framework-integration.md

tessl/npm-storybook--web-components