[AppProvider] Create basic router adapters

docs/data/toolpad/core/introduction/TutorialDefault.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Typography from '@mui/material/Typography';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import { AppProvider, Navigation } from '@toolpad/core/AppProvider';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+
+const NAVIGATION: Navigation = [
+ {
+ title: 'Page',
+ icon: <DashboardIcon />,
+ },
+];
+
+export default function TutorialDefault() {
+ return (
+ <AppProvider navigation={NAVIGATION}>
+ <DashboardLayout>
+ <Box
+ sx={{
+ py: 4,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ }}
+ >
+ <Typography>Dashboard content</Typography>
+ </Box>
+ </DashboardLayout>
+ </AppProvider>
+ );
+}

docs/data/toolpad/core/introduction/TutorialDefault.tsx.preview

@@ -0,0 +1,12 @@
+<DashboardLayout>
+ <Box
+ sx={{
+ py: 4,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ }}
+ >
+ <Typography>Dashboard content</Typography>
+ </Box>
+</DashboardLayout>

docs/data/toolpad/core/introduction/TutorialPages.js

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Typography from '@mui/material/Typography';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import TimelineIcon from '@mui/icons-material/Timeline';
+import { AppProvider } from '@toolpad/core/AppProvider';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+
+const NAVIGATION = [
+ {
+ kind: 'header',
+ title: 'Main items',
+ },
+ {
+ slug: '/page',
+ title: 'Page',
+ icon: <DashboardIcon />,
+ },
+ // Add the following new item:
+ {
+ slug: '/page-2',
+ title: 'Page 2',
+ icon: <TimelineIcon />,
+ },
+];
+
+export default function TutorialPages() {
+ const [pathname, setPathname] = React.useState('/page');
+
+ const router = React.useMemo(() => {
+ return {
+ pathname,
+ searchParams: new URLSearchParams(),
+ navigate: (path) => setPathname(String(path)),
+ };
+ }, [pathname]);
+
+ return (
+ <AppProvider router={router} navigation={NAVIGATION}>
+ <DashboardLayout>
+ <Box
+ sx={{
+ py: 4,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ }}
+ >
+ <Typography>Dashboard content for {pathname}</Typography>
+ </Box>
+ </DashboardLayout>
+ </AppProvider>
+ );
+}

docs/data/toolpad/core/introduction/TutorialPages.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Typography from '@mui/material/Typography';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import TimelineIcon from '@mui/icons-material/Timeline';
+import { AppProvider, Navigation, Router } from '@toolpad/core/AppProvider';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+
+const NAVIGATION: Navigation = [
+ {
+ kind: 'header',
+ title: 'Main items',
+ },
+ {
+ slug: '/page',
+ title: 'Page',
+ icon: <DashboardIcon />,
+ },
+ // Add the following new item:
+ {
+ slug: '/page-2',
+ title: 'Page 2',
+ icon: <TimelineIcon />,
+ },
+];
+
+export default function TutorialPages() {
+ const [pathname, setPathname] = React.useState('/page');
+
+ const router = React.useMemo<Router>(() => {
+ return {
+ pathname,
+ searchParams: new URLSearchParams(),
+ navigate: (path) => setPathname(String(path)),
+ };
+ }, [pathname]);
+
+ return (
+ <AppProvider router={router} navigation={NAVIGATION}>
+ <DashboardLayout>
+ <Box
+ sx={{
+ py: 4,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ }}
+ >
+ <Typography>Dashboard content for {pathname}</Typography>
+ </Box>
+ </DashboardLayout>
+ </AppProvider>
+ );
+}

docs/data/toolpad/core/introduction/TutorialPages.tsx.preview

@@ -0,0 +1,12 @@
+<DashboardLayout>
+ <Box
+ sx={{
+ py: 4,
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ }}
+ >
+ <Typography>Dashboard content for {pathname}</Typography>
+ </Box>
+</DashboardLayout>

docs/data/toolpad/core/introduction/tutorial.md

@@ -95,14 +95,14 @@ const NAVIGATION: Navigation = [
  {
  slug: '/page-2',
  title: 'Page 2',
- icon: <DashboardIcon />,
+ icon: <TimelineIcon />,
  },
 ];
 ```
 
 The newly created page can now be navigated to from the sidebar, like the following:
 
-{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/core/tutorial-2.gif", "alt": "Toolpad Core new page", "caption": "Adding pages to navigation", "zoom": true, "indent": 1 }}
+{{"demo": "TutorialPages.js", "iframe": true, "hideToolbar": true }}
 
 ## Dashboard content
 

docs/pages/toolpad/core/api/app-provider.json

@@ -1,29 +1,12 @@
 {
- "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', slug?: string, title: string }<br>&#124;&nbsp;{ kind: 'header', title: string }<br>&#124;&nbsp;{ kind: 'divider' }&gt;"
- },
- "default": "[]"
- },
- "theme": { "type": { "name": "object" }, "default": "baseTheme" }
- },
+ "props": {},
  "name": "AppProvider",
- "imports": [
- "import { AppProvider } from '@toolpad-core/AppProvider';",
- "import { AppProvider } from '@toolpad-core';"
- ],
+ "imports": ["import { AppProvider } from '@toolpad-core/nextjs';"],
  "classes": [],
  "spread": true,
  "themeDefaultProps": null,
  "muiName": "AppProvider",
- "filename": "/packages/toolpad-core/src/AppProvider/AppProvider.tsx",
+ "filename": "/packages/toolpad-core/src/nextjs/AppProvider.tsx",
  "inheritance": null,
  "demos": "<ul><li><a href=\"/toolpad/core/react-app-provider/\">App Provider</a></li>\n<li><a href=\"/toolpad/core/react-dashboard-layout/\">Dashboard Layout</a></li></ul>",
  "cssComponent": false

docs/translations/api-docs/app-provider/app-provider.json

@@ -1,12 +1 @@
-{
- "componentDescription": "",
- "propDescriptions": {
- "branding": { "description": "Branding options for the app." },
- "children": { "description": "The content of the app provider." },
- "navigation": { "description": "Navigation definition for the app." },
- "theme": {
- "description": "<a href=\"https://mui.com/material-ui/customization/theming/\">Theme</a> used by the app."
- }
- },
- "classDescriptions": {}
-}
+{ "componentDescription": "", "propDescriptions": {}, "classDescriptions": {} }

packages/toolpad-core/package.json

@@ -64,13 +64,21 @@
  "@types/react": "18.3.1",
  "@types/react-dom": "18.3.0",
  "@types/sinon": "^17.0.3",
+ "next": "^14.2.3",
+ "next-router-mock": "^0.9.13",
  "sinon": "^18.0.0"
  },
  "peerDependencies": {
  "@mui/icons-material": "^5",
  "@mui/material": "^5",
+ "next": "^14",
  "react": "^18"
  },
+ "peerDependenciesMeta": {
+ "next": {
+ "optional": true
+ }
+ },
  "sideEffects": false,
  "publishConfig": {
  "access": "public"

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

@@ -1,9 +1,27 @@
+'use client';
 import * as React from 'react';
 import PropTypes from 'prop-types';
 import { ThemeProvider, Theme } from '@mui/material/styles';
 import CssBaseline from '@mui/material/CssBaseline';
 import { baseTheme } from '../themes';
 
+export interface NavigateOptions {
+ history?: 'auto' | 'push' | 'replace';
+}
+
+export interface Navigate {
+ (url: string | URL, options?: NavigateOptions): void;
+}
+
+/**
+ * Abstract router used by Toolpad components.
+ */
+export interface Router {
+ pathname: string;
+ searchParams: URLSearchParams;
+ navigate: Navigate;
+}
+
 export interface Branding {
  title?: string;
  logo?: React.ReactNode;
@@ -30,11 +48,14 @@ export type NavigationItem = NavigationPageItem | NavigationSubheaderItem | Navi
 
 export type Navigation = NavigationItem[];
 
+// TODO: hide these contexts from public API
 export const BrandingContext = React.createContext<Branding | null>(null);
 
 export const NavigationContext = React.createContext<Navigation>([]);
 
-interface AppProviderProps {
+export const RouterContext = React.createContext<Router | null>(null);
+
+export interface AppProviderProps {
  /**
  * The content of the app provider.
  */
@@ -54,6 +75,12 @@ interface AppProviderProps {
  * @default []
  */
  navigation?: Navigation;
+
+ /**
+ * Router implementation used inside Toolpad components.
+ * @default null
+ */
+ router?: Router;
 }
 
 /**
@@ -68,15 +95,17 @@ interface AppProviderProps {
  * - [AppProvider API](https://mui.com/toolpad/core/api/app-provider)
  */
 function AppProvider(props: AppProviderProps) {
- const { children, theme = baseTheme, branding = null, navigation = [] } = props;
+ const { children, theme = baseTheme, branding = null, navigation = [], router = null } = props;
 
  return (
- <ThemeProvider theme={theme}>
- <CssBaseline />
- <BrandingContext.Provider value={branding}>
- <NavigationContext.Provider value={navigation}>{children}</NavigationContext.Provider>
- </BrandingContext.Provider>
- </ThemeProvider>
+ <RouterContext.Provider value={router}>
+ <ThemeProvider theme={theme}>
+ <CssBaseline />
+ <BrandingContext.Provider value={branding}>
+ <NavigationContext.Provider value={navigation}>{children}</NavigationContext.Provider>
+ </BrandingContext.Provider>
+ </ThemeProvider>
+ </RouterContext.Provider>
  );
 }
 
@@ -130,6 +159,15 @@ AppProvider.propTypes /* remove-proptypes */ = {
  }),
  ]).isRequired,
  ),
+ /**
+ * Router implementation used inside Toolpad components.
+ * @default null
+ */
+ router: PropTypes /* @typescript-to-proptypes-ignore */.shape({
+ navigate: PropTypes.func.isRequired,
+ pathname: PropTypes.string.isRequired,
+ searchParams: PropTypes.instanceOf(URLSearchParams),
+ }),
  /**
  * [Theme](https://mui.com/material-ui/customization/theming/) used by the app.
  * @default baseTheme

packages/toolpad-core/src/AppProvider/index.ts

@@ -1,2 +1 @@
-'use client';
 export * from './AppProvider';