Merge pull request storybookjs#35323 from storybookjs/fix/preview-core-annotations

Core: Compose core annotations before preview beforeAll

Author: ndelangen

code/core/src/preview-api/modules/preview-web/Preview.tsx

@@ -45,7 +45,7 @@ import type {
 
 import { global } from '@storybook/global';
 
-import { StoryStore } from '../../store.ts';
+import { StoryStore, composeProjectAnnotationsWithCore } from '../../store.ts';
 import { addons } from '../addons/index.ts';
 import type { CsfDocsRender } from './render/CsfDocsRender.ts';
 import type { MdxDocsRender } from './render/MdxDocsRender.ts';
@@ -154,7 +154,14 @@ export class Preview<TRenderer extends Renderer> {
 
   async getProjectAnnotationsOrRenderError(): Promise<ProjectAnnotations<TRenderer>> {
     try {
-      const projectAnnotations = await this.getProjectAnnotations();
+      // Compose the core annotations in here (the same way the store and portable stories do) so the
+      // `beforeAll` hooks they contribute — e.g. registering the `core/docgen` and `core/story-docs`
+      // services in the preview — run at init. Plain (CSF1-3) previews don't fold core annotations
+      // into `getProjectAnnotations()`, and core annotations would otherwise only be prepended later,
+      // inside the store, which is too late for the `beforeAll` we run below.
+      const projectAnnotations = composeProjectAnnotationsWithCore<TRenderer>([
+        await this.getProjectAnnotations(),
+      ]);
 
       this.renderToCanvas = projectAnnotations.renderToCanvas;
 

code/core/src/preview-api/modules/preview-web/PreviewWeb.test.ts

@@ -3627,9 +3627,11 @@ describe('PreviewWeb', () => {
       await waitForRender();
 
       // @ts-expect-error Ignore protected property
-      expect((preview.storyStoreValue as StoryStore<Renderer>)!.userGlobals.get()).toEqual({
-        a: 'edited',
-      });
+      expect((preview.storyStoreValue as StoryStore<Renderer>)!.userGlobals.get()).toEqual(
+        expect.objectContaining({
+          a: 'edited',
+        })
+      );
     });
 
     it('emits SET_GLOBALS with new values', async () => {
@@ -3642,7 +3644,7 @@ describe('PreviewWeb', () => {
 
       await waitForEvents([SET_GLOBALS]);
       expect(mockChannel.emit).toHaveBeenCalledWith(SET_GLOBALS, {
-        globals: { a: 'edited' },
+        globals: expect.objectContaining({ a: 'edited' }),
         globalTypes: {},
       });
     });
@@ -3707,7 +3709,7 @@ describe('PreviewWeb', () => {
         expect.objectContaining({
           storyContext: expect.objectContaining({
             args: { foo: 'a', one: 'mapped-1', global: 'added' },
-            globals: { a: 'edited' },
+            globals: expect.objectContaining({ a: 'edited' }),
           }),
         }),
         'story-element'

code/core/src/preview-api/modules/store/StoryStore.ts

@@ -1,5 +1,4 @@
 import type { CleanupCallback } from 'storybook/internal/csf';
-import { getCoreAnnotations, hasCoreAnnotations } from 'storybook/internal/csf';
 import {
   CalledExtractOnStoreError,
   MissingStoryFromCsfFileError,
@@ -28,7 +27,7 @@ import { ArgsStore } from './ArgsStore.ts';
 import { GlobalsStore } from './GlobalsStore.ts';
 import { StoryIndexStore } from './StoryIndexStore.ts';
 import {
-  composeConfigs,
+  composeProjectAnnotationsWithCore,
   normalizeProjectAnnotations,
   prepareContext,
   prepareMeta,
@@ -45,20 +44,13 @@ export function picky<T extends Record<string, any>, K extends keyof T>(
 }
 
 /**
- * Compose and normalize the project annotations for the store, prepending the core annotations.
- *
- * CSF4 previews (created with `definePreview`) already compose the core annotations into their
- * `composed` result and flag it via {@link hasCoreAnnotations}. In that case we must NOT prepend
- * core annotations again, otherwise every core decorator/loader/beforeEach/beforeAll would run
- * twice for non-factory (CSF1/2/3) stories that fall back to `store.projectAnnotations`.
+ * Compose and normalize the project annotations for the store, prepending the core annotations via
+ * {@link composeProjectAnnotationsWithCore} (CSF4 previews are detected and not double-composed).
  */
 function composeProjectAnnotations<TRenderer extends Renderer>(
   projectAnnotations: ProjectAnnotations<TRenderer>
 ): NormalizedProjectAnnotations<TRenderer> {
-  if (hasCoreAnnotations(projectAnnotations)) {
-    return normalizeProjectAnnotations(projectAnnotations);
-  }
-  return normalizeProjectAnnotations(composeConfigs([...getCoreAnnotations(), projectAnnotations]));
+  return normalizeProjectAnnotations(composeProjectAnnotationsWithCore([projectAnnotations]));
 }
 
 // TODO -- what are reasonable values for these?

code/core/src/preview-api/modules/store/csf/composeProjectAnnotationsWithCore.ts

@@ -0,0 +1,46 @@
+import {
+  getCoreAnnotations,
+  hasCoreAnnotations,
+  markAsComposedWithCoreAnnotations,
+} from 'storybook/internal/csf';
+import type {
+  ModuleExports,
+  NormalizedProjectAnnotations,
+  Renderer,
+} from 'storybook/internal/types';
+
+import { composeConfigs } from './composeConfigs.ts';
+
+/**
+ * Composes project annotations together, prepending Storybook's core annotations unless they are
+ * already present, and flags the result via {@link markAsComposedWithCoreAnnotations} so later
+ * composition does not add them a second time.
+ *
+ * Core annotations carry behavior that must be applied exactly once per realm: decorators, loaders,
+ * `beforeEach`, and the `beforeAll` hooks that register the built-in open services (`core/docgen`,
+ * `core/story-docs`). CSF4 previews (`definePreview`) already fold the core annotations into their
+ * `composed` result and mark it; plain CSF1-3 previews do not. Every entrypoint that runs `beforeAll`
+ * or builds the story store off the raw project annotations (the browser preview, the store, and
+ * portable stories) funnels them through here so the behavior is identical across all of them.
+ *
+ * Pass the *raw* annotation modules (not pre-composed) so the CSF4 marker survives the
+ * `hasCoreAnnotations` check. The result is composed but NOT normalized — callers that need a
+ * {@link NormalizedProjectAnnotations} should run `normalizeProjectAnnotations` on top.
+ */
+export function composeProjectAnnotationsWithCore<TRenderer extends Renderer = Renderer>(
+  annotations: ModuleExports[]
+): NormalizedProjectAnnotations<TRenderer> {
+  // Drop falsy entries (e.g. `setProjectAnnotations(undefined)` or a sparse array): `composeConfigs`
+  // reads `.default` off each entry and would throw on `null`/`undefined`.
+  const definedAnnotations = annotations.filter(Boolean);
+  const alreadyComposedWithCore = definedAnnotations.some((annotation) =>
+    hasCoreAnnotations(annotation)
+  );
+  return markAsComposedWithCoreAnnotations(
+    composeConfigs<TRenderer>(
+      alreadyComposedWithCore
+        ? definedAnnotations
+        : [...getCoreAnnotations(), ...definedAnnotations]
+    )
+  );
+}

code/core/src/preview-api/modules/store/csf/index.ts

@@ -7,6 +7,7 @@ export * from './normalizeProjectAnnotations.ts';
 export * from './normalizeArrays.ts';
 export * from './getValuesFromGlobalTypes.ts';
 export * from './composeConfigs.ts';
+export * from './composeProjectAnnotationsWithCore.ts';
 export * from './stepRunners.ts';
 export * from './portable-stories.ts';
 export * from './csf-factory-utils.ts';

code/core/src/preview-api/modules/store/csf/portable-stories.ts

@@ -1,5 +1,4 @@
 import { type CleanupCallback, isExportStory } from 'storybook/internal/csf';
-import { getCoreAnnotations, hasCoreAnnotations } from 'storybook/internal/csf';
 import { MountMustBeDestructuredError } from 'storybook/internal/preview-errors';
 import type {
   Args,
@@ -31,6 +30,7 @@ import {
 } from '../../preview-web/render/animation-utils.ts';
 import { ReporterAPI } from '../reporter-api.ts';
 import { composeConfigs } from './composeConfigs.ts';
+import { composeProjectAnnotationsWithCore } from './composeProjectAnnotationsWithCore.ts';
 import { getCsfFactoryAnnotations } from './csf-factory-utils.ts';
 import { getValuesFromGlobalTypes } from './getValuesFromGlobalTypes.ts';
 import { normalizeComponentAnnotations } from './normalizeComponentAnnotations.ts';
@@ -56,34 +56,19 @@ export function setDefaultProjectAnnotations<TRenderer extends Renderer = Render
 const DEFAULT_STORY_TITLE = 'ComposedStory';
 const DEFAULT_STORY_NAME = 'Unnamed Story';
 
-function extractAnnotation<TRenderer extends Renderer = Renderer>(
-  annotation: NamedOrDefaultProjectAnnotations<TRenderer>
-) {
-  if (!annotation) {
-    return {};
-  }
-  // support imports such as
-  // import * as annotations from '.storybook/preview'
-  // import annotations from '.storybook/preview'
-  // in both cases: 1 - the file has a default export; 2 - named exports only
-  // also support when the file has both annotations coming from default and named exports
-  return composeConfigs([annotation]);
-}
-
 export function setProjectAnnotations<TRenderer extends Renderer = Renderer>(
   projectAnnotations:
     | NamedOrDefaultProjectAnnotations<TRenderer>
     | NamedOrDefaultProjectAnnotations<TRenderer>[]
 ): NormalizedProjectAnnotations<TRenderer> {
   const annotations = Array.isArray(projectAnnotations) ? projectAnnotations : [projectAnnotations];
-  // CSF4 previews (definePreview) already compose the core annotations into their `composed`
-  // result, which is what e.g. addon-vitest passes here via `getProjectAnnotations()`. Detect that
-  // marker and skip prepending core annotations so they are not applied twice.
-  const alreadyComposedWithCore = annotations.some((annotation) => hasCoreAnnotations(annotation));
-  globalThis.globalProjectAnnotations = composeConfigs([
-    ...(alreadyComposedWithCore ? [] : getCoreAnnotations()),
+  // Pass the raw annotation modules (which may use `default` and/or named exports, e.g. from
+  // `import * as annotations from '.storybook/preview'`) straight through: `composeConfigs` unwraps
+  // those, and `composeProjectAnnotationsWithCore` detects the CSF4 marker (set by `definePreview`,
+  // which is what e.g. addon-vitest passes here) so core annotations are never applied twice.
+  globalThis.globalProjectAnnotations = composeProjectAnnotationsWithCore<TRenderer>([
     globalThis.defaultProjectAnnotations ?? {},
-    composeConfigs(annotations.map(extractAnnotation)),
+    ...annotations,
   ]);
 
   return globalThis.globalProjectAnnotations ?? {};