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

package/docs/zh/apis/app/runtime/model/create-app.mdx

@@ -1,75 +0,0 @@
----
-sidebar_position: 11
-title: createApp
----
-# createApp
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-Reduck 内部默认会使用 `createApp` 创建一个全局应用，如果整个应用只需要共享一个 Store，那么是不需要使用 `createApp` 的。只有当需要在应用局部创建共享 Store 时，才需要使用 `createApp`。
-
-:::caution 注意
-注意 `@modern-js/runtime/model` 中导出的 `createApp` 用于管理状态，而 `@modern-js/runtime` 导出的 `createApp` 用于管理整个应用的运行时环境，两者功能不同。
-
-:::
-
-## 函数签名
-
-```ts
-interface AppConfig extends StoreConfig {
-  devTools?: boolean | DevToolsOptions;
-  autoActions?: boolean;
-}
-
-function createApp(config: AppConfig): object;
-```
-
-### 参数
-
-- config：`Record<string, any>`
-  - StoreConfig：同 [`createStore`](./create-store.mdx) 的参数。
-  - devTools：默认值为 true。是否开启 Redux DevTools，当为对象类型时，支持配置 Redux DevTools 的 [Options](https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md)。
-  - autoActions：默认值为 true。是否[自动生成 Actions](./auto-actions.mdx)。
-
-### 返回值
-
-Reduck App，有以下属性组成：
-
-- Provider：为应用局部的组件树注入共享 Store 的组件。用法同 [`Provider`](./Provider.mdx)。
-- useModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useModel`](./use-model.mdx)。
-- useStaticModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useStaticModel`](./use-static-model.mdx)。
-- useLocalModel：获取应用局部 Store 挂载的 Model 对象。用法同 [`useLocalModel`](./use-local-model.mdx)。
-- useStore：获取应用局部使用的 Store 对象。用法同 [`useStore`](./use-store.mdx)。
-
-## 示例
-
-通过 `createApp` 可以创建局部状态，将不同 Reduck 应用间的状态隔离。
-
-```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/docs/zh/apis/app/runtime/model/create-store.mdx

@@ -1,61 +0,0 @@
----
-sidebar_position: 10
-title: createStore
----
-# createStore
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-`createStore` 用于创建一个 Store 对象。Reduck 的 Store 基于 Redux 的 [Store](https://redux.js.org/api/store) 实现，用于存储应用的状态，同时提供一组用于管理状态和 Model 的方法。
-
-一般情况下，不需要使用这个 API，只有需要完全掌控 Store 的创建时，才会使用这个 API。例如，自定义一个 Store，传入 [`Provider`](./Provider.mdx) 组件使用。
-
-## 函数签名
-
-```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;
-```
-
-### 参数
-
-- config?：store 配置选项
-  - initialState?: 设置全局 Store 的初始状态。
-  - models?: 设置提前（Store 创建后）挂载到 Store 的 Model。（正常使用无需提前挂载）
-  - middlewares?: 设置 Redux [中间件](https://redux.js.org/understanding/thinking-in-redux/glossary#middleware)。
-  - enhancers?: 设置 Redux 的 [Store enhancer](https://redux.js.org/understanding/thinking-in-redux/glossary#store-enhancer) 。
-  - plugins?: 设置 Reduck 插件。**_试验性配置，不推荐使用_**。
-
-### 返回值
-
-Reduck Store 对象：
-
-- use：动态挂载和获取 Model 对象。用法与 [`useModel`](./use-model.mdx) 相同，但可以在 React 组件外使用。
-- unmount：卸载 Model 对象，Model 的 State 会从 Store 中清除。
-- ReduxStore：Redux Store 对象具有的方法，[详见](https://redux.js.org/tutorials/fundamentals/part-4-store#redux-store)。
-
-## 示例
-
-```tsx
-const store = createStore();
-
-function load() {
-  const [, actions] = store.use(fooModel);
-
-  actions.load();
-}
-```

package/docs/zh/apis/app/runtime/model/handle-effect.mdx

@@ -1,108 +0,0 @@
----
-sidebar_position: 7
-title: handleEffect
----
-
-# handleEffect
-
-import ReduckTip from '@site-docs/components/reduck-tip';
-
-<ReduckTip />
-
-一个异步函数类型的 Effect，通常有三种需要处理的状态: 请求中、请求成功、请求处理失败。这些状态处理的方式，就是编写对应的 Action 函数(pending、fulfilled、rejected)。
-
-借助 `handleEffect` API，我们可以生成默认的 Action 函数来处理异步请求各个阶段的不同结果。`handleEffect` 生成的 Action 返回的 State 的结构如下：
-
-```ts
-interface State {
-  result: any; // 存储 fulfilled 状态的返回结果
-  pending: boolean; // 请求是否结束
-  error: string; // 请求失败的结果
-}
-```
-
-## 函数签名
-
-```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;
-```
-
-### 参数
-
-- ns：默认返回的 State 结构扁平地挂载到 Model 的 State 上，通过设置该参数可以将返回的 State 挂载到 `ns` 值命名的字段下。例如，`ns` 设置为 `data`，返回的 State 结构为：
-
-```ts
-interface State {
-  data: {
-    pending: boolean;
-    result: any;
-    error: string;
-  };
-}
-```
-
-- result：默认值为 `"result"`。该参数对应存储异步请求 fulfilled 状态结果的字段名称。例如，设置 `result` 为 `"items"`，返回的 State 结构为：
-
-```ts
-interface State {
-  items: any; // 默认的 result -> items
-  pending: boolean;
-  error: string;
-}
-```
-
-`result` 为 `false`，返回的 State 结构中不存在 `result`：
-
-```ts
-interface State {
-  pending: boolean;
-  error: string;
-}
-```
-
-- pending：默认值为 `"pending"`。改变返回 State 中的 `pending` 字段名。用法同上。
-
-- error： 默认值为 `"error"`。改变返回 State 中的 `error` 字段名。用法同上。
-
-- combineMode：默认值为 `"merge"`。获取 fulfilled 状态的返回数据后，对 `result` 的处理方式：merge（合并）和 replace（替换）。这里能自动处理的数据类型也仅限为简单的对象或者数组类型。
-
-  - merge：前一次的数据与当前的数据合并。数据为数组类型，内部操作类似于 `[].concat(lastData, currentData)`；数据为对象类型，内部操作类似于 `{...lastData, ...curData}`。
-  - replace：当前的数据直接替换之前的数据。
-
-- omitResultNamespace：默认值为 `"false"`。当异步请求的结果为对象类型，希望把该结果直接挂载到 Model 的 State 上，而不是挂载到 `"result"` 上，可以设置为 true。例如：
-
-```ts
-// 一个异步请求得到的数据为一个对象：{user: 'xx', email: 'xx'}，
-// 配置 handleEffect({ omitResultNamespace: true })
-// 则得到的 State 结构如下：
-{
-  user: 'xx',
-  email: 'xx',
-  pending: false,
-  error: null,
-}
-```
-
-### 返回值
-
-分别处理 pending、fulfilled、rejected 三种状态的 Action 组成的对象。
-
-:::info 更多参考
-[副作用管理](/guides/topic-detail/model/manage-effects)
-
-:::

package/docs/zh/apis/app/runtime/model/model_.mdx

@@ -1,201 +0,0 @@
----
-sidebar_position: 1
-title: model
----
-
-# model
-
-import ReduckTip from '@site-docs/components/reduck-tip';
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/model.ts)。
-
-:::
-
-## model
-
-用于创建管理应用状态的 Model。
-
-`function model(name: string): { define: function }`
-
-- name：`string`，创建的 Model 的唯一标识。
-
-```ts title="示例"
-model('foo');
-```
-
-## define
-
-用于定义 Model 的详细结构，支持传入一个对象类型或函数类型的参数。
-
-### 对象类型
-
-`function define(modelDesc: ModelDesc): Model;`
-
-- modelDesc: `ModelDesc`，对 Model 结构的定义，包含 `state`、`computed`、`actions`、`effects` 等属性。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: 'foo',
-  computed: {
-    cFoo: state => `c${state}`,
-  },
-  actions: {
-    setState: (state, value) => {
-      return value;
-    },
-  },
-  effects: {
-    loadState: async () => {
-      // 从服务端获取 state
-    },
-  },
-});
-```
-
-### 函数类型
-
-`function define((context: Context, utils: Utils) => ModelDesc): Model;`
-
-- context: Context，Reduck 上下文对象，可以获取底层的 `store` 对象。`store` 除支持 Redux Store 的所有 [API](https://redux.js.org/api/store) 以外，还挂载了用于消费 Model 的 `use` 的方法，和用于卸载 Model 的 `unmount` 方法。
-- utils: Utils，定义 Model 时，常用的工具函数：`use`、`onMount`。`use` 作用同 `store` 对象上的 `use`，`onMount` 是 Model 挂载后的钩子函数。
-
-{/* TODO: @anchao 调整类型 */}
-
-```ts
-interface Utils {
-  use: UseModel;
-  onMount: OnMountHook;
-}
-
-interface Context {
-  store: ReduxStore & {
-    use: UseModel;
-    unmount: (model: Model) => void;
-  };
-}
-```
-
-如通过 `use`，可以获取 Model 自身及其它 Model 的 `state`，`actions`。
-
-```tsx title="示例"
-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);
-      },
-    },
-  };
-});
-```
-
-### 参数
-
-#### ModelDesc.state
-
-定义 Model 的状态。技术上，支持任意类型的 **State**，但是实践中建议使用可进行 JSON 序列化的类型。
-
-```ts
-interface ModelDesc {
-  state: any;
-}
-```
-
-#### ModelDesc.actions
-
-定义 Model 的 Actions。Actions 的函数类型为：
-
-```ts
-interface ModelDesc {
-  actions: {
-    [actionKey: string]: (state: State, payload: any) => State | void;
-  };
-}
-```
-
-Reduck 内部集成了 [immer](https://github.com/immerjs/immer)，可以直接原始的 `state`，当 Action 没有显式返回值时，Reduck 内部会返回修改过的新的 State 对象。
-
-#### ModelDesc.computed
-
-定义 Model 的衍生状态。衍生状态的定义支持两种类型：
-
-1. 只依赖 Model 自身的状态
-
-```ts
-interface ModelDesc {
-  computed: {
-    [computedKey: string]: (state: State) => any;
-  };
-}
-```
-
-2. 依赖其他 Model 的状态
-
-```ts
-interface ModelDesc {
-  computed: {
-    [computedKey: string]: [
-      ...models: Model[],
-      (state: State, ...args: ModelState[]) => any,
-    ];
-  };
-}
-```
-
-```ts title="示例"
-const fooModel = model('foo').define({
-  state: 'foo',
-});
-
-const barModel = model('bar').define({
-  state: 'bar',
-  computed: {
-    combineFoo: [fooModel, (state, fooState) => state + fooState],
-  },
-});
-```
-
-#### ModelDesc.effects
-
-定义 Model 的 Effects。Effects 中定义的函数类型为：
-
-```ts
-interface ModelDesc {
-  effects: {
-    [effectKey: string]: (...args: any[]) => any;
-  };
-}
-```
-
-```ts title="示例"
-const fooModel = model('foo').define((context, { use }) => ({
-  state: 'foo',
-  effects: {
-    persist() {
-      const [state] = use(fooModel);
-      localStorage.setItem('state', state);
-    },
-  },
-}));
-```
-
-:::info 更多参考
-[创建 Model](/guides/topic-detail/model/define-model)
-
-:::

package/docs/zh/apis/app/runtime/model/use-local-model.mdx

@@ -1,29 +0,0 @@
----
-sidebar_position: 4
-title: useLocalModel
----
-# useLocalModel
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-用于把 Model 中的 State 作为局部状态使用，效果类似 React 的 `useState`。`useLocalModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.mdx)。
-
-#### 示例
-
-```tsx
-function Container() {
-  const [state, actions] = useLocalModel(modelA);
-  const [state1, actions1] = useLocalModel(modelA);
-
-  // ...
-}
-```
-
-上面通过 `useLocalModel` 加载了两次 `modelA`，因为 `useLocalModel` 消费的是局部状态，所以 `state` 和 `state1` 也是完全隔离的。
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/use-model)
-
-:::

package/docs/zh/apis/app/runtime/model/use-model.mdx

@@ -1,89 +0,0 @@
----
-sidebar_position: 2
-title: useModel
----
-# useModel
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/web-infra-dev/reduck/blob/main/packages/store/src/model/useModel.ts)。
-
-:::
-
-## 函数签名
-
-```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];
-```
-
-### 参数
-
-- models：Model 对象数组，可以作为一个数组类型的参数传入，也可以所有 Model 逐个作为参数传入。
-- stateSelector：可选参数，用于筛选 State 计算。前 n 个参数为 n 个 Model 对应的 State，返回的数据作为 `useModel` 返回值数组的第一个元素。
-- actionSelector：可选参数，用于筛选 Actions 计算。前 n 个参数为 n 个 Model 对应的 Actions，返回的数据作为 `useModel` 返回值数组的第二个元素。
-
-### 返回值
-
-返回一个数组，每一项元素分别为：
-
-- state：`stateSelector` 的返回值。如果未传 `stateSelector`，会把传入的所有 Model 的 State (包含衍生状态)合并后返回。如果不同 Model 的 State 中存在同名属性，后面的 State 会覆盖前面的 State。当 `state` 发生变化时，调用 `useModel` 的组件会重新渲染。
-- actions：第二个元素为 `actionSelector` 的返回值。如果未传 `actionSelector`，会把传入的所有 Model 的 Actions (包含 Effects) 合并后返回。如果不同 Model 的 Actions 中存在同名属性，后面的 Actions 会覆盖前面的 Actions。
-- subscribe：订阅 State 变化的函数。当传入的任意 Model 的 State 发生改变时，该函数会被调用。
-
-## 示例
-
-### 基本用法
-
-```tsx
-import todoModel from 'models/todo';
-import filterModel from 'models/filter';
-
-function Test(props) {
-  const [state, actions] = useModel([todoModel, filterModel]);
-  actions.add(); // 调用 todoModel add action
-  actions.setVisibleStatus(); // 调用 filterModel filterModel action
-
-  state.items; // 获取 todoModel state items
-  state.visibleStatus; // 获取 filterModel state visibleStatus
-}
-```
-
-### selector 用法
-
-```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(); // 调用 todoModel add action
-  actions.setVisibleStatus(); // 调用 filterModel filterModel action
-
-  state.items; // 获取 todoModel state items
-  state.visibleStatus; // 获取 filterModel state visibleStatus
-}
-```
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/use-model)
-
-:::

package/docs/zh/apis/app/runtime/model/use-static-model.mdx

@@ -1,49 +0,0 @@
----
-sidebar_position: 3
-title: useStaticModel
----
-# useStaticModel
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-如果想在组件里以 React Hook 的形式消费某个 Model，并能随时获取到当前最新的状态，但又不希望 Model 状态更新的时候，引起组件的重新渲染，可以使用 `useStaticModel`。`useStaticModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.mdx)。
-
-为了保证总是能获取到最新状态，注意不要对返回的 `state` 解构。
-
-```tsx
-function App() {
-  // ❌ 不能解构 state，但可以解构 actions。
-  const [{ username }, { logout }] = useStaticModel(userModel);
-
-  // ✅ 这才是正确使用姿势。
-  const [state, { logout }] = useStaticModel(userModel);
-
-  useEffect(() => {
-    state.username;
-  }, []);
-}
-```
-
-#### 示例
-
-如下 `App` 组件消费了 `userModel` 的状态，但没有直接在 JSX 里使用。可以发现，`userModel` 状态的改变没有必要引起组件重新渲染，这种情况可以使用 `useStaticModel` 进行优化。
-
-```tsx
-function App() {
-  const [state] = useStaticModel(userModel);
-
-  useEffect(() => {
-    // 统计 UV 数据
-    send('pageview', { user: state.user });
-  }, [state]);
-
-  return <div>Hello</div>;
-}
-```
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/use-model)
-
-:::

package/docs/zh/apis/app/runtime/model/use-store.mdx

@@ -1,26 +0,0 @@
----
-sidebar_position: 9
-title: useStore
----
-# useStore
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-`useStore` 用于获取当前组件树共享的 Store。常用于在组件外访问 Model 的场景。注意，`useStore` 是一个 React Hook，只能在组件内使用。
-
-## 函数签名
-
-```ts
-function useStore(): ReduckStore;
-```
-
-### 返回值
-
-- ReduckStore：Reduck Store，类型参考 [createStore](./create-store.mdx) 返回值。
-
-:::info 更多参考
-[使用 Model](/guides/topic-detail/model/use-model#在组件外使用)
-
-:::