tessl/npm-storybook--docs-tools

Shared utility functions for frameworks to implement docs in Storybook

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@storybook/docs-tools

Name: tessl/npm-storybook--docs-tools
Author: tessl

@storybook/docs-tools provides shared utility functions that enable frameworks to implement comprehensive documentation features within Storybook. The package serves as a compatibility layer that re-exports core documentation tools from Storybook's internal infrastructure, handling argTypes enhancement, JSDoc parsing, type system conversion, and component introspection.

Package Information

Package Name: @storybook/docs-tools
Package Type: npm
Language: TypeScript/JavaScript
Installation: npm install @storybook/docs-tools storybook

Core Imports

import { 
  enhanceArgTypes, 
  hasDocsOrControls, 
  parseJsDoc,
  convert,
  extractComponentProps,
  createSummaryValue,
  ADDON_ID,
  SourceType,
  TypeSystem 
} from "@storybook/docs-tools";

For CommonJS:

const { 
  enhanceArgTypes, 
  hasDocsOrControls, 
  parseJsDoc,
  convert,
  extractComponentProps,
  createSummaryValue,
  ADDON_ID,
  SourceType,
  TypeSystem 
} = require("@storybook/docs-tools");

Basic Usage

import { enhanceArgTypes, parseJsDoc, convert, extractComponentProps, SourceType } from "@storybook/docs-tools";
import type { StoryContextForEnhancers } from "@storybook/core/types";

// Enhance argTypes for a story context
function myDecorator(story: any, context: StoryContextForEnhancers) {
  const enhancedArgTypes = enhanceArgTypes(context);
  
  // Parse JSDoc from component description
  const jsDocResult = parseJsDoc(context.component?.docgenInfo?.description);
  
  // Convert individual docgen info to Storybook format
  const docgenInfo = context.component?.__docgenInfo?.props?.someProp;
  if (docgenInfo) {
    const convertedType = convert(docgenInfo);
  }
  
  // Extract component properties
  const extractedProps = extractComponentProps(context.component, 'props');
  
  return story({ ...context, argTypes: enhancedArgTypes });
}

// Check if docs/controls are enabled
import type { Options } from "@storybook/core/types";

function configurePresets(options: Options) {
  if (hasDocsOrControls(options)) {
    // Configure documentation features
  }
}

Architecture

@storybook/docs-tools is structured around several key subsystems:

ArgTypes Enhancement: Combines extracted component metadata with user-defined argTypes
JSDoc Processing: Parses and extracts structured information from JSDoc comments
Type System Detection: Identifies and handles JavaScript, Flow, and TypeScript type systems
Type Conversion: Converts between different type representations (PropTypes, Flow, TypeScript)
Component Introspection: Extracts properties, descriptions, and metadata from components
Documentation Generation: Provides utilities for creating comprehensive component documentation

Capabilities

Core Constants and Configuration

Essential constants and enums for integrating with Storybook's documentation system.

// Core addon identifiers
const ADDON_ID: "storybook/docs";
const PANEL_ID: string;
const PARAM_KEY: "docs";
const SNIPPET_RENDERED: string;

// Documentation source types
enum SourceType {
  AUTO = "auto",
  CODE = "code", 
  DYNAMIC = "dynamic"
}

Constants and Configuration

ArgTypes Enhancement

Core functionality for enhancing component argTypes by combining extracted type information with user-provided definitions.

function enhanceArgTypes<TRenderer extends Renderer>(
  context: StoryContextForEnhancers<TRenderer>
): typeof userArgTypes;

function hasDocsOrControls(options: Options): boolean;

ArgTypes Enhancement

JSDoc Parsing and Processing

Comprehensive JSDoc parsing system that extracts structured information from component documentation comments.

function parseJsDoc(
  value: string | null, 
  options?: JsDocParsingOptions
): JsDocParsingResult;

interface JsDocParsingResult {
  includesJsDoc: boolean;
  ignore: boolean;
  description?: string;
  extractedTags?: ExtractedJsDoc;
}

interface ExtractedJsDoc {
  params?: ExtractedJsDocParam[] | null;
  deprecated?: string | null;
  returns?: ExtractedJsDocReturns | null;
  ignore: boolean;
}

JSDoc Processing

Component Property Extraction

Tools for extracting and processing component properties from various docgen sources (react-docgen, vue-docgen-api, etc.).

function extractComponentProps(
  component: Component, 
  section: string
): ExtractedProp[];

function extractComponentDescription(component?: Component): string;

interface ExtractedProp {
  propDef: PropDef;
  docgenInfo: DocgenInfo;
  jsDocTags?: ExtractedJsDoc;
  typeSystem: TypeSystem;
}

Component Property Extraction

Type System Conversion

Comprehensive type conversion system supporting PropTypes, Flow, and TypeScript type definitions.

function convert(docgenInfo: DocgenInfo): any | null;

enum TypeSystem {
  JAVASCRIPT = "JavaScript",
  FLOW = "Flow", 
  TYPESCRIPT = "TypeScript",
  UNKNOWN = "Unknown"
}

interface DocgenInfo {
  type: DocgenPropType;
  flowType?: DocgenFlowType;
  tsType?: DocgenTypeScriptType;
  required: boolean;
  description: string;
  defaultValue: DocgenPropDefaultValue;
}

Type System Conversion

Utility Functions

Helper functions for string manipulation, value summarization, and type checking within the documentation system.

function createSummaryValue(summary?: string, detail?: string): PropSummaryValue;
function isTooLongForTypeSummary(value: string): boolean;
function isTooLongForDefaultValueSummary(value: string): boolean;
function normalizeNewlines(string: string): string;

const MAX_TYPE_SUMMARY_LENGTH: 90;
const MAX_DEFAULT_VALUE_SUMMARY_LENGTH: 50;

Utility Functions

Types

// Core component type
type Component = any;

// Type system detection
enum TypeSystem {
  JAVASCRIPT = "JavaScript",
  FLOW = "Flow", 
  TYPESCRIPT = "TypeScript",
  UNKNOWN = "Unknown"
}

// Property definition structures
interface PropDef {
  name: string;
  type: PropType | null;
  sbType?: any;
  required: boolean;
  description?: string;
  defaultValue?: PropDefaultValue | null;
  jsDocTags?: JsDocTags;
}

interface PropSummaryValue {
  summary?: string;
  detail?: string;
}

type PropType = PropSummaryValue;
type PropDefaultValue = PropSummaryValue;

// PropDef factory function type
type PropDefFactory = (
  propName: string,
  docgenInfo: DocgenInfo,
  jsDocTags?: ExtractedJsDoc
) => PropDef;

// JSDoc structures
interface JsDocParam {
  name: string | undefined | null;
  description?: string | null;
}

interface JsDocReturns {
  description?: string | null;
}

interface JsDocTags {
  params?: JsDocParam[] | null;
  returns?: JsDocReturns | null;
}

// Docgen type definitions
interface DocgenPropType {
  name: string;
  raw?: string;
  value?: any;
}

interface DocgenFlowType {
  name: string;
  raw?: string;
  elements?: DocgenFlowType[];
  signature?: any;
}

interface DocgenTypeScriptType {
  name: string;
  raw?: string;
  elements?: DocgenTypeScriptType[];
  signature?: any;
}

interface DocgenPropDefaultValue {
  value: string;
  computed: boolean;
}

// Extraction function types
type PropsExtractor = (component: Component) => { rows?: PropDef[] } | null;
type ArgTypesExtractor = (component: Component) => StrictArgTypes | null;
type ExtractProps = (component: Component, section: string) => ExtractedProp[];