feat: support vue tech stack (#1922)

* feat: add vue tech stack support

* docs: techstack related

how to use vue and how to add techstack support plugin

* feat: add external api parser support

1. Add interfaces to allow dumi to integrate with an external api parser
2. Add dumi-vue-meta package, which can extract metadata from vue.
3.  Add  API tables support for dumi-plugin-vue

* docs: api table support related

* feat: add an option for changing tsconfig path

Add the `tsconfigPath` option in `parserOptions` to allow user to customize tsconfig

* refactor: give watcher creation rights to BaseAtomAssetsParser

* docs: Update README.md

* fix: type of function signature parameter needs to be string

* refactor: code structure adjustment

* fix: babel-plugin-iife type error

* chore: use umi prebundled babel dependencies

prebundle `@vue/babel-plugin-jsx`

* feat: add onBlockLoad method for IDumiTechStack

Provide a method for parsing custom files of frontend frameworks.

* refactor: replace `babel-plugin-iife` with` transformDemoCode`

* refactor: consolidate runtime related APIs into `IDumiTechStack`

remove `useTechStackRuntimeApi`

* feat: add createApiParser

* fix: createApiParser

* docs: techstack related

* refactor: add bundle-utils

* fix: support html2sketch

* fix: html comments FrontMatter

* feat: incorporate live demo into the techstack

* fix: iframe mode

* fix: issue introduced by @vue/babel-plugin-jsx

vuejs/babel-plugin-jsx#687

* refactor: new design of techstack runtime options

* fix: live demo loading

* feat: check vue version

* refactor: flatten options of preset-vue

* refactor: remove id

* docs: preset-vue and techstack

* refactor: remove id of IDemoData

* fix: demo error

* fix: shoud pass id to useRenderer

.eslintignore

@@ -1,3 +1,6 @@
 /dist
 /compiled
 /theme-default
+/runtime
+/suites/*/compiled
+/suites/preset-vue/lib

assets-types/typings/atom/index.d.ts

@@ -41,6 +41,18 @@ export interface AtomComponentAsset extends AtomBaseAsset {
    * props definition of component
    */
   propsConfig: ObjectPropertySchema;
+  /**
+   * slots definition of component
+   */
+  slotsConfig?: ObjectPropertySchema;
+  /**
+   * events definition of component
+   */
+  eventsConfig?: ObjectPropertySchema;
+  /**
+   * methods definition of component
+   */
+  methodsConfig?: ObjectPropertySchema;
 
   /**
    * available parent components of component

assets-types/typings/atom/props/index.d.ts

@@ -115,13 +115,29 @@ export interface ObjectPropertySchema extends BasePropertySchema {
   required?: string[];
 }
 
+export interface FunctionArgSchema {
+  key: string;
+  type: PropertySchema | string;
+  hasQuestionToken?: boolean;
+}
+
+export interface FunctionPropertySchema extends BasePropertySchema {
+  type: 'function';
+  signature: {
+    isAsync: boolean;
+    returnType: PropertySchema;
+    arguments: FunctionArgSchema[];
+  };
+}
+
 /**
  * prop definition
  */
 export type PropertySchema =
   | BasePropertySchema
   | ObjectPropertySchema
   | ArrayPropertySchema
+  | FunctionPropertySchema
   | StringPropertySchema
   | NumberPropertySchema
   | BooleanPropertySchema;

assets-types/typings/example.d.ts

@@ -64,6 +64,10 @@ export interface ExampleBlockAsset extends ExampleBaseAsset {
       value: string;
     }
   >;
+  /**
+   * Entry file name, you can find the relevant entry file content from `dependencies`
+   */
+  entry?: string;
 }
 
 /**

bundler-utils.d.ts

@@ -0,0 +1,5 @@
+import type * as BabelCore from '@umijs/bundler-utils/compiled/@babel/core';
+export { BabelCore };
+export const babelCore: () => typeof import('@umijs/bundler-utils/compiled/@babel/core');
+export const babelPresetTypeScript: () => BabelCore.PluginItem;
+export const babelPresetEnv: () => BabelCore.PluginItem;

bundler-utils.js

@@ -0,0 +1,7 @@
+module.exports = {
+  babelCore: () => require('@umijs/bundler-utils/compiled/babel/core'),
+  babelPresetTypeScript: () =>
+    require('@umijs/bundler-utils/compiled/babel/preset-typescript'),
+  babelPresetEnv: () =>
+    require('@umijs/bundler-utils/compiled/babel/preset-env'),
+};

docs/guide/vue-api-table.md

@@ -0,0 +1,155 @@
+---
+title: 自动 API 表格
+group:
+  title: 使用vue
+  order: 1
+order: 2
+---
+
+# Vue 的自动 API 表格
+
+dumi 支持 Vue 组件的自动 API 表格生成，用户只需配置`entryFile`即可开始 API 表格的使用：
+
+```ts
+import { defineConfig } from 'dumi';
+
+export default defineConfig({
+  resolve: {
+    // 配置入口文件路径，API 解析将从这里开始
+    entryFile: './src/index.ts',
+  },
+});
+```
+
+## tsconfig 配置
+
+Vue 组件的元信息提取主要使用 TypeScript 的 TypeChecker, 所以配置`tsconfig.json`时请务必将`strictNullChecks`设为`false`
+
+```json
+{
+  "compilerOptions": {
+    "strictNullChecks": false
+  }
+}
+```
+
+如果项目中一定要使用`strictNullChecks`，你也可以为 Vue 解析专门配置一个`tsconfig.vue.json`文件
+
+```ts
+// .dumirc.ts
+import * as path from 'path';
+export default {
+  plugins: ['@dumijs/preset-vue'],
+  vue: {
+    tsconfigPath: path.resolve(__dirname, './tsconfig.vue.json'),
+  },
+};
+```
+
+## JSDoc 编写
+
+:::warning
+推荐在 props 中定义组件的事件，这样可以获得完整的 JSDoc 支持
+:::
+
+插件主要支持以下 JSDoc 标签：
+
+### @description
+
+属性描述，可以在`props`, `slots`, `methods`中使用，例如：
+
+```ts
+export default defineComponent({
+  props: {
+    /**
+     * @description 标题
+     */
+    title: {
+      type: String,
+      default: '',
+    },
+  },
+});
+```
+
+### @default
+
+当 prop 的`default`选项为函数时，`default`值不会被解析，这时可以使用`@default`来声明它
+
+```ts
+defineComponent({
+  props: {
+    /**
+     * @default {}
+     */
+    foo: {
+      default() {
+        return {};
+      },
+    },
+  },
+});
+```
+
+### @exposed/@expose
+
+:::warning
+组件实例的方法或是属性的暴露，必须使用@exposed/@expose 标识，单文件组件也不例外
+:::
+
+```ts
+defineExpose({
+  /**
+   * @exposed
+   */
+  focus() {},
+});
+```
+
+JSX/TSX 的组件方法暴露比较麻烦，需要用户另外声明
+
+```ts
+export default Button as typeof Button & {
+  new (): {
+    /**
+     * The signature of the expose api should be obtained from here
+     * @exposed
+     */
+    focus: () => void;
+  };
+};
+```
+
+### @ignore
+
+被`@ignore`标记的属性就会被忽略，不会被解析
+
+## Markdown 编写
+
+在 Markdown 文件编写时
+
+```md
+<API id="Button"></API>
+```
+
+只显示 Vue 组件的`props`部分，完整的显示应该这样编写：
+
+```md
+## Button API
+
+### Props
+
+<API id="Button" type="props"></API>
+
+### Slots
+
+<API id="Button" type="slots"></API>
+
+### Events
+
+<API id="Button" type="events"></API>
+
+### Methods
+
+<API id="Button" type="methods"></API>
+```

docs/guide/vue.md

@@ -0,0 +1,81 @@
+---
+title: 安装插件
+group:
+  title: 使用vue
+  order: 1
+order: 1
+---
+
+# 安装 Vue 支持插件
+
+dumi 中对 Vue 的支持主要通过`@dumijs/preset-vue`插件集实现, 目前只支持 Vue3
+
+## 安装
+
+```bash
+pnpm i vue
+pnpm i -D @dumijs/preset-vue
+```
+
+> [!NOTE]
+> 如果您的 Vue 版本低于 3.3.6，请安装`@vue/compiler-sfc`
+
+## 配置
+
+```ts
+// .dumirc.ts
+export default {
+  presets: ['@dumijs/preset-vue'],
+};
+```
+
+## 插件选项
+
+### checkerOptions
+
+Vue 组件元数据解析选项
+
+例如，以下配置可以使得名称为`InternalType`的类型跳过检查
+
+```ts
+// .dumirc.ts
+export default {
+  presets: ['@dumijs/preset-vue'],
+  vue: {
+    checkerOptions: {
+      schema: { ignore: ['InternalType'] },
+    },
+  },
+};
+```
+
+默认情况下，从`node_modules`中引入所有类型不会被解析，这样可以有效避免元信息冗余，你也可以通过配置`exclude`来定制化类型引入
+
+```ts
+// .dumirc.ts
+export default {
+  presets: ['@dumijs/preset-vue'],
+  vue: {
+    checkerOptions: {
+      schema: { exclude: [/node_modules/, /mylib/] },
+    },
+  },
+};
+```
+
+### tsconfigPath
+
+TypeChecker 使用的 tsconfig，默认值为 `<project-root>/tsconfig.json`
+
+### compiler
+
+Live demo 需要浏览器端的编译器，因此需要加载@babel/standalone。我们提供 `babelStandaloneCDN` 选项来更改其加载地址。默认 CDN 是
+`https://cdn.bootcdn.net/ajax/libs/babel-standalone/7.22.17/babel.min.js`
+
+```js
+vue: {
+  compiler: {
+    babelStandaloneCDN: 'https://cdn.bootcdn.net/ajax/libs/babel-standalone/7.22.17/babel.min.js'
+  },
+},
+```

docs/plugin/api.md

@@ -97,7 +97,10 @@ api.modifyTheme((memo) => {
 
 ```ts
 // CustomTechStack.ts
-import type { ITechStack } from 'dumi';
+import type {
+  IDumiTechStack,
+  IDumiTechStackRuntimeOpts,
+} from 'dumi/tech-stack-utils';
 
 class CustomTechStack implements IDumiTechStack {
   /**
@@ -110,14 +113,45 @@ class CustomTechStack implements IDumiTechStack {
   isSupported(node: hastElement, lang: string) {
     return lang === 'jsx';
   }
+
+  /**
+   * 默认情况下， dumi 只支持js/jsx/ts/tsx模块的依赖分析，
+   * 所以对于无法识别的文件类型需要通过此方法将文件转换为js模块
+   */
+  onBlockLoad?(
+    args: IDumiTechStackOnBlockLoadArgs,
+  ): IDumiTechStackOnBlockLoadResult {
+    // do something
+  }
+
   /**
-   * 代码转换函数，返回值必须是 React 组件代码字符串
+   * 代码转换函数
    * @note  https://github.com/umijs/dumi/tree/master/src/types.ts#L57
    */
   transformCode(raw: string, opts) {
     // do something
     return 'function Demo() { return ... }';
   }
+
+  /**
+   * 运行时选项
+   */
+  runtimeOpts: IDumiTechStackRuntimeOpts = {
+    /**
+     * IDemoCancelableFn函数所在的模块路径
+     * 操作（挂载/卸载）第三方框架组件
+     */
+    rendererPath: '',
+    /**
+     * 运行时编译功能模块的路径
+     */
+    compilePath: '',
+    /**
+     * 该技术堆栈的运行时插件的路径
+     */
+    pluginPath: '',
+  };
+
   /**
    * 生成 demo 资产元数据（可选，通常仅在 dumi 无法分析出元数据时使用，例如非 JS 模块）
    * @note  https://github.com/umijs/dumi/tree/master/src/types.ts#L64