[docs] Add a dialog from menu example (mui#1172)

mj12albert · Dec 19, 2024 · 4941275 · 4941275
1 parent 00286d7
commit 4941275
Show file tree

Hide file tree

Showing 5 changed files with 152 additions and 10 deletions.
diff --git a/docs/src/app/(public)/(content)/react/components/alert-dialog/page.mdx b/docs/src/app/(public)/(content)/react/components/alert-dialog/page.mdx
@@ -35,6 +35,52 @@ import { AlertDialog } from '@base-ui-components/react/alert-dialog';
 
 ## Examples
 
+### Open from a menu
+
+In order to open a dialog using a menu, control the dialog state and open it imperatively using the `onClick` handler on the menu item.
+
+Make sure to also use the dialog’s `finalFocus` prop to return focus back to the menu trigger.
+
+```tsx {12-13,17-18,24-25,28-29} title="Connecting a dialog to a menu"
+import * as React from 'react';
+import { AlertDialog } from '@base-ui/components/alert-dialog';
+import { Menu } from '@base-ui/components/menu';
+
+function ExampleMenu() {
+  const menuTriggerRef = React.useRef<HTMLButtonElement>(null);
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+
+  return (
+    <React.Fragment>
+      <Menu.Root>
+        {/* Set the trigger ref */}
+        <Menu.Trigger ref={menuTriggerRef}>Open menu</Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              {/* Open the dialog when the menu item is clicked */}
+              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+
+      {/* Control the dialog state */}
+      <AlertDialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
+        <AlertDialog.Portal>
+          <AlertDialog.Backdrop />
+          {/* Return focus to the menu trigger when the dialog is closed */}
+          <AlertDialog.Popup finalFocus={menuTriggerRef}>
+            {/* prettier-ignore */}
+            {/* Rest of the dialog */}
+          </AlertDialog.Popup>
+        </AlertDialog.Portal>
+      </AlertDialog.Root>
+    </React.Fragment>
+  );
+}
+```
+
 ### Close confirmation
 
 This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

diff --git a/docs/src/app/(public)/(content)/react/components/dialog/page.mdx b/docs/src/app/(public)/(content)/react/components/dialog/page.mdx
@@ -92,6 +92,52 @@ It’s also common to use `onOpenChange` if your app needs to do something when
 >
 ```
 
+### Open from a menu
+
+In order to open a dialog using a menu, control the dialog state and open it imperatively using the `onClick` handler on the menu item.
+
+Make sure to also use the dialog’s `finalFocus` prop to return focus back to the menu trigger.
+
+```tsx {12-13,17-18,24-25,28-29} title="Connecting a dialog to a menu"
+import * as React from 'react';
+import { Dialog } from '@base-ui/components/dialog';
+import { Menu } from '@base-ui/components/menu';
+
+function ExampleMenu() {
+  const menuTriggerRef = React.useRef<HTMLButtonElement>(null);
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+
+  return (
+    <React.Fragment>
+      <Menu.Root>
+        {/* Set the trigger ref */}
+        <Menu.Trigger ref={menuTriggerRef}>Open menu</Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              {/* Open the dialog when the menu item is clicked */}
+              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+
+      {/* Control the dialog state */}
+      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
+        <Dialog.Portal>
+          <Dialog.Backdrop />
+          {/* Return focus to the menu trigger when the dialog is closed */}
+          <Dialog.Popup finalFocus={menuTriggerRef}>
+            {/* prettier-ignore */}
+            {/* Rest of the dialog */}
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </React.Fragment>
+  );
+}
+```
+
 ### Nested dialogs
 
 You can nest dialogs within one another normally.

diff --git a/docs/src/app/(public)/(content)/react/components/menu/page.mdx b/docs/src/app/(public)/(content)/react/components/menu/page.mdx
@@ -121,3 +121,49 @@ Use the `render` prop to compose a menu item with an anchor element.
 ```jsx title="A menu item that opens a link"
 <Menu.Item render={<a href="/projects">Go to Projects</a>} />
 ```
+
+### Open a dialog
+
+In order to open a dialog using a menu, control the dialog state and open it imperatively using the `onClick` handler on the menu item.
+
+Make sure to also use the dialog’s `finalFocus` prop to return focus back to the menu trigger.
+
+```tsx {12-13,17-18,24-25,28-29} title="Connecting a dialog to a menu"
+import * as React from 'react';
+import { Dialog } from '@base-ui/components/dialog';
+import { Menu } from '@base-ui/components/menu';
+
+function ExampleMenu() {
+  const menuTriggerRef = React.useRef<HTMLButtonElement>(null);
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+
+  return (
+    <React.Fragment>
+      <Menu.Root>
+        {/* Set the trigger ref */}
+        <Menu.Trigger ref={menuTriggerRef}>Open menu</Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner>
+            <Menu.Popup>
+              {/* Open the dialog when the menu item is clicked */}
+              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+
+      {/* Control the dialog state */}
+      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
+        <Dialog.Portal>
+          <Dialog.Backdrop />
+          {/* Return focus to the menu trigger when the dialog is closed */}
+          <Dialog.Popup finalFocus={menuTriggerRef}>
+            {/* prettier-ignore */}
+            {/* Rest of the dialog */}
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </React.Fragment>
+  );
+}
+```
diff --git a/docs/src/components/Code.css b/docs/src/components/Code.css
@@ -17,17 +17,8 @@
       padding-inline: 0.75rem;
     }
 
-    & [data-highlighted-line] {
-      background-color: var(--color-line-highlight);
-    }
-
-    & [data-highlighted-line-id='strong'] {
-      background-color: var(--color-line-highlight-strong);
-    }
-
     & mark {
-      color: var(--syntax-default);
-      background-color: var(--color-inline-highlight);
+      display: inline-block;
     }
   }
 }
diff --git a/docs/src/syntax-highlighting/index.css b/docs/src/syntax-highlighting/index.css
@@ -40,3 +40,16 @@
   --syntax-string: var(--color-navy);
   --syntax-nullish: var(--color-gray-500);
 }
+
+[data-highlighted-line] {
+  background-color: var(--color-line-highlight);
+}
+
+[data-highlighted-line-id='strong'] {
+  background-color: var(--color-line-highlight-strong);
+}
+
+[data-highlighted-chars] {
+  color: var(--syntax-default);
+  background-color: var(--color-inline-highlight);
+}