MDX Integration

/**
 * Validates story functions in MDX contexts
 * @param storyFn - Function to validate
 * @throws Error if not a valid story function
 */
function assertIsFn(storyFn: any): asserts storyFn is Function;

/**
 * Context provider for MDX rendering with Storybook integration
 * @param props - Context provider props
 * @returns React context provider for MDX
 */
function AddContext(props: AddContextProps): React.ReactElement;

interface AddContextProps {
  children: React.ReactNode;
  context: any;
}

/**
 * Renders code blocks in MDX with proper formatting and syntax highlighting
 * @param props - Code block configuration
 * @returns React component with formatted code
 */
function CodeOrSourceMdx(props: CodeOrSourceMdxProps): React.ReactElement;

interface CodeOrSourceMdxProps {
  /** Code content to display */
  children: string;
  /** Programming language for syntax highlighting */
  className?: string;
  /** Enable line numbers */
  showLineNumbers?: boolean;
  /** Code formatting options */
  format?: boolean | string;
}

/**
 * Enhanced anchor links with auto-generated IDs for navigation
 * @param props - Anchor configuration
 * @returns React component with enhanced anchor
 */
function AnchorMdx(props: AnchorMdxProps): React.ReactElement;

interface AnchorMdxProps {
  /** Anchor ID for linking */
  id: string;
  /** Link content */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
}

/**
 * Header components with automatic anchor generation and TOC integration
 * @param props - Header configuration
 * @returns React component with enhanced header
 */
function HeaderMdx(props: HeaderMdxProps): React.ReactElement;

interface HeaderMdxProps {
  /** Header level */
  as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
  /** Header content */
  children: React.ReactNode;
  /** CSS class name */
  className?: string;
  /** Custom ID for anchor */
  id?: string;
}

/**
 * Map of header components (h1-h6) for MDX rendering
 */
const HeadersMdx: HeadersMdxMap;

interface HeadersMdxMap {
  h1: React.FC<HeaderProps>;
  h2: React.FC<HeaderProps>;
  h3: React.FC<HeaderProps>;
  h4: React.FC<HeaderProps>;
  h5: React.FC<HeaderProps>;
  h6: React.FC<HeaderProps>;
}

interface HeaderProps {
  children: React.ReactNode;
  id?: string;
  className?: string;
}

import { HeadersMdx, CodeOrSourceMdx, AnchorMdx } from "@storybook/addon-docs/blocks";

# My Documentation
<HeadersMdx.h1>Enhanced Header with Auto-Anchor</HeadersMdx.h1>

## Code Example
<CodeOrSourceMdx className="language-typescript">
{`
function myComponent() {
  return <div>Hello World</div>;
}
`}
</CodeOrSourceMdx>

<AnchorMdx id="custom-section">Jump to this section</AnchorMdx>

/**
 * Complete re-export of @mdx-js/react for framework compatibility
 * Provides MDXProvider and other MDX utilities
 */
export * from "@mdx-js/react";

// Key exports include:
interface MDXProviderProps {
  /** Custom component mapping for MDX elements */
  components?: MDXComponents;
  /** Child content to wrap */
  children: React.ReactNode;
}

interface MDXComponents {
  /** HTML element mappings */
  h1?: React.ComponentType<any>;
  h2?: React.ComponentType<any>;
  h3?: React.ComponentType<any>;
  h4?: React.ComponentType<any>;
  h5?: React.ComponentType<any>;
  h6?: React.ComponentType<any>;
  p?: React.ComponentType<any>;
  a?: React.ComponentType<any>;
  code?: React.ComponentType<any>;
  pre?: React.ComponentType<any>;
  [key: string]: React.ComponentType<any> | undefined;
}

/**
 * MDX Provider for custom component mapping
 */
const MDXProvider: React.FC<MDXProviderProps>;

/**
 * Hook for accessing MDX components within MDX context
 */
function useMDXComponents(): MDXComponents;

import { Canvas, Story } from "@storybook/addon-docs/blocks";
import * as ButtonStories from "./Button.stories";

# Button Documentation

Here's our primary button:

<Canvas of={ButtonStories.Primary} />

You can also embed stories inline:

<Story of={ButtonStories.Secondary} inline />

// Custom MDX component
function CustomMDXBlock({ children, highlight = false }) {
  return (
    <div className={`custom-block ${highlight ? 'highlighted' : ''}`}>
      {children}
    </div>
  );
}

// Use in MDX
import { CustomMDXBlock } from "./CustomComponents";

<CustomMDXBlock highlight>
This is a custom highlighted block in MDX!
</CustomMDXBlock>

// .storybook/main.js MDX configuration
export default {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx|mdx)"],
  addons: ["@storybook/addon-docs"],
  docs: {
    defaultName: "Documentation",
    autodocs: true
  },
  // MDX configuration
  features: {
    modern: true
  }
};

// Custom MDX components mapping
const mdxComponents = {
  h1: HeadersMdx.h1,
  h2: HeadersMdx.h2,
  h3: HeadersMdx.h3,
  h4: HeadersMdx.h4,
  h5: HeadersMdx.h5,
  h6: HeadersMdx.h6,
  code: CodeOrSourceMdx,
  a: AnchorMdx
};

// Types for MDX components
interface MDXContentProps {
  children?: React.ReactNode;
  components?: MDXComponents;
}

// Custom typed MDX component
const TypedMDXComponent: React.FC<MDXContentProps> = ({ 
  children, 
  components = {} 
}) => {
  const mergedComponents = {
    ...HeadersMdx,
    ...components
  };
  
  return (
    <MDXProvider components={mergedComponents}>
      {children}
    </MDXProvider>
  );
};

/**
 * Error boundary specifically for MDX content rendering
 */
class MDXErrorBoundary extends React.Component {
  constructor(props: { children: React.ReactNode });
  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
  render(): React.ReactNode;
}

/**
 * Error display component for MDX parsing errors
 */
function MDXError(props: MDXErrorProps): React.ReactElement;

interface MDXErrorProps {
  /** Error object */
  error: Error;
  /** Additional error context */
  context?: string;
  /** Retry handler */
  onRetry?: () => void;
}

import { Canvas, Story, Meta } from "@storybook/addon-docs/blocks";
import { HeadersMdx, CodeOrSourceMdx } from "@storybook/addon-docs/blocks";
import * as ComponentStories from "./Component.stories";

<Meta of={ComponentStories} />

<HeadersMdx.h1>Component Documentation</HeadersMdx.h1>

<HeadersMdx.h2>Overview</HeadersMdx.h2>

This component provides enhanced functionality with the following features:

<Canvas of={ComponentStories.Default} />

<HeadersMdx.h2>API Reference</HeadersMdx.h2>

<CodeOrSourceMdx className="language-typescript">
{`
interface ComponentProps {
  title: string;
  variant: 'primary' | 'secondary';
  disabled?: boolean;
}
`}
</CodeOrSourceMdx>

<HeadersMdx.h2>Examples</HeadersMdx.h2>

<Story of={ComponentStories.Primary} />
<Story of={ComponentStories.Secondary} />