@base-ui/react 1.0.0-rc.2 → 1.1.0

package/esm/field/error/FieldError.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 FieldError: React.ForwardRefExoticComponent<FieldErrorProps & React.RefAttributes<HTMLDivElement>>;
+export declare const FieldError: React.ForwardRefExoticComponent<Omit<FieldErrorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export type FieldErrorState = FieldRoot.State;
 export interface FieldErrorProps extends BaseUIComponentProps<'div', FieldError.State> {
   /**

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,7 +7,7 @@ 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.

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;
+}
 export declare namespace FieldLabel {
   type State = FieldLabelState;
   type Props = FieldLabelProps;

package/esm/field/label/FieldLabel.js

@@ -1,7 +1,11 @@
 'use client';
 
 import * as React from 'react';
+import { error } from '@base-ui/utils/error';
+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 +24,7 @@ export const FieldLabel = /*#__PURE__*/React.forwardRef(function FieldLabel(comp
     render,
     className,
     id: idProp,
+    nativeLabel = true,
     ...elementProps
   } = componentProps;
   const fieldRootContext = useFieldRootContext(false);
@@ -30,6 +35,45 @@ 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) {
+          error('<Field.Label> was not rendered as a <label> element, which does not match the `nativeLabel` prop on the component. Ensure that the element passed to the `render` prop of <Field.Label> is a real <label>, or set the `nativeLabel` prop on the component to `false`.');
+        }
+      } else if (isLabelTag) {
+        error('<Field.Label> was rendered as a <label> element, which does not match the `nativeLabel` prop on the component. Ensure that the element passed to the `render` prop of <Field.Label> is not a real <label>, or set the `nativeLabel` prop on the component to `true`.');
+      }
+    }, [nativeLabel]);
+  }
   useIsoLayoutEffect(() => {
     if (id) {
       setLabelId(id);
@@ -42,18 +86,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;
@@ -87,8 +90,14 @@ export interface FieldRootProps extends BaseUIComponentProps<'div', FieldRoot.St
    * Useful when the field state is controlled by an external library.
    */
   touched?: boolean;
+  /**
+   * A ref to imperative actions.
+   * - `validate`: Validates the field when called.
+   */
+  actionsRef?: React.RefObject<FieldRoot.Actions | null>;
 }
 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/useField.js

@@ -47,14 +47,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/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.

package/esm/fieldset/root/FieldsetRoot.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 FieldsetRoot: React.ForwardRefExoticComponent<FieldsetRootProps & React.RefAttributes<HTMLElement>>;
+export declare const FieldsetRoot: React.ForwardRefExoticComponent<Omit<FieldsetRootProps, "ref"> & React.RefAttributes<HTMLElement>>;
 export interface FieldsetRootState {
   /**
    * Whether the component should ignore user interaction.

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

@@ -156,6 +156,10 @@ export function FloatingFocusManager(props) {
   const tabbableIndexRef = React.useRef(-1);
   const closeTypeRef = React.useRef('');
   const lastInteractionTypeRef = React.useRef('');
+  const beforeGuardRef = React.useRef(null);
+  const afterGuardRef = React.useRef(null);
+  const mergedBeforeGuardRef = useMergedRefs(beforeGuardRef, beforeContentFocusGuardRef, portalContext?.beforeInsideRef);
+  const mergedAfterGuardRef = useMergedRefs(afterGuardRef, portalContext?.afterInsideRef);
   const blurTimeout = useTimeout();
   const pointerDownTimeout = useTimeout();
   const restoreFocusFrame = useAnimationFrame();
@@ -261,7 +265,8 @@ export function FloatingFocusManager(props) {
       queueMicrotask(() => {
         const nodeId = getNodeId();
         const triggers = store.context.triggerElements;
-        const movedToUnrelatedNode = !(contains(domReference, relatedTarget) || contains(floating, relatedTarget) || contains(relatedTarget, floating) || contains(portalContext?.portalNode, relatedTarget) || relatedTarget != null && triggers.hasElement(relatedTarget) || triggers.hasMatchingElement(trigger => contains(trigger, relatedTarget)) || relatedTarget?.hasAttribute(createAttribute('focus-guard')) || tree && (getNodeChildren(tree.nodesRef.current, nodeId).find(node => contains(node.context?.elements.floating, relatedTarget) || contains(node.context?.elements.domReference, relatedTarget)) || getNodeAncestors(tree.nodesRef.current, nodeId).find(node => [node.context?.elements.floating, getFloatingFocusElement(node.context?.elements.floating)].includes(relatedTarget) || node.context?.elements.domReference === relatedTarget)));
+        const isRelatedFocusGuard = relatedTarget?.hasAttribute(createAttribute('focus-guard')) && [beforeGuardRef.current, afterGuardRef.current, portalContext?.beforeInsideRef.current, portalContext?.afterInsideRef.current, portalContext?.beforeOutsideRef.current, portalContext?.afterOutsideRef.current, resolveRef(previousFocusableElement), resolveRef(nextFocusableElement)].includes(relatedTarget);
+        const movedToUnrelatedNode = !(contains(domReference, relatedTarget) || contains(floating, relatedTarget) || contains(relatedTarget, floating) || contains(portalContext?.portalNode, relatedTarget) || relatedTarget != null && triggers.hasElement(relatedTarget) || triggers.hasMatchingElement(trigger => contains(trigger, relatedTarget)) || isRelatedFocusGuard || tree && (getNodeChildren(tree.nodesRef.current, nodeId).find(node => contains(node.context?.elements.floating, relatedTarget) || contains(node.context?.elements.domReference, relatedTarget)) || getNodeAncestors(tree.nodesRef.current, nodeId).find(node => [node.context?.elements.floating, getFloatingFocusElement(node.context?.elements.floating)].includes(relatedTarget) || node.context?.elements.domReference === relatedTarget)));
         if (currentTarget === domReference && floatingFocusElement) {
           handleTabIndex(floatingFocusElement, orderRef);
         }
@@ -355,11 +360,7 @@ export function FloatingFocusManager(props) {
         cleanup();
       });
     };
-  }, [disabled, domReference, floating, floatingFocusElement, modal, tree, portalContext, store, closeOnFocusOut, restoreFocus, getTabbableContent, isUntrappedTypeableCombobox, getNodeId, orderRef, dataRef, blurTimeout, pointerDownTimeout, restoreFocusFrame]);
-  const beforeGuardRef = React.useRef(null);
-  const afterGuardRef = React.useRef(null);
-  const mergedBeforeGuardRef = useMergedRefs(beforeGuardRef, beforeContentFocusGuardRef, portalContext?.beforeInsideRef);
-  const mergedAfterGuardRef = useMergedRefs(afterGuardRef, portalContext?.afterInsideRef);
+  }, [disabled, domReference, floating, floatingFocusElement, modal, tree, portalContext, store, closeOnFocusOut, restoreFocus, getTabbableContent, isUntrappedTypeableCombobox, getNodeId, orderRef, dataRef, blurTimeout, pointerDownTimeout, restoreFocusFrame, nextFocusableElement, previousFocusableElement]);
   React.useEffect(() => {
     if (disabled || !floating || !open) {
       return undefined;

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

@@ -40,9 +40,9 @@ export declare function useFloatingPortalNode(props?: UseFloatingPortalNodeProps
  * @see https://floating-ui.com/docs/FloatingPortal
  * @internal
  */
-export declare const FloatingPortal: React.ForwardRefExoticComponent<FloatingPortal.Props<any> & {
+export declare const FloatingPortal: React.ForwardRefExoticComponent<Omit<FloatingPortal.Props<any> & {
   renderGuards?: boolean;
-} & React.RefAttributes<HTMLDivElement>>;
+}, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare namespace FloatingPortal {
   interface Props<State> extends BaseUIComponentProps<'div', State> {
     /**

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

@@ -5,6 +5,7 @@ import * as ReactDOM from 'react-dom';
 import { isNode } from '@floating-ui/utils/dom';
 import { useId } from '@base-ui/utils/useId';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { FocusGuard } from "../../utils/FocusGuard.js";
 import { enableFocusInside, disableFocusInside, getPreviousTabbable, getNextTabbable, isOutsideEvent } from "../utils.js";
 import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
@@ -30,6 +31,14 @@ export function useFloatingPortalNode(props = {}) {
   const parentPortalNode = portalContext?.portalNode;
   const [containerElement, setContainerElement] = React.useState(null);
   const [portalNode, setPortalNode] = React.useState(null);
+  const setPortalNodeRef = useStableCallback(node => {
+    if (node !== null) {
+      // the useIsoLayoutEffect below watching containerProp / parentPortalNode
+      // sets setPortalNode(null) when the container becomes null or changes.
+      // So even though the ref callback now ignores null, the portal node still gets cleared.
+      setPortalNode(node);
+    }
+  });
   const containerRef = React.useRef(null);
   useIsoLayoutEffect(() => {
     // Wait for the container to be resolved if explicitly `null`.
@@ -62,7 +71,7 @@ export function useFloatingPortalNode(props = {}) {
     }
   }, [containerProp, parentPortalNode, uniqueId]);
   const portalElement = useRenderElement('div', componentProps, {
-    ref: [ref, setPortalNode],
+    ref: [ref, setPortalNodeRef],
     state: elementState,
     props: [{
       id: uniqueId,
@@ -125,7 +134,7 @@ export const FloatingPortal = /*#__PURE__*/React.forwardRef(function FloatingPor
     // portal has already been focused, either by tabbing into a focus trap
     // element outside or using the mouse.
     function onFocus(event) {
-      if (portalNode && isOutsideEvent(event)) {
+      if (portalNode && event.relatedTarget && isOutsideEvent(event)) {
         const focusing = event.type === 'focusin';
         const manageFocus = focusing ? enableFocusInside : disableFocusInside;
         manageFocus(portalNode);

package/esm/floating-ui-react/hooks/useClientPoint.js

@@ -80,7 +80,7 @@ export function useClientPoint(context, props = {}) {
   const cleanupListenerRef = React.useRef(null);
   const [pointerType, setPointerType] = React.useState();
   const [reactive, setReactive] = React.useState([]);
-  const setReference = useStableCallback((newX, newY) => {
+  const setReference = useStableCallback((newX, newY, referenceElement) => {
     if (initialRef.current) {
       return;
     }
@@ -91,7 +91,7 @@ export function useClientPoint(context, props = {}) {
     if (dataRef.current.openEvent && !isMouseBasedEvent(dataRef.current.openEvent)) {
       return;
     }
-    store.set('positionReference', createVirtualElement(domReference, {
+    store.set('positionReference', createVirtualElement(referenceElement ?? domReference, {
       x: newX,
       y: newY,
       axis,
@@ -104,7 +104,7 @@ export function useClientPoint(context, props = {}) {
       return;
     }
     if (!open) {
-      setReference(event.clientX, event.clientY);
+      setReference(event.clientX, event.clientY, event.currentTarget);
     } else if (!cleanupListenerRef.current) {
       // If there's no cleanup, there's no listener, but we want to ensure
       // we add the listener if the cursor landed on the floating element and
@@ -176,6 +176,7 @@ export function useClientPoint(context, props = {}) {
     };
   }, [handleReferenceEnterOrMove]);
   return React.useMemo(() => enabled ? {
-    reference
+    reference,
+    trigger: reference
   } : {}, [enabled, reference]);
 }

package/esm/floating-ui-react/hooks/useDismiss.js

@@ -385,6 +385,7 @@ export function useDismiss(context, props = {}) {
         ancestor.removeEventListener('scroll', onScroll);
       });
       compositionTimeout.clear();
+      endedOrStartedInsideRef.current = false;
     };
   }, [dataRef, floatingElement, referenceElement, domReferenceElement, escapeKey, outsidePress, open, onOpenChange, ancestorScroll, enabled, escapeKeyBubbles, outsidePressBubbles, closeOnEscapeKeyDown, closeOnPressOutside, closeOnPressOutsideCapture, handlePointerDown, handleTouchStartCapture, handleTouchMoveCapture, handleTouchEndCapture, trackPointerType, store]);
   React.useEffect(clearInsideReactTree, [outsidePress, clearInsideReactTree]);
@@ -408,6 +409,12 @@ export function useDismiss(context, props = {}) {
     }
     endedOrStartedInsideRef.current = true;
   });
+  const markPressStartedInsideReactTree = useStableCallback(event => {
+    if (!open || !enabled || event.button !== 0) {
+      return;
+    }
+    endedOrStartedInsideRef.current = true;
+  });
   const floating = React.useMemo(() => ({
     onKeyDown: closeOnEscapeKeyDown,
     // `onMouseDown` may be blocked if `event.preventDefault()` is called in
@@ -417,12 +424,18 @@ export function useDismiss(context, props = {}) {
     onMouseDown: handlePressedInside,
     onMouseUp: handlePressedInside,
     onClickCapture: markInsideReactTree,
-    onMouseDownCapture: markInsideReactTree,
-    onPointerDownCapture: markInsideReactTree,
+    onMouseDownCapture(event) {
+      markInsideReactTree();
+      markPressStartedInsideReactTree(event);
+    },
+    onPointerDownCapture(event) {
+      markInsideReactTree();
+      markPressStartedInsideReactTree(event);
+    },
     onMouseUpCapture: markInsideReactTree,
     onTouchEndCapture: markInsideReactTree,
     onTouchMoveCapture: markInsideReactTree
-  }), [closeOnEscapeKeyDown, handlePressedInside, markInsideReactTree]);
+  }), [closeOnEscapeKeyDown, handlePressedInside, markInsideReactTree, markPressStartedInsideReactTree]);
   return React.useMemo(() => enabled ? {
     reference,
     floating,

package/esm/floating-ui-react/hooks/useFocus.d.ts

@@ -12,6 +12,11 @@ export interface UseFocusProps {
    * @default true
    */
   visibleOnly?: boolean;
+  /**
+   * Waits for the specified time before opening.
+   * @default undefined
+   */
+  delay?: number | (() => number | undefined);
 }
 /**
  * Opens the floating element while the reference element has focus, like CSS

package/esm/floating-ui-react/hooks/useFocus.js

@@ -20,9 +20,12 @@ export function useFocus(context, props = {}) {
   } = store.context;
   const {
     enabled = true,
-    visibleOnly = true
+    visibleOnly = true,
+    delay
   } = props;
   const blockFocusRef = React.useRef(false);
+  // Track which reference should be blocked from re-opening after Escape/press dismissal.
+  const blockedReferenceRef = React.useRef(null);
   const timeout = useTimeout();
   const keyboardModalityRef = React.useRef(true);
   React.useEffect(() => {
@@ -36,7 +39,8 @@ export function useFocus(context, props = {}) {
     // floating element was not open, the focus should be blocked when they
     // return to the tab/window.
     function onBlur() {
-      if (!store.select('open') && isHTMLElement(domReference) && domReference === activeElement(getDocument(domReference))) {
+      const currentDomReference = store.select('domReferenceElement');
+      if (!store.select('open') && isHTMLElement(currentDomReference) && currentDomReference === activeElement(getDocument(currentDomReference))) {
         blockFocusRef.current = true;
       }
     }
@@ -65,21 +69,31 @@ export function useFocus(context, props = {}) {
     }
     function onOpenChangeLocal(details) {
       if (details.reason === REASONS.triggerPress || details.reason === REASONS.escapeKey) {
-        blockFocusRef.current = true;
+        const referenceElement = store.select('domReferenceElement');
+        if (isElement(referenceElement)) {
+          blockedReferenceRef.current = referenceElement;
+          blockFocusRef.current = true;
+        }
       }
     }
     events.on('openchange', onOpenChangeLocal);
     return () => {
       events.off('openchange', onOpenChangeLocal);
     };
-  }, [events, enabled]);
+  }, [events, enabled, store]);
   const reference = React.useMemo(() => ({
     onMouseLeave() {
       blockFocusRef.current = false;
+      blockedReferenceRef.current = null;
     },
     onFocus(event) {
+      const focusTarget = event.currentTarget;
       if (blockFocusRef.current) {
-        return;
+        if (blockedReferenceRef.current === focusTarget) {
+          return;
+        }
+        blockFocusRef.current = false;
+        blockedReferenceRef.current = null;
       }
       const target = getTarget(event.nativeEvent);
       if (visibleOnly && isElement(target)) {
@@ -93,10 +107,26 @@ export function useFocus(context, props = {}) {
           return;
         }
       }
-      store.setOpen(true, createChangeEventDetails(REASONS.triggerFocus, event.nativeEvent, event.currentTarget));
+      const movedFromOtherTrigger = event.relatedTarget && store.context.triggerElements.hasElement(event.relatedTarget);
+      const {
+        nativeEvent,
+        currentTarget
+      } = event;
+      const delayValue = typeof delay === 'function' ? delay() : delay;
+      if (store.select('open') && movedFromOtherTrigger || delayValue === 0 || delayValue === undefined) {
+        store.setOpen(true, createChangeEventDetails(REASONS.triggerFocus, nativeEvent, currentTarget));
+        return;
+      }
+      timeout.start(delayValue, () => {
+        if (blockFocusRef.current) {
+          return;
+        }
+        store.setOpen(true, createChangeEventDetails(REASONS.triggerFocus, nativeEvent, currentTarget));
+      });
     },
     onBlur(event) {
       blockFocusRef.current = false;
+      blockedReferenceRef.current = null;
       const relatedTarget = event.relatedTarget;
       const nativeEvent = event.nativeEvent;
 
@@ -128,13 +158,17 @@ export function useFocus(context, props = {}) {
         // If the next focused element is one of the triggers, do not close
         // the floating element. The focus handler of that trigger will
         // handle the open state.
-        if (store.context.triggerElements.hasElement(event.relatedTarget)) {
-          return;
+        const nextFocusedElement = relatedTarget ?? activeEl;
+        if (isElement(nextFocusedElement)) {
+          const triggerElements = store.context.triggerElements;
+          if (triggerElements.hasElement(nextFocusedElement) || triggerElements.hasMatchingElement(trigger => contains(trigger, nextFocusedElement))) {
+            return;
+          }
         }
         store.setOpen(false, createChangeEventDetails(REASONS.triggerFocus, nativeEvent));
       });
     }
-  }), [dataRef, store, visibleOnly, timeout]);
+  }), [dataRef, store, visibleOnly, timeout, delay]);
   return React.useMemo(() => enabled ? {
     reference,
     trigger: reference

package/esm/floating-ui-react/hooks/useHoverReferenceInteraction.js

@@ -158,8 +158,13 @@ export function useHoverReferenceInteraction(context, props = {}) {
       const allTriggers = store.context.triggerElements;
       const isOverInactiveTrigger = (allTriggers.hasElement(event.target) || allTriggers.hasMatchingElement(t => contains(t, event.target))) && (!currentDomReference || !contains(currentDomReference, event.target));
       const triggerNode = event.currentTarget ?? null;
-      const shouldOpen = !store.select('open') || isOverInactiveTrigger;
-      if (openDelay) {
+      const isOpen = store.select('open');
+      const shouldOpen = !isOpen || isOverInactiveTrigger;
+
+      // When moving between triggers while already open, open immediately without delay
+      if (isOverInactiveTrigger && isOpen) {
+        store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, event, triggerNode));
+      } else if (openDelay) {
         openChangeTimeout.start(openDelay, () => {
           if (shouldOpen) {
             store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, event, triggerNode));
@@ -263,7 +268,15 @@ export function useHoverReferenceInteraction(context, props = {}) {
         }
         restTimeout.clear();
         function handleMouseMove() {
-          if (!blockMouseMoveRef.current && (!currentOpen || isOverInactiveTrigger)) {
+          restTimeoutPendingRef.current = false;
+
+          // A delayed hover open should not override a click-like open that happened
+          // while the hover delay was pending.
+          if (isClickLikeOpenEvent()) {
+            return;
+          }
+          const latestOpen = store.select('open');
+          if (!blockMouseMoveRef.current && (!latestOpen || isOverInactiveTrigger)) {
             store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, nativeEvent, trigger));
           }
         }
@@ -279,5 +292,5 @@ export function useHoverReferenceInteraction(context, props = {}) {
         }
       }
     };
-  }, [blockMouseMoveRef, mouseOnly, store, pointerTypeRef, restMsRef, restTimeout, restTimeoutPendingRef]);
+  }, [blockMouseMoveRef, isClickLikeOpenEvent, mouseOnly, store, pointerTypeRef, restMsRef, restTimeout, restTimeoutPendingRef]);
 }

package/esm/floating-ui-react/hooks/useSyncedFloatingRootContext.js

@@ -41,6 +41,9 @@ export function useSyncedFloatingRootContext(options) {
     if (isElement(referenceElement)) {
       valuesToSync.domReferenceElement = referenceElement;
     }
+    if (store.state.positionReference === store.state.referenceElement) {
+      valuesToSync.positionReference = referenceElement;
+    }
     store.update(valuesToSync);
   }, [open, floatingId, referenceElement, floatingElement, store]);
 

package/esm/form/Form.d.ts

@@ -16,6 +16,10 @@ export declare const Form: {
 };
 export type FormSubmitEventReason = typeof REASONS.none;
 export type FormSubmitEventDetails = BaseUIGenericEventDetails<Form.SubmitEventReason>;
+export type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
+export interface FormActions {
+  validate: (fieldName?: string | undefined) => void;
+}
 export interface FormState {}
 export interface FormProps<FormValues extends Record<string, any> = Record<string, any>> extends BaseUIComponentProps<'form', Form.State> {
   /**
@@ -40,11 +44,24 @@ export interface FormProps<FormValues extends Record<string, any> = Record<strin
    * `preventDefault()` is called on the native submit event when used.
    */
   onFormSubmit?: (formValues: FormValues, eventDetails: Form.SubmitEventDetails) => void;
+  /**
+   * A ref to imperative actions.
+   * - `validate`: Validates all fields when called. Optionally pass a field name to validate a single field.
+   * @example
+   * ```tsx
+   * // validate all fields
+   * actionsRef.current.validate();
+   *
+   * // validate one field
+   * actionsRef.current.validate('email');
+   * ```
+   */
+  actionsRef?: React.RefObject<Form.Actions | null>;
 }
-export type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
 export declare namespace Form {
   type Props<FormValues extends Record<string, any> = Record<string, any>> = FormProps<FormValues>;
   type State = FormState;
+  type Actions = FormActions;
   type ValidationMode = FormValidationMode;
   type SubmitEventReason = FormSubmitEventReason;
   type SubmitEventDetails = FormSubmitEventDetails;

package/esm/form/Form.js

@@ -24,6 +24,7 @@ export const Form = /*#__PURE__*/React.forwardRef(function Form(componentProps,
     errors: externalErrors,
     onSubmit,
     onFormSubmit,
+    actionsRef,
     ...elementProps
   } = componentProps;
   const formRef = React.useRef({
@@ -54,6 +55,22 @@ export const Form = /*#__PURE__*/React.forwardRef(function Form(componentProps,
       focusControl(invalidFields[0].controlRef.current);
     }
   }, [errors, focusControl]);
+  const handleImperativeValidate = React.useCallback(fieldName => {
+    const values = Array.from(formRef.current.fields.values());
+    if (fieldName) {
+      const namedField = values.find(field => field.name === fieldName);
+      if (namedField) {
+        namedField.validate(false);
+      }
+    } else {
+      values.forEach(field => {
+        field.validate(false);
+      });
+    }
+  }, []);
+  React.useImperativeHandle(actionsRef, () => ({
+    validate: handleImperativeValidate
+  }), [handleImperativeValidate]);
   const element = useRenderElement('form', componentProps, {
     ref: forwardedRef,
     props: [{