Preview System

/**
 * Web-specific preview implementation with story rendering and state management
 */
class PreviewWeb<TRenderer> {
  constructor(args: PreviewWebArgs<TRenderer>);
  
  /**
   * Initialize the preview environment
   * @returns Promise that resolves when preview is ready
   */
  ready(): Promise<void>;
  
  /**
   * Render a story with the given options
   * @param renderOptions - Story rendering configuration
   * @returns Promise that resolves when rendering is complete
   */
  render(renderOptions: RenderOptions): Promise<void>;
  
  /**
   * Update URL and story selection
   * @param location - New URL location
   */
  updateLocation(location: Location): void;
  
  /**
   * Handle story args update
   * @param storyId - Story identifier
   * @param newArgs - Updated args
   */
  updateStoryArgs(storyId: string, newArgs: Args): void;
  
  /**
   * Handle globals update
   * @param newGlobals - Updated global values
   */
  updateGlobals(newGlobals: Args): void;
}

interface PreviewWebArgs<TRenderer> {
  /** Import function for loading stories */
  importFn: (path: string) => Promise<any>;
  /** Function to get project annotations */
  getProjectAnnotations: () => ProjectAnnotations<TRenderer>;
  /** DOM element for rendering stories */
  renderToCanvas: (context: RenderContext<TRenderer>) => Promise<void>;
  /** Custom render function */
  renderStoryToElement?: (story: Story<TRenderer>, element: HTMLElement) => Promise<void>;
}

interface RenderOptions {
  /** Story to render */
  storyId?: string;
  /** View mode (story or docs) */
  viewMode?: 'story' | 'docs';
  /** Force re-render even if story hasn't changed */
  forceRender?: boolean;
}

import { PreviewWeb } from "@storybook/preview-api";

// Create preview instance
const preview = new PreviewWeb({
  importFn: (path) => import(path),
  getProjectAnnotations: () => ({
    parameters: { actions: { argTypesRegex: '^on[A-Z].*' } },
    decorators: [withTheme]
  }),
  renderToCanvas: async (context) => {
    const element = document.getElementById('storybook-root');
    if (element) {
      const story = context.storyFn();
      ReactDOM.render(story, element);
    }
  }
});

// Initialize and render story
await preview.ready();
await preview.render({ 
  storyId: 'example-button--primary',
  viewMode: 'story' 
});

// Update story args
preview.updateStoryArgs('example-button--primary', { 
  label: 'Updated', 
  variant: 'secondary' 
});

/**
 * Base preview implementation providing core story management
 */
class Preview<TRenderer> {
  constructor(imports: PreviewArgs<TRenderer>);
  
  /**
   * Initialize the preview with story index and configuration
   * @returns Promise that resolves when preview is ready
   */
  ready(): Promise<void>;
  
  /**
   * Extract and cache a story by ID
   * @param storyId - Story identifier
   * @returns Promise resolving to the cached story
   */
  extract(storyId: string): Promise<Story<TRenderer>>;
  
  /**
   * Get story context for a given story
   * @param story - Story object
   * @returns Complete story context
   */
  getStoryContext(story: Story<TRenderer>): StoryContext<TRenderer>;
}

interface PreviewArgs<TRenderer> {
  /** Import function for loading stories */
  importFn: (path: string) => Promise<any>;
  /** Function to get project annotations */
  getProjectAnnotations: () => ProjectAnnotations<TRenderer>;
}

/**
 * Preview implementation with story selection and navigation
 */
class PreviewWithSelection<TRenderer> extends Preview<TRenderer> {
  constructor(imports: PreviewWithSelectionArgs<TRenderer>);
  
  /**
   * Select and render a story
   * @param storyId - Story to select
   * @param viewMode - View mode for rendering
   * @returns Promise that resolves when selection is complete
   */
  selectStory(storyId: string, viewMode?: 'story' | 'docs'): Promise<void>;
  
  /**
   * Get currently selected story
   * @returns Currently selected story or undefined
   */
  getCurrentStory(): Story<TRenderer> | undefined;
  
  /**
   * Navigate to next/previous story
   * @param direction - Navigation direction
   */
  navigate(direction: 'next' | 'previous'): void;
}

interface PreviewWithSelectionArgs<TRenderer> extends PreviewArgs<TRenderer> {
  /** Selection store for managing current selection */
  selectionStore: SelectionStore;
}

/**
 * Manages URL-based state for story selection and parameters
 */
class UrlStore {
  constructor();
  
  /**
   * Get current selection from URL
   * @returns Current story selection
   */
  getSelection(): Selection;
  
  /**
   * Update URL with new selection
   * @param selection - New story selection
   */
  setSelection(selection: Selection): void;
  
  /**
   * Get query parameters as key-value pairs
   * @returns Current query parameters
   */
  getQueryParams(): Record<string, string>;
  
  /**
   * Update query parameters
   * @param params - Parameters to update
   */
  setQueryParams(params: Record<string, string>): void;
}

interface Selection {
  /** Selected story ID */
  storyId?: string;
  /** Current view mode */
  viewMode?: 'story' | 'docs';
  /** Additional selection parameters */
  [key: string]: any;
}

/**
 * Web-specific view implementation for story rendering
 */
class WebView implements View<HTMLElement> {
  constructor(args: WebViewArgs);
  
  /**
   * Prepare DOM element for story rendering
   * @param storyId - Story being prepared
   * @returns Promise that resolves when preparation is complete
   */
  prepareForStory(storyId: string): Promise<void>;
  
  /**
   * Show error in the view
   * @param error - Error to display
   */
  showErrorDisplay(error: Error): void;
  
  /**
   * Show loading state
   */
  showLoadingDisplay(): void;
  
  /**
   * Show story content
   * @param element - Element containing the story
   */
  showStoryDisplay(element: HTMLElement): void;
}

interface WebViewArgs {
  /** Root DOM element for the view */
  rootElement: HTMLElement;
  /** Whether to show loading states */
  showLoader?: boolean;
}

/**
 * Interface for managing story selection state
 */
interface SelectionStore {
  /**
   * Get current selection
   * @returns Current story selection
   */
  getSelection(): Selection;
  
  /**
   * Set new selection
   * @param selection - New story selection
   */
  setSelection(selection: Selection): void;
  
  /**
   * Subscribe to selection changes
   * @param callback - Function called when selection changes
   * @returns Unsubscribe function
   */
  subscribe(callback: (selection: Selection) => void): () => void;
}

/**
 * Generic view interface for story rendering across environments
 */
interface View<TStorybookRoot = any> {
  /**
   * Prepare view for rendering a specific story
   * @param storyId - Story identifier
   * @returns Promise that resolves when ready
   */
  prepareForStory(storyId: string): Promise<void>;
  
  /**
   * Display error state
   * @param error - Error to display
   */
  showErrorDisplay(error: Error): void;
  
  /**
   * Display loading state
   */
  showLoadingDisplay(): void;
  
  /**
   * Display story content
   * @param element - Story content element
   */
  showStoryDisplay(element: TStorybookRoot): void;
}

interface RenderContext<TRenderer = any> {
  /** Story identifier */
  id: string;
  /** Story title */
  title: string;
  /** Story name */
  name: string;
  /** Story context */
  storyContext: StoryContext<TRenderer>;
  /** Function to render story to DOM */
  renderToDOM: (element: HTMLElement) => Promise<void>;
  /** Unbound story function */
  unboundStoryFn: Function;
  /** Whether this is a docs render */
  showMain: boolean;
  /** Whether to force remount */
  forceRemount: boolean;
}

interface Location {
  /** URL pathname */
  pathname: string;
  /** URL search parameters */
  search: string;
  /** URL hash */
  hash: string;
}

interface ProjectAnnotations<TRenderer = any> {
  /** Global parameters */
  parameters?: Parameters;
  /** Global decorators */
  decorators?: DecoratorFunction<TRenderer>[];
  /** Global args */
  args?: Args;
  /** Global arg types */
  argTypes?: ArgTypes;
  /** Global values */
  globals?: Args;
  /** Global controls */
  globalTypes?: GlobalTypes;
  /** Render function */
  render?: Function;
  /** Component for autodocs */
  component?: any;
}