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

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/router/router.md

@@ -0,0 +1,492 @@
+---
+title: router
+sidebar_position: 1
+---
+
+:::info 补充信息
+基于 [react-router](https://reactrouter.com/web/guides/start) 的路由解决方案。
+:::
+
+:::caution 注意
+使用该 API 前，请确认没有禁用 [router 插件](#)。
+:::
+
+## hooks
+
+### useHistory
+
+```ts
+function useHistory<HistoryLocationState = H.LocationState>(): H.History<HistoryLocationState>;
+```
+
+用于获取 `history` 实例。
+
+```tsx
+import { useHistory } from "@modern-js/runtime/router";
+
+export function HomeButton() {
+  let history = useHistory();
+
+  function handleClick() {
+    history.push("/home");
+  }
+
+  return (
+    <button type="button" onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+```ts
+function useLocation<S = H.LocationState>(): H.Location<S>;
+```
+
+`useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
+
+```ts
+import React from "react";
+import { bootstrap, createApp } from '@modern-js/runtime';
+import { router } from '@modern-js/runtime/plugins';
+import {
+  BrowserRouter as Router,
+  Switch,
+  useLocation
+} from "@modern-js/runtime/router";
+
+function usePageViews() {
+  let location = useLocation();
+  React.useEffect(() => {
+    ga.send(["pageview", location.pathname]);
+  }, [location]);
+}
+
+function App() {
+  usePageViews();
+  return <Switch>...</Switch>;
+}
+```
+
+### useParams
+
+```ts
+function useParams<
+  Params extends {
+    [K in keyof Params]?: string
+  } = {}
+>(): Params;
+```
+
+`useParams` 返回一个 key/value 的键值对表示路由中的参数信息。它等同于 `<Route >` 组件中的 `match.params` 值。
+
+```tsx
+import React from "react";
+import {
+  Switch,
+  Route,
+  useParams
+} from "@modern-js/runtime/router";
+
+function BlogPost() {
+  const { slug } = useParams();
+  return <div>Now showing post {slug}</div>;
+}
+
+function App() {
+  return <Switch>
+    <Route exact path="/">
+      <div>home</div>
+    </Route>
+    <Route path="/blog/:slug">
+      <BlogPost />
+    </Route>
+  </Switch>
+}
+```
+
+### useRouteMatch
+
+```ts
+function useRouteMatch<
+  Params extends { [K in keyof Params]?: string } = {}
+>(): match<Params>;
+
+function useRouteMatch<
+  Params extends { [K in keyof Params]?: string } = {}
+>(
+  path: string | string[] | RouteProps,
+): match<Params> | null;
+```
+
+`useRouteMatch` 和 `<Route />` 一样是对路由进行匹配，但无须去渲染 `<Route />` 组件，便能获取到当前匹配结果。
+
+## 组件
+
+
+
+### Link
+
+```ts
+interface Link<S = H.LocationState>
+  extends React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<LinkProps<S>> & React.RefAttributes<HTMLAnchorElement>
+> {}
+```
+
+可以使用 `Link` 组件进行路由跳转。
+
+```ts
+<Link to="/about">About</Link>
+```
+
+#### LinkProps
+
+**to**
+
+类型: `string | object | function`
+
+`string`
+
+```ts
+<Link to="/courses?sort=name" />
+```
+
+`object`
+
+```tsx
+<Link
+  to={{
+    pathname: "/courses",
+    search: "?sort=name",
+    hash: "#the-hash",
+    state: { fromDashboard: true }
+  }}
+/>
+```
+
+`function`
+
+```tsx
+<Link to={location => ({ ...location, pathname: "/courses" })} />
+
+<Link to={location => `${location.pathname}?sort=name`} />
+```
+
+**replace**
+
+类型: `boolean`
+
+当设置为 `true` 时，在跳转的时候替换掉 history 栈中的栈顶路由，而不是添加一个新路由。
+
+**component**
+
+类型: `Component`
+
+如果你想自定义你自己的路由跳转的组件，可以通过传入 `component` 来实现。
+
+```tsx
+ simply do so by passing it through the component prop.const FancyLink = React.forwardRef((props, ref) => (
+  <a ref={ref} {...props}>💅 {props.children}</a>
+))
+
+<Link to="/" component={FancyLink} />
+```
+
+### NavLink
+
+```ts
+interface NavLink<S = H.LocationState>
+  extends React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<NavLinkProps<S>> & React.RefAttributes<HTMLAnchorElement>
+> {}
+```
+
+`NavLink` 是一种特殊的 [Link](#link) 组件，当 `NavLink` 对应路由匹配到当前 `url`, 会给 `NavLink` 所渲染的元素添加一些额外的样式。
+
+
+#### NavLinkProps
+
+**activeClassName**
+
+类型: `string`
+
+设置路由匹配时额外 class。
+
+```tsx
+<NavLink to="/faq" activeClassName="selected">
+  FAQs
+</NavLink>
+```
+
+**activeStyle**
+
+类型: `object`
+
+设置路由匹配时额外的样式。
+
+```tsx
+<NavLink
+  to="/faq"
+  activeStyle={{
+    fontWeight: "bold",
+    color: "red"
+  }}
+>
+  FAQs
+</NavLink>
+```
+
+**exact**
+
+类型: `boolean`
+
+
+**strict**
+
+类型: `boolean`
+
+**isActive**
+
+类型: `function`
+
+如果你想自定义当前 Link 是否激活的逻辑，可以使用 `isActive`。
+
+```tsx
+<NavLink
+  to="/events/123"
+  isActive={(match, location) => {
+    if (!match) {
+      return false;
+    }
+
+    // only consider an event active if its event id is an odd number
+    const eventID = parseInt(match.params.eventID);
+    return !isNaN(eventID) && eventID % 2 === 1;
+  }}
+>
+  Event 123
+</NavLink>
+```
+
+**location**
+
+类型: `object`
+
+`NavLink` 默认会和当前的 `history.location` 进行匹配，判断是否处于激活状态。如果你想指定要匹配的 `location` 对象，可以使用该参数。
+
+**area-current**
+
+类型: `string`
+
+参考 [aria-current](https://www.w3.org/TR/wai-aria-1.1/#aria-current)
+
+
+
+### Prompt
+
+```ts
+interface PromptProps {
+    message: string | ((location: H.Location, action: H.Action) => string | boolean);
+    when?: boolean;
+}
+
+class Prompt extends React.Component<PromptProps, any> {}
+```
+
+`Prompt` 组件可用于在页面跳转前，进行二次确认是否跳转。
+
+```tsx
+<Prompt
+  when={formIsHalfFilledOut}
+  message="Are you sure you want to leave?"
+/>
+```
+
+#### PromptProps
+
+**message**
+
+类型: `string` | `function`
+
+在页面跳转前的二次确认提示信息，支持传入函数形式。
+
+```tsx
+<Prompt
+  message={(location, action) => {
+    if (action === 'POP') {
+      console.log("Backing up...")
+    }
+
+    return location.pathname.startsWith("/app")
+      ? true
+      : `Are you sure you want to go to ${location.pathname}?`
+  }}
+/>
+```
+
+**when**
+
+类型: `boolean`
+
+当 `when` 为 `true` 时，才会在页面跳转前展示二次确认提示。
+
+
+### Route
+
+```ts
+interface RouteProps<
+  Path extends string = string,
+  Params extends { [K: string]: string | undefined } = ExtractRouteParams<Path, string>
+> {
+  location?: H.Location;
+  component?: React.ComponentType<RouteComponentProps<any>> | React.ComponentType<any>;
+  render?: (props: RouteComponentProps<Params>) => React.ReactNode;
+  children?: ((props: RouteChildrenProps<Params>) => React.ReactNode) | React.ReactNode;
+  path?: Path | Path[];
+  exact?: boolean;
+  sensitive?: boolean;
+  strict?: boolean;
+}
+
+class Route<T extends {} = {}, Path extends string = string> extends React.Component<
+  RouteProps<Path> & OmitNative<T, keyof RouteProps>,
+  any
+> {}
+```
+
+`Route` 组件用于定义路由。
+
+#### component
+
+类型: `React.ComponentType`
+
+当路由匹配成功，会渲染传入 `component` 的组件。
+
+```tsx
+import React from "react";
+import { Route } from "@modern-js/runtime/router";
+
+// All route props (match, location and history) are available to User
+function User(props) {
+  return <h1>Hello {props.match.params.username}!</h1>;
+}
+
+function App() {
+  return <Route path="/user/:username" component={User} />;
+}
+```
+
+:::tip 提示
+如果 component 是一个 inline function，如 `<Route path="/user/:username" component={() => 'hello'} />`，因为每次 rerender 的时候，component 都会是一个新的 `type`，所以 component 组件会先 unmount，再 mount。我们需要避免这种写法，或者使用 render 代替 component。
+:::
+
+#### render
+
+类型: `(props: RouteComponentProps<Params>) => React.ReactNode`
+
+允许使用 `inline function` 进行渲染，同时不会有 `component` remounting 的问题。
+
+```tsx
+import React from "react";
+import { Route } from "@modern-js/runtime/router";
+
+function App() {
+  <Route path="/home" render={() => <div>Home</div>} />
+}
+```
+
+:::info
+component 的优先级高于 render。
+:::
+
+#### children
+
+类型: `((props: RouteChildrenProps<Params>) => React.ReactNode) | React.ReactNode`
+
+如果在路由匹配或不匹配的情况下，都需要渲染一些内容，那么可以使用 `children` 参数。
+
+```tsx
+function ListItemLink({ to, ...rest }) {
+  return (
+    <Route
+      path={to}
+      children={({ match }) => (
+        <li className={match ? "active" : ""}>
+          <Link to={to} {...rest} />
+        </li>
+      )}
+    />
+  );
+}
+
+function App() {
+  return <ul>
+    <ListItemLink to="/somewhere" />
+    <ListItemLink to="/somewhere-else" />
+  </ul>;
+}
+```
+
+#### path
+
+类型: `string | string[]`
+
+符合 [path-to-regexp@^1.7.0](https://github.com/pillarjs/path-to-regexp/tree/v1.7.0) 匹配规则的 url 字符串或数组。
+
+```tsx
+<Route path="/users/:id">
+  <User />
+</Route>
+
+<Route path={["/users/:id", "/profile/:id"]}>
+  <User />
+</Route>
+```
+
+#### exact
+
+类型: `boolean`
+
+默认值: `false`
+
+当 `exact` 值为 `true` 时，会进行准确匹配。
+
+|  path   | location.pathname | exact | matches? |
+|  -  | -  | - | - |
+| /one  | /one/two	 | true  | no  |
+| /one  | /one/two	 | false | yes |
+
+
+#### strict
+
+类型: `boolean`
+
+默认值: `false`
+
+当 `strict` 值为 `true` 时，会进行严格匹配。若 `path` 以 '/' 结尾，那么 `location.pathname` 也需要以 '/' 结尾，才能匹配。
+
+|  path   | location.pathname | matches? |
+|  -  | - | - |
+| /one/  | /one  | no  |
+| /one/  | /one/ | yes |
+| /one/| /one/two | yes |
+
+#### sensitive
+
+类型: `boolean`
+
+默认值: `false`
+
+当 `sensitive` 设置为 `true`，则 path 大小写不敏感。
+
+#### location
+
+类型: `object`
+
+## 更多底层 API
+
+若想要了解更多的底层 API 信息，可至 [react-router 官网](https://reactrouter.com/web/guides/start) 查看。
+

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/ssr/_category_.json

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

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/ssr/no-ssr.md

@@ -0,0 +1,44 @@
+---
+title: NoSSR
+---
+
+The content wrapped by NoSSR will not be rendered at the server, nor will it be rendered during the client side hydrate. it will only be rendered immediately after the entire app is rendered.
+
+## Usage
+
+```tsx
+import { NoSSR } from '@modern-js/runtime';
+
+export default () => (
+  <NoSSR>
+    ...
+  </NoSSR>
+)
+```
+
+## Example
+
+In the following code, the `Time` component is used to display the current time. Since the time obtained by server-side rendering and client side hydrate are diff, React will throw an exception. For this case, you can use `NoSSR` to optimize:
+
+```tsx
+import { NoSSR } from '@modern-js/runtime';
+
+function Time() {
+  return (
+    <NoSSR>
+      <div>Time: {Date.now()}</div>
+    </NoSSR>
+  );
+}
+```
+
+## Scene
+
+In CSR, it is often necessary to render different content according to the browser UA, or a parameter of the current page URL. If the application switches directly to SSR at this time, it is very likely that the results will not meet the expectations.
+
+Modern.js provides complete browser side information in the SSR context, which can be used to determine the rendering result of the component on the server side.
+
+Even so, if there is too much logic in the application, or the developer wants to use the context later, or does not want some content to be rendered at the server side. developer can use the NoSSR component to exclude this part from server-side rendering.
+
+
+

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/ssr/pre-render.md

@@ -0,0 +1,91 @@
+---
+title: PreRender
+---
+
+A Helmet-like HOC without content implements SPA routing-level caching, manner without additional configuration.
+
+## Usage
+
+```tsx
+import { PreRender } from '@modern-js/runtime/ssr';
+
+export default () => (
+  <>
+    <PreRender interval={5} />
+  </>
+)
+```
+
+## Function Signature
+
+The `PreRender` provides a set of configuration for controlling caching rules, expiration times, caching algorithms, and more.
+
+```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
+```
+
+### Input
+
+- `interval`: set the time the cache keep fresh，seconds. During this time, the cache will be used directly and not invoke asynchronous rendering.
+- `staleLimit`: sets the time when the cache is completely expired，seconds。During this time, The cache can be returned and asynchronous rendering will be invoke, otherwise must wait for the re-rendered result.
+- `level`: sets the calculation rule level for the cache identity, usually used with `includes` and `matches`. The default value is `0`.
+
+```bash
+0: pathname
+1: pathname + querystring
+2: pathname + headers
+3: pathname + querystring + headers
+```
+
+- `includes`: sets the content that needs to be included in the cache identifier, used when the `level` is not `0`. The default value is `null`.
+- `matches`: sets the rewriting rule for the value of query or header in cache identity, usually used in cache category, supports regular expressions. The default value is `null`.
+
+## Example
+
+```tsx
+import { PreRender } from '@modern-js/runtime/ssr';
+
+export default function App() {
+  return (
+    <>
+      <PreRender interval={10} />
+      <div>Hello Modern</div>
+    </>
+  )
+}
+```
+
+The following example shows how to add the parameters in the query and header into the cache identifier calculation:
+
+```tsx
+/* calculate cache identifier using channel in query and language in header */
+<PreRender interval={10} level={2} includes={{
+  query: ["channel"],
+  header: ["language"]
+}} />
+```
+
+The following example shows how not to let the test channel affect the online cache:
+
+```tsx
+/* rewrite the channel value starting with test_ in the query as "testChannel", otherwise rewrite it as "otherChannel" */
+<PreRender interval={10} level={2} includes={{
+  query: ["channel"],
+  header: ["language"]
+}} matches={{
+  query: {
+    channel: {
+      "testChannel", "^test_",
+      "otherChannel", ".*"
+    }
+  }
+}} />
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/testing/_category_.json

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

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/testing/act.md

@@ -0,0 +1,34 @@
+---
+title: act
+---
+
+Used to ensure that behaviors such as rendering, events, data fetching, etc. have been applied to the DOM.
+
+## Usage
+
+```ts
+import { act } from '@modern-js/runtime/testing';
+```
+
+## Function Signature
+
+`act` is the same as [react-dom/test-utils act function](https://reactjs.org/docs/testing-recipes.html#act).
+
+## Example
+
+```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/en/docusaurus-plugin-content-docs/current/apis/app/runtime/testing/cleanup.md

@@ -0,0 +1,38 @@
+---
+title: cleanup
+sidebar_position: 3
+---
+
+Used to uninstall all currently rendered components.
+
+## Usage
+
+```ts
+import { cleanup } from '@modenr-js/runtime/testing';
+```
+
+## Function Signature
+
+`function cleanup(): void`
+
+## Example
+
+:::info
+Note that if you are using a testing framework that supports afterEach and it is injected into your testing environment (such as mocha, Jest, and Jasmine), **will execute `cleanup`** in the afterEach hook by default. Otherwise, you will need to do manual cleanup after each test.
+:::
+
+For example, if you use the [ava](https://github.com/avajs/ava) test framework, then you need to use the `test.after Each` hook like this.
+
+```tsx
+import { cleanup, render } from '@modern-js/runtime/testing';
+import test from 'ava';
+
+test.afterEach(cleanup);
+
+test('renders into document', () => {
+  render(<div />);
+  // ...
+});
+
+// ... more tests ...
+```