@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/zh/apis/app/runtime/core/use-runtime-context.mdx

@@ -1,116 +0,0 @@
-# useRuntimeContext
-
-该函数主要用于获取 Runtime 上下文，只能在函数组件中使用。
-
-## 使用姿势
-
-```tsx
-import { useRuntimeContext } from '@modern-js/runtime';
-
-export function App() {
-  const runtimeContext = useRuntimeContext();
-  return <div>Hello World</div>
-}
-```
-
-## 函数签名
-
-```ts
-type RuntimeContext = {
-  context: RequestContext;
-};
-```
-
-### context
-
-用于获取[请求上下文](#请求上下文)。
-
-## 使用示例
-
-### 区分运行环境
-
-```ts
-function App() {
-  const { context } = useRuntimeContext();
-
-  if (context.isBrowser === true) {
-    // 浏览器端执行逻辑
-    console.log('browser render')
-  } else {
-    // 服务器端执行逻辑 logger 功能需开启
-    context.logger.info('server render')
-  }
-}
-```
-
-### 请求上下文
-
-开启 SSR 时，在 Node 环境和浏览器端环境可以获取到同构的请求上下文。
-
-稍有不同的是 Node 环境还支持设置响应头、响应码，并提供了 Logger 日志与 Metrics 打点。
-
-:::tip
-当 SSR 未开启时，仅包含可在浏览器端获取的部分信息。
-
-:::
-
-import { Tabs, Tab as TabItem } from "@theme";
-
-<Tabs
-  defaultValue="RequestContext"
-  values={[
-    { label: 'RequestContext', value: 'RequestContext', },
-    { label: 'ServerContext', value: 'ServerContext', },
-    { label: 'ClientContext', value: 'ClientContext', },
-  ]
-}>
-<TabItem value="RequestContext">
-
-```ts
-type RequestContext = ServerContext | ClientContext;
-```
-
-</TabItem>
-<TabItem value="ServerContext">
-
-```ts
-interface ServerContext {
-  isBrowser: false;
-  request: {
-    userAgent: string;
-    cookie: string;
-    cookieMap: Record<string, any>;
-    query: Record<string, any>;
-    url: string;
-    host: string;
-    headers?: IncomingHttpHeaders;
-  };
-  response: {
-    setHeader: (key: string, value: string) => void;
-    status: (code: number) => void;
-  };
-  logger: Logger;
-  metrics: Metrics;
-}
-```
-
-</TabItem>
-<TabItem value="ClientContext">
-
-```ts
-interface ClientContext {
-  isBrowser: true;
-  request: {
-    userAgent: string;
-    cookie: string;
-    cookieMap: Record<string, any>;
-    query: Record<string, any>;
-    url: string;
-    host: string;
-    headers?: IncomingHttpHeaders;
-  };
-}
-```
-
-</TabItem>
-</Tabs>

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

@@ -1,36 +0,0 @@
----
-sidebar_position: 8
-title: Provider
----
-# Provider
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-`Provider` 是一个组件，它将 Reduck 的 Store 注入到应用的组件树中，使组件树内部的组件可以访问 Model。一般情况下，`Provider` 会定义在组件树的最顶层。
-
-## 函数签名
-
-```ts
-interface ProviderProps {
-  store?: ReduckStore;
-  config?: AppConfig;
-}
-```
-
-### 参数
-
-- store：[`createStore`](./create-store.mdx) 创建的 Store 对象。
-- config：创建 Reduck Store 的配置，同 [`createApp`](./create-app.mdx) 的 `config` 参数。
-
-## 示例
-
-```tsx title="应用入口文件"
-ReactDOM.render(
-  <Provider>
-    <App />
-  </Provider>,
-  document.getElementById('root'),
-);
-```

package/docs/zh/apis/app/runtime/model/auto-actions.mdx

@@ -1,122 +0,0 @@
----
-sidebar_position: 6
-title: Auto actions
----
-# Auto actions
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-Reduck 可以根据 State 的类型，自动生成相应的 Actions，为修改 State 提供便利。
-
-:::tip 提示
-可通过 [`runtime.state.autoActions`](/configure/app/runtime/state#autoactions) 关闭 auto actions 功能。
-
-:::
-
-## 示例
-
-### 基础数据类型
-
-State 类型为 `string`、`number`、`boolean`、`null` 时，生成 `setState` Action。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: 1,
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-      <button
-        type="button"
-        onClick={() => {
-          // 调用自动生成的 setState Action
-          actions.setState(state + 1);
-        }}
-      >
-        add
-      </button>
-    </div>
-  );
-}
-```
-
-### 数组 Array
-
-State 类型为 Array 时，生成下列 Actions：
-
-- `push`：将一个或多个元素添加到数组的末尾。
-- `pop`：从数组中删除最后一个元素。
-- `shift`：从数组中删除第一个元素。
-- `unshift`：将一个或多个元素添加到数组的开头。
-  - 语法：`arr.unshift(element1, ..., elementN)`
-  - `elementN`：要添加到数组开头的元素或多个元素。
-- `filter`：过滤元素。
-{/* 语义与原生方法不同，待修改 API  */}
-- `concat`：拼接数组。
-{/* 语义与原生方法不同，待修改 API  */}
-- `splice`：通过删除或替换现有元素或者原地添加新的元素来修改数组，并以数组形式返回修改后的数组（注意和原生 `splice` 返回值不同）。
-  - 语法：`splice(start[, deleteCount[, item1[, item2[, ...]]]])`
-  - `start`：指定修改的开始位置（从 0 计数）。
-  - `deleteCount`：可选，整数，表示要移除的数组元素的个数。
-  - `item, item2, ...`：可选，要添加进数组的元素，从 start 位置开始。如果不指定，则 `splice` 将只删除数组元素。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: [1, 2, 3],
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.push(4);
-    actions.pop();
-    actions.shift(0);
-    actions.unshift();
-    actions.filter(val => val <= 2);
-    actions.splice(0, 1, 1, 2);
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```
-
-### 简单对象 PlainObject
-
-State 类型为 PlainObject 时，根据 State 包含的属性名，生成 `set${key}`（小驼峰命名）Actions。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: {
-    a: 1,
-    b: { value: 1 },
-    c: 'c',
-  },
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.setA(2);
-    actions.setB({ value: 2 });
-    actions.setC('d');
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```

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

@@ -1,143 +0,0 @@
----
-sidebar_position: 5
-title: connect
----
-# connect
-
-import ReduckTip from "@site-docs/components/reduck-tip"
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**connect**](https://github.com/web-infra-dev/reduck/blob/main/packages/react/src/connect.ts)。
-
-:::
-
-`connect` 功能上同 `useModel` 一致，是对应的 HOC 风格的 API。建议优先使用 Hook 风格的 `useModel`。
-
-## 类型
-
-```ts
-type SelectStateToProps = (
-  ...modelStates: State[],
-  ownProps?: any,
-) => PlainObject;
-type SelectActionsToProps = (
-  ...modelActions: Actions[],
-  ownProps?: any,
-) => PlainObject;
-
-function connect(models: Model, options?: ConnectOptions);
-function connect(
-  models: [...Model[], SelectStateToProps?, SelectActionsToProps?],
-  options?: ConnectOptions,
-);
-```
-
-## 参数
-
-- `models`：传入的 1 个或多个 Model，当 `models` 为数组类型参数时，最后两项元素可以是用于筛选 State 的函数（ `SelectStateToProps` 类型）和用于筛选 Actions 的函数（ `SelectActionsToProps` 类型）。
-  - `SelectStateToProps`： `modelStates` 是传入的 Model 对象的 State 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectStateToProps` 返回的数据会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectStateToProps` 参数时，所有 Model 的 State 进行合并后传递到组件的 `props` 上。
-  - `SelectActionsToProps`： `modelActions` 是传入的 Model 对象的 Actions 组成的数组，`ownProps` 是当前组件接收外部传递的 `props`，`SelectActionsToProps` 返回的数据也会传递到组件的 `props` 上。当 `models` 中没有传入 `SelectActionsToProps` 参数时，所有 Model 的 Actions 进行合并后传递到组件的 `props` 上。
-
-- `options`：可选参数，用于辅助配置。目前支持设置 `forwardRef`，用于控制是否转发组件的 `ref`，默认值为 `false`，表示不转发 `ref`。设置为 `{forwardRef: true}`，表示转发 `ref`。
-
-## 返回值
-
-返回一个高阶组件：接收一个传入的组件，返回一个在 `props` 上注入了额外 State 和 Actions 的组件。
-
-## 示例
-
-### 简单用法
-
-```ts
-const modelA = model('modelA').define({
-  state: {
-    a: 1,
-  },
-  actions: {
-    incA(state) {
-      return {
-        ...state,
-        a: state.a + 1,
-      };
-    },
-  },
-});
-
-const modelB = model('modelB').define({
-  state: {
-    b: 10,
-  },
-  actions: {
-    incB(state) {
-      return {
-        ...state,
-        b: state.b + 1,
-      };
-    },
-  },
-});
-
-function Test(props) {
-  props.incA(); // 调用 modelA 的 action
-  props.incB(); // 调用 modelB 的 action
-
-  props.a; // 获取 modelA 的 state: a
-  props.b; // 获取 modelB 的 state: b
-}
-
-export default connect([modelA, modelB])(Test);
-```
-
-### 筛选 State 和 Actions
-
-```ts
-function Test(props) {
-  props.incAll();
-  props.c;
-}
-
-const stateSelector = (stateA, stateB) => ({
-  ...stateA,
-  ...stateB,
-  c: stateA.a + stateA.b,
-});
-const actionsSelector = (actionsA, actionsB) => ({
-  ...actionsA,
-  ...actionsB,
-  incAll: () => {
-    actionsA.incA();
-    actionsB.incB();
-  },
-});
-
-export default connect([modelA, modelB, stateSelector, actionsSelector])(Test);
-```
-
-### 转发组件的 ref
-
-```ts
-import { useRef, forwardRef } from 'react';
-
-function Test(props, ref) {
-  const { a, b } = props;
-
-  return (
-    <div ref={ref}>
-      <span>{a}</span>
-      <span>{b}</span>
-    </div>
-  );
-}
-
-const TestWrapper = connect([modelA, modelB], { forwardRef: true })(
-  forwardRef(Test),
-);
-
-function App() {
-  const testRef = useRef();
-
-  return <TestWrapper ref={testRef} />;
-}
-```

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)
-
-:::