@base-ui/react 1.6.0 → 1.7.0

package/docs/react/components/otp-field.md

@@ -44,7 +44,7 @@ export default function ExampleOTPField() {
           <OTPField.Input
             key={index}
             className="m-0 h-10 w-10 rounded-none border border-neutral-950 bg-white dark:bg-neutral-950 text-center font-inherit text-base font-normal text-neutral-950 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white"
-            aria-label={`Character ${index + 1} of ${OTP_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${OTP_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -160,7 +160,7 @@ export default function ExampleOTPField() {
           <OTPField.Input
             key={index}
             className={styles.Input}
-            aria-label={`Character ${index + 1} of ${OTP_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${OTP_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -276,7 +276,7 @@ export default function OTPFieldAlphanumericDemo() {
           <OTPField.Input
             key={index}
             className="m-0 h-10 w-10 rounded-none border border-neutral-950 bg-white dark:bg-neutral-950 text-center font-inherit text-base font-normal text-neutral-950 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white"
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -366,7 +366,8 @@ This example shows how to implement the component using CSS Modules.
 
 .Code {
   font-family:
-    ui-monospace, SFMono-Regular, 'SF Mono', Consolas, 'Liberation Mono', Menlo, monospace;
+    'Paper Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
+    'Courier New', monospace;
 }
 ```
 
@@ -398,7 +399,7 @@ export default function OTPFieldAlphanumericDemo() {
           <OTPField.Input
             key={index}
             className={styles.Input}
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -443,7 +444,7 @@ export default function OTPFieldGroupedDemo() {
             <OTPField.Input
               key={index}
               className="m-0 h-10 w-10 rounded-none border border-neutral-950 bg-white dark:bg-neutral-950 text-center font-inherit text-base font-normal text-neutral-950 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white"
-              aria-label={`Character ${index + 1} of ${OTP_LENGTH}`}
+              aria-label={index === 0 ? undefined : `Character ${index + 1} of ${OTP_LENGTH}`}
             />
           ))}
         </div>
@@ -568,7 +569,7 @@ export default function OTPFieldGroupedDemo() {
             <OTPField.Input
               key={index}
               className={styles.Input}
-              aria-label={`Character ${index + 1} of ${OTP_LENGTH}`}
+              aria-label={index === 0 ? undefined : `Character ${index + 1} of ${OTP_LENGTH}`}
             />
           ))}
         </div>
@@ -626,7 +627,7 @@ export default function OTPFieldFocusedPlaceholderDemo() {
             key={index}
             className="m-0 h-10 w-10 rounded-none border border-neutral-950 bg-white dark:bg-neutral-950 text-center font-inherit text-base font-normal text-neutral-950 placeholder:text-neutral-500 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white focus:placeholder:text-transparent dark:border-white dark:text-white dark:placeholder:text-neutral-400"
             placeholder="•"
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -755,7 +756,7 @@ export default function OTPFieldFocusedPlaceholderDemo() {
             key={index}
             className={styles.Input}
             placeholder="•"
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -999,7 +1000,7 @@ export default function OTPFieldCustomNormalizeDemo() {
           <OTPField.Input
             key={index}
             className={`${styles.Input} ${activeInvalidIndex === index ? invalidClassName : ''}`.trim()}
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
             onFocus={() => {
               setFocusedIndex(index);
             }}
@@ -1119,7 +1120,7 @@ export default function OTPFieldPasswordDemo() {
           <OTPField.Input
             key={index}
             className="m-0 h-10 w-10 rounded-none border border-neutral-950 bg-white dark:bg-neutral-950 text-center font-inherit text-base font-normal text-neutral-950 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white dark:border-white dark:text-white"
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -1209,7 +1210,8 @@ This example shows how to implement the component using CSS Modules.
 
 .Code {
   font-family:
-    ui-monospace, SFMono-Regular, 'SF Mono', Consolas, 'Liberation Mono', Menlo, monospace;
+    'Paper Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
+    'Courier New', monospace;
 }
 ```
 
@@ -1241,7 +1243,7 @@ export default function OTPFieldPasswordDemo() {
           <OTPField.Input
             key={index}
             className={styles.Input}
-            aria-label={`Character ${index + 1} of ${CODE_LENGTH}`}
+            aria-label={index === 0 ? undefined : `Character ${index + 1} of ${CODE_LENGTH}`}
           />
         ))}
       </OTPField.Root>
@@ -1403,11 +1405,11 @@ Renders an `<input>` element.
 
 **Input Props:**
 
-| Prop      | Type                                                                                         | Default | Description                                                                                                                                                                                   |
-| :-------- | :------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| className | `string \| ((state: OTPField.Input.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: OTPField.Input.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: OTPField.Input.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                                                                                                                                                                                   |
+| :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| className | `string \| ((state: OTPField.Input.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: OTPField.Input.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.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, state: OTPField.Input.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. |
 
 **Input Data Attributes:**
 

package/docs/react/components/popover.md

@@ -23,7 +23,7 @@ This example shows how to implement the component using Tailwind CSS.
 import { Popover } from '@base-ui/react/popover';
 
 const triggerClassName =
-  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-popup-open:bg-neutral-100 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';
+  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-pressed:bg-neutral-100 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';
 
 export default function ExamplePopover() {
   return (
@@ -207,7 +207,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]:not([data-disabled], :disabled) {
+  &[data-pressed]:not([data-disabled], :disabled) {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -307,7 +307,7 @@ This example shows how to implement the component using Tailwind CSS.
 import { Popover } from '@base-ui/react/popover';
 
 const triggerClassName =
-  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-popup-open:bg-neutral-100 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';
+  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-pressed:bg-neutral-100 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';
 
 export default function ExamplePopover() {
   return (
@@ -493,7 +493,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]:not([data-disabled], :disabled) {
+  &[data-pressed]:not([data-disabled], :disabled) {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -559,6 +559,9 @@ For simple, one-off interactions, place the `<Popover.Trigger>` inside `<Popover
 However, if defining the popover's content next to its trigger is not practical, you can use a detached trigger.
 This involves placing the `<Popover.Trigger>` outside of `<Popover.Root>` and linking them with a `handle` created by the `Popover.createHandle()` function.
 
+The imperative methods on the handle, such as `open()` and `close()`, require a `<Popover.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 demoPopover = Popover.createHandle();
 
@@ -590,7 +593,7 @@ import { Popover } from '@base-ui/react/popover';
 const demoPopover = Popover.createHandle();
 
 const triggerClassName =
-  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-popup-open:bg-neutral-100 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';
+  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-pressed:bg-neutral-100 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';
 
 export default function PopoverDetachedTriggersSimpleDemo() {
   return (
@@ -779,7 +782,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]:not([data-disabled], :disabled) {
+  &[data-pressed]:not([data-disabled], :disabled) {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -938,7 +941,7 @@ import { Popover } from '@base-ui/react/popover';
 const demoPopover = Popover.createHandle();
 
 const triggerClassName =
-  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-popup-open:bg-neutral-100 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';
+  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-pressed:bg-neutral-100 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';
 
 export default function PopoverDetachedTriggersControlledDemo() {
   const [open, setOpen] = React.useState(false);
@@ -1164,7 +1167,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]:not([data-disabled], :disabled) {
+  &[data-pressed]:not([data-disabled], :disabled) {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -1279,7 +1282,7 @@ This is useful when different triggers display different content within the same
 
 To enable content animations, wrap the content in the `<Popover.Viewport>` part.
 This part provides features to create direction-aware animations.
-It renders a `div` with a `data-activation-direction` attribute (`left`, `right`, `up`, or `down`) that indicates the new trigger's position relative to the previous one.
+It renders a `div` with a `data-activation-direction` attribute that indicates the new trigger's position relative to the previous one. The value is a space-separated set of up to two tokens (one per axis) — `left` or `right` for the horizontal axis and `up` or `down` for the vertical axis (for example, `right down`). Match a single token with the `~=` attribute selector, such as `[data-activation-direction~='right']`.
 
 Inside the `<Popover.Viewport>`, the content is further wrapped in `div`s with data attributes to help with styling:
 
@@ -1304,7 +1307,7 @@ import { Avatar } from '@base-ui/react/avatar';
 const demoPopover = Popover.createHandle<React.ComponentType>();
 
 const triggerClassName =
-  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-popup-open:bg-neutral-100 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';
+  'flex h-8 items-center justify-center border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm font-normal whitespace-nowrap 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 data-pressed:bg-neutral-100 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';
 
 export default function PopoverDetachedTriggersFullDemo() {
   return (
@@ -1590,7 +1593,7 @@ This example shows how to implement the component using CSS Modules.
     }
   }
 
-  &[data-popup-open]:not([data-disabled], :disabled) {
+  &[data-pressed]:not([data-disabled], :disabled) {
     background-color: oklch(97% 0 0deg);
 
     @media (prefers-color-scheme: dark) {
@@ -1997,18 +2000,18 @@ Doesn't render its own HTML element.
 
 **Root Props:**
 
-| Prop                 | Type                                                                       | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| :------------------- | :------------------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| defaultOpen          | `boolean`                                                                  | `false` | Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| open                 | `boolean`                                                                  | -       | Whether the popover is currently open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| onOpenChange         | `((open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void)` | -       | Event handler called when the popover is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| actionsRef           | `React.RefObject<Popover.Root.Actions \| null>`                            | -       | A ref to imperative actions. `unmount`: Manually unmounts the popover.&#xA;Call this after any externally controlled closing animation finishes.`close`: Closes the popover imperatively when called.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| 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               | `Popover.Handle<Payload>`                                                  | -       | A handle to associate the popover with a trigger.&#xA;If specified, allows external triggers to control the popover's open state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| modal                | `boolean \| 'trap-focus'`                                                  | `false` | Determines if the popover enters a modal state when open. `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed.`'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered&#xA;inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as&#xA;Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch&#xA;screen readers can escape the popup. |
-| onOpenChangeComplete | `((open: boolean) => void)`                                                | -       | Event handler called after any animations complete when the popover is opened or 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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| 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 popover is initially open. To render a controlled popover, use the `open` prop instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| open                 | `boolean`                                                                  | -       | Whether the popover is currently open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| onOpenChange         | `((open: boolean, eventDetails: Popover.Root.ChangeEventDetails) => void)` | -       | Event handler called when the popover is opened or closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| actionsRef           | `React.RefObject<Popover.Root.Actions \| null>`                            | -       | A ref to imperative actions. `unmount`: Manually unmounts the popover.&#xA;Call this after any externally controlled closing animation finishes.`close`: Closes the popover imperatively when called.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| 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               | `Popover.Handle<Payload>`                                                  | -       | A handle to associate the popover with a trigger.&#xA;If specified, allows external triggers to control the popover's open state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| modal                | `boolean \| 'trap-focus'`                                                  | `false` | Determines if the popover enters a modal state when open. `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.`false`: user interaction with the rest of the document is allowed.`'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. 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. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered&#xA;inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as&#xA;Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch&#xA;screen readers can escape the popup. |
+| onOpenChangeComplete | `((open: boolean) => void)`                                                | -       | Event handler called after any animations complete when the popover is opened or 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).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 
 ### Root.Props
 
@@ -2152,12 +2155,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                              |
-| :------------------ | :--- | :--------------------------------------- |
-| data-open           | -    | Present when the popup is open.          |
-| data-closed         | -    | Present when the popup is closed.        |
-| data-starting-style | -    | Present when the popup is animating in.  |
-| data-ending-style   | -    | Present when the popup is animating out. |
+| Attribute           | Type | Description                                 |
+| :------------------ | :--- | :------------------------------------------ |
+| data-open           | -    | Present when the popup is open.             |
+| data-closed         | -    | Present when the popup is closed.           |
+| data-starting-style | -    | Present when the popup begins animating in. |
+| data-ending-style   | -    | Present when the popup is animating out.    |
 
 ### Backdrop.Props
 
@@ -2249,8 +2252,8 @@ Renders a `<div>` element.
 | `--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` | \`\`     | The height of the popover's positioner.&#xA;It is important to set `height` to this value when using CSS to animate size changes. |
-| `--positioner-width`  | \`\`     | The width of the popover's positioner.&#xA;It is important to set `width` to this value when using CSS to animate size changes.   |
+| `--positioner-height` | `number` | The height of the popover'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 popover'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
@@ -2298,7 +2301,7 @@ Renders a `<div>` element.
 | data-align          | `'start' \| 'center' \| 'end'`                                             | Indicates how the popup is aligned relative to specified side.        |
 | data-instant        | `'click' \| 'dismiss' \| 'focus' \| '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 popup is animating in.                               |
+| data-starting-style | -                                                                          | Present when the popup begins animating in.                           |
 | data-ending-style   | -                                                                          | Present when the popup is animating out.                              |
 
 **Popup CSS Variables:**
@@ -2503,11 +2506,18 @@ type ReturnValue = Popover.Handle<Payload>;
 
 ### Handle
 
+Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+`Popover.Root`. Create one with `Popover.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 popover is currently open. |
+| Property | Type      | Modifiers | Description                                                                                     |
+| :------- | :-------- | :-------- | :---------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the popover is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -2516,7 +2526,8 @@ function open(triggerId: string): void;
 ```
 
 Opens the popover and associates it with the trigger with the given id.
-The trigger must be a Popover.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;
@@ -2524,6 +2535,8 @@ function close(): void;
 
 Closes the popover.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ## External Types
 
 ### PayloadChildRenderFunction
@@ -2614,6 +2627,8 @@ Maps `Canonical`: `Alias` — Use Canonical when its namespace is already import
 - `Popover.Viewport.Props`: `PopoverViewportProps`
 - `Popover.Viewport.State`: `PopoverViewportState`
 
+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'