@base-ui/react 1.6.0 → 1.7.0

package/docs/react/components/menu.md

@@ -26,11 +26,11 @@ import { Menu } from '@base-ui/react/menu';
 export default function ExampleMenu() {
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         Song <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <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}>Add to Library</Menu.Item>
             <Menu.Item className={itemClass}>Add to Playlist</Menu.Item>
@@ -118,7 +118,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -247,7 +247,7 @@ export default function ExampleMenu() {
         Song <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.Item className={styles.Item}>Add to Library</Menu.Item>
             <Menu.Item className={styles.Item}>Add to Playlist</Menu.Item>
@@ -346,12 +346,12 @@ export default function ExampleMenu() {
     <Menu.Root>
       <Menu.Trigger
         openOnHover
-        className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+        className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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"
       >
         Add to playlist <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <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}>Get Up!</Menu.Item>
             <Menu.Item className={itemClass}>Inside Out</Menu.Item>
@@ -436,7 +436,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -565,7 +565,7 @@ export default function ExampleMenu() {
         Add to playlist <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.Item className={styles.Item}>Get Up!</Menu.Item>
             <Menu.Item className={styles.Item}>Inside Out</Menu.Item>
@@ -618,11 +618,11 @@ export default function ExampleMenu() {
 
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         Workspace <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <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.CheckboxItem
               checked={showMinimap}
@@ -748,7 +748,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -894,7 +894,7 @@ export default function ExampleMenu() {
         Workspace <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.CheckboxItem
               checked={showMinimap}
@@ -985,11 +985,11 @@ export default function ExampleMenu() {
   const [value, setValue] = React.useState('date');
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         Sort <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <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.RadioGroup value={value} onValueChange={setValue}>
               <Menu.RadioItem value="date" className={radioItemClass}>
@@ -1105,7 +1105,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -1247,7 +1247,7 @@ export default function ExampleMenu() {
         Sort <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.RadioGroup value={value} onValueChange={setValue}>
               <Menu.RadioItem className={styles.RadioItem} value="date">
@@ -1344,11 +1344,11 @@ export default function ExampleMenu() {
 
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         View <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <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.RadioGroup value={value} onValueChange={setValue}>
               <Menu.GroupLabel className="py-2 pr-8 pl-[2.125rem] text-sm leading-4 text-neutral-500 select-none dark:text-neutral-400">
@@ -1505,7 +1505,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -1670,7 +1670,7 @@ export default function ExampleMenu() {
         View <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.RadioGroup value={value} onValueChange={setValue}>
               <Menu.GroupLabel className={styles.GroupLabel}>Sort</Menu.GroupLabel>
@@ -1816,11 +1816,11 @@ import { Menu } from '@base-ui/react/menu';
 export default function ExampleMenu() {
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         Song <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className="outline-hidden" sideOffset={8}>
+        <Menu.Positioner className="outline-hidden" sideOffset={8} align="start">
           <Menu.Popup className={popupClass}>
             <Menu.Item className={itemClass}>Add to Library</Menu.Item>
 
@@ -1865,7 +1865,7 @@ export default function ExampleMenu() {
 const popupClass =
   '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';
 const itemClass =
-  "flex cursor-default py-2 pr-6 pl-4 text-sm leading-4 outline-hidden select-none data-popup-open:relative data-popup-open:z-0 data-popup-open:before:absolute data-popup-open:before:inset-x-1 data-popup-open:before:inset-y-0 data-popup-open:before:z-[-1] data-popup-open:before:bg-neutral-100 data-popup-open:before:content-[''] 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-[''] data-highlighted:data-popup-open:before:bg-neutral-950 data-disabled:text-neutral-500 dark:data-popup-open:before:bg-neutral-800 dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white dark:data-highlighted:data-popup-open:before:bg-white dark:data-disabled:text-neutral-400";
+  "flex cursor-default py-2 pr-6 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-[''] data-disabled:text-neutral-500 dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white dark:data-disabled:text-neutral-400";
 const submenuTriggerClass =
   "flex cursor-default items-center justify-between gap-4 py-2 pr-2 pl-4 text-sm leading-4 outline-hidden select-none data-popup-open:relative data-popup-open:z-0 data-popup-open:before:absolute data-popup-open:before:inset-x-1 data-popup-open:before:inset-y-0 data-popup-open:before:z-[-1] data-popup-open:before:bg-neutral-100 data-popup-open:before:content-[''] 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-[''] data-highlighted:data-popup-open:before:bg-neutral-950 data-disabled:text-neutral-500 dark:data-popup-open:before:bg-neutral-800 dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white dark:data-highlighted:data-popup-open:before:bg-white dark:data-disabled:text-neutral-400";
 
@@ -1956,7 +1956,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2030,11 +2030,6 @@ This example shows how to implement the component using CSS Modules.
   font-size: 0.875rem;
   line-height: 1rem;
 
-  &[data-popup-open] {
-    z-index: 0;
-    position: relative;
-  }
-
   &[data-highlighted] {
     z-index: 0;
     position: relative;
@@ -2045,32 +2040,12 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]::before,
   &[data-highlighted]::before {
     content: '';
     z-index: -1;
     position: absolute;
     inset-block: 0;
     inset-inline: 0.25rem;
-  }
-
-  &[data-popup-open]::before {
-    background-color: oklch(97% 0 0deg);
-
-    @media (prefers-color-scheme: dark) {
-      background-color: oklch(26.9% 0 0deg);
-    }
-  }
-
-  &[data-highlighted]::before {
-    background-color: oklch(14.5% 0 0deg);
-
-    @media (prefers-color-scheme: dark) {
-      background-color: white;
-    }
-  }
-
-  &[data-highlighted][data-popup-open]::before {
     background-color: oklch(14.5% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2092,6 +2067,32 @@ This example shows how to implement the component using CSS Modules.
   justify-content: space-between;
   gap: 1rem;
   padding-right: 0.5rem;
+
+  &[data-popup-open] {
+    z-index: 0;
+    position: relative;
+  }
+
+  &[data-popup-open]::before {
+    content: '';
+    z-index: -1;
+    position: absolute;
+    inset-block: 0;
+    inset-inline: 0.25rem;
+    background-color: oklch(97% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: oklch(26.9% 0 0deg);
+    }
+  }
+
+  &[data-highlighted][data-popup-open]::before {
+    background-color: oklch(14.5% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: white;
+    }
+  }
 }
 
 .Separator {
@@ -2119,7 +2120,7 @@ export default function ExampleMenu() {
         Song <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
-        <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+        <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
           <Menu.Popup className={styles.Popup}>
             <Menu.Item className={styles.Item}>Add to Library</Menu.Item>
 
@@ -2255,6 +2256,9 @@ When the trigger and menu content need to live in different parts of the tree (f
 Note that only top-level menus can have detached triggers.
 Submenus must have their triggers defined within the `SubmenuRoot` part.
 
+The imperative methods on the handle, such as `open()` and `close()`, require a `<Menu.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 demoMenu = Menu.createHandle();
 
@@ -2298,14 +2302,14 @@ export default function MenuDetachedTriggersSimpleDemo() {
       <Menu.Trigger
         handle={demoMenu}
         aria-label="Project actions"
-        className="flex size-8 items-center justify-center rounded-none border border-neutral-950 bg-white text-neutral-950 select-none hover:not-data-disabled:bg-neutral-100 active:not-data-disabled:bg-neutral-200 data-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+        className="flex size-8 items-center justify-center rounded-none border border-neutral-950 bg-white 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 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 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"
       >
         <EllipsisHorizontalIcon />
       </Menu.Trigger>
 
       <Menu.Root handle={demoMenu}>
         <Menu.Portal>
-          <Menu.Positioner sideOffset={8} className="outline-hidden">
+          <Menu.Positioner sideOffset={8} align="start" className="outline-hidden">
             <Menu.Popup className={popupClass}>
               <Menu.Item className={itemClass}>Rename</Menu.Item>
               <Menu.Item className={itemClass}>Duplicate</Menu.Item>
@@ -2391,7 +2395,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2472,7 +2476,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2620,7 +2624,7 @@ export default function MenuDetachedTriggersSimpleDemo() {
 
       <Menu.Root handle={demoMenu}>
         <Menu.Portal>
-          <Menu.Positioner sideOffset={8} className={styles.Positioner}>
+          <Menu.Positioner sideOffset={8} align="start" className={styles.Positioner}>
             <Menu.Popup className={styles.Popup}>
               <Menu.Item className={styles.Item}>Rename</Menu.Item>
               <Menu.Item className={styles.Item}>Duplicate</Menu.Item>
@@ -2823,7 +2827,7 @@ export default function MenuDetachedTriggersControlledDemo() {
       >
         {({ payload }) => (
           <Menu.Portal>
-            <Menu.Positioner sideOffset={8} className="outline-hidden">
+            <Menu.Positioner sideOffset={8} align="start" className="outline-hidden">
               <Menu.Popup className={popupClass}>
                 {payload &&
                   MENUS[payload].map((item, index) => (
@@ -2843,7 +2847,7 @@ export default function MenuDetachedTriggersControlledDemo() {
 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-[''] data-disabled:text-neutral-500 dark:data-highlighted:text-neutral-950 dark:data-highlighted:before:bg-white dark:data-disabled:text-neutral-400";
 const triggerClass =
-  'flex h-8 items-center justify-center gap-2 rounded-none border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:bg-neutral-100 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white active:bg-neutral-200 data-popup-open:bg-neutral-100 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-popup-open:bg-neutral-800';
+  'flex h-8 items-center justify-center gap-2 rounded-none border border-neutral-950 bg-white px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 select-none hover:bg-neutral-100 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white active:bg-neutral-200 data-pressed:bg-neutral-100 dark:border-white dark:bg-neutral-950 dark:text-white dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-pressed:bg-neutral-800';
 const popupClass =
   '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';
 ```
@@ -2895,7 +2899,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -2976,7 +2980,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -3195,7 +3199,7 @@ export default function MenuDetachedTriggersControlledDemo() {
       >
         {({ payload }) => (
           <Menu.Portal>
-            <Menu.Positioner className={styles.Positioner} sideOffset={8}>
+            <Menu.Positioner className={styles.Positioner} sideOffset={8} align="start">
               <Menu.Popup className={styles.Popup}>
                 {payload &&
                   itemGroups[payload].map((item, index) => (
@@ -3232,7 +3236,7 @@ import { Menu } from '@base-ui/react/menu';
 export default function MenuArrowDemo() {
   return (
     <Menu.Root>
-      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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-popup-open: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 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 dark:data-popup-open:bg-neutral-800 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+      <Menu.Trigger className="flex h-8 items-center justify-center gap-1.5 rounded-none border border-neutral-950 bg-white pl-3 pr-2 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 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 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">
         Song <CaretDownIcon />
       </Menu.Trigger>
       <Menu.Portal>
@@ -3328,7 +3332,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -3550,7 +3554,7 @@ The menu also supports content transitions.
 This is useful when different triggers display different content within the same menu.
 
 To enable content animations, wrap the menu content in the `<Menu.Viewport>` part.
-This part renders a `div` with `data-activation-direction`, containing space-separated horizontal (`left` or `right`) and vertical (`up` or `down`) values so you can make direction-aware animations.
+This part renders a `div` with `data-activation-direction`, containing up to two space-separated tokens — a horizontal (`left` or `right`) and a vertical (`up` or `down`) value — so you can make direction-aware animations.
 
 Inside `<Menu.Viewport>`, content is wrapped in `div`s with transition data attributes:
 
@@ -3620,6 +3624,7 @@ export default function MenuDetachedTriggersFullDemo() {
           <Menu.Portal>
             <Menu.Positioner
               sideOffset={8}
+              align="start"
               className={`
                 outline-none
                 h-[var(--positioner-height)] w-[var(--positioner-width)] max-w-[var(--available-width)]
@@ -3700,9 +3705,9 @@ const triggerClass = `
   rounded-none border border-neutral-950 bg-white
   px-3 text-sm font-normal text-neutral-950
   select-none
-  hover:bg-neutral-100 active:bg-neutral-200 data-popup-open:bg-neutral-100
+  hover:bg-neutral-100 active:bg-neutral-200 data-pressed:bg-neutral-100
   dark:border-white dark:bg-neutral-950 dark:text-white
-  dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-popup-open:bg-neutral-800
+  dark:hover:bg-neutral-800 dark:active:bg-neutral-700 dark:data-pressed:bg-neutral-800
   focus-visible:outline focus-visible:outline-2
   focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white
 `;
@@ -3764,7 +3769,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -3845,7 +3850,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open] {
+  &[data-pressed] {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -4034,6 +4039,7 @@ export default function MenuDetachedTriggersFullDemo() {
           <Menu.Portal>
             <Menu.Positioner
               sideOffset={8}
+              align="start"
               className={`${styles.Positioner} ${transitionStyles.Positioner}`}
             >
               <Menu.Popup className={`${styles.Popup} ${transitionStyles.Popup}`}>
@@ -4157,23 +4163,23 @@ Doesn't render its own HTML element.
 
 **Root Props:**
 
-| Prop                 | Type                                                                    | Default      | Description                                                                                                                                                                                                                                                          |
-| :------------------- | :---------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| defaultOpen          | `boolean`                                                               | `false`      | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.                                                                                                                                                                        |
-| open                 | `boolean`                                                               | -            | Whether the menu is currently open.                                                                                                                                                                                                                                  |
-| onOpenChange         | `((open: boolean, eventDetails: Menu.Root.ChangeEventDetails) => void)` | -            | Event handler called when the menu is opened or closed.                                                                                                                                                                                                              |
-| highlightItemOnHover | `boolean`                                                               | `true`       | Whether moving the pointer over items should highlight them.&#xA;Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.                                                                                          |
-| actionsRef           | `React.RefObject<Menu.Root.Actions \| null>`                            | -            | A ref to imperative actions. `unmount`: Manually unmounts the menu.&#xA;Call this after any externally controlled closing animation finishes.`close`: When specified, the menu can be closed imperatively.                                                           |
-| closeParentOnEsc     | `boolean`                                                               | `false`      | When in a submenu, determines whether pressing the Escape key&#xA;closes the entire menu, or only the current child menu.                                                                                                                                            |
-| defaultTriggerId     | `string \| null`                                                        | -            | ID of the trigger that the popover is associated with.&#xA;This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.                                                                                                            |
-| handle               | `Menu.Handle<Payload>`                                                  | -            | A handle to associate the menu with a trigger.&#xA;If specified, allows external triggers to control the menu's open state.                                                                                                                                          |
-| loopFocus            | `boolean`                                                               | `true`       | Whether to loop keyboard focus back to the first item&#xA;when the end of the list is reached while using the arrow keys.                                                                                                                                            |
-| modal                | `boolean`                                                               | `true`       | Determines if the menu enters a modal state when open. `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed. |
-| onOpenChangeComplete | `((open: boolean) => void)`                                             | -            | Event handler called after any animations complete when the menu is closed.                                                                                                                                                                                          |
-| triggerId            | `string \| null`                                                        | -            | ID of the trigger that the popover is associated with.&#xA;This is useful in conjunction with the `open` prop to create a controlled popover.&#xA;There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).  |
-| disabled             | `boolean`                                                               | `false`      | Whether the component should ignore user interaction.                                                                                                                                                                                                                |
-| orientation          | `Menu.Root.Orientation`                                                 | `'vertical'` | The visual orientation of the menu.&#xA;Controls whether roving focus uses up/down or left/right arrow keys.                                                                                                                                                         |
-| children             | `React.ReactNode \| PayloadChildRenderFunction<Payload>`                | -            | The content of the popover.&#xA;This can be a regular React node or a render function that receives the `payload` of the active trigger.                                                                                                                             |
+| Prop                 | Type                                                                    | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| :------------------- | :---------------------------------------------------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| defaultOpen          | `boolean`                                                               | `false`      | Whether the menu is initially open. To render a controlled menu, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| open                 | `boolean`                                                               | -            | Whether the menu is currently open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| onOpenChange         | `((open: boolean, eventDetails: Menu.Root.ChangeEventDetails) => void)` | -            | Event handler called when the menu is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| highlightItemOnHover | `boolean`                                                               | `true`       | Whether moving the pointer over items should highlight them.&#xA;Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.                                                                                                                                                                                                                                                                                                                                             |
+| actionsRef           | `React.RefObject<Menu.Root.Actions \| null>`                            | -            | A ref to imperative actions. `unmount`: Manually unmounts the menu.&#xA;Call this after any externally controlled closing animation finishes.`close`: When specified, the menu can be closed imperatively.                                                                                                                                                                                                                                                                                                              |
+| closeParentOnEsc     | `boolean`                                                               | `false`      | When in a submenu, determines whether pressing the Escape key&#xA;closes the entire menu, or only the current child menu.                                                                                                                                                                                                                                                                                                                                                                                               |
+| defaultTriggerId     | `string \| null`                                                        | -            | ID of the trigger that the menu is associated with.&#xA;This is useful in conjunction with the `defaultOpen` prop to create an initially open menu.                                                                                                                                                                                                                                                                                                                                                                     |
+| handle               | `Menu.Handle<Payload>`                                                  | -            | A handle to associate the menu with a trigger.&#xA;If specified, allows external triggers to control the menu's open state.                                                                                                                                                                                                                                                                                                                                                                                             |
+| loopFocus            | `boolean`                                                               | `true`       | Whether to loop keyboard focus back to the first item&#xA;when the end of the list is reached while using the arrow keys.                                                                                                                                                                                                                                                                                                                                                                                               |
+| modal                | `boolean`                                                               | `true`       | Determines if the menu enters a modal state when open. `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. Nested menus ignore this prop, and menus opened by hover are never modal. |
+| onOpenChangeComplete | `((open: boolean) => void)`                                             | -            | Event handler called after any animations complete when the menu is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| triggerId            | `string \| null`                                                        | -            | ID of the trigger that the menu is associated with.&#xA;This is useful in conjunction with the `open` prop to create a controlled menu.&#xA;There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set).                                                                                                                                                                                                                                                              |
+| disabled             | `boolean`                                                               | `false`      | Whether the component should ignore user interaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| orientation          | `Menu.Root.Orientation`                                                 | `'vertical'` | The visual orientation of the menu.&#xA;Controls whether roving focus uses up/down or left/right arrow keys.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| children             | `React.ReactNode \| PayloadChildRenderFunction<Payload>`                | -            | The content of the menu.&#xA;This can be a regular React node or a render function that receives the `payload` of the active trigger.                                                                                                                                                                                                                                                                                                                                                                                   |
 
 ### Root.Props
 
@@ -4332,12 +4338,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                             |
-| :------------------ | :--- | :-------------------------------------- |
-| data-open           | -    | Present when the menu is open.          |
-| data-closed         | -    | Present when the menu is closed.        |
-| data-starting-style | -    | Present when the menu is animating in.  |
-| data-ending-style   | -    | Present when the menu is animating out. |
+| Attribute           | Type | Description                                |
+| :------------------ | :--- | :----------------------------------------- |
+| data-open           | -    | Present when the menu is open.             |
+| data-closed         | -    | Present when the menu is closed.           |
+| data-starting-style | -    | Present when the menu begins animating in. |
+| data-ending-style   | -    | Present when the menu is animating out.    |
 
 ### Backdrop.Props
 
@@ -4423,13 +4429,15 @@ Renders a `<div>` element.
 
 **Positioner CSS Variables:**
 
-| Variable             | Type     | Description                                                                            |
-| :------------------- | :------- | :------------------------------------------------------------------------------------- |
-| `--anchor-height`    | `number` | The anchor's height.                                                                   |
-| `--anchor-width`     | `number` | The anchor's width.                                                                    |
-| `--available-height` | `number` | The available height between the trigger and the edge of the viewport.                 |
-| `--available-width`  | `number` | The available width between the trigger and the edge of the viewport.                  |
-| `--transform-origin` | `string` | The coordinates that this element is anchored to. Used for animations and transitions. |
+| Variable              | Type     | Description                                                                                                                    |
+| :-------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| `--anchor-height`     | `number` | The anchor's height.                                                                                                           |
+| `--anchor-width`      | `number` | The anchor's width.                                                                                                            |
+| `--available-height`  | `number` | The available height between the trigger and the edge of the viewport.                                                         |
+| `--available-width`   | `number` | The available width between the trigger and the edge of the viewport.                                                          |
+| `--positioner-height` | `number` | The height of the menu's positioner.&#xA;It is important to set `height` to this value when using CSS to animate size changes. |
+| `--positioner-width`  | `number` | The width of the menu's positioner.&#xA;It is important to set `width` to this value when using CSS to animate size changes.   |
+| `--transform-origin`  | `string` | The coordinates that this element is anchored to. Used for animations and transitions.                                         |
 
 ### Positioner.Props
 
@@ -4478,7 +4486,7 @@ Renders a `<div>` element.
 | data-align          | `'start' \| 'center' \| 'end'`                                             | Indicates how the popup is aligned relative to specified side.        |
 | data-instant        | `'click' \| 'dismiss' \| 'group' \| 'trigger-change'`                      | Present if animations should be instant.                              |
 | data-side           | `'top' \| 'bottom' \| 'left' \| 'right' \| 'inline-end' \| 'inline-start'` | Indicates which side the popup is positioned relative to the trigger. |
-| data-starting-style | -                                                                          | Present when the menu is animating in.                                |
+| data-starting-style | -                                                                          | Present when the menu begins animating in.                            |
 | data-ending-style   | -                                                                          | Present when the menu is animating out.                               |
 
 ### Popup.Props
@@ -4726,7 +4734,7 @@ Doesn't render its own HTML element.
 | actionsRef           | `React.RefObject<Menu.Root.Actions \| null>`                                   | -            | A ref to imperative actions. `unmount`: Manually unmounts the menu.&#xA;Call this after any externally controlled closing animation finishes.`close`: When specified, the menu can be closed imperatively. |
 | closeParentOnEsc     | `boolean`                                                                      | `false`      | When in a submenu, determines whether pressing the Escape key&#xA;closes the entire menu, or only the current child menu.                                                                                  |
 | loopFocus            | `boolean`                                                                      | `true`       | Whether to loop keyboard focus back to the first item&#xA;when the end of the list is reached while using the arrow keys.                                                                                  |
-| onOpenChangeComplete | `((open: boolean) => void)`                                                    | -            | Event handler called after any animations complete when the menu is closed.                                                                                                                                |
+| onOpenChangeComplete | `((open: boolean) => void)`                                                    | -            | Event handler called after any animations complete when the menu is opened or closed.                                                                                                                      |
 | disabled             | `boolean`                                                                      | `false`      | Whether the component should ignore user interaction.                                                                                                                                                      |
 | orientation          | `Menu.Root.Orientation`                                                        | `'vertical'` | The visual orientation of the menu.&#xA;Controls whether roving focus uses up/down or left/right arrow keys.                                                                                               |
 | children             | `React.ReactNode`                                                              | -            | The content of the submenu.                                                                                                                                                                                |
@@ -4980,13 +4988,13 @@ Renders a `<span>` element.
 
 **RadioItemIndicator Data Attributes:**
 
-| Attribute           | Type | Description                                        |
-| :------------------ | :--- | :------------------------------------------------- |
-| data-checked        | -    | Present when the menu radio item is selected.      |
-| data-unchecked      | -    | Present when the menu radio item is not selected.  |
-| data-disabled       | -    | Present when the menu radio item is disabled.      |
-| data-starting-style | -    | Present when the radio indicator is animating in.  |
-| data-ending-style   | -    | Present when the radio indicator is animating out. |
+| Attribute           | Type | Description                                           |
+| :------------------ | :--- | :---------------------------------------------------- |
+| data-checked        | -    | Present when the menu radio item is selected.         |
+| data-unchecked      | -    | Present when the menu radio item is not selected.     |
+| data-disabled       | -    | Present when the menu radio item is disabled.         |
+| data-starting-style | -    | Present when the radio indicator begins animating in. |
+| data-ending-style   | -    | Present when the radio indicator is animating out.    |
 
 ### RadioItemIndicator.Props
 
@@ -5126,7 +5134,7 @@ Renders a `<span>` element.
 | data-checked        | -    | Present when the menu checkbox item is checked.     |
 | data-unchecked      | -    | Present when the menu checkbox item is not checked. |
 | data-disabled       | -    | Present when the menu checkbox item is disabled.    |
-| data-starting-style | -    | Present when the indicator is animating in.         |
+| data-starting-style | -    | Present when the indicator begins animating in.     |
 | data-ending-style   | -    | Present when the indicator is animating out.        |
 
 ### CheckboxItemIndicator.Props
@@ -5160,11 +5168,18 @@ type ReturnValue = Menu.Handle<Payload>;
 
 ### Handle
 
+Controls a Menu imperatively and associates detached `Menu.Trigger` components with a `Menu.Root`.
+Create one with `Menu.createHandle()` and pass it to the `handle` prop of the root and of any
+triggers rendered outside of it.
+
+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 menu is currently open. |
+| Property | Type      | Modifiers | Description                                                                                  |
+| :------- | :-------- | :-------- | :------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the menu is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -5173,7 +5188,8 @@ function open(triggerId: string): void;
 ```
 
 Opens the menu and associates it with the trigger with the given id.
-The trigger must be a Menu.Trigger component with this handle passed as a prop.
+
+This method should only be called in an event handler or an effect (not during rendering).
 
 ```typescript
 function close(): void;
@@ -5181,6 +5197,8 @@ function close(): void;
 
 Closes the menu.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ### LinkItem
 
 A link in the menu that can be used to navigate to a different page or section.
@@ -5188,13 +5206,13 @@ Renders an `<a>` element.
 
 **LinkItem Props:**
 
-| Prop         | Type                                                                                        | Default | Description                                                                                                                                                                                   |
-| :----------- | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| label        | `string`                                                                                    | -       | Overrides the text label to use when the item is matched during keyboard text navigation.                                                                                                     |
-| closeOnClick | `boolean`                                                                                   | `false` | Whether to close the menu when the item is clicked.                                                                                                                                           |
-| className    | `string \| ((state: Menu.LinkItem.State) => string \| undefined)`                           | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
-| style        | `React.CSSProperties \| ((state: Menu.LinkItem.State) => React.CSSProperties \| undefined)` | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
-| render       | `ReactElement \| ((props: HTMLProps, state: Menu.LinkItem.State) => ReactElement)`          | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
+| Prop         | Type                                                                                                                                                               | Default | Description                                                                                                                                                                                   |
+| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| label        | `string`                                                                                                                                                           | -       | Overrides the text label to use when the item is matched during keyboard text navigation.                                                                                                     |
+| closeOnClick | `boolean`                                                                                                                                                          | `false` | Whether to close the menu when the item is clicked.                                                                                                                                           |
+| className    | `string \| ((state: Menu.LinkItem.State) => string \| undefined)`                                                                                                  | -       | CSS class applied to the element, or a function that&#xA;returns a class based on the component's state.                                                                                      |
+| style        | `React.CSSProperties \| ((state: Menu.LinkItem.State) => React.CSSProperties \| undefined)`                                                                        | -       | Style applied to the element, or a function that&#xA;returns a style object based on the component's state.                                                                                   |
+| render       | `ReactElement \| ((props: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, state: Menu.LinkItem.State) => ReactElement)` | -       | Allows you to replace the component's HTML element&#xA;with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
 
 **LinkItem Data Attributes:**
 
@@ -5350,6 +5368,8 @@ Maps `Canonical`: `Alias` — Use Canonical when its namespace is already import
 - `Menu.SubmenuTrigger.Props`: `MenuSubmenuTriggerProps`
 - `Menu.SubmenuTrigger.State`: `MenuSubmenuTriggerState`
 
+The `Viewport` is optional — reach for it only when a single popup is opened by multiple triggers, its content differs per trigger, and the switch between them is animated. When used, set `width: var(--positioner-width)` and `height: var(--positioner-height)` on the `Positioner` so its box is frozen to the measured size during the transition; otherwise content-driven resizing can make the popup thrash or flip to another side.
+
 ## createHandle
 
 [//]: # '@exclude-table-of-contents'