[docs] Improve Toolpad Core docs

docs/data/material/components/app-bar/app-bar.md

@@ -154,7 +154,7 @@ You can override this behavior by setting the `enableColorOnDark` prop to `true`
 
 {{"demo": "EnableColorOnDarkAppBar.js", "bg": true}}
 
-## Experimental APIs
+## Toolpad
 
 ### DashboardLayout
 

docs/data/material/components/breadcrumbs/breadcrumbs.md

@@ -66,10 +66,10 @@ The accessibility of this component relies on:
 - To prevent screen reader announcement of the visual separators between links, they are hidden with `aria-hidden`.
 - A nav element labeled with `aria-label` identifies the structure as a breadcrumb trail and makes it a navigation landmark so that it is easy to locate.
 
-## Experimental APIs
+## Toolpad
 
 ### Page Container
 
-The [PageContainer](https://mui.com/toolpad/core/react-page-container/) component in `@toolpad/core` is the ideal wrapper for the content of your dashboard. It makes the Material UI Container navigation aware and extends it with page title, breadcrumbs, actions, and more.
+The [PageContainer](https://mui.com/toolpad/core/react-page-container/) component in `@toolpad/core` is the ideal wrapper for the content of your dashboard. It makes the Material UI Container navigation-aware and extends it with page title, breadcrumbs, actions, and more.
 
 {{"demo": "./PageContainerBasic.js", "height": 400, "hideToolbar": true}}

docs/data/material/components/container/container.md

@@ -35,10 +35,10 @@ The max-width matches the min-width of the current breakpoint.
 <Container fixed>
 ```
 
-## Experimental APIs
+## Toolpad
 
 ### Page Container
 
-The [PageContainer](https://mui.com/toolpad/core/react-page-container/) component in `@toolpad/core` is the ideal wrapper for the content of your dashboard. It makes the Material UI Container navigation aware and extends it with page title, breadcrumbs, actions, and more.
+The [PageContainer](https://mui.com/toolpad/core/react-page-container/) component in `@toolpad/core` is the ideal wrapper for the content of your dashboard. It makes the Material UI Container navigation-aware and extends it with page title, breadcrumbs, actions, and more.
 
 {{"demo": "../breadcrumbs/PageContainerBasic.js", "height": 400, "hideToolbar": true}}

docs/data/material/components/dialogs/ToolpadDialogs.js

@@ -0,0 +1,99 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+import { DialogsProvider, useDialogs } from '@toolpad/core/useDialogs';
+import Button from '@mui/material/Button';
+import Dialog from '@mui/material/Dialog';
+import DialogTitle from '@mui/material/DialogTitle';
+import DialogContent from '@mui/material/DialogContent';
+import DialogActions from '@mui/material/DialogActions';
+
+function MyCustomDialog({ open, onClose }) {
+  return (
+    <Dialog
+      fullWidth
+      open={open}
+      onClose={(event) => onClose?.(event, 'escapeKeyDown')}
+    >
+      <DialogTitle>Custom dialog</DialogTitle>
+      <DialogContent>I am a custom dialog</DialogContent>
+      <DialogActions>
+        <Button onClick={(event) => onClose?.(event, 'escapeKeyDown')}>
+          Close me
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+
+MyCustomDialog.propTypes = {
+  /**
+   * Callback fired when the component requests to be closed.
+   *
+   * @param {object} event The event source of the callback.
+   * @param {string} reason Can be: `"escapeKeyDown"`, `"backdropClick"`.
+   */
+  onClose: PropTypes.func,
+  /**
+   * If `true`, the component is shown.
+   */
+  open: PropTypes.bool.isRequired,
+};
+
+function DemoContent() {
+  const dialogs = useDialogs();
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Button
+        onClick={async () => {
+          await dialogs.open(MyCustomDialog);
+        }}
+      >
+        Open a custom dialog!
+      </Button>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button
+          onClick={async () => {
+            await dialogs.alert('This is an alert dialog');
+          }}
+        >
+          Alert
+        </Button>
+        <Button
+          onClick={async () => {
+            const confirmed = await dialogs.confirm(
+              'Are you sure you want to delete this?',
+              {
+                okText: 'Confirm',
+                cancelText: 'Cancel',
+              },
+            );
+            if (confirmed) {
+              dialogs.alert('Deleted!');
+            }
+          }}
+        >
+          Confirm
+        </Button>
+        <Button
+          onClick={async () => {
+            const name = await dialogs.prompt('Enter your name', {
+              okText: 'Confirm',
+              cancelText: 'Cancel',
+            });
+            dialogs.alert(`Hello, ${name}!`);
+          }}
+        >
+          Prompt
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export default function ToolpadDialogs() {
+  return (
+    <DialogsProvider>
+      <DemoContent />
+    </DialogsProvider>
+  );
+}

docs/data/material/components/dialogs/ToolpadDialogs.tsx

@@ -0,0 +1,88 @@
+import * as React from 'react';
+import { DialogsProvider, useDialogs } from '@toolpad/core/useDialogs';
+import Button from '@mui/material/Button';
+import Dialog, { DialogProps } from '@mui/material/Dialog';
+import DialogTitle from '@mui/material/DialogTitle';
+import DialogContent from '@mui/material/DialogContent';
+import DialogActions from '@mui/material/DialogActions';
+
+function MyCustomDialog({ open, onClose }: Pick<DialogProps, 'open' | 'onClose'>) {
+  return (
+    <Dialog
+      fullWidth
+      open={open}
+      onClose={(event: React.SyntheticEvent) => onClose?.(event, 'escapeKeyDown')}
+    >
+      <DialogTitle>Custom dialog</DialogTitle>
+      <DialogContent>I am a custom dialog</DialogContent>
+      <DialogActions>
+        <Button
+          onClick={(event: React.SyntheticEvent) =>
+            onClose?.(event, 'escapeKeyDown')
+          }
+        >
+          Close me
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+
+function DemoContent() {
+  const dialogs = useDialogs();
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+      <Button
+        onClick={async () => {
+          await dialogs.open(MyCustomDialog);
+        }}
+      >
+        Open a custom dialog!
+      </Button>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button
+          onClick={async () => {
+            await dialogs.alert('This is an alert dialog');
+          }}
+        >
+          Alert
+        </Button>
+        <Button
+          onClick={async () => {
+            const confirmed = await dialogs.confirm(
+              'Are you sure you want to delete this?',
+              {
+                okText: 'Confirm',
+                cancelText: 'Cancel',
+              },
+            );
+            if (confirmed) {
+              dialogs.alert('Deleted!');
+            }
+          }}
+        >
+          Confirm
+        </Button>
+        <Button
+          onClick={async () => {
+            const name = await dialogs.prompt('Enter your name', {
+              okText: 'Confirm',
+              cancelText: 'Cancel',
+            });
+            dialogs.alert(`Hello, ${name}!`);
+          }}
+        >
+          Prompt
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+export default function ToolpadDialogs() {
+  return (
+    <DialogsProvider>
+      <DemoContent />
+    </DialogsProvider>
+  );
+}

docs/data/material/components/dialogs/ToolpadDialogs.tsx.preview

@@ -0,0 +1,3 @@
+<DialogsProvider>
+  <DemoContent />
+</DialogsProvider>

docs/data/material/components/dialogs/dialogs.md

@@ -168,8 +168,10 @@ The package [`material-ui-confirm`](https://github.com/jonatanklosko/material-ui
 
 Follow the [Modal accessibility section](/material-ui/react-modal/#accessibility).
 
-## Experimental APIs
+## Toolpad
 
-### Imperative API
+### `useDialogs`
 
-You can create and manipulate dialogs imperatively with the [`useDialog`](https://mui.com/toolpad/core/react-use-dialogs/) API in `@toolpad/core`. This API provides state management for opening and closing dialogs and for passing data to the dialog and back. It allows for stacking multiple dialogs. It also provides themed alternatives for `window.alert`, `window.confirm` and `window.prompt`.
+You can create and manipulate dialogs imperatively with the [`useDialogs`](https://mui.com/toolpad/core/react-use-dialogs/) API in `@toolpad/core`. This API provides state management for opening and closing dialogs and for passing data to the dialog and back. It allows for stacking multiple dialogs. It also provides themed alternatives for `window.alert`, `window.confirm` and `window.prompt`.
+
+{{"demo": "ToolpadDialogs.js", "defaultCodeOpen": false}}

docs/data/material/components/drawers/drawers.md

@@ -136,7 +136,7 @@ Apps focused on productivity that require balance across the screen.
 
 {{"demo": "ClippedDrawer.js", "iframe": true}}
 
-## Experimental APIs
+## Toolpad
 
 ### DashboardLayout
 

docs/data/material/components/snackbars/ToolpadNotifications.js

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import {
+  useNotifications,
+  NotificationsProvider,
+} from '@toolpad/core/useNotifications';
+import Button from '@mui/material/Button';
+
+export default function ToolpadNotifications() {
+  const notifications = useNotifications();
+  return (
+    <NotificationsProvider>
+      <div>
+        <Button
+          onClick={() => {
+            // preview-start
+            notifications.show('Consider yourself notified!', {
+              autoHideDuration: 3000,
+            });
+            // preview-end
+          }}
+        >
+          Notify me
+        </Button>
+      </div>
+    </NotificationsProvider>
+  );
+}

docs/data/material/components/snackbars/ToolpadNotifications.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import {
+  useNotifications,
+  NotificationsProvider,
+} from '@toolpad/core/useNotifications';
+import Button from '@mui/material/Button';
+
+function NotifyButton() {
+  const notifications = useNotifications();
+  return (
+    <Button
+      onClick={() => {
+        notifications.show('Consider yourself notified!', {
+          autoHideDuration: 3000,
+        });
+      }}
+    >
+      Notify me
+    </Button>
+  );
+}
+
+export default function ToolpadNotifications() {
+  return (
+    <NotificationsProvider>
+      <NotifyButton />
+    </NotificationsProvider>
+  );
+}

docs/data/material/components/snackbars/ToolpadNotifications.tsx.preview

@@ -0,0 +1,15 @@
+<NotificationsProvider>
+  <div>
+    <Button
+      onClick={() => {
+        // preview-start
+        notifications.show('Consider yourself notified!', {
+          autoHideDuration: 3000,
+        });
+        // preview-end
+      }}
+    >
+      Notify me
+    </Button>
+  </div>
+</NotificationsProvider>

docs/data/material/components/snackbars/snackbars.md

@@ -141,8 +141,10 @@ The Snackbar component is composed of a root `<div>` that houses interior elemen
 </div>
 ```
 
-## Experimental APIs
+## Toolpad
 
-### Imperative API
+### `useNotifications`
 
 You can create and manipulate notifications imperatively with the [`useNotifications`](https://mui.com/toolpad/core/react-use-notifications/) API in `@toolpad/core`. This API provides state management for opening and closing snackbars. It also allows for queueing multiple notifications at once.
+
+{{"demo": "ToolpadNotifications.js", "defaultCodeOpen": false}}

docs/data/material/getting-started/templates/templates.md

@@ -40,6 +40,6 @@ Looking for something more? You can find complete templates and themes in the <a
 
 ## Toolpad Core (beta)
 
-[Toolpad Core](https://mui.com/toolpad/core/introduction/) is a framework designed to build dashboards and internal tools. It leverages the existing suite of components offered by Material UI and ties them together to help you create applications quickly.
+[Toolpad Core](https://mui.com/toolpad/core/introduction/) is a set of components designed to build dashboards and internal tools. It leverages the existing suite of components offered by Material UI and ties them together to help you create applications quickly.
 
 {{"demo": "../../components/app-bar/DashboardLayoutBasic.js", "height": 400, "iframe": true, "hideToolbar": true}}