Display the ToggleThemeButton automatically

fzaninotto · fzaninotto · commit ebb37ba743f0 · 2023-05-07T12:12:33.000+02:00
diff --git a/docs/Admin.md b/docs/Admin.md
@@ -425,9 +425,12 @@ const App = () => (
 
 ## `darkTheme`
 
-If you want to support both light and dark mode, you can provide a `darkTheme` in addition to the `theme` prop. The `darkTheme` will be used when the user's browser is in dark mode, or when the user manually switches to dark mode using [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
+If you want to support both light and dark mode, you can provide a `darkTheme` in addition to the `theme` prop. The app will use the `darkTheme` by default for users who prefer the dark mode at the OS level, and users will be able to switch from light to dark mode using a new app bar button leveraging [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
 
-![Dark mode](./img/dark-theme.png)
+<video controls autoplay muted loop>
+  <source src="./img/ToggleThemeButton.webm" type="video/webm"/>
+  Your browser does not support the video tag.
+</video>
 
 ```jsx
 import { Admin } from 'react-admin';
@@ -444,37 +447,7 @@ const App = () => (
 );
 ```
 
-To let users change the theme manually, add a `<ToggleThemeButton>` component to the AppBar, and add that AppBar to a custom layout:
-
-```jsx
-// in src/MyAppBar.js
-import { AppBar, TitlePortal, ToggleThemeButton } from 'react-admin';
-
-export const MyAppBar = () => (
-    <AppBar>
-        <TitlePortal />
-        <ToggleThemeButton />
-    </AppBar>>
-);
-
-// in src/App.js
-import { Admin, Layout } from 'react-admin';
-import { MyAppBar } from './MyAppBar';
-import { darkTheme, lightTheme } from './themes';
-
-const MyLayout = (props) => <Layout {...props} appBar={MyAppBar} />;
-
-const App = () => (
-    <Admin
-        dataProvider={dataProvider}
-        layout={MyLayout} 
-        theme={lightTheme}
-        darkTheme={darkTheme}
-    >
-        ...
-    </Admin>
-);
-```
+**Tip**: To disable OS preference detection and always use the light theme, see the [`defaultToLightTheme`](#defaulttolighttheme) prop.
 
 ## `defaultToLightTheme`
 
diff --git a/docs/AppBar.md b/docs/AppBar.md
@@ -17,6 +17,7 @@ By default, the `<AppBar>` component displays:
 - a hamburger icon to toggle the sidebar width,
 - the page title,
 - a button to change locales (if the application uses [i18n](./Translation.md)),
+- a button to change the theme (if the application uses a [dark theme](./Admin.md#darktheme)),
 - a loading indicator,
 - a button to display the user menu.
 
@@ -74,28 +75,29 @@ Additional props are passed to [the underlying Material UI `<AppBar>` element](h
 
 ## `children`
 
-The `<AppBar>` component accepts a `children` prop, which is displayed in the central part of the app bar. This is useful to add buttons to the app bar, for instance, a light/dark theme switcher.
+The `<AppBar>` component accepts a `children` prop, which is displayed in the central part of the app bar. This is useful to add buttons to the app bar, for instance, a settings button.
 
 ```jsx
 // in src/MyAppBar.js
-import { 
-    AppBar,
-    TitlePortal,
-    ToggleThemeButton,
-    defaultTheme,
-} from 'react-admin';
+import { AppBar, TitlePortal } from 'react-admin';
+import SettingsIcon from '@mui/icons-material/Settings';
+import { IconButton } from '@mui/material';
 
-const darkTheme = { palette: { mode: 'dark' } };
+const SettingsButton = () => (
+    <IconButton color="inherit">
+        <SettingsIcon />
+    </IconButton>
+);
 
 export const MyAppBar = () => (
     <AppBar>
         <TitlePortal />
-        <ToggleThemeButton lightTheme={defaultTheme} darkTheme={darkTheme} />
+        <SettingsButton />
     </AppBar>
 );
 ```
 
-![App bar with a toggle theme button](./img/AppBar-children.png)
+![App bar with a settings button](./img/AppBar-children.png)
 
 **Tip**: Whats the `<TitlePortal>`? It's a placeholder for the page title, that components in the page can fill using [the `<Title>` component](./Title.md). `<Title>` uses a [React Portal](https://reactjs.org/docs/portals.html) under the hood. `<TitlePortal>` takes all the available space in the app bar, so it "pushes" the following children to the right.
  
@@ -166,7 +168,11 @@ To override the style of `<AppBar>` using the [Material UI style overrides](http
 
 ## `toolbar`
 
-By default, the `<AppBar>` renders two buttons in addition to the user menu: the language menu and the refresh button.
+By default, the `<AppBar>` renders three buttons in addition to the user menu:
+
+- the [language menu button](./LocalesMenuButton.md),
+- the [theme toggle button](./ToggleThemeButton.md),
+- and [the refresh button](./Buttons.md#refreshbutton).
 
 If you want to reorder or remove these buttons, you can customize the toolbar by passing a `toolbar` prop.
 
@@ -177,36 +183,37 @@ import {
     LocalesMenuButton,
     RefreshIconButton,
     ToggleThemeButton,
-    defaultTheme,
 } from 'react-admin';
 
-const darkTheme = {
-    palette: { mode: 'dark' },
-};
-
 export const MyAppBar = () => (
     <AppBar toolbar={
         <>
             <LocalesMenuButton />
-            <ToggleThemeButton lightTheme={defaultTheme} darkTheme={darkTheme} />
+            <ToggleThemeButton />
             <RefreshIconButton />
         </>
     } />
 );
 ```
 
-**Tip**: If you only need to *add* buttons to the toolbar, you can pass them as children instead of overriding the entire toolbar.
+**Tip**: If you only need to *add* buttons to the toolbar, you can pass them as [children](#children) instead of overriding the entire toolbar.
 
 ```jsx
 // in src/MyAppBar.js
-import { AppBar, TitlePortal, ToggleThemeButton, defaultTheme } from 'react-admin';
+import { AppBar, TitlePortal } from 'react-admin';
+import SettingsIcon from '@mui/icons-material/Settings';
+import { IconButton } from '@mui/material';
 
-const darkTheme = { palette: { mode: 'dark' } };
+const SettingsButton = () => (
+    <IconButton color="inherit">
+        <SettingsIcon />
+    </IconButton>
+);
 
 export const MyAppBar = () => (
     <AppBar>
         <TitlePortal />
-        <ToggleThemeButton lightTheme={defaultTheme} darkTheme={darkTheme} />
+        <SettingsButton />
     </AppBar>
 );
 ```
@@ -346,23 +353,24 @@ export const i18nProvider = {
 
 To add buttons to the app bar, you can use the `<AppBar>` [`children` prop](#children).
 
-For instance, to add `<ToggleThemeButton>`:
+For instance, to add a settings button:
 
 ```jsx
 // in src/MyAppBar.js
-import { 
-    AppBar,
-    TitlePortal,
-    ToggleThemeButton,
-    defaultTheme,
-} from 'react-admin';
+import { AppBar, TitlePortal } from 'react-admin';
+import SettingsIcon from '@mui/icons-material/Settings';
+import { IconButton } from '@mui/material';
 
-const darkTheme = { palette: { mode: 'dark' } };
+const SettingsButton = () => (
+    <IconButton color="inherit">
+        <SettingsIcon />
+    </IconButton>
+);
 
 export const MyAppBar = () => (
     <AppBar>
         <TitlePortal />
-        <ToggleThemeButton lightTheme={defaultTheme} darkTheme={darkTheme} />
+        <SettingsButton />
     </AppBar>
 );
 ```
diff --git a/docs/Theming.md b/docs/Theming.md
@@ -369,53 +369,13 @@ const App = () => (
 
 It's a common practice to support both a light theme and a dark theme in an application, and let users choose which one they prefer. 
 
-React-admin's `<Admin>` component accepts a `darkTheme` mode in addition to the `theme` prop. 
-
-```jsx
-import { Admin, defaultTheme } from 'react-admin';
-
-const lightTheme = defaultTheme;
-const darkTheme = { ...defaultTheme, palette: { mode: 'dark' } };
-
-const App = () => (
-    <Admin
-        dataProvider={...}
-        theme={lightTheme}
-        darkTheme={darkTheme}
-    >
-        // ...
-    </Admin>
-);
-```
-
-With this setup, the default application theme will depend on the user's system settings. If the user has chosen a dark mode in their OS, react-admin will use the dark theme. Otherwise, it will use the light theme.
-
-In addition, you can let users switch from one theme to the other: [the `<ToggleThemeButton>` component](./ToggleThemeButton.md) lets users switch from light to dark mode, and persists that choice by leveraging the [store](./Store.md).
-
 <video controls autoplay muted loop>
   <source src="./img/ToggleThemeButton.webm" type="video/webm"/>
   Your browser does not support the video tag.
 </video>
 
-Add the `<ToggleThemeButton>` to a custom App Bar:
-
-```jsx
-// in src/MyLayout.jsx
-import * as React from 'react';
-import { Layout, AppBar, ToggleThemeButton, TitlePortal } from 'react-admin';
-import { Box, Typography } from '@mui/material';
-
-const MyAppBar = () => (
-    <AppBar>
-        <TitlePortal />
-        <ToggleThemeButton />
-    </AppBar>
-);
-
-const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
-```
 
-Then, pass the custom layout to the `<Admin>` component:
+React-admin's `<Admin>` component accepts a `darkTheme` mode in addition to the `theme` prop. 
 
 ```jsx
 import { Admin, defaultTheme } from 'react-admin';
@@ -428,13 +388,16 @@ const App = () => (
         dataProvider={...}
         theme={lightTheme}
         darkTheme={darkTheme}
-        layout={MyLayout}
     >
         // ...
     </Admin>
 );
 ```
 
+With this setup, the default application theme depends on the user's system settings. If the user has chosen a dark mode in their OS, react-admin will use the dark theme. Otherwise, it will use the light theme.
+
+In addition, users can switch from one theme to the other using [the `<ToggleThemeButton>` component](./ToggleThemeButton.md), which appears in the AppBar as soon as you define a `daerkTheme` prop.
+
 ## Changing the Theme Programmatically
 
 React-admin provides the `useTheme` hook to read and update the theme programmatically. It uses the same syntax as `useState`. Its used internally by [the `<ToggleThemeButton>` component](./ToggleThemeButton.md).
diff --git a/docs/ToggleThemeButton.md b/docs/ToggleThemeButton.md
@@ -12,6 +12,7 @@ The `<ToggleThemeButton>` component lets users switch from light to dark mode, a
   Your browser does not support the video tag.
 </video>
 
+It is enabled by default in the `<AppBar>` as soon as you define a dark theme via [the `<Admin darkTheme>` prop](./Admin.md#darktheme).
 
 ## Usage
 
@@ -22,9 +23,8 @@ You can add the `<ToggleThemeButton>` to a custom App Bar:
 import { AppBar, TitlePortal, ToggleThemeButton } from 'react-admin';
 
 export const MyAppBar = () => (
-    <AppBar>
+    <AppBar toolbar={<ToggleThemeButton />}>
         <TitlePortal />
-        <ToggleThemeButton />
     </AppBar>>
 );
 ```
@@ -51,6 +51,25 @@ const App = () => (
 ```
 {% endraw %}
 
+## Removing The Button From The AppBar
+
+The `<ToggleThemeButton>` appears by default in the `<AppBar>` if the `<Admin darkTheme>` prop is defined. If you want to remove it, you need to set a custom [`<AppBar toolbar>` prop](./AppBar.md#toolbar):
+
+```jsx
+// in src/MyAppBar.js
+import { AppBar, LocalesMenuButton, RefreshIconButton } from 'react-admin';
+
+export const MyAppBar = () => (
+    <AppBar toolbar={
+        <>
+            <LocalesMenuButton />
+            {/* no ToggleThemeButton here */}
+            <RefreshIconButton />
+        </>
+    } />
+);
+```
+
 ## Creating A Dark Theme
 
 For this button to work, you must provide a dark theme to the `<Admin>` component. The `darkTheme` should be a JSON object that follows the [Material UI theme specification](https://material-ui.com/customization/theming/).
diff --git a/docs/img/AppBar-children.png b/docs/img/AppBar-children.png
diff --git a/examples/demo/src/layout/AppBar.tsx b/examples/demo/src/layout/AppBar.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { AppBar, TitlePortal, ToggleThemeButton } from 'react-admin';
+import { AppBar, TitlePortal } from 'react-admin';
 import { Box, useMediaQuery, Theme } from '@mui/material';
 
 import Logo from './Logo';
@@ -13,7 +13,6 @@ const CustomAppBar = () => {
             <TitlePortal />
             {isLargeEnough && <Logo />}
             {isLargeEnough && <Box component="span" sx={{ flex: 1 }} />}
-            <ToggleThemeButton />
         </AppBar>
     );
 };
diff --git a/packages/ra-ui-materialui/src/button/ToggleThemeButton.stories.tsx b/packages/ra-ui-materialui/src/button/ToggleThemeButton.stories.tsx
@@ -85,48 +85,37 @@ const dataProvider = fakeRestDataProvider({
 
 const history = createMemoryHistory({ initialEntries: ['/books'] });
 
-const BookList = () => {
-    return (
-        <List>
-            <Datagrid>
-                <TextField source="id" />
-                <TextField source="title" />
-                <TextField source="author" />
-                <TextField source="year" />
-            </Datagrid>
-        </List>
-    );
-};
-
-const MyAppBar = () => (
-    <AppBar>
-        <TitlePortal />
-        <ToggleThemeButton />
-    </AppBar>
+const BookList = () => (
+    <List>
+        <Datagrid>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="author" />
+            <TextField source="year" />
+        </Datagrid>
+    </List>
 );
-const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
 
 export const Basic = () => (
     <Admin
         dataProvider={dataProvider}
         history={history}
-        layout={MyLayout}
         darkTheme={{ palette: { mode: 'dark' } }}
     >
         <Resource name="books" list={BookList} />
     </Admin>
 );
 
-const LegacyAppBar = () => (
+const MyAppBar = () => (
     <AppBar>
         <TitlePortal />
         <ToggleThemeButton darkTheme={{ palette: { mode: 'dark' } }} />
     </AppBar>
 );
-const LegacyLayout = props => <Layout {...props} appBar={LegacyAppBar} />;
+const MyLayout = props => <Layout {...props} appBar={MyAppBar} />;
 
 export const Legacy = () => (
-    <Admin dataProvider={dataProvider} history={history} layout={LegacyLayout}>
+    <Admin dataProvider={dataProvider} history={history} layout={MyLayout}>
         <Resource name="books" list={BookList} />
     </Admin>
 );
diff --git a/packages/ra-ui-materialui/src/layout/AppBar.stories.tsx b/packages/ra-ui-materialui/src/layout/AppBar.stories.tsx
diff --git a/packages/ra-ui-materialui/src/layout/AppBar.tsx b/packages/ra-ui-materialui/src/layout/AppBar.tsx
