@base-ui/react 1.6.0 → 1.8.0

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

@@ -182,20 +182,20 @@ Renders a `<div>` element.
 
 **Root Props:**
 
-| Prop                   | Type                                                                                                               | Default      | Description                                                                                                                                                                                                                                                                                                                                                   |
-| :--------------------- | :----------------------------------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| name                   | `string`                                                                                                           | -            | Identifies the field when a form is submitted.&#xA;Takes precedence over the `name` prop on the `<Field.Control>` component.                                                                                                                                                                                                                                  |
-| actionsRef             | `React.RefObject<Field.Root.Actions \| null>`                                                                      | -            | A ref to imperative actions. `validate`: Validates the field when called.                                                                                                                                                                                                                                                                                     |
-| dirty                  | `boolean`                                                                                                          | -            | Whether the field's value has been changed from its initial value.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                      |
-| touched                | `boolean`                                                                                                          | -            | Whether the field has been touched.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                                                     |
-| disabled               | `boolean`                                                                                                          | `false`      | Whether the component should ignore user interaction.&#xA;Takes precedence over the `disabled` prop on the `<Field.Control>` component.                                                                                                                                                                                                                       |
-| invalid                | `boolean`                                                                                                          | -            | Whether the field is invalid.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                                                           |
-| validate               | `((value: unknown, formValues: Form.Values) => string \| string[] \| Promise<string \| string[] \| null> \| null)` | -            | A function for custom validation. Return a string or an array of strings with&#xA;the error message(s) if the value is invalid, or `null` if the value is valid.&#xA;Asynchronous functions are supported, but they do not prevent form submission&#xA;when using `validationMode="onSubmit"`.                                                                |
-| validationMode         | `Form.ValidationMode`                                                                                              | `'onSubmit'` | Determines when the field should be validated.&#xA;This takes precedence over the `validationMode` prop on `<Form>`. `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission.`onBlur`: triggers validation when the control loses focus.`onChange`: triggers validation on every change to the control value. |
-| validationDebounceTime | `number`                                                                                                           | `0`          | How long to wait between `validate` callbacks if&#xA;`validationMode="onChange"` is used. Specified in milliseconds.                                                                                                                                                                                                                                          |
-| className              | `string \| ((state: Field.Root.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: Field.Root.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: Field.Root.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                                                                                                                                                                                                                                                                                                                                                   |
+| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| name                   | `string`                                                                                                                           | -            | Identifies the field when a form is submitted.&#xA;Takes precedence over the `name` prop on the `<Field.Control>` component.                                                                                                                                                                                                                                  |
+| actionsRef             | `React.RefObject<Field.Root.Actions \| null>`                                                                                      | -            | A ref to imperative actions. `validate`: Validates the field when called.                                                                                                                                                                                                                                                                                     |
+| dirty                  | `boolean`                                                                                                                          | -            | Whether the field's value has been changed from its initial value.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                      |
+| touched                | `boolean`                                                                                                                          | -            | Whether the field has been touched.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                                                     |
+| disabled               | `boolean`                                                                                                                          | `false`      | Whether the component should ignore user interaction.&#xA;Takes precedence over the `disabled` prop on the `<Field.Control>` component.                                                                                                                                                                                                                       |
+| invalid                | `boolean`                                                                                                                          | -            | Whether the field is invalid.&#xA;Useful when the field state is controlled by an external library.                                                                                                                                                                                                                                                           |
+| validate               | `((value: unknown, formValues: Form.Values) => string \| void \| string[] \| Promise<string \| void \| string[] \| null> \| null)` | -            | A function for custom validation. Return a string or an array of strings with&#xA;the error message(s) if the value is invalid. Returning nothing, `null`, an empty&#xA;string, or an empty array means the value is valid.&#xA;Asynchronous functions are supported, but they do not prevent form submission&#xA;when using `validationMode="onSubmit"`.     |
+| validationMode         | `Form.ValidationMode`                                                                                                              | `'onSubmit'` | Determines when the field should be validated.&#xA;This takes precedence over the `validationMode` prop on `<Form>`. `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission.`onBlur`: triggers validation when the control loses focus.`onChange`: triggers validation on every change to the control value. |
+| validationDebounceTime | `number`                                                                                                                           | `0`          | How long to wait between `validate` callbacks if&#xA;`validationMode="onChange"` is used. Specified in milliseconds.                                                                                                                                                                                                                                          |
+| className              | `string \| ((state: Field.Root.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: Field.Root.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: Field.Root.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.                                                                                                                                                                 |
 
 **Root Data Attributes:**
 
@@ -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
 

package/docs/react/components/form.md

@@ -374,7 +374,8 @@ export default function ActionStateForm() {
           Username
         </Field.Label>
         <Field.Control
-          type="username"
+          type="text"
+          autoComplete="username"
           required
           defaultValue="admin"
           placeholder="e.g. alice132"
@@ -598,7 +599,8 @@ export default function ActionStateForm() {
       <Field.Root name="username" className={styles.Field}>
         <Field.Label className={styles.Label}>Username</Field.Label>
         <Field.Control
-          type="username"
+          type="text"
+          autoComplete="username"
           required
           defaultValue="admin"
           placeholder="e.g. alice132"
@@ -968,15 +970,15 @@ Renders a `<form>` element.
 
 **Form Props:**
 
-| Prop           | Type                                                                                 | Default      | Description                                                                                                                                                                                                                                                                                                                                                |
-| :------------- | :----------------------------------------------------------------------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| errors         | `Errors`                                                                             | -            | Validation errors returned externally, typically after submission by a server or a form action.&#xA;This should be an object where keys correspond to the `name` attribute on `<Field.Root>`,&#xA;and values correspond to error(s) related to that field.                                                                                                 |
-| actionsRef     | `React.RefObject<Form.Actions \| null>`                                              | -            | A ref to imperative actions. `validate`: Validates all fields when called. Optionally pass a field name to validate a single field.                                                                                                                                                                                                                        |
-| onFormSubmit   | `((formValues: Record<string, any>, eventDetails: Form.SubmitEventDetails) => void)` | -            | Event handler called when the form is submitted.&#xA;`preventDefault()` is called on the native submit event when used.                                                                                                                                                                                                                                    |
-| validationMode | `Form.ValidationMode`                                                                | `'onSubmit'` | Determines when the form should be validated.&#xA;The `validationMode` prop on `<Field.Root>` takes precedence over this. `onSubmit` (default): validates the field when the form is submitted, afterwards fields will re-validate on change.`onBlur`: validates a field when it loses focus.`onChange`: validates the field on every change to its value. |
-| className      | `string \| ((state: Form.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: Form.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: Form.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                                                                                                                                                                                                                                                                                                                                                |
+| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| errors         | `Errors`                                                                                                                                            | -            | Validation errors returned externally, typically after submission by a server or a form action.&#xA;This should be an object where keys correspond to the `name` attribute on `<Field.Root>`,&#xA;and values correspond to error(s) related to that field.                                                                                                 |
+| actionsRef     | `React.RefObject<Form.Actions \| null>`                                                                                                             | -            | A ref to imperative actions. `validate`: Validates all fields when called. Optionally pass a field name to validate a single field.                                                                                                                                                                                                                        |
+| onFormSubmit   | `((formValues: Record<string, any>, eventDetails: Form.SubmitEventDetails) => void)`                                                                | -            | Event handler called when the form is submitted.&#xA;`preventDefault()` is called on the native submit event when used.                                                                                                                                                                                                                                    |
+| validationMode | `Form.ValidationMode`                                                                                                                               | `'onSubmit'` | Determines when the form should be validated.&#xA;The `validationMode` prop on `<Field.Root>` takes precedence over this. `onSubmit` (default): validates the field when the form is submitted, afterwards fields will re-validate on change.`onBlur`: validates a field when it loses focus.`onChange`: validates the field on every change to its value. |
+| className      | `string \| ((state: Form.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: Form.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.FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>, state: Form.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.                                                                                                                                                              |
 
 **`actionsRef` Prop Example:**