@modern-js/main-doc 2.1.0 → 2.2.0

package/en/docusaurus-plugin-content-docs/current/tutorials/first-app/c06-model.md

@@ -1,260 +0,0 @@
----
-title: 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 set runtime.state(/docs/configure/app/runtime/state) to enable the state management plugin.
-:::
-
-## 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](/docs/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/docusaurus-plugin-content-docs/current/tutorials/first-app/c07-container.md

@@ -1,282 +0,0 @@
----
-title: Add Container
----
-
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-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.

package/en/docusaurus-plugin-content-docs/current/tutorials/first-app/c08-entries.md

@@ -1,135 +0,0 @@
----
-title: Add Application Entry
----
-
-In the last chapter, we basically completed the development of the point of contact list application, introduced the usage of some functions in the Modern.js, and recommended best practices.
-
-In this chapter, we will describe how to add a new entry to the application.
-
-## New entry
-
-A complete project may require multiple entries, Modern.js supports the automatic creation of new entries, as mentioned in the previous section, `pnpm run new` can enable optional features.
-
-We can also use it to create new project elements and execute `pnpm run new` in the project root directory:
-
-```bash
-? Action Create project element
-? Create project element New "entry"
-? Entry name (entry) landing-page
-```
-
-When created, the project will look like this:
-
-```bash
-.
-├── README.md
-├── modern.config.ts
-├── node_modules
-├── package.json
-├── pnpm-lock.yaml
-├── src
-│   ├── modern-app-env.d.ts
-│   ├── landing-page
-│   │   └── routes
-│   │       ├── index.css
-│   │       ├── layout.tsx
-│   │       └── page.tsx
-│   └── myapp
-│       ├── components
-│       │   ├── Avatar
-│       │   │   └── index.tsx
-│       │   └── Item
-│       │       └── index.tsx
-│       ├── containers
-│       │   └── Contacts.tsx
-│       ├── models
-│       │   └── contacts.ts
-│       ├── routes
-│       │   ├── archives
-│       │   │   └── page.tsx
-│       │   ├── layout.tsx
-│       │   └── page.tsx
-│       └── styles
-│           └── utils.css
-└── tsconfig.json
-```
-
-You can see that the files of the contact list application are automatically refactored into `src/myapp/`.
-
-At the same time, a new `src/landing-page/` is created, which also has `routes/*` (the `pnpm run new` command only does these things, so you can also easily create new entries or modify entries manually).
-
-Execute `pnpm run dev` to display:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-myapp.png)
-
-Access `http://localhost:8080/` to see the application as before.
-
-Visit `http://localhost:8080/landing-page` to see the landing-page for the new entry you just created (Modern.js automatically generated default page).
-
-One of the design principles of the Modern.js framework is [[Convention over Configuration](https://en.wikipedia.org/wiki/Convention_over_configuration) ]. In most cases, you can write code directly by convention without any configuration. The directory structure in `src/` is a convention:
-
-`src/myapp/` and `src/landing-page/` are automatically identified as two application portals: myapp and landing-page.
-
-The directory name of `src/myapp/` is the same as the project name (`name` in `package.json`), which will be considered as the main entry of the project, and the root path of the project URL (the default in the development environment is `http://localhost:8080/`) will automatically point to the main entry.
-
-The URL of other entries is to append the entry name after the root path, such as `http://localhost:8080/landing-page`.
-
-Next, we rename `src/myapp/` to `src/contacts/`:
-
-```bash
-mv src/myapp src/contacts
-```
-
-Execute `pnpm run dev` again, the result becomes:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c08-entries-contacts.png)
-
-There is no longer a main entry, the point of contact list is now a normal entry that needs to be accessed with `http://localhost:8080/contacts`.
-
-## Modify the configuration by entry
-
-In the Modern.js configuration file, we can write our own code to control the configuration of the project.
-
-Now, modify the `modern.config.ts` to add something:
-
-```ts
-import appTools, { defineConfig } from '@modern-js/app-tools';
-import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
-
-// https://modernjs.dev/docs/apis/app/config
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-  server: {
-    ssr: true,
-    ssrByEntries: {
-      'landing-page': false,
-    },
-  },
-  plugins: [appTools(), tailwindcssPlugin()],
-});
-```
-
-Execute `pnpm run dev`, and then open `view-source: http://localhost:8080/landing-page` with the browser, you can see that the content of the `landing-page` web page is dynamically loaded through js, and the SSR function of this page is turned off.
-
-If `ssrByEntries` and its value are annotated, the SSR function of landing-page is restored.
-
-Other times, you need some more sophisticated logic to do the setup, such as JS variables, expressions, import modules, etc., for example, only in the development environment to enable SSR:
-
-```js
-export default defineConfig({
-  server: {
-    ssrByEntries: {
-      'landing-page': process.env.NODE_ENV !== 'production',
-    },
-  },
-};
-```
-
-So far, the prototype of our point of contact list application is almost complete 👏👏👏.
-
-## Next step
-
-Then you can further refine your application by following more tutorials like [Guides](/docs/guides/get-started/quick-start), [configuration](/docs/configure/app/usage), and more.