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

package/merge-props/mergeProps.d.ts

@@ -6,11 +6,14 @@ type InputProps<T extends React.ElementType> = PropsOf<T> | ((otherProps: PropsO
 /**
  * Merges multiple sets of React props. It follows the Object.assign pattern where the rightmost object's fields overwrite
  * the conflicting ones from others. This doesn't apply to event handlers, `className` and `style` props.
- * Event handlers are merged such that they are called in sequence (the rightmost one being called first),
- * and allows the user to prevent the subsequent event handlers from being
- * executed by attaching a `preventBaseUIHandler` method.
- * It also merges the `className` and `style` props, whereby the classes are concatenated
- * and the rightmost styles overwrite the subsequent ones.
+ *
+ * Event handlers are merged and called in right-to-left order (rightmost handler executes first, leftmost last).
+ * For React synthetic events, the rightmost handler can prevent prior (left-positioned) handlers from executing
+ * by calling `event.preventBaseUIHandler()`. For non-synthetic events (custom events with primitive/object values),
+ * all handlers always execute without prevention capability.
+ *
+ * The `className` prop is merged by concatenating classes in right-to-left order (rightmost class appears first in the string).
+ * The `style` prop is merged with rightmost styles overwriting the prior ones.
  *
  * Props can either be provided as objects or as functions that take the previous props as an argument.
  * The function will receive the merged props up to that point (going from left to right):
@@ -21,14 +24,31 @@ type InputProps<T extends React.ElementType> = PropsOf<T> | ((otherProps: PropsO
  * They must check `event.baseUIHandlerPrevented` themselves and bail out if it's true.
  *
  * @important **`ref` is not merged.**
- * @param props props to merge.
- * @returns the merged props.
+ * @param a Props object to merge.
+ * @param b Props object to merge. The function will overwrite conflicting props from `a`.
+ * @param c Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @param d Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @param e Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @returns The merged props.
+ * @public
  */
-export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>): PropsOf<T>;
-export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>): PropsOf<T>;
-export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>, c: InputProps<T>): PropsOf<T>;
-export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>, c: InputProps<T>, d: InputProps<T>): PropsOf<T>;
 export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>, c: InputProps<T>, d: InputProps<T>, e: InputProps<T>): PropsOf<T>;
+export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>, c: InputProps<T>, d: InputProps<T>): PropsOf<T>;
+export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>, c: InputProps<T>): PropsOf<T>;
+export declare function mergeProps<T extends ElementType>(a: InputProps<T>, b: InputProps<T>): PropsOf<T>;
+/**
+ * Merges an arbitrary number of React props using the same logic as {@link mergeProps}.
+ * This function accepts an array of props instead of individual arguments.
+ *
+ * This has slightly lower performance than {@link mergeProps} due to accepting an array
+ * instead of a fixed number of arguments. Prefer {@link mergeProps} when merging 5 or
+ * fewer prop sets for better performance.
+ *
+ * @param props Array of props to merge.
+ * @returns The merged props.
+ * @see mergeProps
+ * @public
+ */
 export declare function mergePropsN<T extends ElementType>(props: InputProps<T>[]): PropsOf<T>;
 export declare function makeEventPreventable<T extends React.SyntheticEvent>(event: BaseUIEvent<T>): BaseUIEvent<T>;
 export declare function mergeClassNames(ourClassName: string | undefined, theirClassName: string | undefined): string | undefined;

package/merge-props/mergeProps.js

@@ -10,14 +10,18 @@ exports.mergePropsN = mergePropsN;
 var _mergeObjects = require("@base-ui/utils/mergeObjects");
 const EMPTY_PROPS = {};
 
+/* eslint-disable id-denylist */
 /**
  * Merges multiple sets of React props. It follows the Object.assign pattern where the rightmost object's fields overwrite
  * the conflicting ones from others. This doesn't apply to event handlers, `className` and `style` props.
- * Event handlers are merged such that they are called in sequence (the rightmost one being called first),
- * and allows the user to prevent the subsequent event handlers from being
- * executed by attaching a `preventBaseUIHandler` method.
- * It also merges the `className` and `style` props, whereby the classes are concatenated
- * and the rightmost styles overwrite the subsequent ones.
+ *
+ * Event handlers are merged and called in right-to-left order (rightmost handler executes first, leftmost last).
+ * For React synthetic events, the rightmost handler can prevent prior (left-positioned) handlers from executing
+ * by calling `event.preventBaseUIHandler()`. For non-synthetic events (custom events with primitive/object values),
+ * all handlers always execute without prevention capability.
+ *
+ * The `className` prop is merged by concatenating classes in right-to-left order (rightmost class appears first in the string).
+ * The `style` prop is merged with rightmost styles overwriting the prior ones.
  *
  * Props can either be provided as objects or as functions that take the previous props as an argument.
  * The function will receive the merged props up to that point (going from left to right):
@@ -28,10 +32,14 @@ const EMPTY_PROPS = {};
  * They must check `event.baseUIHandlerPrevented` themselves and bail out if it's true.
  *
  * @important **`ref` is not merged.**
- * @param props props to merge.
- * @returns the merged props.
+ * @param a Props object to merge.
+ * @param b Props object to merge. The function will overwrite conflicting props from `a`.
+ * @param c Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @param d Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @param e Props object to merge. The function will overwrite conflicting props from previous parameters.
+ * @returns The merged props.
+ * @public
  */
-/* eslint-disable id-denylist */
 
 function mergeProps(a, b, c, d, e) {
   // We need to mutably own `merged`
@@ -54,6 +62,19 @@ function mergeProps(a, b, c, d, e) {
 }
 /* eslint-enable id-denylist */
 
+/**
+ * Merges an arbitrary number of React props using the same logic as {@link mergeProps}.
+ * This function accepts an array of props instead of individual arguments.
+ *
+ * This has slightly lower performance than {@link mergeProps} due to accepting an array
+ * instead of a fixed number of arguments. Prefer {@link mergeProps} when merging 5 or
+ * fewer prop sets for better performance.
+ *
+ * @param props Array of props to merge.
+ * @returns The merged props.
+ * @see mergeProps
+ * @public
+ */
 function mergePropsN(props) {
   if (props.length === 0) {
     return EMPTY_PROPS;

package/meter/indicator/MeterIndicator.d.ts

@@ -7,7 +7,7 @@ import type { MeterRoot } from "../root/MeterRoot.js";
  *
  * Documentation: [Base UI Meter](https://base-ui.com/react/components/meter)
  */
-export declare const MeterIndicator: React.ForwardRefExoticComponent<MeterIndicatorProps & React.RefAttributes<HTMLDivElement>>;
+export declare const MeterIndicator: React.ForwardRefExoticComponent<Omit<MeterIndicatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface MeterIndicatorProps extends BaseUIComponentProps<'div', MeterRoot.State> {}
 export declare namespace MeterIndicator {
   type Props = MeterIndicatorProps;

package/meter/label/MeterLabel.d.ts

@@ -7,7 +7,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Meter](https://base-ui.com/react/components/meter)
  */
-export declare const MeterLabel: React.ForwardRefExoticComponent<MeterLabelProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const MeterLabel: React.ForwardRefExoticComponent<Omit<MeterLabelProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 export interface MeterLabelProps extends BaseUIComponentProps<'span', MeterRoot.State> {}
 export declare namespace MeterLabel {
   type Props = MeterLabelProps;

package/meter/root/MeterRoot.d.ts

@@ -6,7 +6,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Meter](https://base-ui.com/react/components/meter)
  */
-export declare const MeterRoot: React.ForwardRefExoticComponent<MeterRootProps & React.RefAttributes<HTMLDivElement>>;
+export declare const MeterRoot: React.ForwardRefExoticComponent<Omit<MeterRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface MeterRootState {}
 export interface MeterRootProps extends BaseUIComponentProps<'div', MeterRoot.State> {
   /**

package/meter/track/MeterTrack.d.ts

@@ -7,7 +7,7 @@ import { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Meter](https://base-ui.com/react/components/meter)
  */
-export declare const MeterTrack: React.ForwardRefExoticComponent<MeterTrackProps & React.RefAttributes<HTMLDivElement>>;
+export declare const MeterTrack: React.ForwardRefExoticComponent<Omit<MeterTrackProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface MeterTrackProps extends BaseUIComponentProps<'div', MeterRoot.State> {}
 export declare namespace MeterTrack {
   type Props = MeterTrackProps;

package/meter/value/MeterValue.d.ts

@@ -7,7 +7,7 @@ import type { MeterRoot } from "../root/MeterRoot.js";
  *
  * Documentation: [Base UI Meter](https://base-ui.com/react/components/meter)
  */
-export declare const MeterValue: React.ForwardRefExoticComponent<MeterValueProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const MeterValue: React.ForwardRefExoticComponent<Omit<MeterValueProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 export interface MeterValueProps extends Omit<BaseUIComponentProps<'span', MeterRoot.State>, 'children'> {
   children?: null | ((formattedValue: string, value: number) => React.ReactNode);
 }

package/navigation-menu/arrow/NavigationMenuArrow.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuArrow: React.ForwardRefExoticComponent<NavigationMenuArrowProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuArrow: React.ForwardRefExoticComponent<Omit<NavigationMenuArrowProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuArrowState {
   /**
    * Whether the popup is currently open.

package/navigation-menu/backdrop/NavigationMenuBackdrop.d.ts

@@ -7,7 +7,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuBackdrop: React.ForwardRefExoticComponent<NavigationMenuBackdropProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuBackdrop: React.ForwardRefExoticComponent<Omit<NavigationMenuBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuBackdropState {
   /**
    * If `true`, the popup is open.

package/navigation-menu/content/NavigationMenuContent.d.ts

@@ -8,7 +8,7 @@ import { TransitionStatus } from "../../utils/useTransitionStatus.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuContent: React.ForwardRefExoticComponent<NavigationMenuContentProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuContent: React.ForwardRefExoticComponent<Omit<NavigationMenuContentProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuContentState {
   /**
    * If `true`, the component is open.

package/navigation-menu/content/NavigationMenuContent.js

@@ -65,6 +65,12 @@ const NavigationMenuContent = exports.NavigationMenuContent = /*#__PURE__*/React
     setMounted,
     transitionStatus
   } = (0, _useTransitionStatus.useTransitionStatus)(open);
+
+  // If the popup unmounts before the content's exit animation completes, reset the internal
+  // mounted state so the next open can re-enter via `transitionStatus="starting"`.
+  if (mounted && !popupMounted) {
+    setMounted(false);
+  }
   (0, _useOpenChangeComplete.useOpenChangeComplete)({
     ref,
     open,

package/navigation-menu/icon/NavigationMenuIcon.d.ts

@@ -5,7 +5,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuIcon: React.ForwardRefExoticComponent<NavigationMenuIconProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuIcon: React.ForwardRefExoticComponent<Omit<NavigationMenuIconProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuIconState {
   /**
    * Whether the navigation menu is open and the item is active.

package/navigation-menu/item/NavigationMenuItem.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuItem: React.ForwardRefExoticComponent<NavigationMenuItemProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuItem: React.ForwardRefExoticComponent<Omit<NavigationMenuItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuItemState {}
 export interface NavigationMenuItemProps extends BaseUIComponentProps<'li', NavigationMenuItem.State> {
   /**

package/navigation-menu/link/NavigationMenuLink.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuLink: React.ForwardRefExoticComponent<NavigationMenuLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+export declare const NavigationMenuLink: React.ForwardRefExoticComponent<Omit<NavigationMenuLinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
 export interface NavigationMenuLinkState {
   /**
    * Whether the link is the currently active page.

package/navigation-menu/list/NavigationMenuList.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuList: React.ForwardRefExoticComponent<NavigationMenuListProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuList: React.ForwardRefExoticComponent<Omit<NavigationMenuListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuListState {
   /**
    * If `true`, the popup is open.

package/navigation-menu/popup/NavigationMenuPopup.d.ts

@@ -7,7 +7,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuPopup: React.ForwardRefExoticComponent<NavigationMenuPopupProps & React.RefAttributes<HTMLElement>>;
+export declare const NavigationMenuPopup: React.ForwardRefExoticComponent<Omit<NavigationMenuPopupProps, "ref"> & React.RefAttributes<HTMLElement>>;
 export interface NavigationMenuPopupState {
   /**
    * If `true`, the popup is open.

package/navigation-menu/portal/NavigationMenuPortal.d.ts

@@ -7,7 +7,7 @@ import { FloatingPortal } from "../../floating-ui-react/index.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuPortal: React.ForwardRefExoticComponent<NavigationMenuPortalProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuPortal: React.ForwardRefExoticComponent<Omit<NavigationMenuPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare namespace NavigationMenuPortal {
   interface State {}
 }

package/navigation-menu/positioner/NavigationMenuPositioner.d.ts

@@ -7,7 +7,7 @@ import { useAnchorPositioning, type Align, type Side } from "../../utils/useAnch
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuPositioner: React.ForwardRefExoticComponent<NavigationMenuPositionerProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuPositioner: React.ForwardRefExoticComponent<Omit<NavigationMenuPositionerProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuPositionerState {
   /**
    * Whether the navigation menu is currently open.

package/navigation-menu/root/NavigationMenuRoot.d.ts

@@ -8,7 +8,7 @@ import { REASONS } from "../../utils/reasons.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuRoot: React.ForwardRefExoticComponent<NavigationMenuRootProps & React.RefAttributes<HTMLElement>>;
+export declare const NavigationMenuRoot: React.ForwardRefExoticComponent<Omit<NavigationMenuRootProps, "ref"> & React.RefAttributes<HTMLElement>>;
 export interface NavigationMenuRootState {
   /**
    * If `true`, the popup is open.
@@ -23,7 +23,7 @@ export interface NavigationMenuRootProps extends BaseUIComponentProps<'nav', Nav
   /**
    * A ref to imperative actions.
    */
-  actionsRef?: React.RefObject<NavigationMenuRoot.Actions>;
+  actionsRef?: React.RefObject<NavigationMenuRoot.Actions | null>;
   /**
    * Event handler called after any animations complete when the navigation menu is closed.
    */

package/navigation-menu/trigger/NavigationMenuTrigger.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuTrigger: React.ForwardRefExoticComponent<NavigationMenuTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const NavigationMenuTrigger: React.ForwardRefExoticComponent<Omit<NavigationMenuTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface NavigationMenuTriggerState {
   /**
    * If `true`, the popup is open and the item is active.

package/navigation-menu/viewport/NavigationMenuViewport.d.ts

@@ -6,7 +6,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-export declare const NavigationMenuViewport: React.ForwardRefExoticComponent<NavigationMenuViewportProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NavigationMenuViewport: React.ForwardRefExoticComponent<Omit<NavigationMenuViewportProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NavigationMenuViewportState {}
 export interface NavigationMenuViewportProps extends BaseUIComponentProps<'div', NavigationMenuViewport.State> {}
 export declare namespace NavigationMenuViewport {

package/number-field/decrement/NumberFieldDecrement.d.ts

@@ -7,7 +7,7 @@ import type { NumberFieldRoot } from "../root/NumberFieldRoot.js";
  *
  * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
  */
-export declare const NumberFieldDecrement: React.ForwardRefExoticComponent<NumberFieldDecrementProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const NumberFieldDecrement: React.ForwardRefExoticComponent<Omit<NumberFieldDecrementProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface NumberFieldDecrementState extends NumberFieldRoot.State {}
 export interface NumberFieldDecrementProps extends NativeButtonProps, BaseUIComponentProps<'button', NumberFieldDecrement.State> {}
 export declare namespace NumberFieldDecrement {

package/number-field/decrement/NumberFieldDecrement.js

@@ -37,7 +37,6 @@ const NumberFieldDecrement = exports.NumberFieldDecrement = /*#__PURE__*/React.f
     inputValue,
     intentionalTouchCheckTimeout,
     isPressedRef,
-    maxWithDefault,
     minWithDefault,
     movesAfterTouchRef,
     readOnly,
@@ -51,15 +50,13 @@ const NumberFieldDecrement = exports.NumberFieldDecrement = /*#__PURE__*/React.f
     lastChangedValueRef,
     onValueCommitted
   } = (0, _NumberFieldRootContext.useNumberFieldRootContext)();
-  const disabled = disabledProp || contextDisabled;
+  const isMin = value != null && value <= minWithDefault;
+  const disabled = disabledProp || contextDisabled || isMin;
   const props = (0, _useNumberFieldButton.useNumberFieldButton)({
     isIncrement: false,
     inputRef,
     startAutoChange,
     stopAutoChange,
-    minWithDefault,
-    maxWithDefault,
-    value,
     inputValue,
     disabled,
     readOnly,
@@ -82,7 +79,8 @@ const NumberFieldDecrement = exports.NumberFieldDecrement = /*#__PURE__*/React.f
     buttonRef
   } = (0, _useButton.useButton)({
     disabled,
-    native: nativeButton
+    native: nativeButton,
+    focusableWhenDisabled: true
   });
   const buttonState = React.useMemo(() => ({
     ...state,

package/number-field/group/NumberFieldGroup.d.ts

@@ -7,7 +7,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  *
  * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
  */
-export declare const NumberFieldGroup: React.ForwardRefExoticComponent<NumberFieldGroupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NumberFieldGroup: React.ForwardRefExoticComponent<Omit<NumberFieldGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NumberFieldGroupState extends NumberFieldRoot.State {}
 export interface NumberFieldGroupProps extends BaseUIComponentProps<'div', NumberFieldGroup.State> {}
 export declare namespace NumberFieldGroup {

package/number-field/increment/NumberFieldIncrement.d.ts

@@ -7,7 +7,7 @@ import type { NumberFieldRoot } from "../root/NumberFieldRoot.js";
  *
  * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
  */
-export declare const NumberFieldIncrement: React.ForwardRefExoticComponent<NumberFieldIncrementProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const NumberFieldIncrement: React.ForwardRefExoticComponent<Omit<NumberFieldIncrementProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface NumberFieldIncrementState extends NumberFieldRoot.State {}
 export interface NumberFieldIncrementProps extends NativeButtonProps, BaseUIComponentProps<'button', NumberFieldIncrement.State> {}
 export declare namespace NumberFieldIncrement {

package/number-field/increment/NumberFieldIncrement.js

@@ -39,7 +39,6 @@ const NumberFieldIncrement = exports.NumberFieldIncrement = /*#__PURE__*/React.f
     isPressedRef,
     locale,
     maxWithDefault,
-    minWithDefault,
     movesAfterTouchRef,
     readOnly,
     setValue,
@@ -51,15 +50,13 @@ const NumberFieldIncrement = exports.NumberFieldIncrement = /*#__PURE__*/React.f
     lastChangedValueRef,
     onValueCommitted
   } = (0, _NumberFieldRootContext.useNumberFieldRootContext)();
-  const disabled = disabledProp || contextDisabled;
+  const isMax = value != null && value >= maxWithDefault;
+  const disabled = disabledProp || contextDisabled || isMax;
   const props = (0, _useNumberFieldButton.useNumberFieldButton)({
     isIncrement: true,
     inputRef,
     startAutoChange,
     stopAutoChange,
-    minWithDefault,
-    maxWithDefault,
-    value,
     inputValue,
     disabled,
     readOnly,
@@ -82,7 +79,8 @@ const NumberFieldIncrement = exports.NumberFieldIncrement = /*#__PURE__*/React.f
     buttonRef
   } = (0, _useButton.useButton)({
     disabled,
-    native: nativeButton
+    native: nativeButton,
+    focusableWhenDisabled: true
   });
   const buttonState = React.useMemo(() => ({
     ...state,

package/number-field/input/NumberFieldInput.d.ts

@@ -7,7 +7,7 @@ import type { NumberFieldRoot } from "../root/NumberFieldRoot.js";
  *
  * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
  */
-export declare const NumberFieldInput: React.ForwardRefExoticComponent<NumberFieldInputProps & React.RefAttributes<HTMLInputElement>>;
+export declare const NumberFieldInput: React.ForwardRefExoticComponent<Omit<NumberFieldInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 export interface NumberFieldInputState extends NumberFieldRoot.State {}
 export interface NumberFieldInputProps extends BaseUIComponentProps<'input', NumberFieldInput.State> {
   /**

package/number-field/input/NumberFieldInput.js

@@ -123,11 +123,14 @@ const NumberFieldInput = exports.NumberFieldInput = /*#__PURE__*/React.forwardRe
     // causing a hydration mismatch.
     suppressHydrationWarning: true,
     onFocus(event) {
-      if (event.defaultPrevented || readOnly || disabled || hasTouchedInputRef.current) {
+      if (event.defaultPrevented || readOnly || disabled) {
         return;
       }
-      hasTouchedInputRef.current = true;
       setFocused(true);
+      if (hasTouchedInputRef.current) {
+        return;
+      }
+      hasTouchedInputRef.current = true;
 
       // Browsers set selection at the start of the input field by default. We want to set it at
       // the end for the first focus.

package/number-field/root/NumberFieldRoot.d.ts

@@ -10,7 +10,7 @@ import { REASONS } from "../../utils/reasons.js";
  *
  * Documentation: [Base UI Number Field](https://base-ui.com/react/components/number-field)
  */
-export declare const NumberFieldRoot: React.ForwardRefExoticComponent<NumberFieldRootProps & React.RefAttributes<HTMLDivElement>>;
+export declare const NumberFieldRoot: React.ForwardRefExoticComponent<Omit<NumberFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface NumberFieldRootProps extends Omit<BaseUIComponentProps<'div', NumberFieldRootState>, 'onChange'> {
   /**
    * The id of the input element.
@@ -31,11 +31,12 @@ export interface NumberFieldRootProps extends Omit<BaseUIComponentProps<'div', N
    */
   smallStep?: number;
   /**
-   * Amount to increment and decrement with the buttons and arrow keys,
-   * or to scrub with pointer movement in the scrub area.
+   * Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area.
+   * To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop.
+   * Specify `step="any"` to always disable step validation.
    * @default 1
    */
-  step?: number;
+  step?: number | 'any';
   /**
    * The large step value of the input element when incrementing while the shift key is held. Snaps
    * to multiples of this value.

package/number-field/root/NumberFieldRoot.js

@@ -42,7 +42,7 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
     min,
     max,
     smallStep = 0.1,
-    step = 1,
+    step: stepProp = 1,
     largeStep = 10,
     required = false,
     disabled: disabledProp = false,
@@ -74,6 +74,7 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
   } = (0, _FieldRootContext.useFieldRootContext)();
   const disabled = fieldDisabled || disabledProp;
   const name = fieldName ?? nameProp;
+  const step = stepProp === 'any' ? 1 : stepProp;
   const [isScrubbing, setIsScrubbing] = React.useState(false);
   const minWithDefault = min ?? Number.MIN_SAFE_INTEGER;
   const maxWithDefault = max ?? Number.MAX_SAFE_INTEGER;
@@ -396,6 +397,9 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
     value: contextValue,
     children: [element, /*#__PURE__*/(0, _jsxRuntime.jsx)("input", {
       ...validation.getInputValidationProps({
+        onFocus() {
+          inputRef.current?.focus();
+        },
         onChange(event) {
           // Workaround for https://github.com/facebook/react/issues/9023
           if (event.nativeEvent.defaultPrevented) {
@@ -418,13 +422,16 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
       name: name,
       value: value ?? '',
       min: min,
-      max: max,
-      step: step,
+      max: max
+      // stepMismatch validation is broken unless an explicit `min` is added.
+      // See https://github.com/facebook/react/issues/12334.
+      ,
+      step: stepProp,
       disabled: disabled,
       required: required,
       "aria-hidden": true,
       tabIndex: -1,
-      style: _visuallyHidden.visuallyHidden
+      style: name ? _visuallyHidden.visuallyHiddenInput : _visuallyHidden.visuallyHidden
     })]
   });
 });

package/number-field/root/useNumberFieldButton.d.ts

@@ -17,14 +17,11 @@ export interface UseNumberFieldButtonParameters {
   isIncrement: boolean;
   isPressedRef: React.RefObject<boolean | null>;
   locale?: Intl.LocalesArgument;
-  maxWithDefault: number;
-  minWithDefault: number;
   movesAfterTouchRef: React.RefObject<number | null>;
   readOnly: boolean;
   setValue: (value: number | null, details: NumberFieldRoot.ChangeEventDetails) => void;
   startAutoChange: (isIncrement: boolean, event?: React.MouseEvent | Event) => void;
   stopAutoChange: () => void;
-  value: number | null;
   valueRef: React.RefObject<number | null>;
   lastChangedValueRef: React.RefObject<number | null>;
   onValueCommitted: (value: number | null, eventDetails: NumberFieldRoot.CommitEventDetails) => void;

package/number-field/root/useNumberFieldButton.js

@@ -24,14 +24,11 @@ function useNumberFieldButton(params) {
     isIncrement,
     isPressedRef,
     locale,
-    maxWithDefault,
-    minWithDefault,
     movesAfterTouchRef,
     readOnly,
     setValue,
     startAutoChange,
     stopAutoChange,
-    value,
     valueRef,
     lastChangedValueRef,
     onValueCommitted
@@ -43,8 +40,6 @@ function useNumberFieldButton(params) {
   const isTouchingButtonRef = React.useRef(false);
   const ignoreClickRef = React.useRef(false);
   const pointerTypeRef = React.useRef('');
-  const isMin = value != null && value <= minWithDefault;
-  const isMax = value != null && value >= maxWithDefault;
   const pressReason = isIncrement ? 'increment-press' : 'decrement-press';
   function commitValue(nativeEvent) {
     allowInputSyncRef.current = true;
@@ -61,7 +56,7 @@ function useNumberFieldButton(params) {
     }
   }
   const props = {
-    disabled: disabled || (isIncrement ? isMax : isMin),
+    disabled,
     'aria-readonly': readOnly || undefined,
     'aria-label': isIncrement ? 'Increase' : 'Decrease',
     'aria-controls': id,
@@ -80,7 +75,7 @@ function useNumberFieldButton(params) {
       isTouchingButtonRef.current = false;
     },
     onClick(event) {
-      const isDisabled = disabled || readOnly || (isIncrement ? isMax : isMin);
+      const isDisabled = disabled || readOnly;
       if (event.defaultPrevented || isDisabled || (
       // If it's not a keyboard/virtual click, ignore.
       pointerTypeRef.current === 'touch' ? ignoreClickRef.current : event.detail !== 0)) {
@@ -101,8 +96,7 @@ function useNumberFieldButton(params) {
     },
     onPointerDown(event) {
       const isMainButton = !event.button || event.button === 0;
-      const isDisabled = disabled || (isIncrement ? isMax : isMin);
-      if (event.defaultPrevented || readOnly || !isMainButton || isDisabled) {
+      if (event.defaultPrevented || readOnly || !isMainButton || disabled) {
         return;
       }
       pointerTypeRef.current = event.pointerType;
@@ -148,7 +142,7 @@ function useNumberFieldButton(params) {
       }
     },
     onPointerMove(event) {
-      const isDisabled = disabled || readOnly || (isIncrement ? isMax : isMin);
+      const isDisabled = disabled || readOnly;
       if (isDisabled || event.pointerType !== 'touch' || !isPressedRef.current) {
         return;
       }
@@ -169,7 +163,7 @@ function useNumberFieldButton(params) {
       }
     },
     onMouseEnter(event) {
-      const isDisabled = disabled || readOnly || (isIncrement ? isMax : isMin);
+      const isDisabled = disabled || readOnly;
       if (event.defaultPrevented || isDisabled || !isPressedRef.current || isTouchingButtonRef.current || pointerTypeRef.current === 'touch') {
         return;
       }