[material-ui][joy-ui] Add InitColorSchemeScript for Next.js App Rou…

…ter (#42829)
mui · Jul 3, 2024 · a2972e8 · a2972e8
1 parent 5dc161b
commit a2972e8
Show file tree

Hide file tree

Showing 32 changed files with 354 additions and 175 deletions.
diff --git a/docs/data/joy/customization/dark-mode/dark-mode.md b/docs/data/joy/customization/dark-mode/dark-mode.md
@@ -12,10 +12,10 @@ When you change the `defaultMode` to another value, you must clear the local sto
 
 {{"demo": "DarkModeByDefault.js"}}
 
-For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `getInitColorSchemeScript` function:
+For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `InitColorSchemeScript` component:
 
 ```js
-getInitColorSchemeScript({ defaultMode: 'dark' });
+<InitColorSchemeScript defaultMode="dark" />
 ```
 
 ## Matching device's preference
@@ -28,10 +28,10 @@ import { CssVarsProvider } from '@mui/joy/styles';
 <CssVarsProvider defaultMode="system">...</CssVarsProvider>;
 ```
 
-For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `getInitColorSchemeScript` function:
+For server-side applications, check out the framework setup in [the section below](#server-side-rendering) and provide the same value to the `InitColorSchemeScript` component:
 
 ```js
-getInitColorSchemeScript({ defaultMode: 'system' });
+<InitColorSchemeScript defaultMode="system" />
 ```
 
 ### Identify the system mode
@@ -121,23 +121,47 @@ If you try to render your UI based on the server, before mounting on the client,
 
 ### Avoiding screen flickering
 
-To [prevent the UI from flickering](/joy-ui/main-features/dark-mode-optimization/#the-problem-flickering-on-first-load), apply `getInitColorSchemeScript()` before the main application script－it varies across frameworks:
+To [prevent the UI from flickering](/joy-ui/main-features/dark-mode-optimization/#the-problem-flickering-on-first-load), add the `<InitColorSchemeScript />` component before the `<CssVarsProvider />` component:
+
+### Next.js App Router
+
+To use the Joy UI API with a Next.js project with the App Router, add the following code to the [`app/layout.js`](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts) file in order to prevent flickering:
+
+```jsx title="layout.js"
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
+import { CssVarsProvider } from '@mui/joy/styles';
+import CssBaseline from '@mui/joy/CssBaseline';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning={true}>
+      <body>
+        <InitColorSchemeScript />
+        <CssVarsProvider>
+          <CssBaseline />
+          {children}
+        </CssVarsProvider>
+      </body>
+    </html>
+  );
+}
+```
 
 ### Next.js Pages Router
 
 To use the Joy UI API with a Next.js project, add the following code to the custom [`pages/_document.js`](https://nextjs.org/docs/pages/building-your-application/routing/custom-document) file:
 
 ```jsx
 import Document, { Html, Head, Main, NextScript } from 'next/document';
-import { getInitColorSchemeScript } from '@mui/joy/styles';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
 
 export default class MyDocument extends Document {
   render() {
     return (
       <Html data-color-scheme="light">
         <Head>...</Head>
         <body>
-          {getInitColorSchemeScript()}
+          <InitColorSchemeScript />
           <Main />
           <NextScript />
         </body>

diff --git a/docs/data/joy/main-features/dark-mode-optimization/dark-mode-optimization.md b/docs/data/joy/main-features/dark-mode-optimization/dark-mode-optimization.md
@@ -27,22 +27,22 @@ Solving this problem required us to take a novel approach to styling and theming
 
 Thanks to Joy UI's built-in support for CSS variables, your app can render all of its color schemes at build time, so that the user's preference can be injected _before_ the DOM is rendered in the browser.
 
-Joy UI provides the `getInitColorSchemeScript()` function to make this flash-free dark mode possible with React frameworks like Next.js or Remix.
+Joy UI provides the `InitColorSchemeScript` component to make this flash-free dark mode possible with React frameworks like Next.js or Remix.
 This function must be placed before the main script so it can apply the correct stylesheet before your components are rendered.
 
 The code snippet below shows how this works with the Next.js Pages Router:
 
 ```jsx
 import Document, { Html, Head, Main, NextScript } from 'next/document';
-import { getInitColorSchemeScript } from '@mui/joy/styles';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
 
 export default class MyDocument extends Document {
   render() {
     return (
       <Html data-color-scheme="light">
         <Head>...</Head>
         <body>
-          {getInitColorSchemeScript()}
+          <InitColorSchemeScript />
           <Main />
           <NextScript />
         </body>

diff --git a/docs/data/material/experimental-api/css-theme-variables/customization.md b/docs/data/material/experimental-api/css-theme-variables/customization.md
@@ -289,12 +289,10 @@ function App() {
 }
 ```
 
-For a server-side application, provide the same value to [`getInitColorSchemeScript()`](/material-ui/experimental-api/css-theme-variables/usage/#server-side-rendering):
+For a server-side application, provide the same value to [`InitColorSchemeScript`](/material-ui/experimental-api/css-theme-variables/usage/#server-side-rendering):
 
 ```js
-getInitColorSchemeScript({
-  defaultMode: 'dark',
-});
+<InitColorSchemeScript defaultMode="dark" />
 ```
 
 :::warning

diff --git a/docs/data/material/experimental-api/css-theme-variables/migration.md b/docs/data/material/experimental-api/css-theme-variables/migration.md
@@ -180,23 +180,23 @@ The `mode` is stored inside `CssVarsProvider` which handles local storage synchr
 
 ## 3. Prevent dark-mode flickering in server-side applications
 
-The `getInitColorSchemeScript()` API prevents dark-mode flickering by returning a script that must be run before React.
+The `InitColorSchemeScript` component prevents dark-mode flickering by returning a script that must be run before React.
 
 ### Next.js Pages Router
 
-Place the script before `<Main />` in your [`pages/_document.js`](https://nextjs.org/docs/pages/building-your-application/routing/custom-document):
+Place the component before `<Main />` in your [`pages/_document.js`](https://nextjs.org/docs/pages/building-your-application/routing/custom-document):
 
 ```jsx
 import Document, { Html, Head, Main, NextScript } from 'next/document';
-import { getInitColorSchemeScript } from '@mui/material/styles';
+import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';
 
 export default class MyDocument extends Document {
   render() {
     return (
       <Html data-color-scheme="light">
         <Head>...</Head>
         <body>
-          {getInitColorSchemeScript()}
+          <InitColorSchemeScript />
           <Main />
           <NextScript />
         </body>
@@ -212,10 +212,10 @@ Place the script in your [`gatsby-ssr.js`](https://www.gatsbyjs.com/docs/referen
 
 ```jsx
 import * as React from 'react';
-import { getInitColorSchemeScript } from '@mui/material/styles';
+import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';
 
 export function onRenderBody({ setPreBodyComponents }) {
-  setPreBodyComponents([getInitColorSchemeScript()]);
+  setPreBodyComponents([<InitColorSchemeScript />]);
 }
 ```
 

diff --git a/docs/data/material/experimental-api/css-theme-variables/usage/usage.md b/docs/data/material/experimental-api/css-theme-variables/usage/usage.md
@@ -116,23 +116,42 @@ The structure of this object is nearly identical to the theme structure, the onl
 
 ## Server-side rendering
 
-Place `getInitColorSchemeScript()` before the `<Main />` tag to prevent the dark-mode SSR flickering during the hydration phase.
+Place `<InitColorSchemeScript />` before the `<Main />` tag to prevent the dark-mode SSR flickering during the hydration phase.
+
+### Next.js App Router
+
+Add the following code to the [root layout](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) file:
+
+```jsx title="app/layout.js"
+import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <InitColorSchemeScript /> {/* must come before the <main> element */}
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+```
 
 ### Next.js Pages Router
 
 Add the following code to the custom [`pages/_document.js`](https://nextjs.org/docs/pages/building-your-application/routing/custom-document) file:
 
-```jsx
+```jsx title="pages/_document.js"
 import Document, { Html, Head, Main, NextScript } from 'next/document';
-import { getInitColorSchemeScript } from '@mui/material/styles';
+import InitColorSchemeScript from '@mui/material/InitColorSchemeScript';
 
 export default class MyDocument extends Document {
   render() {
     return (
       <Html data-color-scheme="light">
         <Head>...</Head>
         <body>
-          {getInitColorSchemeScript()}
+          <InitColorSchemeScript /> {/* must come before the <Main> element */}
           <Main />
           <NextScript />
         </body>
@@ -159,7 +178,7 @@ const StyledComponent = styled('button')(({ theme }) => ({
 
 ## API
 
-### `<CssVarsProvider>` props
+### `<CssVarsProvider>` &nbsp;props
 
 - `defaultMode?: 'light' | 'dark' | 'system'` - Application's default mode (`light` by default)
 - `disableTransitionOnChange : boolean` - Disable CSS transitions when switching between modes
@@ -172,10 +191,9 @@ const StyledComponent = styled('button')(({ theme }) => ({
 - `mode: string` - The user's selected mode
 - `setMode: mode => {…}` - Function for setting the `mode`. The `mode` is saved to internal state and local storage; if `mode` is null, it will be reset to the default mode
 
-### `getInitColorSchemeScript: (options) => React.ReactElement`
-
-**options**
+### `<InitColorSchemeScript>` &nbsp;props
 
 - `defaultMode?: 'light' | 'dark' | 'system'`: - Application's default mode before React renders the tree (`light` by default)
 - `modeStorageKey?: string`: - localStorage key used to store application `mode`
 - `attribute?: string` - DOM attribute for applying color scheme
+- `nonce?: string` - Optional nonce passed to the injected script tag, used to allow-list the next-themes script in your CSP
diff --git a/docs/pages/_document.js b/docs/pages/_document.js
@@ -5,8 +5,8 @@ import { ServerStyleSheets as JSSServerStyleSheets } from '@mui/styles';
 import { ServerStyleSheet } from 'styled-components';
 import Document, { Html, Head, Main, NextScript } from 'next/document';
 import GlobalStyles from '@mui/material/GlobalStyles';
-import { getInitColorSchemeScript as getMuiInitColorSchemeScript } from '@mui/material/styles';
-import { getInitColorSchemeScript as getJoyInitColorSchemeScript } from '@mui/joy/styles';
+import MuiInitColorSchemeScript from '@mui/material/InitColorSchemeScript';
+import JoyInitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
 import { pathnameToLanguage } from 'docs/src/modules/utils/helpers';
 import createEmotionCache from 'docs/src/createEmotionCache';
 import { getMetaThemeColor } from '@mui/docs/branding';
@@ -173,8 +173,8 @@ export default class MyDocument extends Document {
           />
         </Head>
         <body>
-          {getMuiInitColorSchemeScript({ defaultMode: 'system' })}
-          {getJoyInitColorSchemeScript({ defaultMode: 'system' })}
+          <MuiInitColorSchemeScript defaultMode="system" />
+          <JoyInitColorSchemeScript defaultMode="system" />
           <Main />
           <script
             // eslint-disable-next-line react/no-danger

diff --git a/docs/pages/blog/first-look-at-joy.md b/docs/pages/blog/first-look-at-joy.md
@@ -93,20 +93,20 @@ You're still able to override the style completely via the usual CSS overrides,
 Joy UI provides an effective way to prevent UI flicker when users refresh or re-enter a page with dark mode enabled.
 The out-of-the-box CSS variables support allows every color scheme to be rendered at build time, inserting the selected color scheme and mode before the browser renders the DOM.
 
-What's more, it provides a function called `getInitColorSchemeScript()` that enables you to have perfect functioning dark mode in various React frameworks, such as Next.js, Gatsby, and Remix.
+What's more, it provides a component called `InitColorSchemeScript` that enables you to have perfect functioning dark mode in various React frameworks, such as Next.js, Gatsby, and Remix.
 
 ```js
 // A Next.js example
 import Document, { Html, Head, Main, NextScript } from 'next/document';
-import { getInitColorSchemeScript } from '@mui/joy/styles';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
 
 export default class MyDocument extends Document {
   render() {
     return (
       <Html data-color-scheme="light">
         <Head>...</Head>
         <body>
-          {getInitColorSchemeScript()}
+          <InitColorSchemeScript />
           <Main />
           <NextScript />
         </body>

diff --git a/packages/api-docs-builder-core/joyUi/projectSettings.ts b/packages/api-docs-builder-core/joyUi/projectSettings.ts
@@ -26,8 +26,9 @@ export const projectSettings: ProjectSettings = {
     // Container's demo isn't ready
     // GlobalStyles's demo isn't ready
     return (
-      filename.match(/(ThemeProvider|CssVarsProvider|Container|ColorInversion|GlobalStyles)/) !==
-      null
+      filename.match(
+        /(ThemeProvider|CssVarsProvider|Container|ColorInversion|GlobalStyles|InitColorSchemeScript)/,
+      ) !== null
     );
   },
   translationPagesDirectory: 'docs/translations/api-docs-joy',

diff --git a/packages/api-docs-builder-core/materialUi/projectSettings.ts b/packages/api-docs-builder-core/materialUi/projectSettings.ts
@@ -28,7 +28,11 @@ export const projectSettings: ProjectSettings = {
   getComponentInfo: getMaterialUiComponentInfo,
   translationLanguages: LANGUAGES,
   skipComponent(filename: string) {
-    return filename.match(/(ThemeProvider|CssVarsProvider|DefaultPropsProvider|Grid2)/) !== null;
+    return (
+      filename.match(
+        /(ThemeProvider|CssVarsProvider|InitColorSchemeScript|DefaultPropsProvider|Grid2)/,
+      ) !== null
+    );
   },
   translationPagesDirectory: 'docs/translations/api-docs',
   generateClassName: generateUtilityClass,

diff --git a/packages/api-docs-builder-core/muiSystem/projectSettings.ts b/packages/api-docs-builder-core/muiSystem/projectSettings.ts
@@ -24,7 +24,9 @@ export const projectSettings: ProjectSettings = {
   translationLanguages: LANGUAGES,
   skipComponent(filename) {
     return (
-      filename.match(/(ThemeProvider|CssVarsProvider|DefaultPropsProvider|GlobalStyles)/) !== null
+      filename.match(
+        /(ThemeProvider|CssVarsProvider|InitColorSchemeScript|DefaultPropsProvider|GlobalStyles)/,
+      ) !== null
     );
   },
   translationPagesDirectory: 'docs/translations/api-docs',

diff --git a/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts b/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts
@@ -773,7 +773,7 @@ export default async function generateComponentApi(
     throw new Error(
       'Unable to find demos. \n' +
         `Be sure to include \`components: ${reactApi.name}\` in the markdown pages where the \`${reactApi.name}\` component is relevant. ` +
-        'Every public component should have a demo. ',
+        'Every public component should have a demo.\nFor internal component, add the name of the component to the `skipComponent` method of the product.',
     );
   }
 

diff --git a/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.spec.tsx b/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.spec.tsx
@@ -0,0 +1,4 @@
+import * as React from 'react';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
+
+<InitColorSchemeScript nonce="foo-bar" />;
diff --git a/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.test.tsx b/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.test.tsx
@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { createRenderer } from '@mui-internal/test-utils';
+import InitColorSchemeScript from '@mui/joy/InitColorSchemeScript';
+
+describe('InitColorSchemeScript', () => {
+  const { render } = createRenderer();
+
+  it('should render as expected', () => {
+    const { container } = render(<InitColorSchemeScript />);
+    expect(container.firstChild).to.have.tagName('script');
+  });
+});
diff --git a/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.tsx b/packages/mui-joy/src/InitColorSchemeScript/InitColorSchemeScript.tsx
@@ -0,0 +1,14 @@
+import * as React from 'react';
+import SystemInitColorSchemeScript from '@mui/system/InitColorSchemeScript';
+
+export const defaultConfig = {
+  attribute: 'data-joy-color-scheme',
+  colorSchemeStorageKey: 'joy-color-scheme',
+  defaultLightColorScheme: 'light',
+  defaultDarkColorScheme: 'dark',
+  modeStorageKey: 'joy-mode',
+} as const;
+
+export default (function InitColorSchemeScript(props) {
+  return <SystemInitColorSchemeScript {...defaultConfig} {...props} />;
+} as typeof SystemInitColorSchemeScript);
diff --git a/packages/mui-joy/src/InitColorSchemeScript/index.ts b/packages/mui-joy/src/InitColorSchemeScript/index.ts
@@ -0,0 +1 @@
+export { default } from './InitColorSchemeScript';