@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/en/tutorials/first-app/c05-loader.mdx

@@ -0,0 +1,85 @@
+---
+title: Add Loader
+---
+# Add Loader
+
+In the previous chapter, we learned how to add client route.
+
+In this chapter, we will learn how to add **Loader** to the routing component.
+
+By far, we have provided data to components through hardcoding. If you want to get data from the remote, you usually use `useEffect` to do it. But when SSR is enabled, `useEffect` will not be executed at the server level, so this SSR can only render a very limited UI.
+
+Modern.js provides the ability of Data Loader to support homogeneous data acquisition in components to maximize the value of SSR.
+
+Below we demonstrate how to add Data Loader to the routing component and simulate remote data acquisition. We use faker to mock the required data, first install dependency:
+
+```bash
+pnpm add faker@5
+pnpm add @types/faker@5 -D
+```
+
+Create `src/routes/page.loader.ts`:
+
+```tsx
+import { name, internet } from 'faker';
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export default async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+```
+
+:::note
+Data Loader doesn't just work for SSR. In CSR projects, Data Loader can also avoid data acquisition dependency UI rendering, which solves the problem of requesting dynamic grid layout. In the future, Modern.js will also add more capabilities to this feature, such as pre-fetching, data caching, etc.
+
+:::
+
+Modern.js also provides a hooks API called `useLoaderData`, we modify the exported component of `src/routes/page.tsx`:
+
+```tsx {1,4,13}
+import { useLoaderData } from '@modern-js/runtime/router';
+
+function Index() {
+  const { data } = useLoaderData() as LoaderData;
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={data}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+{/* Todo 重新截图，SSR 内容  */}
+
+Re-execute `pnpm run dev`, view `view-source: http://localhost:8080/`, or view the "Preview" of the HTML request in the Network panel of devtools, you can see that the HTML rendered by SSR already contains the complete UI:
+
+![display6](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/11/display6.png)

package/en/tutorials/first-app/c06-model.mdx

@@ -0,0 +1,275 @@
+---
+title: Add Model
+---
+
+# Add Model
+
+In the previous chapter, we changed the hardcoding `mockData` to load from Data Loader.
+
+In this chapter, we will further implement the functions of the project, such as the implementation of the function of the **Archive** button to put the point of contact archive.
+
+Therefore, we will start to write some business logic that has nothing to do with the UI at all. If we continue to write in the component code, more and more noodle code will be generated. To this end, we introduced a code module called **Model** to decoupling these business logic and UI.
+
+:::info note
+To use the Model API, you need to opt in [runtime.state](/docs/configure/app/runtime/state):
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    state: true,
+  },
+});
+```
+
+:::
+
+## Model implementation
+
+To create a complete Model, you first need to define **state**, including the name and initial value of data in the state.
+
+We use Model to manage the data of the point of contact list, so define the following data state:
+
+```js
+const state = {
+  items: [],
+};
+```
+
+Using TS syntax, you can define more complete type information, such as items in each object should have a `name`, `email` field. In order to implement archive function, also need to create the `archived` field to hold the point of contact has been archived state.
+
+We also need a field to access all archived points of contact. We can define a field of type **computed** to convert the existing data:
+
+```js
+const computed = {
+  archived: ({ items }) => {
+    return items.filter(item => item.archived);
+  },
+};
+```
+
+Fields of type `computed` are defined as function, but can be accessed through state just like normal fields.
+
+:::info
+Modern.js integrates [Immer](https://immerjs.github.io/immer/) and can write such state transfer logic just like normal mutable data in JS.
+
+:::
+
+When implementing the Archive button, we need an `archive` function, which is responsible for modifying the `archived` field of the specified contact. We call this function **action**:
+
+```js
+const actions = {
+  archive(draft, payload) {
+    const target = draft.items.find(item => item.email === payload);
+    if (target) {
+      target.archived = true;
+    }
+  },
+};
+```
+
+An action function is a pure function, where a defined input gets a defined output (a shifted state) and should not have any side effects.
+
+The first parameter of the function is the Draft State provided by Immer, and the second parameter is the parameter passed in when the action is called (more on how to call it later).
+
+We try to implement them completely:
+
+```js
+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;
+    }
+  },
+};
+```
+
+Next we connect the above code and put it in the same Model file. First execute the following command to create a new file directory:
+
+```bash
+mkdir -p src/models/
+touch src/models/contacts.ts
+```
+
+Add `src/models/contacts.ts`:
+
+```tsx
+import { model } from '@modern-js/runtime/model';
+
+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;
+      }
+    },
+  },
+});
+```
+
+We call a plain object containing elements such as state, action, etc. as **Model Spec**, Modern.js provides [Model API](/apis/app/runtime/model/model_), which can generate **Model** from Model Spec.
+
+## Use Model
+
+Now let's use this Model directly to complement the logic of the project.
+
+First modify `src/components/Item/index.tsx` and add the UI and interaction of the **Archive button**, the content is as follows:
+
+```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;
+```
+
+Next, we modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { useLoaderData } from '@modern-js/runtime/router';
+import { List } from 'antd';
+import { name, internet } from 'faker';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+      archived: false,
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+function Index() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { archive, setItems }] = useModel(contacts);
+  if (items.length === 0) {
+    setItems(data);
+  }
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+`useModel` is the hooks API provided by the Modern.js. You can provide the state defined in the Model in the component, or call the side effects and actions defined in the Model through actions to change the state of the Model.
+
+Model is business logic, a computational process that does not create or hold state itself. Only after being used by the component with the hooks API, the state is created in the specified place.
+
+Execute `pnpm run dev` and click the **Archive button** to see that the page UI has changed.
+
+:::note
+In the above example, `useLoaderData` is actually executed every time the route is switched. Because we used fake data in the Data Loader, the data returned each time is different. But we use the data in the Model first, so the data does not change when switching routes.
+
+:::

package/en/tutorials/first-app/c07-container.mdx

@@ -0,0 +1,282 @@
+---
+title: Add Container
+---
+# Add Container
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+In the previous chapter, we initially introduced the **model** to split this part of the logic from the UI component. The `page.tsx` no longer contains UI-independent business logic implementation details, and only needs to use the Model to implement the same function.
+
+In this chapter, we will further use the business logic of implementation in Model to let `page.tsx` and `archived/page.tsx` get the same data. And implementation Archive button, click the button to display the point of contact archive only in the Archives list, not in the All list.
+
+## Use the full Model
+
+Because the two pages need to share the same set of state (point of contact tabular data, point of contact is archived or not), both need to contain the logic to load the initial data, so we need to complete the data acquisition at a higher level.
+
+Modern.js support obtaining data through Data Loader in `layout.tsx`, we first move the data acquisition part of the code to `src/routes/layout.tsx`:
+
+```tsx
+import { name, internet } from 'faker';
+import {
+  Outlet,
+  useLoaderData,
+  useLocation,
+  useNavigate,
+} from '@modern-js/runtime/router';
+import { useState } from 'react';
+import { Radio, RadioChangeEvent } from 'antd';
+import { useModel } from '@modern-js/runtime/model';
+import contacts from '../models/contacts';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import '../styles/utils.css';
+
+type LoaderData = {
+  code: number;
+  data: {
+    name: string;
+    avatar: string;
+    email: string;
+  }[];
+};
+
+export const loader = async (): Promise<LoaderData> => {
+  const data = new Array(20).fill(0).map(() => {
+    const firstName = name.firstName();
+    return {
+      name: firstName,
+      avatar: `https://avatars.dicebear.com/api/identicon/${firstName}.svg`,
+      email: internet.email(),
+    };
+  });
+
+  return {
+    code: 200,
+    data,
+  };
+};
+
+export default function Layout() {
+  const { data } = useLoaderData() as LoaderData;
+  const [{ items }, { setItems }] = useModel(contacts);
+  if (items.length === 0) {
+    setItems(data);
+  }
+
+  const navigate = useNavigate();
+  ...
+}
+```
+
+In `src/routes/page.tsx`, use Model directly to get data:
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+function Index() {
+  const [{ items }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>All</title>
+      </Helmet>
+      <List
+        dataSource={items}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+Also in `archived/page.tsx`, delete the original `mockData` logic and use the `archived` value computed in Model as the data source:
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../../components/Item';
+import contacts from '../../models/contacts';
+
+function Index() {
+  const [{ archived }, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>Archives</title>
+      </Helmet>
+      <List
+        dataSource={archived}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+Execute `pnpm run dev`, visit `http://localhost:8080/`, click the Archive button, you can see the button grey out:
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-all.png)
+
+Next, click the top navigation and switch to the Archives list. You can find that the point of contact of **Archive** just now has appeared in the list:
+
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c07-contacts-archives.png)
+
+## Withdraw container components
+
+In the previous chapters, we split the business logic in the project into two layers, one is the **view component**, and the other is the **module**. The former is responsible for UI display, interaction, etc., and the latter is responsible for the implementation of UI-independent business logic, which specializes in managing state.
+
+Like `src/routes/page.tsx` and `src/routes/archives/page.tsx` use the component of the `useModel` API, which is responsible for linking the two layers of View and Model, similar to the role of the Controller in the traditional MVC architecture. In the Modern.js, we follow the habit and call them **Container**.
+
+The container component is recommended to be placed in a special `containers/` directory. We execute the following command to create a new file:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/containers
+touch src/containers/Contacts.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/containers
+ni src/containers/Contacts.tsx
+```
+
+</TabItem>
+</Tabs>
+
+We extracted the common part of the original two `page.tsx`, and the code of `src/containers/Contacts.tsx` is as follows:
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import { Helmet } from '@modern-js/runtime/head';
+import { useModel } from '@modern-js/runtime/model';
+import { List } from 'antd';
+import Item from '../components/Item';
+import contacts from '../models/contacts';
+
+function Contacts({
+  title,
+  source,
+}: {
+  title: string;
+  source: 'items' | 'archived';
+}) {
+  const [state, { archive }] = useModel(contacts);
+
+  return (
+    <div className="container lg mx-auto">
+      <Helmet>
+        <title>{title}</title>
+      </Helmet>
+      <List
+        dataSource={state[source]}
+        renderItem={info => (
+          <Item
+            key={info.name}
+            info={info}
+            onArchive={() => {
+              archive(info.email);
+            }}
+          />
+        )}
+      />
+    </div>
+  );
+}
+
+export default Contacts;
+```
+
+Modify the code for `src/routes/page.tsx` and `src/routes/archives/page.tsx`:
+
+```tsx title="src/routes/page.tsx"
+import Contacts from '../containers/Contacts';
+
+function Index() {
+  return <Contacts title="All" source="items" />;
+}
+
+export default Index;
+```
+
+```tsx title="src/routes/archives/page.tsx"
+import Contacts from '../../containers/Contacts';
+
+function Index() {
+  return <Contacts title="Archives" source="archived" />;
+}
+
+export default Index;
+```
+
+The refactoring is complete, and the current project structure is:
+
+```bash
+.
+├── README.md
+├── dist
+├── modern.config.ts
+├── node_modules
+├── package.json
+├── pnpm-lock.yaml
+├── src
+│   ├── components
+│   │   ├── Avatar
+│   │   │   └── index.tsx
+│   │   └── Item
+│   │       └── index.tsx
+│   ├── containers
+│   │   └── Contacts.tsx
+│   ├── models
+│   │   └── contacts.ts
+│   ├── modern-app-env.d.ts
+│   ├── routes
+│   │   ├── archives
+│   │   │   └── page.tsx
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   └── styles
+│       └── utils.css
+└── tsconfig.json
+```
+
+The **view components** in `components/` dir are in the form of directories, such as `Avatar/index.tsx`. And the **container components** in `containers/` dir are in the form of single files, such as `contacts.tsx`. **This is a best practice we recommend**.
+
+As mentioned in the chapter [Add UI component](./c02-component.md), the view component is in the form of a directory, because the view component is responsible for the implementation of UI display and interaction details, and can evolve in complexity. In the form of a directory, it is convenient to add sub-files, including dedicated resources (pictures, etc.), dedicated sub-components, CSS files, etc. You can reconstruct at will within this directory, considering only the smallest parts.
+
+The container component is only responsible for linkage and is a glue layer. The sophisticated business logic and implementation details are handed over to the View layer and the Model layer for implementation. The container component itself should be kept simple and clear, and should not contain complex implementation details, so there should be no internal structure. The single-file form is not only more concise, but also acts as a constraint, reminding developers not to write complicated container components.