@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/apis/app/runtime/router/router.md

@@ -0,0 +1,280 @@
+# router
+
+:::info
+The router solution based on [react-router v7](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;
+}
+```
+
+The `useNavigate` hook returns a function that lets you navigate programmatically.
+
+```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;
+}
+```
+
+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 { 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>>;
+```
+
+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 { Routes, 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` returns the nearest ancestor Route error。
+
+```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;
+```
+
+## Components
+
+### 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>;
+```
+
+A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it.
+
+```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);
+}
+```
+
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active".
+
+### Outlet
+
+```ts
+interface OutletProps {
+  context?: unknown;
+}
+declare function Outlet(props: OutletProps): React.ReactElement | null;
+```
+
+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
+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` represents the route information. A `Route` object couples URL segments to components, data loading and data mutations.
+
+`Route` can be used as a plain object, passing to the router creation functions:
+
+```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 />,
+  },
+]);
+```
+
+You can also declare your routes with JSX and `createRoutesFromElements`, the props to the element are identical to the properties of the route objects:
+
+```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 />}
+    />,
+  ),
+);
+```
+
+## More
+
+You can access to [React Router](https://reactrouter.com/) to get the full API information.

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

@@ -0,0 +1,35 @@
+# 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/ssr';
+
+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/ssr';
+
+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/docs/apis/app/runtime/ssr/renderStreaming.md

@@ -0,0 +1,67 @@
+# renderStreaming
+
+Used for `React v18` + `Streaming SSR` to render readable streams, used in conjunction with `createRequestHandler`.
+
+## Usage
+
+```ts 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);
+```
+
+## Function Signature
+
+```ts
+export type RenderStreaming = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<ReadableStream>;
+```
+
+## Example
+
+```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/apis/app/runtime/ssr/renderString.md

@@ -0,0 +1,60 @@
+# renderString
+
+Used for React String SSR to render strings, used in conjunction with `createRequestHandler`.
+
+## Usage
+
+```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);
+```
+
+## Function Signature
+
+```ts
+export type RenderString = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<string>;
+```
+
+## Example
+
+```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/apis/app/runtime/ssr/requestHandler.md

@@ -0,0 +1,44 @@
+# createRequestHandler
+
+Used to customize the Server-Side Rendering entry to return the `requestHandler`.
+
+## Usage
+
+```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);
+```
+
+## Function Signature
+
+```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/apis/app/runtime/utility/css-in-js.md

@@ -0,0 +1,40 @@
+# CSS-In-JS API
+
+Use Style Component to write CSS.
+
+## Usage
+
+```ts
+import styled from '@modern-js/plugin-styled-components/styled';
+```
+
+## Function Signature
+
+see [styled-component API](https://styled-components.com/docs/api).
+
+## Example
+
+```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/apis/app/runtime/utility/head.md

@@ -0,0 +1,35 @@
+# Head
+
+Used to add html elements (such as title, meta, script, etc.) to the `<head>` element, supports SSR.
+
+## Usage
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+export default () => <Helmet>...</Helmet>;
+```
+
+## Example
+
+```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;
+```
+
+## More
+
+For detail, see [react-helmet](https://github.com/nfl/react-helmet).

package/docs/apis/app/runtime/utility/loadable.md

@@ -0,0 +1,82 @@
+# loadable
+
+Used to create Loadable component
+
+## Usage
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+```
+
+## Function Signature
+
+```ts
+type Options = {
+  resolveComponent?: (
+    module: Module,
+    props: Props,
+  ) => React.ComponentType<Props>,
+  fallback?: JSX.Element;
+  ssr?: boolean;
+}
+
+function loadable(loadFn: Function, options?: Options) => LoadableComponent
+```
+
+### Input
+
+#### loadFn
+
+Used to load component.
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+
+const OtherComponent = loadable(() => import('./OtherComponent'));
+```
+
+#### options.resolveComponent
+
+Type: `(module: Module, props: Props) => React.ComponentType<Props>`
+
+`module` is the component returned by `loadFn`, and `props` is the props parameter accepted by the component.
+
+By default, we think that the default export of file is a react component, so we can render the component directly. But when the component is named export, or we need to dynamically determine which component needs to be rendered according to the `props`, we can use `resolveComponent`. Here is an example:
+
+```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
+
+Whether to display fallback content during loading.
+
+#### options.ssr
+
+Whether to support SSR, the default value is `true`.
+
+### Return Value
+
+#### LoadableComponent
+
+```ts
+type LoadableComponent<Props> = React.ComponentType<
+  Props & { fallback?: JSX.Element }
+> & {
+  preload(props?: Props): void;
+  load(props?: Props): Promise<React.ComponentType<Props>>;
+};
+```