@base-ui/react 1.6.0 → 1.7.0

package/docs/react/components/dialog.md

@@ -1132,6 +1132,377 @@ export default function ExampleDialog() {
 }
 ```
 
+### Custom focus management
+
+You can control where the focus goes when the dialog opens and closes using the `initialFocus` and `finalFocus` props on the `<Dialog.Popup>` component.
+
+You can also set these props to `false` to prevent focus from moving when the dialog opens or closes, or to a function that returns the element to focus based on the interaction type.
+
+## Demo
+
+### Tailwind
+
+This example shows how to implement the component using Tailwind CSS.
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { Dialog } from '@base-ui/react/dialog';
+import { Field } from '@base-ui/react/field';
+import { Fieldset } from '@base-ui/react/fieldset';
+
+export default function ExampleDialog() {
+  const initialFocusRef = React.useRef<HTMLInputElement | null>(null);
+  const finalFocusRef = React.useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <div className="flex flex-wrap justify-center gap-3">
+      <Dialog.Root>
+        <Dialog.Trigger className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+          Open feedback
+        </Dialog.Trigger>
+        <Dialog.Portal>
+          <Dialog.Backdrop className="fixed inset-0 min-h-dvh bg-black opacity-20 transition-opacity duration-150 data-ending-style:opacity-0 data-starting-style:opacity-0 dark:opacity-50 supports-[-webkit-touch-callout:none]:absolute" />
+          <Dialog.Popup
+            initialFocus={initialFocusRef}
+            finalFocus={finalFocusRef}
+            className="fixed top-1/2 left-1/2 -mt-8 flex w-96 max-w-[calc(100vw-3rem)] -translate-x-1/2 -translate-y-1/2 flex-col gap-4 bg-white dark:bg-neutral-950 p-4 text-neutral-950 dark:text-white border border-neutral-950 dark:border-white shadow-[0.25rem_0.25rem_0] shadow-black/12 dark:shadow-none transition-[scale,opacity] duration-100 ease-out data-ending-style:scale-[0.98] data-ending-style:opacity-0 data-starting-style:scale-[0.98] data-starting-style:opacity-0"
+          >
+            <div className="flex flex-col gap-1">
+              <Dialog.Title className="text-base font-bold">Feedback form</Dialog.Title>
+              <Dialog.Description className="text-sm text-neutral-600 dark:text-neutral-400">
+                Your feedback means a lot to us.
+              </Dialog.Description>
+            </div>
+            <Fieldset.Root className="flex flex-col gap-3 border-0 p-0 m-0">
+              <Field.Root className="flex flex-col items-start gap-1">
+                <Field.Label className="text-sm font-normal">Full name</Field.Label>
+                <Field.Control
+                  placeholder="Enter your name"
+                  className="h-8 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
+                />
+              </Field.Root>
+              <Field.Root className="flex flex-col items-start gap-1">
+                <Field.Label className="text-sm font-normal">Feedback</Field.Label>
+                <Field.Control
+                  ref={initialFocusRef}
+                  required
+                  placeholder="Enter your feedback"
+                  className="h-8 w-full border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-2 text-sm any-pointer-coarse:text-base font-normal text-neutral-950 dark:text-white placeholder:text-neutral-500 dark:placeholder:text-neutral-400 focus:outline-2 focus:-outline-offset-1 focus:outline-neutral-950 dark:focus:outline-white"
+                />
+              </Field.Root>
+            </Fieldset.Root>
+            <div className="flex justify-end gap-3">
+              <Dialog.Close className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:not-data-disabled:bg-neutral-100 dark:hover:not-data-disabled:bg-neutral-800 active:not-data-disabled:bg-neutral-200 dark:active:not-data-disabled:bg-neutral-700 data-disabled:border-neutral-500 data-disabled:text-neutral-500 disabled:border-neutral-500 disabled:text-neutral-500 dark:data-disabled:border-neutral-400 dark:data-disabled:text-neutral-400 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white">
+                Close
+              </Dialog.Close>
+            </div>
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+      <button
+        ref={finalFocusRef}
+        type="button"
+        className="flex h-8 items-center justify-center gap-2 border border-neutral-950 dark:border-white bg-white dark:bg-neutral-950 px-3 text-sm leading-none whitespace-nowrap font-normal text-neutral-950 dark:text-white select-none hover:bg-neutral-100 dark:hover:bg-neutral-800 active:bg-neutral-200 dark:active:bg-neutral-700 disabled:border-neutral-500 disabled:text-neutral-500 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white"
+      >
+        Final focus
+      </button>
+    </div>
+  );
+}
+```
+
+### CSS Modules
+
+This example shows how to implement the component using CSS Modules.
+
+```css
+/* index.module.css */
+.Container {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.75rem;
+}
+
+.Button {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 2rem;
+  padding: 0 0.75rem;
+  margin: 0;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1;
+  white-space: nowrap;
+  color: oklch(14.5% 0 0deg);
+  -webkit-user-select: none;
+  user-select: none;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
+
+  @media (hover: hover) {
+    &:hover:not([data-disabled]) {
+      background-color: oklch(97% 0 0deg);
+
+      @media (prefers-color-scheme: dark) {
+        background-color: oklch(26.9% 0 0deg);
+      }
+    }
+  }
+
+  &:active:not([data-disabled]) {
+    background-color: oklch(92.2% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      background-color: oklch(37.1% 0 0deg);
+    }
+  }
+
+  &[data-disabled] {
+    color: oklch(55.6% 0 0deg);
+    border-color: oklch(55.6% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(70.8% 0 0deg);
+      border-color: oklch(70.8% 0 0deg);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+
+.Backdrop {
+  position: fixed;
+  min-height: 100dvh;
+  inset: 0;
+  background-color: black;
+  opacity: 0.2;
+  transition: opacity 150ms;
+
+  /* iOS 26+: Ensure the backdrop covers the entire visible viewport. */
+  @supports (-webkit-touch-callout: none) {
+    position: absolute;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    opacity: 0.5;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+  }
+}
+
+.Popup {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 24rem;
+  max-width: calc(100vw - 3rem);
+  margin-top: -2rem;
+  padding: 1rem;
+  border: 1px solid oklch(14.5% 0 0deg);
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+  box-shadow: 0.25rem 0.25rem 0 rgb(0 0 0 / 12%);
+  transition:
+    transform 100ms ease-out,
+    opacity 100ms ease-out;
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+    box-shadow: none;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: translate(-50%, -50%) scale(0.98);
+  }
+}
+
+.Intro,
+.Fieldset,
+.Field {
+  display: flex;
+  flex-direction: column;
+}
+
+.Intro {
+  gap: 0.25rem;
+}
+
+.Fieldset {
+  gap: 0.75rem;
+  padding: 0;
+  margin: 0;
+  border: 0;
+}
+
+.Field {
+  align-items: start;
+  gap: 0.25rem;
+}
+
+.Title {
+  margin: 0;
+  font-size: 1rem;
+  line-height: 1.5rem;
+  font-weight: 700;
+}
+
+.Description {
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  color: oklch(43.9% 0 0deg);
+
+  @media (prefers-color-scheme: dark) {
+    color: oklch(70.8% 0 0deg);
+  }
+}
+
+.Label {
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 400;
+}
+
+.Input {
+  box-sizing: border-box;
+  padding: 0 0.5rem;
+  margin: 0;
+  border-radius: 0;
+  border: 1px solid oklch(14.5% 0 0deg);
+  width: 100%;
+  height: 2rem;
+  font-family: inherit;
+  font-size: 0.875rem;
+  font-weight: 400;
+  background-color: white;
+  color: oklch(14.5% 0 0deg);
+
+  @media (any-pointer: coarse) {
+    font-size: 1rem;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    border: 1px solid white;
+    background-color: oklch(14.5% 0 0deg);
+    color: white;
+  }
+
+  &::placeholder {
+    color: oklch(55.6% 0 0deg);
+
+    @media (prefers-color-scheme: dark) {
+      color: oklch(70.8% 0 0deg);
+    }
+  }
+
+  &:focus {
+    outline: 2px solid oklch(14.5% 0 0deg);
+    outline-offset: -1px;
+
+    @media (prefers-color-scheme: dark) {
+      outline-color: white;
+    }
+  }
+}
+
+.Actions {
+  display: flex;
+  justify-content: end;
+  gap: 0.75rem;
+}
+```
+
+```tsx
+/* index.tsx */
+'use client';
+import * as React from 'react';
+import { Dialog } from '@base-ui/react/dialog';
+import { Field } from '@base-ui/react/field';
+import { Fieldset } from '@base-ui/react/fieldset';
+import styles from './index.module.css';
+
+export default function ExampleDialog() {
+  const initialFocusRef = React.useRef<HTMLInputElement | null>(null);
+  const finalFocusRef = React.useRef<HTMLButtonElement | null>(null);
+
+  return (
+    <div className={styles.Container}>
+      <Dialog.Root>
+        <Dialog.Trigger className={styles.Button}>Open feedback</Dialog.Trigger>
+        <Dialog.Portal>
+          <Dialog.Backdrop className={styles.Backdrop} />
+          <Dialog.Popup
+            className={styles.Popup}
+            initialFocus={initialFocusRef}
+            finalFocus={finalFocusRef}
+          >
+            <div className={styles.Intro}>
+              <Dialog.Title className={styles.Title}>Feedback form</Dialog.Title>
+              <Dialog.Description className={styles.Description}>
+                Your feedback means a lot to us.
+              </Dialog.Description>
+            </div>
+            <Fieldset.Root className={styles.Fieldset}>
+              <Field.Root className={styles.Field}>
+                <Field.Label className={styles.Label}>Full name</Field.Label>
+                <Field.Control placeholder="Enter your name" className={styles.Input} />
+              </Field.Root>
+              <Field.Root className={styles.Field}>
+                <Field.Label className={styles.Label}>Feedback</Field.Label>
+                <Field.Control
+                  ref={initialFocusRef}
+                  required
+                  placeholder="Enter your feedback"
+                  className={styles.Input}
+                />
+              </Field.Root>
+            </Fieldset.Root>
+            <div className={styles.Actions}>
+              <Dialog.Close className={styles.Button}>Close</Dialog.Close>
+            </div>
+          </Dialog.Popup>
+        </Dialog.Portal>
+      </Dialog.Root>
+      <button ref={finalFocusRef} type="button" className={styles.Button}>
+        Final focus
+      </button>
+    </div>
+  );
+}
+```
+
 ### Outside scroll dialog
 
 The dialog can be made scrollable by using `<Dialog.Viewport>` as an outer scrollable container for `<Dialog.Popup>` while the popup can extend past the bottom edge. The scrollable area uses the [Scroll Area component](/react/components/scroll-area.md) to provide custom scrollbars.
@@ -2726,6 +3097,9 @@ For simple, one-off interactions, place the `<Dialog.Trigger>` inside `<Dialog.R
 However, if defining the dialog's content next to its trigger is not practical, you can use a detached trigger.
 This involves placing the `<Dialog.Trigger>` outside of `<Dialog.Root>` and linking them with a `handle` created by the `Dialog.createHandle()` function.
 
+The imperative methods on the handle, such as `open()` and `openWithPayload()`, require a `<Dialog.Root>` using the same handle to be mounted.
+Calls made while no root is attached to the handle — before one mounts, or after it unmounts — are ignored. Each time a root mounts, it starts from fresh state: a call made while no root was attached is not replayed, and no open state carries over from a previous mount.
+
 ```jsx title="Detached triggers"
 const demoDialog = Dialog.createHandle();
 
@@ -3547,12 +3921,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                               |
-| :------------------ | :--- | :---------------------------------------- |
-| data-open           | -    | Present when the dialog is open.          |
-| data-closed         | -    | Present when the dialog is closed.        |
-| data-starting-style | -    | Present when the dialog is animating in.  |
-| data-ending-style   | -    | Present when the dialog is animating out. |
+| Attribute           | Type | Description                                  |
+| :------------------ | :--- | :------------------------------------------- |
+| data-open           | -    | Present when the dialog is open.             |
+| data-closed         | -    | Present when the dialog is closed.           |
+| data-starting-style | -    | Present when the dialog begins animating in. |
+| data-ending-style   | -    | Present when the dialog is animating out.    |
 
 ### Backdrop.Props
 
@@ -3592,7 +3966,7 @@ Renders a `<div>` element.
 | data-closed             | -    | Present when the dialog is closed.                               |
 | data-nested             | -    | Present when the dialog is nested within another dialog.         |
 | data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
-| data-starting-style     | -    | Present when the dialog is animating in.                         |
+| data-starting-style     | -    | Present when the dialog begins animating in.                     |
 | data-ending-style       | -    | Present when the dialog is animating out.                        |
 
 **Popup CSS Variables:**
@@ -3720,7 +4094,7 @@ Renders a `<div>` element.
 | data-closed             | -    | Present when the dialog is closed.                               |
 | data-nested             | -    | Present when the dialog is nested within another dialog.         |
 | data-nested-dialog-open | -    | Present when the dialog has other open dialogs nested within it. |
-| data-starting-style     | -    | Present when the dialog is animating in.                         |
+| data-starting-style     | -    | Present when the dialog begins animating in.                     |
 | data-ending-style       | -    | Present when the dialog is animating out.                        |
 
 ### Viewport.Props
@@ -3754,19 +4128,18 @@ type ReturnValue = Dialog.Handle<Payload>;
 
 ### Handle
 
-A handle to control a Dialog imperatively and to associate detached triggers with it.
-
-**Constructor Parameters:**
+Controls a Dialog imperatively and associates detached `Dialog.Trigger` components with a
+`Dialog.Root`. Create one with `Dialog.createHandle()` and pass it to the `handle` prop of the
+root and of any triggers rendered outside of it.
 
-| Parameter | Type                   | Default | Description |
-| :-------- | :--------------------- | :------ | :---------- |
-| store?    | `DialogStore<Payload>` | -       | -           |
+The imperative methods take effect only while a root using this handle is mounted; calls made
+before a root attaches (or after it unmounts) are ignored.
 
 **Properties:**
 
-| Property | Type      | Modifiers | Description                                     |
-| :------- | :-------- | :-------- | :---------------------------------------------- |
-| isOpen   | `boolean` | readonly  | Indicates whether the dialog is currently open. |
+| Property | Type      | Modifiers | Description                                                                                    |
+| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the dialog is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -3774,8 +4147,7 @@ A handle to control a Dialog imperatively and to associate detached triggers wit
 function open(triggerId: string | null): void;
 ```
 
-Opens the dialog and associates it with the trigger with the given id.
-The trigger, if provided, must be a matching Trigger component with this handle passed as a prop.
+Opens the dialog, optionally associating it with a trigger.
 
 This method should only be called in an event handler or an effect (not during rendering).
 
@@ -3783,8 +4155,9 @@ This method should only be called in an event handler or an effect (not during r
 function openWithPayload(payload: Payload): void;
 ```
 
-Opens the dialog and sets the payload.
-Does not associate the dialog with any trigger.
+Opens the dialog with the given payload, without associating it with any trigger.
+
+This method should only be called in an event handler or an effect (not during rendering).
 
 ```typescript
 function close(): void;
@@ -3792,6 +4165,8 @@ function close(): void;
 
 Closes the dialog.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ## External Types
 
 ### InteractionType

package/docs/react/components/drawer.md

@@ -4981,6 +4981,9 @@ A drawer can be controlled by a trigger located either inside or outside the `<D
 
 However, if defining the drawer's content next to its trigger is not practical, you can use a detached trigger. This involves placing the `<Drawer.Trigger>` outside of `<Drawer.Root>` and linking them with a `handle` created by the `Drawer.createHandle()` function.
 
+The imperative methods on the handle, such as `open()` and `openWithPayload()`, require a `<Drawer.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 demoDrawer = Drawer.createHandle();
 
@@ -5291,7 +5294,7 @@ Renders a `<button>` element.
 
 | Prop         | Type                                                                                         | Default | Description                                                                                                                                                                                          |
 | :----------- | :------------------------------------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| handle       | `DrawerHandle<Payload>`                                                                      | -       | A handle to associate the trigger with a drawer.&#xA;Can be created with the Drawer.createHandle() method.                                                                                           |
+| handle       | `Drawer.Handle<Payload>`                                                                     | -       | A handle to associate the trigger with a drawer.&#xA;Can be created with the Drawer.createHandle() method.                                                                                           |
 | nativeButton | `boolean`                                                                                    | `true`  | Whether the component renders a native `<button>` element when replacing it&#xA;via the `render` prop.&#xA;Set to `false` if the rendered element is not a button (for example, `<div>`).            |
 | payload      | `Payload`                                                                                    | -       | A payload to pass to the drawer when it is opened.                                                                                                                                                   |
 | id           | `string`                                                                                     | -       | ID of the trigger. In addition to being forwarded to the rendered element,&#xA;it is also used to specify the active trigger for drawers in controlled mode (with the Drawer.Root `triggerId` prop). |
@@ -5356,12 +5359,12 @@ Renders a `<div>` element.
 
 **Backdrop Data Attributes:**
 
-| Attribute           | Type | Description                               |
-| :------------------ | :--- | :---------------------------------------- |
-| data-open           | -    | Present when the drawer is open.          |
-| data-closed         | -    | Present when the drawer is closed.        |
-| data-starting-style | -    | Present when the drawer is animating in.  |
-| data-ending-style   | -    | Present when the drawer is animating out. |
+| Attribute           | Type | Description                                  |
+| :------------------ | :--- | :------------------------------------------- |
+| data-open           | -    | Present when the drawer is open.             |
+| data-closed         | -    | Present when the drawer is closed.           |
+| data-starting-style | -    | Present when the drawer begins animating in. |
+| data-ending-style   | -    | Present when the drawer is animating out.    |
 
 **Backdrop CSS Variables:**
 
@@ -5411,7 +5414,7 @@ Renders a `<div>` element.
 | data-swipe-direction       | `'up' \| 'down' \| 'left' \| 'right'` | Indicates the swipe direction.                                       |
 | data-swipe-dismiss         | -                                     | Present when the drawer is dismissed by swiping.                     |
 | data-swiping               | -                                     | Present when the drawer is being swiped.                             |
-| data-starting-style        | -                                     | Present when the drawer is animating in.                             |
+| data-starting-style        | -                                     | Present when the drawer begins animating in.                         |
 | data-ending-style          | -                                     | Present when the drawer is animating out.                            |
 
 **Popup CSS Variables:**
@@ -5569,7 +5572,7 @@ Renders a `<div>` element.
 | data-open           | -    | Present when the drawer is open.                         |
 | data-closed         | -    | Present when the drawer is closed.                       |
 | data-nested         | -    | Present when the drawer is nested within another drawer. |
-| data-starting-style | -    | Present when the drawer is animating in.                 |
+| data-starting-style | -    | Present when the drawer begins animating in.             |
 | data-ending-style   | -    | Present when the drawer is animating out.                |
 
 **Viewport CSS Variables:**
@@ -5599,7 +5602,7 @@ type DrawerViewportState = {
 
 ### createHandle
 
-Creates a new handle to connect a Dialog.Root with detached Dialog.Trigger components.
+Creates a new handle to connect a Drawer.Root with detached Drawer.Trigger components.
 
 **Return Value:**
 
@@ -5609,19 +5612,18 @@ type ReturnValue = Drawer.Handle<Payload>;
 
 ### Handle
 
-A handle to control a Dialog imperatively and to associate detached triggers with it.
-
-**Constructor Parameters:**
+Controls a Drawer imperatively and associates detached `Drawer.Trigger` components with a
+`Drawer.Root`. Create one with `Drawer.createHandle()` and pass it to the `handle` prop of the
+root and of any triggers rendered outside of it.
 
-| Parameter | Type                   | Default | Description |
-| :-------- | :--------------------- | :------ | :---------- |
-| store?    | `DialogStore<Payload>` | -       | -           |
+The imperative methods take effect only while a root using this handle is mounted; calls made
+before a root attaches (or after it unmounts) are ignored.
 
 **Properties:**
 
-| Property | Type      | Modifiers | Description                                     |
-| :------- | :-------- | :-------- | :---------------------------------------------- |
-| isOpen   | `boolean` | readonly  | Indicates whether the dialog is currently open. |
+| Property | Type      | Modifiers | Description                                                                                    |
+| :------- | :-------- | :-------- | :--------------------------------------------------------------------------------------------- |
+| isOpen   | `boolean` | readonly  | Whether the dialog is currently open. Returns `false` while no root is attached to the handle. |
 
 **Methods:**
 
@@ -5629,8 +5631,7 @@ A handle to control a Dialog imperatively and to associate detached triggers wit
 function open(triggerId: string | null): void;
 ```
 
-Opens the dialog and associates it with the trigger with the given id.
-The trigger, if provided, must be a matching Trigger component with this handle passed as a prop.
+Opens the dialog, optionally associating it with a trigger.
 
 This method should only be called in an event handler or an effect (not during rendering).
 
@@ -5638,8 +5639,9 @@ This method should only be called in an event handler or an effect (not during r
 function openWithPayload(payload: Payload): void;
 ```
 
-Opens the dialog and sets the payload.
-Does not associate the dialog with any trigger.
+Opens the dialog with the given payload, without associating it with any trigger.
+
+This method should only be called in an event handler or an effect (not during rendering).
 
 ```typescript
 function close(): void;
@@ -5647,6 +5649,8 @@ function close(): void;
 
 Closes the dialog.
 
+This method should only be called in an event handler or an effect (not during rendering).
+
 ### Indent
 
 A wrapper element intended to contain your app's main UI.

package/docs/react/components/field.md

@@ -481,17 +481,17 @@ Renders a `<div>` element.
 
 **Error Data Attributes:**
 
-| Attribute           | Type | Description                                      |
-| :------------------ | :--- | :----------------------------------------------- |
-| data-disabled       | -    | Present when the field is disabled.              |
-| data-valid          | -    | Present when the field is in a valid state.      |
-| data-invalid        | -    | Present when the field is in an invalid state.   |
-| data-dirty          | -    | Present when the field's value has changed.      |
-| data-touched        | -    | Present when the field has been touched.         |
-| data-filled         | -    | Present when the field is filled.                |
-| data-focused        | -    | Present when the field control is focused.       |
-| data-starting-style | -    | Present when the error message is animating in.  |
-| data-ending-style   | -    | Present when the error message is animating out. |
+| Attribute           | Type | Description                                         |
+| :------------------ | :--- | :-------------------------------------------------- |
+| data-disabled       | -    | Present when the field is disabled.                 |
+| data-valid          | -    | Present when the field is in a valid state.         |
+| data-invalid        | -    | Present when the field is in an invalid state.      |
+| data-dirty          | -    | Present when the field's value has changed.         |
+| data-touched        | -    | Present when the field has been touched.            |
+| data-filled         | -    | Present when the field is filled.                   |
+| data-focused        | -    | Present when the field control is focused.          |
+| data-starting-style | -    | Present when the error message begins animating in. |
+| data-ending-style   | -    | Present when the error message is animating out.    |
 
 ### Error.Props