@modern-js/main-doc 2.1.0 → 2.2.0

package/en/guides/topic-detail/model/quick-start.mdx

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+title: 快速上手
+---
+# 快速上手
+
+import ReduckMigration from "@site-docs/components/reduck-migration"
+
+<ReduckMigration />
+
+[Reduck](https://github.com/modern-js-dev/reduck) 是 Modern.js 团队开发的遵循 MVC 模式的状态管理库，底层状态存储基于 [Redux](https://redux.js.org/) 实现，同时提供更高层级的抽象，并完全兼容 Redux 生态。
+
+Reduck 的目标是以 MVC 模式组织 React 应用开发结构，将业务逻辑维护在 Model 层，业务逻辑与 UI 解耦，让开发业务逻辑更集中、更简单，同时通过更高层级的抽象，减少重复工作（样板代码）。
+
+Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应 V(View)，从 Reduck 中获取 Model 并修改 Model 的 React Container Component 对应 C(View Controller/Container)。
+
+Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
+
+:::info 注
+1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/configure/app/runtime/state) 以启用状态管理插件。
+2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
+
+:::
+
+## 核心概念
+
+Reduck 中的核心概念只有 4 个： Model、State、Actions、Effects。
+
+Model: 对独立模块的逻辑和所需状态的封装，由 State、Actions、Effects 组成。
+
+State: Model 中保存的状态。
+
+Actions: 用于修改 State 的纯函数，函数必须是**同步**的。
+
+Effects: 用于修改 State 的带有副作用的函数，函数可以是**异步**的。Effects 中可以调用自身或其他 Model 的 Actions 和 Effects。
+
+Reduck 数据流如下图所示：
+
+![Reduck 数据流](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/reduck-concept.svg)
+
+## 基本用法
+
+下来我们以一个简单的 **计数器** 应用为例，演示 Reduck 的基本用法。
+
+首先，我们定义一个名为 `count` 的 Model：
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+});
+
+export default countModel;
+```
+
+我们使用 API `model` 创建 `countModel`，`countModel` 当前只包含存储计数器值的状态，即代码中的 `value`。
+
+我们定义一个 action，用于计算器自增加 1：
+
+```js
+import { model } from '@modern-js/runtime/model';
+
+const countModel = model('count').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state.value += 1;
+    },
+  },
+});
+
+export default countModel;
+```
+
+在 `add` action 中，我们可以直接修改 state 的值，进行加 1 操作，而不需要把 state 作为不可变对象进行操作，这是因为 Reduck 集成了 [immer](https://github.com/immerjs/immer)，可以直接修改原 state 对象。
+
+接下来，我们演示如何在组件中使用 Model。
+
+新建一个组件 Counter，在组件内通过 `useModel` API 使用 `countModel`：
+
+```js
+import { useModel } from '@modern-js/runtime/model';
+import countModel from './models/count';
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add</button>
+    </div>
+  );
+}
+```
+
+`useModel` 获取 `countModel` 的 `state` 和 `actions`，组件展示当前计算器的值，点击 `add` 按钮，计数器自增 1。
+
+:::info 注
+由于使用的案例比较简单，这里并没有严格按照 MVC 模式进行分层，组件 `Counter` 同时起到了 V 和 C 两层的作用。
+
+:::
+
+最终演示效果如下：
+
+![countModel](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/simple-count-model.gif)
+
+这样，我们就完了一个简单的计数器应用。本节完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model)查看。

package/en/guides/topic-detail/model/redux-integration.mdx

@@ -0,0 +1,24 @@
+---
+sidebar_position: 11
+title: Redux 生态集成
+---
+# Redux 生态集成
+
+Reduck 基于 Redux 实现，因此可以使用 Redux [生态的库](https://redux.js.org/introduction/ecosystem)，实现功能增强。通过 [`Provider`](/apis/app/runtime/model/Provider) 、[`createApp`](/apis/app/runtime/model/create-app) 和 [`createStore`](/apis/app/runtime/model/create-store) 等 API ，可以设置使用 Redux 的 [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware) 和 [Store Enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer)；使用 [`createStore`](/apis/app/runtime/model/create-store) 还可以完全掌控 Store 的创建过程。
+
+例如，我们希望使用中间件 [`redux-logger`](https://github.com/LogRocket/redux-logger)，示例代码如下：
+
+```ts
+ReactDOM.render(
+  <Provider config={{ middlewares: [logger] }}>
+    // 通过 Provider 的 config 参数设置 中间件
+    <App />
+  </Provider>,
+  document.getElementById('root'),
+);
+```
+
+:::caution
+Reduck 基于 Redux 底层 API 做了上层封装，屏蔽了 Redux 的一些底层概念，如 Reducer 等。Reduck 对于 Model 是动态挂载的，而 Redux 是在 Store 创建时就会挂载应用所需的全部状态。基于这些实现上的差异，有些 Redux 生态的库是无法直接在 Reduck 中使用的。
+
+:::

package/en/guides/topic-detail/model/test-model.mdx

@@ -0,0 +1,45 @@
+---
+sidebar_position: 9
+title: 测试 Model
+---
+# 测试 Model
+
+好的测试对代码的稳健性至关重要。下面以 [快速上手](/guides/topic-detail/model/quick-start) 的 `countModel` 为例，演示在 Modern.js 中，如何对 Model 进行单元测试。
+
+使用测试功能，需要先开启该功能。在项目根目录下，执行 `pnpm run new`，进行如下选择：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「单元测试 / 集成测试」功能
+```
+
+即可开启测试功能支持。
+
+新增 `count.test.ts` 文件，代码如下：
+
+```ts
+import { createStore } from '@modern-js/runtime/testing';
+import countModel from './count';
+
+describe('test model', () => {
+  it('count value should plus one after add', () => {
+    const store = createStore();
+    const [state, { add }] = store.use(countModel);
+
+    expect(state).toEqual({ value: 1 });
+
+    add();
+
+    expect(store.use(countModel)[0]).toEqual({ value: 2 });
+  });
+});
+```
+
+:::info 注
+这里使用的 [`createStore`](/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/configure/app/runtime/state) 的配置去创建 `store`。
+
+:::
+
+在测试用例里，我们新建一个 `store` 来挂载 `countModel`，通过 `store.use` 获取 `countModel` 的 State 和 Actions。然后调用 `add` Action 更新状态，并断言更新后的状态值。
+
+执行 `pnpm run test` 命令，触发测试用例的执行。

package/en/guides/topic-detail/model/typescript-best-practice.mdx

@@ -0,0 +1,71 @@
+---
+sidebar_position: 10
+title: TS 最佳实践
+---
+# TS 最佳实践
+
+Reduck 对 TS 提供了良好的支持，大部分使用场景下，无需任何额外工作，就可以直接获得 API 的 TS 类型提示。本节，将对其他的一些使用场景，做补充介绍。
+
+## 定义 Model 的 State 类型
+
+为 Model 的 State 声明类型信息，是在 TS 中使用 Reduck 的最佳实践。
+
+```ts title="示例"
+interface State {
+  data: string;
+}
+
+export const foo = model<State>('foo').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    withSuffix: state => state.data + 'suffix',
+  },
+  actions: {
+    setData: (state, payload: string) => {
+      state.data = payload;
+    },
+  },
+});
+```
+
+当为 Model 的 State 声明类型信息后，Model 的 `computed`、`actions` 都能获取正确的类型信息。事实上，上面的示例代码中，即使我们不定义 State 类型信息，也会根据 `state` 的初始值信息自动推导出 State 的类型信息。不过，仍然建议你在定义 Model 时，声明 State 的类型信息，因为根据 `state` 的初始值信息推导出的 State 类型信息可能不完整(缺少字段或字段的类型信息缺少)，而且当使用[函数类型](/apis/app/runtime/model/model_#函数类型)定义 Model 时，State 的类型信息也是无法根据 `state` 的初始值信息自动推导的。
+
+## 衍生状态的依赖类型
+
+当 Model 的衍生状态依赖其他 Model 时，需要手动指定其他 Model 的 State。
+
+```ts title="示例"
+interface State {
+  data: string;
+}
+
+export const bar = model<State>('bar').define({
+  state: {
+    data: '',
+  },
+  computed: {
+    // 为 fooState 指定类型
+    withFoo: [foo, (state, fooState: FooState) => state.data + fooState.data],
+  },
+});
+```
+
+## 获取 Model 类型信息的 Hooks
+
+Reduck 提供了一组用于获取 Model 类型信息的工具类型：
+
+- `GetModelState`： 获取 Model 的 State（包含衍生状态）类型信息。
+- `GetModelActions`：获取 Model 的 Actions（包含 Effects 函数）类型信息。
+
+```ts title="示例"
+export const foo = model<State2>('foo').define({
+  // 省略
+});
+
+// 获取 foo 的 State 类型
+let fooActions: GetModelActions<typeof foo>;
+// 获取 foo 的 Actions 类型
+let fooState: GetModelState<typeof foo>;
+```

package/en/guides/topic-detail/model/use-model.mdx

@@ -0,0 +1,252 @@
+---
+sidebar_position: 3
+title: 使用 Model
+---
+# 使用 Model
+
+## 在组件内使用
+
+### 作为全局状态使用
+
+通过 `useModel` 可以获取 Model 的 State、Actions 等。当 Model 的 State 通过 Actions 进行修改后，任何其他使用了该 Model 的组件，都会自动重新渲染。
+
+在 [快速上手](/guides/topic-detail/model/quick-start) 的计数器案例中，我们已经演示了 `useModel` 的使用，不再重复。
+
+`useModel` 支持传入多个 Model，多个 Model 的 State 和 Actions 会进行合并后作为返回结果。例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state += 1;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    title: 'bar',
+  },
+  actions: {
+    set(state, payload) {
+      state.title = payload;
+    },
+  },
+});
+
+const [state, actions] = useModel([fooModel, barModel]);
+// 或
+const [state, actions] = useModel(fooModel, barModel);
+```
+
+`state` 和 `actions` 的值分别为：
+
+```ts
+state = {
+  value: 1,
+  title: 'bar',
+};
+
+actions = {
+  add(state) {
+    state += 1;
+  },
+  set(state, payload) {
+    state.title = payload;
+  },
+};
+```
+
+`useModel` 还支持对 State 和 Actions 做 selector 操作，实现对 State 和 Actions 的筛选或重命名，例如：
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 1,
+  },
+  actions: {
+    add(state) {
+      state += 1;
+    },
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    value: 'bar',
+  },
+  actions: {
+    set(state, payload) {
+      state.value = payload;
+    },
+  },
+});
+
+const [state, actions] = useModel(
+  [fooModel, barModel],
+  (fooState, barState) => ({
+    fooValue: fooState.value,
+    barValue: barState.value,
+  }), // stateSelector
+  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
+);
+```
+
+我们通过 `stateSelector` ，把 `fooModel` 和 `barModel` 中重名的状态做了命名修改，通过 `actionsSelector` ，过滤掉了 `barModel` 的 Actions。
+
+如果只需要设置 `actionsSelector`，可以把 `stateSelector` 设置为 `undefined`，作为参数占位。例如：
+
+```ts
+const [state, actions] = useModel(
+  [fooModel, barModel],
+  undefined,
+  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
+);
+```
+
+### 作为静态状态使用
+
+通过 `useStaticModel` 获取 Model ，将 Model 中的状态作为静态状态使用。可以保证组件每次访问到的 Model 的 State 都是最新值，但是 Model 的 State 的变化，并不会引起当前组件的重新渲染。
+
+:::info 注
+`useStaticModel` 的使用方式和 `useModel` 完全一致。
+
+:::
+
+考虑下面一种场景，有一个组件 Input 负责用户输入，另外一个组件 Search 负责根据用户的输入信息，在点击查询按钮后执行查询操作，我们不希望用户输入过程中的状态变化引起 Search 重新渲染，这时候就可以使用 `useStaticModel`：
+
+```ts
+import { useStaticModel } from '@modern-js/runtime/model';
+
+function Search() {
+  // 这里注意不要解构 state
+  const [state] = useStaticModel(searchModel);
+
+  return (
+    <div>
+      <button
+        onClick={async () => {
+          const result = await mockSearch(state.input);
+          console.log(result);
+        }}
+      >
+        Search
+      </button>
+    </div>
+  );
+}
+```
+
+:::warning 注意
+不要解构 `useStaticModel` 返回的 `state`，例如改成如下写法：
+`const [{input}] = useStaticModel(searchModel);`
+将始终获取到 Input 的初始值。
+
+:::
+
+`useStaticModel` 还适合和 [react-three-fiber](https://github.com/pmndrs/react-three-fiber) 等动画库一起使用，因为在动画组件 UI 里绑定会快速变化的状态，容易引起[性能问题](https:/docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive)。这种情况就可以选择使用 `useStaticModel`，它只会订阅状态，但不会引起视图组件的重新渲染。下面是一个简化示例：
+
+```ts
+function ThreeComponent() {
+  const [state, actions] = useStaticModel(modelA);
+
+  useFrame(() => {
+    state.value; // 假设初始化为 0
+    actions.setValue(1);
+    state.value; // 这里会得到1
+  });
+}
+```
+
+使用 React 的 refs 也可以实现类似效果，其实 `useStaticModel` 内部也使用到了 refs。不过直接 `useStaticModel` 有助于将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/static-model)查看。
+
+### 作为局部状态使用
+
+通过 `useLocalModel` 获取 Model ，将 Model 中的状态作为局部状态使用。此时 Model State 的变化，只会引起当前组件的重新渲染，但是不会引起其他使用了该 Model 的组件重新渲染。效果和通过 React 的 `useState` 管理状态类似，但是可以将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
+
+:::info 注
+`useLocalModel` 的使用方式和 `useModel` 完全一致。
+
+:::
+
+例如，我们修改计数器应用的代码，添加一个有局部状态的计数器组件 `LocalCounter`：
+
+```ts
+import { useLocalModel } from '@modern-js/runtime/model';
+
+function LocalCounter() {
+  const [state, actions] = useLocalModel(countModel);
+
+  return (
+    <div>
+      <div>local counter: {state.value}</div>
+      <button onClick={() => actions.add()}>add</button>
+    </div>
+  );
+}
+```
+
+分别点击 `Counter` 和 `LocalCounter` 的 `add` 按钮，两者的状态互不影响：
+
+![local-model](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/local-model.gif)
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/local-model)查看。
+
+## 在组件外使用
+
+在实际业务场景中，有时候我们需要在 React 组件外使用 Model，例如在工具函数中访问 State、执行 Actions 等。这个时候，我们就需要使用 Store。 Store 是一个底层概念，一般情况下用户接触不到，它负责存储和管理整个应用的状态。Reduck 的 Store 基于 [Redux 的 Store](https://redux.js.org/api/store) 实现，增加了 Reduck 特有的 API，如 `use` 。
+
+首先，在组件内调用 `useStore` 获取当前应用使用的 `store` 对象，并挂载到组件外的变量上：
+
+```ts
+let store; // 组件外部 `store` 对象的引用
+function setStore(s) {
+  store = s;
+}
+function getStore() {
+  return store;
+}
+
+function Counter() {
+  const [state] = useModel(countModel);
+  const store = useStore();
+  // 通过 useMemo 避免不必要的重复设置
+  useMemo(() => {
+    setStore(store);
+  }, [store]);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+    </div>
+  );
+}
+```
+
+通过 `store.use` 可以获取 Model 对象，`store.use` 的用法同 `useModel` 相同。以计数器应用为例，我们在组件树外，每 1s 对计数器值
+执行自增操作：
+
+```ts
+setInterval(() => {
+  const store = getStore();
+  const [, actions] = store.use(countModel);
+  actions.add();
+}, 1000);
+```
+
+完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model-outof-react)查看。
+
+:::info 注
+如果是通过 [`createStore`](/apis/app/runtime/model/create-store) 手动创建的 Store 对象，无需通过 `useStore` 在组件内获取，即可直接使用。
+
+:::
+
+:::info 补充信息
+本节涉及的 API 的详细定义，请参考[这里](/apis/app/runtime/model/model_)。
+
+:::

package/en/guides/topic-detail/model/use-out-of-modernjs.mdx

@@ -0,0 +1,50 @@
+---
+sidebar_position: 12
+title: 单独使用 Reduck
+---
+# 单独使用 Reduck
+
+在 Modern.js 以外，单独集成 Reduck 使用时，主要需要做以下修改：
+
+1. 安装 Reduck 相关包
+
+在项目中安装 Reduck 包：`@modern-js-reduck/react`。
+
+2. API 导入包名
+
+在 Modern.js 中使用时，Reduck 导出 API 的包名为：`@modern-js/runtime/model`。单独使用 Reduck 时，导出包名为：`@modern-js-reduck/react`。
+
+3. 包裹 `Provider` 组件
+
+Modern.js 自动在应用的入口组件上，包裹了用于注入 Reduck 全局 Store 的 [`Provider`](/apis/app/runtime/model/Provider) 组件。单独使用 Reduck 时，需要手动完成。
+
+示例：
+
+```tsx
+// 根组件
+const Root = () => {
+  return (
+    <Provider>
+      {/* 应用入口组件 */}
+      <App />
+    </Provider>
+  );
+};
+```
+
+4. 功能配置
+
+在 Modern.js 中使用时，可以通过 [`runtime.state`](/configure/app/runtime/state) 对 Reduck 功能进行配置。单独使用时，需要通过 [`Provider`](/apis/app/runtime/model/Provider) 的 `config` 或 `store` 参数配置。
+
+示例：
+
+```tsx
+const Root = () => {
+  return (
+    {/* 关闭 Redux DevTools */}
+    <Provider config={{ devTools: false }}>
+      <App />
+    </Provider>
+  )
+}
+```

package/en/guides/troubleshooting/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "FAQ",
+  "position": 6,
+  "collapsed": true
+}

package/en/guides/troubleshooting/cli.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# CLI FAQ
+
+### Can't pass command line arguments correctly when using pnpm?
+
+The pnpm v6 and pnpm v7 versions do not use the same posture when executing commands. The following should be noted:
+
+pnpm v7：
+
+When using pnpm to invoke a command in `package.json`, if you need to pass arguments to pnpm, you need to put the arguments before the command.
+
+For example, execute the prepare command with the pnpm '--filter' parameter:
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+If you need to pass parameters to a command, you need to put the parameters after the command.
+
+For example, in the following `package.json` configuration:
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+The way to carry parameters when executing the command command is:
+
+```bash
+pnpm run command --options
+```
+
+pnpm v6:
+
+In the following `package.json` configuration:
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+If you need to execute `modern command --option`,
+
+When using pnpm, you need to execute the `pnpm run command -- --option`。
+
+This is because pnpm does not handle command parameters the same as Yarn, but is similar to npm: when not adding a `--` character string, the parameters of pnpm are passed; when using a `--` character string, the parameters of the execution script are passed.
+
+In the above example the parameter `--option` is passed to `modern command`. If `pnpm run command --option` is executed, the parameter `--option` will be passed to pnpm.
+
+Summary:
+
+** When using pnpm v7, if you pass arguments to pnpm, you need to put the arguments before the command **
+
+** When using pnpm v6, if the parameter passed to pnpm, you do not need to add `--`; if the parameter passed is for script use, you need to add `--` character string **.

package/en/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# index