@modern-js/main-doc 2.33.1 → 2.34.0

package/docs/en/configure/app/server/ssr.mdx

@@ -28,6 +28,8 @@ When the value type is `Object`, the following properties can be configured:
 - `mode`: `string = 'string'`, which defaults to using `renderToString` for rendering. Configure `stream` to enable streaming rendering.
 - `forceCSR`: `boolean = false`, which is off by default for forcing CSR rendering. Configure `true` to force CSR by adding `?csr=true` or adding `x-modern-ssr-fallback` header when accessing the page.
 - `inlineScript`: `boolean = true`, by default, SSR data is injected into HTML as inline scripts and assigned directly to global variables. Configure `false` to distribute JSON instead of assigning to global variables.
+- `disablePrerender`: `boolean = fasle`, To ensure compatibility with the old data request method (`useLoader`), by default, Modern.js performs pre-rendering of components.
+  However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration `disablePrerender=true`.
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/en/tutorials/examples/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Examples",
+  "position": 3,
+  "collapsed": false
+}

package/docs/en/tutorials/examples/csr-auth.mdx

@@ -0,0 +1,214 @@
+---
+title: Route Authorization
+---
+
+# Route Authorization
+
+Modern.js defaults to the convention-based routing based on React Router 6. For more details, please refer to [Routing](/guides/basic-features/routes.html#routing-scheme).
+
+In a web application, if there are multiple routes, we may need to authorize access to some of them before accessing them. For example, in the following scenario:
+
+- Access to the `/` route does not require authorization and can be accessed directly.
+- Access to the `/protected` route requires authorization. If there is no authorization, it will automatically redirect to the `/login` route. After successful login, it returns to `/protected`.
+
+import Sandpack from '@site/src/components/Sandpack';
+
+<Sandpack template="web-app">
+```tsx title="src/routes/page.tsx"
+import { Helmet } from '@modern-js/runtime/head';
+import './index.css';
+
+const PublicPage = (): JSX.Element => (
+  <div className="container-box">
+    <Helmet>
+      <link
+        rel="icon"
+        type="image/x-icon"
+        href="https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico"
+      />
+    </Helmet>
+    <h3>Public</h3>
+  </div>
+);
+
+export default PublicPage;
+
+```
+```tsx title="src/routes/layout.tsx"
+import { Link, Outlet } from '@modern-js/runtime/router';
+import { AuthProvider, AuthStatus } from './Auth';
+
+export default function Layout() {
+  return (
+    <AuthProvider>
+      <AuthStatus />
+
+      <ul>
+        <li>
+          <Link to="/">Public Page</Link>
+        </li>
+        <li>
+          <Link to="/protected">Protected Page</Link>
+        </li>
+      </ul>
+
+      <Outlet />
+    </AuthProvider>
+  );
+}
+
+```
+```ts title="src/routes/fakeAuth.ts"
+/**
+ * This represents some generic auth provider API, like Firebase.
+ */
+const fakeAuthProvider = {
+  isAuthenticated: false,
+  signin(callback: VoidFunction) {
+    fakeAuthProvider.isAuthenticated = true;
+    setTimeout(callback, 100); // fake async
+  },
+  signout(callback: VoidFunction) {
+    fakeAuthProvider.isAuthenticated = false;
+    setTimeout(callback, 100);
+  },
+};
+
+export { fakeAuthProvider };
+
+```
+```ts title="src/routes/Auth.tsx"
+import React from 'react';
+import { useNavigate, Navigate, useLocation } from '@modern-js/runtime/router';
+import { fakeAuthProvider } from './fakeAuth';
+
+interface AuthContextType {
+  user: any;
+  signin: (user: string, callback: VoidFunction) => void;
+  signout: (callback: VoidFunction) => void;
+}
+
+const AuthContext = React.createContext<AuthContextType>(null!);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [user, setUser] = React.useState<any>(null);
+
+  const signin = (newUser: string, callback: VoidFunction) =>
+    fakeAuthProvider.signin(() => {
+      setUser(newUser);
+      callback();
+    });
+
+  const signout = (callback: VoidFunction) =>
+    fakeAuthProvider.signout(() => {
+      setUser(null);
+      callback();
+    });
+
+  const value = { user, signin, signout };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth() {
+  return React.useContext(AuthContext);
+}
+
+export function AuthStatus() {
+  const auth = useAuth();
+  console.log('auth', auth);
+  const navigate = useNavigate();
+
+  if (!auth.user) {
+    return <p>You are not logged in.</p>;
+  }
+
+  return (
+    <p>
+      Welcome {auth.user}!{' '}
+      <button
+        type="button"
+        onClick={() => {
+          auth.signout(() => navigate('/'));
+        }}
+      >
+        Sign out
+      </button>
+    </p>
+  );
+}
+
+export function RequireAuth({ children }: { children: JSX.Element }) {
+  const auth = useAuth();
+  const location = useLocation();
+
+  if (!auth.user) {
+    // Redirect them to the /login page, but save the current location they were
+    // trying to go to when they were redirected. This allows us to send them
+    // along to that page after they login, which is a nicer user experience
+    // than dropping them off on the home page.
+    return <Navigate to="/login" state={{ from: location }} replace />;
+  }
+
+  return children;
+}
+
+```
+```ts title="src/routes/protected/page.tsx"
+import { RequireAuth } from '../Auth';
+
+export default function ProtectedPage() {
+  return (
+    <div className="container-box">
+      <RequireAuth>
+        <h3>Protected</h3>
+      </RequireAuth>
+    </div>
+  );
+}
+
+```
+```ts title="src/routes/login/page.tsx"
+import { useLocation, useNavigate } from '@modern-js/runtime/router';
+import { useAuth } from '../Auth';
+
+export default function Login() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const auth = useAuth();
+
+  const from = location.state?.from?.pathname || '/';
+
+  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+
+    const formData = new FormData(event.currentTarget);
+    const username = formData.get('username') as string;
+
+    auth.signin(username, () => {
+      // Send them back to the page they tried to visit when they were
+      // redirected to the login page. Use { replace: true } so we don't create
+      // another entry in the history stack for the login page.  This means that
+      // when they get to the protected page and click the back button, they
+      // won't end up back on the login page, which is also really nice for the
+      // user experience.
+      navigate(from, { replace: true });
+    });
+  }
+
+  return (
+    <div>
+      <p>You must log in to view the page at {from}</p>
+
+      <form onSubmit={handleSubmit}>
+        <label>
+          Username: <input name="username" type="text" />
+        </label>{' '}
+        <button type="submit">Login</button>
+      </form>
+    </div>
+  );
+}
+
+```
+</Sandpack>

package/docs/en/tutorials/foundations/introduction.mdx

@@ -24,5 +24,14 @@ We have prepared a tutorial on creating a "contact list app" that you can follow
 - Data fetching
 - State Management
 - Container components
-- New portal
+- New entry
 - ...
+
+## Case Studies
+
+We offer some commonly used case studies for your reference during the development process. Here you can find some usage patterns of the feature combinations provided by Modern.js. We will continue to improve the case studies here.
+
+- [Route Authorization](/tutorials/examples/csr-auth.html)
+- ...
+
+Let's start from [creating a project](tutorials/first-app/c01-start) now!

package/docs/zh/configure/app/server/ssr.mdx

@@ -28,6 +28,8 @@ export default defineConfig({
 - `mode`：`string = 'string'`，默认为使用 `renderToString` 渲染。配置为 `stream` 开启流式渲染。
 - `forceCSR`：`boolean = false`，默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR。
 - `inlineScript`：`boolean = true`，默认情况下，SSR 的数据会以内联脚本的方式注入到 HTML 中，并且直接赋值给全局变量。配置为 `false` 后，会下发 JSON，而不是赋值给全局变量。
+- `disablePrerender`: `boolean = fasle`, 为了兼容旧数据请求方式 - `useLoader`, 默认情况下 Modern.js 会对组件进行一次预渲染即有两次渲染。
+  开发者在保证项目中没有使用 useLoader Api 情况下, 可通过配置 `disablePrerender=true`来减少一次渲染。
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -36,6 +38,7 @@ export default defineConfig({
       forceCSR: true,
       mode: 'stream',
       inlineScript: false,
+      disablePrerender: true,
     },
   },
 });

package/docs/zh/guides/basic-features/routes.mdx

@@ -207,7 +207,7 @@ export default () => {
     └── page.tsx
 ```
 
-`routes/user/[id$]/page.tsx` 文件会转为 `/user/:id?` 路由。`/user` 下的所有路由都会匹配到该路由，并且 `id` 参数可选存在。通常在区分**创建**于**编辑**时，可以使用该路由。
+`routes/user/[id$]/page.tsx` 文件会转为 `/user/:id?` 路由。`/user` 下的所有路由都会匹配到该路由，并且 `id` 参数可选存在。通常在区分**创建**与**编辑**时，可以使用该路由。
 
 在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
 

package/docs/zh/tutorials/examples/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "案例",
+  "position": 3,
+  "collapsed": false
+}

package/docs/zh/tutorials/examples/csr-auth.mdx

@@ -0,0 +1,214 @@
+---
+title: 路由鉴权
+---
+
+# 路由鉴权
+
+Modern.js 默认提供的路由方式是基于 React Router 6 的约定式路由，具体可查看[路由方案](/guides/basic-features/routes.html#路由方案)。
+
+在一个 Web 应用中如果存在多个路由，我们可能需要对部分路由进行鉴权后才能访问。例如下面这个案例：
+
+- 访问 `/` 路由，无需鉴权，可直接访问。
+- 访问 `/protected` 路由，需要鉴权，如果无，自动跳转到 `/login` 路由，登录成功后返回 `/protected`。
+
+import Sandpack from '@site/src/components/Sandpack';
+
+<Sandpack template="web-app">
+```tsx title="src/routes/page.tsx"
+import { Helmet } from '@modern-js/runtime/head';
+import './index.css';
+
+const PublicPage = (): JSX.Element => (
+  <div className="container-box">
+    <Helmet>
+      <link
+        rel="icon"
+        type="image/x-icon"
+        href="https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico"
+      />
+    </Helmet>
+    <h3>Public</h3>
+  </div>
+);
+
+export default PublicPage;
+
+```
+```tsx title="src/routes/layout.tsx"
+import { Link, Outlet } from '@modern-js/runtime/router';
+import { AuthProvider, AuthStatus } from './Auth';
+
+export default function Layout() {
+  return (
+    <AuthProvider>
+      <AuthStatus />
+
+      <ul>
+        <li>
+          <Link to="/">Public Page</Link>
+        </li>
+        <li>
+          <Link to="/protected">Protected Page</Link>
+        </li>
+      </ul>
+
+      <Outlet />
+    </AuthProvider>
+  );
+}
+
+```
+```ts title="src/routes/fakeAuth.ts"
+/**
+ * This represents some generic auth provider API, like Firebase.
+ */
+const fakeAuthProvider = {
+  isAuthenticated: false,
+  signin(callback: VoidFunction) {
+    fakeAuthProvider.isAuthenticated = true;
+    setTimeout(callback, 100); // fake async
+  },
+  signout(callback: VoidFunction) {
+    fakeAuthProvider.isAuthenticated = false;
+    setTimeout(callback, 100);
+  },
+};
+
+export { fakeAuthProvider };
+
+```
+```ts title="src/routes/Auth.tsx"
+import React from 'react';
+import { useNavigate, Navigate, useLocation } from '@modern-js/runtime/router';
+import { fakeAuthProvider } from './fakeAuth';
+
+interface AuthContextType {
+  user: any;
+  signin: (user: string, callback: VoidFunction) => void;
+  signout: (callback: VoidFunction) => void;
+}
+
+const AuthContext = React.createContext<AuthContextType>(null!);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [user, setUser] = React.useState<any>(null);
+
+  const signin = (newUser: string, callback: VoidFunction) =>
+    fakeAuthProvider.signin(() => {
+      setUser(newUser);
+      callback();
+    });
+
+  const signout = (callback: VoidFunction) =>
+    fakeAuthProvider.signout(() => {
+      setUser(null);
+      callback();
+    });
+
+  const value = { user, signin, signout };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth() {
+  return React.useContext(AuthContext);
+}
+
+export function AuthStatus() {
+  const auth = useAuth();
+  console.log('auth', auth);
+  const navigate = useNavigate();
+
+  if (!auth.user) {
+    return <p>You are not logged in.</p>;
+  }
+
+  return (
+    <p>
+      Welcome {auth.user}!{' '}
+      <button
+        type="button"
+        onClick={() => {
+          auth.signout(() => navigate('/'));
+        }}
+      >
+        Sign out
+      </button>
+    </p>
+  );
+}
+
+export function RequireAuth({ children }: { children: JSX.Element }) {
+  const auth = useAuth();
+  const location = useLocation();
+
+  if (!auth.user) {
+    // Redirect them to the /login page, but save the current location they were
+    // trying to go to when they were redirected. This allows us to send them
+    // along to that page after they login, which is a nicer user experience
+    // than dropping them off on the home page.
+    return <Navigate to="/login" state={{ from: location }} replace />;
+  }
+
+  return children;
+}
+
+```
+```ts title="src/routes/protected/page.tsx"
+import { RequireAuth } from '../Auth';
+
+export default function ProtectedPage() {
+  return (
+    <div className="container-box">
+      <RequireAuth>
+        <h3>Protected</h3>
+      </RequireAuth>
+    </div>
+  );
+}
+
+```
+```ts title="src/routes/login/page.tsx"
+import { useLocation, useNavigate } from '@modern-js/runtime/router';
+import { useAuth } from '../Auth';
+
+export default function Login() {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const auth = useAuth();
+
+  const from = location.state?.from?.pathname || '/';
+
+  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+
+    const formData = new FormData(event.currentTarget);
+    const username = formData.get('username') as string;
+
+    auth.signin(username, () => {
+      // Send them back to the page they tried to visit when they were
+      // redirected to the login page. Use { replace: true } so we don't create
+      // another entry in the history stack for the login page.  This means that
+      // when they get to the protected page and click the back button, they
+      // won't end up back on the login page, which is also really nice for the
+      // user experience.
+      navigate(from, { replace: true });
+    });
+  }
+
+  return (
+    <div>
+      <p>You must log in to view the page at {from}</p>
+
+      <form onSubmit={handleSubmit}>
+        <label>
+          Username: <input name="username" type="text" />
+        </label>{' '}
+        <button type="submit">Login</button>
+      </form>
+    </div>
+  );
+}
+
+```
+</Sandpack>

package/docs/zh/tutorials/foundations/introduction.mdx

@@ -27,4 +27,12 @@ sidebar_position: 1
 - 新建入口
 - ...
 
+## 案例
+
+我们提供了一些在开发过程中常用的案例供你参考，可以在这里找到 Modern.js 提供的一些功能组合的使用方式，我们将持续完善这里的案例。
+
+- [路由鉴权](/tutorials/examples/csr-auth.html)
+- ...
+
 下面就让我们从 [创建项目](tutorials/first-app/c01-start) 开始吧！
+

package/package.json

@@ -15,14 +15,17 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.33.1",
+  "version": "2.34.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "@modern-js/sandpack-react": "2.34.0"
+  },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.33.1"
+    "@modern-js/builder-doc": "^2.34.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -36,8 +39,8 @@
     "@rspress/shared": "0.0.6",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.33.1",
-    "@modern-js/doc-plugin-auto-sidebar": "2.33.1"
+    "@modern-js/builder-doc": "2.34.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.34.0"
   },
   "scripts": {
     "dev": "rspress dev",

package/src/components/Sandpack/index.css

@@ -0,0 +1,10 @@
+.light {
+  --sp-layout-height: 500px !important;
+}
+
+.dark {
+  --sp-layout-height: 500px !important;
+}
+.sp-read-only {
+  display: none;
+}

package/src/components/Sandpack/index.tsx

@@ -0,0 +1,30 @@
+import ModernSandpack, { ModernSandpackProps } from '@modern-js/sandpack-react';
+import React, { PropsWithChildren } from 'react';
+import { useDark, NoSSR } from 'rspress/runtime';
+
+import './index.css';
+
+const Sandpack = (props: PropsWithChildren<ModernSandpackProps>) => {
+  const dark = useDark();
+  const { children, ...otherProps } = props;
+  const files: Record<string, string> = {};
+  React.Children.forEach(children, (child: any) => {
+    if (child) {
+      const { meta, children } = child.props.children.props;
+      const matches = meta.match(/title="(.*)"/);
+      if (matches.length > 1) {
+        files[matches[1]] = children;
+      }
+    }
+  });
+  return (
+    <NoSSR>
+      <ModernSandpack
+        files={files}
+        theme={dark ? 'dark' : 'light'}
+        {...otherProps}
+      />
+    </NoSSR>
+  );
+};
+export default Sandpack;