@modern-js/main-doc 2.1.0 → 2.3.0

package/en/apis/app/runtime/router/router.mdx

@@ -0,0 +1,262 @@
+---
+title: router
+sidebar_position: 1
+---
+# router
+
+:::info
+The router solution based on [react-router 6](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>
+  );
+}
+```
+
+## 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/en/apis/app/runtime/ssr/no-ssr.mdx

@@ -0,0 +1,38 @@
+---
+title: NoSSR
+---
+# 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/apis/app/runtime/ssr/pre-render.mdx

@@ -0,0 +1,96 @@
+---
+title: PreRender
+---
+# 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/apis/app/runtime/testing/act.mdx

@@ -0,0 +1,35 @@
+---
+title: act
+---
+# 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/apis/app/runtime/testing/cleanup.mdx

@@ -0,0 +1,40 @@
+---
+title: cleanup
+sidebar_position: 3
+---
+# cleanup
+
+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 ...
+```

package/en/apis/app/runtime/testing/render.mdx

@@ -0,0 +1,71 @@
+---
+title: render
+---
+# render
+
+Used to render the component in the test case.
+
+## Usage
+
+```ts
+import { render } from '@modern-js/runtime/testing';
+```
+
+## Function Signature
+
+```ts
+type Options = {
+  container: DOMElement;
+  baseElement: DOMElement;
+  hydrate: boolean;
+  warpper: React.ComponentType<{children: ReactNode}>;
+  queries: any;
+};
+
+type RenderResult = {
+  {...queries}: any;
+  container: DOMElement;
+  baseElement: DOMElement;
+  debug: function;
+  rerender: function;
+  unmount: function;
+  asFragment: function;
+}
+
+function render(ui: React.ReactElement<any>, options: Options): RenderResult;
+```
+
+### Input
+
+- `ui`: the React component that needs to be rendered.
+- `options`: render options.
+  - `container`: the dom which component mounted. by default create a `div` element，and auto append to `document.body`. the default value is `document.body.append(document.createElement('div'))`.
+  - `baseElement`: Used to specify the `basename` used in `queries`. If `container` is specified, the default value is the value of `container`, otherwise it is `document.body`.
+  - `hydrate`: If set to `true`, the [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) rendering component is used. The default value is `false`.
+  - `wrapper`: a react component that can be used to customize rendering logic.
+  - `queries`: customize some own `queries`.
+
+### Return Value
+
+- `{...queries}`: all available [queries](https://testing-library.com/docs/queries/about/)。
+- `container`: the DOM element that React component mounted.
+- `baseElement`
+- `debug`
+- `rerender`: if you want to test some scene when a rendered component is updated, you can use rerender for reality.
+- `unmount`: unmount rendered components. This API is helpful if you want to test what happens after the component is unmounted.
+- `asFragment`: return the [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) of rendered component. used to test the response of the DOM structure after the react event is triggered.
+
+## Example
+
+```ts
+import { render } from '@modern-js/runtime/testing';
+import App from './App';
+
+test('renders a message', () => {
+  const { container, getByText } = render(<App />);
+  expect(getByText('Hello, world!')).toBeInTheDocument();
+  expect(container.firstChild).toMatchInlineSnapshot(`
+    <h1>Hello, World!</h1>
+  `);
+});
+```

package/en/apis/app/runtime/testing/renderApp.mdx

@@ -0,0 +1,34 @@
+---
+title: renderApp
+---
+# renderApp
+
+The `render` function is used to test normal components, and the `renderApp` function is used to test App components.
+
+## Usage
+
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+```
+
+App components refer to components that contain some Modern.js contexts, such as App root components, Containers using Models, etc.
+
+For the testing of such components, you can use the `renderApp` function, which will automatically wrap the context information according to the current `modern.config.js`.
+
+## Function Signature
+
+`renderApp` is the same as [render](./render.md).
+
+## Example
+
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+import App from './App';
+
+describe('test', () => {
+  it('test App', () => {
+    const { getByText } = renderApp(<App />);
+    expect(getByText('Hello Modern!')).toBeInTheDocument();
+  });
+});
+```

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

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

@@ -0,0 +1,38 @@
+---
+title: Head
+---
+# 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).