@modern-js/main-doc 0.0.0-next-20221227140603 → 0.0.0-next-20221228051706

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.0-beta.6 build /tmp/repo/modern.js/packages/toolkit/main-doc
+> @modern-js/main-doc@2.0.0-canary.1 build /tmp/repo/modern.js/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/CHANGELOG.md

@@ -1,33 +1,8 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-20221227140603
+## 0.0.0-next-20221228051706
 
 ### Patch Changes
 
-- 7879e8f71: refactor: remove enableModernMode config
-
-  refactor: 不再支持 enableModernMode 配置项
-
-- 5927355ee: feat: develop documentation directly with main-doc
-  feat: 直接使用 main-doc 包开发文档
-- ebf899fb5: feat(app-tools): support configure builder plugins
-
-  feat(app-tools): 支持配置 builder 插件
-
-- 1ef69374b: feat: support update main-doc when package build or website build
-  feat: 支持在包发布和官网发布时，更新 main-doc 包
-- Updated dependencies [2bc090c08]
-- Updated dependencies [f96a72521]
-- Updated dependencies [57077b2c6]
-- Updated dependencies [2ff6167be]
-- Updated dependencies [309f08bdf]
-- Updated dependencies [5402fdb0c]
-- Updated dependencies [10d08a480]
-- Updated dependencies [5d67c26cd]
-- Updated dependencies [af4422d67]
 - Updated dependencies [dda38c9c3]
-- Updated dependencies [812913ccd]
-- Updated dependencies [3fae2d03b]
-- Updated dependencies [df41d71ad]
-- Updated dependencies [14b712da8]
-  - @modern-js/builder-doc@0.0.0-next-20221227140603
+  - @modern-js/builder-doc@0.0.0-next-20221228051706

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

@@ -3,32 +3,44 @@ title: router
 sidebar_position: 1
 ---
 
-:::info 补充信息
-基于 [react-router](https://reactrouter.com/web/guides/start) 的路由解决方案。
+:::info
+The router solution based on [react-router 6](https://reactrouter.com/).
 :::
 
-:::caution 注意
-使用该 API 前，请确认没有禁用 [router 插件](#)。
+:::caution
+Make sure the [router plugin](/docs/configure/app/runtime/router) is opted in before using the API.
 :::
 
 ## hooks
 
-### useHistory
+### useNavigate
 
 ```ts
-function useHistory<HistoryLocationState = H.LocationState>(): H.History<HistoryLocationState>;
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+  (
+    to: To,
+    options?: {
+      replace?: boolean;
+      state?: any;
+      relative?: RelativeRoutingType;
+    }
+  ): void;
+  (delta: number): void;
+}
 ```
 
-用于获取 `history` 实例。
+The `useNavigate` hook returns a function that lets you navigate programmatically。
 
 ```tsx
-import { useHistory } from "@modern-js/runtime/router";
+import { useNavigate } from "@modern-js/runtime/router";
 
 export function HomeButton() {
-  let history = useHistory();
+  let navigate = useNavigate();
 
   function handleClick() {
-    history.push("/home");
+    navigate("/home");
   }
 
   return (
@@ -42,20 +54,18 @@ export function HomeButton() {
 ### useLocation
 
 ```ts
-function useLocation<S = H.LocationState>(): H.Location<S>;
+declare function useLocation(): Location;
+
+interface Location extends Path {
+  state: unknown;
+  key: Key;
+}
 ```
 
-`useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
+The `useLocation` hook returns the current [location](https://reactrouter.com/web/api/location) object. A new location object would be returned whenever the current location changes.
 
 ```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";
+import { useLocation } from "@modern-js/runtime/router";
 
 function usePageViews() {
   let location = useLocation();
@@ -66,26 +76,25 @@ function usePageViews() {
 
 function App() {
   usePageViews();
-  return <Switch>...</Switch>;
+  return (
+    //...
+  );
 }
 ```
 
 ### useParams
 
 ```ts
-function useParams<
-  Params extends {
-    [K in keyof Params]?: string
-  } = {}
->(): Params;
+declare function useParams<
+  K extends string = string
+>(): Readonly<Params<K>>;
 ```
 
-`useParams` 返回一个 key/value 的键值对表示路由中的参数信息。它等同于 `<Route >` 组件中的 `match.params` 值。
+The `useParams` hook returns an object of key/value pairs of the dynamic params from the current URL that were matched by the `<Route path>`.
 
 ```tsx
-import React from "react";
 import {
-  Switch,
+  Routes,
   Route,
   useParams
 } from "@modern-js/runtime/router";
@@ -96,397 +105,191 @@ function BlogPost() {
 }
 
 function App() {
-  return <Switch>
-    <Route exact path="/">
-      <div>home</div>
-    </Route>
-    <Route path="/blog/:slug">
-      <BlogPost />
-    </Route>
-  </Switch>
+  return (
+    <Routes>
+      <Route path="/" element={ <div>home</div> } />
+      <Route path="/blog/:slug" element={ <BlogPost />}/>
+    </Routes>
+  )
 }
 ```
 
-### 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 />` 组件，便能获取到当前匹配结果。
-
-## 组件
-
-
+## Components
 
 ### Link
 
 ```ts
-interface Link<S = H.LocationState>
-  extends React.ForwardRefExoticComponent<
-    React.PropsWithoutRef<LinkProps<S>> & React.RefAttributes<HTMLAnchorElement>
-> {}
-```
-
-可以使用 `Link` 组件进行路由跳转。
+declare function Link(props: LinkProps): React.ReactElement;
+
+interface LinkProps
+  extends Omit<
+    React.AnchorHTMLAttributes<HTMLAnchorElement>,
+    "href"
+  > {
+  replace?: boolean;
+  state?: any;
+  to: To;
+  reloadDocument?: boolean;
+}
 
-```ts
-<Link to="/about">About</Link>
+type To = string | Partial<Path>;
 ```
 
-#### LinkProps
-
-**to**
-
-类型: `string | object | function`
-
-`string`
+A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it.
 
 ```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} />
+<Link to="/about">About</Link>
 ```
 
 ### 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;
+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);
 }
-
-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}?`
-  }}
-/>
-```
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active".
 
-**when**
 
-类型: `boolean`
-
-当 `when` 为 `true` 时，才会在页面跳转前展示二次确认提示。
-
-
-### Route
+### Outlet
 
 ```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;
+interface OutletProps {
+  context?: unknown;
 }
-
-class Route<T extends {} = {}, Path extends string = string> extends React.Component<
-  RouteProps<Path> & OmitNative<T, keyof RouteProps>,
-  any
-> {}
+declare function Outlet(
+  props: OutletProps
+): React.ReactElement | null;
 ```
 
-`Route` 组件用于定义路由。
-
-#### component
-
-类型: `React.ComponentType`
-
-当路由匹配成功，会渲染传入 `component` 的组件。
+An `<Outlet>` should be used in parent route elements to render their child route elements. This allows nested UI to show up when child routes are rendered.
 
 ```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 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 <Route path="/user/:username" component={User} />;
+  return (
+    <Routes>
+      <Route path="/" element={<Dashboard />}>
+        <Route
+          path="messages"
+          element={<DashboardMessages />}
+        />
+        <Route path="tasks" element={<DashboardTasks />} />
+      </Route>
+    </Routes>
+  );
 }
 ```
 
-:::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";
+### Route
 
-function App() {
-  <Route path="/home" render={() => <div>Home</div>} />
+```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;
 }
 ```
 
-:::info
-component 的优先级高于 render。
-:::
+`Route` represents the route information. A `Route` object couples URL segments to components, data loading and data mutations.
 
-#### children
+`Route` can be used as a plain object, passing to the router creation functions：
 
-类型: `((props: RouteChildrenProps<Params>) => React.ReactNode) | React.ReactNode`
+```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 />,
+  },
+]);
+```
 
-如果在路由匹配或不匹配的情况下，都需要渲染一些内容，那么可以使用 `children` 参数。
+You can also declare your routes with JSX and `createRoutesFromElements`, the props to the element are identical to the properties of the route objects:
 
-```tsx
-function ListItemLink({ to, ...rest }) {
-  return (
+```ts
+const router = createBrowserRouter(
+  createRoutesFromElements(
     <Route
-      path={to}
-      children={({ match }) => (
-        <li className={match ? "active" : ""}>
-          <Link to={to} {...rest} />
-        </li>
-      )}
+      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 />}
     />
-  );
-}
-
-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`
+## More
 
-## 更多底层 API
+You can access to [React Router](https://reactrouter.com/) to get the full API information.
 
-若想要了解更多的底层 API 信息，可至 [react-router 官网](https://reactrouter.com/web/guides/start) 查看。