@modern-js/main-doc 2.1.0 → 2.3.0

package/en/apis/app/runtime/model/create-app.mdx

@@ -0,0 +1,75 @@
+---
+sidebar_position: 11
+title: createApp
+---
+# createApp
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+Reduck will call `createApp` to create a global application by default. If the entire application only needs one Store, then there is no need to call `createApp` manually。Only need to use `createApp` when you need to create a Store locally in the app.
+
+:::caution
+Note that the exported `createApp` in `@modern-js/runtime/model` is used to manage state, while the exported `createApp` in `@modern-js/runtime` is used to create the entire application. The two are differently.
+
+:::
+
+## Function Signature
+
+```ts
+interface AppConfig extends StoreConfig {
+  devTools?: boolean | DevToolsOptions;
+  autoActions?: boolean;
+}
+
+function createApp(config: AppConfig): object;
+```
+
+### Input
+
+- `config`
+  - `StoreConfig`: the same as [`createStore`](./create-store.md) params.
+  - `devTools`: the default value is `true`. when it is an object type，configuring [Options](https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md) of Redux DevTools。
+  - `autoActions`: the default value is `true`。if [auto generate Actions](./auto-actions.md)。
+
+### Return Value
+
+Reduck App, consists of the following properties:
+
+- `Provider`: inject shared Store into locally component tree, same as [`Provider`](./Provider.md)。
+- `useModel`: get the Model mounted by the app's local Store, same as [`useModel`](./use-model.md)。
+- `useStaticModel`: get the Model mounted by the app's local Store. same as [`useStaticModel`](./use-static-model.md)。
+- `useLocalModel`: get the Model mounted by the app's local Store. same as [`useLocalModel`](./use-local-model.md)。
+- `useStore`: get the Store used locally by the app. same as [`useStore`](./use-store.md)。
+
+## Example
+
+use `createApp`, local states can be created to isolate the states between different Reduck applications.
+
+```tsx
+const { Provider: LocalFooProvider, useModel: useLocalFooModel } = createApp();
+const { Provider: LocalBarProvider, useModel: useLocalBarModel } = createApp();
+
+function Foo() {
+  const [fooState] = useLocalFooModel(fooModel);
+  const [barState] = useLocalBarModel(fooModel);
+
+  return (
+    <div>
+      <div>Foo: {fooState}</div>
+      <div>Bar: {barState}</div>
+    </div>
+  );
+}
+
+function Container() {
+  return (
+    <LocalFooProvider>
+      <LocalBarProvider>
+        <Foo />
+      </LocalBarProvider>
+    </LocalFooProvider>
+  );
+}
+```

package/en/apis/app/runtime/model/create-store.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_position: 10
+title: createStore
+---
+# createStore
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+`createStore` is used to create a Store. Reduck’s Store based on Redux's [Store](https://redux.js.org/api/store) implementatio. Used to store the state of the application and managing the state and Model.
+
+In general, this API is only used when you need to have full control over the creation of the Store. For example, to customize a Store, pass in the ['Provider'](./Provider.md) component to use.
+
+## Function Signature
+
+```ts
+interface StoreConfig {
+  initialState?: Record<string, any>;
+  middlewares?: Middleware[];
+  models?: Model[];
+  plugins?: Plugin[];
+  enhancers?: StoreEnhancer[];
+}
+
+interface ReduckStore extends ReduxStore {
+  use: typeof useModel;
+  unmount: (model: Model) => void;
+}
+
+function createStore(config?: StoreConfig): ReduckStore;
+```
+
+### Input
+
+- `config`: store options.
+  - `initialState`: set the initial state for store.
+  - `models`: set the Model to mount to the Store in advance(No need for normal use).
+  - `middlewares`: set Redux [middleware](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware).
+  - `enhancers`: set Redux [Store enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer).
+  - `plugins`: set Reduck plugin。***experimental API, not recommended***。
+
+### Return Value
+
+Reduck Store:
+
+- `use`: mount and fetch Model objects dynamically. Usage is the same as ['useModel'](./use-model.md), but can be used outside of React components.
+- `unmount`: unmount the Model object, and the Model State is cleared from the Store.
+- `ReduxStore`: [Redux Store API](https://redux.js.org/tutorials/fundamentals/part-4-store#redux-store).
+
+## Example
+
+```tsx
+const store = createStore();
+
+function load() {
+  const [, actions] = store.use(fooModel);
+
+  actions.load();
+}
+```

package/en/apis/app/runtime/model/handle-effect.mdx

@@ -0,0 +1,107 @@
+---
+sidebar_position: 7
+title: handleEffect
+---
+# handleEffect
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+An asynchronous function type Effect usually has three states that need to be processed: in request, request successful, and request failed. The way to handle these states is to write the Action functions (pending, fulfilled, rejected).
+
+With the help of the `handleEffect` API, we can generate default Action functions to handle different results at each stage of an asynchronous request. The structure of the State returned by the Action generated by `handleEffect` is as follows:
+
+```ts
+interface State {
+  result: any; // result of fulfilled state
+  pending: boolean; // request is pending
+  error: string; // request error message
+}
+```
+
+## Function Signature
+
+```ts
+interface EffectActions {
+  pending: Action;
+  fulfilled: Action;
+  rejected: Action;
+}
+
+interface Config {
+  ns?: string;
+  result?: string | false;
+  error?: string | false;
+  pending?: string | false;
+  combineMode?: 'merge' | 'replace';
+  omitResultNamespace?: boolean;
+}
+
+function handleEffect(config: Config): EffectActions;
+```
+
+### Input
+
+- `ns`: the default returned State structure is flat, By setting this parameter, the returned State can be mounted under the field named by the `ns`. For example, if `ns` is set to `"data"`, the returned structure is:
+
+```ts
+interface State {
+  data: {
+    pending: boolean;
+    result: any;
+    error: string;
+  };
+}
+```
+
+- `result`: the default value is "result". This parameter corresponds to the field name that stores the fulfilled state results. For example, set `result` to `"items"`, the returned State structure is:
+
+```ts
+interface State {
+  items: any; // 默认的 result -> items
+  pending: boolean;
+  error: string;
+}
+```
+
+if `result` is `false`，then returned State has no `result`:
+
+```ts
+interface State {
+  pending: boolean;
+  error: string;
+}
+```
+
+- `pending`: the default value is `"pending"`. Change the name of the `pending` field in the returned State. Usage is the same as `result`.
+
+- `error`: the default value is `"error"`. Change the name of the `error` field in the returned State. Usage is the same as `result`.
+
+- `combineMode`: the default value is `"merge"`。get fulfilled state results. There are two ways to deal with it (The data types that can be automatically processed here are also limited to simple object or array types):
+
+  - `"merge"`: the previous data is merged with the current data. the data is an array type, operation is similar to `[].concat(lastData, currentData)`. the data is an object，operation is similar to `{...lastData, ...curData}`.
+  - `"replace"`: the current data directly replaces the previous data.
+
+- `omitResultNamespace`: the default value is `false`. When the result is an object type, you want to mount the result directly on the State of the Model, rather than on "result", you can set it to true. For example:
+
+```ts
+// the result: {user: 'xx', email: 'xx'}，
+// config handleEffect({ omitResultNamespace: true })
+// get State like follows:
+{
+  user: 'xx',
+  email: 'xx',
+  pending: false,
+  error: null,
+}
+```
+
+### Return Type
+
+Objects are processed by actions in pending, fulfilled, and rejected states.
+
+:::info More
+[Manage Effect](/guides/topic-detail/model/manage-effects).
+
+:::

package/en/apis/app/runtime/model/model_.mdx

@@ -0,0 +1,199 @@
+---
+sidebar_position: 1
+title: model
+---
+# model
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip
+The original type of Reduck is complex. The following type definition shows the simplified type information. For the original type, see [**model**](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/model.ts)。
+
+:::
+
+## model
+
+Create a Model for managing application state.
+
+`function model(name: string): { define: function }`
+
+- name: `string`, the unique id of the Model created.
+
+```ts title="example"
+model('foo');
+```
+
+## define
+
+Used to define the detailed structure of the Model, supporting passing in an object type or function type parameter.
+
+### Object Type
+
+`function define(modelDesc: ModelDesc): Model;`
+
+- modelDesc: `ModelDesc`，definition of Model structure，includes `state`、`computed`、`actions`、`effects` etc. props.
+
+```tsx title="example"
+const fooModel = model('foo').define({
+  state: 'foo',
+  computed: {
+    cFoo: state => `c${state}`,
+  },
+  actions: {
+    setState: (state, value) => {
+      return value;
+    },
+  },
+  effects: {
+    loadState: async () => {
+      // get state from remote
+    },
+  },
+});
+```
+
+### Function Type
+
+`function define((context: Context, utils: Utils) => ModelDesc): Model;`
+
+- `context`: Reduck Context, can get underlying `store` object. `store` support all Redux Store [API](https://redux.js.org/api/store), also mounts the `use` method for consuming the Model, and the `unmount` method for unmounting the Model.
+- utils: commonly used tool like `use`、`onMount`. `use` is the same as `store.use`，`onMount` is the hook function after the Model is mounted.
+
+{/* TODO: @anchao 调整类型  */}
+```ts
+interface Utils {
+  use: UseModel;
+  onMount: OnMountHook;
+}
+
+interface Context {
+  store: ReduxStore & {
+    use: UseModel;
+    unmount: (model: Model) => void;
+  };
+}
+```
+
+For example, through `use`, you can get the `state` and `actions` of the Model itself and other Models.
+
+```tsx title="example"
+const fooModel = model('foo').define(() => {
+  return {
+    state: 'foo',
+    actions: {
+      setState: (state, value) => {
+        return value;
+      },
+    },
+  };
+});
+
+const barModel = model('bar').define((_, { use }) => {
+  return {
+    state: 'bar',
+    effects: {
+      syncFoo() {
+        const [state, actions] = use(fooModel);
+        actions.setState(state);
+      },
+    },
+  };
+});
+```
+
+### Input
+
+#### ModelDesc.state
+
+Define the state of the Model. Technically, any type of **State** is supported, but in practice it is recommended to use a JSON serializable type.
+
+```ts
+interface ModelDesc {
+  state: any;
+}
+```
+
+#### ModelDesc.actions
+
+Define the Actions of the Model. The function type of Actions is:
+
+```ts
+interface ModelDesc {
+  actions: {
+    [actionKey: string]: (state: State, payload: any) => State | void;
+  };
+}
+```
+
+Reduck internally integrates [immer](https://github.com/immerjs/immer), which can directly return the original `state`. When the Action has no explicit return value, Reduck internally returns a modified new State object.
+
+#### ModelDesc.computed
+
+Defines the derived state of the Model. The definition of derived state supports two types:
+
+1. Depends only on the state of the Model itself
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: (state: State) => any;
+  };
+}
+```
+
+2. Depends on the state of other Models
+
+```ts
+interface ModelDesc {
+  computed: {
+    [computedKey: string]: [
+      ...models: Model[],
+      (state: State, ...args: ModelState[]) => any,
+    ];
+  };
+}
+```
+
+```ts title="example"
+const fooModel = model('foo').define({
+  state: 'foo',
+});
+
+const barModel = model('bar').define({
+  state: 'bar',
+  computed: {
+    combineFoo: [fooModel, (state, fooState) => state + fooState],
+  },
+});
+```
+
+#### ModelDesc.effects
+
+Defines the Effects of the Model. The function types defined in Effects are:
+
+```ts
+interface ModelDesc {
+  effects: {
+    [effectKey: string]: (...args: any[]) => any;
+  };
+}
+```
+
+```ts title="example"
+const fooModel = model('foo').define((context, { use }) => ({
+  state: 'foo',
+  effects: {
+    persist() {
+      const [state] = use(fooModel);
+      localStorage.setItem('state', state);
+    },
+  },
+}));
+```
+
+:::info More
+[Define Model](/guides/topic-detail/model/define-model).
+
+:::

package/en/apis/app/runtime/model/use-local-model.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+title: useLocalModel
+---
+# useLocalModel
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+To use the State in the Model as a local state, the effect is similar to React's `useState`. `useLocalModel` API same as `useModel`. For detail, see [`useModel`](./use-model.md)。
+
+## Example
+
+```tsx
+function Container() {
+  const [state, actions] = useLocalModel(modelA);
+  const [state1, actions1] = useLocalModel(modelA);
+
+  // ...
+}
+```
+
+`modelA` was loaded twice with useLocalModel above, because useLocalModel consumes local state, so state and state1 are also completely isolated.
+
+:::info More
+[Use Model](/guides/topic-detail/model/use-model).
+
+:::

package/en/apis/app/runtime/model/use-model.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+title: useModel
+---
+# useModel
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+:::tip
+The original type of Reduck is complex. The following type definition shows the simplified type information. For the original type, see [**model**](https://github.com/modern-js-dev/reduck/blob/main/packages/store/src/model/model.ts)。
+
+:::
+
+## Function Signature
+
+```ts
+function useModel(
+  models: Models[],
+  stateSelector?: StateSelector,
+  actionSelector?: ActionSelector,
+): [state, actions, subscribe];
+function useModel(
+  ...models: Models[],
+  stateSelector?: (...args: State[]) => any,
+  actionSelector?: (...args: Actions[]) => any,
+): [state, actions, subscribe];
+```
+
+### Input
+
+- models: Array of Model objects, which can be passed in as an array type parameter, or all Models can be passed in as parameters one by one.
+- stateSelector: Optional parameters, used to filter State calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the first element of the `useModel` return value array.
+- actionSelector: Optional parameters, used to filter Action calculations. The first n parameters are the States corresponding to n Models, and the returned data is used as the second element of the `useModel` return value array.
+
+### Return Value
+
+Returns an array with each value:
+
+- state: return value of `stateSelector`. if there is no `stateSelector`，will combine all incoming Model States(including derived states) and return them. If there is an attribute of the same name in the State of different Models, the following State will override the previous State. when `state` changes，the component call `useModel` will re-render.
+- actions: return value of `actionSelector`. if there is no `actionSelector`，will combine all incoming Model Action(including Effect) and return them. If there is an attribute of the same name in the Action of different Models, the following Action will override the previous Action.
+- subscribe: A function that subscribes to State changes. This function is called when the State of any Model passed in changes.
+
+## Example
+
+### Basic
+
+```tsx
+import todoModel from 'models/todo';
+import filterModel from 'models/filter';
+
+function Test(props) {
+  const [state, actions] = useModel([todoModel, filterModel]);
+  actions.add(); // call todoModel add action
+  actions.setVisibleStatus(); // call filterModel filterModel action
+
+  state.items; // get todoModel state items
+  state.visibleStatus; // get filterModel state visibleStatus
+}
+```
+
+### Selector Usage
+
+```js
+function Test(props) {
+  const [state, actions] = useModel(
+    [todoModel, filterModel],
+    (todoState, filterState) => ({
+      items: todoState.items,
+      visibleStatus: `${props.prefix}-${filterState.visibleStatus}`,
+    }),
+    (todoActions, filterActions) => ({
+      ...todoActions,
+      ...filterActions,
+    }),
+  );
+  actions.add(); // call todoModel add action
+  actions.setVisibleStatus(); // call filterModel filterModel action
+
+  state.items; // get todoModel state items
+  state.visibleStatus; // get filterModel state visibleStatus
+}
+```
+
+:::info More
+[use Model](/guides/topic-detail/model/use-model).
+
+:::

package/en/apis/app/runtime/model/use-static-model.mdx

@@ -0,0 +1,51 @@
+---
+sidebar_position: 3
+title: useStaticModel
+---
+# useStaticModel
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+If want to consume a Model in the form of React Hook in the component，and can get the current latest state at any time，but you don't want the Model state to be updated, which will cause the component to be re-rendered, we can use `useStaticModel`。
+
+`useStaticModel` API is same as `useModel`。For detail, see [`useModel`](./use-model.md)。
+
+To ensure that the latest state is always available, be careful not to deconstruct the returned `state`.
+
+```tsx
+function App() {
+  // ❌ Do not deconstruct state，but can deconstruct actions。
+  const [{ username }, { logout }] = useStaticModel(userModel);
+
+  // ✅ True Usage。
+  const [state, { logout }] = useStaticModel(userModel);
+
+  useEffect(() => {
+    state.username;
+  }, []);
+}
+```
+
+## Example
+
+The following `App` component consumes the `userModel` state, but does not use it directly in JSX. It can be found that changes in the `userModel` state do not necessarily cause the component to re-render. This situation can be optimized using `useStaticModel`.
+
+```tsx
+function App() {
+  const [state] = useStaticModel(userModel);
+
+  useEffect(() => {
+    // 统计 UV 数据
+    send('pageview', { user: state.user });
+  }, [state]);
+
+  return <div>Hello</div>;
+}
+```
+
+:::info More
+[Use Model](/guides/topic-detail/model/use-model).
+
+:::

package/en/apis/app/runtime/model/use-store.mdx

@@ -0,0 +1,26 @@
+---
+sidebar_position: 9
+title: useStore
+---
+# useStore
+
+import ReduckTip from "@site-docs-en/components/reduck-tip"
+
+<ReduckTip />
+
+`useStore` Used to get the store shared by the current component tree.
+
+## Function Signature
+
+```ts
+function useStore(): ReduckStore;
+```
+
+### Return Type
+
+- ReduckStore: Reduck Store，type refer to the return type of [createStore](./create-store.md).
+
+:::info More
+[Use Model](/guides/topic-detail/model/use-model).
+
+:::