React: Experimental code examples

code/.storybook/main.ts

@@ -138,6 +138,7 @@ const config = defineMain({
     developmentModeForBuild: true,
     experimentalTestSyntax: true,
     experimentalComponentsManifest: true,
+    experimentalCodeExamples: true,
   },
   staticDirs: [{ from: './bench/bundle-analyzer', to: '/bundle-analyzer' }],
   viteFinal: async (viteConfig, { configType }) => {

code/addons/docs/src/preset.ts

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
 
 import { logger } from 'storybook/internal/node-logger';
 import type { Options, PresetProperty, StorybookConfigRaw } from 'storybook/internal/types';
+import { type CsfEnricher } from 'storybook/internal/types';
 
 import type { CsfPluginOptions } from '@storybook/csf-plugin';
 
@@ -41,6 +42,8 @@ async function webpack(
 
   const { csfPluginOptions = {}, mdxPluginOptions = {} } = options;
 
+  const enrichCsf = await options.presets.apply('experimental_enrichCsf');
+
   const rehypeSlug = (await import('rehype-slug')).default;
   const rehypeExternalLinks = (await import('rehype-external-links')).default;
 
@@ -100,7 +103,12 @@ async function webpack(
       ...(webpackConfig.plugins || []),
 
       ...(csfPluginOptions
-        ? [(await import('@storybook/csf-plugin')).webpack(csfPluginOptions)]
+        ? [
+            (await import('@storybook/csf-plugin')).webpack({
+              ...csfPluginOptions,
+              enrichCsf,
+            }),
+          ]
         : []),
     ],
     resolve: {

code/builders/builder-vite/src/plugins/csf-plugin.ts

@@ -12,6 +12,11 @@ export async function csfPlugin(config: Options): Promise<Plugin> {
     // @ts-expect-error - not sure what type to use here
     addons.find((a) => [a, a.name].includes('@storybook/addon-docs'))?.options ?? {};
 
+  const enrichCsf = await presets.apply('experimental_enrichCsf');
+
   // TODO: looks like unplugin can return an array of plugins
-  return vite(docsOptions?.csfPluginOptions) as Plugin;
+  return vite({
+    ...docsOptions?.csfPluginOptions,
+    enrichCsf,
+  }) as Plugin;
 }

code/core/src/common/presets.ts

@@ -20,7 +20,7 @@ import { getInterpretedFile } from './utils/interpret-files';
 import { stripAbsNodeModulesPath } from './utils/strip-abs-node-modules-path';
 import { validateConfigurationFiles } from './utils/validate-configuration-files';
 
-type InterPresetOptions = Omit<
+export type InterPresetOptions = Omit<
   CLIOptions &
     LoadOptions &
     BuilderOptions & { isCritical?: boolean; build?: StorybookConfigRaw['build'] },
@@ -321,7 +321,7 @@ export async function getPresets(
   const loadedPresets: LoadedPreset[] = await loadPresets(presets, 0, storybookOptions);
 
   return {
-    apply: async (extension: string, config: any, args = {}) =>
+    apply: async (extension: string, config?: any, args = {}) =>
       applyPresets(loadedPresets, extension, config, args, storybookOptions),
   };
 }

code/core/src/common/utils/formatter.ts

@@ -1,4 +1,4 @@
-async function getPrettier() {
+export async function getPrettier() {
   return import('prettier').catch((e) => ({
     resolveConfig: async () => null,
     format: (content: string) => content,

code/core/src/csf-tools/enrichCsf.ts

@@ -1,10 +1,12 @@
 import { generate, types as t } from 'storybook/internal/babel';
+import { type CsfEnricher } from 'storybook/internal/types';
 
 import type { CsfFile } from './CsfFile';
 
 export interface EnrichCsfOptions {
   disableSource?: boolean;
   disableDescription?: boolean;
+  enrichCsf?: CsfEnricher;
 }
 
 export const enrichCsfStory = (
@@ -139,8 +141,9 @@ export const enrichCsfMeta = (csf: CsfFile, csfSource: CsfFile, options?: Enrich
   }
 };
 
-export const enrichCsf = (csf: CsfFile, csfSource: CsfFile, options?: EnrichCsfOptions) => {
+export const enrichCsf = async (csf: CsfFile, csfSource: CsfFile, options?: EnrichCsfOptions) => {
   enrichCsfMeta(csf, csfSource, options);
+  await options?.enrichCsf?.(csf, csfSource);
   Object.keys(csf._storyExports).forEach((key) => {
     enrichCsfStory(csf, csfSource, key, options);
   });

code/core/src/types/modules/core-common.ts

@@ -1,6 +1,7 @@
 // should be node:http, but that caused the ui/manager to fail to build, might be able to switch this back once ui/manager is in the core
 import type { FileSystemCache } from 'storybook/internal/common';
 import { type StoryIndexGenerator } from 'storybook/internal/core-server';
+import { type CsfFile } from 'storybook/internal/csf-tools';
 
 import type { Server as HttpServer, IncomingMessage, ServerResponse } from 'http';
 import type { Server as NetServer } from 'net';
@@ -106,6 +107,9 @@ export interface Presets {
     config?: StorybookConfigRaw['staticDirs'],
     args?: any
   ): Promise<StorybookConfigRaw['staticDirs']>;
+
+  /** The second and third parameter are not needed. And make type inference easier. */
+  apply<T extends keyof StorybookConfigRaw>(extension: T): Promise<StorybookConfigRaw[T]>;
   apply<T>(extension: string, config?: T, args?: unknown): Promise<T>;
 }
 
@@ -359,6 +363,8 @@ export type ComponentManifestGenerator = (
   storyIndexGenerator: StoryIndexGenerator
 ) => Promise<ComponentsManifest>;
 
+export type CsfEnricher = (csf: CsfFile, csfSource: CsfFile) => Promise<void>;
+
 export interface StorybookConfigRaw {
   /**
    * Sets the addons you want to use with Storybook.
@@ -373,6 +379,7 @@ export interface StorybookConfigRaw {
   addons?: Preset[];
   core?: CoreConfig;
   componentManifestGenerator?: ComponentManifestGenerator;
+  experimental_enrichCsf?: CsfEnricher;
   staticDirs?: (DirectoryMapping | string)[];
   logLevel?: string;
   features?: {
@@ -472,6 +479,19 @@ export interface StorybookConfigRaw {
     angularFilterNonInputControls?: boolean;
 
     experimentalComponentsManifest?: boolean;
+
+    /**
+     * Enables the new code example generation for React components. You can see those examples when
+     * clicking on the "Show code" button in the Storybook UI.
+     *
+     * We refactored the code examples by reading the actual source file. This should make the code
+     * examples a lot faster, more readable and more accurate. They are not dynamic though, it won't
+     * change if you change when using the control panel.
+     *
+     * @default false
+     * @experimental This feature is in early development and may change significantly in future releases.
+     */
+    experimentalCodeExamples?: boolean;
   };
 
   build?: TestBuildConfig;

code/lib/csf-plugin/src/rollup-based-plugin.ts

@@ -23,7 +23,7 @@ export function rollupBasedPlugin(options: EnrichCsfOptions): Partial<RollupPlug
         const csfSource = loadCsf(sourceCode, {
           makeTitle,
         }).parse();
-        enrichCsf(csf, csfSource, options);
+        await enrichCsf(csf, csfSource, options);
         const inputSourceMap = this.getCombinedSourcemap();
         return formatCsf(csf, { sourceMaps: true, inputSourceMap }, code);
       } catch (err: any) {

code/lib/csf-plugin/src/webpack-loader.ts

@@ -20,7 +20,7 @@ async function loader(this: LoaderContext, content: string, map: any) {
     const makeTitle = (userTitle: string) => userTitle || 'default';
     const csf = loadCsf(content, { makeTitle }).parse();
     const csfSource = loadCsf(sourceCode, { makeTitle }).parse();
-    enrichCsf(csf, csfSource, options);
+    await enrichCsf(csf, csfSource, options);
     const formattedCsf = formatCsf(
       csf,
       { sourceMaps: true, inputSourceMap: map, sourceFileName: id },

code/renderers/react/src/componentManifest/generator.test.ts

@@ -4,13 +4,13 @@ import { type StoryIndexGenerator } from 'storybook/internal/core-server';
 
 import { vol } from 'memfs';
 import { dedent } from 'ts-dedent';
-import * as TsconfigPaths from 'tsconfig-paths';
+import { loadConfig } from 'tsconfig-paths';
 
 import { componentManifestGenerator } from './generator';
 
-vi.mock('tsconfig-paths', { spy: true });
 vi.mock('node:fs/promises', async () => (await import('memfs')).fs.promises);
 vi.mock('node:fs', async () => (await import('memfs')).fs);
+vi.mock('tsconfig-paths', { spy: true });
 
 // Use the provided indexJson from this file
 const indexJson = {
@@ -95,10 +95,7 @@ const indexJson = {
 };
 
 beforeEach(() => {
-  vi.mocked(TsconfigPaths.loadConfig).mockImplementation(() => ({
-    resultType: null!,
-    message: null!,
-  }));
+  vi.mocked(loadConfig).mockImplementation(() => ({ resultType: null!, message: null! }));
   vi.spyOn(process, 'cwd').mockReturnValue('/app');
   vol.fromJSON(
     {

code/renderers/react/src/componentManifest/generator.ts

@@ -9,7 +9,7 @@ import { type ComponentManifest } from 'storybook/internal/types';
 import path from 'pathe';
 
 import { getCodeSnippet } from './generateCodeSnippet';
-import { extractJSDocTags, removeTags } from './jsdocTags';
+import { extractJSDocInfo } from './jsdocTags';
 import { type DocObj, getMatchingDocgen, parseWithReactDocgen } from './reactDocgen';
 import { groupBy } from './utils';
 
@@ -69,16 +69,14 @@ export const componentManifestGenerator = async () => {
 
         const metaDescription = extractDescription(csf._metaStatement);
         const jsdocComment = metaDescription || docgen?.description;
-        const tags = jsdocComment ? extractJSDocTags(jsdocComment) : {};
+        const { tags = {}, description } = jsdocComment ? extractJSDocInfo(jsdocComment) : {};
 
-        const manifestDescription = jsdocComment
-          ? removeTags(tags.describe?.[0] || tags.desc?.[0] || jsdocComment).trim()
-          : undefined;
+        const manifestDescription = (tags?.describe?.[0] || tags?.desc?.[0]) ?? description;
 
         return {
           id,
           name: componentName,
-          description: manifestDescription,
+          description: manifestDescription?.trim(),
           summary: tags.summary?.[0],
           import: tags.import?.[0],
           reactDocgen: docgen,

code/renderers/react/src/componentManifest/jsdocTags.test.ts

@@ -2,16 +2,19 @@ import { expect, it } from 'vitest';
 
 import { dedent } from 'ts-dedent';
 
-import { extractJSDocTags } from './jsdocTags';
+import { extractJSDocInfo } from './jsdocTags';
 
 it('should extract @summary tag', () => {
-  const code = dedent`@summary This is the summary`;
-  const tags = extractJSDocTags(code);
+  const code = dedent`description\n@summary\n my summary`;
+  const tags = extractJSDocInfo(code);
   expect(tags).toMatchInlineSnapshot(`
     {
-      "summary": [
-        "This is the summary",
-      ],
+      "description": "description",
+      "tags": {
+        "summary": [
+          " my summary",
+        ],
+      },
     }
   `);
 });
@@ -21,14 +24,17 @@ it('should extract @param tag with type', () => {
  @param {Object} employee - The employee who is responsible for the project.
  @param {string} employee.name - The name of the employee.
  @param {string} employee.department - The employee's department.`;
-  const tags = extractJSDocTags(code);
+  const tags = extractJSDocInfo(code);
   expect(tags).toMatchInlineSnapshot(`
     {
-      "param": [
-        "{Object} employee - The employee who is responsible for the project.",
-        "{string} employee.name - The name of the employee.",
-        "{string} employee.department - The employee's department.",
-      ],
+      "description": "",
+      "tags": {
+        "param": [
+          "{Object} employee - The employee who is responsible for the project.",
+          "{string} employee.name - The name of the employee.",
+          "{string} employee.department - The employee's department.",
+        ],
+      },
     }
   `);
 });

code/renderers/react/src/componentManifest/jsdocTags.ts

@@ -2,24 +2,21 @@ import { parse } from 'comment-parser';
 
 import { groupBy } from './utils';
 
-export function extractJSDocTags(jsdocComment: string) {
+export function extractJSDocInfo(jsdocComment: string) {
   const lines = jsdocComment.split('\n');
   const jsDoc = ['/**', ...lines.map((line) => ` * ${line}`), ' */'].join('\n');
 
   const parsed = parse(jsDoc);
 
-  return Object.fromEntries(
-    Object.entries(groupBy(parsed[0].tags, (it) => it.tag)).map(([key, tags]) => [
-      key,
-      tags?.map((tag) => (tag.type ? `{${tag.type}} ` : '') + `${tag.name} ${tag.description}`) ??
-        [],
-    ])
-  );
+  return {
+    description: parsed[0].description,
+    tags: Object.fromEntries(
+      Object.entries(groupBy(parsed[0].tags, (it) => it.tag)).map(([key, tags]) => [
+        key,
+        tags?.map((tag) => (tag.type ? `{${tag.type}} ` : '') + `${tag.name} ${tag.description}`) ??
+          [],
+      ])
+    ),
+  };
 }
 
-export function removeTags(jsdocComment: string) {
-  return jsdocComment
-    .split('\n')
-    .filter((line) => !line.trim().startsWith('@'))
-    .join('\n');
-}

code/renderers/react/src/docs/jsxDecorator.tsx

@@ -4,6 +4,7 @@ import React, { createElement, isValidElement } from 'react';
 import { logger } from 'storybook/internal/client-logger';
 import { SourceType, getDocgenSection } from 'storybook/internal/docs-tools';
 import type { PartialStoryFn, StoryContext } from 'storybook/internal/types';
+import { type StorybookConfigRaw } from 'storybook/internal/types';
 
 import type { Options } from 'react-element-to-jsx-string';
 import type reactElementToJSXStringType from 'react-element-to-jsx-string';