[core] Agnostic DashboardLayout component

[apedroferreira]

Agnostic DashboardLayout so that it can be used in any app by itself, even without an AppProvider wrapping it.
Need to adjust docs, maybe adjust/update tests too.
Also remove any mentions of CSS vars theming being experimental in docs now.

[Janpot]

I don't believe the state for paletteMode and setPaletteMode (we use a different naming convention for controlled props anyway) should be owned by DashboardLayout. It's owned by the theme and if the user wants to manipulate it useColorScheme should be used. For the classic theme, I believe we should create a useColorScheme shim (i.e. rewrite useStandardPaletteMode with the same signature as useColorScheme and export from the library).

[apedroferreira]

Ok, it was just a first idea and I wasn't sure about the names for these 2 props either.
We can go with that, the only disadvantage I guess is that it will only work with MUI theming (nevermind, the theme is strongly connected to the component anyway so this should be more automatic, sounds good!)

[apedroferreira]

I was looking a bit more into this and not sure about the approach to take.

1. User is using DashboardLayout inside an AppProvider with any of the 3 theming methods we support (https://mui.com/toolpad/core/react-app-provider/#theming) => theme switcher already works
2. User uses DashboardLayout without AppProvider around it => we can make things work automatically if they're using a CSS vars theme by simply using the methods from useColorScheme, otherwise if they're using a standard theme it can only have one mode unless they're managing the active theme state themselves somehow, in which case we can't support it automatically?

About the shim, what scenario are we trying to solve with it? For internal components we have this context https://github.com/mui/mui-toolpad/blob/ad9bddb719a81cd113b73e82d304ae5ead1a0e8c/packages/toolpad-core/src/DashboardLayout/DashboardLayout.tsx#L81

Should I make an abstraction around the context as a hook that users can import called useColorScheme?

[Janpot]

Ok, we could make it a dumb controlled property. But name it colorScheme, onColorSchemeChange to match naming of the cssvar theme, and also we always use onXyzChange for controlled prop xyz, not setXyz

[apedroferreira]

Just realized that we also need to deal with the routing if we want to make DashboardLayout work as a standalone component, but integrating that with our current system seems like a complicated problem, so not sure what the best solution is.

There are a few possible approaches but maybe none of them sounds ideal, plus don't want to go too far in any of them without first aligning on a solution:

1. router prop in DashboardLayout just like AppProvider['router']. Ideally with this approach a specific somewhat preconfigured DashboardLayout for the Next.js app and pages routers would be made available, but then the framework-specific DashboardLayout should only be used if not using an AppProvider and that might be a bit convoluted to explain and confusing to use... Or we could make those Next.js router configurations importable from @toolpad/core and ready to be passed as props to the generic component.

2. Maybe allow users to pass in a custom Link component to be used somehow? And as for the pathname defaulting to window.pathname might work, or it could also be passed as a prop?

3. Considering these issues perhaps we should not make it possible to use these components standalone as the configuration doesn't seem simple/straightforward enough, as users might as well wrap the component in an AppProvider every time.

[Janpot]

We can always wait with this feature until there is clear demand and user benefit.