@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/apis/app/runtime/router/router.mdx

@@ -0,0 +1,287 @@
+---
+title: router
+sidebar_position: 1
+---
+# router
+
+:::info 补充信息
+基于 [react-router](https://reactrouter.com/) 的路由解决方案。
+
+本页文档对应 React Router 运行时导出（`@modern-js/runtime/router`）。  
+如果应用使用 TanStack Router（`--router tanstack`），请使用 `@modern-js/plugin-tanstack/runtime`，并参考 TanStack Router 官方 API 文档。
+
+:::
+
+## 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>
+  );
+}
+```
+
+### useRouteError
+
+```ts
+export declare function useRouteError(): unknown;
+```
+
+`useRouteError` 返回离 ErrorBoundary 定义最近的路由渲染错误信息。
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.message}</h2>
+    </div>
+  );
+};
+export default ErrorBoundary;
+```
+
+## 组件
+
+### 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/docs/zh/apis/app/runtime/ssr/no-ssr.mdx

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

package/docs/zh/apis/app/runtime/ssr/renderStreaming.mdx

@@ -0,0 +1,71 @@
+---
+title: renderStreaming
+---
+
+# renderStreaming
+
+用于 `React v18` + `Streaming SSR` 渲染出可读流, 配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  return new Response(stream, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type RenderStreaming = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<ReadableStream>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  // docs: https://developer.mozilla.org/en-US/docs/Web/API/TransformStream
+  const transformStream = new TransformStream({
+    transform(chunk, controller) {
+      // do some transform
+    },
+  });
+
+  stream.pipeThrough(transformStream);
+
+  return new Response(transformStream.readable, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/runtime/ssr/renderString.mdx

@@ -0,0 +1,64 @@
+---
+title: renderString
+---
+
+# renderString
+
+用于 React String SSR 渲染出字符串，配合 `createRequestHandler` 使用
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type RenderString = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<string>;
+```
+
+## 示例
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/runtime/ssr/requestHandler.mdx

@@ -0,0 +1,48 @@
+---
+title: createRequestHandler
+---
+
+# createRequestHandler
+
+用于自定义 Server-Side Rendering 入口返回 requestHandler
+
+## 使用
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 函数签名
+
+```ts
+export type HandleRequest = (
+  request: Request,
+  ServerRoot: React.ComponentType
+  options: HandleRequestOptions,
+) => Promise<Response>;
+
+export type RequestHandler = (
+  request: Request,
+  options: RequestHandlerOptions,
+) => Promise<Response>;
+
+export type CreateRequestHandler = (
+  handleRequest: HandleRequest,
+) => Promise<RequestHandler>;
+```

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

@@ -0,0 +1,44 @@
+---
+title: CSS-In-JS API
+---
+
+# CSS-In-JS API
+
+使用 Style Component 来编写组件 CSS。
+
+## 使用姿势
+
+```ts
+import styled from '@modern-js/plugin-styled-components/styled';
+```
+
+## 函数签名
+
+请看 [styled-component API](https://styled-components.com/docs/api)。
+
+## 示例
+
+```tsx
+import styled from '@modern-js/plugin-styled-components/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>
+    </>
+  );
+}
+```

package/docs/zh/apis/app/runtime/utility/head.mdx

@@ -0,0 +1,38 @@
+---
+title: Head
+---
+# Head
+
+用于给 `<head>` 元素内添加 html 元素（如 title、meta、script 等），支持 `SSR`。
+
+## 使用姿势
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+export default () => <Helmet>...</Helmet>;
+```
+
+## 示例
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+function IndexPage() {
+  return (
+    <div>
+      <Helmet>
+        <title>My page title</title>
+        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
+      </Helmet>
+      <p>Hello Modern.js!</p>
+    </div>
+  );
+}
+
+export default IndexPage;
+```
+
+## 更多用法
+
+详见 [react-helmet](https://github.com/nfl/react-helmet)。

package/docs/zh/apis/app/runtime/utility/loadable.mdx

@@ -0,0 +1,83 @@
+---
+title: loadable
+---
+# loadable
+
+用于创建 Loadable 的组件。
+
+## 使用姿势
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+```
+
+## 函数签名
+
+```ts
+type Options = {
+  resolveComponent?: (
+    module: Module,
+    props: Props,
+  ) => React.ComponentType<Props>,
+  fallback?: JSX.Element;
+  ssr?: boolean;
+}
+
+function loadable(loadFn: Function, options?: Options) => LoadableComponent
+```
+
+### 参数
+
+#### loadFn
+
+用于加载组件。
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+
+const OtherComponent = loadable(() => import('./OtherComponent'));
+```
+
+#### options.resolveComponent
+
+类型：`(module: Module, props: Props) => React.ComponentType<Props>`
+
+`module` 为 `loadFn` 返回的组件，`props` 是 loadable 返回的组件接受的 props 参数。默认的话，我们认为 `import` 的文件都是默认导出 react 组件，这时候直接渲染该组件即可。但当组件是具名导出的，或者我们需要根据具体的 `props` 动态判断需要渲染哪个组件的时候，可以使用 `resolveComponent` 来实现。下面是一个示例：
+
+```ts title='component.js'
+export const Apple = () => 'Apple!';
+export const Orange = () => 'Orange!';
+```
+
+```ts title='loadable.js'
+const LoadableApple = loadable(() => import('./components'), {
+  resolveComponent: components => components.Apple,
+});
+const LoadableOrange = loadable(() => import('./components'), {
+  resolveComponent: components => components.Orange,
+});
+const LoadableFruit = loadable(() => import('./components'), {
+  resolveComponent: (components, props) => components[props.fruit],
+});
+```
+
+#### options.fallback
+
+是否在 loading 阶段显示 fallback 内容。
+
+#### options.ssr
+
+是否支持 SSR，默认值是 `true`。
+
+### 返回值
+
+#### LoadableComponent
+
+```ts
+type LoadableComponent<Props> = React.ComponentType<
+  Props & { fallback?: JSX.Element }
+> & {
+  preload(props?: Props): void;
+  load(props?: Props): Promise<React.ComponentType<Props>>;
+};
+```

package/docs/zh/community/_meta.json

@@ -0,0 +1,11 @@
+[
+  "showcase",
+  "team",
+  "releases",
+  "contributing-guide",
+  {
+    "type": "dir",
+    "name": "blog",
+    "label": "blog"
+  }
+]