[core] Agnostic DashboardLayout component

docs/pages/toolpad/core/api/dashboard-layout.json

@@ -1,5 +1,21 @@
 {
-  "props": { "children": { "type": { "name": "node" }, "required": true } },
+  "props": {
+    "children": { "type": { "name": "node" }, "required": true },
+    "branding": {
+      "type": { "name": "shape", "description": "{ logo?: node, title?: string }" },
+      "default": "null"
+    },
+    "navigation": {
+      "type": {
+        "name": "arrayOf",
+        "description": "Array&lt;{ children?: Array&lt;object<br>&#124;&nbsp;{ kind: 'header', title: string }<br>&#124;&nbsp;{ kind: 'divider' }&gt;, icon?: node, kind?: 'page', segment: string, title?: string }<br>&#124;&nbsp;{ kind: 'header', title: string }<br>&#124;&nbsp;{ kind: 'divider' }&gt;"
+      },
+      "default": "[]"
+    },
+    "paletteMode": { "type": { "name": "enum", "description": "'dark'<br>&#124;&nbsp;'light'" } },
+    "setPaletteMode": { "type": { "name": "func" } },
+    "window": { "type": { "name": "object" }, "default": "window" }
+  },
   "name": "DashboardLayout",
   "imports": [
     "import { DashboardLayout } from '@toolpad-core/DashboardLayout';",

docs/translations/api-docs/dashboard-layout/dashboard-layout.json

@@ -1,5 +1,14 @@
 {
   "componentDescription": "",
-  "propDescriptions": { "children": { "description": "The content of the dashboard." } },
+  "propDescriptions": {
+    "branding": { "description": "Branding options for the layout." },
+    "children": { "description": "The content of the dashboard." },
+    "navigation": { "description": "Navigation definition for the layout." },
+    "paletteMode": { "description": "Active palette mode in theme." },
+    "setPaletteMode": { "description": "Function to run when the theme switcher is toggled." },
+    "window": {
+      "description": "The window where the layout is rendered. This is needed when rendering the layout inside an iframe, for example."
+    }
+  },
   "classDescriptions": {}
 }

packages/toolpad-core/src/DashboardLayout/DashboardLayout.tsx

@@ -1,7 +1,7 @@
 'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
-import { styled, useTheme } from '@mui/material';
+import { PaletteMode, styled, useTheme } from '@mui/material';
 import MuiAppBar from '@mui/material/AppBar';
 import Box from '@mui/material/Box';
 import Collapse from '@mui/material/Collapse';
@@ -34,7 +34,7 @@ import {
   RouterContext,
   WindowContext,
 } from '../shared/context';
-import type { Navigation, NavigationPageItem } from '../AppProvider';
+import type { AppProviderProps, Navigation, NavigationPageItem } from '../AppProvider';
 import { ToolpadLogo } from './ToolpadLogo';
 import { getItemTitle, isPageItem } from '../shared/navigation';
 
@@ -78,11 +78,20 @@ const NavigationListItemButton = styled(ListItemButton)(({ theme }) => ({
   },
 }));
 
-function ThemeSwitcher() {
+interface ThemeSwitcherProps {
+  value?: PaletteMode;
+  onChange?: (mode: PaletteMode) => void;
+}
+
+function ThemeSwitcher({ value, onChange }: ThemeSwitcherProps) {
   const isSsr = useSsr();
   const theme = useTheme();
 
-  const { paletteMode, setPaletteMode, isDualTheme } = React.useContext(PaletteModeContext);
+  const paletteModeContext = React.useContext(PaletteModeContext);
+
+  const paletteMode = value ?? paletteModeContext.paletteMode;
+  const setPaletteMode = onChange ?? paletteModeContext.setPaletteMode;
+  const isDualTheme = !!onChange ?? paletteModeContext.isDualTheme;
 
   const toggleMode = React.useCallback(() => {
     setPaletteMode(paletteMode === 'dark' ? 'light' : 'dark');
@@ -301,6 +310,30 @@ export interface DashboardLayoutProps {
    * The content of the dashboard.
    */
   children: React.ReactNode;
+  /**
+   * Branding options for the layout.
+   * @default null
+   */
+  branding?: AppProviderProps['branding'];
+  /**
+   * Navigation definition for the layout.
+   * @default []
+   */
+  navigation?: AppProviderProps['navigation'];
+  /**
+   * Active palette mode in theme.
+   */
+  paletteMode?: PaletteMode;
+  /**
+   * Function to run when the theme switcher is toggled.
+   */
+  setPaletteMode?: (theme: PaletteMode) => void;
+  /**
+   * The window where the layout is rendered.
+   * This is needed when rendering the layout inside an iframe, for example.
+   * @default window
+   */
+  window?: AppProviderProps['window'];
 }
 
 /**
@@ -314,11 +347,22 @@ export interface DashboardLayoutProps {
  * - [DashboardLayout API](https://mui.com/toolpad/core/api/dashboard-layout)
  */
 function DashboardLayout(props: DashboardLayoutProps) {
-  const { children } = props;
-
-  const branding = React.useContext(BrandingContext);
-  const navigation = React.useContext(NavigationContext);
-  const appWindow = React.useContext(WindowContext);
+  const {
+    children,
+    paletteMode,
+    setPaletteMode,
+    branding: brandingProp,
+    navigation: navigationProp,
+    window: windowProp,
+  } = props;
+
+  const brandingContext = React.useContext(BrandingContext);
+  const navigationContext = React.useContext(NavigationContext);
+  const windowContext = React.useContext(WindowContext);
+
+  const branding = brandingProp ?? brandingContext;
+  const navigation = navigationProp ?? navigationContext;
+  const appWindow = windowProp ?? windowContext;
 
   const [isMobileNavigationOpen, setIsMobileNavigationOpen] = React.useState(false);
 
@@ -396,7 +440,7 @@ function DashboardLayout(props: DashboardLayoutProps) {
             </a>
           </Box>
           <Box sx={{ flexGrow: 1 }} />
-          <ThemeSwitcher />
+          <ThemeSwitcher value={paletteMode} onChange={setPaletteMode} />
         </Toolbar>
       </AppBar>
       <Drawer
@@ -449,10 +493,65 @@ DashboardLayout.propTypes /* remove-proptypes */ = {
   // │ These PropTypes are generated from the TypeScript type definitions. │
   // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
   // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * Branding options for the layout.
+   * @default null
+   */
+  branding: PropTypes.shape({
+    logo: PropTypes.node,
+    title: PropTypes.string,
+  }),
   /**
    * The content of the dashboard.
    */
   children: PropTypes.node,
+  /**
+   * Navigation definition for the layout.
+   * @default []
+   */
+  navigation: PropTypes.arrayOf(
+    PropTypes.oneOfType([
+      PropTypes.shape({
+        children: PropTypes.arrayOf(
+          PropTypes.oneOfType([
+            PropTypes.object,
+            PropTypes.shape({
+              kind: PropTypes.oneOf(['header']).isRequired,
+              title: PropTypes.string.isRequired,
+            }),
+            PropTypes.shape({
+              kind: PropTypes.oneOf(['divider']).isRequired,
+            }),
+          ]).isRequired,
+        ),
+        icon: PropTypes.node,
+        kind: PropTypes.oneOf(['page']),
+        segment: PropTypes.string.isRequired,
+        title: PropTypes.string,
+      }),
+      PropTypes.shape({
+        kind: PropTypes.oneOf(['header']).isRequired,
+        title: PropTypes.string.isRequired,
+      }),
+      PropTypes.shape({
+        kind: PropTypes.oneOf(['divider']).isRequired,
+      }),
+    ]).isRequired,
+  ),
+  /**
+   * Active palette mode in theme.
+   */
+  paletteMode: PropTypes.oneOf(['dark', 'light']),
+  /**
+   * Function to run when the theme switcher is toggled.
+   */
+  setPaletteMode: PropTypes.func,
+  /**
+   * The window where the layout is rendered.
+   * This is needed when rendering the layout inside an iframe, for example.
+   * @default window
+   */
+  window: PropTypes.object,
 } as any;
 
 export { DashboardLayout };

playground/nextjs/src/app/layout.tsx

@@ -11,12 +11,12 @@ const NAVIGATION: Navigation = [
     title: 'Main items',
   },
   {
-    slug: '',
+    segment: '',
     title: 'Dashboard',
     icon: <DashboardIcon />,
   },
   {
-    slug: 'orders',
+    segment: 'orders',
     title: 'Orders',
     icon: <ShoppingCartIcon />,
   },