@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

package/docs/apis/app/runtime/core/render.md

@@ -0,0 +1,39 @@
+# render
+
+It is used to render project components.
+
+## Usage
+
+```ts
+import { render } from '@modern-js/runtime/browser';
+
+render(<ModernRoot />);
+```
+
+## Function Signature
+
+```ts
+export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+```
+
+### Parameters
+
+- `App`：An instance of ReactElement created through [`createRoot`](/apis/app/runtime/core/create-root.md).
+- `id`：The id of the DOM root element to be mounted, such as "root".
+
+## Example
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```

package/docs/apis/app/runtime/core/runtime-context.md

@@ -0,0 +1,156 @@
+# RuntimeContext
+
+`RuntimeContext` is a React Context used to get Runtime context information in components. This Context can be accessed through React's `use` or `useContext` API.
+
+:::warning
+
+The `useRuntimeContext` Hook has been deprecated. Please use `use(RuntimeContext)` instead. `useRuntimeContext` is internally implemented as `useContext(RuntimeContext)`, while `use(RuntimeContext)` is the recommended new approach in React 19.
+
+:::
+
+## Usage
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = use(RuntimeContext); // You can also use useContext(RuntimeContext)
+  return <div>Hello World</div>
+}
+```
+
+## Type Definition
+
+```ts
+type TRuntimeContext = {
+  initialData?: Record<string, unknown>;
+  isBrowser: boolean;
+  routes?: RouteObject[];
+  requestContext: RequestContext;
+  /**
+   * @deprecated Use `requestContext` instead
+   */
+  context: RequestContext;
+  [key: string]: unknown;
+};
+```
+
+### Property Description
+
+- `isBrowser`: Indicates whether the current runtime environment is a browser
+- `routes`: Route configuration information
+- `requestContext`: Request context, containing `request` and `response` objects
+- `context`: Deprecated, please use `requestContext` instead
+
+### RequestContext
+
+`RequestContext` is the type of the `requestContext` property, containing request and response related information:
+
+```ts
+type RequestContext = {
+  request: {
+    params: Record<string, string>;      // Route parameters
+    pathname: string;                     // Pathname
+    query: Record<string, string>;        // Query parameters
+    headers: IncomingHttpHeaders;         // Request headers
+    host: string;                         // Hostname
+    url: string;                          // Full URL
+    referer?: string;                     // Referrer page
+    userAgent?: string;                   // User agent
+    cookie?: string;                      // Cookie string
+    cookieMap?: Record<string, string>;   // Cookie map object
+  };
+  response: {
+    setHeader: (key: string, value: string) => void;  // Set response header (server-side only)
+    status: (code: number) => void;                   // Set status code (server-side only)
+    locals: Record<string, any>;                      // Local data
+  };
+};
+```
+
+**Notes**:
+
+- `response.setHeader` and `response.status` are only available on the server-side (SSR)
+- On the browser side, the `response` object may not contain these methods
+- The `request` object is available on both server and browser, but server-side information is more complete
+
+## Usage Examples
+
+### Distinguishing Runtime Environment
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context, isBrowser } = use(RuntimeContext);
+
+  if (isBrowser === true) {
+    // Browser-side execution logic
+    console.log('browser render')
+  } else {
+    // Server-side execution logic
+    // Note: Functions like logger need to be injected into context through Runtime plugins
+    console.log('server render')
+  }
+}
+```
+
+### Getting Request Context
+
+When SSR is enabled, isomorphic request context can be obtained in both Node environment and browser environment.
+
+The slight difference is that the Node environment also supports setting response headers, response codes, and provides Logger logging and Metrics tracking.
+
+:::tip
+
+When SSR is not enabled, only the information that can be obtained on the browser side is included.
+
+:::
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const runtimeContext = use(RuntimeContext);
+  const { request, response } = runtimeContext.requestContext || {};
+
+  // Access request information
+  const userAgent = request?.userAgent || request?.headers?.['user-agent'];
+  const url = request?.url;
+  const query = request?.query;
+  const params = request?.params;
+
+  // Server-side can set response headers
+  if (!runtimeContext.isBrowser && response) {
+    response.setHeader('X-Custom-Header', 'value');
+    response.status(200);
+  }
+
+  return (
+    <div>
+      <div>User Agent: {userAgent}</div>
+      <div>URL: {url}</div>
+      <div>Query: {JSON.stringify(query)}</div>
+    </div>
+  );
+}
+```
+
+### Accessing Injected Global Data
+
+Global data can be injected into `RuntimeContext` through the `onBeforeRender` hook of Runtime plugins:
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = use(RuntimeContext);
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```

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

@@ -0,0 +1,283 @@
+# router
+
+:::info
+The router solution based on [react-router](https://reactrouter.com/).
+
+This page documents the React Router runtime export (`@modern-js/runtime/router`).\
+If your app uses TanStack Router (`--router tanstack`), use `@modern-js/plugin-tanstack/runtime` and refer to TanStack Router API docs.
+
+:::
+
+## 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>;
+```