feat(preset): support to register compiletime component (#933)

* feat: support to register markdown component

* test: update markdown component tests

* fix: improve module path in windows

* feat: support to replace the older component

* feat: compiler function supports return values

packages/preset-dumi/src/fixtures/md-components/.umirc.js

@@ -0,0 +1,5 @@
+export default {
+    history: { type: 'memory' },
+    mountElementId: '',
+    plugins: ['./plugin.js'],
+}

packages/preset-dumi/src/fixtures/md-components/README.md

@@ -0,0 +1 @@
+<Test />

packages/preset-dumi/src/fixtures/md-components/Test.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+export default () => (
+    <div>for testing markdown component</div>
+)

packages/preset-dumi/src/fixtures/md-components/plugin.js

@@ -0,0 +1,19 @@
+import path from "path";
+
+export default (api) => {
+  api.chainWebpack((memo) => {
+    // babel compile src folder
+    memo.module.rule("js").include.add(path.join(__dirname, "../../.."));
+
+    return memo;
+  });
+
+  api.register({
+    key: "dumi.registerMdComponent",
+    fn: () => ({
+      name: "Test",
+      component: path.join(__dirname, "Test.js"),
+      compiler(node, i, parent, vFile) {},
+    }),
+  });
+};

packages/preset-dumi/src/index.test.ts

@@ -25,7 +25,8 @@ describe('preset-dumi', () => {
       'sitemap',
       'dynamic-import',
       'compiletime',
-      'custom-components'
+      'custom-components',
+      'md-components'
     ].forEach(dir => {
       rimraf.sync(path.join(fixtures, dir, 'node_modules'));
     });
@@ -443,4 +444,26 @@ describe('preset-dumi', () => {
     expect(distContent).toContain('custom-single-component');
     expect(distContent).toContain('custom-directory-component');
   });
+
+  it('custom md components in compile time', async () => {
+    const cwd = path.join(fixtures, 'md-components');
+    const service = new Service({
+      cwd,
+      env: 'production',
+      presets: [require.resolve('@umijs/preset-built-in'), require.resolve('./index.ts')],
+    });
+
+    // add UMI_DIR to avoid alias error
+    process.env.UMI_DIR = path.dirname(require.resolve('umi/package'));
+
+    await service.run({
+      name: 'build',
+    });
+
+    const distContent = fs
+      .readFileSync(path.join(service.paths.absOutputPath, 'umi.js'))
+      .toString();
+
+    expect(distContent).toContain('for testing markdown component');
+  });
 });

packages/preset-dumi/src/index.ts

@@ -39,6 +39,9 @@ export default () => {
       // for disable dumi
       require.resolve('./plugins/features/disable'),
 
+      // register markdown components
+      require.resolve('./plugins/features/mdComponent'),
+
       // compiletime
       require.resolve('./plugins/features/compiletime'),
     ],

packages/preset-dumi/src/loader/index.ts

@@ -28,6 +28,7 @@ export default async function loader(raw: string) {
     import { Link, AnchorLink } from 'dumi/theme';
     ${theme.builtins
       .concat(theme.fallbacks)
+      .concat(theme.customs)
       .map(component => `import ${component.identifier} from '${component.source}';`)
       .join('\n')}
     import DUMI_ALL_DEMOS from '@@/dumi/demos';

packages/preset-dumi/src/plugins/features/mdComponent.ts

@@ -0,0 +1,17 @@
+import { IApi } from '@umijs/types';
+import type { IMarkdwonComponent } from '../../transformer/remark/mdComponent';
+import { registerMdComponent } from '../../transformer/remark/mdComponent';
+
+export default (api: IApi) => {
+  api.onPluginReady(async () => {
+    const mdComponents: IMarkdwonComponent[] = await api.applyPlugins({
+      type: api.ApplyPluginsType.add,
+      key: 'dumi.registerMdComponent',
+      initialValue: [],
+    });
+
+    mdComponents.forEach(comp => {
+      registerMdComponent(comp);
+    });
+  });
+};

packages/preset-dumi/src/routes/test/examples.test.ts

@@ -15,11 +15,15 @@ describe('routes: examples', () => {
         cwd,
         paths: { cwd, absNodeModulesPath: cwd },
         ApplyPluginsType: {},
-        applyPlugins: (() => ({
-          layoutPaths: { _: '' },
-          builtins: [{ identifier: 'Example', modulePath: '' }],
-          fallbacks: [],
-        })) as any,
+        applyPlugins: (({ key }) =>
+          key === 'dumi.registerMdComponent'
+            ? []
+            : {
+                layoutPaths: { _: '' },
+                builtins: [{ identifier: 'Example', modulePath: '' }],
+                fallbacks: [],
+                customs: [],
+              }) as any,
       } as IApi,
       {} as IDumiOpts,
     );

packages/preset-dumi/src/theme/loader.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import { winPath, createDebug } from '@umijs/utils';
 import { getModuleResolvePath } from '../utils/moduleResolver';
 import ctx from '../context';
+import type { IMarkdwonComponent } from '../transformer/remark/mdComponent';
 
 const debug = createDebug('dumi:theme');
 
@@ -51,6 +52,10 @@ export interface IThemeLoadResult {
    * fallback components
    */
   fallbacks: ThemeComponent[];
+  /**
+   * customize markdown components
+   */
+  customs: ThemeComponent[];
 }
 
 const THEME_PREFIX = 'dumi-theme-';
@@ -237,6 +242,19 @@ export default async () => {
       },
     );
 
+    // get markdown components
+    const mdComponents: IMarkdwonComponent[] = await ctx.umi.applyPlugins({
+      type: ctx.umi.ApplyPluginsType.add,
+      key: 'dumi.registerMdComponent',
+      initialValue: [],
+    });
+
+    const customs = mdComponents.map(component => ({
+      identifier: component.name,
+      source: pathJoin(component.component),
+      cModulePath: pathJoin(component.component),
+    }));
+
     cache = await ctx.umi.applyPlugins({
       key: 'dumi.modifyThemeResolved',
       type: ctx.umi.ApplyPluginsType.modify,
@@ -246,6 +264,7 @@ export default async () => {
         builtins: components,
         fallbacks,
         layoutPaths,
+        customs,
       },
     });
 

packages/preset-dumi/src/transformer/fixtures/remark-components/Test.js

@@ -0,0 +1,3 @@
+import React from 'react';
+
+export default () => <div>test</div>

packages/preset-dumi/src/transformer/fixtures/remark-components/another.md

@@ -0,0 +1 @@
+<Test />

packages/preset-dumi/src/transformer/fixtures/remark-components/index.md

@@ -0,0 +1 @@
+<Test />

packages/preset-dumi/src/transformer/fixtures/remark-components/test.md

@@ -0,0 +1 @@
+<Test />

packages/preset-dumi/src/transformer/remark/index.ts

@@ -17,6 +17,7 @@ import codeBlock from './codeBlock';
 import code from './code';
 import embed from './embed';
 import api from './api';
+import mdComponent from './mdComponent';
 import link from './link';
 import img from './img';
 import previewer from './previewer';
@@ -139,6 +140,7 @@ export default (source: string, fileAbsPath: string, type: 'jsx' | 'html', maste
     .use(debug('code'))
     .use(api)
     .use(debug('api'))
+    .use(mdComponent)
     .use(slug)
     .use(debug('slug'))
     .use(embed)

packages/preset-dumi/src/transformer/remark/mdComponent.ts

@@ -0,0 +1,58 @@
+import is from 'hast-util-is-element';
+import visit from 'unist-util-visit';
+import type { IDumiUnifiedTransformer, IDumiElmNode } from '.';
+import type { Transformer } from 'unified';
+import type unified from 'unified';
+
+type ICompiler = (
+  this: Pick<unified.Processor<unified.Settings>, 'data'>,
+  node: Parameters<visit.Visitor<IDumiElmNode>>[0],
+  index: Parameters<visit.Visitor<IDumiElmNode>>[1],
+  parent: Parameters<visit.Visitor<IDumiElmNode>>[2],
+  vFile: Parameters<Transformer>[1],
+) => ReturnType<visit.Visitor<IDumiElmNode>>;
+
+export interface IMarkdwonComponent {
+  /**
+   * The markdown component name which should always start with a capital letter
+   */
+  name: string;
+  /**
+   * The component path
+   */
+  component: string;
+  /**
+   * The compiler function about how to parse the HTML Abstract Syntax Tree parsed by rehype
+   * @see https://github.com/syntax-tree/hast for more details about the HTML Abstract Syntax Tree
+   * @see https://github.com/syntax-tree/unist-util-visit-parents#returns for more details about the return value for this function
+   */
+  compiler: ICompiler;
+}
+
+const markdownComponents: IMarkdwonComponent[] = [];
+export function registerMdComponent(comp: IMarkdwonComponent) {
+  const target = markdownComponents.find(item => item.name === comp.name);
+  if (target) {
+    // replace the existed one
+    Object.assign(target, comp);
+  } else {
+    markdownComponents.push(comp);
+  }
+}
+
+/**
+ * remark plugin for parsing the customize markdwon components
+ */
+export default function mdComponent(): IDumiUnifiedTransformer {
+  return (ast, vFile) => {
+    visit<IDumiElmNode>(ast, 'element', (node, i, parent) => {
+      const componentNames = markdownComponents.map(a => a.name);
+      if (is(node, componentNames) && !node._dumi_parsed) {
+        const target = markdownComponents.find(item => item.name === node.tagName);
+        // mark this node as a parsed node by dumi
+        node._dumi_parsed = true;
+        return target.compiler.call(this, node, i, parent, vFile);
+      }
+    });
+  };
+}

packages/preset-dumi/src/transformer/test/remark-markdown-component.test.ts

@@ -0,0 +1,87 @@
+import path from 'path';
+import fs from 'fs';
+import transformer from '..';
+import { registerMdComponent } from '../remark/mdComponent';
+
+describe('markdown component examples', () => {
+  const fixtures = path.join(__dirname, '../fixtures/remark-components');
+
+  it('Should NOT transform unrecognized markdown component', () => {
+    const filePath = path.join(fixtures, 'index.md');
+    const result = transformer.markdown(
+      fs.readFileSync(filePath, 'utf8').toString(),
+      filePath,
+    ).content;
+
+    // compare transform content
+    expect(result).toEqual(`<div className="markdown"><Test /></div>`);
+  });
+
+  it('Should transform recognized markdown component', () => {
+    // register mdComponents
+    registerMdComponent({
+      name: 'Test',
+      component: path.join(fixtures, 'remark-components', 'Test.js'),
+      compiler(node, index, parent) {
+        // insert a h3 title before Test component
+        parent.children.splice(
+          index,
+          0,
+          ...[
+            {
+              type: 'element',
+              tagName: 'h3',
+              properties: { id: `markdown-components` },
+              children: [],
+            },
+          ],
+        );
+      },
+    });
+
+    const filePath = path.join(fixtures, 'test.md');
+    const result = transformer.markdown(
+      fs.readFileSync(filePath, 'utf8').toString(),
+      filePath,
+    ).content;
+
+    // compare transform content
+    expect(result).toEqual(
+      `<div className=\"markdown\"><h3 id=\"markdown-components\"><AnchorLink to=\"#markdown-components\" aria-hidden=\"true\" tabIndex={-1}><span className=\"icon icon-link\" /></AnchorLink></h3><Test /></div>`,
+    );
+  });
+
+  it('Should support to replace the markdown component', () => {
+    // register another Test component
+    registerMdComponent({
+      name: 'Test',
+      component: path.join(fixtures, 'remark-components', 'Test.js'),
+      compiler(node, index, parent) {
+        // insert a h3 title before Test component
+        parent.children.splice(
+          index,
+          0,
+          ...[
+            {
+              type: 'element',
+              tagName: 'h3',
+              properties: { id: `another-markdown-components` },
+              children: [],
+            },
+          ],
+        );
+      },
+    });
+
+    const filePath = path.join(fixtures, 'another.md');
+    const result = transformer.markdown(
+      fs.readFileSync(filePath, 'utf8').toString(),
+      filePath,
+    ).content;
+
+    // compare transform content
+    expect(result).toEqual(
+      `<div className=\"markdown\"><h3 id=\"another-markdown-components\"><AnchorLink to=\"#another-markdown-components\" aria-hidden=\"true\" tabIndex={-1}><span className=\"icon icon-link\" /></AnchorLink></h3><Test /></div>`,
+    );
+  });
+});