@base-ui/react 1.1.0 → 1.3.0

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

@@ -31,33 +31,50 @@ export interface FieldRootActions {
   validate: () => void;
 }
 export interface FieldRootState {
-  /** Whether the component should ignore user interaction. */
+  /**
+   * Whether the component should ignore user interaction.
+   */
   disabled: boolean;
+  /**
+   * Whether the field has been touched.
+   */
   touched: boolean;
+  /**
+   * Whether the field value has changed from its initial value.
+   */
   dirty: boolean;
+  /**
+   * Whether the field is valid.
+   */
   valid: boolean | null;
+  /**
+   * Whether the field has a value.
+   */
   filled: boolean;
+  /**
+   * Whether the field is focused.
+   */
   focused: boolean;
 }
-export interface FieldRootProps extends BaseUIComponentProps<'div', FieldRoot.State> {
+export interface FieldRootProps extends BaseUIComponentProps<'div', FieldRootState> {
   /**
    * Whether the component should ignore user interaction.
    * 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>`.
@@ -68,33 +85,33 @@ 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>;
+  actionsRef?: React.RefObject<FieldRoot.Actions | null> | undefined;
 }
 export declare namespace FieldRoot {
   type State = FieldRootState;

package/esm/field/root/FieldRoot.js

@@ -62,7 +62,8 @@ const FieldRootInner = /*#__PURE__*/React.forwardRef(function FieldRootInner(com
     setTouchedUnwrapped(value);
   });
   const shouldValidateOnChange = useStableCallback(() => validationMode === 'onChange' || validationMode === 'onSubmit' && submitAttemptedRef.current);
-  const invalid = Boolean(invalidProp || name && {}.hasOwnProperty.call(errors, name) && errors[name] !== undefined);
+  const hasFormError = !!name && Object.hasOwn(errors, name) && errors[name] !== undefined;
+  const invalid = invalidProp === true || hasFormError;
   const [validityData, setValidityData] = React.useState({
     state: DEFAULT_VALIDITY_STATE,
     error: '',

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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { FieldRoot, FieldValidityData } from "./FieldRoot.js";
+import type { FieldValidityData, FieldRootState } from "./FieldRoot.js";
 import type { Form } from "../../form/index.js";
 import type { UseFieldValidationReturnValue } from "./useFieldValidation.js";
 export interface FieldRootContext {
@@ -20,8 +20,8 @@ export interface FieldRootContext {
   validationMode: Form.ValidationMode;
   validationDebounceTime: number;
   shouldValidateOnChange: () => boolean;
-  state: FieldRoot.State;
-  markedDirtyRef: React.MutableRefObject<boolean>;
+  state: FieldRootState;
+  markedDirtyRef: React.RefObject<boolean>;
   validation: UseFieldValidationReturnValue;
 }
 export declare const FieldRootContext: React.Context<FieldRootContext>;

package/esm/field/root/FieldRootContext.js

@@ -3,7 +3,7 @@
 import _formatErrorMessage from "@base-ui/utils/formatErrorMessage";
 import * as React from 'react';
 import { NOOP } from "../../utils/noop.js";
-import { DEFAULT_VALIDITY_STATE } from "../utils/constants.js";
+import { DEFAULT_FIELD_ROOT_STATE, DEFAULT_FIELD_STATE_ATTRIBUTES, DEFAULT_VALIDITY_STATE } from "../utils/constants.js";
 import { EMPTY_OBJECT } from "../../utils/constants.js";
 export const FieldRootContext = /*#__PURE__*/React.createContext({
   invalid: undefined,
@@ -17,26 +17,19 @@ export const FieldRootContext = /*#__PURE__*/React.createContext({
   },
   setValidityData: NOOP,
   disabled: undefined,
-  touched: false,
+  touched: DEFAULT_FIELD_STATE_ATTRIBUTES.touched,
   setTouched: NOOP,
-  dirty: false,
+  dirty: DEFAULT_FIELD_STATE_ATTRIBUTES.dirty,
   setDirty: NOOP,
-  filled: false,
+  filled: DEFAULT_FIELD_STATE_ATTRIBUTES.filled,
   setFilled: NOOP,
-  focused: false,
+  focused: DEFAULT_FIELD_STATE_ATTRIBUTES.focused,
   setFocused: NOOP,
   validate: () => null,
   validationMode: 'onSubmit',
   validationDebounceTime: 0,
   shouldValidateOnChange: () => false,
-  state: {
-    disabled: false,
-    valid: null,
-    touched: false,
-    dirty: false,
-    filled: false,
-    focused: false
-  },
+  state: DEFAULT_FIELD_ROOT_STATE,
   markedDirtyRef: {
     current: false
   },

package/esm/field/root/useFieldValidation.js

@@ -191,6 +191,7 @@ export function useFieldValidation(params) {
       if (currentFieldData) {
         formRef.current.fields.set(controlId, {
           ...currentFieldData,
+          // Keep Form-level errors part of overall field validity for submit blocking/focus logic.
           ...getCombinedFieldValidityData(nextValidityData, invalid)
         });
       }
@@ -211,9 +212,9 @@ export function useFieldValidation(params) {
         commit(event.currentTarget.value, true);
         return;
       }
-      if (invalid) {
-        return;
-      }
+
+      // When validating on change, run client-side validation even if
+      // externally invalid
       const element = event.currentTarget;
       if (element.value === '') {
         // Ignore the debounce time for empty values.
@@ -229,7 +230,7 @@ export function useFieldValidation(params) {
         commit(element.value);
       }
     }
-  }, getValidationProps(externalProps)), [getValidationProps, clearErrors, name, timeout, commit, invalid, validationDebounceTime, shouldValidateOnChange]);
+  }, getValidationProps(externalProps)), [getValidationProps, clearErrors, name, timeout, commit, validationDebounceTime, shouldValidateOnChange]);
   return React.useMemo(() => ({
     getValidationProps,
     getInputValidationProps,

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';

package/esm/field/utils/constants.d.ts

@@ -1,3 +1,4 @@
+import type { FieldRootState } from "../root/FieldRoot.js";
 export declare const DEFAULT_VALIDITY_STATE: {
   badInput: boolean;
   customError: boolean;
@@ -11,6 +12,8 @@ export declare const DEFAULT_VALIDITY_STATE: {
   valid: null;
   valueMissing: boolean;
 };
+export declare const DEFAULT_FIELD_STATE_ATTRIBUTES: Pick<FieldRootState, 'valid' | 'touched' | 'dirty' | 'filled' | 'focused'>;
+export declare const DEFAULT_FIELD_ROOT_STATE: FieldRootState;
 export declare const fieldValidityMapping: {
   valid(value: boolean | null): Record<string, string> | null;
 };

package/esm/field/utils/constants.js

@@ -12,6 +12,17 @@ export const DEFAULT_VALIDITY_STATE = {
   valid: null,
   valueMissing: false
 };
+export const DEFAULT_FIELD_STATE_ATTRIBUTES = {
+  valid: null,
+  touched: false,
+  dirty: false,
+  filled: false,
+  focused: false
+};
+export const DEFAULT_FIELD_ROOT_STATE = {
+  disabled: false,
+  ...DEFAULT_FIELD_STATE_ATTRIBUTES
+};
 export const fieldValidityMapping = {
   valid(value) {
     if (value === null) {

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.
@@ -8,7 +9,14 @@ import { FieldValidityData } from "../root/FieldRoot.js";
  */
 export declare const FieldValidity: React.FC<FieldValidity.Props>;
 export interface FieldValidityState extends Omit<FieldValidityData, 'state'> {
+  /**
+   * The validity state.
+   */
   validity: FieldValidityData['state'];
+  /**
+   * The transition status of the component.
+   */
+  transitionStatus: TransitionStatus;
 }
 export interface FieldValidityProps {
   /**
@@ -22,7 +30,7 @@ export interface FieldValidityProps {
    * </Field.Validity>
    * ```
    */
-  children: (state: FieldValidity.State) => React.ReactNode;
+  children: (state: FieldValidityState) => React.ReactNode;
 }
 export declare namespace FieldValidity {
   type State = FieldValidityState;

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

@@ -13,7 +13,7 @@ export interface FieldsetLegendState {
    */
   disabled: boolean;
 }
-export interface FieldsetLegendProps extends BaseUIComponentProps<'div', FieldsetLegend.State> {}
+export interface FieldsetLegendProps extends BaseUIComponentProps<'div', FieldsetLegendState> {}
 export declare namespace FieldsetLegend {
   type State = FieldsetLegendState;
   type Props = FieldsetLegendProps;

package/esm/fieldset/legend/FieldsetLegend.js

@@ -29,9 +29,9 @@ export const FieldsetLegend = /*#__PURE__*/React.forwardRef(function FieldsetLeg
       setLegendId(undefined);
     };
   }, [setLegendId, id]);
-  const state = React.useMemo(() => ({
+  const state = {
     disabled: disabled ?? false
-  }), [disabled]);
+  };
   const element = useRenderElement('div', componentProps, {
     state,
     ref: forwardedRef,

package/esm/fieldset/root/FieldsetRoot.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import type { BaseUIComponentProps } from "../../utils/types.js";
 /**
- * Groups the fieldset legend and the associated fields.
+ * Groups a shared legend with related controls.
  * Renders a `<fieldset>` element.
  *
  * Documentation: [Base UI Fieldset](https://base-ui.com/react/components/fieldset)
@@ -13,7 +13,7 @@ export interface FieldsetRootState {
    */
   disabled: boolean;
 }
-export interface FieldsetRootProps extends BaseUIComponentProps<'fieldset', FieldsetRoot.State> {}
+export interface FieldsetRootProps extends BaseUIComponentProps<'fieldset', FieldsetRootState> {}
 export declare namespace FieldsetRoot {
   type State = FieldsetRootState;
   type Props = FieldsetRootProps;

package/esm/fieldset/root/FieldsetRoot.js

@@ -5,7 +5,7 @@ import { FieldsetRootContext } from "./FieldsetRootContext.js";
 import { useRenderElement } from "../../utils/useRenderElement.js";
 
 /**
- * Groups the fieldset legend and the associated fields.
+ * Groups a shared legend with related controls.
  * Renders a `<fieldset>` element.
  *
  * Documentation: [Base UI Fieldset](https://base-ui.com/react/components/fieldset)
@@ -19,9 +19,9 @@ export const FieldsetRoot = /*#__PURE__*/React.forwardRef(function FieldsetRoot(
     ...elementProps
   } = componentProps;
   const [legendId, setLegendId] = React.useState(undefined);
-  const state = React.useMemo(() => ({
+  const state = {
     disabled
-  }), [disabled]);
+  };
   const element = useRenderElement('fieldset', componentProps, {
     ref: forwardedRef,
     state,

package/esm/floating-ui-react/components/FloatingDelayGroup.d.ts

@@ -12,7 +12,7 @@ export interface FloatingDelayGroupProps {
    * This is useful if you want grouping to “last” longer than the close delay,
    * for example if there is no close delay at all.
    */
-  timeoutMs?: number;
+  timeoutMs?: number | undefined;
 }
 /**
  * Experimental next version of `FloatingDelayGroup` to become the default
@@ -26,11 +26,6 @@ export interface FloatingDelayGroupProps {
  */
 export declare function FloatingDelayGroup(props: FloatingDelayGroupProps): React.JSX.Element;
 interface UseDelayGroupOptions {
-  /**
-   * Whether delay grouping should be enabled.
-   * @default true
-   */
-  enabled?: boolean;
   /**
    * Whether the trigger this hook is used in has opened the tooltip.
    */
@@ -40,7 +35,7 @@ interface UseDelayGroupReturn {
   /**
    * The delay reference object.
    */
-  delayRef: React.MutableRefObject<Delay>;
+  delayRef: React.RefObject<Delay>;
   /**
    * Whether animations should be removed.
    */

package/esm/floating-ui-react/components/FloatingDelayGroup.js

@@ -3,7 +3,7 @@
 import * as React from 'react';
 import { useTimeout, Timeout } from '@base-ui/utils/useTimeout';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
-import { getDelay } from "../hooks/useHover.js";
+import { getDelay } from "../hooks/useHoverShared.js";
 import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -71,7 +71,6 @@ export function useDelayGroup(context, options = {
   const store = 'rootStore' in context ? context.rootStore : context;
   const floatingId = store.useState('floatingId');
   const {
-    enabled = true,
     open
   } = options;
   const groupContext = React.useContext(FloatingDelayGroupContext);
@@ -93,9 +92,6 @@ export function useDelayGroup(context, options = {
       currentContextRef.current = null;
       delayRef.current = initialDelayRef.current;
     }
-    if (!enabled) {
-      return undefined;
-    }
     if (!currentIdRef.current) {
       return undefined;
     }
@@ -117,11 +113,8 @@ export function useDelayGroup(context, options = {
       unset();
     }
     return undefined;
-  }, [enabled, open, floatingId, currentIdRef, delayRef, timeoutMs, initialDelayRef, currentContextRef, timeout, store]);
+  }, [open, floatingId, currentIdRef, delayRef, timeoutMs, initialDelayRef, currentContextRef, timeout, store]);
   useIsoLayoutEffect(() => {
-    if (!enabled) {
-      return;
-    }
     if (!open) {
       return;
     }
@@ -148,7 +141,7 @@ export function useDelayGroup(context, options = {
       setIsInstantPhase(false);
       prevContext?.setIsInstantPhase(false);
     }
-  }, [enabled, open, floatingId, store, currentIdRef, delayRef, timeoutMs, initialDelayRef, currentContextRef, timeout]);
+  }, [open, floatingId, store, currentIdRef, delayRef, timeoutMs, initialDelayRef, currentContextRef, timeout]);
   useIsoLayoutEffect(() => {
     return () => {
       currentContextRef.current = null;

package/esm/floating-ui-react/components/FloatingFocusManager.d.ts

@@ -11,19 +11,14 @@ export interface FloatingFocusManagerProps {
   /**
    * The interaction type used to open the floating element.
    */
-  openInteractionType?: InteractionType | null;
+  openInteractionType?: InteractionType | null | undefined;
   /**
    * Whether or not the focus manager should be disabled. Useful to delay focus
    * management until after a transition completes or some other conditional
    * state.
    * @default false
    */
-  disabled?: boolean;
-  /**
-   * The order in which focus cycles.
-   * @default ['content']
-   */
-  order?: Array<'reference' | 'floating' | 'content'>;
+  disabled?: boolean | undefined;
   /**
    * Determines the element to focus when the floating element is opened.
    *
@@ -35,7 +30,7 @@ export interface FloatingFocusManagerProps {
    *   or `false`/`undefined` to do nothing.
    * @default true
    */
-  initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | HTMLElement | null | void);
+  initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | HTMLElement | null | void) | undefined;
   /**
    * Determines the element to focus when the floating element is closed.
    *
@@ -47,7 +42,7 @@ export interface FloatingFocusManagerProps {
    *   or `false`/`undefined` to do nothing.
    * @default true
    */
-  returnFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void);
+  returnFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void) | undefined;
   /**
    * Determines where focus should be restored if focus inside the floating element is lost
    * (such as due to the removal of the currently focused element from the DOM).
@@ -58,14 +53,14 @@ export interface FloatingFocusManagerProps {
    * - `false`: do not restore focus
    * @default false
    */
-  restoreFocus?: boolean | 'popup';
+  restoreFocus?: boolean | 'popup' | undefined;
   /**
    * Determines if focus is “modal”, meaning focus is fully trapped inside the
    * floating element and outside content cannot be accessed. This includes
    * screen reader virtual cursors.
    * @default true
    */
-  modal?: boolean;
+  modal?: boolean | undefined;
   /**
    * Determines whether `focusout` event listeners that control whether the
    * floating element should be closed if the focus moves outside of it are
@@ -73,29 +68,29 @@ export interface FloatingFocusManagerProps {
    * focus management.
    * @default true
    */
-  closeOnFocusOut?: boolean;
-  /**
-   * Returns a list of elements that should be considered part of the
-   * floating element.
-   */
-  getInsideElements?: () => Element[];
+  closeOnFocusOut?: boolean | undefined;
   /**
    * Overrides the element to focus when tabbing forward out of the floating element.
    */
-  nextFocusableElement?: HTMLElement | React.RefObject<HTMLElement | null> | null;
+  nextFocusableElement?: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined;
   /**
    * Overrides the element to focus when tabbing backward out of the floating element.
    */
-  previousFocusableElement?: HTMLElement | React.RefObject<HTMLElement | null> | null;
+  previousFocusableElement?: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined;
   /**
    * Ref to the focus guard preceding the floating element content.
-   * Can be useful to focus the popup progammatically.
+   * Can be useful to focus the popup programmatically.
    */
-  beforeContentFocusGuardRef?: React.RefObject<HTMLSpanElement | null>;
+  beforeContentFocusGuardRef?: React.RefObject<HTMLSpanElement | null> | undefined;
   /**
    * External FlatingTree to use when the one provided by context can't be used.
    */
-  externalTree?: FloatingTreeStore;
+  externalTree?: FloatingTreeStore | undefined;
+  /**
+   * Additional elements that should be treated as part of the floating subtree
+   * even if they are rendered outside the floating element itself.
+   */
+  getInsideElements?: (() => Array<Element | null | undefined>) | undefined;
 }
 /**
  * Provides focus management for the floating element.