0
# Story Store & Management
1

2
Central story management system providing story loading, caching, args management, and context creation. The Story Store serves as the core infrastructure for Storybook's preview environment, handling story lifecycle and state management.
3

4
## Capabilities
5

6
### Story Store
7

8
Primary class for managing stories, their state, and related configurations.
9

10
```typescript { .api }
11
/**
12
 * Central story management class handling story lifecycle and state
13
 */
14
class StoryStore<TRenderer> {
15
  /** Index of all available stories */
16
  storyIndex: StoryIndex;
17
  /** Global project configuration */
18
  projectAnnotations: ProjectAnnotations<TRenderer>;
19
  /** User-defined global values */
20
  userGlobals: Args;
21
  /** Args store for managing story arguments */
22
  args: ArgsStore;
23
  /** Hook context for story execution */
24
  hooks: HooksContext<TRenderer>;
25
  
26
  constructor(args: StoryStoreArgs<TRenderer>);
27
  
28
  /**
29
   * Initialize the store with story index and project annotations
30
   * @param storyIndex - Index of all stories
31
   * @param projectAnnotations - Global project configuration
32
   */
33
  initialize(storyIndex: StoryIndex, projectAnnotations: ProjectAnnotations<TRenderer>): Promise<void>;
34
  
35
  /**
36
   * Load and cache a story by ID
37
   * @param storyId - Unique story identifier
38
   * @returns Promise resolving to the loaded story
39
   */
40
  loadStory(storyId: string): Promise<Story<TRenderer>>;
41
  
42
  /**
43
   * Get story context for rendering
44
   * @param story - Story object
45
   * @returns Complete story context
46
   */
47
  getStoryContext(story: Story<TRenderer>): StoryContext<TRenderer>;
48
  
49
  /**
50
   * Update story args
51
   * @param storyId - Story identifier
52
   * @param newArgs - Args to update
53
   */
54
  updateStoryArgs(storyId: string, newArgs: Args): void;
55
  
56
  /**
57
   * Reset story args to defaults
58
   * @param storyId - Story identifier
59
   * @param argNames - Specific arg names to reset (optional)
60
   */
61
  resetStoryArgs(storyId: string, argNames?: string[]): void;
62
}
63

64
interface StoryStoreArgs<TRenderer> {
65
  /** Module loading function */
66
  importFn: (path: string) => Promise<any>;
67
  /** Cache for loaded stories */
68
  cache?: Map<string, any>;
69
  /** Initial story index */
70
  storyIndex?: StoryIndex;
71
}
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { StoryStore } from "@storybook/preview-api";
78

79
// Create story store instance
80
const storyStore = new StoryStore({
81
  importFn: (path) => import(path),
82
  cache: new Map()
83
});
84

85
// Initialize with story index
86
await storyStore.initialize(storyIndex, projectAnnotations);
87

88
// Load specific story
89
const story = await storyStore.loadStory('example-button--primary');
90

91
// Get story context for rendering
92
const context = storyStore.getStoryContext(story);
93

94
// Update story args
95
storyStore.updateStoryArgs('example-button--primary', { 
96
  label: 'Updated Label',
97
  disabled: false 
98
});
99

100
// Reset specific args
101
storyStore.resetStoryArgs('example-button--primary', ['disabled']);
102
```
103

104
### Args Management
105

106
Specialized store for managing story arguments across the application.
107

108
```typescript { .api }
109
/**
110
 * Store for managing story arguments with persistence and updates
111
 */
112
class ArgsStore {
113
  constructor();
114
  
115
  /**
116
   * Get args for a specific story
117
   * @param storyId - Story identifier
118
   * @returns Current args for the story
119
   */
120
  get(storyId: string): Args;
121
  
122
  /**
123
   * Update args for a story
124
   * @param storyId - Story identifier
125
   * @param newArgs - Args to merge with existing args
126
   */
127
  update(storyId: string, newArgs: Args): void;
128
  
129
  /**
130
   * Reset args for a story to defaults
131
   * @param storyId - Story identifier
132
   * @param argNames - Specific arg names to reset (optional)
133
   */
134
  reset(storyId: string, argNames?: string[]): void;
135
  
136
  /**
137
   * Get all args across all stories
138
   * @returns Map of story IDs to their args
139
   */
140
  getAll(): Record<string, Args>;
141
}
142
```
143

144
### Globals Management
145

146
Store for managing global values that apply across all stories.
147

148
```typescript { .api }
149
/**
150
 * Store for managing global values across all stories
151
 */
152
class GlobalsStore {
153
  constructor();
154
  
155
  /**
156
   * Get current global values
157
   * @returns Current globals object
158
   */
159
  get(): Args;
160
  
161
  /**
162
   * Update global values
163
   * @param newGlobals - Globals to merge with existing values
164
   */
165
  update(newGlobals: Args): void;
166
  
167
  /**
168
   * Reset globals to defaults
169
   */
170
  reset(): void;
171
}
172
```
173

174
### Story Index Management
175

176
System for managing the index of all available stories.
177

178
```typescript { .api }
179
/**
180
 * Store for managing the story index and metadata
181
 */
182
class StoryIndexStore {
183
  constructor();
184
  
185
  /**
186
   * Initialize with story index data
187
   * @param storyIndex - Complete story index
188
   */
189
  initialize(storyIndex: StoryIndex): void;
190
  
191
  /**
192
   * Get story entry by ID
193
   * @param storyId - Story identifier
194
   * @returns Story index entry or undefined
195
   */
196
  getStoryEntry(storyId: string): StoryIndexEntry | undefined;
197
  
198
  /**
199
   * Get all stories for a component
200
   * @param componentId - Component identifier
201
   * @returns Array of story entries
202
   */
203
  getStoriesForComponent(componentId: string): StoryIndexEntry[];
204
  
205
  /**
206
   * Search stories by title or ID
207
   * @param query - Search query
208
   * @returns Matching story entries
209
   */
210
  searchStories(query: string): StoryIndexEntry[];
211
}
212

213
interface StoryIndex {
214
  /** Version of the story index format */
215
  v: number;
216
  /** Map of story IDs to story entries */
217
  entries: Record<string, StoryIndexEntry>;
218
}
219

220
interface StoryIndexEntry {
221
  /** Unique story identifier */
222
  id: string;
223
  /** Display name of the story */
224
  name: string;
225
  /** Component title/path */
226
  title: string;
227
  /** Path to the story file */
228
  importPath: string;
229
  /** Story type (story or docs) */
230
  type: 'story' | 'docs';
231
  /** Story tags for filtering */
232
  tags?: string[];
233
}
234
```
235

236
### Story Loading & Caching
237

238
Functions and utilities for efficient story loading and caching.
239

240
```typescript { .api }
241
/**
242
 * Load CSF file and process its exports
243
 * @param importFn - Function to import the CSF file
244
 * @param importPath - Path to the CSF file
245
 * @param cache - Optional cache for loaded modules
246
 * @returns Processed CSF file with stories
247
 */
248
function loadCSFFile<TRenderer>(
249
  importFn: (path: string) => Promise<any>,
250
  importPath: string,
251
  cache?: Map<string, any>
252
): Promise<CSFFile<TRenderer>>;
253

254
interface CSFFile<TRenderer = any> {
255
  /** File metadata */
256
  meta: ComponentAnnotations<TRenderer>;
257
  /** Map of story names to story annotations */
258
  stories: Record<string, StoryAnnotations<TRenderer>>;
259
  /** Component being documented */
260
  component?: any;
261
  /** Module exports */
262
  moduleExports: any;
263
}
264
```
265

266
### Reporter API
267

268
System for collecting and reporting test results and story execution data.
269

270
```typescript { .api }
271
/**
272
 * API for collecting and reporting test results
273
 */
274
class ReporterAPI {
275
  constructor();
276
  
277
  /**
278
   * Report test results for a story
279
   * @param storyId - Story identifier
280
   * @param report - Test report data
281
   */
282
  report(storyId: string, report: Report): void;
283
  
284
  /**
285
   * Get all reports
286
   * @returns Map of story IDs to their reports
287
   */
288
  getReports(): Record<string, Report[]>;
289
  
290
  /**
291
   * Clear all reports
292
   */
293
  clearReports(): void;
294
}
295

296
interface Report<T = unknown> {
297
  /** Report type identifier */
298
  type: string;
299
  /** Report format version */
300
  version?: number;
301
  /** Report data payload */
302
  result: T;
303
  /** Execution status */
304
  status: 'failed' | 'passed' | 'warning';
305
  /** Error message if failed */
306
  message?: string;
307
  /** Timestamp of report creation */
308
  timestamp?: number;
309
}
310
```
311

312
**Usage Examples:**
313

314
```typescript
315
import { ReporterAPI } from "@storybook/preview-api";
316

317
const reporter = new ReporterAPI();
318

319
// Report test success
320
reporter.report('example-button--primary', {
321
  type: 'test-result',
322
  version: 1,
323
  result: { testsPassed: 5, testsTotal: 5 },
324
  status: 'passed'
325
});
326

327
// Report test failure
328
reporter.report('example-button--secondary', {
329
  type: 'test-result', 
330
  version: 1,
331
  result: { error: 'Assertion failed' },
332
  status: 'failed',
333
  message: 'Expected button to be disabled'
334
});
335

336
// Get all reports
337
const allReports = reporter.getReports();
338
console.log(allReports['example-button--primary']);
339
```
340

341
## Types & Interfaces
342

343
```typescript { .api }
344
interface Story<TRenderer = any> {
345
  /** Unique story identifier */
346
  id: string;
347
  /** Story display name */
348
  name: string;
349
  /** Component title */
350
  title: string;
351
  /** Story args */
352
  args: Args;
353
  /** Story arg types */
354
  argTypes: ArgTypes;
355
  /** Story parameters */
356
  parameters: Parameters;
357
  /** Component being rendered */
358
  component?: any;
359
  /** Story render function */
360
  renderFn: (args: Args, context: StoryContext<TRenderer>) => any;
361
  /** Play function for interactions */
362
  playFn?: (context: PlayFunctionContext<TRenderer>) => Promise<void> | void;
363
}
364

365
interface StoryContext<TRenderer = any> {
366
  /** Story identifier */
367
  id: string;
368
  /** Story name */
369
  name: string;
370
  /** Component title */
371
  title: string;
372
  /** Current story args */
373
  args: Args;
374
  /** Story arg types definition */
375
  argTypes: ArgTypes;
376
  /** Story parameters */
377
  parameters: Parameters;
378
  /** Global values */
379
  globals: Args;
380
  /** Hook execution context */
381
  hooks: HooksContext<TRenderer>;
382
  /** Current view mode */
383
  viewMode: 'story' | 'docs';
384
  /** Loaded data from loaders */
385
  loaded: Record<string, any>;
386
  /** Abort signal for cancellation */
387
  abortSignal: AbortSignal;
388
}
389

390
interface Args {
391
  [key: string]: any;
392
}
393

394
interface ArgTypes {
395
  [key: string]: ArgType;
396
}
397

398
interface Parameters {
399
  [key: string]: any;
400
}
401
```