[RFC] New compiletime component

[PeachScript]

提案背景

dumi 已在 1.1 支持 运行时级别 的自定义组件，例如 dumi 官网通过 .dumi/theme/builtins/Tree.tsx 自定义目录树组件，使得我们可以在 Markdown 中直接使用 <Tree><ul><li>balabala</li></ul></Tree> 的方式来 展示一颗目录树；

但倘若我们想新增一个 JSON.tsx，希望通过 <JSON src="/path/to/a.json"></JSON> 来格式化渲染本地的 JSON 文件，由于 dumi 没有在 编译时 为用户提供处理 src、读取文件内容、传递给 JSON 组件的时机，目前是无法实现的。

另外，API 作为 dumi 1.1 的重要特性发布，但目前积累的 issue 已占 dumi 总 issue 的 四分之一，一方面是 dumi 目前 Contributors 的精力确实有限；另一方面也是因为这份『狗粮』大家没吃，没有实际业务场景做支撑，自然也没有持续推进的动力，这就导致 API 成为 dumi 一项非常鸡肋的功能，Contributors 看着 issue 头疼、dumi 用户饱受缺陷困扰用着也是很糟心。

所以，为了解决上述两个问题，计划在 dumi 中新增一种注册 编译时组件 的插件化方式，并且将目前内置的 API 组件实现也插件化、与 dumi 解耦，便于大家根据实际需要 PRs、fork、甚至自行重写。

具体方案

关于插件化体系

由于 Umi 已经有成熟的插件体系，所以整体插件的开发、发布、使用方式仍然沿用 Umi 插件体系（dumi 自身也是一个 Umi 的插件集），比如目前内置的 API 组件可能被迁移成 NPM 包名为 @umijs/umi-plugin-dumi-api 的插件。

如何注册编译时组件

不同于自定义主题中的运行时组件，编译时组件暂时只提供从插件中注册的入口，dumi 会在 Umi 插件 API 的基础上额外提供一个 registerMdComponent 的方法：

import { IApi } from 'dumi';

// 插件的入口文件
export default (api: IApi) => {
  api.registerMdComponent({
    // 注册组件的名称，首字母必须大写以符合 JSX 的约定
    name: 'API',
    // 运行时的组件路径，会被 dumi 注册为全局组件，可在任一 Markdown 中使用
    component: '/path/to/API.tsx',
    // 编译时的处理函数，入参是 rehype 解析之后的 HTML Abstract Syntax Tree
    // refer: https://github.com/syntax-tree/hast
    compiler: (ast: hast): void => { /* ... */ },
  });
}

关于如何触发编译时处理函数

@umijs/preset-dumi 会再新增一个 rehype plugin，伪代码大致如下：

export default function compileComponent() {
  // 在遍历 AST 之前先拿到所有注册的编译时插件组件名称
  const components = ctx.umi.applyPlugins({ key: 'dumi.registerMdComponent', ... });

  return (ast) => {
    visit(ast, 'element', (node, i, parent) => {
      // 遍历每个节点的时候判断该节点是否命中 components
      if (components.find(node.tagName)) {
        // AST 节点传给处理函数
        component.compiler(node);
      }
    });
  };
}

关于内置 API 迁出

基于上述新增 API，通过以下步骤把内置 API 组件迁出：

1. 以下内容直接挪进新 plugin，逻辑（应该）无需修改：
   a. 默认主题中的 API.tsx 运行时组件
   b. @umijs/preset-dumi 中的子插件 plugin/features/api.ts
2. @umijs/preset-dumi 中的 rehype 插件 transformer/remark/api.ts 挪进新 plugin，内部处理逻辑从遍历整颗 AST 改成接收 API 节点的 AST 做处理（相当于 visit 筛选逻辑不用做了，由 dumi 根据 registerMdComponent 时的 name 预先筛选好）
3. @umijs/preset-dumi 默认注册这个新 plugin，仍提供默认的 API 组件

如果对以上方案有建议或者更好的解法，欢迎在下方一起讨论。

[xiaohuoni]

我有吃，只是不消化，也没时间处理，一直“得过且过”。

[PeachScript]

看来买了很多健胃消食片😁

[PeachScript]

refer: #933