@base-ui/react 1.2.0 → 1.3.0

package/esm/scroll-area/scrollbar/ScrollAreaScrollbar.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { BaseUIComponentProps } from "../../utils/types.js";
-import type { ScrollAreaRoot } from "../root/ScrollAreaRoot.js";
+import type { ScrollAreaRootState } from "../root/ScrollAreaRoot.js";
 /**
  * A vertical or horizontal scrollbar for the scroll area.
  * Renders a `<div>` element.
@@ -8,20 +8,26 @@ import type { ScrollAreaRoot } from "../root/ScrollAreaRoot.js";
  * Documentation: [Base UI Scroll Area](https://base-ui.com/react/components/scroll-area)
  */
 export declare const ScrollAreaScrollbar: React.ForwardRefExoticComponent<Omit<ScrollAreaScrollbarProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface ScrollAreaScrollbarState extends ScrollAreaRoot.State {
-  /** Whether the scroll area is being hovered. */
+export interface ScrollAreaScrollbarState extends ScrollAreaRootState {
+  /**
+   * Whether the scroll area is being hovered.
+   */
   hovering: boolean;
-  /** Whether the scroll area is being scrolled. */
+  /**
+   * Whether the scroll area is being scrolled.
+   */
   scrolling: boolean;
-  /** The orientation of the scrollbar. */
+  /**
+   * The orientation of the scrollbar.
+   */
   orientation: 'vertical' | 'horizontal';
 }
-export interface ScrollAreaScrollbarProps extends BaseUIComponentProps<'div', ScrollAreaScrollbar.State> {
+export interface ScrollAreaScrollbarProps extends BaseUIComponentProps<'div', ScrollAreaScrollbarState> {
   /**
    * Whether the scrollbar controls vertical or horizontal scroll.
    * @default 'vertical'
    */
-  orientation?: ('vertical' | 'horizontal') | undefined;
+  orientation?: 'vertical' | 'horizontal' | undefined;
   /**
    * Whether to keep the HTML element in the DOM when the viewport isn’t scrollable.
    * @default false

package/esm/scroll-area/scrollbar/ScrollAreaScrollbar.js

@@ -38,7 +38,8 @@ export const ScrollAreaScrollbar = /*#__PURE__*/React.forwardRef(function Scroll
     handlePointerDown,
     handlePointerUp,
     rootId,
-    thumbSize
+    thumbSize,
+    hasMeasuredScrollbar
   } = useScrollAreaRootContext();
   const state = {
     hovering,
@@ -56,6 +57,7 @@ export const ScrollAreaScrollbar = /*#__PURE__*/React.forwardRef(function Scroll
     cornerHidden: hiddenState.corner
   };
   const direction = useDirection();
+  const hideTrackUntilMeasured = !hasMeasuredScrollbar && !keepMounted;
   React.useEffect(() => {
     const viewportEl = viewportRef.current;
     const scrollbarEl = orientation === 'vertical' ? scrollbarYRef.current : scrollbarXRef.current;
@@ -157,6 +159,7 @@ export const ScrollAreaScrollbar = /*#__PURE__*/React.forwardRef(function Scroll
       touchAction: 'none',
       WebkitUserSelect: 'none',
       userSelect: 'none',
+      visibility: hideTrackUntilMeasured ? 'hidden' : undefined,
       ...(orientation === 'vertical' && {
         top: 0,
         bottom: `var(${ScrollAreaRootCssVars.scrollAreaCornerHeight})`,

package/esm/scroll-area/thumb/ScrollAreaThumb.d.ts

@@ -8,9 +8,12 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  */
 export declare const ScrollAreaThumb: React.ForwardRefExoticComponent<Omit<ScrollAreaThumbProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface ScrollAreaThumbState {
-  orientation?: ('horizontal' | 'vertical') | undefined;
+  /**
+   * The component orientation.
+   */
+  orientation?: 'horizontal' | 'vertical' | undefined;
 }
-export interface ScrollAreaThumbProps extends BaseUIComponentProps<'div', ScrollAreaThumb.State> {}
+export interface ScrollAreaThumbProps extends BaseUIComponentProps<'div', ScrollAreaThumbState> {}
 export declare namespace ScrollAreaThumb {
   type State = ScrollAreaThumbState;
   type Props = ScrollAreaThumbProps;

package/esm/scroll-area/thumb/ScrollAreaThumb.js

@@ -25,7 +25,8 @@ export const ScrollAreaThumb = /*#__PURE__*/React.forwardRef(function ScrollArea
     handlePointerMove,
     handlePointerUp,
     setScrollingX,
-    setScrollingY
+    setScrollingY,
+    hasMeasuredScrollbar
   } = useScrollAreaRootContext();
   const {
     orientation
@@ -49,6 +50,7 @@ export const ScrollAreaThumb = /*#__PURE__*/React.forwardRef(function ScrollArea
         handlePointerUp(event);
       },
       style: {
+        visibility: hasMeasuredScrollbar ? undefined : 'hidden',
         ...(orientation === 'vertical' && {
           height: `var(${ScrollAreaScrollbarCssVars.scrollAreaThumbHeight})`
         }),

package/esm/scroll-area/viewport/ScrollAreaViewport.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { BaseUIComponentProps } from "../../utils/types.js";
-import type { ScrollAreaRoot } from "../root/ScrollAreaRoot.js";
+import type { ScrollAreaRootState } from "../root/ScrollAreaRoot.js";
 /**
  * The actual scrollable container of the scroll area.
  * Renders a `<div>` element.
@@ -8,8 +8,8 @@ import type { ScrollAreaRoot } from "../root/ScrollAreaRoot.js";
  * Documentation: [Base UI Scroll Area](https://base-ui.com/react/components/scroll-area)
  */
 export declare const ScrollAreaViewport: React.ForwardRefExoticComponent<Omit<ScrollAreaViewportProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface ScrollAreaViewportProps extends BaseUIComponentProps<'div', ScrollAreaViewport.State> {}
-export interface ScrollAreaViewportState extends ScrollAreaRoot.State {}
+export interface ScrollAreaViewportProps extends BaseUIComponentProps<'div', ScrollAreaViewportState> {}
+export interface ScrollAreaViewportState extends ScrollAreaRootState {}
 export declare namespace ScrollAreaViewport {
   type Props = ScrollAreaViewportProps;
   type State = ScrollAreaViewportState;

package/esm/scroll-area/viewport/ScrollAreaViewport.js

@@ -22,6 +22,7 @@ import { normalizeScrollOffset } from "../utils/scrollEdges.js";
 // regardless of how many Scroll Area components are mounted.
 import { jsx as _jsx } from "react/jsx-runtime";
 let scrollAreaOverflowVarsRegistered = false;
+const HAS_RESIZE_OBSERVER = typeof ResizeObserver !== 'undefined';
 
 /**
  * Removes inheritance of the scroll area overflow CSS variables, which
@@ -80,6 +81,7 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
     rootId,
     setHiddenState,
     hiddenState,
+    setHasMeasuredScrollbar,
     handleScroll,
     setHovering,
     setOverflowEdges,
@@ -90,6 +92,7 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
   } = useScrollAreaRootContext();
   const direction = useDirection();
   const programmaticScrollRef = React.useRef(true);
+  const lastMeasuredViewportMetricsRef = React.useRef([NaN, NaN, NaN, NaN]);
   const scrollEndTimeout = useTimeout();
   const waitForAnimationsTimeout = useTimeout();
   const computeThumbPosition = useStableCallback(() => {
@@ -108,11 +111,21 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
     const viewportWidth = viewportEl.clientWidth;
     const scrollTop = viewportEl.scrollTop;
     const scrollLeft = viewportEl.scrollLeft;
+    const lastMeasuredViewportMetrics = lastMeasuredViewportMetricsRef.current;
+    const isFirstMeasurement = Number.isNaN(lastMeasuredViewportMetrics[0]);
+    lastMeasuredViewportMetrics[0] = viewportHeight;
+    lastMeasuredViewportMetrics[1] = scrollableContentHeight;
+    lastMeasuredViewportMetrics[2] = viewportWidth;
+    lastMeasuredViewportMetrics[3] = scrollableContentWidth;
+    if (isFirstMeasurement) {
+      setHasMeasuredScrollbar(true);
+    }
     if (scrollableContentHeight === 0 || scrollableContentWidth === 0) {
       return;
     }
-    const scrollbarYHidden = viewportHeight >= scrollableContentHeight;
-    const scrollbarXHidden = viewportWidth >= scrollableContentWidth;
+    const nextHiddenState = getHiddenState(viewportEl);
+    const scrollbarYHidden = nextHiddenState.y;
+    const scrollbarXHidden = nextHiddenState.x;
     const ratioX = viewportWidth / scrollableContentWidth;
     const ratioY = viewportHeight / scrollableContentHeight;
     const maxScrollLeft = Math.max(0, scrollableContentWidth - viewportWidth);
@@ -206,17 +219,7 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
         });
       }
     }
-    setHiddenState(prevState => {
-      const cornerHidden = scrollbarYHidden || scrollbarXHidden;
-      if (prevState.y === scrollbarYHidden && prevState.x === scrollbarXHidden && prevState.corner === cornerHidden) {
-        return prevState;
-      }
-      return {
-        y: scrollbarYHidden,
-        x: scrollbarXHidden,
-        corner: cornerHidden
-      };
-    });
+    setHiddenState(prevState => mergeHiddenState(prevState, nextHiddenState));
     const nextOverflowEdges = {
       xStart: !scrollbarXHidden && scrollLeftFromStart > overflowEdgeThreshold.xStart,
       xEnd: !scrollbarXHidden && scrollLeftFromEnd > overflowEdgeThreshold.xEnd,
@@ -235,17 +238,15 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
       return undefined;
     }
     removeCSSVariableInheritance();
-    let hasInitialized = false;
+    if (HAS_RESIZE_OBSERVER) {
+      return undefined;
+    }
     return onVisible(viewportRef.current, () => {
-      if (!hasInitialized) {
-        hasInitialized = true;
-        return;
-      }
       computeThumbPosition();
     });
   }, [computeThumbPosition, viewportRef]);
   useIsoLayoutEffect(() => {
-    // Wait for scrollbar-related refs to be set
+    // Wait for scrollbar and thumb refs after hidden-state toggles, and refresh math on direction flips.
     queueMicrotask(computeThumbPosition);
   }, [computeThumbPosition, hiddenState, direction]);
   useIsoLayoutEffect(() => {
@@ -257,16 +258,20 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
   }, [viewportRef, setHovering]);
   React.useEffect(() => {
     const viewport = viewportRef.current;
-    if (typeof ResizeObserver === 'undefined' || !viewport) {
+    if (!HAS_RESIZE_OBSERVER || !viewport) {
       return undefined;
     }
     let hasInitialized = false;
     const ro = new ResizeObserver(() => {
-      // ResizeObserver fires once upon observing, so we skip the initial call
-      // to avoid double-calculating the thumb position on mount.
+      // Avoid duplicate mount-time recompute when observer data matches what the mount
+      // scheduling pass already measured. If dimensions changed before the first observer
+      // delivery, keep the recompute so overflow transitions stay in sync.
       if (!hasInitialized) {
         hasInitialized = true;
-        return;
+        const lastMeasuredViewportMetrics = lastMeasuredViewportMetricsRef.current;
+        if (lastMeasuredViewportMetrics[0] === viewport.clientHeight && lastMeasuredViewportMetrics[1] === viewport.scrollHeight && lastMeasuredViewportMetrics[2] === viewport.clientWidth && lastMeasuredViewportMetrics[3] === viewport.scrollWidth) {
+          return;
+        }
       }
       computeThumbPosition();
     });
@@ -302,9 +307,8 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
       'data-id': `${rootId}-viewport`
     }),
     // https://accessibilityinsights.io/info-examples/web/scrollable-region-focusable/
-    ...((!hiddenState.x || !hiddenState.y) && {
-      tabIndex: 0
-    }),
+    // Keep non-scrollable viewports out of tab order.
+    tabIndex: hiddenState.x && hiddenState.y ? -1 : 0,
     className: styleDisableScrollbar.className,
     style: {
       overflow: 'scroll'
@@ -361,4 +365,19 @@ export const ScrollAreaViewport = /*#__PURE__*/React.forwardRef(function ScrollA
     children: element
   });
 });
-if (process.env.NODE_ENV !== "production") ScrollAreaViewport.displayName = "ScrollAreaViewport";
+if (process.env.NODE_ENV !== "production") ScrollAreaViewport.displayName = "ScrollAreaViewport";
+function getHiddenState(viewport) {
+  const y = viewport.clientHeight >= viewport.scrollHeight;
+  const x = viewport.clientWidth >= viewport.scrollWidth;
+  return {
+    y,
+    x,
+    corner: y || x
+  };
+}
+function mergeHiddenState(prevState, nextState) {
+  if (prevState.y === nextState.y && prevState.x === nextState.x && prevState.corner === nextState.corner) {
+    return prevState;
+  }
+  return nextState;
+}

package/esm/select/arrow/SelectArrow.d.ts

@@ -13,11 +13,20 @@ export interface SelectArrowState {
    * Whether the select popup is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side | 'none';
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the arrow cannot be centered on the anchor.
+   */
   uncentered: boolean;
 }
-export interface SelectArrowProps extends BaseUIComponentProps<'div', SelectArrow.State> {}
+export interface SelectArrowProps extends BaseUIComponentProps<'div', SelectArrowState> {}
 export declare namespace SelectArrow {
   type State = SelectArrowState;
   type Props = SelectArrowProps;

package/esm/select/backdrop/SelectBackdrop.d.ts

@@ -9,10 +9,16 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  */
 export declare const SelectBackdrop: React.ForwardRefExoticComponent<Omit<SelectBackdropProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface SelectBackdropState {
+  /**
+   * Whether the component is open.
+   */
   open: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface SelectBackdropProps extends BaseUIComponentProps<'div', SelectBackdrop.State> {}
+export interface SelectBackdropProps extends BaseUIComponentProps<'div', SelectBackdropState> {}
 export declare namespace SelectBackdrop {
   type State = SelectBackdropState;
   type Props = SelectBackdropProps;

package/esm/select/group/SelectGroup.d.ts

@@ -8,7 +8,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  */
 export declare const SelectGroup: React.ForwardRefExoticComponent<Omit<SelectGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface SelectGroupState {}
-export interface SelectGroupProps extends BaseUIComponentProps<'div', SelectGroup.State> {}
+export interface SelectGroupProps extends BaseUIComponentProps<'div', SelectGroupState> {}
 export declare namespace SelectGroup {
   type State = SelectGroupState;
   type Props = SelectGroupProps;

package/esm/select/group-label/SelectGroupLabel.d.ts

@@ -8,7 +8,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  */
 export declare const SelectGroupLabel: React.ForwardRefExoticComponent<Omit<SelectGroupLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface SelectGroupLabelState {}
-export interface SelectGroupLabelProps extends BaseUIComponentProps<'div', SelectGroupLabel.State> {}
+export interface SelectGroupLabelProps extends BaseUIComponentProps<'div', SelectGroupLabelState> {}
 export declare namespace SelectGroupLabel {
   type State = SelectGroupLabelState;
   type Props = SelectGroupLabelProps;

package/esm/select/icon/SelectIcon.d.ts

@@ -13,7 +13,7 @@ export interface SelectIconState {
    */
   open: boolean;
 }
-export interface SelectIconProps extends BaseUIComponentProps<'span', SelectIcon.State> {}
+export interface SelectIconProps extends BaseUIComponentProps<'span', SelectIconState> {}
 export declare namespace SelectIcon {
   type State = SelectIconState;
   type Props = SelectIconProps;

package/esm/select/index.d.ts

@@ -1,5 +1,6 @@
 export * as Select from "./index.parts.js";
 export type * from "./root/SelectRoot.js";
+export type * from "./label/SelectLabel.js";
 export type * from "./trigger/SelectTrigger.js";
 export type * from "./value/SelectValue.js";
 export type * from "./icon/SelectIcon.js";

package/esm/select/index.parts.d.ts

@@ -1,4 +1,5 @@
 export { SelectRoot as Root } from "./root/SelectRoot.js";
+export { SelectLabel as Label } from "./label/SelectLabel.js";
 export { SelectTrigger as Trigger } from "./trigger/SelectTrigger.js";
 export { SelectValue as Value } from "./value/SelectValue.js";
 export { SelectIcon as Icon } from "./icon/SelectIcon.js";

package/esm/select/index.parts.js

@@ -1,4 +1,5 @@
 export { SelectRoot as Root } from "./root/SelectRoot.js";
+export { SelectLabel as Label } from "./label/SelectLabel.js";
 export { SelectTrigger as Trigger } from "./trigger/SelectTrigger.js";
 export { SelectValue as Value } from "./value/SelectValue.js";
 export { SelectIcon as Icon } from "./icon/SelectIcon.js";

package/esm/select/item/SelectItem.d.ts

@@ -21,7 +21,7 @@ export interface SelectItemState {
    */
   highlighted: boolean;
 }
-export interface SelectItemProps extends NonNativeButtonProps, Omit<BaseUIComponentProps<'div', SelectItem.State>, 'id'> {
+export interface SelectItemProps extends NonNativeButtonProps, Omit<BaseUIComponentProps<'div', SelectItemState>, 'id'> {
   children?: React.ReactNode;
   /**
    * A unique value that identifies this select item.

package/esm/select/item/SelectItem.js

@@ -106,7 +106,8 @@ export const SelectItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(
   } = useButton({
     disabled,
     focusableWhenDisabled: true,
-    native: nativeButton
+    native: nativeButton,
+    composite: true
   });
   function commitSelection(event) {
     const selectedValue = store.state.value;
@@ -155,6 +156,9 @@ export const SelectItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(
     onKeyDown(event) {
       lastKeyRef.current = event.key;
       store.set('activeIndex', index);
+      if (event.key === ' ' && typingRef.current) {
+        event.preventDefault();
+      }
     },
     onClick(event) {
       didPointerDownRef.current = false;
@@ -163,7 +167,7 @@ export const SelectItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(
       if (event.type === 'keydown' && lastKeyRef.current === null) {
         return;
       }
-      if (disabled || lastKeyRef.current === ' ' && typingRef.current || pointerTypeRef.current !== 'touch' && !highlighted) {
+      if (disabled || event.type === 'keydown' && lastKeyRef.current === ' ' && typingRef.current || pointerTypeRef.current !== 'touch' && !highlighted) {
         return;
       }
       lastKeyRef.current = null;
@@ -176,10 +180,12 @@ export const SelectItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(
       pointerTypeRef.current = event.pointerType;
       didPointerDownRef.current = true;
     },
-    onMouseUp(event) {
+    onMouseUp() {
       if (disabled) {
         return;
       }
+
+      // Regular click (pointerdown on this element) if didPointerDownRef is set, otherwise drag-to-select
       if (didPointerDownRef.current) {
         didPointerDownRef.current = false;
         return;
@@ -189,7 +195,7 @@ export const SelectItem = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(
       if (disallowSelectedMouseUp || disallowUnselectedMouseUp || pointerTypeRef.current !== 'touch' && !highlighted) {
         return;
       }
-      commitSelection(event.nativeEvent);
+      itemRef.current?.click();
     }
   };
   const element = useRenderElement('div', componentProps, {

package/esm/select/item-indicator/SelectItemIndicator.d.ts

@@ -9,12 +9,20 @@ import { type TransitionStatus } from "../../utils/useTransitionStatus.js";
  */
 export declare const SelectItemIndicator: React.ForwardRefExoticComponent<Omit<SelectItemIndicatorProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 export interface SelectItemIndicatorState {
+  /**
+   * Whether the item is selected.
+   */
   selected: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface SelectItemIndicatorProps extends BaseUIComponentProps<'span', SelectItemIndicator.State> {
+export interface SelectItemIndicatorProps extends BaseUIComponentProps<'span', SelectItemIndicatorState> {
   children?: React.ReactNode;
-  /** Whether to keep the HTML element in the DOM when the item is not selected. */
+  /**
+   * Whether to keep the HTML element in the DOM when the item is not selected.
+   */
   keepMounted?: boolean | undefined;
 }
 export declare namespace SelectItemIndicator {

package/esm/select/item-indicator/SelectItemIndicatorDataAttributes.d.ts

@@ -0,0 +1,10 @@
+export declare enum SelectItemIndicatorDataAttributes {
+  /**
+   * Present when the indicator is animating in.
+   */
+  startingStyle = "data-starting-style",
+  /**
+   * Present when the indicator is animating out.
+   */
+  endingStyle = "data-ending-style",
+}

package/esm/select/item-indicator/SelectItemIndicatorDataAttributes.js

@@ -0,0 +1,12 @@
+import { TransitionStatusDataAttributes } from "../../utils/stateAttributesMapping.js";
+export let SelectItemIndicatorDataAttributes = function (SelectItemIndicatorDataAttributes) {
+  /**
+   * Present when the indicator is animating in.
+   */
+  SelectItemIndicatorDataAttributes[SelectItemIndicatorDataAttributes["startingStyle"] = TransitionStatusDataAttributes.startingStyle] = "startingStyle";
+  /**
+   * Present when the indicator is animating out.
+   */
+  SelectItemIndicatorDataAttributes[SelectItemIndicatorDataAttributes["endingStyle"] = TransitionStatusDataAttributes.endingStyle] = "endingStyle";
+  return SelectItemIndicatorDataAttributes;
+}({});

package/esm/select/item-text/SelectItemText.d.ts

@@ -8,7 +8,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  */
 export declare const SelectItemText: React.NamedExoticComponent<Omit<SelectItemTextProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export interface SelectItemTextState {}
-export interface SelectItemTextProps extends BaseUIComponentProps<'div', SelectItemText.State> {}
+export interface SelectItemTextProps extends BaseUIComponentProps<'div', SelectItemTextState> {}
 export declare namespace SelectItemText {
   type State = SelectItemTextState;
   type Props = SelectItemTextProps;

package/esm/select/label/SelectLabel.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { BaseUIComponentProps } from "../../utils/types.js";
+import type { FieldRoot } from "../../field/root/FieldRoot.js";
+/**
+ * An accessible label that is automatically associated with the select trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Select](https://base-ui.com/react/components/select)
+ */
+export declare const SelectLabel: React.ForwardRefExoticComponent<Omit<SelectLabelProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export type SelectLabelState = FieldRoot.State;
+export interface SelectLabelProps extends Omit<BaseUIComponentProps<'div', SelectLabel.State>, 'id'> {}
+export declare namespace SelectLabel {
+  type State = SelectLabelState;
+  type Props = SelectLabelProps;
+}

package/esm/select/label/SelectLabel.js

@@ -0,0 +1,49 @@
+'use client';
+
+import * as React from 'react';
+import { useStore } from '@base-ui/utils/store';
+import { useRenderElement } from "../../utils/useRenderElement.js";
+import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
+import { fieldValidityMapping } from "../../field/utils/constants.js";
+import { useLabel } from "../../labelable-provider/useLabel.js";
+import { getDefaultLabelId } from "../../utils/resolveAriaLabelledBy.js";
+import { useSelectRootContext } from "../root/SelectRootContext.js";
+import { selectors } from "../store.js";
+
+/**
+ * An accessible label that is automatically associated with the select trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Select](https://base-ui.com/react/components/select)
+ */
+export const SelectLabel = /*#__PURE__*/React.forwardRef(function SelectLabel(componentProps, forwardedRef) {
+  const {
+    render,
+    className,
+    ...elementProps
+  } = componentProps;
+  // Keep label id derived from the root and ignore runtime `id` overrides from untyped consumers.
+  const elementPropsWithoutId = elementProps;
+  delete elementPropsWithoutId.id;
+  const fieldRootContext = useFieldRootContext();
+  const {
+    store
+  } = useSelectRootContext();
+  const triggerElement = useStore(store, selectors.triggerElement);
+  const rootId = useStore(store, selectors.id);
+  const defaultLabelId = getDefaultLabelId(rootId);
+  const labelProps = useLabel({
+    id: defaultLabelId,
+    fallbackControlId: triggerElement?.id ?? rootId,
+    setLabelId(nextLabelId) {
+      store.set('labelId', nextLabelId);
+    }
+  });
+  return useRenderElement('div', componentProps, {
+    ref: forwardedRef,
+    state: fieldRootContext.state,
+    props: [labelProps, elementProps],
+    stateAttributesMapping: fieldValidityMapping
+  });
+});
+if (process.env.NODE_ENV !== "production") SelectLabel.displayName = "SelectLabel";

package/esm/select/list/SelectList.d.ts

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

package/esm/select/popup/SelectPopup.d.ts

@@ -10,7 +10,7 @@ import type { TransitionStatus } from "../../utils/useTransitionStatus.js";
  * Documentation: [Base UI Select](https://base-ui.com/react/components/select)
  */
 export declare const SelectPopup: React.ForwardRefExoticComponent<Omit<SelectPopupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export interface SelectPopupProps extends BaseUIComponentProps<'div', SelectPopup.State> {
+export interface SelectPopupProps extends BaseUIComponentProps<'div', SelectPopupState> {
   children?: React.ReactNode;
   /**
    * Determines the element to focus when the select popup is closed.
@@ -21,12 +21,24 @@ export interface SelectPopupProps extends BaseUIComponentProps<'div', SelectPopu
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  finalFocus?: (boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void)) | undefined;
+  finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void) | undefined;
 }
 export interface SelectPopupState {
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side | 'none';
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the component is open.
+   */
   open: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
 export declare namespace SelectPopup {