[material-ui][docs] Open Material UI template with CodeSandbox/StackBlitz

.circleci/config.yml

@@ -299,12 +299,6 @@ jobs:
           command: |
             pnpm docs:link-check
             git add -A && git diff --exit-code --staged
-      - run:
-          name: Update the templates shared themes
-          command: pnpm template:update-theme
-      - run:
-          name: '`pnpm template:update-theme` changes committed?'
-          command: git add -A && git diff --exit-code --staged
   test_types:
     <<: *default-job
     resource_class: 'medium+'

docs/data/material/getting-started/faq/faq.md

@@ -261,6 +261,81 @@
 
 If you are getting the error: `TypeError: Cannot convert a Symbol value to a string`, take a look at the [styled()](/system/styled/#how-to-use-components-selector-api) docs page for instructions on how you can fix this.
 
+## How can I contribute to the free templates?
+
+The templates are built using a [shared theme](https://github.com/mui/material-ui/tree/v6.0.2/docs/data/material/getting-started/templates/shared-theme). Below are the structure to create a new template:
+
+### Template page
+
+Create a new page in the `docs/pages/material-ui/getting-started/templates/<name>.js` directory with the following code:
+
+```js
+import * as React from 'react';
+import AppTheme from 'docs/src/modules/components/AppTheme';
+import TemplateFrame from 'docs/src/modules/components/TemplateFrame';
+import Template from 'docs/data/material/getting-started/templates/<name>/<Template>';
+
+export default function Page() {
+  return (
+    <AppTheme>
+      <TemplateFrame>
+        <Template />
+      </TemplateFrame>
+    </AppTheme>
+  );
+}
+```
+
+Then create a template file at `docs/data/material/getting-started/templates/<name>/<Template>.tsx` (add more files if needed):
+
+> Note: The `<Template>` must be a pascal case string of the `<name>` folder.
+
+### Shared theme
+
+The template must use `AppTheme` from `../shared-theme/AppTheme` to ensure a consistent look and feel across all templates.
+
+If the template includes custom-themed components, such as the dashboard template with MUI X themed components, pass them to the `AppTheme`'s `themedComponents` prop:
+
+```js
+import AppTheme from '../shared-theme/AppTheme';
+
+const xThemeComponents = {
+  ...chartsCustomizations,
+  ...dataGridCustomizations,
+  ...datePickersCustomizations,
+  ...treeViewCustomizations,
+};
+
+export default function Dashboard(props: { disableCustomTheme?: boolean }) {
+  return (
+    <AppTheme {...props} themeComponents={xThemeComponents}>...</AppTheme>
+  )
+}
+```
+
+### Color mode toggle
+
+The shared theme provides 2 appearance of the color mode toggle, `ColorModeSelect` and `ColorModeIconDropdown`.
+You can use either of them in your template, it will be hidden within the `TemplateFrame` but will be visible in the Code Sandbox and Stackblitz.
+
+### Template frame
+
+If the template has a sidebar or a header that needs to stick to the top, refer to the CSS variable `--template-frame-height` to adjust.
+
+For example, the dashboard template has a fixed header that needs to be accounted for the template frame height:
+
+```js
+<AppBar
+  position="fixed"
+  sx={{
+    top: 'var(--template-frame-height, 0px)',
+    // ...other styles
+  }}
+>
+```
+
+This will make the `AppBar` stay below the `TemplateFrame` in a preview mode but stick to the top in the CodeSandbox and Stackblitz.
+
 ## [legacy] I have several instances of styles on the page
 
 If you are seeing a warning message in the console like the one below, you probably have several instances of `@mui/styles` initialized on the page.

docs/data/material/getting-started/templates/dashboard/Dashboard.js

@@ -1,81 +1,60 @@
 import * as React from 'react';
-import { createTheme, ThemeProvider, alpha } from '@mui/material/styles';
+
+import { alpha } from '@mui/material/styles';
 import CssBaseline from '@mui/material/CssBaseline';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
-import getDashboardTheme from './theme/getDashboardTheme';
 import AppNavbar from './components/AppNavbar';
 import Header from './components/Header';
 import MainGrid from './components/MainGrid';
 import SideMenu from './components/SideMenu';
-import TemplateFrame from './TemplateFrame';
-
-export default function Dashboard() {
-  const [mode, setMode] = React.useState('light');
-  const [showCustomTheme, setShowCustomTheme] = React.useState(true);
-  const dashboardTheme = createTheme(getDashboardTheme(mode));
-  const defaultTheme = createTheme({ palette: { mode } });
-  // This code only runs on the client side, to determine the system color preference
-  React.useEffect(() => {
-    // Check if there is a preferred mode in localStorage
-    const savedMode = localStorage.getItem('themeMode');
-    if (savedMode) {
-      setMode(savedMode);
-    } else {
-      // If no preference is found, it uses system preference
-      const systemPrefersDark = window.matchMedia(
-        '(prefers-color-scheme: dark)',
-      ).matches;
-      setMode(systemPrefersDark ? 'dark' : 'light');
-    }
-  }, []);
-
-  const toggleColorMode = () => {
-    const newMode = mode === 'dark' ? 'light' : 'dark';
-    setMode(newMode);
-    localStorage.setItem('themeMode', newMode); // Save the selected mode to localStorage
-  };
+import AppTheme from '../shared-theme/AppTheme';
+import {
+  chartsCustomizations,
+  dataGridCustomizations,
+  datePickersCustomizations,
+  treeViewCustomizations,
+} from './theme/customizations';
 
-  const toggleCustomTheme = () => {
-    setShowCustomTheme((prev) => !prev);
-  };
+const xThemeComponents = {
+  ...chartsCustomizations,
+  ...dataGridCustomizations,
+  ...datePickersCustomizations,
+  ...treeViewCustomizations,
+};
 
+export default function Dashboard(props) {
   return (
-    <TemplateFrame
-      toggleCustomTheme={toggleCustomTheme}
-      showCustomTheme={showCustomTheme}
-      mode={mode}
-      toggleColorMode={toggleColorMode}
-    >
-      <ThemeProvider theme={showCustomTheme ? dashboardTheme : defaultTheme}>
-        <CssBaseline enableColorScheme />
-        <Box sx={{ display: 'flex' }}>
-          <SideMenu />
-          <AppNavbar />
-          {/* Main content */}
-          <Box
-            component="main"
-            sx={(theme) => ({
-              flexGrow: 1,
-              backgroundColor: alpha(theme.palette.background.default, 1),
-              overflow: 'auto',
-            })}
+    <AppTheme {...props} themeComponents={xThemeComponents}>
+      <CssBaseline enableColorScheme />
+      <Box sx={{ display: 'flex' }}>
+        <SideMenu />
+        <AppNavbar />
+        {/* Main content */}
+        <Box
+          component="main"
+          sx={(theme) => ({
+            flexGrow: 1,
+            backgroundColor: theme.vars
+              ? `rgba(${theme.vars.palette.background.defaultChannel} / 1)`
+              : alpha(theme.palette.background.default, 1),
+            overflow: 'auto',
+          })}
+        >
+          <Stack
+            spacing={2}
+            sx={{
+              alignItems: 'center',
+              mx: 3,
+              pb: 10,
+              mt: { xs: 8, md: 0 },
+            }}
           >
-            <Stack
-              spacing={2}
-              sx={{
-                alignItems: 'center',
-                mx: 3,
-                pb: 10,
-                mt: { xs: 8, md: 0 },
-              }}
-            >
-              <Header />
-              <MainGrid />
-            </Stack>
-          </Box>
+            <Header />
+            <MainGrid />
+          </Stack>
         </Box>
-      </ThemeProvider>
-    </TemplateFrame>
+      </Box>
+    </AppTheme>
   );
 }

docs/data/material/getting-started/templates/dashboard/Dashboard.tsx

@@ -1,86 +1,63 @@
 import * as React from 'react';
-import {
-  PaletteMode,
-  createTheme,
-  ThemeProvider,
-  alpha,
-} from '@mui/material/styles';
+import type {} from '@mui/x-date-pickers/themeAugmentation';
+import type {} from '@mui/x-charts/themeAugmentation';
+import type {} from '@mui/x-data-grid/themeAugmentation';
+import type {} from '@mui/x-tree-view/themeAugmentation';
+import { alpha } from '@mui/material/styles';
 import CssBaseline from '@mui/material/CssBaseline';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
-import getDashboardTheme from './theme/getDashboardTheme';
 import AppNavbar from './components/AppNavbar';
 import Header from './components/Header';
 import MainGrid from './components/MainGrid';
 import SideMenu from './components/SideMenu';
-import TemplateFrame from './TemplateFrame';
-
-export default function Dashboard() {
-  const [mode, setMode] = React.useState<PaletteMode>('light');
-  const [showCustomTheme, setShowCustomTheme] = React.useState(true);
-  const dashboardTheme = createTheme(getDashboardTheme(mode));
-  const defaultTheme = createTheme({ palette: { mode } });
-  // This code only runs on the client side, to determine the system color preference
-  React.useEffect(() => {
-    // Check if there is a preferred mode in localStorage
-    const savedMode = localStorage.getItem('themeMode') as PaletteMode | null;
-    if (savedMode) {
-      setMode(savedMode);
-    } else {
-      // If no preference is found, it uses system preference
-      const systemPrefersDark = window.matchMedia(
-        '(prefers-color-scheme: dark)',
-      ).matches;
-      setMode(systemPrefersDark ? 'dark' : 'light');
-    }
-  }, []);
-
-  const toggleColorMode = () => {
-    const newMode = mode === 'dark' ? 'light' : 'dark';
-    setMode(newMode);
-    localStorage.setItem('themeMode', newMode); // Save the selected mode to localStorage
-  };
+import AppTheme from '../shared-theme/AppTheme';
+import {
+  chartsCustomizations,
+  dataGridCustomizations,
+  datePickersCustomizations,
+  treeViewCustomizations,
+} from './theme/customizations';
 
-  const toggleCustomTheme = () => {
-    setShowCustomTheme((prev) => !prev);
-  };
+const xThemeComponents = {
+  ...chartsCustomizations,
+  ...dataGridCustomizations,
+  ...datePickersCustomizations,
+  ...treeViewCustomizations,
+};
 
+export default function Dashboard(props: { disableCustomTheme?: boolean }) {
   return (
-    <TemplateFrame
-      toggleCustomTheme={toggleCustomTheme}
-      showCustomTheme={showCustomTheme}
-      mode={mode}
-      toggleColorMode={toggleColorMode}
-    >
-      <ThemeProvider theme={showCustomTheme ? dashboardTheme : defaultTheme}>
-        <CssBaseline enableColorScheme />
-        <Box sx={{ display: 'flex' }}>
-          <SideMenu />
-          <AppNavbar />
-          {/* Main content */}
-          <Box
-            component="main"
-            sx={(theme) => ({
-              flexGrow: 1,
-              backgroundColor: alpha(theme.palette.background.default, 1),
-              overflow: 'auto',
-            })}
+    <AppTheme {...props} themeComponents={xThemeComponents}>
+      <CssBaseline enableColorScheme />
+      <Box sx={{ display: 'flex' }}>
+        <SideMenu />
+        <AppNavbar />
+        {/* Main content */}
+        <Box
+          component="main"
+          sx={(theme) => ({
+            flexGrow: 1,
+            backgroundColor: theme.vars
+              ? `rgba(${theme.vars.palette.background.defaultChannel} / 1)`
+              : alpha(theme.palette.background.default, 1),
+            overflow: 'auto',
+          })}
+        >
+          <Stack
+            spacing={2}
+            sx={{
+              alignItems: 'center',
+              mx: 3,
+              pb: 10,
+              mt: { xs: 8, md: 0 },
+            }}
           >
-            <Stack
-              spacing={2}
-              sx={{
-                alignItems: 'center',
-                mx: 3,
-                pb: 10,
-                mt: { xs: 8, md: 0 },
-              }}
-            >
-              <Header />
-              <MainGrid />
-            </Stack>
-          </Box>
+            <Header />
+            <MainGrid />
+          </Stack>
         </Box>
-      </ThemeProvider>
-    </TemplateFrame>
+      </Box>
+    </AppTheme>
   );
 }