0
# Preview System
1

2
Web-based preview environment with story selection, rendering, and URL-based state management. The Preview System handles the complete story rendering lifecycle in browser environments, providing the core infrastructure for Storybook's UI.
3

4
## Capabilities
5

6
### Preview Web
7

8
Main preview implementation for web environments with full story lifecycle management.
9

10
```typescript { .api }
11
/**
12
 * Web-specific preview implementation with story rendering and state management
13
 */
14
class PreviewWeb<TRenderer> {
15
  constructor(args: PreviewWebArgs<TRenderer>);
16
  
17
  /**
18
   * Initialize the preview environment
19
   * @returns Promise that resolves when preview is ready
20
   */
21
  ready(): Promise<void>;
22
  
23
  /**
24
   * Render a story with the given options
25
   * @param renderOptions - Story rendering configuration
26
   * @returns Promise that resolves when rendering is complete
27
   */
28
  render(renderOptions: RenderOptions): Promise<void>;
29
  
30
  /**
31
   * Update URL and story selection
32
   * @param location - New URL location
33
   */
34
  updateLocation(location: Location): void;
35
  
36
  /**
37
   * Handle story args update
38
   * @param storyId - Story identifier
39
   * @param newArgs - Updated args
40
   */
41
  updateStoryArgs(storyId: string, newArgs: Args): void;
42
  
43
  /**
44
   * Handle globals update
45
   * @param newGlobals - Updated global values
46
   */
47
  updateGlobals(newGlobals: Args): void;
48
}
49

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

61
interface RenderOptions {
62
  /** Story to render */
63
  storyId?: string;
64
  /** View mode (story or docs) */
65
  viewMode?: 'story' | 'docs';
66
  /** Force re-render even if story hasn't changed */
67
  forceRender?: boolean;
68
}
69
```
70

71
**Usage Examples:**
72

73
```typescript
74
import { PreviewWeb } from "@storybook/preview-api";
75

76
// Create preview instance
77
const preview = new PreviewWeb({
78
  importFn: (path) => import(path),
79
  getProjectAnnotations: () => ({
80
    parameters: { actions: { argTypesRegex: '^on[A-Z].*' } },
81
    decorators: [withTheme]
82
  }),
83
  renderToCanvas: async (context) => {
84
    const element = document.getElementById('storybook-root');
85
    if (element) {
86
      const story = context.storyFn();
87
      ReactDOM.render(story, element);
88
    }
89
  }
90
});
91

92
// Initialize and render story
93
await preview.ready();
94
await preview.render({ 
95
  storyId: 'example-button--primary',
96
  viewMode: 'story' 
97
});
98

99
// Update story args
100
preview.updateStoryArgs('example-button--primary', { 
101
  label: 'Updated', 
102
  variant: 'secondary' 
103
});
104
```
105

106
### Base Preview
107

108
Foundation preview class providing core functionality for different environments.
109

110
```typescript { .api }
111
/**
112
 * Base preview implementation providing core story management
113
 */
114
class Preview<TRenderer> {
115
  constructor(imports: PreviewArgs<TRenderer>);
116
  
117
  /**
118
   * Initialize the preview with story index and configuration
119
   * @returns Promise that resolves when preview is ready
120
   */
121
  ready(): Promise<void>;
122
  
123
  /**
124
   * Extract and cache a story by ID
125
   * @param storyId - Story identifier
126
   * @returns Promise resolving to the cached story
127
   */
128
  extract(storyId: string): Promise<Story<TRenderer>>;
129
  
130
  /**
131
   * Get story context for a given story
132
   * @param story - Story object
133
   * @returns Complete story context
134
   */
135
  getStoryContext(story: Story<TRenderer>): StoryContext<TRenderer>;
136
}
137

138
interface PreviewArgs<TRenderer> {
139
  /** Import function for loading stories */
140
  importFn: (path: string) => Promise<any>;
141
  /** Function to get project annotations */
142
  getProjectAnnotations: () => ProjectAnnotations<TRenderer>;
143
}
144
```
145

146
### Preview with Selection
147

148
Extended preview class that adds story selection and navigation capabilities.
149

150
```typescript { .api }
151
/**
152
 * Preview implementation with story selection and navigation
153
 */
154
class PreviewWithSelection<TRenderer> extends Preview<TRenderer> {
155
  constructor(imports: PreviewWithSelectionArgs<TRenderer>);
156
  
157
  /**
158
   * Select and render a story
159
   * @param storyId - Story to select
160
   * @param viewMode - View mode for rendering
161
   * @returns Promise that resolves when selection is complete
162
   */
163
  selectStory(storyId: string, viewMode?: 'story' | 'docs'): Promise<void>;
164
  
165
  /**
166
   * Get currently selected story
167
   * @returns Currently selected story or undefined
168
   */
169
  getCurrentStory(): Story<TRenderer> | undefined;
170
  
171
  /**
172
   * Navigate to next/previous story
173
   * @param direction - Navigation direction
174
   */
175
  navigate(direction: 'next' | 'previous'): void;
176
}
177

178
interface PreviewWithSelectionArgs<TRenderer> extends PreviewArgs<TRenderer> {
179
  /** Selection store for managing current selection */
180
  selectionStore: SelectionStore;
181
}
182
```
183

184
### URL Store
185

186
URL-based state management for story selection and parameters.
187

188
```typescript { .api }
189
/**
190
 * Manages URL-based state for story selection and parameters
191
 */
192
class UrlStore {
193
  constructor();
194
  
195
  /**
196
   * Get current selection from URL
197
   * @returns Current story selection
198
   */
199
  getSelection(): Selection;
200
  
201
  /**
202
   * Update URL with new selection
203
   * @param selection - New story selection
204
   */
205
  setSelection(selection: Selection): void;
206
  
207
  /**
208
   * Get query parameters as key-value pairs
209
   * @returns Current query parameters
210
   */
211
  getQueryParams(): Record<string, string>;
212
  
213
  /**
214
   * Update query parameters
215
   * @param params - Parameters to update
216
   */
217
  setQueryParams(params: Record<string, string>): void;
218
}
219

220
interface Selection {
221
  /** Selected story ID */
222
  storyId?: string;
223
  /** Current view mode */
224
  viewMode?: 'story' | 'docs';
225
  /** Additional selection parameters */
226
  [key: string]: any;
227
}
228
```
229

230
### Web View
231

232
Web-specific view implementation for rendering stories in browser environments.
233

234
```typescript { .api }
235
/**
236
 * Web-specific view implementation for story rendering
237
 */
238
class WebView implements View<HTMLElement> {
239
  constructor(args: WebViewArgs);
240
  
241
  /**
242
   * Prepare DOM element for story rendering
243
   * @param storyId - Story being prepared
244
   * @returns Promise that resolves when preparation is complete
245
   */
246
  prepareForStory(storyId: string): Promise<void>;
247
  
248
  /**
249
   * Show error in the view
250
   * @param error - Error to display
251
   */
252
  showErrorDisplay(error: Error): void;
253
  
254
  /**
255
   * Show loading state
256
   */
257
  showLoadingDisplay(): void;
258
  
259
  /**
260
   * Show story content
261
   * @param element - Element containing the story
262
   */
263
  showStoryDisplay(element: HTMLElement): void;
264
}
265

266
interface WebViewArgs {
267
  /** Root DOM element for the view */
268
  rootElement: HTMLElement;
269
  /** Whether to show loading states */
270
  showLoader?: boolean;
271
}
272
```
273

274
### Selection Store
275

276
Interface for managing story selection state.
277

278
```typescript { .api }
279
/**
280
 * Interface for managing story selection state
281
 */
282
interface SelectionStore {
283
  /**
284
   * Get current selection
285
   * @returns Current story selection
286
   */
287
  getSelection(): Selection;
288
  
289
  /**
290
   * Set new selection
291
   * @param selection - New story selection
292
   */
293
  setSelection(selection: Selection): void;
294
  
295
  /**
296
   * Subscribe to selection changes
297
   * @param callback - Function called when selection changes
298
   * @returns Unsubscribe function
299
   */
300
  subscribe(callback: (selection: Selection) => void): () => void;
301
}
302
```
303

304
### View Interface
305

306
Generic view interface for different rendering environments.
307

308
```typescript { .api }
309
/**
310
 * Generic view interface for story rendering across environments
311
 */
312
interface View<TStorybookRoot = any> {
313
  /**
314
   * Prepare view for rendering a specific story
315
   * @param storyId - Story identifier
316
   * @returns Promise that resolves when ready
317
   */
318
  prepareForStory(storyId: string): Promise<void>;
319
  
320
  /**
321
   * Display error state
322
   * @param error - Error to display
323
   */
324
  showErrorDisplay(error: Error): void;
325
  
326
  /**
327
   * Display loading state
328
   */
329
  showLoadingDisplay(): void;
330
  
331
  /**
332
   * Display story content
333
   * @param element - Story content element
334
   */
335
  showStoryDisplay(element: TStorybookRoot): void;
336
}
337
```
338

339
## Context & Configuration
340

341
Additional interfaces and types for preview system configuration.
342

343
```typescript { .api }
344
interface RenderContext<TRenderer = any> {
345
  /** Story identifier */
346
  id: string;
347
  /** Story title */
348
  title: string;
349
  /** Story name */
350
  name: string;
351
  /** Story context */
352
  storyContext: StoryContext<TRenderer>;
353
  /** Function to render story to DOM */
354
  renderToDOM: (element: HTMLElement) => Promise<void>;
355
  /** Unbound story function */
356
  unboundStoryFn: Function;
357
  /** Whether this is a docs render */
358
  showMain: boolean;
359
  /** Whether to force remount */
360
  forceRemount: boolean;
361
}
362

363
interface Location {
364
  /** URL pathname */
365
  pathname: string;
366
  /** URL search parameters */
367
  search: string;
368
  /** URL hash */
369
  hash: string;
370
}
371

372
interface ProjectAnnotations<TRenderer = any> {
373
  /** Global parameters */
374
  parameters?: Parameters;
375
  /** Global decorators */
376
  decorators?: DecoratorFunction<TRenderer>[];
377
  /** Global args */
378
  args?: Args;
379
  /** Global arg types */
380
  argTypes?: ArgTypes;
381
  /** Global values */
382
  globals?: Args;
383
  /** Global controls */
384
  globalTypes?: GlobalTypes;
385
  /** Render function */
386
  render?: Function;
387
  /** Component for autodocs */
388
  component?: any;
389
}
390
```