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

@@ -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

@@ -106,6 +106,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 +362,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 +378,7 @@ export interface StorybookConfigRaw {
   addons?: Preset[];
   core?: CoreConfig;
   componentManifestGenerator?: ComponentManifestGenerator;
+  experimental_enrichCsf?: CsfEnricher;
   staticDirs?: (DirectoryMapping | string)[];
   logLevel?: string;
   features?: {
@@ -472,6 +478,14 @@ export interface StorybookConfigRaw {
     angularFilterNonInputControls?: boolean;
 
     experimentalComponentsManifest?: boolean;
+    /**
+     * @experimental This feature is experimental and may change in future versions.
+     * 
+     * Enable experimental code examples generation for components.
+     * 
+     * @default false
+     */
+    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/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';
@@ -231,6 +232,9 @@ const mdxToJsx = (node: any) => {
   return createElement(originalType, rest, ...jsxChildren);
 };
 
+// eslint-disable-next-line no-var
+declare var FEATURES: NonNullable<StorybookConfigRaw['features']>;
+
 export const jsxDecorator = (
   storyFn: PartialStoryFn<ReactRenderer>,
   context: StoryContext<ReactRenderer>

code/renderers/react/src/enrichCsf.ts

@@ -0,0 +1,97 @@
+import { type NodePath, recast, types as t } from 'storybook/internal/babel';
+import { getPrettier } from 'storybook/internal/common';
+import { type CsfFile } from 'storybook/internal/csf-tools';
+import type { PresetPropertyFn } from 'storybook/internal/types';
+
+import { join } from 'pathe';
+import invariant from 'tiny-invariant';
+
+import { getCodeSnippet } from './componentManifest/generateCodeSnippet';
+
+export const enrichCsf: PresetPropertyFn<'experimental_enrichCsf'> = async (input, options) => {
+  const features = await options.presets.apply('features');
+  if (!features.experimentalCodeExamples) {
+    return;
+  }
+  return async (csf: CsfFile, csfSource: CsfFile) => {
+    await Promise.all(
+      Object.entries(csf._storyPaths).map(async ([key, storyExport]) => {
+        if (csfSource._meta?.component) {
+          const { format } = await getPrettier();
+
+          const code = recast.print(
+            getCodeSnippet(storyExport, csfSource._metaNode, csfSource._meta?.component)
+          ).code;
+
+          // TODO read the user config
+          const snippet = await format(code, { filepath: join(process.cwd(), 'component.tsx') });
+
+          const declaration = storyExport.get('declaration') as NodePath<t.Declaration>;
+          invariant(declaration.isVariableDeclaration(), 'Expected variable declaration');
+
+          const declarator = declaration.get('declarations')[0] as NodePath<t.VariableDeclarator>;
+          const init = declarator.get('init') as NodePath<t.Expression>;
+          invariant(init.isExpression(), 'Expected story initializer to be an expression');
+
+          const parameters = [];
+          const isCsfFactory =
+            t.isCallExpression(init.node) &&
+            t.isMemberExpression(init.node.callee) &&
+            t.isIdentifier(init.node.callee.object) &&
+            init.node.callee.object.name === 'meta';
+
+          // in csf 1/2/3 use Story.parameters; CSF factories use Story.input.parameters
+          const baseStoryObject = isCsfFactory
+            ? t.memberExpression(t.identifier(key), t.identifier('input'))
+            : t.identifier(key);
+
+          const originalParameters = t.memberExpression(
+            baseStoryObject,
+            t.identifier('parameters')
+          );
+          parameters.push(t.spreadElement(originalParameters));
+          const optionalDocs = t.optionalMemberExpression(
+            originalParameters,
+            t.identifier('docs'),
+            false,
+            true
+          );
+          const extraDocsParameters = [];
+
+          if (snippet) {
+            const optionalSource = t.optionalMemberExpression(
+              optionalDocs,
+              t.identifier('source'),
+              false,
+              true
+            );
+
+            extraDocsParameters.push(
+              t.objectProperty(
+                t.identifier('source'),
+                t.objectExpression([
+                  t.objectProperty(t.identifier('code'), t.stringLiteral(snippet)),
+                  t.spreadElement(optionalSource),
+                ])
+              )
+            );
+          }
+
+          // docs: { description: { story: %%description%% } },
+          if (extraDocsParameters.length > 0) {
+            parameters.push(
+              t.objectProperty(
+                t.identifier('docs'),
+                t.objectExpression([t.spreadElement(optionalDocs), ...extraDocsParameters])
+              )
+            );
+            const addParameter = t.expressionStatement(
+              t.assignmentExpression('=', originalParameters, t.objectExpression(parameters))
+            );
+            csf._ast.program.body.push(addParameter);
+          }
+        }
+      })
+    );
+  };
+};

code/renderers/react/src/entry-preview-docs.ts

@@ -1,9 +1,15 @@
 import type { DecoratorFunction } from 'storybook/internal/types';
+import type { StorybookConfigRaw } from 'storybook/internal/types';
 
 import { jsxDecorator } from './docs/jsxDecorator';
 import type { ReactRenderer } from './types';
 
-export const decorators: DecoratorFunction<ReactRenderer>[] = [jsxDecorator];
+// eslint-disable-next-line no-var
+declare var FEATURES: NonNullable<StorybookConfigRaw['features']>;
+
+export const decorators: DecoratorFunction<ReactRenderer>[] = FEATURES.experimentalCodeExamples
+  ? []
+  : [jsxDecorator];
 
 export { applyDecorators } from './docs/applyDecorators';
 

code/renderers/react/src/preset.ts

@@ -10,6 +10,8 @@ export const addons: PresetProperty<'addons'> = [
 
 export { componentManifestGenerator as experimental_componentManifestGenerator } from './componentManifest/generator';
 
+export { enrichCsf as experimental_enrichCsf } from './enrichCsf';
+
 export const previewAnnotations: PresetProperty<'previewAnnotations'> = async (
   input = [],
   options