CSF Factories: Add parameters/globals types, extend API, portable stories

code/addons/a11y/src/index.ts

@@ -1,9 +1,10 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addonAnnotations from './preview';
+import type { A11yTypes } from './types';
 
 export { PARAM_KEY } from './constants';
 export * from './params';
-export type { A11yParameters } from './types';
+export type { A11yTypes } from './types';
 
-export default () => definePreview(addonAnnotations);
+export default () => definePreviewAddon<A11yTypes>(addonAnnotations);

code/addons/a11y/src/types.ts

@@ -19,7 +19,7 @@ export interface A11yGlobals {
    *
    * @see https://storybook.js.org/docs/writing-tests/accessibility-testing
    */
-  a11y: {
+  a11y?: {
     /**
      * Prevent the addon from executing automated accessibility checks upon visiting a story. You
      * can still trigger the checks from the addon panel.
@@ -51,3 +51,8 @@ export type EnhancedResults = Omit<AxeResults, 'incomplete' | 'passes' | 'violat
   passes: EnhancedResult[];
   violations: EnhancedResult[];
 };
+
+export interface A11yTypes {
+  parameters: A11yParameters;
+  globals: A11yGlobals;
+}

code/addons/docs/src/index.ts

@@ -1,11 +1,12 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addonAnnotations from './preview';
+import type { DocsTypes } from './types';
 
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore (these types only work once the package is compiled)
 export * from '@storybook/addon-docs/blocks';
 export { DocsRenderer } from './DocsRenderer';
-export type { DocsParameters } from './types';
+export type { DocsTypes };
 
-export default () => definePreview(addonAnnotations);
+export default () => definePreviewAddon<DocsTypes>(addonAnnotations);

code/addons/docs/src/types.ts

@@ -164,7 +164,7 @@ export interface DocsParameters {
      *
      * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-canvas
      */
-    canvas?: CanvasBlockParameters;
+    canvas?: Partial<CanvasBlockParameters>;
 
     /**
      * Controls block configuration
@@ -195,14 +195,14 @@ export interface DocsParameters {
      *
      * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-source
      */
-    source?: SourceBlockParameters;
+    source?: Partial<SourceBlockParameters>;
 
     /**
      * Story configuration
      *
      * @see https://storybook.js.org/docs/api/doc-blocks/doc-block-story
      */
-    story?: StoryBlockParameters;
+    story?: Partial<StoryBlockParameters>;
 
     /**
      * The subtitle displayed when shown in docs page
@@ -219,3 +219,7 @@ export interface DocsParameters {
     title?: string;
   };
 }
+
+export interface DocsTypes {
+  parameters: DocsParameters;
+}

code/addons/links/src/index.ts

@@ -1,7 +1,7 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addonAnnotations from './preview';
 
 export { linkTo, hrefTo, withLinks, navigate } from './utils';
 
-export default () => definePreview(addonAnnotations);
+export default () => definePreviewAddon(addonAnnotations);

code/addons/pseudo-states/src/index.ts

@@ -1,7 +1,7 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addonAnnotations from './preview';
 
 export { PARAM_KEY } from './constants';
 
-export default () => definePreview(addonAnnotations);
+export default () => definePreviewAddon(addonAnnotations);

code/addons/themes/src/index.ts

@@ -1,9 +1,10 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addonAnnotations from './preview';
+import type { ThemesTypes } from './types';
 
-export type { ThemesGlobals, ThemesParameters } from './types';
+export type { ThemesTypes } from './types';
 
-export default () => definePreview(addonAnnotations);
+export default () => definePreviewAddon<ThemesTypes>(addonAnnotations);
 
 export * from './decorators';

code/addons/themes/src/theme-switcher.tsx

@@ -17,7 +17,7 @@ import {
 } from './constants';
 import type { ThemesParameters as Parameters, ThemeAddonState } from './types';
 
-type ThemesParameters = Parameters['themes'];
+type ThemesParameters = NonNullable<Parameters['themes']>;
 
 const IconButtonLabel = styled.div(({ theme }) => ({
   fontSize: theme.typography.size.s2 - 1,

code/addons/themes/src/types.ts

@@ -9,7 +9,7 @@ export interface ThemesParameters {
    *
    * @see https://github.com/storybookjs/storybook/blob/next/code/addons/themes/README.md
    */
-  themes: {
+  themes?: {
     /** Remove the addon panel and disable the addon's behavior */
     disable?: boolean;
     /** Which theme to override for the story */
@@ -21,3 +21,8 @@ export interface ThemesGlobals {
   /** Which theme to override for the story */
   theme?: string;
 }
+
+export interface ThemesTypes {
+  parameters: ThemesParameters;
+  globals: ThemesGlobals;
+}

code/addons/vitest/src/index.ts

@@ -1,5 +1,3 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
-export default () => definePreview({});
-
-export type { TestParameters } from './types';
+export default () => definePreviewAddon({});

code/addons/vitest/src/types.ts

@@ -2,21 +2,6 @@ import type { experimental_UniversalStore } from 'storybook/internal/core-server
 import type { PreviewAnnotation, StoryId } from 'storybook/internal/types';
 import type { API_HashEntry } from 'storybook/internal/types';
 
-export interface TestParameters {
-  /**
-   * Test addon configuration
-   *
-   * @see https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon
-   */
-  test: {
-    /** Ignore unhandled errors during test execution */
-    dangerouslyIgnoreUnhandledErrors?: boolean;
-
-    /** Whether to throw exceptions coming from the play function */
-    throwPlayFunctionExceptions?: boolean;
-  };
-}
-
 export interface VitestError extends Error {
   VITEST_TEST_PATH?: string;
   VITEST_TEST_NAME?: string;

code/core/src/actions/index.ts

@@ -1,5 +1,3 @@
 export * from './constants';
 export * from './models';
 export * from './runtime';
-
-export type { ActionsParameters } from './types';

code/core/src/actions/preview.ts

@@ -1,10 +1,13 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import * as addArgs from './addArgs';
 import * as loaders from './loaders';
+import type { ActionsTypes } from './types';
+
+export { ActionsTypes };
 
 export default () =>
-  definePreview({
+  definePreviewAddon<ActionsTypes>({
     ...addArgs,
     ...loaders,
   });

code/core/src/actions/types.ts

@@ -4,7 +4,7 @@ export interface ActionsParameters {
    *
    * @see https://storybook.js.org/docs/essentials/actions#parameters
    */
-  actions: {
+  actions?: {
     /**
      * Create actions for each arg that matches the regex. (**NOT recommended, see below**)
      *
@@ -36,3 +36,7 @@ export interface ActionsParameters {
     handles?: string[];
   };
 }
+
+export interface ActionsTypes {
+  parameters: ActionsParameters;
+}

code/core/src/backgrounds/decorator.ts

@@ -24,7 +24,7 @@ export const withBackgroundAndGrid: DecoratorFunction = (StoryFn, context) => {
     options = DEFAULT_BACKGROUNDS,
     disable,
     grid = defaultGrid,
-  } = (parameters[PARAM_KEY] || {}) as BackgroundsParameters['backgrounds'];
+  } = (parameters[PARAM_KEY] || {}) as NonNullable<BackgroundsParameters['backgrounds']>;
   const data = globals[PARAM_KEY] || {};
   const backgroundName: string | undefined = typeof data === 'string' ? data : data?.value;
 

code/core/src/backgrounds/index.ts

@@ -1,5 +1 @@
-import addonAnnotations from './preview';
-
-export default addonAnnotations;
-
-export type { BackgroundsParameters, BackgroundsGlobals } from './types';
+export {};

code/core/src/backgrounds/preview.ts

@@ -1,8 +1,8 @@
-import { definePreview } from 'storybook/preview-api';
+import { definePreviewAddon } from 'storybook/internal/csf';
 
 import { PARAM_KEY } from './constants';
 import { withBackgroundAndGrid } from './decorator';
-import type { BackgroundsParameters, GlobalState } from './types';
+import type { BackgroundTypes, BackgroundsParameters, GlobalState } from './types';
 
 const decorators = globalThis.FEATURES?.backgrounds ? [withBackgroundAndGrid] : [];
 
@@ -21,8 +21,10 @@ const initialGlobals: Record<string, GlobalState> = {
   [PARAM_KEY]: { value: undefined, grid: false },
 };
 
+export type { BackgroundTypes };
+
 export default () =>
-  definePreview({
+  definePreviewAddon<BackgroundTypes>({
     decorators,
     parameters,
     initialGlobals,

code/core/src/backgrounds/types.ts

@@ -15,11 +15,19 @@ export interface GridConfig {
   offsetY?: number;
 }
 
-export type GlobalState = { value: string | undefined; grid: boolean };
+export type GlobalState = { value: string | undefined; grid?: boolean };
 export type GlobalStateUpdate = Partial<GlobalState>;
 
 export interface BackgroundsParameters {
-  [PARAM_KEY]: {
+  /**
+   * Backgrounds configuration
+   *
+   * @see https://storybook.js.org/docs/essentials/backgrounds#parameters
+   */
+  backgrounds?: {
+    /** Default background color */
+    default?: string;
+
     /** Remove the addon panel and disable the addon's behavior */
     disable?: boolean;
 
@@ -37,5 +45,10 @@ export interface BackgroundsGlobals {
    *
    * @see https://storybook.js.org/docs/essentials/backgrounds#globals
    */
-  [PARAM_KEY]: GlobalState | GlobalState['value'];
+  [PARAM_KEY]?: GlobalState | GlobalState['value'];
+}
+
+export interface BackgroundTypes {
+  parameters: BackgroundsParameters;
+  globals: BackgroundsGlobals;
 }

code/core/src/common/utils/get-addon-annotations.ts

@@ -23,26 +23,24 @@ export function getAnnotationsName(addonName: string): string {
   return cleanedUpName;
 }
 
-export async function getAddonAnnotations(addon: string) {
+export async function getAddonAnnotations(addon: string, configDir: string) {
+  const data = {
+    // core addons will have a function as default export in index entrypoint
+    importPath: addon,
+    importName: getAnnotationsName(addon),
+    isCoreAddon: isCorePackage(addon),
+  };
+
+  if (!data.isCoreAddon) {
+    // for backwards compatibility, if it's not a core addon we use /preview entrypoint
+    data.importPath = `${addon}/preview`;
+  }
+
+  // If the preview endpoint doesn't exist, we don't need to add the addon to definePreview
   try {
-    const data = {
-      // core addons will have a function as default export in index entrypoint
-      importPath: addon,
-      importName: getAnnotationsName(addon),
-      isCoreAddon: isCorePackage(addon),
-    };
-
-    if (addon === '@storybook/addon-essentials') {
-      return data;
-    } else if (!data.isCoreAddon) {
-      // for backwards compatibility, if it's not a core addon we use /preview entrypoint
-      data.importPath = `${addon}/preview`;
-    }
-
-    require.resolve(path.join(addon, 'preview'));
-
-    return data;
-  } catch (err) {}
-
-  return null;
+    require.resolve(path.join(addon, 'preview'), { paths: [configDir] });
+  } catch (err) {
+    return null;
+  }
+  return data;
 }

code/core/src/common/utils/sync-main-preview-addons.test.ts

@@ -22,6 +22,8 @@ describe('getSyncedStorybookAddons', () => {
     addons: ['custom-addon', '@storybook/addon-a11y'],
   };
 
+  const configDir = '/user/storybook/.storybook';
+
   it('should sync addons between main and preview', async () => {
     const preview = loadConfig(`
       import * as myAddonAnnotations from "custom-addon/preview";
@@ -36,7 +38,7 @@ describe('getSyncedStorybookAddons', () => {
       return { importName: 'addonA11yAnnotations', importPath: '@storybook/addon-a11y/preview' };
     });
 
-    const result = await getSyncedStorybookAddons(mainConfig, preview);
+    const result = await getSyncedStorybookAddons(mainConfig, preview, configDir);
     expect(printConfig(result).code).toMatchInlineSnapshot(`
       import * as addonA11yAnnotations from "@storybook/addon-a11y/preview";
       import * as myAddonAnnotations from "custom-addon/preview";
@@ -66,7 +68,7 @@ describe('getSyncedStorybookAddons', () => {
       };
     });
 
-    const result = await getSyncedStorybookAddons(mainConfig, preview);
+    const result = await getSyncedStorybookAddons(mainConfig, preview, configDir);
     expect(printConfig(result).code).toMatchInlineSnapshot(`
       import addonA11yAnnotations from "@storybook/addon-a11y";
       import * as myAddonAnnotations from "custom-addon/preview";
@@ -92,7 +94,7 @@ describe('getSyncedStorybookAddons', () => {
       return { importName: 'addonA11yAnnotations', importPath: '@storybook/addon-a11y/preview' };
     });
 
-    const result = await getSyncedStorybookAddons(mainConfig, preview);
+    const result = await getSyncedStorybookAddons(mainConfig, preview, configDir);
     expect(printConfig(result).code).toMatchInlineSnapshot(`
       import * as addonA11yAnnotations from "@storybook/addon-a11y/preview";
       import { definePreview } from "@storybook/react/preview";
@@ -122,7 +124,7 @@ describe('getSyncedStorybookAddons', () => {
       return { importName: 'addonA11yAnnotations', importPath: '@storybook/addon-a11y/preview' };
     });
 
-    const result = await getSyncedStorybookAddons(mainConfig, preview);
+    const result = await getSyncedStorybookAddons(mainConfig, preview, configDir);
     const transformedCode = normalizeLineBreaks(printConfig(result).code);
 
     expect(transformedCode).toMatch(originalCode);
@@ -144,7 +146,7 @@ describe('getSyncedStorybookAddons', () => {
       return { importName: 'addonA11yAnnotations', importPath: '@storybook/addon-a11y/preview' };
     });
 
-    const result = await getSyncedStorybookAddons(mainConfig, preview);
+    const result = await getSyncedStorybookAddons(mainConfig, preview, configDir);
     const transformedCode = normalizeLineBreaks(printConfig(result).code);
 
     expect(transformedCode).toMatch(originalCode);