@base-ui/react 1.4.0 → 1.5.0

package/esm/slider/value/SliderValueDataAttributes.js

@@ -13,11 +13,11 @@ export let SliderValueDataAttributes = /*#__PURE__*/function (SliderValueDataAtt
    */
   SliderValueDataAttributes["disabled"] = "data-disabled";
   /**
-   * Present when the slider is in valid state (when wrapped in Field.Root).
+   * Present when the slider is in a valid state (when wrapped in Field.Root).
    */
   SliderValueDataAttributes["valid"] = "data-valid";
   /**
-   * Present when the slider is in invalid state (when wrapped in Field.Root).
+   * Present when the slider is in an invalid state (when wrapped in Field.Root).
    */
   SliderValueDataAttributes["invalid"] = "data-invalid";
   /**

package/esm/switch/root/SwitchRoot.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
-import type { BaseUIComponentProps, NonNativeButtonProps } from "../../utils/types.js";
+import type { BaseUIComponentProps, NonNativeButtonProps } from "../../internals/types.js";
 import type { FieldRootState } from "../../field/root/FieldRoot.js";
-import { REASONS } from "../../utils/reasons.js";
+import { REASONS } from "../../internals/reasons.js";
 import type { BaseUIChangeEventDetails } from "../../types/index.js";
 /**
  * Represents the switch itself.

package/esm/switch/root/SwitchRoot.js

@@ -2,26 +2,26 @@
 
 import * as React from 'react';
 import { useControlled } from '@base-ui/utils/useControlled';
-import { useStableCallback } from '@base-ui/utils/useStableCallback';
 import { useMergedRefs } from '@base-ui/utils/useMergedRefs';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { visuallyHidden, visuallyHiddenInput } from '@base-ui/utils/visuallyHidden';
 import { EMPTY_OBJECT } from '@base-ui/utils/empty';
-import { useRenderElement } from "../../utils/useRenderElement.js";
+import { ownerWindow } from '@base-ui/utils/owner';
+import { useRenderElement } from "../../internals/useRenderElement.js";
 import { mergeProps } from "../../merge-props/index.js";
-import { useBaseUiId } from "../../utils/useBaseUiId.js";
-import { useButton } from "../../use-button/index.js";
+import { useBaseUiId } from "../../internals/useBaseUiId.js";
+import { useButton } from "../../internals/use-button/index.js";
 import { SwitchRootContext } from "./SwitchRootContext.js";
 import { stateAttributesMapping } from "../stateAttributesMapping.js";
-import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
-import { useRegisterFieldControl } from "../../field/root/useRegisterFieldControl.js";
-import { useFormContext } from "../../form/FormContext.js";
-import { useLabelableContext } from "../../labelable-provider/LabelableContext.js";
-import { useAriaLabelledBy } from "../../labelable-provider/useAriaLabelledBy.js";
-import { useLabelableId } from "../../labelable-provider/useLabelableId.js";
-import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
-import { REASONS } from "../../utils/reasons.js";
-import { useValueChanged } from "../../utils/useValueChanged.js";
+import { useFieldRootContext } from "../../internals/field-root-context/FieldRootContext.js";
+import { useRegisterFieldControl } from "../../internals/field-register-control/useRegisterFieldControl.js";
+import { useFormContext } from "../../internals/form-context/FormContext.js";
+import { useLabelableContext } from "../../internals/labelable-provider/LabelableContext.js";
+import { useAriaLabelledBy } from "../../internals/labelable-provider/useAriaLabelledBy.js";
+import { useLabelableId } from "../../internals/labelable-provider/useLabelableId.js";
+import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
+import { useValueChanged } from "../../internals/useValueChanged.js";
 
 /**
  * Represents the switch itself.
@@ -41,7 +41,7 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
     inputRef: externalInputRef,
     name: nameProp,
     nativeButton = false,
-    onCheckedChange: onCheckedChangeProp,
+    onCheckedChange,
     readOnly = false,
     required = false,
     disabled: disabledProp = false,
@@ -72,7 +72,6 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
   } = useLabelableContext();
   const disabled = fieldDisabled || disabledProp;
   const name = fieldName ?? nameProp;
-  const onCheckedChange = useStableCallback(onCheckedChangeProp);
   const inputRef = React.useRef(null);
   const handleInputRef = useMergedRefs(inputRef, externalInputRef, validation.inputRef);
   const switchRef = React.useRef(null);
@@ -89,10 +88,7 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
     name: 'Switch',
     state: 'checked'
   });
-  useRegisterFieldControl(switchRef, {
-    id,
-    value: checked
-  });
+  useRegisterFieldControl(switchRef, id, checked);
   useIsoLayoutEffect(() => {
     if (inputRef.current) {
       setFilled(inputRef.current.checked);
@@ -144,7 +140,11 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
         return;
       }
       event.preventDefault();
-      inputRef.current?.dispatchEvent(new PointerEvent('click', {
+      const input = inputRef.current;
+      if (!input) {
+        return;
+      }
+      input.dispatchEvent(new (ownerWindow(input).PointerEvent)('click', {
         bubbles: true,
         shiftKey: event.shiftKey,
         ctrlKey: event.ctrlKey,
@@ -153,7 +153,7 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
       }));
     }
   };
-  const inputProps = React.useMemo(() => mergeProps({
+  const inputProps = mergeProps({
     checked,
     disabled,
     form,
@@ -190,7 +190,7 @@ export const SwitchRoot = /*#__PURE__*/React.forwardRef(function SwitchRoot(comp
   // To avoid this, we only set the value if it's defined
   value !== undefined ? {
     value
-  } : EMPTY_OBJECT), [checked, disabled, form, handleInputRef, hiddenInputId, name, onCheckedChange, readOnly, required, setCheckedState, validation, value]);
+  } : EMPTY_OBJECT);
   const state = React.useMemo(() => ({
     ...fieldState,
     checked,

package/esm/switch/root/SwitchRootDataAttributes.d.ts

@@ -20,11 +20,11 @@ export declare enum SwitchRootDataAttributes {
    */
   required = "data-required",
   /**
-   * Present when the switch is in valid state (when wrapped in Field.Root).
+   * Present when the switch is in a valid state (when wrapped in Field.Root).
    */
   valid = "data-valid",
   /**
-   * Present when the switch is in invalid state (when wrapped in Field.Root).
+   * Present when the switch is in an invalid state (when wrapped in Field.Root).
    */
   invalid = "data-invalid",
   /**

package/esm/switch/root/SwitchRootDataAttributes.js

@@ -20,11 +20,11 @@ export let SwitchRootDataAttributes = /*#__PURE__*/function (SwitchRootDataAttri
    */
   SwitchRootDataAttributes["required"] = "data-required";
   /**
-   * Present when the switch is in valid state (when wrapped in Field.Root).
+   * Present when the switch is in a valid state (when wrapped in Field.Root).
    */
   SwitchRootDataAttributes["valid"] = "data-valid";
   /**
-   * Present when the switch is in invalid state (when wrapped in Field.Root).
+   * Present when the switch is in an invalid state (when wrapped in Field.Root).
    */
   SwitchRootDataAttributes["invalid"] = "data-invalid";
   /**

package/esm/switch/stateAttributesMapping.d.ts

@@ -1,3 +1,3 @@
 import type { SwitchRootState } from "./root/SwitchRoot.js";
-import type { StateAttributesMapping } from "../utils/getStateAttributesProps.js";
+import type { StateAttributesMapping } from "../internals/getStateAttributesProps.js";
 export declare const stateAttributesMapping: StateAttributesMapping<SwitchRootState>;

package/esm/switch/stateAttributesMapping.js

@@ -1,4 +1,4 @@
-import { fieldValidityMapping } from "../field/utils/constants.js";
+import { fieldValidityMapping } from "../internals/field-constants/constants.js";
 import { SwitchRootDataAttributes } from "./root/SwitchRootDataAttributes.js";
 export const stateAttributesMapping = {
   ...fieldValidityMapping,

package/esm/switch/thumb/SwitchThumb.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { SwitchRootState } from "../root/SwitchRoot.js";
-import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { BaseUIComponentProps } from "../../internals/types.js";
 /**
  * The movable part of the switch that indicates whether the switch is on or off.
  * Renders a `<span>`.

package/esm/switch/thumb/SwitchThumb.js

@@ -2,8 +2,7 @@
 
 import * as React from 'react';
 import { useSwitchRootContext } from "../root/SwitchRootContext.js";
-import { useRenderElement } from "../../utils/useRenderElement.js";
-import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
 import { stateAttributesMapping } from "../stateAttributesMapping.js";
 
 /**
@@ -19,16 +18,9 @@ export const SwitchThumb = /*#__PURE__*/React.forwardRef(function SwitchThumb(co
     style,
     ...elementProps
   } = componentProps;
-  const {
-    state: fieldState
-  } = useFieldRootContext();
   const state = useSwitchRootContext();
-  const extendedState = {
-    ...fieldState,
-    ...state
-  };
   return useRenderElement('span', componentProps, {
-    state: extendedState,
+    state,
     ref: forwardedRef,
     stateAttributesMapping,
     props: elementProps

package/esm/switch/thumb/SwitchThumbDataAttributes.d.ts

@@ -20,11 +20,11 @@ export declare enum SwitchThumbDataAttributes {
    */
   required = "data-required",
   /**
-   * Present when the switch is in valid state (when wrapped in Field.Root).
+   * Present when the switch is in a valid state (when wrapped in Field.Root).
    */
   valid = "data-valid",
   /**
-   * Present when the switch is in invalid state (when wrapped in Field.Root).
+   * Present when the switch is in an invalid state (when wrapped in Field.Root).
    */
   invalid = "data-invalid",
   /**

package/esm/switch/thumb/SwitchThumbDataAttributes.js

@@ -20,11 +20,11 @@ export let SwitchThumbDataAttributes = /*#__PURE__*/function (SwitchThumbDataAtt
    */
   SwitchThumbDataAttributes["required"] = "data-required";
   /**
-   * Present when the switch is in valid state (when wrapped in Field.Root).
+   * Present when the switch is in a valid state (when wrapped in Field.Root).
    */
   SwitchThumbDataAttributes["valid"] = "data-valid";
   /**
-   * Present when the switch is in invalid state (when wrapped in Field.Root).
+   * Present when the switch is in an invalid state (when wrapped in Field.Root).
    */
   SwitchThumbDataAttributes["invalid"] = "data-invalid";
   /**

package/esm/tabs/indicator/TabsIndicator.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { BaseUIComponentProps } from "../../internals/types.js";
 import type { TabsRoot, TabsRootState } from "../root/TabsRoot.js";
 import type { TabsTab } from "../tab/TabsTab.js";
 /**

package/esm/tabs/indicator/TabsIndicator.js

@@ -2,7 +2,7 @@
 
 import * as React from 'react';
 import { useForcedRerendering } from '@base-ui/utils/useForcedRerendering';
-import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
 import { getCssDimensions } from "../../utils/getCssDimensions.js";
 import { useIsHydrating } from "../../utils/useIsHydrating.js";
 import { useTabsRootContext } from "../root/TabsRootContext.js";
@@ -10,7 +10,7 @@ import { tabsStateAttributesMapping } from "../root/stateAttributesMapping.js";
 import { useTabsListContext } from "../list/TabsListContext.js";
 import { script as prehydrationScript } from "./prehydrationScript.min.js";
 import { TabsIndicatorCssVars } from "./TabsIndicatorCssVars.js";
-import { useCSPContext } from "../../csp-provider/CSPContext.js";
+import { useCSPContext } from "../../internals/csp-context/CSPContext.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const stateAttributesMapping = {
   ...tabsStateAttributesMapping,
@@ -24,7 +24,7 @@ const stateAttributesMapping = {
  *
  * Documentation: [Base UI Tabs](https://base-ui.com/react/components/tabs)
  */
-export const TabsIndicator = /*#__PURE__*/React.forwardRef(function TabIndicator(componentProps, forwardedRef) {
+export const TabsIndicator = /*#__PURE__*/React.forwardRef(function TabsIndicator(componentProps, forwardedRef) {
   const {
     className,
     render,
@@ -89,29 +89,24 @@ export const TabsIndicator = /*#__PURE__*/React.forwardRef(function TabIndicator
       bottom = tabsListElement.scrollHeight - top - height;
     }
   }
-  const activeTabPosition = React.useMemo(() => isTabSelected ? {
+  const activeTabPosition = isTabSelected ? {
     left,
     right,
     top,
     bottom
-  } : null, [left, right, top, bottom, isTabSelected]);
-  const activeTabSize = React.useMemo(() => isTabSelected ? {
+  } : null;
+  const activeTabSize = isTabSelected ? {
     width,
     height
-  } : null, [width, height, isTabSelected]);
-  const style = React.useMemo(() => {
-    if (!isTabSelected) {
-      return undefined;
-    }
-    return {
-      [TabsIndicatorCssVars.activeTabLeft]: `${left}px`,
-      [TabsIndicatorCssVars.activeTabRight]: `${right}px`,
-      [TabsIndicatorCssVars.activeTabTop]: `${top}px`,
-      [TabsIndicatorCssVars.activeTabBottom]: `${bottom}px`,
-      [TabsIndicatorCssVars.activeTabWidth]: `${width}px`,
-      [TabsIndicatorCssVars.activeTabHeight]: `${height}px`
-    };
-  }, [left, right, top, bottom, width, height, isTabSelected]);
+  } : null;
+  const style = isTabSelected ? {
+    [TabsIndicatorCssVars.activeTabLeft]: `${left}px`,
+    [TabsIndicatorCssVars.activeTabRight]: `${right}px`,
+    [TabsIndicatorCssVars.activeTabTop]: `${top}px`,
+    [TabsIndicatorCssVars.activeTabBottom]: `${bottom}px`,
+    [TabsIndicatorCssVars.activeTabWidth]: `${width}px`,
+    [TabsIndicatorCssVars.activeTabHeight]: `${height}px`
+  } : undefined;
   const displayIndicator = isTabSelected && width > 0 && height > 0;
   const state = {
     orientation,

package/esm/tabs/list/TabsList.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { BaseUIComponentProps } from "../../utils/types.js";
+import { BaseUIComponentProps } from "../../internals/types.js";
 import type { TabsRootState } from "../root/TabsRoot.js";
 /**
  * Groups the individual tab buttons.

package/esm/tabs/list/TabsList.js

@@ -2,11 +2,11 @@
 
 import * as React from 'react';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
-import { CompositeRoot } from "../../composite/root/CompositeRoot.js";
+import { EMPTY_ARRAY } from '@base-ui/utils/empty';
+import { CompositeRoot } from "../../internals/composite/root/CompositeRoot.js";
 import { tabsStateAttributesMapping } from "../root/stateAttributesMapping.js";
 import { useTabsRootContext } from "../root/TabsRootContext.js";
 import { TabsListContext } from "./TabsListContext.js";
-import { EMPTY_ARRAY } from "../../utils/constants.js";
 
 /**
  * Groups the individual tab buttons.
@@ -36,20 +36,14 @@ export const TabsList = /*#__PURE__*/React.forwardRef(function TabsList(componen
   const indicatorUpdateListenersRef = React.useRef(new Set());
   const tabResizeObserverElementsRef = React.useRef(new Set());
   const resizeObserverRef = React.useRef(null);
-  const notifyIndicatorUpdateListeners = useStableCallback(() => {
-    indicatorUpdateListenersRef.current.forEach(listener => {
-      listener();
-    });
-  });
   React.useEffect(() => {
     if (typeof ResizeObserver === 'undefined') {
       return undefined;
     }
     const resizeObserver = new ResizeObserver(() => {
-      if (!indicatorUpdateListenersRef.current.size) {
-        return;
-      }
-      notifyIndicatorUpdateListeners();
+      indicatorUpdateListenersRef.current.forEach(listener => {
+        listener();
+      });
     });
     resizeObserverRef.current = resizeObserver;
     if (tabsListElement) {
@@ -62,7 +56,7 @@ export const TabsList = /*#__PURE__*/React.forwardRef(function TabsList(componen
       resizeObserver.disconnect();
       resizeObserverRef.current = null;
     };
-  }, [tabsListElement, notifyIndicatorUpdateListeners]);
+  }, [tabsListElement]);
   const registerIndicatorUpdateListener = useStableCallback(listener => {
     indicatorUpdateListenersRef.current.add(listener);
     return () => {

package/esm/tabs/list/TabsListContext.d.ts

@@ -1,11 +1,12 @@
 import * as React from 'react';
 import type { TabsRoot } from "../root/TabsRoot.js";
+import type { TabsTab } from "../tab/TabsTab.js";
 export interface TabsListContext {
   activateOnFocus: boolean;
   highlightedTabIndex: number;
   registerIndicatorUpdateListener: (listener: () => void) => () => void;
   registerTabResizeObserverElement: (element: HTMLElement) => () => void;
-  onTabActivation: (newValue: any, eventDetails: TabsRoot.ChangeEventDetails) => void;
+  onTabActivation: (newValue: TabsTab.Value, eventDetails: TabsRoot.ChangeEventDetails) => void;
   setHighlightedTabIndex: (index: number) => void;
   tabsListElement: HTMLElement | null;
 }

package/esm/tabs/panel/TabsPanel.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
-import type { BaseUIComponentProps } from "../../utils/types.js";
+import { type TransitionStatus } from "../../internals/useTransitionStatus.js";
+import type { BaseUIComponentProps } from "../../internals/types.js";
 import type { TabsRootState } from "../root/TabsRoot.js";
 import type { TabsTab } from "../tab/TabsTab.js";
 /**

package/esm/tabs/panel/TabsPanel.js

@@ -3,12 +3,12 @@
 import * as React from 'react';
 import { inertValue } from '@base-ui/utils/inertValue';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
-import { useBaseUiId } from "../../utils/useBaseUiId.js";
-import { transitionStatusMapping } from "../../utils/stateAttributesMapping.js";
-import { useOpenChangeComplete } from "../../utils/useOpenChangeComplete.js";
-import { useTransitionStatus } from "../../utils/useTransitionStatus.js";
-import { useRenderElement } from "../../utils/useRenderElement.js";
-import { useCompositeListItem } from "../../composite/list/useCompositeListItem.js";
+import { useBaseUiId } from "../../internals/useBaseUiId.js";
+import { transitionStatusMapping } from "../../internals/stateAttributesMapping.js";
+import { useOpenChangeComplete } from "../../internals/useOpenChangeComplete.js";
+import { useTransitionStatus } from "../../internals/useTransitionStatus.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
+import { useCompositeListItem } from "../../internals/composite/list/useCompositeListItem.js";
 import { tabsStateAttributesMapping } from "../root/stateAttributesMapping.js";
 import { useTabsRootContext } from "../root/TabsRootContext.js";
 import { TabsPanelDataAttributes } from "./TabsPanelDataAttributes.js";
@@ -23,7 +23,7 @@ const stateAttributesMapping = {
  *
  * Documentation: [Base UI Tabs](https://base-ui.com/react/components/tabs)
  */
-export const TabsPanel = /*#__PURE__*/React.forwardRef(function TabPanel(componentProps, forwardedRef) {
+export const TabsPanel = /*#__PURE__*/React.forwardRef(function TabsPanel(componentProps, forwardedRef) {
   const {
     className,
     value,

package/esm/tabs/panel/TabsPanelDataAttributes.js

@@ -1,4 +1,4 @@
-import { TransitionStatusDataAttributes } from "../../utils/stateAttributesMapping.js";
+import { TransitionStatusDataAttributes } from "../../internals/stateAttributesMapping.js";
 export let TabsPanelDataAttributes = function (TabsPanelDataAttributes) {
   /**
    * Indicates the index of the tab panel.

package/esm/tabs/root/TabsRoot.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import type { BaseUIComponentProps, Orientation as BaseOrientation } from "../../utils/types.js";
+import type { BaseUIComponentProps, Orientation as BaseOrientation } from "../../internals/types.js";
 import type { TabsTab } from "../tab/TabsTab.js";
-import { type BaseUIChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
-import { REASONS } from "../../utils/reasons.js";
+import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
 /**
  * Groups the tabs and the corresponding panels.
  * Renders a `<div>` element.
@@ -40,10 +40,25 @@ export interface TabsRootProps extends BaseUIComponentProps<'div', TabsRootState
   orientation?: TabsRoot.Orientation | undefined;
   /**
    * Callback invoked when new value is being set.
+   *
+   * The event `reason` is `'none'` for user-initiated changes, such as a click
+   * or keyboard navigation; `'initial'` for the first automatic selection or
+   * fallback in uncontrolled roots when `defaultValue` is omitted or
+   * `undefined`, including when the implicit initial value is disabled or
+   * missing; `'disabled'` for automatic fallback when the selected tab becomes
+   * disabled in uncontrolled roots; or `'missing'` for automatic fallback when
+   * the selected tab is removed, or when an explicit `defaultValue` never
+   * matches a mounted tab in uncontrolled roots.
+   *
+   * For automatic changes, the selected value can be `null` when no enabled Tab
+   * is available as a fallback.
+   *
+   * Automatic changes cannot be canceled; calling `eventDetails.cancel()` for
+   * `'initial'`, `'disabled'`, or `'missing'` has no effect.
    */
   onValueChange?: ((value: TabsTab.Value, eventDetails: TabsRoot.ChangeEventDetails) => void) | undefined;
 }
-export type TabsRootChangeEventReason = typeof REASONS.none;
+export type TabsRootChangeEventReason = typeof REASONS.none | typeof REASONS.disabled | typeof REASONS.missing | typeof REASONS.initial;
 export type TabsRootChangeEventDetails = BaseUIChangeEventDetails<TabsRoot.ChangeEventReason, {
   activationDirection: TabsTab.ActivationDirection;
 }>;

package/esm/tabs/root/TabsRoot.js

@@ -4,17 +4,20 @@ import * as React from 'react';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useStableCallback } from '@base-ui/utils/useStableCallback';
-import { useRenderElement } from "../../utils/useRenderElement.js";
-import { CompositeList } from "../../composite/list/CompositeList.js";
+import { useRenderElement } from "../../internals/useRenderElement.js";
+import { CompositeList } from "../../internals/composite/list/CompositeList.js";
 import { TabsRootContext } from "./TabsRootContext.js";
 import { tabsStateAttributesMapping } from "./stateAttributesMapping.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
+
 /**
  * Groups the tabs and the corresponding panels.
  * Renders a `<div>` element.
  *
  * Documentation: [Base UI Tabs](https://base-ui.com/react/components/tabs)
  */
+import { jsx as _jsx } from "react/jsx-runtime";
 export const TabsRoot = /*#__PURE__*/React.forwardRef(function TabsRoot(componentProps, forwardedRef) {
   const {
     className,
@@ -27,9 +30,9 @@ export const TabsRoot = /*#__PURE__*/React.forwardRef(function TabsRoot(componen
     ...elementProps
   } = componentProps;
 
-  // Track whether the user explicitly provided a `defaultValue` prop.
+  // Track whether the user explicitly provided a defined `defaultValue` prop.
   // Used to determine if we should honor a disabled tab selection.
-  const hasExplicitDefaultValueProp = Object.hasOwn(componentProps, 'defaultValue');
+  const hasExplicitDefaultValueProp = componentProps.defaultValue !== undefined;
   const tabPanelRefs = React.useRef([]);
   const [mountedTabPanels, setMountedTabPanels] = React.useState(() => new Map());
   const [value, setValue] = useControlled({
@@ -97,6 +100,11 @@ export const TabsRoot = /*#__PURE__*/React.forwardRef(function TabsRoot(componen
     }
     setValue(newValue);
   });
+  const notifyAutomaticValueChange = useStableCallback((nextValue, reason) => {
+    onValueChangeProp?.(nextValue, createChangeEventDetails(reason, undefined, undefined, {
+      activationDirection: 'none'
+    }));
+  });
   const registerMountedTabPanel = useStableCallback((panelValue, panelId) => {
     setMountedTabPanels(prev => {
       if (prev.get(panelValue) === panelId) {
@@ -164,38 +172,78 @@ export const TabsRoot = /*#__PURE__*/React.forwardRef(function TabsRoot(componen
     return undefined;
   }, [tabMap]);
 
-  // Automatically switch to the first enabled tab when:
-  // - The current selection is disabled (and wasn't explicitly set via defaultValue)
-  // - The current selection is missing (tab was removed from DOM)
-  // Falls back to null if all tabs are disabled.
+  // Implicit uncontrolled selections are still automatic changes, so notify
+  // once when the tabs first register. Explicit defaults are treated as user-owned.
+  const shouldNotifyInitialValueChangeRef = React.useRef(!hasExplicitDefaultValueProp);
+  // An explicit defaultValue can intentionally point at a disabled tab on mount.
+  // Once that selection becomes valid, later disabled states should fall back.
+  const shouldHonorDisabledDefaultValueRef = React.useRef(hasExplicitDefaultValueProp);
+  const didRegisterTabsRef = React.useRef(false);
+
+  // Uncontrolled roots own automatic fallback. Controlled roots keep the exact
+  // value supplied by the parent, even when that tab is disabled or missing.
   useIsoLayoutEffect(() => {
-    if (isControlled || tabMap.size === 0) {
+    if (isControlled) {
+      return;
+    }
+    function commitAutomaticValueChange(fallbackValue, fallbackReason) {
+      setValue(fallbackValue);
+      // Automatic fallbacks are not directional transitions; reset the direction
+      // alongside the value so the batched commit keeps both in sync.
+      setActivationDirectionState(prev => {
+        if (prev.previousValue === fallbackValue && prev.tabActivationDirection === 'none') {
+          return prev;
+        }
+        return {
+          previousValue: fallbackValue,
+          tabActivationDirection: 'none'
+        };
+      });
+      notifyAutomaticValueChange(fallbackValue, fallbackReason);
+      // Mark the initial notification as delivered only after the consumer
+      // callback returns. The fallback value is queued first so automatic
+      // consistency updates are not cancelable through a throwing handler.
+      shouldNotifyInitialValueChangeRef.current = false;
+    }
+    if (tabMap.size === 0) {
+      if (!didRegisterTabsRef.current || value === null) {
+        return;
+      }
+      commitAutomaticValueChange(null, REASONS.missing);
       return;
     }
+    didRegisterTabsRef.current = true;
     const selectionIsDisabled = selectedTabMetadata?.disabled;
     const selectionIsMissing = selectedTabMetadata == null && value !== null;
-    const shouldHonorExplicitDefaultSelection = hasExplicitDefaultValueProp && selectionIsDisabled && value === defaultValueProp;
-    if (shouldHonorExplicitDefaultSelection) {
-      return;
+    if (!selectionIsDisabled && value === defaultValueProp) {
+      shouldHonorDisabledDefaultValueRef.current = false;
     }
-    if (!selectionIsDisabled && !selectionIsMissing) {
+    if (shouldHonorDisabledDefaultValueRef.current && selectionIsDisabled && value === defaultValueProp) {
       return;
     }
-    const fallbackValue = firstEnabledTabValue ?? null;
-    if (value === fallbackValue) {
+    const shouldNotifyInitialValueChange = shouldNotifyInitialValueChangeRef.current;
+    if (selectionIsDisabled || selectionIsMissing) {
+      const fallbackValue = firstEnabledTabValue ?? null;
+      if (value === fallbackValue) {
+        // Already at the fallback value; no commit or notification needed,
+        // but record that the implicit-initial transition has resolved.
+        shouldNotifyInitialValueChangeRef.current = false;
+        return;
+      }
+      let fallbackReason = REASONS.missing;
+      if (shouldNotifyInitialValueChange) {
+        fallbackReason = REASONS.initial;
+      } else if (selectionIsDisabled) {
+        fallbackReason = REASONS.disabled;
+      }
+      commitAutomaticValueChange(fallbackValue, fallbackReason);
       return;
     }
-    setValue(fallbackValue);
-    setActivationDirectionState(prev => {
-      if (prev.tabActivationDirection === 'none') {
-        return prev;
-      }
-      return {
-        ...prev,
-        tabActivationDirection: 'none'
-      };
-    });
-  }, [defaultValueProp, firstEnabledTabValue, hasExplicitDefaultValueProp, isControlled, selectedTabMetadata, setValue, tabMap, value]);
+    if (shouldNotifyInitialValueChange && selectedTabMetadata != null) {
+      notifyAutomaticValueChange(value, REASONS.initial);
+      shouldNotifyInitialValueChangeRef.current = false;
+    }
+  }, [defaultValueProp, firstEnabledTabValue, isControlled, notifyAutomaticValueChange, selectedTabMetadata, setValue, tabMap, value]);
   const state = {
     orientation,
     tabActivationDirection

package/esm/tabs/root/TabsRootContext.d.ts

@@ -20,12 +20,10 @@ export interface TabsRootContext {
   getTabElementBySelectedValue: (selectedValue: TabsTab.Value | undefined) => HTMLElement | null;
   /**
    * Gets the `id` attribute of the Tab that corresponds to the given TabPanel value.
-   * @param (any) panelValue Value to find the Tab for.
    */
   getTabIdByPanelValue: (panelValue: TabsTab.Value) => string | undefined;
   /**
    * Gets the `id` attribute of the TabPanel that corresponds to the given Tab value.
-   * @param (any) tabValue Value to find the TabPanel for.
    */
   getTabPanelIdByValue: (tabValue: TabsTab.Value) => string | undefined;
   registerMountedTabPanel: (panelValue: TabsTab.Value | number, panelId: string) => void;

package/esm/tabs/root/stateAttributesMapping.d.ts

@@ -1,3 +1,3 @@
 import type { TabsRootState } from "./TabsRoot.js";
-import type { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
+import type { StateAttributesMapping } from "../../internals/getStateAttributesProps.js";
 export declare const tabsStateAttributesMapping: StateAttributesMapping<TabsRootState>;