React: Extract jsdoc tags in component manifest

code/core/src/core-server/build-static.ts

@@ -1,4 +1,4 @@
-import { cp, mkdir } from 'node:fs/promises';
+import { cp, mkdir, writeFile } from 'node:fs/promises';
 import { rm } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
 
@@ -18,6 +18,7 @@ import { global } from '@storybook/global';
 import picocolors from 'picocolors';
 
 import { resolvePackageDir } from '../shared/utils/module';
+import { type ComponentManifestGenerator } from '../types';
 import { StoryIndexGenerator } from './utils/StoryIndexGenerator';
 import { buildOrThrow } from './utils/build-or-throw';
 import { copyAllStaticFilesRelativeToMain } from './utils/copy-all-static-files';
@@ -163,6 +164,23 @@ export async function buildStaticStandalone(options: BuildStaticStandaloneOption
         initializedStoryIndexGenerator as Promise<StoryIndexGenerator>
       )
     );
+
+    const features = await presets.apply('features');
+
+    if (features?.experimental_componentsManifest) {
+      const componentManifestGenerator: ComponentManifestGenerator = await presets.apply(
+        'componentManifestGenerator'
+      );
+      const indexGenerator = await initializedStoryIndexGenerator;
+      if (componentManifestGenerator && indexGenerator) {
+        const manifests = await componentManifestGenerator(indexGenerator);
+        await mkdir(join(options.outputDir, 'manifests'), { recursive: true });
+        await writeFile(
+          join(options.outputDir, 'manifests', 'components.json'),
+          JSON.stringify(manifests)
+        );
+      }
+    }
   }
 
   if (!core?.disableProjectJson) {

code/core/src/core-server/dev-server.ts

@@ -8,6 +8,7 @@ import polka from 'polka';
 import invariant from 'tiny-invariant';
 
 import { telemetry } from '../telemetry';
+import { type ComponentManifestGenerator } from '../types';
 import type { StoryIndexGenerator } from './utils/StoryIndexGenerator';
 import { doTelemetry } from './utils/doTelemetry';
 import { getManagerBuilder, getPreviewBuilder } from './utils/get-builders';
@@ -135,6 +136,32 @@ export async function storybookDevServer(options: Options) {
     throw indexError;
   }
 
+  app.use('/manifests/components.json', async (req, res) => {
+    try {
+      const features = await options.presets.apply('features');
+      if (!features?.experimental_componentsManifest) {
+        const componentManifestGenerator: ComponentManifestGenerator = await options.presets.apply(
+          'componentManifestGenerator'
+        );
+        const indexGenerator = await initializedStoryIndexGenerator;
+        if (componentManifestGenerator && indexGenerator) {
+          const manifest = await componentManifestGenerator(indexGenerator);
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify(manifest));
+          return;
+        }
+      }
+      res.statusCode = 400;
+      res.end('No component manifest generator configured.');
+      return;
+    } catch (e) {
+      logger.error(e instanceof Error ? e : String(e));
+      res.statusCode = 500;
+      res.end(e instanceof Error ? e.toString() : String(e));
+      return;
+    }
+  });
+
   // Now the preview has successfully started, we can count this as a 'dev' event.
   doTelemetry(app, core, initializedStoryIndexGenerator, options);
 

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

@@ -295,7 +295,7 @@ export class CsfFile {
 
   _metaStatement: t.Statement | undefined;
 
-  _metaNode: t.Expression | undefined;
+  _metaNode: t.ObjectExpression | undefined;
 
   _metaPath: NodePath<t.ExportDefaultDeclaration> | undefined;
 

code/core/src/preview-api/modules/preview-web/render/mount-utils.ts

@@ -1,14 +1,10 @@
 // Inspired by Vitest fixture implementation:
 // https://github.com/vitest-dev/vitest/blob/200a4349a2f85686bc7005dce686d9d1b48b84d2/packages/runner/src/fixture.ts
-import type { PlayFunction } from 'storybook/internal/csf';
-import { type Renderer } from 'storybook/internal/types';
-
-export function mountDestructured<TRenderer extends Renderer>(
-  playFunction?: PlayFunction<TRenderer>
-): boolean {
+export function mountDestructured(playFunction?: (...args: any[]) => any): boolean {
   return playFunction != null && getUsedProps(playFunction).includes('mount');
 }
-export function getUsedProps(fn: Function) {
+
+export function getUsedProps(fn: (...args: any[]) => any) {
   const match = fn.toString().match(/[^(]*\(([^)]*)/);
 
   if (!match) {

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

@@ -6,6 +6,7 @@ import type { Server as NetServer } from 'net';
 import type { Options as TelejsonOptions } from 'telejson';
 import type { PackageJson as PackageJsonFromTypeFest } from 'type-fest';
 
+import { type StoryIndexGenerator } from '../../core-server';
 import type { Indexer, StoriesEntry } from './indexer';
 
 /** ⚠️ This file contains internal WIP types they MUST NOT be exported outside this package for now! */
@@ -343,6 +344,17 @@ export type TagsOptions = Record<Tag, Partial<TagOptions>>;
  * The interface for Storybook configuration used internally in presets The difference is that these
  * values are the raw values, AKA, not wrapped with `PresetValue<>`
  */
+
+export interface ComponentManifest {
+  id: string;
+  name?: string;
+  examples: { name: string; snippet: string }[];
+}
+
+export type ComponentManifestGenerator = (
+  storyIndexGenerator: StoryIndexGenerator
+) => Promise<Record<string, ComponentManifest>>;
+
 export interface StorybookConfigRaw {
   /**
    * Sets the addons you want to use with Storybook.
@@ -356,6 +368,7 @@ export interface StorybookConfigRaw {
    */
   addons?: Preset[];
   core?: CoreConfig;
+  componentManifestGenerator?: ComponentManifestGenerator;
   staticDirs?: (DirectoryMapping | string)[];
   logLevel?: string;
   features?: {
@@ -453,6 +466,8 @@ export interface StorybookConfigRaw {
     developmentModeForBuild?: boolean;
     /** Only show input controls in Angular */
     angularFilterNonInputControls?: boolean;
+
+    experimental_componentsManifest?: boolean;
   };
 
   build?: TestBuildConfig;

code/core/src/types/modules/indexer.ts

@@ -70,6 +70,7 @@ export interface BaseIndexEntry {
   title: ComponentTitle;
   tags?: Tag[];
   importPath: Path;
+  componentPath?: Path;
 }
 export type StoryIndexEntry = BaseIndexEntry & {
   type: 'story';

code/renderers/react/__mocks__/fs/promises.cjs

@@ -0,0 +1,3 @@
+const { fs } = require('memfs');
+
+module.exports = fs.promises;

code/renderers/react/package.json

@@ -66,6 +66,7 @@
     "acorn-jsx": "^5.3.1",
     "acorn-walk": "^7.2.0",
     "babel-plugin-react-docgen": "^4.2.1",
+    "comment-parser": "^1.4.1",
     "es-toolkit": "^1.36.0",
     "escodegen": "^2.1.0",
     "expect-type": "^0.15.0",

code/renderers/react/src/component-manifest/docgen-handlers/actualNameHandler.ts

@@ -0,0 +1,56 @@
+/**
+ * This is heavily based on the react-docgen `displayNameHandler`
+ * (https://github.com/reactjs/react-docgen/blob/26c90c0dd105bf83499a83826f2a6ff7a724620d/src/handlers/displayNameHandler.ts)
+ * but instead defines an `actualName` property on the generated docs that is taken first from the
+ * component's actual name. This addresses an issue where the name that the generated docs are
+ * stored under is incorrectly named with the `displayName` and not the component's actual name.
+ *
+ * This is inspired by `actualNameHandler` from
+ * https://github.com/storybookjs/babel-plugin-react-docgen, but is modified directly from
+ * displayNameHandler, using the same approach as babel-plugin-react-docgen.
+ */
+import type { Handler, NodePath, babelTypes as t } from 'react-docgen';
+import { utils } from 'react-docgen';
+
+const { getNameOrValue, isReactForwardRefCall } = utils;
+
+const actualNameHandler: Handler = function actualNameHandler(documentation, componentDefinition) {
+  documentation.set('definedInFile', componentDefinition.hub.file.opts.filename);
+
+  if (
+    (componentDefinition.isClassDeclaration() || componentDefinition.isFunctionDeclaration()) &&
+    componentDefinition.has('id')
+  ) {
+    documentation.set(
+      'actualName',
+      getNameOrValue(componentDefinition.get('id') as NodePath<t.Identifier>)
+    );
+  } else if (
+    componentDefinition.isArrowFunctionExpression() ||
+    componentDefinition.isFunctionExpression() ||
+    isReactForwardRefCall(componentDefinition)
+  ) {
+    let currentPath: NodePath = componentDefinition;
+
+    while (currentPath.parentPath) {
+      if (currentPath.parentPath.isVariableDeclarator()) {
+        documentation.set('actualName', getNameOrValue(currentPath.parentPath.get('id')));
+        return;
+      }
+      if (currentPath.parentPath.isAssignmentExpression()) {
+        const leftPath = currentPath.parentPath.get('left');
+
+        if (leftPath.isIdentifier() || leftPath.isLiteral()) {
+          documentation.set('actualName', getNameOrValue(leftPath));
+          return;
+        }
+      }
+
+      currentPath = currentPath.parentPath;
+    }
+    // Could not find an actual name
+    documentation.set('actualName', '');
+  }
+};
+
+export default actualNameHandler;

code/renderers/react/src/component-manifest/docgen-resolver.ts

@@ -0,0 +1,75 @@
+import { extname } from 'node:path';
+
+import resolve from 'resolve';
+
+export class ReactDocgenResolveError extends Error {
+  // the magic string that react-docgen uses to check if a module is ignored
+  readonly code = 'MODULE_NOT_FOUND';
+
+  constructor(filename: string) {
+    super(`'${filename}' was ignored by react-docgen.`);
+  }
+}
+
+/* The below code was copied from:
+ * https://github.com/reactjs/react-docgen/blob/df2daa8b6f0af693ecc3c4dc49f2246f60552bcb/packages/react-docgen/src/importer/makeFsImporter.ts#L14-L63
+ * because it wasn't exported from the react-docgen package.
+ * watch out: when updating this code, also update the code in code/presets/react-webpack/src/loaders/docgen-resolver.ts
+ */
+
+// These extensions are sorted by priority
+// resolve() will check for files in the order these extensions are sorted
+export const RESOLVE_EXTENSIONS = [
+  '.js',
+  '.cts', // These were originally not in the code, I added them
+  '.mts', // These were originally not in the code, I added them
+  '.ctsx', // These were originally not in the code, I added them
+  '.mtsx', // These were originally not in the code, I added them
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+  '.jsx',
+];
+
+export function defaultLookupModule(filename: string, basedir: string): string {
+  const resolveOptions = {
+    basedir,
+    extensions: RESOLVE_EXTENSIONS,
+    // we do not need to check core modules as we cannot import them anyway
+    includeCoreModules: false,
+  };
+
+  try {
+    return resolve.sync(filename, resolveOptions);
+  } catch (error) {
+    const ext = extname(filename);
+    let newFilename: string;
+
+    // if we try to import a JavaScript file it might be that we are actually pointing to
+    // a TypeScript file. This can happen in ES modules as TypeScript requires to import other
+    // TypeScript files with .js extensions
+    // https://www.typescriptlang.org/docs/handbook/esm-node.html#type-in-packagejson-and-new-extensions
+    switch (ext) {
+      case '.js':
+      case '.mjs':
+      case '.cjs':
+        newFilename = `${filename.slice(0, -2)}ts`;
+        break;
+
+      case '.jsx':
+        newFilename = `${filename.slice(0, -3)}tsx`;
+        break;
+      default:
+        throw error;
+    }
+
+    return resolve.sync(newFilename, {
+      ...resolveOptions,
+      // we already know that there is an extension at this point, so no need to check other extensions
+      extensions: [],
+    });
+  }
+}