[AppProvider] Add Tanstack React Router provider (#4971)

Author: apedroferreira

.eslintignore

@@ -24,3 +24,6 @@ test
 /packages/toolpad-studio/
 /packages/toolpad-studio-runtime/
 /packages/toolpad-studio-components/
+
+# generated TanStack Router files
+routeTree.gen.ts

docs/data/toolpad/core/components/app-provider/app-provider.md

@@ -80,7 +80,7 @@ export default function App(props) {
 }
 ```
 
-## Client-side routing
+## React Router
 
 The `ReactRouterAppProvider` includes routing out-of-the-box for projects using [react-router](https://www.npmjs.com/package/react-router).
 
@@ -90,6 +90,14 @@ This specific `ReactRouterAppProvider` is recommended when building single-page
 import { ReactRouterAppProvider } from '@toolpad/core/react-router';
 ```
 
+## Other Integrations
+
+### TanStack Router
+
+```tsx
+import { TanStackRouterAppProvider } from '@toolpad/core/tanstack-router';
+```
+
 ## Theming
 
 An `AppProvider` can set a visual theme for all elements inside it to adopt via the `theme` prop. This prop can be set in a few distinct ways with different advantages and disadvantages:

docs/data/toolpad/core/integrations/react-router.md

@@ -6,7 +6,7 @@ title: React Router - Integration
 
 <p class="description">To integrate Toolpad Core into a single-page app (with Vite, for example) using React Router, follow these steps.</p>
 
-## Wrap all your pages in a `ReactRouterAppProvider`
+## Wrap all your pages with a `ReactRouterAppProvider`
 
 In your router configuration (for example `src/main.tsx`), use a shared component or element (for example `src/App.tsx`) as a root **layout route** that wraps the whole application with the `ReactRouterAppProvider` from `@toolpad/core/react-router`.
 

docs/data/toolpad/core/integrations/tanstack-router.md

@@ -0,0 +1,118 @@
+---
+title: TanStack Router - Integration
+---
+
+# TanStack Router
+
+<p class="description">To integrate Toolpad Core into a project that uses TanStack Router, follow these steps.</p>
+
+## Wrap all routes with a `TanStackRouterAppProvider`
+
+In the root route (for example `src/routes/__root.tsx`), wrap all the route page content with the `TanStackRouterAppProvider` from `@toolpad/core/tanstack-router`.
+
+```tsx title="src/routes/__root.tsx"
+import * as React from 'react';
+import { Outlet, createRootRoute } from '@tanstack/react-router';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
+import { TanStackRouterAppProvider } from '@toolpad/core/tanstack-router';
+import type { Navigation } from '@toolpad/core/AppProvider';
+
+const NAVIGATION: Navigation = [
+  {
+    kind: 'header',
+    title: 'Main items',
+  },
+  {
+    title: 'Dashboard',
+    icon: <DashboardIcon />,
+  },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
+];
+
+const BRANDING = {
+  title: 'My Toolpad Core App',
+};
+
+function App() {
+  return (
+    <TanStackRouterAppProvider navigation={NAVIGATION} branding={BRANDING}>
+      <Outlet />
+    </TanStackRouterAppProvider>
+  );
+}
+
+export const Route = createRootRoute({
+  component: App,
+});
+```
+
+## Create a dashboard layout
+
+Place all your other routes under a `_layout` folder, where the `_layout/route.tsx` file defines a shared layout to be used by all those routes. The `<Outlet />` component from `@tanstack/react-router` should also be used:
+
+```tsx title="src/routes/_layout/route.tsx"
+import * as React from 'react';
+import { Outlet, createFileRoute } from '@tanstack/react-router';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+import { PageContainer } from '@toolpad/core/PageContainer';
+
+function Layout() {
+  return (
+    <DashboardLayout>
+      <PageContainer>
+        <Outlet />
+      </PageContainer>
+    </DashboardLayout>
+  );
+}
+
+export const Route = createFileRoute('/_layout')({
+  component: Layout,
+});
+```
+
+The [`DashboardLayout`](/toolpad/core/react-dashboard-layout/) component provides a consistent layout for your dashboard pages, including a sidebar, navigation, and header. The [`PageContainer`](/toolpad/core/react-page-container/) component is used to wrap the page content, and provides breadcrumbs for navigation.
+
+## Create pages
+
+Create a dashboard page (for example `src/routes/_layout/index.tsx`) and an orders page (`src/routes/_layout/orders.tsx`).
+
+```tsx title="src/routes/_layout/index.tsx"
+import * as React from 'react';
+import { createFileRoute } from '@tanstack/react-router';
+import Typography from '@mui/material/Typography';
+
+function DashboardPage() {
+  return <Typography>Welcome to Toolpad!</Typography>;
+}
+
+export const Route = createFileRoute('/_layout/')({
+  component: DashboardPage,
+});
+```
+
+```tsx title="src/routes/_layout/orders.tsx"
+import * as React from 'react';
+import { createFileRoute } from '@tanstack/react-router';
+import Typography from '@mui/material/Typography';
+
+function OrdersPage() {
+  return <Typography>Welcome to the Toolpad orders!</Typography>;
+}
+
+export const Route = createFileRoute('/_layout/orders')({
+  component: OrdersPage,
+});
+```
+
+That's it! You now have Toolpad Core integrated into your project with TanStack Router!
+
+<!-- :::info
+@TODO: Uncomment when example is live
+For a full working example, see the [Toolpad Core Vite app with TanStack Router example](https://github.com/mui/toolpad/tree/master/examples/core/vite-tanstack-router/)
+::: -->

docs/data/toolpad/core/pages.ts

@@ -55,6 +55,10 @@ const pages: MuiPage[] = [
         pathname: '/toolpad/core/integrations/react-router',
         title: 'Vite with React Router',
       },
+      {
+        pathname: '/toolpad/core/integrations/tanstack-router',
+        title: 'TanStack Router',
+      },
     ],
   },
   {

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

@@ -41,7 +41,7 @@
   "name": "AppProvider",
   "imports": [
     "import { AppProvider } from '@toolpad/core/AppProvider';",
-    "import { AppProvider } from '@toolpad/core';\nimport { NextAppProvider } from '@toolpad/core/nextjs'; // Next.js\nimport { ReactRouterAppProvider } from '@toolpad/core/react-router'; // React Router"
+    "import { AppProvider } from '@toolpad/core';\nimport { NextAppProvider } from '@toolpad/core/nextjs'; // Next.js\nimport { ReactRouterAppProvider } from '@toolpad/core/react-router'; // React Router\nimport { TanStackRouterAppProvider } from '@toolpad/core/tanstack-router'; // TanStack Router"
   ],
   "classes": [],
   "spread": true,

docs/pages/toolpad/core/integrations/tanstack-router.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from '../../../../data/toolpad/core/integrations/tanstack-router.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs disableAd {...pageProps} />;
+}

packages/toolpad-core/package.json

@@ -45,7 +45,6 @@
     "@mui/utils": "^7.0.2",
     "@mui/x-data-grid": "^8.5.0",
     "@mui/x-date-pickers": "^8.5.0",
-    "@standard-schema/spec": "^1.0.0",
     "@toolpad/utils": "workspace:*",
     "client-only": "^0.0.1",
     "dayjs": "1.11.13",
@@ -58,6 +57,8 @@
     "@emotion/react": "11.14.0",
     "@mui/icons-material": "^7.0.2",
     "@mui/material": "^7.0.2",
+    "@standard-schema/spec": "^1.0.0",
+    "@tanstack/react-router": "^1.120.5",
     "@mui/x-data-grid-premium": "^8.5.0",
     "@mui/x-data-grid-pro": "^8.5.0",
     "@types/invariant": "2.2.37",
@@ -79,6 +80,7 @@
     "@emotion/react": "^11",
     "@mui/icons-material": "^7.0.0-beta || ^7.0.0",
     "@mui/material": "^7.0.0-beta || ^7.0.0",
+    "@tanstack/react-router": "^1",
     "next": "^14 || ^15",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
@@ -90,6 +92,9 @@
     },
     "react-router": {
       "optional": true
+    },
+    "@tanstack/react-router": {
+      "optional": true
     }
   },
   "sideEffects": false,

packages/toolpad-core/src/Crud/List.tsx

@@ -30,7 +30,7 @@ import invariant from 'invariant';
 import { useDialogs } from '../useDialogs';
 import { useNotifications } from '../useNotifications';
 import { NoSsr } from '../shared/NoSsr';
-import { CrudContext, RouterContext, WindowContext } from '../shared/context';
+import { CrudContext, RouterContext } from '../shared/context';
 import { useLocaleText } from '../AppProvider/LocalizationProvider';
 import { DataSourceCache } from './cache';
 import { useCachedDataSource } from './useCachedDataSource';
@@ -158,9 +158,6 @@ function List<D extends DataModel>(props: ListProps<D>) {
   const { getMany, deleteOne } = methods;
 
   const routerContext = React.useContext(RouterContext);
-  const appWindowContext = React.useContext(WindowContext);
-
-  const appWindow = appWindowContext ?? (typeof window !== 'undefined' ? window : null);
 
   const dialogs = useDialogs();
   const notifications = useNotifications();
@@ -192,53 +189,77 @@ function List<D extends DataModel>(props: ListProps<D>) {
   const [isLoading, setIsLoading] = React.useState(true);
   const [error, setError] = React.useState<Error | null>(null);
 
-  React.useEffect(() => {
-    if (appWindow) {
-      const url = new URL(appWindow.location.href);
+  const handlePaginationModelChange = React.useCallback(
+    (model: GridPaginationModel) => {
+      setPaginationModel(model);
 
-      url.searchParams.set('page', String(paginationModel.page));
-      url.searchParams.set('pageSize', String(paginationModel.pageSize));
+      if (routerContext) {
+        const { pathname, searchParams, navigate } = routerContext;
 
-      if (!appWindow.frameElement) {
-        appWindow.history.pushState({}, '', url);
-      }
-    }
-  }, [appWindow, paginationModel.page, paginationModel.pageSize]);
+        // Needed because searchParams from Next.js are read-only
+        const writeableSearchParams = new URLSearchParams(searchParams);
 
-  React.useEffect(() => {
-    if (appWindow) {
-      const url = new URL(appWindow.location.href);
-
-      if (
-        filterModel.items.length > 0 ||
-        (filterModel.quickFilterValues && filterModel.quickFilterValues.length > 0)
-      ) {
-        url.searchParams.set('filter', JSON.stringify(filterModel));
-      } else {
-        url.searchParams.delete('filter');
-      }
+        writeableSearchParams.set('page', String(paginationModel.page));
+        writeableSearchParams.set('pageSize', String(paginationModel.pageSize));
+
+        const newSearchParamsString = writeableSearchParams.toString();
 
-      if (!appWindow.frameElement) {
-        appWindow.history.pushState({}, '', url);
+        navigate(`${pathname}${newSearchParamsString ? '?' : ''}${newSearchParamsString}`);
       }
-    }
-  }, [appWindow, filterModel]);
+    },
+    [paginationModel.page, paginationModel.pageSize, routerContext],
+  );
 
-  React.useEffect(() => {
-    if (appWindow) {
-      const url = new URL(appWindow.location.href);
+  const handleFilterModelChange = React.useCallback(
+    (model: GridFilterModel) => {
+      setFilterModel(model);
 
-      if (sortModel.length > 0) {
-        url.searchParams.set('sort', JSON.stringify(sortModel));
-      } else {
-        url.searchParams.delete('sort');
+      if (routerContext) {
+        const { pathname, searchParams, navigate } = routerContext;
+
+        // Needed because searchParams from Next.js are read-only
+        const writeableSearchParams = new URLSearchParams(searchParams);
+
+        if (
+          filterModel.items.length > 0 ||
+          (filterModel.quickFilterValues && filterModel.quickFilterValues.length > 0)
+        ) {
+          writeableSearchParams.set('filter', JSON.stringify(filterModel));
+        } else {
+          writeableSearchParams.delete('filter');
+        }
+
+        const newSearchParamsString = writeableSearchParams.toString();
+
+        navigate(`${pathname}${newSearchParamsString ? '?' : ''}${newSearchParamsString}`);
       }
+    },
+    [filterModel, routerContext],
+  );
+
+  const handleSortModelChange = React.useCallback(
+    (model: GridSortModel) => {
+      setSortModel(model);
+
+      if (routerContext) {
+        const { pathname, searchParams, navigate } = routerContext;
+
+        // Needed because searchParams from Next.js are read-only
+        const writeableSearchParams = new URLSearchParams(searchParams);
 
-      if (!appWindow.frameElement) {
-        appWindow.history.pushState({}, '', url);
+        if (sortModel.length > 0) {
+          writeableSearchParams.set('sort', JSON.stringify(sortModel));
+        } else {
+          writeableSearchParams.delete('sort');
+        }
+
+        const newSearchParamsString = writeableSearchParams.toString();
+
+        navigate(`${pathname}${newSearchParamsString ? '?' : ''}${newSearchParamsString}`);
       }
-    }
-  }, [appWindow, sortModel]);
+    },
+    [routerContext, sortModel],
+  );
 
   const loadData = React.useCallback(async () => {
     setError(null);
@@ -417,11 +438,11 @@ function List<D extends DataModel>(props: ListProps<D>) {
             filterMode="server"
             paginationMode="server"
             paginationModel={paginationModel}
-            onPaginationModelChange={setPaginationModel}
+            onPaginationModelChange={handlePaginationModelChange}
             sortModel={sortModel}
-            onSortModelChange={setSortModel}
+            onSortModelChange={handleSortModelChange}
             filterModel={filterModel}
-            onFilterModelChange={setFilterModel}
+            onFilterModelChange={handleFilterModelChange}
             disableRowSelectionOnClick
             onRowClick={handleRowClick}
             loading={isLoading}