CSF-tools: Turn story comments into docs descriptions

code/addons/docs/template/stories/docspage/basic.stories.ts

@@ -7,15 +7,24 @@ export default {
   parameters: { chromatic: { disable: true } },
 };
 
+/**
+ * A basic button
+ */
 export const Basic = {
   args: { label: 'Basic' },
 };
 
+/**
+ * Won't show up in DocsPage
+ */
 export const Disabled = {
   args: { label: 'Disabled in DocsPage' },
   parameters: { docs: { disable: true } },
 };
 
+/**
+ * Another button, just to show multiple stories
+ */
 export const Another = {
   args: { label: 'Another' },
 };

code/lib/csf-tools/package.json

@@ -51,7 +51,6 @@
   "devDependencies": {
     "@babel/generator": "^7.12.11",
     "@babel/parser": "^7.12.11",
-    "@babel/template": "^7.12.11",
     "@babel/traverse": "^7.12.11",
     "@types/fs-extra": "^9.0.6",
     "js-yaml": "^3.14.1",

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

@@ -156,6 +156,8 @@ export class CsfFile {
 
   _storyExports: Record<string, t.VariableDeclarator | t.FunctionDeclaration> = {};
 
+  _storyStatements: Record<string, t.ExportNamedDeclaration> = {};
+
   _storyAnnotations: Record<string, Record<string, t.Node>> = {};
 
   _templates: Record<string, t.Expression> = {};
@@ -283,6 +285,7 @@ export class CsfFile {
                   return;
                 }
                 self._storyExports[exportName] = decl;
+                self._storyStatements[exportName] = node;
                 let name = storyNameFromExport(exportName);
                 if (self._storyAnnotations[exportName]) {
                   logger.warn(

code/lib/csf-tools/src/enrichCsf.test.ts

@@ -125,6 +125,122 @@ describe('enrichCsf', () => {
       `);
     });
   });
+
+  describe('descriptions', () => {
+    it('skips inline comments', () => {
+      expect(
+        enrich(dedent`
+          export default {
+           title: 'Button',
+          }
+          // The most basic button
+          export const Basic = () => <Button />
+        `)
+      ).toMatchInlineSnapshot(`
+        export default {
+          title: 'Button'
+        };
+        // The most basic button
+        export const Basic = () => <Button />;
+        Basic.parameters = {
+          storySource: {
+            source: "() => <Button />"
+          },
+          ...Basic.parameters
+        };
+      `);
+    });
+
+    it('skips blocks without jsdoc', () => {
+      expect(
+        enrich(dedent`
+          export default {
+           title: 'Button',
+          }
+          /* The most basic button */
+          export const Basic = () => <Button />
+        `)
+      ).toMatchInlineSnapshot(`
+        export default {
+          title: 'Button'
+        };
+        /* The most basic button */
+        export const Basic = () => <Button />;
+        Basic.parameters = {
+          storySource: {
+            source: "() => <Button />"
+          },
+          ...Basic.parameters
+        };
+      `);
+    });
+
+    it('JSDoc single-line', () => {
+      expect(
+        enrich(dedent`
+          export default {
+           title: 'Button',
+          }
+          /** The most basic button */
+          export const Basic = () => <Button />
+        `)
+      ).toMatchInlineSnapshot(`
+        export default {
+          title: 'Button'
+        };
+        /** The most basic button */
+        export const Basic = () => <Button />;
+        Basic.parameters = {
+          storySource: {
+            source: "() => <Button />"
+          },
+          docs: {
+            description: {
+              story: "The most basic button"
+            }
+          },
+          ...Basic.parameters
+        };
+      `);
+    });
+
+    it('JSDoc multi-line', () => {
+      expect(
+        enrich(dedent`
+          export default {
+           title: 'Button',
+          }
+          /**
+           * The most basic button
+           * 
+           * In a block!
+           */
+          export const Basic = () => <Button />
+        `)
+      ).toMatchInlineSnapshot(`
+        export default {
+          title: 'Button'
+        };
+        /**
+         * The most basic button
+         * 
+         * In a block!
+         */
+        export const Basic = () => <Button />;
+        Basic.parameters = {
+          storySource: {
+            source: "() => <Button />"
+          },
+          docs: {
+            description: {
+              story: "The most basic button\\n\\nIn a block!"
+            }
+          },
+          ...Basic.parameters
+        };
+      `);
+    });
+  });
 });
 
 const source = (csfExport: string) => {

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

@@ -2,20 +2,42 @@
 import * as t from '@babel/types';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import * as generate from '@babel/generator';
-// eslint-disable-next-line import/no-extraneous-dependencies
-import * as template from '@babel/template';
 import type { CsfFile } from './CsfFile';
 
 export const enrichCsf = (csf: CsfFile) => {
   Object.keys(csf._storyExports).forEach((key) => {
     const storyExport = csf.getStoryExport(key);
     const source = extractSource(storyExport);
-    const addParameter = template.default(`
-       %%key%%.parameters = { storySource: { source: %%source%% }, ...%%key%%.parameters };
-    `)({
-      key: t.identifier(key),
-      source: t.stringLiteral(source),
-    }) as t.Statement;
+    const description = extractDescription(csf._storyStatements[key]);
+    const parameters = [];
+    // storySource: { source: %%source%% },
+    parameters.push(
+      t.objectProperty(
+        t.identifier('storySource'),
+        t.objectExpression([t.objectProperty(t.identifier('source'), t.stringLiteral(source))])
+      )
+    );
+    // docs: { description: { story: %%description%% } },
+    if (description) {
+      parameters.push(
+        t.objectProperty(
+          t.identifier('docs'),
+          t.objectExpression([
+            t.objectProperty(
+              t.identifier('description'),
+              t.objectExpression([
+                t.objectProperty(t.identifier('story'), t.stringLiteral(description)),
+              ])
+            ),
+          ])
+        )
+      );
+    }
+    const originalParameters = t.memberExpression(t.identifier(key), t.identifier('parameters'));
+    parameters.push(t.spreadElement(originalParameters));
+    const addParameter = t.expressionStatement(
+      t.assignmentExpression('=', originalParameters, t.objectExpression(parameters))
+    );
     csf._ast.program.body.push(addParameter);
   });
 };
@@ -25,3 +47,20 @@ export const extractSource = (node: t.Node) => {
   const { code } = generate.default(src, {});
   return code;
 };
+
+export const extractDescription = (node?: t.Node) => {
+  if (node?.leadingComments) {
+    const comments = node.leadingComments
+      .map((comment) => {
+        if (comment.type === 'CommentLine' || !comment.value.startsWith('*')) return null;
+        return comment.value
+          .split('\n')
+          .map((line) => line.replace(/^(\s+)?(\*+)?(\s+)?/, ''))
+          .join('\n')
+          .trim();
+      })
+      .filter(Boolean);
+    return comments.join('\n');
+  }
+  return '';
+};

code/ui/blocks/src/controls/Boolean.stories.tsx

@@ -4,6 +4,7 @@ import { BooleanControl } from './Boolean';
 export default {
   title: 'Controls/Boolean',
   component: BooleanControl,
+  tags: ['docsPage'],
 };
 
 const Template = (initialValue?: boolean) => {
@@ -20,4 +21,7 @@ export const True = () => Template(true);
 
 export const False = () => Template(false);
 
+/**
+ * When no value is set on the control
+ */
 export const Undefined = () => Template(undefined);

code/yarn.lock

@@ -2119,7 +2119,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/template@npm:^7.12.11, @babel/template@npm:^7.16.7, @babel/template@npm:^7.18.10, @babel/template@npm:^7.3.3, @babel/template@npm:^7.4.0, @babel/template@npm:^7.7.0, @babel/template@npm:^7.8.6":
+"@babel/template@npm:^7.16.7, @babel/template@npm:^7.18.10, @babel/template@npm:^7.3.3, @babel/template@npm:^7.4.0, @babel/template@npm:^7.7.0, @babel/template@npm:^7.8.6":
   version: 7.18.10
   resolution: "@babel/template@npm:7.18.10"
   dependencies:
@@ -6644,7 +6644,6 @@ __metadata:
   dependencies:
     "@babel/generator": ^7.12.11
     "@babel/parser": ^7.12.11
-    "@babel/template": ^7.12.11
     "@babel/traverse": ^7.12.11
     "@babel/types": ^7.12.11
     "@storybook/csf": next