@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

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

@@ -3,20 +3,20 @@ sidebar_position: 9
 title: useStore
 ---
 
-import ReduckTip from '@site/docs/components/reduck-tip.md'
+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) 返回值。
 

package/zh/apis/app/runtime/router/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Router API",
+  "position": 5
+}

package/zh/apis/app/runtime/ssr/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "SSR API",
+  "position": 7
+}

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

@@ -0,0 +1,41 @@
+---
+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

@@ -0,0 +1,91 @@
+---
+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/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Testing API",
-  "position": 5
+  "position": 11
 }

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

@@ -1,16 +1,16 @@
 ---
 title: act
-sidebar_position: 4
 ---
 
-:::info 补充信息
 用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
+
+## 使用姿势
+
 ```ts
 import { act } from '@modern-js/runtime/testing';
 ```
-:::
 
-## API
+## 函数签名
 
 `act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
 
@@ -23,12 +23,12 @@ import { Foo } from '@/components/Foo';
 
 describe('test act', () => {
   it('it should be foo', () => {
-    const el = document.createElement("div");
+    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

@@ -3,16 +3,17 @@ title: cleanup
 sidebar_position: 3
 ---
 
-:::info 补充信息
 用于卸载掉当前已渲染的所有组件。
+
+## 使用姿势
+
 ```ts
-import { cleanup } from '@modern-js/runtime/testing';
+import { cleanup } from '@modenr-js/runtime/testing';
 ```
-:::
 
-## API
+## 函数签名
 
-`cleanup() => void`
+`function cleanup(): void`
 
 ## 示例
 
@@ -24,14 +25,14 @@ import { cleanup } from '@modern-js/runtime/testing';
 
 ```tsx
 import { cleanup, render } from '@modern-js/runtime/testing';
-import test from 'ava'
+import test from 'ava';
 
-test.afterEach(cleanup)
+test.afterEach(cleanup);
 
 test('renders into document', () => {
-  render(<div />)
+  render(<div />);
   // ...
-})
+});
 
 // ... more tests ...
 ```

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

@@ -1,52 +1,72 @@
 ---
 title: render
-sidebar_position: 1
 ---
 
-:::info 补充信息
 用于在测试用例中渲染组件，完成测试。
+
+## 使用姿势
+
 ```ts
 import { render } from '@modern-js/runtime/testing';
 ```
-:::
 
+## 函数签名
 
-## API
+```ts
+type Options = {
+  container: DOMElement;
+  baseElement: DOMElement;
+  hydrate: boolean;
+  warpper: React.ComponentType<{children: ReactNode}>;
+  queries: any;
+};
 
-`render(ui, [options]) => RenderResult`
+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.ReactElement<any>`，需要被渲染的 React 组件。
-- [options]: `object`，render 可选配置。
-  - container: `DOMElement`，表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
-  - baseElement: `DOMElement`，用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
-  - hydrate: `boolean`，如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) 渲染组件。默认值为 `false`。
-  - wrapper: `React.ComponentType<{children: ReactNode}>`，是一个 react 组件，可用于自定义渲染逻辑。
-  - queries: `any`，自定义一些自己的 `queries`。
+- `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}: `any`, 所有可用的 [queries](https://testing-library.com/docs/queries/about/)。
-- container: `DOMElement`，`container` 是挂载 React 组件的 DOM 节点。
-- baseElement: `DOMElement`。
-- debug: `function`。
-- rerender: `function`，如果想测试一个已渲染的组件在其 props 更新时的一些场景，可以使用 rerender 来现实。
-- unmount: `function`，会卸载掉已渲染的组件。如果想测试组件卸载后的情况（如，绑定的事件是否在 unmount 阶段被卸载掉），那么这个 API 是很帮助的。
-- asFragment: `function`，返回当前渲染的组件的 [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 对象。可用于测试 react 事件触发后 DOM 结构的响应。
+- `{...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(<Greeting />)
-  expect(getByText('Hello, world!')).toBeInTheDocument()
+  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 +1,31 @@
 ---
 title: renderApp
-sidebar_position: 2
 ---
 
-:::info 补充信息
 `render` 函数用于测试普通组件，`renderApp` 函数用于测试应用组件。
+
+## 使用姿势
+
 ```ts
 import { renderApp } from '@modern-js/runtime/testing';
 ```
-:::
 
-应用组件指包含一些 Modern 上下文的组件，如 App根组件，使用了 model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
+应用组件指包含一些 Modern.js 上下文的组件，如 App 根组件，使用了 Model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
 
-## API
+## 函数签名
 
-`renderApp` 在 API 层面和 [render](./render.md) 完全一致。
+`renderApp` 和 [render](./render.md) 完全一致。
 
 ## 示例
 
 ```ts
 import { renderApp } from '@modern-js/runtime/testing';
-import App from '../App';
+import App from './App';
 
 describe('test', () => {
   it('test App', () => {
     const { getByText } = renderApp(<App />);
     expect(getByText('Hello Modern!')).toBeInTheDocument();
   });
-})
+});
 ```

package/zh/apis/app/runtime/utility/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Utility API",
-  "position": 6
+  "position": 10
 }

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

@@ -1,18 +1,16 @@
 ---
 title: CSS-In-JS API
-sidebar_position: 2
 ---
 
-:::info 补充信息
-通过 Style Component 在页面上使用 CSS。
+使用 Style Component 来编写组件 CSS。
+
+## 使用姿势
+
 ```ts
 import styled from '@modern-js/runtime/styled';
 ```
-:::
-
-`styled` 具体API，请看：[styled-component api](https://styled-components.com/docs/api)。
 
-## API
+## 函数签名
 
 请看 [styled-component API](https://styled-components.com/docs/api)。
 
@@ -26,35 +24,19 @@ const Button = styled.button`
   border-radius: 3px;
   border: none;
   color: white;
-`
+`;
 
 const TomatoButton = styled(Button)`
   background: tomato;
-`
-
-render(
-  <>
-    <Button>I'm purple.</Button>
-    <br />
-    <TomatoButton>I'm red.</TomatoButton>
-  </>
-)
-`
-
-render(
-  <div>
-    <Button
-      href="https://github.com/styled-components/styled-components"
-      target="_blank"
-      rel="noopener"
-      primary
-    >
-      GitHub
-    </Button>
-
-    <Button as={Link} href="/docs">
-      Documentation
-    </Button>
-  </div>
-)
+`;
+
+function ButtonExample(){
+  return (
+    <>
+      <Button>I'm purple.</Button>
+      <br />
+      <TomatoButton>I'm red.</TomatoButton>
+    </>
+  );
+};
 ```

package/zh/apis/app/runtime/{app → utility}/head.md

@@ -1,21 +1,17 @@
 ---
 title: Head
-sidebar_position: 1
 ---
 
-# Head
+用于给 `<head>` 元素内添加 html 元素（如 title、meta、script 等），支持 `SSR`。
+
+## 使用姿势
 
-:::info 补充信息
-用于给 `head` 元素内添加 html 元素（如 title、meta、script 等），并且支持 `SSR`。
 ```tsx
 import { Helmet } from '@modern-js/runtime/head';
-```
-:::
 
-## API
-
-```tsx
-<Helmet></Helmet>
+export default () => (
+  <Helmet>...</Helmet>
+)
 ```
 
 ## 示例

package/zh/apis/app/runtime/utility/{loadable/loadable_.md → loadable.md}

@@ -1,35 +1,33 @@
 ---
 title: loadable
-sidebar_position: 1
 ---
 
-:::info 补充信息
-用于创建 `loadable 的组件`。
-:::
+用于创建 Loadable 的组件。
+
+## 使用姿势
 
 ```ts
 import loadable from '@modern-js/runtime/loadable';
 ```
 
-## API
+## 函数签名
 
 ```ts
-<Props>(
-  loadFn: Function,
-  options?: {
-    resolveComponent?: (
-      module: Module,
-      props: Props,
-    ) => React.ComponentType<Props>,
-    fallback?: JSX.Element;
-    ssr?: boolean;
-  }
-) => LoadableComponent
+type Options = {
+  resolveComponent?: (
+    module: Module,
+    props: Props,
+  ) => React.ComponentType<Props>,
+  fallback?: JSX.Element;
+  ssr?: boolean;
+}
+
+function loadable(loadFn: Function, options?: Options) => LoadableComponent
 ```
 
-### loadFn
+### 参数
 
-类型：`function`
+#### loadFn
 
 用于加载组件。
 
@@ -39,7 +37,7 @@ import loadable from '@modern-js/runtime/loadable';
 const OtherComponent = loadable(() => import('./OtherComponent'))
 ```
 
-### options.resolveComponent
+#### options.resolveComponent
 
 类型：`(module: Module, props: Props) => React.ComponentType<Props>`
 
@@ -62,49 +60,24 @@ const LoadableFruit = loadable(() => import('./components'), {
 })
 ```
 
-### options.fallback
-
-类型：`JSX.Element`
-
-在 loading 阶段显示 fallback 内容。
-
-### options.ssr
-
-类型：`boolean`
-
-默认值：`true`
-
-如果是 `false`，则该组件不会再服务端渲染阶段处理，即不支持 ssr，默认值是 `true`。
+#### options.fallback
 
-### LoadableComponent（返回值类型）
+是否在 loading 阶段显示 fallback 内容。
 
-[loadableComponent](./loadable-component.md)。
+#### options.ssr
 
-## loadable.lib
+是否支持 SSR，默认值是 `true`。
 
-创建一个 `loadable 的库`。
+### 返回值
 
-```ts
-import loadable from '@modern-js/runtime/loadable';
-const Moment = loadable.lib(() => import('moment'))
-```
+#### LoadableComponent
 
 ```ts
-<Props>(
-  loadFn: Function,
-  options?: {
-    resolveComponent?: any,
-    fallback?: any;
-    ssr?: boolean;
+type LoadableComponent<Props> =
+  React.ComponentType<
+    Props & { fallback?: JSX.Element; }>
+  & {
+    preload(props?: Props): void;
+    load(props?: Props): Promise<React.ComponentType<Props>>;
   }
-) => LoadableLibrary
 ```
-
-### options
-
-同 [options](#optionsresolvecomponent)。
-
-### LoadableLibrary （返回值类型）
-
-移架 [LoadableLibrary](./loadable-library.md)。
-

package/zh/apis/app/runtime/web-server/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Web Server API",
-  "position": 5
+  "position": 9
 }