@modern-js/main-doc 2.0.0-beta.2 → 2.0.0-beta.4

package/zh/tutorials/first-app/c10-model/10.2-add-model.md

@@ -1,185 +0,0 @@
----
-title: 实现 Model
----
-
-创建一个完整的 Model 首先需要定义**状态（state）**，包括状态中数据的名称和初始值。
-
-我们使用 Model 来管理联系人列表的数据，因此定义如下数据状态：
-
-```js
-const state = {
-  items: [],
-};
-```
-
-使用 TS 语法，可以定义更完整的类型信息，比如 items 里每个对象都应该有 `name`、`email` 字段；
-
-为了实现归档功能，还需要创建 `archived` 字段保存这个联系人是否已被归档的状态；
-
-我们还需要一个字段用来访问所有已归档的联系人，可以定义 **computed** 类型的字段，对已有的数据做转换：
-
-```js
-const computed = {
-  archived: ({ items }) => {
-    return items.filter(item => item.archived);
-  },
-};
-```
-
-:::info 注
-当前版本还未支持 computed，本章节后续部分会先使用其他方式实现 archived 列表，这里只做介绍。
-:::
-
-computed 类型字段的定义方式是函数，但使用时可以像普通字段一样通过 state 访问。
-
-Modern.js 支持的 Model 模块跟 React 组件一样，是基于 FP（Functional Programming）而不是 OOP（Object-Oriented Programming）的，对状态的管理是基于**不可变数据**的，不会修改状态中的数据，只会从一个状态转移到另一个状态，这样的好处很多，比如保障程序的可靠性、方便调试、方便记录和还原状态等。
-
-由于 JS 没有原生支持不可变数据，为了提高编写这种代码的效率，Modern.js 集成了 [Immer](https://immerjs.github.io/immer/)，能够像操作 JS 中常规的可变数据一样，去写这种状态转移的逻辑。
-
-实现 Archive 按钮时，我们需要一个 `archive` 函数，负责修改指定联系人的 `archived` 字段，我们把这种函数都叫作 **action**：
-
-```js
-const actions = {
-  archive(draft, payload) {
-    const target = draft.items.find(item => item.email === payload);
-    if (target) {
-      target.archived = true;
-    }
-  },
-};
-```
-
-action 函数是一种**纯函数**，确定的输入得到确定的输出（转移后的状态），不应该有任何副作用。
-
-函数的第一个参数是 Immer 提供的 Draft State，第二个参数是 action 被调用时传入的参数（后面会介绍怎么调用）。
-
-Model 里也可以定义 Side Effect，比如我们需要从 BFF 加载这个联系人列表的数据，这段业务逻辑可以写成：
-
-```js
-const effects = {
-  async load() {
-    const { data } = await contacts();
-    return data;
-  },
-};
-```
-
-一个 Side Effect 有多种实现方式，上面使用的是 Async 函数方式，这种方式是最简单直观的。Modern.js 会根据它返回的 Promise 对象的状态变化，自动触发不同的 action。
-
-因此一个 effect 总共有三个 action，命名里会用 Side Effect 的名称作为命名空间，在这个例子里，分别是：
-
-- `load.pending`：等待中
-- `load.fulfilled`：成功，得到结果
-- `load.rejected`：失败，得到错误信息
-
-Modern.js 虽然会自动定义和触发这些 action，但默认不会为这些 action 实现具体的业务逻辑（action 直接返回原本的状态，不做任何转换）。
-
-我们尝试自己实现它们：
-
-```js
-import _ from 'lodash';
-
-const state = {
-  items: [],
-  pending: false,
-  error: null,
-};
-
-const computed = {
-  archived: ({ items }) => {
-    return items.filter(item => item.archived);
-  },
-};
-
-const actions = {
-  archive(draft, payload) {
-    const target = draft.items.find(item => item.email === payload);
-    if (target) {
-      target.archived = true;
-    }
-  },
-  load: {
-    pending(draft) {
-      draft.pending = true;
-    },
-    fulfilled(draft, payload) {
-      draft.pending = false;
-      _.merge(draft.items, payload);
-    },
-    rejected(draft, payload) {
-      draft.pending = false;
-      draft.error = payload;
-    },
-  },
-};
-```
-
-上述实现里，成功时，payload 是 promise 的结果；失败时，payload 是错误信息。
-
-从上面这个例子里可以看到，可以用嵌套的写法，实现 `load.pending` 这样名称中包含命名空间的 action。
-
-为了做到高内聚低耦合，一个 Model 的 state、action、side effect 不应该分散在不同文件里。接下来我们把上面的代码连起来，放在同一个 Model 文件里，执行以下命令：
-
-```bash
-mkdir -p src/contacts/models/
-touch src/contacts/models/contacts.ts
-```
-
-`src/contacts/models/contacts.ts` 的内容：
-
-```tsx
-import { model } from '@modern-js/runtime/model';
-import { get as contacts } from '@api/contacts';
-
-type State = {
-  items: {
-    avatar: string;
-    name: string;
-    email: string;
-    archived?: boolean;
-  }[];
-  pending: boolean;
-  error: null | Error;
-};
-
-export default model<State>('contacts').define({
-  state: {
-    items: [],
-    pending: false,
-    error: null,
-  },
-  computed: {
-    archived: ({ items }: State) => items.filter(item => item.archived),
-  },
-  actions: {
-    archive(draft, payload) {
-      const target = draft.items.find(item => item.email === payload)!;
-      if (target) {
-        target.archived = true;
-      }
-    },
-    load: {
-      pending(draft) {
-        draft.pending = true;
-      },
-      rejected(draft, payload) {
-        draft.pending = false;
-        draft.error = payload;
-      },
-      fulfilled(draft, p) {
-        draft.items = p;
-      },
-    },
-  },
-  effects: {
-    async load() {
-      const { data } = await contacts();
-      return data;
-    },
-  },
-});
-```
-
-我们把一个包含 state，action 等要素的 plain object 称作【 Model Spec 】，Modern.js 提供了 [Model API](/docs/apis/app/runtime/model/model_)，可以根据 Model Spec 生成【 Model 】。
-
-本小节中，我们联系人列表项目需要的 Model 实现。下一小节我们将会学习如何使用 Model。

package/zh/tutorials/first-app/c10-model/10.3-use-model.md

@@ -1,54 +0,0 @@
----
-title: 使用 Model
----
-
-上一小节中，我们实现了 Model，已经把 AllContacts 组件中原有的 UI 无关业务逻辑解耦出来。
-
-这一小节中，我们使用这个 Model 直接把 AllContacts 组件重新还原出来，实现变得更简洁清晰：
-
-```js title="src/contacts/components/AllContacts/index.tsx"
-import { useEffect } from 'react';
-import { useLocalModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import Item from '../Item';
-import contacts from '../../models/contacts';
-
-const AllContacts = () => {
-  const [{ items, error, pending }, actions] = useLocalModel(contacts);
-
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-  return (
-    (items.length && (
-      <List
-        dataSource={items}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    )) || (
-      <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-        Pending...
-      </div>
-    )
-  );
-};
-
-export default AllContacts;
-```
-
-以上代码跟上一章节中 `AllContacts` 组件的代码等价。
-
-`useLocalModel` 是 Modern.js 提供的 hooks API，可以使用 Model，在组件中提供 Model 中定义的 state，或通过 actions 调用 Model 中定义的 side effect 与 action，从而改变 Model 的 state。
-
-Modern.js 的 Model 能够这样使用的原因是 Model 是基于 FP 的，不像 OOP 的 Model 那样自身持有和封装了状态，对外部提供方法访问和修改自身内部的状态。
-
-Model 是业务逻辑，是计算过程，本身不创建也不持有状态，只有在被组件用 hooks API 使用后，才在指定的地方（比如这个例子里，是组件内部的 state）创建状态。
-
-执行 `pnpm run dev`，可以看到跟上一章节一样的效果。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c10/hello-modern-3)。
-

package/zh/tutorials/first-app/c10-model/10.4-testing.md

@@ -1,69 +0,0 @@
----
-title: 测试 Model
----
-
-上一小节中我们学习了如何使用 Model。
-
-这一小节里我们来测试 Model。
-
-跟[测试组件​​​](../c06-css-and-component/6.6-testing.md)中一样，不需要做任何配置，可以直接给 Model 写测试用例。
-
-以 `models/contacts` 为例，我们创建对应的 `.test` 文件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-touch src/contacts/models/contacts.test.ts
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-ni src/contacts/models/contacts.test.ts
-```
-
-</TabItem>
-</Tabs>
-
-在测试用例中可以使用 Modern.js 提供的 Model 模拟，可以调用这个对象的方法写断言。
-
-我们直接使用 createStore API 来编写测试文件，示例内容如下：
-
-```ts
-import { createStore } from '@modern-js/runtime/testing';
-import contactsModel from './contacts';
-
-const mockItem = {
-  avatar: '',
-  name: '李华',
-  age: '16',
-  email: 'lihua@gmail.com',
-  archived: false,
-};
-
-describe('test contracts model', () => {
-  it('actions works well', async () => {
-    const store = createStore();
-    const [state, actions] = store.use(contactsModel);
-
-    state.items.push(mockItem);
-    expect(store.use(contactsModel)[0].items.length).toBe(1);
-    expect(store.use(contactsModel)[0].items[0].archived).toBeFalsy();
-
-    await actions.archive('lihua@gmail.com');
-    expect(store.use(contactsModel)[0].items[0].archived).toBeTruthy();
-  });
-});
-```
-
-执行 `pnpm run test`，可以看到测试报告。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c10/hello-modern-4)。
-

package/zh/tutorials/first-app/c10-model/_category_.json

@@ -1,3 +0,0 @@
-{
-  "label": "10: 添加业务模型"
-}

package/zh/tutorials/first-app/c11-container/11.1-use-model-with-app-state.md

@@ -1,274 +0,0 @@
----
-title: ​完整使用 Model
----
-
-上一章节中，我们初步引入**客户端应用架构**，从【 视图组件 】中拆分出【 业务模型（Model）】，`AllContacts` 中不再包含 UI 无关的业务逻辑实现细节，只需要使用 Model，就能实现同样的功能。
-
-这一章节中，我们要进一步利用 Model 中实现的业务逻辑，让 `AllContacts` 和  `ArchivedContacts` 都从 BFF 获取数据，实现 Archive 按钮，点击按钮能把联系人归档，只显示在 Archives 列表里，不显示在 All 列表里。
-
-先改造 `Item` 组件，增加 Archive 按钮的交互实现：
-
-```tsx title="src/contacts/components/Item/index.tsx"
-import Avatar from '../Avatar';
-
-type InfoProps = {
-  avatar: string;
-  name: string;
-  email: string;
-  archived?: boolean;
-};
-
-const Item = ({
-  info,
-  onArchive,
-}: {
-  info: InfoProps;
-  onArchive?: () => void;
-}) => {
-  const { avatar, name, email, archived } = info;
-  return (
-    <div className="flex p-4 items-center border-gray-200 border-b">
-      <Avatar src={avatar} />
-      <div className="ml-4 custom-text-gray flex-1 flex justify-between">
-        <div className="flex-1">
-          <p>{name}</p>
-          <p>{email}</p>
-        </div>
-        <button
-          type="button"
-          disabled={archived}
-          onClick={onArchive}
-          className={`text-white font-bold py-2 px-4 rounded-full ${
-            archived
-              ? 'bg-gray-400 cursor-default'
-              : 'bg-blue-500 hover:bg-blue-700'
-          }`}>
-          {archived ? 'Archived' : 'Archive'}
-        </button>
-      </div>
-    </div>
-  );
-};
-
-export default Item;
-```
-
-`ArchivedContacts` 和 `AllContacts` 需要共用同一套状态（联系人列表数据、联系人是否被归档），并且由于 Archives 列表和 All 列表都可能是第一屏页面（从不同 URL 访问），这两个组件都需要包含加载初始数据的逻辑（如果客户端没有联系人列表数据，就请求 BFF），所以这类两个组件公用的实现逻辑应该合并到一起：
-
-我们删除原有的两个组件，创建一个新的 `Contacts` 组件：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-rm -r src/contacts/components/*Contacts
-mkdir -p src/contacts/components/Contacts/
-touch src/contacts/components/Contacts/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-rm -r src/contacts/components/*Contacts
-mkdir -p src/contacts/components/Contacts/
-ni src/contacts/components/Contacts/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-修改`components/Contacts/index.tsx` ，内容如下：
-
-```tsx title="src/contacts/components/Contacts/index.tsx"
-import { useEffect } from 'react';
-import { useLocalModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import contacts from '../../models/contacts';
-import Item from '../Item';
-
-const Contacts = ({ source }: { source: 'archived' | 'items' }) => {
-  const [state, actions] = useLocalModel(contacts);
-  const { items, error, pending } = state;
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-
-  const data = state.items.filter(item =>
-    source === 'archived' ? item.archived : true,
-  );
-
-  return (
-    (items.length && (
-      <List
-        dataSource={data}
-        renderItem={info => (
-          <Item
-            key={info.email}
-            info={info}
-            onArchive={() => {
-              actions.archive(info.email);
-            }}
-          />
-        )}
-      />
-    )) || (
-      <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-        Pending...
-      </div>
-    )
-  );
-};
-
-export default Contacts;
-```
-
-:::info 注
-由于 computed 功能还未提供，这里先在组件里将传入的数据做预处理。
-:::
-
-最后改造 `App.tsx`，利用 Contacts 实现 Archives 列表和 All 列表：
-
-```tsx title="src/contacts/App.tsx"
-import { useState } from 'react';
-import { Radio, RadioChangeEvent } from 'antd';
-import { Route, useHistory } from '@modern-js/runtime/router';
-import { Helmet } from '@modern-js/runtime/head';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import './styles/utils.css';
-import Contacts from './components/Contacts';
-
-function App() {
-  const history = useHistory();
-  const [currentList, setList] = useState(history.location.pathname || '/');
-  const handleSetList = (e: RadioChangeEvent) => {
-    const { value } = e.target;
-    setList(value);
-    history.push(value);
-  };
-
-  return (
-    <div className="container lg mx-auto">
-      <div className="h-16 p-2 flex items-center justify-center">
-        <Radio.Group onChange={handleSetList} value={currentList}>
-          <Radio value="/">All</Radio>
-          <Radio value="/archives">Archives</Radio>
-        </Radio.Group>
-      </div>
-      <Route path="/" exact={true}>
-        <Helmet>
-          <title>All</title>
-        </Helmet>
-        <Contacts source="items" />
-      </Route>
-      <Route path="/archives" exact={true}>
-        <Helmet>
-          <title>Archives</title>
-        </Helmet>
-        <Contacts source="archived" />
-      </Route>
-    </div>
-  );
-}
-
-export default App;
-```
-
-执行 `pnpm run dev`，访问 `http://localhost:8080/contacts/`，点击 Archive 按钮后，可以看到按钮置灰：
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display.png)
-
-接下来点击顶部导航，切换到 Archives 列表，我们预期的时候能看到列表里显示刚才归档的联系人，但实际上列表是空的：
-
-![display7](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display7.png)
-
-出现这个问题的原因是，我们继续沿用了上一节的 `useLocalModel` API 来使用 Model，状态被保存到了组件内部的 state 里，而 `All` 列表和 `Archives` 列表中分别调用的 `Contacts` 组件，是两个各自独立的组件：
-
-```tsx title="src/contacts/App.tsx"
-<Route path="/" exact={true}>
-  <Helmet>
-    <title>All</title>
-  </Helmet>
-  <Contacts source="items" />
-</Route>
-<Route path="/archives" exact={true}>
-  <Helmet>
-    <title>Archives</title>
-  </Helmet>
-  <Contacts source="archived" />
-</Route>
-```
-
-所以它们有各自独立的内部 state，互相不共享状态，渲染 `Archives` 列表的时候，`items` 仍然是初始状态。
-
-要解决这个问题，一种方式把 `useLocalModel` 的逻辑提升到父组件里，把状态分别传给两个 `Contacts` 组件。更清晰、完善的方式，是启用全局唯一的「 应用状态 」，两个 `Contacts` 组件「 连接 」应用状态。
-
-在 Modern.js 里实现应用状态管理很简单，只需要把 `useLocalModel` 换成 `useModel`。
-
-修改 `components/Contacts/index.tsx` 的内容：
-
-
-```tsx title="src/contacts/components/Contacts/index.tsx"
-import { useEffect } from 'react';
-import { useModel } from '@modern-js/runtime/model';
-import { List } from 'antd';
-import contacts from '../../models/contacts';
-import Item from '../Item';
-
-const Contacts = ({ source }: { source: 'archived' | 'items' }) => {
-  const [state, actions] = useModel(contacts);
-  const { items, error, pending } = state;
-  useEffect(() => {
-    if (!items.length && !error && !pending) {
-      actions.load();
-    }
-  });
-
-  const data = state.items.filter(item =>
-    source === 'archived' ? item.archived : true,
-  );
-
-  return (
-    (items.length && (
-      <List
-        dataSource={data}
-        renderItem={info => (
-          <Item
-            key={info.email}
-            info={info}
-            onArchive={() => {
-              actions.archive(info.email);
-            }}
-          />
-        )}
-      />
-    )) || (
-      <div className="p-4 items-center border-gray-200 border-b border-t custom-text-gray">
-        Pending...
-      </div>
-    )
-  );
-};
-
-export default Contacts;
-```
-
-重新执行 `pnpm run dev`，重复刚才的操作，可以看到 Archives 列表能正常显示了：
-
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display1.png)
-
-:::info 注
-useModel API 还可以设置 Selector，只连接这个 Model 定义的状态中的局部。
-:::
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern)。
-

package/zh/tutorials/first-app/c11-container/11.2-add-container.md

@@ -1,106 +0,0 @@
----
-title: 容器组件（Container）
----
-
-前两个章节中，我们把项目中的业务逻辑拆分成了两个 layer，一个是【 视图组件 】，另一个是 【 业务模块 】。
-
-【 视图组件 】 负责 UI 展示、交互等；【 业务模块 】负责实现 UI 无关的业务逻辑，专门管理状态，既可以是组件状态（局部，不唯一），也可以是应用状态（全局，唯一）。
-
-像 `components/Contacts/index.tsx` 这样使用了 `useModel` API 的组件，其实已经在**客户端应用架构**中扮演一种新的角色，负责把 View 和 Model 这两个 layer 连接起来，类似传统 MVC 架构中 Controller 的角色，也类似一种 ViewController。
-
-因为这种组件属于一种新的功能模块，在 Modern.js 里我们沿用习惯，把它们称作【 容器组件（Container）】。
-
-容器组件推荐放在专门的 `containers/` 目录里，我们执行以下命令：
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/contacts/containers/
-mv src/contacts/components/Contacts/index.tsx src/contacts/containers/Contacts.tsx
-rm -r src/contacts/components/Contacts/
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/contacts/containers/
-mv src/contacts/components/Contacts/index.tsx src/contacts/containers/Contacts.tsx
-rm -r src/contacts/components/Contacts/
-```
-
-</TabItem>
-</Tabs>
-
-修改 `containers/Contacts.tsx` 的代码：
-
-```tsx
-import Item from '../components/Item';
-import contacts from '../models/contacts';
-```
-
-修改 `App.tsx` 的代码：
-
-```tsx
-import Contacts from './containers/Contacts';
-```
-
-重构完成，现在的项目结构是：
-
-```md
-.
-├── .vscode/
-├── api/
-│   ├── .eslintrc.json
-│   └── contacts.ts
-├── src/
-│   ├── contacts/
-│   │   ├── components/
-│   │   │   ├── Avatar/
-│   │   │   │   ├── index.stories.tsx
-│   │   │   │   └── index.tsx
-│   │   │   └── Item/
-│   │   │       ├── index.test.tsx
-│   │   │       └── index.tsx
-│   │   ├── containers/
-│   │   │   └── Contacts.tsx
-│   │   ├── models/
-│   │   │   ├── contacts.test.ts
-│   │   │   └── contacts.ts
-│   │   ├── styles/
-│   │   │   └── utils.css
-│   │   ├── App.css
-│   │   └── App.tsx
-│   ├── landing-page/
-│   │   └── pages/
-│   │       ├── comments/
-│   │       │   └── [commentTitle]/
-│   │       │       └── index.tsx
-│   │       ├── _app.tsx
-│   │       ├── docs.tsx
-│   │       └── index.tsx
-│   ├── .eslintrc.json
-│   └── modern-app-env.d.ts
-├── .editorconfig
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── README.md
-├── package.json
-├── pnpm-lock.yaml
-└── tsconfig.json
-```
-
-`components/` 里的【 视图组件 】，都是目录形式，如 `Avatar/index.tsx`。而 `containers/` 里的【 容器组件 】，都是单文件形式，如 `contacts.tsx`。**这是我们推荐的一种最佳实践**。
-
-在​ [添加 UI 组件（Component）](../c06-css-and-component/6.1-css-in-js.md) 章节提到过，【 视图组件 】用目录形式，是因为【 视图组件 】负责实现 UI 展示和交互细节，可以演变的复杂，用目录形式，可以方便增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等，在这个目录内部可以随意重构，只考虑最小局部。
-
-而【 容器组件 】只负责连接，是一个胶水层，复杂的业务逻辑和实现细节都交给 View 层和 Model 层去实现，【 容器组件 】自己应该保持简单清晰，不应该包含复杂实现细节，所以不应该有内部结构，采用单文件形式不但更简洁，也能起到约束作用，提醒开发者不要把容器组件写复杂。
-
----
-
-> 本小节的代码可以在[这里查看](https://github.com/modern-js-dev/modern-js-examples/tree/main/tutorials/c11/hello-modern-2)。