@modern-js/main-doc 2.1.0 → 2.2.0

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,24 +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,260 +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,37 +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 组件将这一部分剔除在服务端渲染外。

package/zh/apis/app/runtime/ssr/pre-render.md

@@ -1,95 +0,0 @@
----
-title: PreRender
----
-
-无展示内容的高阶组件，通过类似 Helmet 的方式实现 SPA 路由级的缓存，无需额外配置。
-
-## 使用姿势
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default () => (
-  <>
-    <PreRender interval={5} />
-  </>
-);
-```
-
-## 函数签名
-
-`PreRender` 组件提供了一套常用的配置参数，用于控制缓存的规则、过期时间、缓存算法等。
-
-```tsx
-type Props {
-  interval: number;
-  staleLimit: number;
-  level: number;
-  include: { header?: string[], query?: string[] };
-  matches: { header?: Record<string, any>, query?: Record<string, any> }
-}
-
-function PreRender(props: Props): React.Component
-```
-
-### 参数
-
-- `interval`：设置缓存保持新鲜的时间，单位秒。在该时间内，将直接使用缓存，并且不做异步渲染。
-- `staleLimit`：设置缓存完全过期的时间，单位秒。在该时间内，缓存可以被返回，并且会做一步渲染，否则必须使用重新渲染的结果。
-- `level`：设置缓存标识的计算规则等级，通常配合 `includes` 与 `matches` 使用。默认值为 `0`。
-
-```bash
-0：路由路径
-1：路由路径 + 查询字符串
-2：路由路径 + 请求头
-3：路由路径 + 查询字符串 + 请求头
-```
-
-- `includes`：设置需要被纳入缓存标识的内容，在 level 非 0 时使用。默认值为 `null`。
-- `matches`：设置 query 或 header 的值在缓存标识计算中的重写规则，通常用在缓存分类时，支持正则表达式。默认值为 `null`。
-
-## 示例
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default function App() {
-  return (
-    <>
-      <PreRender interval={10} />
-      <div>Hello Modern</div>
-    </>
-  );
-}
-```
-
-下面例子展示了如何将 query、header 中指定的参数纳入缓存计算中：
-
-```tsx
-/* 使用 query 中的 channel 和 header 中的 language 计算缓存标识 */
-<PreRender
-  interval={10}
-  level={2}
-  includes={{
-    query: ['channel'],
-    header: ['language'],
-  }}
-/>
-```
-
-下面例子展示了如何不让测试频道影响线上缓存：
-
-```tsx
-/* 将 query 中 channel 值为 test_ 开头的重写为 testChannel，否则重写为 otherChannel */
-<PreRender interval={10} level={2} includes={{
-  query: ["channel"],
-  header: ["language"]
-}} matches={{
-  query: {
-    channel: {
-      "testChannel", "^test_",
-      "otherChannel", ".*"
-    }
-  }
-}} />
-```

package/zh/apis/app/runtime/testing/act.md

@@ -1,34 +0,0 @@
----
-title: act
----
-
-用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
-
-## 使用姿势
-
-```ts
-import { act } from '@modern-js/runtime/testing';
-```
-
-## 函数签名
-
-`act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
-
-## 示例
-
-```tsx
-import ReactDOM from 'react-dom';
-import { act } from '@modern-js/runtime/testing';
-import { Foo } from '@/components/Foo';
-
-describe('test act', () => {
-  it('it should be foo', () => {
-    const el = document.createElement('div');
-    act(() => {
-      ReactDOM.render(<Foo />, el);
-    });
-
-    expect(el.innerHTML).toBe('<div>Foo</div>');
-  });
-});
-```

package/zh/apis/app/runtime/testing/cleanup.md

@@ -1,38 +0,0 @@
----
-title: cleanup
-sidebar_position: 3
----
-
-用于卸载掉当前已渲染的所有组件。
-
-## 使用姿势
-
-```ts
-import { cleanup } from '@modenr-js/runtime/testing';
-```
-
-## 函数签名
-
-`function cleanup(): void`
-
-## 示例
-
-:::info 注
-请注意，如果你使用的测试框架支持 afterEach，并且它被注入到你的测试环境中（如 mocha、Jest 和 Jasmine），**会默认在 afterEach 钩子里执行 `cleanup`**。否则，你将需要在每次测试后进行手动清理。
-:::
-
-例如，如果你使用[ava](https://github.com/avajs/ava)测试框架，那么你需要像这样使用 test.afterEach 钩子。
-
-```tsx
-import { cleanup, render } from '@modern-js/runtime/testing';
-import test from 'ava';
-
-test.afterEach(cleanup);
-
-test('renders into document', () => {
-  render(<div />);
-  // ...
-});
-
-// ... more tests ...
-```

package/zh/apis/app/runtime/testing/render.md

@@ -1,70 +0,0 @@
----
-title: render
----
-
-用于在测试用例中渲染组件，完成测试。
-
-## 使用姿势
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-```
-
-## 函数签名
-
-```ts
-type Options = {
-  container: DOMElement;
-  baseElement: DOMElement;
-  hydrate: boolean;
-  warpper: React.ComponentType<{children: ReactNode}>;
-  queries: any;
-};
-
-type RenderResult = {
-  {...queries}: any;
-  container: DOMElement;
-  baseElement: DOMElement;
-  debug: function;
-  rerender: function;
-  unmount: function;
-  asFragment: function;
-}
-
-function render(ui: React.ReactElement<any>, options: Options): RenderResult;
-```
-
-### 参数
-
-- `ui`：需要被渲染的 React 组件。
-- `options`：render 可选配置。
-  - `container`：表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
-  - `baseElement`：用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
-  - `hydrate`：如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) 渲染组件。默认值为 `false`。
-  - `wrapper`：是一个 react 组件，可用于自定义渲染逻辑。
-  - `queries`：自定义一些自己的 `queries`。
-
-### 返回值
-
-- `{...queries}`：所有可用的 [queries](https://testing-library.com/docs/queries/about/)。
-- `container`：挂载 React 组件的 DOM 节点。
-- `baseElement`
-- `debug`
-- `rerender`：如果想测试一个已渲染的组件在其 props 更新时的一些场景，可以使用 rerender 来现实。
-- `unmount`：会卸载掉已渲染的组件。如果想测试组件卸载后的情况（如，绑定的事件是否在 unmount 阶段被卸载掉），那么这个 API 是很帮助的。
-- `asFragment`：返回当前渲染的组件的 [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 对象。可用于测试 react 事件触发后 DOM 结构的响应。
-
-## 示例
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-import App from './App';
-
-test('renders a message', () => {
-  const { container, getByText } = render(<App />);
-  expect(getByText('Hello, world!')).toBeInTheDocument();
-  expect(container.firstChild).toMatchInlineSnapshot(`
-    <h1>Hello, World!</h1>
-  `);
-});
-```

package/zh/apis/app/runtime/testing/renderApp.md

@@ -1,31 +0,0 @@
----
-title: renderApp
----
-
-`render` 函数用于测试普通组件，`renderApp` 函数用于测试应用组件。
-
-## 使用姿势
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-```
-
-应用组件指包含一些 Modern.js 上下文的组件，如 App 根组件，使用了 Model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
-
-## 函数签名
-
-`renderApp` 和 [render](./render.md) 完全一致。
-
-## 示例
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-import App from './App';
-
-describe('test', () => {
-  it('test App', () => {
-    const { getByText } = renderApp(<App />);
-    expect(getByText('Hello Modern!')).toBeInTheDocument();
-  });
-});
-```

package/zh/apis/app/runtime/utility/css-in-js.md

@@ -1,42 +0,0 @@
----
-title: CSS-In-JS API
----
-
-使用 Style Component 来编写组件 CSS。
-
-## 使用姿势
-
-```ts
-import styled from '@modern-js/runtime/styled';
-```
-
-## 函数签名
-
-请看 [styled-component API](https://styled-components.com/docs/api)。
-
-## 示例
-
-```tsx
-import styled from '@modern-js/runtime/styled';
-
-const Button = styled.button`
-  background: palevioletred;
-  border-radius: 3px;
-  border: none;
-  color: white;
-`;
-
-const TomatoButton = styled(Button)`
-  background: tomato;
-`;
-
-function ButtonExample() {
-  return (
-    <>
-      <Button>I'm purple.</Button>
-      <br />
-      <TomatoButton>I'm red.</TomatoButton>
-    </>
-  );
-}
-```