@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/apis/app/runtime/plugin/hook.md

@@ -0,0 +1,170 @@
+---
+sidebar_position: 2
+---
+
+# Hook 模型
+
+首先介绍一下 Modern.js 的基础的插件系统中的一些内容，包括 Hook 模型的工作方式、各个 Hook 模型的运行模式、Manager 的工作模式。
+
+每种 Hook 模型都是独立的，可以独立管理运行函数。
+
+## 基础工作方式
+
+先以 Pipeline 为例，简单介绍一下 Hook 模型的工作方式。先看一个简单的例子：
+
+```ts
+import { createPipeline } from '@modern-js/plugin'
+
+// 1. 创建
+const pipeline = createPipeline<number, number>()
+
+// 2. 添加函数
+pipeline.use((count, next) => {
+  return next(count + 1)
+})
+pipeline.use((count, next) => {
+  return count * 2
+})
+
+// 3. 执行
+pipeline.run(1) // 4
+pipeline.run(5) // 12
+```
+
+在这个例子中，创建了一个 `Pipeline<number, number>` 类型的 Pipeline（L3），这意味着运行它的时候，你需要传入一个 `number`，然后你会得到一个 `number`，而这个模型管理的函数的类型是：
+
+```ts
+(count: number, next: (nextCount: number) => number) => number
+```
+
+这里全是 `number`，是因为我们创建的是 `Pipeline<number, number>` ，如果创建的是 `Pipeline<number, string>` 则运行它入参是 `number`，返回值是 `string`，对应管理的函数的类型会是：
+
+```ts
+(count: number, next: (nextCount: number) => string) => string
+```
+
+
+创建好 Pipeline 之后，可以通过 `use` 添加函数（L5、L8），需要注意的是，添加的顺序就是他们默认的运行顺序，在这些函数中，你可以对 `count` 进行处理、返回一个值，如果你调用了 `next` 函数，则会运行后面的函数，即如果你添加了三个函数： `A`、`B`、`C`，如果你在 `A` 中调用 `next` 那么就会运行 `B`，同样的，如果你在 `B` 中调用 `next` 那么就会运行 `C`，而在上面的例子中，添加的第一个函数（L5）就运行了 `next`，所以这里就会运行第二个函数（L8），并且运行的返回值就是 第二个函数的返回值，如果在第一个函数中没有调用 `next`，直接返回，例如：
+
+```ts
+import { createPipeline } from '@modern-js/plugin'
+
+// 1. 创建
+const pipeline = createPipeline<number, number>()
+
+// 2. 添加函数
+pipeline.use((count, next) => {
+  return count + 1
+})
+pipeline.use((count, next) => {
+  return count * 2
+})
+
+// 3. 执行
+pipeline.run(1) // 2
+pipeline.run(5) // 6
+```
+
+则在运行 Pipeline 的时候就不会运行第二个函数，那么 Pipeline 的运行结果则就是第一个函数的返回值。
+
+最后，运行 Pipeline 的方式也显而易见就是调用 `pipeline.run` 。
+
+## 不同 Hook 模型的区别
+
+上面这部分就是 Pipeline 整体的一个工作模式的描述，其他的 Hook 模型的工作模式基本也是这样，主要的区别点，是函数类型、执行顺序，参数。
+
+### Pipeline
+
+上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
+
+:::info 注
+当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
+
+```ts
+pipeline({}, {
+    onLast: () => {
+        // do something
+    }
+})
+```
+:::
+
+### Waterfall
+
+这种模型顾名思义，他的特点就是参数的顺序递交，即前面一个函数的返回值，将会成为下一个函数的入参，我们也用一个例子来看一下：
+
+```ts
+import { createWaterfall } from '@modern-js/plugin'
+
+// 1. 创建
+const waterfall = createWaterfall<number>()
+
+// 2. 添加函数
+waterfall.use((count) => {
+  return count + 1
+})
+waterfall.use((count) => {
+  return count * 2
+})
+
+// 3. 执行
+waterfall.run(1) // 4
+waterfall.run(5) // 12
+```
+
+这个例子中，创建了一个类型为 `Waterfall<number> `，即这个模型执行的入参和返回值是一样的，这个例子中都是 `number`，而它管理的函数的类型是：
+
+```ts
+(count: number) => number
+```
+
+可能简单看这个例子感觉和上面的 Pipeline 功能一样，那需要注意的是，首先这里 Waterfall 管理的函数没有next 函数作为第二个参数，所以它无法在函数内部通过调用 next 来先运行之后添加的函数，从而修改运行的顺序，其次这里的运行的入参的类型和返回值的类型必须是一样的（而 Pipeline 可以不一样）。
+
+同样的，在 Waterfall 这个大类中，也提供了 Sync 和 Async 的小类，分别对应 Sync 和 Async 的函数。
+
+### Workflow
+
+这种 Hook 模型与上面两种 Hook 模型的区别是，没有那么强的前后参数返回值递交的概念，在这个模型中，每个函数都是基于同样的入参，相对独立运行的，通过一个例子简单看一下：
+
+```ts
+import { createWorkflow } from '@modern-js/plugin'
+
+// 1. 创建
+const workflow = createWorkflow <number, number>()
+
+// 2. 添加函数
+workflow.use((count) => {
+  return count + 1
+})
+workflow.use((count) => {
+  return count * 2
+})
+
+// 3. 执行
+workflow.run(1) // [2, 2]
+workflow.run(5) // [6, 10]
+```
+
+在这个例子中，添加了两个函数，所以运行的结果就是这两个函数运行的结果形成的一个数组。
+
+虽然这种模型中没有那么强的前后参数返回值递交的概念，但依旧有执行顺序的区别，在 Workflow 这个大类中，提供了三个小类：Sync、Async、Parallel。他们之间的区别就是函数的执行顺序，当然默认的都是按照添加顺序执行，而在 Sync、Async 则是强制按照添加顺序执行，而 Parallel 则是 Async 模式的一个变体，即它使用的是 `Promise.all` 来执行所有函数，而 Async 则会 `await` 前面的函数运行结束。
+
+## Hook 模型对比
+
+<div style={{ width: "100%", overflowX: "scroll" }}>
+<div style={{ width: "150%" }}>
+
+||函数类型|执行顺序|函数参数来源|执行返回值来源|倾向处理的任务类型|函数 TS 类型|
+|-----|-----|-----|-----|----|----|----|
+|Pipeline|Sync|默认执行第一个添加的函数，可以通过 next 调用之后添加的函数|第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数|第一个函数的返回值|<ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>|`(input: I, next: Next<I, O>) => O`|
+|AsyncPipeline|Sync/Async|默认执行第一个添加的函数，可以通过 next 调用之后添加的函数|第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数向 next 函数传递的参数|第一个函数的返回值|<ul><li>需要修改初始参数</li><li>需要修改函数执行顺序</li></ul>|`(input: I, next: AsyncNext<I, O>) => O ｜ Promise<O>`|
+|WaterFall|Sync|一直顺序执行|第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值|最后一个函数的返回值|<ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>|`(I: I) => I`|
+|AsyncWaterFall|Sync/Async|一直顺序执行|第一个函数的参数来源是运行的参数，之后的函数的参数来源是，前一个函数的返回值|最后一个函数的返回值|<ul><li>需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>|`(I: I) => I ｜ Promise<I>`|
+|Workflow|Sync|一直顺序执行|所有函数的入参都是运行的参数|所有函数返回值形成的数组|<ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>|`(I: I) => O`|
+|AsyncWorkflow|Sync/Async|一直顺序执行|所有函数的入参都是运行的参数|所有函数返回值形成的数组|<ul><li>不需要修改初始参数</li><li>不需要修改函数执行顺序</li></ul>|`(I: I) => O ｜ Promise<O>`|
+|ParallelWorkFlow|Sync/Async|异步执行|所有函数的入参都是运行的参数|所有函数返回值形成的数组|<ul><li>不需要修改初始参数</li><li>不关心执行顺序</li></ul>|`(I: I) => O ｜ Promise<O>`|
+
+</div>
+</div>
+
+Workflow、Waterfall 其实都是 Pipeline 的变体，Pipeline 可以通过特定的写法来实现 Workflow、Waterfall ，但都较为麻烦，有许多隐形的约定，为了方便使用，提供了这两种变体来满足这种特殊场景。

package/zh/apis/app/runtime/plugin/plugin-api.md

@@ -0,0 +1,117 @@
+---
+sidebar_position: 5
+---
+
+# Plugin API
+
+插件的 setup 函数会接收一个 api 入参，你可以调用 api 上提供的一些方法来获取到配置、应用上下文等信息。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    // 获取应用原始配置
+    const config = api.useConfigContext();
+    // 获取应用运行上下文
+    const appContext = api.useAppContext();
+    // 获取解析之后的最终配置
+    const resolvedConfig = api.useResolvedConfigContext();
+  },
+});
+```
+
+## API
+
+### useConfigContext
+
+用于获取应用原始配置。
+
+```ts
+const useConfigContext: () => UserConfig
+
+interface UserConfig {
+  source?: SourceConfig;
+  output?: OutputConfig;
+  server?: ServerConfig;
+  dev?: DevConfig;
+  deploy?: DeployConfig;
+  tools?: ToolsConfig;
+  plugins?: PluginConfig;
+  runtime?: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+}
+```
+
+具体配置字段的意义请参考【[配置](/docs/configure/app/source/alias)】。
+
+### useAppContext
+
+用于获取应用运行上下文。
+
+```ts
+const useAppContext: () => IAppContext
+
+interface IAppContext {
+  appDirectory: string;
+  configFile: string | false;
+  ip?: string;
+  port?: number;
+  distDirectory: string;
+  packageName: string;
+  srcDirectory: string;
+  sharedDirectory: string;
+  nodeModulesDirectory: string;
+  internalDirectory: string;
+  plugins: {
+    cli?: any;
+    server?: any;
+  }[];
+  entrypoints: Entrypoint[];
+  serverRoutes: ServerRoute[];
+  htmlTemplates: HtmlTemplates;
+}
+```
+
+### useResolvedConfigContext
+
+用于获取解析之后的最终配置。
+
+```ts
+const useResolvedConfigContext: () => NormalizedConfig
+
+interface NormalizedConfig {
+  source: NormalizedSourceConfig;
+  output: OutputConfig;
+  server: ServerConfig;
+  dev: DevConfig;
+  deploy: DeployConfig;
+  tools: NormalizedToolsConfig;
+  plugins: PluginConfig;
+  runtime: RuntimeConfig;
+  runtimeByEntries?: RuntimeByEntriesConfig;
+  _raw: UserConfig
+}
+```
+
+具体配置字段的意义请参考【[配置](/docs/configure/app/source/alias)】。
+
+### useHookRunners
+
+用于获取 Hooks 的执行器，并触发特定的 Hook 执行。
+
+```ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  async setup(api) {
+    const hookRunners = api.useHookRunners();
+    // 触发 afterBuild Hook
+    await hookRunners.afterBuild();
+  },
+});
+```

package/zh/apis/app/runtime/testing/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Testing API",
+  "position": 5
+}

package/zh/apis/app/runtime/testing/act.md

@@ -0,0 +1,34 @@
+---
+title: act
+sidebar_position: 4
+---
+
+:::info 补充信息
+用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
+```ts
+import { act } from '@modern-js/runtime/testing';
+```
+:::
+
+## API
+
+`act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
+
+## 示例
+
+```tsx
+import ReactDOM from 'react-dom';
+import { act } from '@modern-js/runtime/testing';
+import { Foo } from '@/components/Foo';
+
+describe('test act', () => {
+  it('it should be foo', () => {
+    const el = document.createElement("div");
+    act(() => {
+      ReactDOM.render(<Foo />, el);
+    })
+
+    expect(el.innerHTML).toBe('<div>Foo</div>');
+  })
+})
+```

package/zh/apis/app/runtime/testing/cleanup.md

@@ -0,0 +1,37 @@
+---
+title: cleanup
+sidebar_position: 3
+---
+
+:::info 补充信息
+用于卸载掉当前已渲染的所有组件。
+```ts
+import { cleanup } from '@modern-js/runtime/testing';
+```
+:::
+
+## API
+
+`cleanup() => void`
+
+## 示例
+
+:::info 注
+请注意，如果你使用的测试框架支持 afterEach，并且它被注入到你的测试环境中（如mocha、Jest和Jasmine），**会默认在 afterEach 钩子里执行 `cleanup`**。否则，你将需要在每次测试后进行手动清理。
+:::
+
+例如，如果你使用[ava](https://github.com/avajs/ava)测试框架，那么你需要像这样使用test.afterEach钩子。
+
+```tsx
+import { cleanup, render } from '@modern-js/runtime/testing';
+import test from 'ava'
+
+test.afterEach(cleanup)
+
+test('renders into document', () => {
+  render(<div />)
+  // ...
+})
+
+// ... more tests ...
+```

package/zh/apis/app/runtime/testing/render.md

@@ -0,0 +1,52 @@
+---
+title: render
+sidebar_position: 1
+---
+
+:::info 补充信息
+用于在测试用例中渲染组件，完成测试。
+```ts
+import { render } from '@modern-js/runtime/testing';
+```
+:::
+
+
+## API
+
+`render(ui, [options]) => RenderResult`
+
+### 参数
+
+- ui: `React.ReactElement<any>`，需要被渲染的 React 组件。
+- [options]: `object`，render 可选配置。
+  - container: `DOMElement`，表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
+  - baseElement: `DOMElement`，用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
+  - hydrate: `boolean`，如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) 渲染组件。默认值为 `false`。
+  - wrapper: `React.ComponentType<{children: ReactNode}>`，是一个 react 组件，可用于自定义渲染逻辑。
+  - queries: `any`，自定义一些自己的 `queries`。
+
+
+### 返回值
+
+- {...queries}: `any`, 所有可用的 [queries](https://testing-library.com/docs/queries/about/)。
+- container: `DOMElement`，`container` 是挂载 React 组件的 DOM 节点。
+- baseElement: `DOMElement`。
+- debug: `function`。
+- rerender: `function`，如果想测试一个已渲染的组件在其 props 更新时的一些场景，可以使用 rerender 来现实。
+- unmount: `function`，会卸载掉已渲染的组件。如果想测试组件卸载后的情况（如，绑定的事件是否在 unmount 阶段被卸载掉），那么这个 API 是很帮助的。
+- asFragment: `function`，返回当前渲染的组件的 [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 对象。可用于测试 react 事件触发后 DOM 结构的响应。
+
+
+## 示例
+
+```ts
+import { render } from '@modern-js/runtime/testing';
+
+test('renders a message', () => {
+  const { container, getByText } = render(<Greeting />)
+  expect(getByText('Hello, world!')).toBeInTheDocument()
+  expect(container.firstChild).toMatchInlineSnapshot(`
+    <h1>Hello, World!</h1>
+  `)
+})
+```

package/zh/apis/app/runtime/testing/renderApp.md

@@ -0,0 +1,31 @@
+---
+title: renderApp
+sidebar_position: 2
+---
+
+:::info 补充信息
+`render` 函数用于测试普通组件，`renderApp` 函数用于测试应用组件。
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+```
+:::
+
+应用组件指包含一些 Modern 上下文的组件，如 App根组件，使用了 model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
+
+## API
+
+`renderApp` 在 API 层面和 [render](./render.md) 完全一致。
+
+## 示例
+
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+import App from '../App';
+
+describe('test', () => {
+  it('test App', () => {
+    const { getByText } = renderApp(<App />);
+    expect(getByText('Hello Modern!')).toBeInTheDocument();
+  });
+})
+```

package/zh/apis/app/runtime/utility/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Utility API",
+  "position": 6
+}

package/zh/apis/app/runtime/utility/css-in-js.md

@@ -0,0 +1,60 @@
+---
+title: CSS-In-JS API
+sidebar_position: 2
+---
+
+:::info 补充信息
+通过 Style Component 在页面上使用 CSS。
+```ts
+import styled from '@modern-js/runtime/styled';
+```
+:::
+
+`styled` 具体API，请看：[styled-component api](https://styled-components.com/docs/api)。
+
+## API
+
+请看 [styled-component API](https://styled-components.com/docs/api)。
+
+## 示例
+
+```tsx
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  background: palevioletred;
+  border-radius: 3px;
+  border: none;
+  color: white;
+`
+
+const TomatoButton = styled(Button)`
+  background: tomato;
+`
+
+render(
+  <>
+    <Button>I'm purple.</Button>
+    <br />
+    <TomatoButton>I'm red.</TomatoButton>
+  </>
+)
+`
+
+render(
+  <div>
+    <Button
+      href="https://github.com/styled-components/styled-components"
+      target="_blank"
+      rel="noopener"
+      primary
+    >
+      GitHub
+    </Button>
+
+    <Button as={Link} href="/docs">
+      Documentation
+    </Button>
+  </div>
+)
+```

package/zh/apis/app/runtime/utility/loadable/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "loadable",
+  "position": 9
+}

package/zh/apis/app/runtime/utility/loadable/lazy.md

@@ -0,0 +1,29 @@
+---
+title: lazy
+sidebar_position: 2
+---
+
+:::info
+用于创建支持 [Suspense](https://reactjs.org/docs/react-api.html#reactsuspense) 的 `loadable 组件`。
+```ts
+import { lazy } from '@modern-js/runtime/loadable';
+```
+:::
+## API
+
+### lazy
+
+```ts
+import { lazy } from '@modern-js/runtime/loadable';
+const OtherComponent = lazy(() => import('./OtherComponent'));
+```
+
+### lazy.lib
+
+创建一个支持 [Suspense](https://reactjs.org/docs/react-api.html#reactsuspense) 的 `loadable 库`。
+
+```ts
+import { lazy } from '@modern-js/runtime/loadable';
+const Moment = lazy.lib(() => import('moment'))
+```
+

package/zh/apis/app/runtime/utility/loadable/loadable-component.md

@@ -0,0 +1,61 @@
+---
+title: LoadableComponent
+sidebar_position: 3
+---
+
+`LoadableComponent` 是 `loadable` 或 `lazy` 函数返回的对象类型。
+
+## LoadableComponent 类型
+
+```ts
+type LoadableComponent<Props> =
+  React.ComponentType<
+    Props & { fallback?: JSX.Element; }>
+  & {
+    preload(props?: Props): void;
+    load(props?: Props): Promise<React.ComponentType<Props>>;
+  }
+```
+
+### props
+
+类型：`object`
+
+`LoadableComponent` 组件可接收任意 props 参数，这些参数会转发给 loadFn。
+
+### fallback
+
+类型：`JSX.Element`
+
+当组件尚未加载完成（即 loading 阶段）会显示 `fallback` 内容。
+
+## LoadableComponent.preload
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+
+const OtherComponent = loadable(() => import('./OtherComponent'))
+OtherComponent.preload()
+```
+
+`preload` 接收的参数会全部传给 `loadFn`。
+
+:::info 注
+预加载脚本中函数始终不会返回一个 Promise 对象，如果你想等待组件加载完成，请使用 [load](#LoadableComponent.load) 函数
+:::
+
+
+## LoadableComponent.load
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+
+const OtherComponent = loadable(() => import('./OtherComponent'))
+OtherComponent.load().then(() => {
+  console.log('Component is loaded!')
+})
+```
+
+:::info 注
+如果你无需等待组件加载完成，则使用 [preload](#LoadableComponent.preload) 即可。
+:::

package/zh/apis/app/runtime/utility/loadable/loadable-library.md

@@ -0,0 +1,67 @@
+---
+title: LoadableLibrary
+sidebar_position: 4
+---
+
+`lazy.lib` 和 `loadable.lib` 函数返回 `LoadableLibrary` 对象
+
+## LoadableLibrary 类型
+
+```ts
+type LoadableLibrary = React.ComponentType<{
+  fallback?: JSX.Element;
+  children?: (module: Module) => React.ReactNode;
+  ref?: React.Ref<Module>;
+}>
+```
+
+### fallback
+
+类型：`JSX.Element`
+
+组件 `loading` 阶段显示 `fallback` 内容。
+
+### children
+
+库加载完成只有的回调。
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+const Moment = loadable.lib(() => import('moment'))
+function FromNow({ date }) {
+  return (
+    <div>
+      <Moment fallback={date.toLocaleDateString()}>
+        {({ default: moment }) => moment(date).fromNow()}
+      </Moment>
+    </div>
+  )
+}
+```
+
+### ref
+
+类型：`React.Ref<Module>`
+
+可以通过 `ref` 拿到所加载库的实例。
+
+```ts
+import loadable from '@modern-js/runtime/loadable'
+const Moment = loadable.lib(() => import('moment'))
+class MyComponent {
+  moment = React.createRef()
+  handleClick = () => {
+    if (this.moment.current) {
+      return alert(this.moment.current.default.format('HH:mm'))
+    }
+  }
+  render() {
+    return (
+      <div>
+        <button onClick={this.handleClick}>What time is it?</button>
+        <Moment ref={this.moment} />
+      </div>
+    )
+  }
+}
+```