@modern-js/main-doc 2.7.0 → 2.9.0

package/docs/en/guides/topic-detail/model/auto-actions.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 6
+title: Automatically Actions
+---
+# Automatically Generated Actions
+
+In the [Quick Start](/guides/topic-detail/model/quick-start), we implemented the simplest counter model, which still required 10 lines of code. In fact, Modern.js supports automatically generating commonly used actions based on the declared `state` type, which reduces the amount of boilerplate code. The currently supported types are:
+
+- Primitive data types
+- Array types
+- Simple object types (Plain Object)
+
+## Primitive data types
+
+```ts
+const countModel = model('count').define({ state: 1 });
+```
+
+As shown above, we only need one line to create a simple `countModel`. Here's an example code that uses the model:
+
+```tsx
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    // 增加 1
+    actions.setState(state + 1);
+  }, []);
+}
+```
+
+## Array Types
+
+When the state is an array type, an example code for automatically generating actions is shown below:
+
+```ts
+const countModel = model('count').define({ state: [] });
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    actions.push(1);
+    actions.pop();
+    actions.shift();
+    actions.unshift(1);
+    actions.concat([1]);
+    actions.splice(0, 1, 2);
+    actions.filter(value => value > 1);
+  }, []);
+}
+```
+
+We can use the methods of the JavaScript Array object to modify the state.
+
+## Simple Object Types
+
+When the state is a simple object type, an example code for automatically generating actions is shown below:
+
+```ts
+const countModel = model('count').define({
+  state: {
+    a: 1,
+    b: [],
+    c: {},
+  },
+});
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    actions.setA(2);
+    actions.setB([1]);
+    actions.setC({ a: 1 });
+  }, []);
+}
+```
+
+Three different fields `a`, `b`, and `c` each generate `setA`, `setB`, and `setC` actions, respectively.
+
+:::info
+When the user-defined action and the action automatically generated by Modern.js have the same name, the user-defined action takes precedence. For example, if `setA` action is already defined in `countModel`, calling `actions.setA()` executes the user-defined `setA`.
+:::
+
+:::info Additional Information
+For more information on related APIs, please refer to [here](/apis/app/runtime/model/auto-actions).
+:::
+

package/docs/en/guides/topic-detail/model/computed-state.mdx

@@ -0,0 +1,153 @@
+---
+sidebar_position: 4
+title: Derived State
+---
+
+# Derived State
+
+In some scenarios, components need to perform further calculations on the State in Model before they can be used in the components. This logic can be directly written in the component or implemented through derived states in Model. Derived states are defined under the `computed` field in the Model. Depending on the dependencies of the Model and the return type, there are three ways to define derived states.
+
+## Only Depend on the Model's Own State
+
+The derived state only depends on the current Model's State, which is passed as the first parameter to the derived state's definition function.
+
+For example, the todo application has `items` and `filter` in its State, and `filter` is used to filter the todo items displayed on the current page. Therefore, we define a `visibleTodos` derived state that can be directly used in the component. The sample code is as follows:
+
+```ts
+/**
+ *  Assuming the structure of the todo item is as follows:
+{
+    id: string;          // id
+    text: string;        // todo
+    completed: boolean;
+}
+**/
+
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    filter: 'ALL', // ALL: show all；COMPLETED: show completed；ACTIVE: show active
+  },
+  computed: {
+    visibleTodos: state => {
+      switch (state.filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+```
+
+Derived state will eventually be merged with the Model's State, so the derived state can be accessed through the Model's State object. For example, the `visibleTodos` can be used in the component as follows:
+
+```ts
+function Todo() {
+  const [state, actions] = useModel(todoModel);
+
+  return (
+    <div>
+      <div>
+        {state.visibleTodos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Dependent State from Other Models
+
+In addition to depending on the current model's state, derived states may also depend on the state of other models. In this case, the definition format for the derived state is:
+
+
+```ts
+[stateKey]: [...depModels, (selfState, ...depModels) => computedState]
+```
+
+The following example demonstrates how the derived state `combinedValue` of `barModel` depends on the state of `fooModel`.
+
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    value: 'foo',
+  },
+  computed: {
+    combinedValue: [
+      fooModel,
+      (state, fooState) => state.value + fooState.value,
+    ],
+  },
+});
+```
+
+## Derived State with Function Type
+
+Derived states can also return a function. In this case, the definition format for the derived state is:
+
+```ts
+[stateKey]: (state) => (...args) => computedState    // Only relies on its own state
+[stateKey]: [...depModels, (selfState, ...depModels) => (...args) => computedState]  // Relies on the state of other models
+```
+
+Assuming the `filter` state is not stored in the state of the todo app, but is instead used directly in the component, `visibleTodos` can be a function type value. This function receives the `filter` parameter when used in the component, as shown below:
+
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+  },
+  computed: {
+    visibleTodos: state => filter => {
+      switch (filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+
+function Todo(props) {
+  // use props pass filter
+  const { filter } = props;
+  const [state, actions] = useModel(todoModel);
+
+  // get final todos
+  const todos = state.visibleTodos(filter);
+
+  return (
+    <div>
+      <div>
+        {todos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+:::info Additional Reference
+[Using Models](/guides/topic-detail/model/computed-state)
+:::

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

@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+title: Define Model
+---
+# Define a Model
+
+In the previous section, we demonstrated how to create a Model for a simple counter application. In this section, we will provide a detailed introduction on how to create a Model.
+
+We can create a Model using the `model` API. For example, `model('foo')` creates a Model named `foo`. We can define the State and Actions included in the Model by calling the `define` function returned by `model('foo')`:
+
+
+```js
+import { model, useModel } from '@modern-js/runtime/model';
+
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+  actions: {
+    setValue: (state, payload){
+      state.value = payload
+    }
+  }
+});
+```
+
+:::info
+- Actions in the Model cannot contain side-effect logic, such as requesting HTTP interfaces, accessing localStorage, etc.
+- `setValue` directly modifies the input State, which seems to violate the definition of a pure function. However, Reduck uses [immer](https://github.com/immerjs/immer) internally to modify immutable objects, ensuring that this approach does not affect the immutability of the object, so `setValue` is still a pure function. Of course, you can also return a new object directly in the Action, but this approach will be more complex.
+
+:::
+
+The `define` function only describes the original structure of the Model, including the internally defined State, Actions, and so on. The `fooModel` returned by `define` is the actual Model object that is created. For example, although `setValue` has two parameters, when we call the `setValue` Action, we only need to pass in the `payload` parameter, because we are calling the Action method on `fooModel`, not the one described in the original structure of the Model. For more information, please refer to [Using Models](/guides/topic-detail/model/use-model).
+
+In addition to object-type parameters, `define` can also receive function-type parameters. For example:
+
+```js
+import { model, useModel } from '@modern-js/runtime/model';
+
+const fooModel = model('foo').define((context, utils) => {
+  return {
+    state: {
+      value: 'foo',
+    },
+    actions: {
+      setValue: (state, payload){
+        state.value = payload
+      }
+    }
+  }
+});
+```
+
+When defining a Model using a function, the function automatically receives two parameters: `context` and `utils`. `context` is the context object of Reduck, which can obtain the `store` object, and `utils` provides a set of utility functions to facilitate the implementation of complex features such as Model communication.
+
+Models support duplication. For example:
+
+```ts
+const barModel = fooModel('bar');
+```
+
+`barModel` is a new Model object created based on `fooModel`. Analogous to the concepts in object-oriented programming languages, `barModel` and `fooModel` are two instance objects created based on the same class. When the state management logic of two modules is the same, for example, two tab modules in the same page use the same data structure and logic, but the difference is that they obtain data from different interfaces, then you can create two different Model objects by duplicating the Model.
+
+:::info Additional Information
+For detailed definitions of the APIs mentioned in this section, please refer to [here](/apis/app/runtime/model/model_).
+:::

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

@@ -0,0 +1,40 @@
+---
+sidebar_position: 13
+title: FAQ
+---
+
+# FAQ
+
+## Browser Compatibility
+
+The compiled build artifacts of Reduck use ES6 syntax by default. If you need to support older versions of browsers, please include all packages under the `@modern-js-reduck` namespace in your application's build process.
+
+:::info Additional Information
+Reduck uses [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) with [specific configurations](https://github.com/web-infra-dev/reduck/blob/main/common/config.js#L10~L17).
+:::
+
+## Accessing the Main Application Model from a Microfrontend Sub-Application Model
+
+When a microfrontend sub-application model accesses the main application model and the model has not yet been mounted on the main application, it will be automatically mounted on the sub-application.
+
+Example:
+
+```ts
+import { useModel } from '@modern-js/runtime/model';
+import parentModel from '@MasterApp/models/todoModel';
+
+function SubModelApp() {
+  const [state, actions] = useModel(parentModel);
+
+  return <div>...</div>;
+}
+```
+
+![Microfrontend Communication Flowchart](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/mf-communicate.svg)
+
+To avoid accidental downgrades, it is recommended to pre-mount the model that the main application needs to share:
+
+```ts
+// App is the entry component of the main application, and sharedModel1 and sharedModel2 are the models that need to be shared.
+App.models = [sharedModel1, sharedModel2];
+```

package/docs/en/guides/topic-detail/model/manage-effects.mdx

@@ -0,0 +1,251 @@
+---
+sidebar_position: 5
+title: Management Effect
+---
+# Management Effect
+
+The actions in the model must be pure functions and cannot have any side effects during execution. However, in real-world scenarios, we often encounter many side effects, such as: requesting data from an HTTP API to obtain state data, or modifying `localStorage` or sending events while updating the state. In Reduck, side effects are managed through the model's `effects` function.
+
+## Modifying State via Side Effects
+
+The most common scenario in which side effects modify the state is requesting data from an HTTP API to update state data.
+
+Let's take a simple `todoModel` as an example. It has a side effect function `load` that requests the TODO list from a remote server. After the request succeeds, it updates the `state.items` field.
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    load: {
+      pending(state) {
+        state.loading = true;
+      },
+      fulfilled(state, items) {
+        state.items = items;
+        state.loading = false;
+      },
+      rejected(state, error) {
+        state.error = error;
+        state.loading = false;
+      },
+    },
+  },
+  effects: {
+    // Promise effects
+    async load() {
+      return new Promise(resolve => {
+        setTimeout(() => resolve(['Learn Modern.js']), 2000);
+      });
+    },
+  },
+});
+```
+
+The side effect function is uniformly defined under the `effects` field. Here we have written a `load` function that returns a Promise. After the Promise is successfully executed, it returns the TODO list `["Lerna Modern.js"]`.
+
+Side effect functions need to work with actions to modify state. Therefore, we define a `load` object in `actions` (the name needs to be consistent with the name of the side effect function under `effects`), which includes three actions (`pending`, `fulfilled`, `rejected`) that handle the three states (`pending`, `fulfilled`, `rejected`) of the `Promise` returned by the side effect function `load`:
+
+- `pending`: Receives the current state `state` as a parameter and sets the `loading` flag to `true` in the new state.
+- `fulfilled`: Receives the current state `state` and the Promise fulfilled value `items` as parameters, and sets `items` to the parameter `items` and `loading` to `false` in the new state.
+- `rejected`: Receives the current state `state` and the Promise rejected error `error` as parameters, and sets `error` to the parameter `error` and `loading` to `false` in the new state.
+
+How do we call the effects function in the component? The effects function will be merged into the actions object, so you can call the effects function through the actions object, as shown below:
+
+```ts
+function Todo() {
+  const [state, actions] = useModel(todoModel);
+
+  useEffect(() => {
+    // invoke effects function
+    actions.load();
+  }, []);
+
+  if (state.loading) {
+    return <div>loading....</div>;
+  }
+
+  return (
+    <div>
+      <div>
+        {state.items.map((item, index) => (
+          <div key={index}>{item}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+In the example above, the three actions `pending`, `fulfilled`, and `rejected` are generally required for HTTP requests used to obtain data. Reduck provides a utility function `handleEffect` to simplify the creation of actions in this scenario.
+
+For this type of side effect scenario, `handleEffect` stipulates that the state structure of the model contains three fields: `result`, `error`, and `pending`, with initial values of:
+
+```ts
+{
+  result: null,
+  error: null,
+  pending: false，
+}
+```
+
+Calling `handleEffect` will return the following data structure:
+
+```ts
+{
+  pending() { // ... },
+  fulfilled() { // ... },
+  rejected() { // ... }
+}
+```
+
+This data structure is the same as the data structure of the `load` object under `actions`. The object returned by `handleEffect` actually corresponds to the three actions required by the Effects function.
+
+We can use `handleEffect` to rewrite `todoModel`:
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    load: handleEffect({ result: 'items' }),
+  },
+  effects: {
+    // Promise effects
+    async load() {
+      return new Promise(resolve => {
+        setTimeout(() => resolve(['Learn Modern.js']), 2000);
+      });
+    },
+  },
+});
+```
+
+The `handleEffect` function sets `result` to `items` in the received parameter object. Because `todoModel` uses `items` as the key to save the TODO list data instead of using the default `result` as the key of `handleEffect`, configuration is required here.
+
+It is obvious that the `todoModel` implemented through `handleEffect` is much more concise than the previous implementation.
+
+If you do not want all three states (pending, fulfilled, rejected) to be automatically handled by `handleEffect`, for example, if the fulfilled state requires more complex data processing and needs to be manually handled, but you still want to automate the handling of the pending and rejected states, you can use the following method:
+
+```ts
+  actions: {
+    load: {
+      ...handleEffect(),
+      fulfilled(state, payload) {
+        // manual handle
+      },
+    },
+  },
+```
+
+`handleEffect` [API](/apis/app/runtime/model/handle-effect).
+
+In the Effects function, you can also manually call Actions. For example:
+
+```ts
+const todoModel = model('todo').define((context, utils) => ({
+  state: {
+    items: [],
+    loading: false,
+    error: null,
+  },
+  actions: {
+    pending(state) {
+      state.loading = true;
+    },
+    fulfilled(state, items) {
+      state.items = items;
+      state.loading = false;
+    },
+  },
+  effects: {
+    async load() {
+      // use utils.use get cuttent Model actions
+      const [, actions] = utils.use(todoModel);
+      // invoke action
+      actions.pending();
+
+      return new Promise(resolve => {
+        setTimeout(() => {
+          const items = ['Learn Modern.js'];
+          // invoke action
+          actions.fulfilled(items);
+          resolve(items);
+        }, 2000);
+      });
+    },
+  },
+}));
+```
+
+You can use the `use` function to load other Models (including the Model itself) to achieve [Model communication](/guides/topic-detail/model/model-communicate).
+
+## Side effects do not affect state
+
+In some cases, we only need to read State and execute relevant side effect logic, and the side effect will not modify State.
+
+For example, store some State in `localStorage`:
+
+```ts
+const fooModel = model('foo').define((context, utils) => ({
+  state: {
+    value: 'foo',
+  },
+  effects: {
+    setLocalStorage(key) {
+      const [state] = utils.use(fooModel);
+      localStorage.set(key, state.value);
+      return 'success';
+    },
+  },
+}));
+```
+
+or send message to server:
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+  effects: {
+    async sendData(data) {
+      const res = await fetch('url', {
+        method: 'POST',
+        body: data,
+      });
+      return res.json();
+    },
+  },
+});
+```
+
+Sometimes, we want to execute subsequent logic directly based on the execution result of the side effect function. In this case, we need to use the return value of the Effects function.
+
+For example, when the send button is clicked and the data is successfully sent, close the current popup immediately; if it fails, display an error message. We can achieve this through the following code:
+
+```ts
+// The code is for illustration only and cannot be executed.
+// Response function of the "send" button within the component.
+const handleClick = async () => {
+  // sendData returns a string that represents the state.
+  const result = await actions.sendData('some data');
+  if (result === 'success') {
+    // Close the popup window.
+    closeModal();
+  } else {
+    // show error
+    showError(result);
+  }
+};
+```
+
+:::info
+[Example](https://github.com/web-infra-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/effects)
+:::