@base-ui/react 1.6.0 → 1.8.0

package/docs/react/components/dialog.md

@@ -325,73 +325,417 @@ It's also common to use `onOpenChange` if your app needs to do something when th
 
 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.
 
-```tsx title="Connecting a dialog to a menu"
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+'use client';
 import * as React from 'react';
 import { Dialog } from '@base-ui/react/dialog';
 import { Menu } from '@base-ui/react/menu';
 
-function ExampleMenu() {
+export default function ExampleDialog() {
   const [dialogOpen, setDialogOpen] = React.useState(false);
 
   return (
     <React.Fragment>
       <Menu.Root>
-        <Menu.Trigger>Open menu</Menu.Trigger>
+        <Menu.Trigger className={buttonClass}>
+          Playlist <CaretDownIcon />
+        </Menu.Trigger>
         <Menu.Portal>
-          <Menu.Positioner>
-            <Menu.Popup>
-              {/* @highlight-start */}
+          <Menu.Positioner className="outline-hidden" sideOffset={8} align="start">
+            <Menu.Popup className="relative origin-[var(--transform-origin)] border border-neutral-950 bg-white py-1 text-neutral-950 shadow-[0.25rem_0.25rem_0] shadow-black/12 outline-hidden transition-[scale,opacity] duration-100 ease-out data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0 dark:border-white dark:bg-neutral-950 dark:text-white dark:shadow-none">
+              <Menu.Item className={itemClass}>Play</Menu.Item>
+              <Menu.Item className={itemClass}>Share</Menu.Item>
+              <Menu.Separator className="mx-1 my-1 h-px bg-neutral-950 dark:bg-white" />
               {/* Open the dialog when the menu item is clicked */}
-              <Menu.Item onClick={() => setDialogOpen(true)}>Open dialog</Menu.Item>
-              {/* @highlight-end */}
+              <Menu.Item className={itemClass} onClick={() => setDialogOpen(true)}>
+                Details…
+              </Menu.Item>
             </Menu.Popup>
           </Menu.Positioner>
         </Menu.Portal>
       </Menu.Root>
 
-      {/* @highlight-start */}
       {/* Control the dialog state */}
       <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
-        {/* @highlight-end */}
         <Dialog.Portal>
-          <Dialog.Backdrop />
-          <Dialog.Popup>
-            {/* prettier-ignore */}
-            {/* Rest of the dialog */}
+          <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
+          <Dialog.Popup className="fixed top-1/2 left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[scale,opacity] duration-100 ease-out data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0">
+            <div className="flex flex-col gap-1">
+              <Dialog.Title className="text-base font-bold">Playlist details</Dialog.Title>
+              <Dialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
+                This playlist contains 24 songs and was last updated today.
+              </Dialog.Description>
+            </div>
+            <div className="flex justify-end gap-3">
+              <Dialog.Close className={buttonClass}>Close</Dialog.Close>
+            </div>
           </Dialog.Popup>
         </Dialog.Portal>
       </Dialog.Root>
     </React.Fragment>
   );
 }
+
+const buttonClass =
+  'flex h-8 items-center justify-center gap-1.5 border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:not-data-disabled:bg-neutral-100 active:not-data-disabled:bg-neutral-200 data-pressed:bg-neutral-100 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:not-data-disabled:bg-neutral-800 dark:active:not-data-disabled:bg-neutral-700 dark:data-pressed:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white';
+
+const itemClass =
+  "flex cursor-default py-2 pr-8 pl-4 text-sm leading-4 outline-hidden select-none data-highlighted:relative data-highlighted:z-0 data-highlighted:text-white data-highlighted:before:absolute data-highlighted:before:inset-x-1 data-highlighted:before:inset-y-0 data-highlighted:before:z-[-1] data-highlighted:before:bg-neutral-950 data-highlighted:before:content-[''] dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white";
+
+function CaretDownIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="M12 6H4l4 4.5z" />
+    </svg>
+  );
+}
 ```
 
-### Nested dialogs
+### CSS Modules
 
-You can nest dialogs within one another normally.
+This example shows how to implement the component using CSS Modules.
 
-Use the `[data-nested-dialog-open]` selector and the `var(--nested-dialogs)` CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won't be rendered so that you can present the parent dialog in a clean way behind the one on top of it.
+```css
+/* index.module.css */
+.Button {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
+  height: 2rem;
+  padding: 0 0.75rem;
+  margin: 0;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1;
+  white-space: nowrap;
+  color: oklch(14.5% 0 0deg);
+  -webkit-user-select: none;
+  user-select: none;
 
-## Demo
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
 
-### Tailwind
+  @media (hover: hover) {
+    &:hover:not([data-disabled]) {
+      background-color: oklch(97% 0 0deg);
 
-This example shows how to implement the component using Tailwind CSS.
+      @media (prefers-color-scheme: dark) {
+        background-color: oklch(26.9% 0 0deg);
+      }
+    }
+  }
+
+  &:active:not([data-disabled]) {
+    background-color: oklch(92.2% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: oklch(37.1% 0 0deg);
+    }
+  }
+
+  &[data-pressed] {
+    background-color: oklch(97% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: oklch(26.9% 0 0deg);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+
+.Positioner {
+  outline: 0;
+}
+
+.MenuPopup {
+  box-sizing: border-box;
+  position: relative;
+  outline: 0;
+  padding-block: 0.25rem;
+  border: 1px solid oklch(14.5% 0 0deg);
+  border-radius: 0;
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
+  transform-origin: var(--transform-origin);
+  transition:
+    transform 100ms ease-out,
+    opacity 100ms ease-out;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+    box-shadow: none;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.98);
+  }
+}
+
+.MenuItem {
+  outline: 0;
+  cursor: default;
+  -webkit-user-select: none;
+  user-select: none;
+  padding-block: 0.5rem;
+  padding-left: 1rem;
+  padding-right: 2rem;
+  display: flex;
+  font-size: 0.875rem;
+  line-height: 1rem;
+
+  &[data-highlighted] {
+    z-index: 0;
+    position: relative;
+    color: white;
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(14.5% 0 0deg);
+    }
+  }
+
+  &[data-highlighted]::before {
+    content: '';
+    z-index: -1;
+    position: absolute;
+    inset-block: 0;
+    inset-inline: 0.25rem;
+    background-color: oklch(14.5% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: white;
+    }
+  }
+}
+
+.Separator {
+  margin: 0.25rem;
+  height: 1px;
+  background-color: oklch(14.5% 0 0deg);
+
+  @media (prefers-color-scheme: dark) {
+    background-color: white;
+  }
+}
+
+.Backdrop {
+  position: fixed;
+  min-height: 100dvh;
+  inset: 0;
+  background-color: black;
+  opacity: 0.2;
+  transition: opacity 150ms;
+
+  /* iOS 26+: Ensure the backdrop covers the entire visible viewport. */
+  @supports (-webkit-touch-callout: none) {
+    position: absolute;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    opacity: 0.5;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+  }
+}
+
+.DialogPopup {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 24rem;
+  max-width: calc(100vw - 3rem);
+  margin-top: -2rem;
+  padding: 1rem;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
+  transition:
+    transform 100ms ease-out,
+    opacity 100ms ease-out;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+    box-shadow: none;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: translate(-50%, -50%) scale(0.98);
+  }
+}
+
+.Intro {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.Title {
+  margin: 0;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  font-weight: 700;
+}
+
+.Description {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: oklch(43.9% 0 0deg);
+
+  @media (prefers-color-scheme: dark) {
+    color: oklch(70.8% 0 0deg);
+  }
+}
+
+.Actions {
+  display: flex;
+  justify-content: end;
+  gap: 0.75rem;
+}
+```
 
 ```tsx
 /* index.tsx */
+'use client';
+import * as React from 'react';
 import { Dialog } from '@base-ui/react/dialog';
+import { Menu } from '@base-ui/react/menu';
+import styles from './index.module.css';
 
 export default function ExampleDialog() {
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+
   return (
-    <Dialog.Root>
-      <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
-        View notifications
-      </Dialog.Trigger>
-      <Dialog.Portal>
-        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
-        <Dialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
-          <div className="flex flex-col gap-1">
+    <React.Fragment>
+      <Menu.Root>
+        <Menu.Trigger className={styles.Button}>
+          Playlist <CaretDownIcon />
+        </Menu.Trigger>
+        <Menu.Portal>
+          <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
+            <Menu.Popup className={styles.MenuPopup}>
+              <Menu.Item className={styles.MenuItem}>Play</Menu.Item>
+              <Menu.Item className={styles.MenuItem}>Share</Menu.Item>
+              <Menu.Separator className={styles.Separator} />
+              {/* Open the dialog when the menu item is clicked */}
+              <Menu.Item className={styles.MenuItem} onClick={() => setDialogOpen(true)}>
+                Details…
+              </Menu.Item>
+            </Menu.Popup>
+          </Menu.Positioner>
+        </Menu.Portal>
+      </Menu.Root>
+
+      {/* Control the dialog state */}
+      <Dialog.Root open={dialogOpen} onOpenChange={setDialogOpen}>
+        <Dialog.Portal>
+          <Dialog.Backdrop className={styles.Backdrop} />
+          <Dialog.Popup className={styles.DialogPopup}>
+            <div className={styles.Intro}>
+              <Dialog.Title className={styles.Title}>Playlist details</Dialog.Title>
+              <Dialog.Description className={styles.Description}>
+                This playlist contains 24 songs and was last updated today.
+              </Dialog.Description>
+            </div>
+            <div className={styles.Actions}>
+              <Dialog.Close className={styles.Button}>Close</Dialog.Close>
+            </div>
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+    </React.Fragment>
+  );
+}
+
+function CaretDownIcon(props: React.ComponentProps<'svg'>) {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      {...props}
+      style={{ display: 'block', ...props.style }}
+    >
+      <path d="M12 6H4l4 4.5z" />
+    </svg>
+  );
+}
+```
+
+### Nested dialogs
+
+You can nest dialogs within one another normally.
+
+Use the `[data-nested-dialog-open]` selector and the `var(--nested-dialogs)` CSS variable to customize the styling of the parent dialog. Backdrops of the child dialogs won't be rendered so that you can present the parent dialog in a clean way behind the one on top of it.
+
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+import { Dialog } from '@base-ui/react/dialog';
+
+export default function ExampleDialog() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+        View notifications
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
+        <Dialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
+          <div className="flex flex-col gap-1">
             <Dialog.Title className="text-base font-bold">Notifications</Dialog.Title>
             <Dialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
               You are all caught up. Good job!
@@ -498,49 +842,388 @@ This example shows how to implement the component using CSS Modules.
   }
 }
 
-.GhostButton {
-  box-sizing: border-box;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  height: 2rem;
-  padding: 0 0.75rem;
-  margin: 0;
-  border: none;
-  background-color: transparent;
-  font-family: inherit;
-  font-size: 0.875rem;
-  font-weight: 400;
-  line-height: 1.25rem;
-  color: oklch(14.5% 0 0deg);
-  -webkit-user-select: none;
-  user-select: none;
-
-  @media (prefers-color-scheme: dark) {
-    color: white;
-  }
-
-  @media (hover: hover) {
-    &:hover {
-      background-color: oklch(92.2% 0 0deg);
-
-      @media (prefers-color-scheme: dark) {
-        background-color: oklch(26.9% 0 0deg);
-      }
-    }
-  }
-
-  &:focus-visible {
-    outline: 2px solid oklch(14.5% 0 0deg);
-    outline-offset: -1px;
-
-    @media (prefers-color-scheme: dark) {
-      outline-color: white;
-    }
-  }
-}
-
+.GhostButton {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2rem;
+  padding: 0 0.75rem;
+  margin: 0;
+  border: none;
+  background-color: transparent;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.25rem;
+  color: oklch(14.5% 0 0deg);
+  -webkit-user-select: none;
+  user-select: none;
+
+  @media (prefers-color-scheme: dark) {
+    color: white;
+  }
+
+  @media (hover: hover) {
+    &:hover {
+      background-color: oklch(92.2% 0 0deg);
+
+      @media (prefers-color-scheme: dark) {
+        background-color: oklch(26.9% 0 0deg);
+      }
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+
+.Backdrop {
+  position: fixed;
+  min-height: 100dvh;
+  inset: 0;
+  background-color: black;
+  opacity: 0.2;
+  transition: opacity 150ms;
+
+  /* iOS 26+: Ensure the backdrop covers the entire visible viewport. */
+  @supports (-webkit-touch-callout: none) {
+    position: absolute;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    opacity: 0.5;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+  }
+}
+
+.Popup {
+  box-sizing: border-box;
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  width: 24rem;
+  max-width: calc(100vw - 3rem);
+  margin-top: -2rem;
+  padding: 1rem;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
+  translate: -50% calc(-50% + 1.25rem * var(--nested-dialogs));
+  scale: calc(1 - 0.1 * var(--nested-dialogs));
+  transition:
+    translate 100ms ease-out,
+    scale 100ms ease-out,
+    opacity 100ms ease-out;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+    box-shadow: none;
+  }
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background-color: rgb(0 0 0 / 0.05);
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 100ms ease-out;
+  }
+
+  &[data-nested-dialog-open]::after {
+    opacity: 1;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    translate: -50% calc(-50% + 0.25rem + 1.25rem * var(--nested-dialogs));
+    scale: 0.96;
+  }
+}
+
+.Intro {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.Title {
+  margin: 0;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  font-weight: 700;
+}
+
+.Description {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: oklch(43.9% 0 0deg);
+
+  @media (prefers-color-scheme: dark) {
+    color: oklch(70.8% 0 0deg);
+  }
+}
+
+.Actions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.EndActions {
+  display: flex;
+  align-items: center;
+  justify-content: end;
+  gap: 0.75rem;
+}
+```
+
+```tsx
+/* index.tsx */
+import { Dialog } from '@base-ui/react/dialog';
+import styles from './index.module.css';
+
+export default function ExampleDialog() {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger className={styles.Button}>View notifications</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className={styles.Backdrop} />
+        <Dialog.Popup className={styles.Popup}>
+          <div className={styles.Intro}>
+            <Dialog.Title className={styles.Title}>Notifications</Dialog.Title>
+            <Dialog.Description className={styles.Description}>
+              You are all caught up. Good job!
+            </Dialog.Description>
+          </div>
+          <div className={styles.Actions}>
+            <Dialog.Root>
+              <Dialog.Trigger className={styles.Button}>Customize</Dialog.Trigger>
+              <Dialog.Portal>
+                <Dialog.Popup className={styles.Popup}>
+                  <div className={styles.Intro}>
+                    <Dialog.Title className={styles.Title}>Customize notifications</Dialog.Title>
+                    <Dialog.Description className={styles.Description}>
+                      Review your settings here.
+                    </Dialog.Description>
+                  </div>
+                  <div className={styles.EndActions}>
+                    <Dialog.Close className={styles.Button}>Close</Dialog.Close>
+                  </div>
+                </Dialog.Popup>
+              </Dialog.Portal>
+            </Dialog.Root>
+          </div>
+        </Dialog.Popup>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}
+```
+
+### Close confirmation
+
+This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.
+
+To implement this, both dialogs should be controlled. The confirmation dialog may be opened when `onOpenChange` callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.
+
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { AlertDialog } from '@base-ui/react/alert-dialog';
+import { Dialog } from '@base-ui/react/dialog';
+
+export default function ExampleDialog() {
+  const [dialogOpen, setDialogOpen] = React.useState(false);
+  const [confirmationOpen, setConfirmationOpen] = React.useState(false);
+  const [textareaValue, setTextareaValue] = React.useState('');
+  const titleId = React.useId();
+
+  return (
+    <Dialog.Root
+      open={dialogOpen}
+      onOpenChange={(open) => {
+        // Show the close confirmation if there’s text in the textarea
+        if (!open && textareaValue) {
+          setConfirmationOpen(true);
+        } else {
+          // Reset the text area value
+          setTextareaValue('');
+          // Open or close the dialog normally
+          setDialogOpen(open);
+        }
+      }}
+    >
+      <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+        Tweet
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
+        <Dialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-1 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
+          <Dialog.Title id={titleId} className="text-base font-bold">
+            New tweet
+          </Dialog.Title>
+          <form
+            className="flex flex-col gap-4"
+            onSubmit={(event) => {
+              event.preventDefault();
+              // Close the dialog when submitting
+              setDialogOpen(false);
+            }}
+          >
+            <textarea
+              aria-labelledby={titleId}
+              required
+              className="min-h-32 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 p-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
+              placeholder="What’s on your mind?"
+              value={textareaValue}
+              onChange={(event) => setTextareaValue(event.target.value)}
+            />
+            <div className="flex justify-end gap-3">
+              <Dialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+                Cancel
+              </Dialog.Close>
+              <button
+                type="submit"
+                className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+              >
+                Tweet
+              </button>
+            </div>
+          </form>
+        </Dialog.Popup>
+      </Dialog.Portal>
+
+      {/* Confirmation dialog */}
+      <AlertDialog.Root open={confirmationOpen} onOpenChange={setConfirmationOpen}>
+        <AlertDialog.Portal>
+          <AlertDialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
+            <div className="flex flex-col gap-1">
+              <AlertDialog.Title className="text-base font-bold">Discard tweet?</AlertDialog.Title>
+              <AlertDialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
+                Your tweet will be lost.
+              </AlertDialog.Description>
+            </div>
+            <div className="flex justify-end gap-3">
+              <AlertDialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+                Go back
+              </AlertDialog.Close>
+              <button
+                type="button"
+                className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+                onClick={() => {
+                  setConfirmationOpen(false);
+                  setDialogOpen(false);
+                }}
+              >
+                Discard
+              </button>
+            </div>
+          </AlertDialog.Popup>
+        </AlertDialog.Portal>
+      </AlertDialog.Root>
+    </Dialog.Root>
+  );
+}
+```
+
+### CSS Modules
+
+This example shows how to implement the component using CSS Modules.
+
+```css
+/* index.module.css */
+.Button {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2rem;
+  padding: 0 0.75rem;
+  margin: 0;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1;
+  white-space: nowrap;
+  color: oklch(14.5% 0 0deg);
+  -webkit-user-select: none;
+  user-select: none;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
+
+  @media (hover: hover) {
+    &:hover:not([data-disabled]) {
+      background-color: oklch(97% 0 0deg);
+
+      @media (prefers-color-scheme: dark) {
+        background-color: oklch(26.9% 0 0deg);
+      }
+    }
+  }
+
+  &:active:not([data-disabled]) {
+    background-color: oklch(92.2% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: oklch(37.1% 0 0deg);
+    }
+  }
+
+  &[data-disabled] {
+    color: oklch(55.6% 0 0deg);
+    border-color: oklch(55.6% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(70.8% 0 0deg);
+      border-color: oklch(70.8% 0 0deg);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+
 .Backdrop {
   position: fixed;
   min-height: 100dvh;
@@ -616,6 +1299,7 @@ This example shows how to implement the component using CSS Modules.
   }
 }
 
+.PopupBody,
 .Intro {
   display: flex;
   flex-direction: column;
@@ -642,72 +1326,60 @@ This example shows how to implement the component using CSS Modules.
 
 .Actions {
   display: flex;
-  align-items: center;
+  justify-content: end;
   gap: 0.75rem;
 }
 
-.EndActions {
+.TextareaContainer {
   display: flex;
-  align-items: center;
-  justify-content: end;
-  gap: 0.75rem;
+  flex-direction: column;
+  gap: 1rem;
 }
-```
-
-```tsx
-/* index.tsx */
-import { Dialog } from '@base-ui/react/dialog';
-import styles from './index.module.css';
 
-export default function ExampleDialog() {
-  return (
-    <Dialog.Root>
-      <Dialog.Trigger className={styles.Button}>View notifications</Dialog.Trigger>
-      <Dialog.Portal>
-        <Dialog.Backdrop className={styles.Backdrop} />
-        <Dialog.Popup className={styles.Popup}>
-          <div className={styles.Intro}>
-            <Dialog.Title className={styles.Title}>Notifications</Dialog.Title>
-            <Dialog.Description className={styles.Description}>
-              You are all caught up. Good job!
-            </Dialog.Description>
-          </div>
-          <div className={styles.Actions}>
-            <Dialog.Root>
-              <Dialog.Trigger className={styles.Button}>Customize</Dialog.Trigger>
-              <Dialog.Portal>
-                <Dialog.Popup className={styles.Popup}>
-                  <div className={styles.Intro}>
-                    <Dialog.Title className={styles.Title}>Customize notifications</Dialog.Title>
-                    <Dialog.Description className={styles.Description}>
-                      Review your settings here.
-                    </Dialog.Description>
-                  </div>
-                  <div className={styles.EndActions}>
-                    <Dialog.Close className={styles.Button}>Close</Dialog.Close>
-                  </div>
-                </Dialog.Popup>
-              </Dialog.Portal>
-            </Dialog.Root>
-          </div>
-        </Dialog.Popup>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
-```
+.Textarea {
+  box-sizing: border-box;
+  padding: 0.5rem;
+  margin: 0;
+  border-radius: 0;
+  border: 1px solid oklch(14.5% 0 0deg);
+  width: 100%;
+  min-height: 8rem;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.25rem;
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
 
-### Close confirmation
+  @media (any-pointer: coarse) {
+    font-size: 1rem;
+    line-height: 1.5rem;
+  }
 
-This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
 
-To implement this, both dialogs should be controlled. The confirmation dialog may be opened when `onOpenChange` callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.
+  &::placeholder {
+    color: oklch(55.6% 0 0deg);
 
-## Demo
+    @media (prefers-color-scheme: dark) {
+      color: oklch(70.8% 0 0deg);
+    }
+  }
 
-### Tailwind
+  &:focus {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
 
-This example shows how to implement the component using Tailwind CSS.
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+```
 
 ```tsx
 /* index.tsx */
@@ -715,6 +1387,7 @@ This example shows how to implement the component using Tailwind CSS.
 import * as React from 'react';
 import { AlertDialog } from '@base-ui/react/alert-dialog';
 import { Dialog } from '@base-ui/react/dialog';
+import styles from './index.module.css';
 
 export default function ExampleDialog() {
   const [dialogOpen, setDialogOpen] = React.useState(false);
@@ -734,66 +1407,59 @@ export default function ExampleDialog() {
           setTextareaValue('');
           // Open or close the dialog normally
           setDialogOpen(open);
-        }
-      }}
-    >
-      <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
-        Tweet
-      </Dialog.Trigger>
-      <Dialog.Portal>
-        <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
-        <Dialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-1 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
-          <Dialog.Title id={titleId} className="text-base font-bold">
-            New tweet
-          </Dialog.Title>
-          <form
-            className="flex flex-col gap-4"
-            onSubmit={(event) => {
-              event.preventDefault();
-              // Close the dialog when submitting
-              setDialogOpen(false);
-            }}
-          >
-            <textarea
-              aria-labelledby={titleId}
-              required
-              className="min-h-32 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 p-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
-              placeholder="What’s on your mind?"
-              value={textareaValue}
-              onChange={(event) => setTextareaValue(event.target.value)}
-            />
-            <div className="flex justify-end gap-3">
-              <Dialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
-                Cancel
-              </Dialog.Close>
-              <button
-                type="submit"
-                className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
-              >
-                Tweet
-              </button>
-            </div>
-          </form>
+        }
+      }}
+    >
+      <Dialog.Trigger className={styles.Button}>Tweet</Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className={styles.Backdrop} />
+        <Dialog.Popup className={styles.Popup}>
+          <div className={styles.PopupBody}>
+            <Dialog.Title id={titleId} className={styles.Title}>
+              New tweet
+            </Dialog.Title>
+            <form
+              className={styles.TextareaContainer}
+              onSubmit={(event) => {
+                event.preventDefault();
+                // Close the dialog when submitting
+                setDialogOpen(false);
+              }}
+            >
+              <textarea
+                aria-labelledby={titleId}
+                required
+                className={styles.Textarea}
+                placeholder="What’s on your mind?"
+                value={textareaValue}
+                onChange={(event) => setTextareaValue(event.target.value)}
+              />
+              <div className={styles.Actions}>
+                <Dialog.Close className={styles.Button}>Cancel</Dialog.Close>
+                <button type="submit" className={styles.Button}>
+                  Tweet
+                </button>
+              </div>
+            </form>
+          </div>
         </Dialog.Popup>
       </Dialog.Portal>
 
       {/* Confirmation dialog */}
       <AlertDialog.Root open={confirmationOpen} onOpenChange={setConfirmationOpen}>
         <AlertDialog.Portal>
-          <AlertDialog.Popup className="fixed top-[calc(50%+1.25rem*var(--nested-dialogs))] left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 scale-[calc(1-0.1*var(--nested-dialogs))] bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[top,scale,opacity] duration-100 ease-out after:absolute after:inset-0 after:bg-black/5 after:opacity-0 after:transition-opacity after:duration-100 after:ease-out after:pointer-events-none data-ending-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-ending-style:scale-[0.96] data-ending-style:opacity-0 data-nested-dialog-open:after:opacity-100 data-starting-style:top-[calc(50%+0.25rem+1.25rem*var(--nested-dialogs))] data-starting-style:scale-[0.96] data-starting-style:opacity-0">
-            <div className="flex flex-col gap-1">
-              <AlertDialog.Title className="text-base font-bold">Discard tweet?</AlertDialog.Title>
-              <AlertDialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
+          <AlertDialog.Popup className={styles.Popup}>
+            <div className={styles.Intro}>
+              <AlertDialog.Title className={styles.Title}>Discard tweet?</AlertDialog.Title>
+              <AlertDialog.Description className={styles.Description}>
                 Your tweet will be lost.
               </AlertDialog.Description>
             </div>
-            <div className="flex justify-end gap-3">
-              <AlertDialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
-                Go back
-              </AlertDialog.Close>
+            <div className={styles.Actions}>
+              <AlertDialog.Close className={styles.Button}>Go back</AlertDialog.Close>
               <button
                 type="button"
-                className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+                className={styles.Button}
                 onClick={() => {
                   setConfirmationOpen(false);
                   setDialogOpen(false);
@@ -810,12 +1476,100 @@ export default function ExampleDialog() {
 }
 ```
 
+### Custom focus management
+
+You can control where the focus goes when the dialog opens and closes using the `initialFocus` and `finalFocus` props on the `<Dialog.Popup>` component.
+
+You can also set these props to `false` to prevent focus from moving when the dialog opens or closes, or to a function that returns the element to focus based on the interaction type.
+
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { Dialog } from '@base-ui/react/dialog';
+import { Field } from '@base-ui/react/field';
+import { Fieldset } from '@base-ui/react/fieldset';
+
+export default function ExampleDialog() {
+  const initialFocusRef = React.useRef<HTMLInputElement | null>(null);
+  const finalFocusRef = React.useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <div className="flex flex-wrap justify-center gap-3">
+      <Dialog.Root>
+        <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+          Open feedback
+        </Dialog.Trigger>
+        <Dialog.Portal>
+          <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
+          <Dialog.Popup
+            initialFocus={initialFocusRef}
+            finalFocus={finalFocusRef}
+            className="fixed top-1/2 left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[scale,opacity] duration-100 ease-out data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0"
+          >
+            <div className="flex flex-col gap-1">
+              <Dialog.Title className="text-base font-bold">Feedback form</Dialog.Title>
+              <Dialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
+                Your feedback means a lot to us.
+              </Dialog.Description>
+            </div>
+            <Fieldset.Root className="flex flex-col gap-3 border-0 p-0 m-0">
+              <Field.Root className="flex flex-col items-start gap-1">
+                <Field.Label className="text-sm font-normal">Full name</Field.Label>
+                <Field.Control
+                  placeholder="Enter your name"
+                  className="h-8 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
+                />
+              </Field.Root>
+              <Field.Root className="flex flex-col items-start gap-1">
+                <Field.Label className="text-sm font-normal">Feedback</Field.Label>
+                <Field.Control
+                  ref={initialFocusRef}
+                  required
+                  placeholder="Enter your feedback"
+                  className="h-8 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
+                />
+              </Field.Root>
+            </Fieldset.Root>
+            <div className="flex justify-end gap-3">
+              <Dialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+                Close
+              </Dialog.Close>
+            </div>
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+      <button
+        ref={finalFocusRef}
+        type="button"
+        className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+      >
+        Final focus
+      </button>
+    </div>
+  );
+}
+```
+
 ### CSS Modules
 
 This example shows how to implement the component using CSS Modules.
 
 ```css
 /* index.module.css */
+.Container {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+}
+
 .Button {
   box-sizing: border-box;
   display: flex;
@@ -905,12 +1659,13 @@ This example shows how to implement the component using CSS Modules.
 
 .Popup {
   box-sizing: border-box;
-  position: fixed;
-  top: 50%;
-  left: 50%;
   display: flex;
   flex-direction: column;
   gap: 1rem;
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
   width: 24rem;
   max-width: calc(100vw - 3rem);
   margin-top: -2rem;
@@ -919,11 +1674,8 @@ This example shows how to implement the component using CSS Modules.
   background-color: white;
   color: oklch(14.5% 0 0deg);
   box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
-  translate: -50% calc(-50% + 1.25rem * var(--nested-dialogs));
-  scale: calc(1 - 0.1 * var(--nested-dialogs));
   transition:
-    translate 100ms ease-out,
-    scale 100ms ease-out,
+    transform 100ms ease-out,
     opacity 100ms ease-out;
 
   @media (prefers-color-scheme: dark) {
@@ -933,32 +1685,33 @@ This example shows how to implement the component using CSS Modules.
     box-shadow: none;
   }
 
-  &::after {
-    content: '';
-    position: absolute;
-    inset: 0;
-    background-color: rgb(0 0 0 / 0.05);
-    opacity: 0;
-    pointer-events: none;
-    transition: opacity 100ms ease-out;
-  }
-
-  &[data-nested-dialog-open]::after {
-    opacity: 1;
-  }
-
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
-    translate: -50% calc(-50% + 0.25rem + 1.25rem * var(--nested-dialogs));
-    scale: 0.96;
+    transform: translate(-50%, -50%) scale(0.98);
   }
 }
 
-.PopupBody,
-.Intro {
+.Intro,
+.Fieldset,
+.Field {
   display: flex;
   flex-direction: column;
+}
+
+.Intro {
+  gap: 0.25rem;
+}
+
+.Fieldset {
+  gap: 0.75rem;
+  padding: 0;
+  margin: 0;
+  border: 0;
+}
+
+.Field {
+  align-items: start;
   gap: 0.25rem;
 }
 
@@ -980,36 +1733,28 @@ This example shows how to implement the component using CSS Modules.
   }
 }
 
-.Actions {
-  display: flex;
-  justify-content: end;
-  gap: 0.75rem;
-}
-
-.TextareaContainer {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
+.Label {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 400;
 }
 
-.Textarea {
+.Input {
   box-sizing: border-box;
-  padding: 0.5rem;
+  padding: 0 0.5rem;
   margin: 0;
   border-radius: 0;
   border: 1px solid oklch(14.5% 0 0deg);
   width: 100%;
-  min-height: 8rem;
+  height: 2rem;
   font-family: inherit;
   font-size: 0.875rem;
   font-weight: 400;
-  line-height: 1.25rem;
   background-color: white;
   color: oklch(14.5% 0 0deg);
 
   @media (any-pointer: coarse) {
     font-size: 1rem;
-    line-height: 1.5rem;
   }
 
   @media (prefers-color-scheme: dark) {
@@ -1035,99 +1780,69 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 }
+
+.Actions {
+  display: flex;
+  justify-content: end;
+  gap: 0.75rem;
+}
 ```
 
 ```tsx
 /* index.tsx */
 'use client';
 import * as React from 'react';
-import { AlertDialog } from '@base-ui/react/alert-dialog';
 import { Dialog } from '@base-ui/react/dialog';
+import { Field } from '@base-ui/react/field';
+import { Fieldset } from '@base-ui/react/fieldset';
 import styles from './index.module.css';
 
 export default function ExampleDialog() {
-  const [dialogOpen, setDialogOpen] = React.useState(false);
-  const [confirmationOpen, setConfirmationOpen] = React.useState(false);
-  const [textareaValue, setTextareaValue] = React.useState('');
-  const titleId = React.useId();
+  const initialFocusRef = React.useRef<HTMLInputElement | null>(null);
+  const finalFocusRef = React.useRef<HTMLButtonElement | null>(null);
 
   return (
-    <Dialog.Root
-      open={dialogOpen}
-      onOpenChange={(open) => {
-        // Show the close confirmation if there’s text in the textarea
-        if (!open && textareaValue) {
-          setConfirmationOpen(true);
-        } else {
-          // Reset the text area value
-          setTextareaValue('');
-          // Open or close the dialog normally
-          setDialogOpen(open);
-        }
-      }}
-    >
-      <Dialog.Trigger className={styles.Button}>Tweet</Dialog.Trigger>
-      <Dialog.Portal>
-        <Dialog.Backdrop className={styles.Backdrop} />
-        <Dialog.Popup className={styles.Popup}>
-          <div className={styles.PopupBody}>
-            <Dialog.Title id={titleId} className={styles.Title}>
-              New tweet
-            </Dialog.Title>
-            <form
-              className={styles.TextareaContainer}
-              onSubmit={(event) => {
-                event.preventDefault();
-                // Close the dialog when submitting
-                setDialogOpen(false);
-              }}
-            >
-              <textarea
-                aria-labelledby={titleId}
-                required
-                className={styles.Textarea}
-                placeholder="What’s on your mind?"
-                value={textareaValue}
-                onChange={(event) => setTextareaValue(event.target.value)}
-              />
-              <div className={styles.Actions}>
-                <Dialog.Close className={styles.Button}>Cancel</Dialog.Close>
-                <button type="submit" className={styles.Button}>
-                  Tweet
-                </button>
-              </div>
-            </form>
-          </div>
-        </Dialog.Popup>
-      </Dialog.Portal>
-
-      {/* Confirmation dialog */}
-      <AlertDialog.Root open={confirmationOpen} onOpenChange={setConfirmationOpen}>
-        <AlertDialog.Portal>
-          <AlertDialog.Popup className={styles.Popup}>
+    <div className={styles.Container}>
+      <Dialog.Root>
+        <Dialog.Trigger className={styles.Button}>Open feedback</Dialog.Trigger>
+        <Dialog.Portal>
+          <Dialog.Backdrop className={styles.Backdrop} />
+          <Dialog.Popup
+            className={styles.Popup}
+            initialFocus={initialFocusRef}
+            finalFocus={finalFocusRef}
+          >
             <div className={styles.Intro}>
-              <AlertDialog.Title className={styles.Title}>Discard tweet?</AlertDialog.Title>
-              <AlertDialog.Description className={styles.Description}>
-                Your tweet will be lost.
-              </AlertDialog.Description>
+              <Dialog.Title className={styles.Title}>Feedback form</Dialog.Title>
+              <Dialog.Description className={styles.Description}>
+                Your feedback means a lot to us.
+              </Dialog.Description>
             </div>
+            <Fieldset.Root className={styles.Fieldset}>
+              <Field.Root className={styles.Field}>
+                <Field.Label className={styles.Label}>Full name</Field.Label>
+                <Field.Control placeholder="Enter your name" className={styles.Input} />
+              </Field.Root>
+              <Field.Root className={styles.Field}>
+                <Field.Label className={styles.Label}>Feedback</Field.Label>
+                <Field.Control
+                  ref={initialFocusRef}
+                  required
+                  placeholder="Enter your feedback"
+                  className={styles.Input}
+                />
+              </Field.Root>
+            </Fieldset.Root>
             <div className={styles.Actions}>
-              <AlertDialog.Close className={styles.Button}>Go back</AlertDialog.Close>
-              <button
-                type="button"
-                className={styles.Button}
-                onClick={() => {
-                  setConfirmationOpen(false);
-                  setDialogOpen(false);
-                }}
-              >
-                Discard
-              </button>
+              <Dialog.Close className={styles.Button}>Close</Dialog.Close>
             </div>
-          </AlertDialog.Popup>
-        </AlertDialog.Portal>
-      </AlertDialog.Root>
-    </Dialog.Root>
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+      <button ref={finalFocusRef} type="button" className={styles.Button}>
+        Final focus
+      </button>
+    </div>
   );
 }
 ```
@@ -2726,6 +3441,9 @@ For simple, one-off interactions, place the `<Dialog.Trigger>` inside `<Dialog.R
 However, if defining the dialog's content next to its trigger is not practical, you can use a detached trigger.
 This involves placing the `<Dialog.Trigger>` outside of `<Dialog.Root>` and linking them with a `handle` created by the `Dialog.createHandle()` function.
 
+The imperative methods on the handle, such as `open()` and `openWithPayload()`, require a `<Dialog.Root>` using the same handle to be mounted.
+Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.
+
 ```jsx title="Detached triggers"
 const demoDialog = Dialog.createHandle();
 
@@ -3547,12 +4265,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                               |
-| :------------------ | :--- | :---------------------------------------- |
-| data-open           | -    | Present when the dialog is open.          |
-| data-closed         | -    | Present when the dialog is closed.        |
-| data-starting-style | -    | Present when the dialog is animating in.  |
-| data-ending-style   | -    | Present when the dialog is animating out. |
+| Attribute           | Type | Description                                  |
+| :------------------ | :--- | :------------------------------------------- |
+| data-open           | -    | Present when the dialog is open.             |
+| data-closed         | -    | Present when the dialog is closed.           |
+| data-starting-style | -    | Present when the dialog begins animating in. |
+| data-ending-style   | -    | Present when the dialog is animating out.    |
 
 ### Backdrop.Props
 
@@ -3592,7 +4310,7 @@ Renders a `<div>` element.
 | data-closed             | -    | Present when the dialog is closed.                               |
 | data-nested             | -    | Present when the dialog is nested within another dialog.         |
 | data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
-| data-starting-style     | -    | Present when the dialog is animating in.                         |
+| data-starting-style     | -    | Present when the dialog begins animating in.                     |
 | data-ending-style       | -    | Present when the dialog is animating out.                        |
 
 **Popup CSS Variables:**
@@ -3720,7 +4438,7 @@ Renders a `<div>` element.
 | data-closed             | -    | Present when the dialog is closed.                               |
 | data-nested             | -    | Present when the dialog is nested within another dialog.         |
 | data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
-| data-starting-style     | -    | Present when the dialog is animating in.                         |
+| data-starting-style     | -    | Present when the dialog begins animating in.                     |
 | data-ending-style       | -    | Present when the dialog is animating out.                        |
 
 ### Viewport.Props
@@ -3754,19 +4472,18 @@ type ReturnValue = Dialog.Handle<Payload>;
 
 ### Handle
 
-A handle to control a Dialog imperatively and to associate detached triggers with it.
-
-**Constructor Parameters:**
+Controls a Dialog imperatively and associates detached `Dialog.Trigger` components with a
+`Dialog.Root`. Create one with `Dialog.createHandle()` and pass it to the `handle` prop of the
+root and of any triggers rendered outside of it.
 
-| Parameter | Type                   | Default | Description |
-| :-------- | :--------------------- | :------ | :---------- |
-| store?    | `DialogStore<Payload>` | -       | -           |
+The imperative methods take effect only while a root using this handle is mounted; calls made
+before a root attaches (or after it unmounts) are ignored.
 
 **Properties:**
 
-| Property | Type      | Modifiers | Description                                     |
-| :------- | :-------- | :-------- | :---------------------------------------------- |
-| isOpen   | `boolean` | readonly  | Indicates whether the dialog is currently open. |
+| Property | Type      | Modifiers | Description                                                                                    |
+| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the dialog is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -3774,8 +4491,7 @@ A handle to control a Dialog imperatively and to associate detached triggers wit
 function open(triggerId: string | null): void;
 ```
 
-Opens the dialog and associates it with the trigger with the given id.
-The trigger, if provided, must be a matching Trigger component with this handle passed as a prop.
+Opens the dialog, optionally associating it with a trigger.
 
 This method should only be called in an event handler or an effect (not during rendering).
 
@@ -3783,8 +4499,9 @@ This method should only be called in an event handler or an effect (not during r
 function openWithPayload(payload: Payload): void;
 ```
 
-Opens the dialog and sets the payload.
-Does not associate the dialog with any trigger.
+Opens the dialog with the given payload, without associating it with any trigger.
+
+This method should only be called in an event handler or an effect (not during rendering).
 
 ```typescript
 function close(): void;
@@ -3792,6 +4509,8 @@ function close(): void;
 
 Closes the dialog.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ## External Types
 
 ### InteractionType