@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/apis/app/runtime/model/model_.md

@@ -1,199 +0,0 @@
----
-sidebar_position: 1
-title: model
----
-
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [**model**](https://github.com/modern-js-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](/docs/guides/topic-detail/model/define-model)
-:::

package/zh/apis/app/runtime/model/use-local-model.md

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

package/zh/apis/app/runtime/model/use-model.md

@@ -1,86 +0,0 @@
----
-sidebar_position: 2
-title: useModel
----
-
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-
-<ReduckTip />
-
-:::tip 提示
-Reduck 原始类型较为复杂，以下涉及类型定义的地方，展示的是简化后的类型信息。原始类型见 [model](https://github.com/modern-js-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](/docs/guides/topic-detail/model/use-model)
-:::

package/zh/apis/app/runtime/model/use-static-model.md

@@ -1,47 +0,0 @@
----
-sidebar_position: 3
-title: useStaticModel
----
-
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-
-<ReduckTip />
-
-如果想在组件里以 React Hook 的形式消费某个 Model，并能随时获取到当前最新的状态，但又不希望 Model 状态更新的时候，引起组件的重新渲染，可以使用 `useStaticModel`。`useStaticModel` API 形式上与 `useModel` 完全一致。具体使用请参考 [`useModel`](./use-model.md)。
-
-为了保证总是能获取到最新状态，注意不要对返回的 `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](/docs/guides/topic-detail/model/use-model)
-:::

package/zh/apis/app/runtime/model/use-store.md

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

package/zh/apis/app/runtime/router/router.md

@@ -1,290 +0,0 @@
----
-title: router
-sidebar_position: 1
----
-
-:::info 补充信息
-基于 [react-router](https://reactrouter.com/) 的路由解决方案。
-:::
-
-## hooks
-
-### useNavigate
-
-```ts
-declare function useNavigate(): NavigateFunction;
-
-interface NavigateFunction {
-  (
-    to: To,
-    options?: {
-      replace?: boolean;
-      state?: any;
-      relative?: RelativeRoutingType;
-    }
-  ): void;
-  (delta: number): void;
-}
-```
-
-`useNavigate` 返回一个可以用于执行导航操作的函数。
-
-```tsx
-import { useNavigate } from "@modern-js/runtime/router";
-
-export function HomeButton() {
-  let navigate = useNavigate();
-
-  function handleClick() {
-    navigate("/home");
-  }
-
-  return (
-    <button type="button" onClick={handleClick}>
-      Go home
-    </button>
-  );
-}
-```
-
-### useLocation
-
-```ts
-declare function useLocation(): Location;
-
-interface Location extends Path {
-  state: unknown;
-  key: Key;
-}
-```
-
-`useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
-
-```ts
-import { useLocation } from "@modern-js/runtime/router";
-
-function usePageViews() {
-  let location = useLocation();
-  React.useEffect(() => {
-    ga.send(["pageview", location.pathname]);
-  }, [location]);
-}
-
-function App() {
-  usePageViews();
-  return (
-    //...
-  );
-}
-```
-
-### useParams
-
-```ts
-declare function useParams<
-  K extends string = string
->(): Readonly<Params<K>>;
-```
-
-`useParams` 返回一个 key/value 的键值对，表示当前匹配的路由 `<Route path>` 中的参数信息。
-
-```tsx
-import {
-  Switch,
-  Route,
-  useParams
-} from "@modern-js/runtime/router";
-
-function BlogPost() {
-  const { slug } = useParams();
-  return <div>Now showing post {slug}</div>;
-}
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/" element={ <div>home</div> } />
-      <Route path="/blog/:slug" element={ <BlogPost />}/>
-    </Routes>
-  )
-}
-```
-
-## 组件
-
-### Link
-
-```ts
-declare function Link(props: LinkProps): React.ReactElement;
-
-interface LinkProps
-  extends Omit<
-    React.AnchorHTMLAttributes<HTMLAnchorElement>,
-    "href"
-  > {
-  replace?: boolean;
-  state?: any;
-  to: To;
-  reloadDocument?: boolean;
-}
-
-type To = string | Partial<Path>;
-```
-
-可以使用 `Link` 组件进行路由跳转。
-
-```ts
-<Link to="/about">About</Link>
-```
-
-### NavLink
-
-```ts
-declare function NavLink(
-  props: NavLinkProps
-): React.ReactElement;
-
-interface NavLinkProps
-  extends Omit<
-    LinkProps,
-    "className" | "style" | "children"
-  > {
-  caseSensitive?: boolean;
-  children?:
-    | React.ReactNode
-    | ((props: { isActive: boolean }) => React.ReactNode);
-  className?:
-    | string
-    | ((props: {
-        isActive: boolean;
-      }) => string | undefined);
-  end?: boolean;
-  style?:
-    | React.CSSProperties
-    | ((props: {
-        isActive: boolean;
-      }) => React.CSSProperties);
-}
-```
-
-`<NavLink>` 是一种特殊的 `<Link>`，当 `<NavLink>` 对应的链接和当前 URL 匹配时，会给 `<NavLink>` 所渲染的元素添加“激活”态样式。
-
-
-### Outlet
-
-```ts
-interface OutletProps {
-  context?: unknown;
-}
-declare function Outlet(
-  props: OutletProps
-): React.ReactElement | null;
-```
-
-`<Outlet>` 用于嵌套路由场景。在父路由的元素中使用，代表待渲染的子路由的元素在父组件中的位置。
-
-```tsx
-function Dashboard() {
-  return (
-    <div>
-      <h1>Dashboard</h1>
-
-      {/* This element will render either <DashboardMessages> when the URL is
-          "/messages", <DashboardTasks> at "/tasks", or null if it is "/"
-      */}
-      <Outlet />
-    </div>
-  );
-}
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/" element={<Dashboard />}>
-        <Route
-          path="messages"
-          element={<DashboardMessages />}
-        />
-        <Route path="tasks" element={<DashboardTasks />} />
-      </Route>
-    </Routes>
-  );
-}
-```
-
-### Route
-
-```ts
-interface RouteObject {
-  path?: string;
-  index?: boolean;
-  children?: React.ReactNode;
-  caseSensitive?: boolean;
-  id?: string;
-  loader?: LoaderFunction;
-  action?: ActionFunction;
-  element?: React.ReactNode | null;
-  errorElement?: React.ReactNode | null;
-  handle?: RouteObject["handle"];
-  shouldRevalidate?: ShouldRevalidateFunction;
-}
-```
-
-`Route` 用于定义路由。一个 `Route` 对象，将 URL 片段和组件、数据获取关联起来。
-
-`Route` 可以作为普通对象，传给创建 router 的函数的参数：
-
-```ts
-const router = createBrowserRouter([
-  {
-    // it renders this element
-    element: <Team />,
-
-    // when the URL matches this segment
-    path: "teams/:teamId",
-
-    // with this data loaded before rendering
-    loader: async ({ request, params }) => {
-      return fetch(
-        `/fake/api/teams/${params.teamId}.json`,
-        { signal: request.signal }
-      );
-    },
-
-    // performing this mutation when data is submitted to it
-    action: async ({ request }) => {
-      return updateFakeTeam(await request.formData());
-    },
-
-    // and renders this element in case something went wrong
-    errorElement: <ErrorBoundary />,
-  },
-]);
-```
-
-`Route` 还可以作为组件使用，通过 `createRoutesFromElements` 转换后，再传给创建 router 的函数的参数：
-
-```ts
-const router = createBrowserRouter(
-  createRoutesFromElements(
-    <Route
-      element={<Team />}
-      path="teams/:teamId"
-      loader={async ({ params }) => {
-        return fetch(
-          `/fake/api/teams/${params.teamId}.json`
-        );
-      }}
-      action={async ({ request }) => {
-        return updateFakeTeam(await request.formData());
-      }}
-      errorElement={<ErrorBoundary />}
-    />
-  )
-);
-```
-
-## 更多 API
-
-若想要了解完整的路由 API 信息，可至 [react-router 官网](https://reactrouter.com/web/guides/start) 查看。
-

package/zh/apis/app/runtime/ssr/no-ssr.md

@@ -1,41 +0,0 @@
----
-title: NoSSR
----
-
-被 NoSSR 包裹的内容在服务端不会进行渲染，在客户端 hydrate 阶段也不会渲染，等到整个 App 渲染完成后便会立即渲染。
-
-## 使用姿势
-
-```tsx
-import { NoSSR } from '@modern-js/runtime';
-
-export default () => (
-  <NoSSR>
-    ...
-  </NoSSR>
-)
-```
-
-## 示例
-
-下列代码中，`Time` 组件用于展示当前的时间，由于服务端渲染和客户端 hydrate 时获取到的时间是不一致的，React 就会抛出异常。针对这种情况可以使用 `NoSSR` 进行优化：
-
-```tsx
-import { NoSSR } from '@modern-js/runtime';
-
-function Time() {
-  return (
-    <NoSSR>
-      <div>Time: {Date.now()}</div>
-    </NoSSR>
-  );
-}
-```
-
-## 使用场景
-
-在 CSR 中，常常需要根据当前浏览器 UA，或是当前页面 URL 的某个参数的不同，来渲染不同的内容。如果此时应用直接切换到 SSR，很有可能出现不符合预期的结果。
-
-Modern.js 在 SSR 上下文中提供了完整的浏览器端信息，可以利用上下文信息来决定组件在服务端的渲染结果。
-
-即便如此，如果应用里有太多的判断，开发者希望以后再使用上下文，或者不希望某些内容在服务端被渲染，可以使用 NoSSR 组件将这一部分剔除在服务端渲染外。