@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/en/tutorials/first-app/c04-routes.mdx

@@ -1,172 +0,0 @@
----
-title: Add Client Route
----
-# Add Client Route
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-In the previous chapter, we learned how to create UI components and add styles.
-
-In this chapter, we will learn how to add **Client Route**.
-
-Previously we have added the Archive button to the point of contact list, next we add a route `/archives`, when accessing this route, only the point of contact of the saved file is displayed, while the original `/` continues to display all points of contact.
-
-Create a new `src/routes/archives/page.tsx` file:
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/routes/archives
-touch src/routes/archives/page.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/routes/archives
-ni src/routes/archives/page.tsx
-```
-
-</TabItem>
-</Tabs>
-
-Add the following code:
-
-```tsx title="src/archives/page.tsx"
-import { List } from 'antd';
-import { Helmet } from '@modern-js/runtime/head';
-import Item from '../../components/Item';
-
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-const getMockArchivedData = () =>
-  getAvatar([
-    { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-    { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-  ]);
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>Archives</title>
-      </Helmet>
-      <List
-        dataSource={getMockArchivedData()}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-The `Helmet` component of [React Helmet](https://github.com/nfl/react-helmet) is used here, and the Helmet component is also added in `src/routes/page.tsx`:
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      ...
-    </div>
-  );
-}
-```
-
-:::info note
-Modern.js integrates react-helmet by default, and can also be used in conjunction with SSR to meet SEO needs.
-
-:::
-
-Since there are multiple pages now, all of which need to use the previous Utility Class, we need to move the style file to `src/routes/layout.tsx`:
-
-```tsx
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import '../styles/utils.css';
-```
-
-Execute `pnpm run dev`, visit `http://localhost:8080`, you can see the full point of contact, the title of the page is All:
-
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-archives.png)
-
-Visit `http://localhost:8080/archives` and you will only see the point of contact of the saved file with the title Archives:
-
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-all.png)
-
-Looking at the HTML source code of the page, you can see that the content of the two pages is the same, and different content is rendered for different URLs.
-
-**Next we add a simple navigation bar that allows the user to toggle between the two lists**.
-
-Open `src/routes/layout.tsx` and import the Radio component at the top:
-
-```tsx
-import { Radio } from 'antd';
-```
-
-Then modify the top of the UI to add a set of radio group:
-
-```tsx
-export default function Layout() {
-  return (
-    <div>
-      // [!code highlight:6]
-      <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>
-      <Outlet />
-    </div>
-  );
-}
-```
-
-Then we come to the implementation of `currentList` and `handleSetList`.
-
-Introducing three React Hooks: `useState` and `useNavigate` and `useParams`, as well as Ant Design's event type definition:
-
-```js
-import { useState } from 'react';
-import { Radio, RadioChangeEvent } from 'antd';
-import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
-```
-
-Finally, add local state and related logic to the Layout component:
-
-```tsx
-export default function Layout() {
-  // [!code highlight:8]
-  const navigate = useNavigate();
-  const location = useLocation();
-  const [currentList, setList] = useState(location.pathname || '/');
-  const handleSetList = (e: RadioChangeEvent) => {
-    const { value } = e.target;
-    setList(value);
-    navigate(value);
-  };
-  return (
-  ...
-}
-```
-
-At this point, the page navigation bar implementation has been completed, and execute `pnpm run dev` to see the effect:
-
-![display2](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-switch.png)
-
-Click Archives in the navigation bar, you can see that the selected state and URL of the radio box will change, the page is not refreshed, only CSR occurs.
-
-Accessing the two pages through the URL, you can see that the HTML content is different, because the page executes the logic of client routing in the SSR stage, and the HTML already contains the final render result.

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

@@ -1,87 +0,0 @@
----
-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.
-
-So 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.data.ts`:
-
-```tsx
-import { name, internet } from 'faker';
-
-export 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://api.dicebear.com/7.x/pixel-art/svg?seed=${firstName}`,
-      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
-// [!code highlight:2]
-import { useLoaderData } from '@modern-js/runtime/router';
-import type { LoaderData } from './page.data';
-
-function Index() {
-  // [!code highlight:1]
-  const { data } = useLoaderData() as LoaderData;
-
-  return (
-    <div className="container lg mx-auto">
-      <Helmet>
-        <title>All</title>
-      </Helmet>
-      // [!code highlight:1]
-      <List
-        dataSource={data}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-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/docs/en/tutorials/first-app/c06-model.mdx

@@ -1,278 +0,0 @@
----
-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](/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 add `src/routes.page.data` and modify `src/routes/page.tsx` to pass more parameters to the `<Item>` component:
-
-```tsx title="src/routes/page.data.ts"
-export 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://api.dicebear.com/7.x/pixel-art/svg?seed=${firstName}`,
-      email: internet.email(),
-      archived: false,
-    };
-  });
-
-  return {
-    code: 200,
-    data,
-  };
-};
-```
-
-```tsx title="src/routes/page.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';
-import type { LoaderData } from './page.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.
-
-:::