Doc Block Components

/**
 * Main doc block component for embedding in Storybook docs pages
 * @param props - Configuration options for the doc block
 * @returns JSX element containing the token documentation
 */
function DesignTokenDocBlock(props: DesignTokenDocBlockProps): JSX.Element;

interface DesignTokenDocBlockProps {
  /** Name of the token category to display */
  categoryName: string;
  /** Maximum height of the container in pixels (default: 600) */
  maxHeight?: number;
  /** Whether to show the token value column (default: true) */
  showValueColumn?: boolean;
  /** Display type for tokens */
  viewType: TokenViewType;
  /** Array of token names to filter by */
  filterNames?: string[];
  /** Map of token names to usage examples */
  usageMap?: Record<string, string[]>;
  /** Theme override for styling */
  theme?: string;
  /** Enable search functionality (default: true) */
  showSearch?: boolean;
  /** Number of items per page for pagination */
  pageSize?: number;
  /** Custom presenter components */
  presenters?: PresenterMapType;
}

type TokenViewType = "table" | "card";

import { DesignTokenDocBlock } from "storybook-design-token";

// Basic usage in Storybook docs
<DesignTokenDocBlock
  categoryName="Colors"
  viewType="table"
/>

// Advanced configuration with filtering and custom presenters
<DesignTokenDocBlock
  categoryName="Typography"
  viewType="card"
  maxHeight={800}
  showSearch={true}
  pageSize={20}
  filterNames={["primary", "secondary", "accent"]}
  usageMap={{
    "primary-color": ["background-color: var(--primary-color)", "color: var(--primary-color)"],
    "heading-font": ["font-family: var(--heading-font)", "font: var(--heading-font)"]
  }}
  presenters={{
    "CustomColor": MyCustomColorPresenter
  }}
/>

// Embedded in MDX documentation
export const TokenShowcase = () => (
  <DesignTokenDocBlock
    categoryName="Spacing" 
    viewType="table"
    showValueColumn={true}
    theme="dark"
  />
);

interface StoryParameters {
  designToken?: Config;
}

interface Config {
  /** Enable search functionality */
  showSearch?: boolean;
  /** Default selected tab name */
  defaultTab?: string;
  /** Custom CSS injection */
  styleInjection?: string;
  /** Items per page */
  pageSize?: number;
  /** Custom presenter components */
  presenters?: PresenterMapType;
  /** Visible tab names filter */
  tabs?: string[];
}

// Story with custom configuration
export const MyStory = {
  parameters: {
    designToken: {
      showSearch: true,
      defaultTab: "Colors",
      pageSize: 15,
      tabs: ["Colors", "Typography", "Spacing"],
      styleInjection: `
        .design-token-container { 
          border: 1px solid #ccc; 
          border-radius: 8px; 
        }
      `
    }
  }
};

// Global configuration in preview.js
export default {
  parameters: {
    designToken: {
      showSearch: true,
      pageSize: 10,
      presenters: {
        "Color": CustomColorPresenter,
        "FontSize": CustomFontSizePresenter
      }
    }
  }
};

interface PresenterMapType {
  /** Map of presenter names to React components */
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
}

interface PresenterProps {
  /** Token data to present */
  token: Token;
}

import React from "react";
import { PresenterProps } from "storybook-design-token";

// Custom presenter component
const CustomColorPresenter: React.FC<PresenterProps> = ({ token }) => (
  <div style={{ display: "flex", alignItems: "center", gap: "8px" }}>
    <div
      style={{
        width: "32px",
        height: "32px",
        backgroundColor: token.value,
        borderRadius: "4px",
        border: "1px solid #ccc"
      }}
    />
    <div>
      <div style={{ fontWeight: "bold" }}>{token.name}</div>
      <div style={{ fontSize: "12px", color: "#666" }}>{token.value}</div>
    </div>
  </div>
);

// Usage in doc block
<DesignTokenDocBlock
  categoryName="CustomColors"
  viewType="table"
  presenters={{
    "Color": CustomColorPresenter
  }}
/>