@base-ui/react 1.0.0 → 1.2.0

package/esm/drawer/viewport/DrawerViewportContext.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+interface DrawerViewportContextValue {
+  swiping: boolean;
+  getDragStyles: () => React.CSSProperties;
+  swipeStrength: number | null;
+  setSwipeDismissed: (dismissed: boolean) => void;
+}
+export declare const DrawerViewportContext: React.Context<DrawerViewportContextValue | null>;
+export declare function useDrawerViewportContext(optional?: false): DrawerViewportContextValue;
+export declare function useDrawerViewportContext(optional: true): DrawerViewportContextValue | null;
+export {};

package/esm/drawer/viewport/DrawerViewportContext.js

@@ -0,0 +1,13 @@
+'use client';
+
+import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
+import * as React from 'react';
+export const DrawerViewportContext = /*#__PURE__*/React.createContext(null);
+if (process.env.NODE_ENV !== "production") DrawerViewportContext.displayName = "DrawerViewportContext";
+export function useDrawerViewportContext(optional) {
+  const context = React.useContext(DrawerViewportContext);
+  if (optional === false && context === null) {
+    throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: DrawerViewportContext is missing. Drawer parts must be placed within <Drawer.Viewport>.' : _formatErrorMessage(92));
+  }
+  return context;
+}

package/esm/field/control/FieldControl.d.ts

@@ -13,14 +13,14 @@ import type { BaseUIChangeEventDetails } from "../../utils/createBaseUIEventDeta
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldControl: React.ForwardRefExoticComponent<FieldControlProps & React.RefAttributes<HTMLInputElement>>;
+export declare const FieldControl: React.ForwardRefExoticComponent<Omit<FieldControlProps, "ref"> & React.RefAttributes<HTMLElement>>;
 export type FieldControlState = FieldRoot.State;
 export interface FieldControlProps extends BaseUIComponentProps<'input', FieldControl.State> {
   /**
    * Callback fired when the `value` changes. Use when controlled.
    */
-  onValueChange?: (value: string, eventDetails: FieldControl.ChangeEventDetails) => void;
-  defaultValue?: React.ComponentProps<'input'>['defaultValue'];
+  onValueChange?: ((value: string, eventDetails: FieldControl.ChangeEventDetails) => void) | undefined;
+  defaultValue?: React.ComponentProps<'input'>['defaultValue'] | undefined;
 }
 export type FieldControlChangeEventReason = typeof REASONS.none;
 export type FieldControlChangeEventDetails = BaseUIChangeEventDetails<FieldControl.ChangeEventReason>;

package/esm/field/control/FieldControl.js

@@ -1,9 +1,9 @@
 'use client';
 
 import * as React from 'react';
-import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { ownerDocument } from '@base-ui/utils/owner';
 import { useFieldRootContext } from "../root/FieldRootContext.js";
 import { useLabelableContext } from "../../labelable-provider/LabelableContext.js";
 import { useLabelableId } from "../../labelable-provider/useLabelableId.js";
@@ -12,6 +12,8 @@ import { useRenderElement } from "../../utils/useRenderElement.js";
 import { useField } from "../useField.js";
 import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
+import { activeElement } from "../../floating-ui-react/utils.js";
+
 /**
  * The form control to label and validate.
  * Renders an `<input>` element.
@@ -32,20 +34,13 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
     disabled: disabledProp = false,
     onValueChange,
     defaultValue,
+    autoFocus = false,
     ...elementProps
   } = componentProps;
   const {
     state: fieldState,
     name: fieldName,
-    disabled: fieldDisabled
-  } = useFieldRootContext();
-  const disabled = fieldDisabled || disabledProp;
-  const name = fieldName ?? nameProp;
-  const state = React.useMemo(() => ({
-    ...fieldState,
-    disabled
-  }), [fieldState, disabled]);
-  const {
+    disabled: fieldDisabled,
     setTouched,
     setDirty,
     validityData,
@@ -54,6 +49,12 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
     validationMode,
     validation
   } = useFieldRootContext();
+  const disabled = fieldDisabled || disabledProp;
+  const name = fieldName ?? nameProp;
+  const state = {
+    ...fieldState,
+    disabled
+  };
   const {
     labelId
   } = useLabelableContext();
@@ -68,20 +69,20 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
       setFilled(false);
     }
   }, [validation.inputRef, setFilled, valueProp]);
-  const [value, setValueUnwrapped] = useControlled({
+  const inputRef = React.useRef(null);
+  useIsoLayoutEffect(() => {
+    if (autoFocus && inputRef.current === activeElement(ownerDocument(inputRef.current))) {
+      setFocused(true);
+    }
+  }, [autoFocus, setFocused]);
+  const [valueUnwrapped] = useControlled({
     controlled: valueProp,
     default: defaultValue,
     name: 'FieldControl',
     state: 'value'
   });
   const isControlled = valueProp !== undefined;
-  const setValue = useStableCallback((nextValue, eventDetails) => {
-    onValueChange?.(nextValue, eventDetails);
-    if (eventDetails.isCanceled) {
-      return;
-    }
-    setValueUnwrapped(nextValue);
-  });
+  const value = isControlled ? valueUnwrapped : undefined;
   useField({
     id,
     name,
@@ -91,7 +92,7 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
     controlRef: validation.inputRef
   });
   const element = useRenderElement('input', componentProps, {
-    ref: forwardedRef,
+    ref: [forwardedRef, inputRef],
     state,
     props: [{
       id,
@@ -99,6 +100,7 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
       name,
       ref: validation.inputRef,
       'aria-labelledby': labelId,
+      autoFocus,
       ...(isControlled ? {
         value
       } : {
@@ -106,7 +108,7 @@ export const FieldControl = /*#__PURE__*/React.forwardRef(function FieldControl(
       }),
       onChange(event) {
         const inputValue = event.currentTarget.value;
-        setValue(inputValue, createChangeEventDetails(REASONS.none, event.nativeEvent));
+        onValueChange?.(inputValue, createChangeEventDetails(REASONS.none, event.nativeEvent));
         setDirty(inputValue !== validityData.initialValue);
         setFilled(inputValue !== '');
       },

package/esm/field/description/FieldDescription.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldDescription: React.ForwardRefExoticComponent<FieldDescriptionProps & React.RefAttributes<HTMLParagraphElement>>;
+export declare const FieldDescription: React.ForwardRefExoticComponent<Omit<FieldDescriptionProps, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
 export type FieldDescriptionState = FieldRoot.State;
 export interface FieldDescriptionProps extends BaseUIComponentProps<'p', FieldDescription.State> {}
 export declare namespace FieldDescription {

package/esm/field/error/FieldError.d.ts

@@ -1,14 +1,17 @@
 import * as React from 'react';
 import { FieldRoot } from "../root/FieldRoot.js";
 import type { BaseUIComponentProps } from "../../utils/types.js";
+import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
 /**
  * An error message displayed if the field control fails validation.
  * Renders a `<div>` element.
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldError: React.ForwardRefExoticComponent<FieldErrorProps & React.RefAttributes<HTMLDivElement>>;
-export type FieldErrorState = FieldRoot.State;
+export declare const FieldError: React.ForwardRefExoticComponent<Omit<FieldErrorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface FieldErrorState extends FieldRoot.State {
+  transitionStatus: TransitionStatus;
+}
 export interface FieldErrorProps extends BaseUIComponentProps<'div', FieldError.State> {
   /**
    * Determines whether to show the error message according to the field’s
@@ -16,7 +19,7 @@ export interface FieldErrorProps extends BaseUIComponentProps<'div', FieldError.
    * Specifying `true` will always show the error message, and lets external libraries
    * control the visibility.
    */
-  match?: boolean | keyof ValidityState;
+  match?: (boolean | keyof ValidityState) | undefined;
 }
 export declare namespace FieldError {
   type State = FieldErrorState;

package/esm/field/error/FieldError.js

@@ -8,6 +8,14 @@ import { fieldValidityMapping } from "../utils/constants.js";
 import { useFormContext } from "../../form/FormContext.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
 import { useBaseUiId } from "../../utils/useBaseUiId.js";
+import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
+import { transitionStatusMapping } from "../../utils/stateAttributesMapping.js";
+import { useTransitionStatus } from "../../utils/useTransitionStatus.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const stateAttributesMapping = {
+  ...fieldValidityMapping,
+  ...transitionStatusMapping
+};
 
 /**
  * An error message displayed if the field control fails validation.
@@ -26,7 +34,7 @@ export const FieldError = /*#__PURE__*/React.forwardRef(function FieldError(comp
   const id = useBaseUiId(idProp);
   const {
     validityData,
-    state,
+    state: fieldState,
     name
   } = useFieldRootContext(false);
   const {
@@ -44,6 +52,11 @@ export const FieldError = /*#__PURE__*/React.forwardRef(function FieldError(comp
   } else {
     rendered = validityData.state.valid === false;
   }
+  const {
+    mounted,
+    transitionStatus,
+    setMounted
+  } = useTransitionStatus(rendered);
   useIsoLayoutEffect(() => {
     if (!rendered || !id) {
       return undefined;
@@ -53,18 +66,48 @@ export const FieldError = /*#__PURE__*/React.forwardRef(function FieldError(comp
       setMessageIds(v => v.filter(item => item !== id));
     };
   }, [rendered, id, setMessageIds]);
+  const errorRef = React.useRef(null);
+  const [lastRenderedMessage, setLastRenderedMessage] = React.useState(null);
+  const [lastRenderedMessageKey, setLastRenderedMessageKey] = React.useState(null);
+  const errorMessage = formError || (validityData.errors.length > 1 ? /*#__PURE__*/_jsx("ul", {
+    children: validityData.errors.map(message => /*#__PURE__*/_jsx("li", {
+      children: message
+    }, message))
+  }) : validityData.error);
+  let errorKey = validityData.error;
+  if (formError != null) {
+    errorKey = Array.isArray(formError) ? JSON.stringify(formError) : formError;
+  } else if (validityData.errors.length > 1) {
+    errorKey = JSON.stringify(validityData.errors);
+  }
+  if (rendered && errorKey !== lastRenderedMessageKey) {
+    setLastRenderedMessageKey(errorKey);
+    setLastRenderedMessage(errorMessage);
+  }
+  useOpenChangeComplete({
+    open: rendered,
+    ref: errorRef,
+    onComplete() {
+      if (!rendered) {
+        setMounted(false);
+      }
+    }
+  });
+  const state = {
+    ...fieldState,
+    transitionStatus
+  };
   const element = useRenderElement('div', componentProps, {
-    ref: forwardedRef,
+    ref: [forwardedRef, errorRef],
     state,
     props: [{
       id,
-      children: formError || (validityData.errors.length > 1 ? /*#__PURE__*/React.createElement('ul', {}, validityData.errors.map(message => /*#__PURE__*/React.createElement('li', {
-        key: message
-      }, message))) : validityData.error)
+      children: rendered ? errorMessage : lastRenderedMessage
     }, elementProps],
-    stateAttributesMapping: fieldValidityMapping
+    stateAttributesMapping,
+    enabled: mounted
   });
-  if (!rendered) {
+  if (!mounted) {
     return null;
   }
   return element;

package/esm/field/index.d.ts

@@ -4,4 +4,5 @@ export type * from "./label/FieldLabel.js";
 export type * from "./description/FieldDescription.js";
 export type * from "./error/FieldError.js";
 export type * from "./control/FieldControl.js";
-export type * from "./validity/FieldValidity.js";
+export type * from "./validity/FieldValidity.js";
+export type * from "./item/FieldItem.js";

package/esm/field/item/FieldItem.d.ts

@@ -7,14 +7,14 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldItem: React.ForwardRefExoticComponent<FieldItemProps & React.RefAttributes<HTMLDivElement>>;
+export declare const FieldItem: React.ForwardRefExoticComponent<Omit<FieldItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface FieldItemProps extends BaseUIComponentProps<'div', FieldItem.State> {
   /**
    * Whether the wrapped control should ignore user interaction.
    * The `disabled` prop on `<Field.Root>` takes precedence over this.
    * @default false
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
 }
 export declare namespace FieldItem {
   type State = FieldRoot.State;

package/esm/field/item/FieldItemContext.js

@@ -1,3 +1,5 @@
+'use client';
+
 import * as React from 'react';
 export const FieldItemContext = /*#__PURE__*/React.createContext({
   disabled: false

package/esm/field/label/FieldLabel.d.ts

@@ -7,9 +7,18 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps & React.RefAttributes<any>>;
+export declare const FieldLabel: React.ForwardRefExoticComponent<Omit<FieldLabelProps, "ref"> & React.RefAttributes<HTMLElement>>;
 export type FieldLabelState = FieldRoot.State;
-export interface FieldLabelProps extends BaseUIComponentProps<'label', FieldLabel.State> {}
+export interface FieldLabelProps extends BaseUIComponentProps<'label', FieldLabel.State> {
+  /**
+   * Whether the component renders a native `<label>` element when replacing it via the `render` prop.
+   * Set to `false` if the rendered element is not a label (e.g. `<div>`).
+   *
+   * This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button.
+   * @default true
+   */
+  nativeLabel?: boolean | undefined;
+}
 export declare namespace FieldLabel {
   type State = FieldLabelState;
   type Props = FieldLabelProps;

package/esm/field/label/FieldLabel.js

@@ -1,7 +1,12 @@
 'use client';
 
 import * as React from 'react';
+import { error } from '@base-ui/utils/error';
+import { SafeReact } from '@base-ui/utils/safeReact';
+import { isHTMLElement } from '@floating-ui/utils/dom';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { ownerDocument } from '@base-ui/utils/owner';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { getTarget } from "../../floating-ui-react/utils.js";
 import { useFieldRootContext } from "../root/FieldRootContext.js";
 import { useLabelableContext } from "../../labelable-provider/LabelableContext.js";
@@ -20,6 +25,7 @@ export const FieldLabel = /*#__PURE__*/React.forwardRef(function FieldLabel(comp
     render,
     className,
     id: idProp,
+    nativeLabel = true,
     ...elementProps
   } = componentProps;
   const fieldRootContext = useFieldRootContext(false);
@@ -30,6 +36,49 @@ export const FieldLabel = /*#__PURE__*/React.forwardRef(function FieldLabel(comp
   } = useLabelableContext();
   const id = useBaseUiId(idProp);
   const labelRef = React.useRef(null);
+  const handleInteraction = useStableCallback(event => {
+    const target = getTarget(event.nativeEvent);
+    if (target?.closest('button,input,select,textarea')) {
+      return;
+    }
+
+    // Prevent text selection when double clicking label.
+    if (!event.defaultPrevented && event.detail > 1) {
+      event.preventDefault();
+    }
+    if (nativeLabel || !controlId) {
+      return;
+    }
+    const controlElement = ownerDocument(event.currentTarget).getElementById(controlId);
+    if (isHTMLElement(controlElement)) {
+      controlElement.focus({
+        // Available from Chrome 144+ (January 2026).
+        // Safari and Firefox already support it.
+        // @ts-expect-error not available in types yet
+        focusVisible: true
+      });
+    }
+  });
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (!labelRef.current) {
+        return;
+      }
+      const isLabelTag = labelRef.current.tagName === 'LABEL';
+      if (nativeLabel) {
+        if (!isLabelTag) {
+          const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+          const message = '<Field.Label> expected a <label> element because the `nativeLabel` prop is true. ' + 'Rendering a non-<label> disables native label association, so `htmlFor` will not ' + 'work. Use a real <label> in the `render` prop, or set `nativeLabel` to `false`.';
+          error(`${message}${ownerStackMessage}`);
+        }
+      } else if (isLabelTag) {
+        const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+        const message = '<Field.Label> expected a non-<label> element because the `nativeLabel` prop is false. ' + 'Rendering a <label> assumes native label behavior while Base UI treats it as ' + 'non-native, which can cause unexpected pointer behavior. Use a non-<label> in the ' + '`render` prop, or set `nativeLabel` to `true`.';
+        error(`${message}${ownerStackMessage}`);
+      }
+    }, [nativeLabel]);
+  }
   useIsoLayoutEffect(() => {
     if (id) {
       setLabelId(id);
@@ -42,18 +91,14 @@ export const FieldLabel = /*#__PURE__*/React.forwardRef(function FieldLabel(comp
     ref: [forwardedRef, labelRef],
     state: fieldRootContext.state,
     props: [{
-      id: labelId,
+      id: labelId
+    }, nativeLabel ? {
       htmlFor: controlId ?? undefined,
-      onMouseDown(event) {
-        const target = getTarget(event.nativeEvent);
-        if (target?.closest('button,input,select,textarea')) {
-          return;
-        }
-
-        // Prevent text selection when double clicking label.
-        if (!event.defaultPrevented && event.detail > 1) {
-          event.preventDefault();
-        }
+      onMouseDown: handleInteraction
+    } : {
+      onClick: handleInteraction,
+      onPointerDown(event) {
+        event.preventDefault();
       }
     }, elementProps],
     stateAttributesMapping: fieldValidityMapping

package/esm/field/root/FieldRoot.d.ts

@@ -7,7 +7,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
-export declare const FieldRoot: React.ForwardRefExoticComponent<FieldRootProps & React.RefAttributes<HTMLDivElement>>;
+export declare const FieldRoot: React.ForwardRefExoticComponent<Omit<FieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface FieldValidityData {
   state: {
     badInput: boolean;
@@ -27,6 +27,9 @@ export interface FieldValidityData {
   value: unknown;
   initialValue: unknown;
 }
+export interface FieldRootActions {
+  validate: () => void;
+}
 export interface FieldRootState {
   /** Whether the component should ignore user interaction. */
   disabled: boolean;
@@ -42,19 +45,19 @@ export interface FieldRootProps extends BaseUIComponentProps<'div', FieldRoot.St
    * Takes precedence over the `disabled` prop on the `<Field.Control>` component.
    * @default false
    */
-  disabled?: boolean;
+  disabled?: boolean | undefined;
   /**
    * Identifies the field when a form is submitted.
    * Takes precedence over the `name` prop on the `<Field.Control>` component.
    */
-  name?: string;
+  name?: string | undefined;
   /**
    * A function for custom validation. Return a string or an array of strings with
    * the error message(s) if the value is invalid, or `null` if the value is valid.
    * Asynchronous functions are supported, but they do not prevent form submission
    * when using `validationMode="onSubmit"`.
    */
-  validate?: (value: unknown, formValues: Form.Values) => string | string[] | null | Promise<string | string[] | null>;
+  validate?: ((value: unknown, formValues: Form.Values) => string | string[] | null | Promise<string | string[] | null>) | undefined;
   /**
    * Determines when the field should be validated.
    * This takes precedence over the `validationMode` prop on `<Form>`.
@@ -65,30 +68,36 @@ export interface FieldRootProps extends BaseUIComponentProps<'div', FieldRoot.St
    *
    * @default 'onSubmit'
    */
-  validationMode?: Form.ValidationMode;
+  validationMode?: Form.ValidationMode | undefined;
   /**
    * How long to wait between `validate` callbacks if
    * `validationMode="onChange"` is used. Specified in milliseconds.
    * @default 0
    */
-  validationDebounceTime?: number;
+  validationDebounceTime?: number | undefined;
   /**
    * Whether the field is invalid.
    * Useful when the field state is controlled by an external library.
    */
-  invalid?: boolean;
+  invalid?: boolean | undefined;
   /**
    * Whether the field's value has been changed from its initial value.
    * Useful when the field state is controlled by an external library.
    */
-  dirty?: boolean;
+  dirty?: boolean | undefined;
   /**
    * Whether the field has been touched.
    * Useful when the field state is controlled by an external library.
    */
-  touched?: boolean;
+  touched?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   * - `validate`: Validates the field when called.
+   */
+  actionsRef?: React.RefObject<FieldRoot.Actions | null> | undefined;
 }
 export declare namespace FieldRoot {
   type State = FieldRootState;
   type Props = FieldRootProps;
+  type Actions = FieldRootActions;
 }

package/esm/field/root/FieldRoot.js

@@ -31,6 +31,7 @@ const FieldRootInner = /*#__PURE__*/React.forwardRef(function FieldRootInner(com
     invalid: invalidProp,
     dirty: dirtyProp,
     touched: touchedProp,
+    actionsRef,
     ...elementProps
   } = componentProps;
   const {
@@ -89,6 +90,13 @@ const FieldRootInner = /*#__PURE__*/React.forwardRef(function FieldRootInner(com
     name,
     shouldValidateOnChange
   });
+  const handleImperativeValidate = React.useCallback(() => {
+    markedDirtyRef.current = true;
+    validation.commit(validityData.value);
+  }, [validation, validityData]);
+  React.useImperativeHandle(actionsRef, () => ({
+    validate: handleImperativeValidate
+  }), [handleImperativeValidate]);
   const contextValue = React.useMemo(() => ({
     invalid,
     name,

package/esm/field/root/FieldRootContext.d.ts

@@ -21,7 +21,7 @@ export interface FieldRootContext {
   validationDebounceTime: number;
   shouldValidateOnChange: () => boolean;
   state: FieldRoot.State;
-  markedDirtyRef: React.MutableRefObject<boolean>;
+  markedDirtyRef: React.RefObject<boolean>;
   validation: UseFieldValidationReturnValue;
 }
 export declare const FieldRootContext: React.Context<FieldRootContext>;

package/esm/field/useField.d.ts

@@ -1,6 +1,6 @@
 export declare function useField(params: UseFieldParameters): void;
 export interface UseFieldParameters {
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   value: unknown;
   getValue?: (() => unknown) | undefined;
   id: string | undefined;

package/esm/field/useField.js

@@ -1,3 +1,5 @@
+'use client';
+
 import * as ReactDOM from 'react-dom';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
@@ -47,14 +49,18 @@ export function useField(params) {
       name,
       controlRef,
       validityData: getCombinedFieldValidityData(validityData, invalid),
-      validate() {
+      validate(flushSync = true) {
         let nextValue = value;
         if (nextValue === undefined) {
           nextValue = getValue();
         }
         markedDirtyRef.current = true;
-        // Synchronously update the validity state so the submit event can be prevented.
-        ReactDOM.flushSync(() => commit(nextValue));
+        if (!flushSync) {
+          commit(nextValue);
+        } else {
+          // Synchronously update the validity state so the submit event can be prevented.
+          ReactDOM.flushSync(() => commit(nextValue));
+        }
       }
     });
   }, [commit, controlRef, enabled, formRef, getValue, id, invalid, markedDirtyRef, name, validityData, value]);

package/esm/field/validity/FieldValidity.d.ts

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { FieldValidityData } from "../root/FieldRoot.js";
+import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
 /**
  * Used to display a custom message based on the field’s validity.
  * Requires `children` to be a function that accepts field validity state as an argument.
@@ -9,6 +10,7 @@ import { FieldValidityData } from "../root/FieldRoot.js";
 export declare const FieldValidity: React.FC<FieldValidity.Props>;
 export interface FieldValidityState extends Omit<FieldValidityData, 'state'> {
   validity: FieldValidityData['state'];
+  transitionStatus: TransitionStatus;
 }
 export interface FieldValidityProps {
   /**

package/esm/field/validity/FieldValidity.js

@@ -3,13 +3,15 @@
 import * as React from 'react';
 import { useFieldRootContext } from "../root/FieldRootContext.js";
 import { getCombinedFieldValidityData } from "../utils/getCombinedFieldValidityData.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { useTransitionStatus } from "../../utils/useTransitionStatus.js";
+
 /**
  * Used to display a custom message based on the field’s validity.
  * Requires `children` to be a function that accepts field validity state as an argument.
  *
  * Documentation: [Base UI Field](https://base-ui.com/react/components/field)
  */
+import { jsx as _jsx } from "react/jsx-runtime";
 export const FieldValidity = function FieldValidity(props) {
   const {
     children
@@ -18,13 +20,18 @@ export const FieldValidity = function FieldValidity(props) {
     validityData,
     invalid
   } = useFieldRootContext(false);
+  const combinedFieldValidityData = React.useMemo(() => getCombinedFieldValidityData(validityData, invalid), [validityData, invalid]);
+  const isInvalid = combinedFieldValidityData.state.valid === false;
+  const {
+    transitionStatus
+  } = useTransitionStatus(isInvalid);
   const fieldValidityState = React.useMemo(() => {
-    const combinedFieldValidityData = getCombinedFieldValidityData(validityData, invalid);
     return {
       ...combinedFieldValidityData,
-      validity: combinedFieldValidityData.state
+      validity: combinedFieldValidityData.state,
+      transitionStatus
     };
-  }, [validityData, invalid]);
+  }, [combinedFieldValidityData, transitionStatus]);
   return /*#__PURE__*/_jsx(React.Fragment, {
     children: children(fieldValidityState)
   });

package/esm/fieldset/legend/FieldsetLegend.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Fieldset](https://base-ui.com/react/components/fieldset)
  */
-export declare const FieldsetLegend: React.ForwardRefExoticComponent<FieldsetLegendProps & React.RefAttributes<HTMLDivElement>>;
+export declare const FieldsetLegend: React.ForwardRefExoticComponent<Omit<FieldsetLegendProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface FieldsetLegendState {
   /**
    * Whether the component should ignore user interaction.