@modern-js/main-doc 2.7.0 → 2.9.0

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

@@ -0,0 +1,247 @@
+---
+sidebar_position: 3
+title: Use Models
+---
+# Use Models
+
+## Using Models in Components
+
+### Using as Global State
+
+`useModel` can be used to obtain the State, Actions, and other information of the Model. When the State of the Model is modified by Actions, any other components that use the Model will automatically re-render.
+
+In the counter example in [Quick Start](/guides/topic-detail/model/quick-start), we have demonstrated the use of `useModel` and will not repeat it here.
+
+`useModel` supports passing multiple Models, and the State and Actions of multiple Models will be merged and returned as the result. For example:
+
+```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` and `actions` value are:
+
+```ts
+state = {
+  value: 1,
+  title: 'bar',
+};
+
+actions = {
+  add(state) {
+    state += 1;
+  },
+  set(state, payload) {
+    state.title = payload;
+  },
+};
+```
+
+`useModel` also supports selector operations on State and Actions to filter or rename State and Actions. For example:
+
+```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
+);
+```
+
+We use `stateSelector` to rename the states with the same name in `fooModel` and `barModel`. We use `actionsSelector` to filter out the Actions of `barModel`.
+
+If only `actionsSelector` needs to be set, you can set `stateSelector` to `undefined` as a placeholder. For example:
+
+```ts
+const [state, actions] = useModel(
+  [fooModel, barModel],
+  undefined,
+  (fooActions, barActions) => ({ add: fooActions.add }), // actionsSelector
+);
+```
+
+### Using as Static State
+
+`useStaticModel` can be used to obtain the Model and use the state of the Model as a static state. This ensures that the State accessed by the component is always the latest value, but the change of the Model's State does not cause the current component to re-render.
+
+:::info
+The usage of `useStaticModel` is exactly the same as `useModel`.
+:::
+
+Consider the following scenario: there is an Input component responsible for user input, and another Search component responsible for executing a search operation after the user input information is entered and the search button is clicked. We do not want the state changes during the user input process to cause Search to re-render. In this case, `useStaticModel` can be used:
+
+```ts
+import { useStaticModel } from '@modern-js/runtime/model';
+
+function Search() {
+  // should not be destructured
+  const [state] = useStaticModel(searchModel);
+
+  return (
+    <div>
+      <button
+        onClick={async () => {
+          const result = await mockSearch(state.input);
+          console.log(result);
+        }}
+      >
+        Search
+      </button>
+    </div>
+  );
+}
+```
+
+:::warning Caution
+Do not destructure the `state` returned by `useStaticModel`. For example, changing it to the following code:
+`const [{input}] = useStaticModel(searchModel);`
+will always get the initial value of Input.
+
+:::
+
+`useStaticModel` is also suitable for use with animation libraries such as [react-three-fiber](https://github.com/pmndrs/react-three-fiber), because binding fast-changing states in animation component UI can easily cause [performance issues](https:/docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive). In this case, you can choose to use `useStaticModel`, which only subscribes to the State but does not cause the view component to re-render. Here is a simplified example:
+
+```ts
+function ThreeComponent() {
+  const [state, actions] = useStaticModel(modelA);
+
+  useFrame(() => {
+    state.value;
+    actions.setValue(1);
+    state.value;
+  });
+}
+```
+
+Using React's refs can also achieve similar effects. In fact, `useStaticModel` also uses refs internally. However, using `useStaticModel` directly helps decouple the state management logic from the component and converge it into the Model layer.
+
+The complete sample code can be found [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/static-model).
+
+### Using as Local State
+
+`useLocalModel` can be used to obtain the Model and use the state of the Model as local state. At this time, the change of the Model State only causes the current component to re-render, but does not cause other components that use the Model to re-render. The effect is similar to managing state through `useState` in React, but it can decouple the state management logic from the component and converge it into the Model layer.
+
+:::info
+The usage of `useLocalModel` is exactly the same as `useModel`.
+:::
+
+For example, we modify the code of the counter application and add a counter component `LocalCounter` with local state:
+
+```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>
+  );
+}
+```
+
+Click the `add` button of `Counter` and `LocalCounter` respectively, and the states of the two do not affect each other:
+
+![local-model](https://lf3-static.bytednsdoc.com/obj/eden-cn/eueh7vhojuh/modern/local-model.gif)
+
+The complete sample code can be found [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/local-model).
+
+## Using outside of components
+
+In actual business scenarios, sometimes we need to use Model outside of React components, such as accessing State and executing Actions in utility functions. At this time, we need to use the Store. The Store is a low-level concept that users generally cannot touch. It is responsible for storing and managing the entire application's state. Reduck's Store is based on Redux's Store implementation and adds Reduck-specific APIs, such as `use`.
+
+First, call `useStore` in the component to obtain the `store` object used by the current application and mount it to a variable outside the component:
+
+```ts
+let store; // Reference to `store` object outside of the component
+function setStore(s) {
+  store = s;
+}
+function getStore() {
+  return store;
+}
+
+function Counter() {
+  const [state] = useModel(countModel);
+  const store = useStore();
+  // Avoid unnecessary duplicate settings through `useMemo`
+  useMemo(() => {
+    setStore(store);
+  }, [store]);
+
+  return (
+    <div>
+      <div>counter: {state.value}</div>
+    </div>
+  );
+}
+```
+
+You can obtain the Model object through `store.use`, and the usage of `store.use` is the same as `useModel`. Taking the counter application as an example, we perform an increment operation on the counter value every 1 second outside the component tree:
+
+```ts
+setInterval(() => {
+  const store = getStore();
+  const [, actions] = store.use(countModel);
+  actions.add();
+}, 1000);
+```
+
+The complete sample code can be found [here](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model-outof-react).
+
+:::info
+If the Store object is manually created through [`createStore`](/apis/app/runtime/model/create-store), there is no need to obtain it through `useStore` in the component, and it can be used directly.
+:::
+
+:::info Additional Information
+For detailed API definitions related to this section, please refer to [here](/apis/app/runtime/model/model_).
+:::

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

@@ -0,0 +1,50 @@
+---
+sidebar_position: 12
+title: Using Reduck Separately
+---
+# Using Reduck Separately
+
+When integrating Reduck separately from Modern.js, the following modifications need to be made:
+
+1. Install the Reduck related packages
+
+Install the Reduck package in the project: `@modern-js-reduck/react`.
+
+2. Import package names for API
+
+When used in Modern.js, the package name for exporting Reduck API is: `@modern-js/runtime/model`. When using Reduck separately, the package name for exporting is: `@modern-js-reduck/react`.
+
+3. Wrap the `Provider` component
+
+Modern.js automatically wraps the [`Provider`](/apis/app/runtime/model/Provider) component used to inject the Reduck global Store on the entry component of the application. When using Reduck separately, this needs to be done manually.
+
+Example:
+
+```tsx
+// Root Component
+const Root = () => {
+  return (
+    <Provider>
+      {/* Entry App */}
+      <App />
+    </Provider>
+  );
+};
+```
+
+4. Feature configuration
+
+When used in Modern.js, Reduck features can be configured through [`runtime.state`](/configure/app/runtime/state). When used separately, configuration needs to be done through the `config` or `store` parameter of [`Provider`](/apis/app/runtime/model/Provider).
+
+Example:
+
+```tsx
+const Root = () => {
+  return (
+    {/* Close Redux DevTools */}
+    <Provider config={{ devTools: false }}>
+      <App />
+    </Provider>
+  )
+}
+```

package/docs/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/docs/en/tutorials/first-app/c03-css.mdx

@@ -0,0 +1,323 @@
+---
+title: Add Style
+---
+# Add Style
+
+import { Tabs, Tab as TabItem } from "@theme";
+
+In the previous chapter, we learned how to use components from the three-way library.
+
+In this chapter, we will learn how to implement UI components.
+
+## JS components using CSS
+
+First of all, we want to control the display of contact avatars by ourselves, and implement this design draft:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
+
+Hypothesis has no ready-made components to implement, so you need to write some CSS yourself. Here we use [styled-components] (https://styled-components.com/) to implement similar requirements. Modern.js out of the box supports styled-components, which requires neither dependency nor configuration.
+
+Style-components avoids many problems of traditional CSS writing through modularization. For example, writing styles directly on the style attribute of elements, the visual details of UI will also be mixed with the details of UI structure and business logic. Or classname needs to avoid global space renaming, which requires the use of naming conventions.
+
+Modify the code at the top in `src/routes/page.tsx`:
+
+```js
+import styled from '@modern-js/runtime/styled';
+```
+
+Add the following code:
+
+```js
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+```
+
+Modify the code of `List.Item.Meta`:
+
+```tsx
+<List.Item.Meta
+  avatar={<Avatar src={avatar} />}
+  title={name}
+  description={email}
+/>
+```
+
+Execute `pnpm run dev` to see the expected running result:
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-result1.png)
+
+Next we do a little refactoring. To enhance legibility and make the code easier to maintain, we can split the Avatar component. We execute the following command at the end point to create a new file:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Avatar
+touch src/components/Avatar/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Avatar
+ni src/components/Avatar/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+Delete the `<Avatar>` implementation in `src/routes/page.tsx` and change it to:
+
+```ts
+import Avatar from '../components/Avatar';
+```
+
+The content of `src/components/Avatar/index.tsx` is modified to:
+
+```ts
+import styled from '@modern-js/runtime/styled';
+
+const Avatar = styled.img`
+  width: 50px;
+  height: 50px;
+  border: 4px solid #0ef;
+  border-radius: 50%;
+`;
+
+export default Avatar;
+```
+
+Execute `pnpm run dev`, the result should be the same.
+
+:::info note
+The reason for using the directory form `Avatar/index.tsx` instead of the single-file form `Avatar.tsx` is that you can easily add sub-files inside the directory later, including dedicated resources (pictures, etc.), dedicated sub-components, CSS files, etc.
+
+:::
+
+## Utility
+
+We have used the style-components implementation `<Avatar>` component, but the current UI is still unsatisfactory and lacks professionalism, such as the list item inhouse layout is a bit rough and misaligned in many places.
+
+Now, let's implement a better `Item` component ourselves, implementing a design draft like this:
+
+![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
+
+The UI to be implemented this time is more complex and has an internal structure, but on the other hand, there is no very thick bright blue border of the `<Avatar>` component such a very special UI, which is a very conventional horizontal and vertical layout, centering, font style, etc. In this case, there is actually no need to write CSS at all. There is a more efficient implementation method that complements styled-components: **Utility Class**.
+
+Modern.js integrates the mainstream, light, general-purpose Utility Class library [Tailwind CSS](https://tailwindcss.com/).
+
+Execute `pnpm run new` and select the following to start Tailwind CSS:
+
+```bash
+? Action: Enable features
+? Enable features: Enable Tailwind CSS
+```
+
+Register the Tailwind plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools(), tailwindcssPlugin()],
+});
+```
+
+Import the Tailwind CSS css file at the top of `src/routes/page.tsx` to start a quick implementation of the professional UI:
+
+```js
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+```
+
+Create the Item component first:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/components/Item
+touch src/components/Item/index.tsx
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/components/Item
+ni src/components/Item/index.tsx
+```
+
+</TabItem>
+</Tabs>
+
+Modify `src/routes/page.tsx` to pass the `render` implementation of `List` to `Item` component:
+
+```js
+import { List } from 'antd';
+import 'tailwindcss/base.css';
+import 'tailwindcss/components.css';
+import 'tailwindcss/utilities.css';
+import Item from '../components/Item';
+
+const getAvatar = (users: Array<{ name: string, email: string }>) =>
+  users.map(user => ({
+    ...user,
+    avatar: `https://avatars.dicebear.com/v2/identicon/${user.name}.svg`,
+  }));
+
+const mockData = getAvatar([
+  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
+  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
+  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
+  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
+]);
+
+function Index() {
+  return (
+    <div className="container lg mx-auto">
+      <List
+        dataSource={mockData}
+        renderItem={info => <Item key={info.name} info={info} />}
+      />
+    </div>
+  );
+}
+
+export default Index;
+```
+
+Utility Class(https://tailwindcss.com/docs/container) is used on the parent container for a quick implementation of the most basic maximum width, center, and other styles.
+
+Next implementation `src/components/Item/index.tsx`:
+
+```tsx
+import Avatar from '../Avatar';
+
+type InfoProps = {
+  avatar: string;
+  name: string;
+  email: string;
+  archived?: boolean;
+};
+
+const Item = ({ info }: { info: InfoProps }) => {
+  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 flex-1 flex justify-between">
+        <div className="flex-1">
+          <p>{name}</p>
+          <p>{email}</p>
+        </div>
+        <button
+          type="button"
+          disabled={archived}
+          className={`bg-blue-500  text-white font-bold
+            py-2 px-4 rounded-full hover:bg-blue-700`}
+        >
+          Archive
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default Item;
+```
+
+Execute `pnpm run dev` to see the expected running result:
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
+
+We only use a few Utility Classes, such as [Flex](https://tailwindcss.com/docs/display/), [Padding](https://tailwindcss.com/docs/padding/), [Margin](https://tailwindcss.com/docs/margin/), [Text](https://tailwindcss.com/docs/text-color/), [Font](https://tailwindcss.com/docs/font-weight/), [Border](https://tailwindcss.com/docs/border-width), without writing a single CSS implementation Professional UI that conforms to the design draft.
+
+## Customized Utility Class
+
+We can also implement the new Utility Class ourselves to facilitate reuse between codes.
+
+Utility Class itself is also a **component-oriented** technology (using different classes on a component is equivalent to setting some attributes from the base class for this component), but the classname of Utility Class is global (because it is used on arbitrary components/elements), it is very suitable for implementation with separate CSS files.
+
+Create a new CSS file:
+
+<Tabs>
+<TabItem value="macOS" label="macOS" default>
+
+```bash
+mkdir -p src/styles
+touch src/styles/utils.css
+```
+
+</TabItem>
+<TabItem value="Windows" label="Windows">
+
+```powershell
+mkdir -p src/styles
+ni src/styles/utils.css
+```
+
+</TabItem>
+</Tabs>
+
+Import `utils.css` in `src/routes/page.tsx`:
+
+```js
+import '../styles/utils.css';
+```
+
+A Utility Class named `custom-text-gray` is implemented in `src/routes/styles/utils.css`.
+
+```css
+:root {
+  --custom-text-color: rgb(113, 128, 150);
+}
+
+.custom-text-gray {
+  color: var(--custom-text-color);
+}
+```
+
+:::info note
+Modern.js integrates with [PostCSS](/guides/basic-features/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+
+:::
+
+Use in `src/routes/components/Item/index.tsx`:
+
+```js
+<div className="ml-4 flex-1 flex justify-between">
+```
+
+Change to:
+
+```js
+<div className="ml-4 custom-text-gray flex-1 flex justify-between">
+```
+
+Execute `pnpm run dev`, you can see that the font color has changed:
+
+![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
+
+:::info note
+This is just to demonstrate Utility Class usage. In a real project, with Tailwind CSS, this Utility Class is of little value and should be added to the font color through the [**theme**](https://tailwindcss.com/docs/customizing-colors) of the configuration Design System.
+
+`utils.css` can also be written as `utils.scss` or `utils.less`, Modern.js out of the box support for SCSS and Less.
+
+However, with the support of PostCSS, modern CSS should be sufficient to meet these development needs, and the performance is also better than that of the preprocessor. It is recommended to use `.css` files first.
+
+:::