@octanejs/base-ui 0.1.49 → 0.1.51

package/src/select/root/SelectRoot.tsrx

@@ -0,0 +1,752 @@
+'use client';
+import * as React from 'octane';
+import { visuallyHidden, visuallyHiddenInput } from '@octanejs/base-ui-utils/visuallyHidden';
+import { useMergedRefs } from '@octanejs/base-ui-utils/useMergedRefs';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import { useOnFirstRender } from '@octanejs/base-ui-utils/useOnFirstRender';
+import { usePreviousValue } from '@octanejs/base-ui-utils/usePreviousValue';
+import { isElementDisabled } from '@octanejs/base-ui-utils/isElementDisabled';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useValueAsRef } from '@octanejs/base-ui-utils/useValueAsRef';
+import { ReactStore } from '@octanejs/base-ui-utils/store';
+import { EMPTY_ARRAY, EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import {
+	useClick,
+	useDismiss,
+	useFloatingRootContext,
+	useListNavigation,
+	useTypeahead,
+} from '../../floating-ui-react';
+import {
+	SelectFloatingContext,
+	SelectRootContext,
+	SelectRootPropsContext,
+	type SelectRootPropsContextValue,
+} from './SelectRootContext';
+import { useFieldRootContext } from '../../internals/field-root-context/FieldRootContext';
+import { useRegisterFieldControl } from '../../internals/field-register-control/useRegisterFieldControl';
+import { useLabelableId } from '../../internals/labelable-provider/useLabelableId';
+import { useTransitionStatus } from '../../internals/useTransitionStatus';
+import { selectors, type SelectStoreContext, type State as StoreState } from '../store';
+import {
+	type BaseUIChangeEventDetails,
+	createChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import { useFormContext } from '../../internals/form-context/FormContext';
+import {
+	type Group,
+	stringifyAsLabel,
+	stringifyAsValue,
+} from '../../internals/resolveValueLabel.tsrx';
+import {
+	defaultItemEquality,
+	findSelectionIndex,
+	isSelectedValueDirty,
+} from '../../internals/itemEquality';
+import { useValueChanged } from '../../internals/useValueChanged';
+import { useOpenInteractionType } from '../../utils/useOpenInteractionType';
+import { getMaxScrollOffset, normalizeScrollOffset } from '../../utils/scrollEdges';
+import { FOCUSABLE_POPUP_PROPS } from '../../utils/popups';
+import { mergeProps } from '../../merge-props';
+import { NOOP } from '../../internals/noop';
+
+/**
+ * Groups all parts of the select.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Select](https://base-ui.com/react/components/select)
+ */
+export function SelectRoot<Value, Multiple extends boolean | undefined = false>(
+	props: SelectRoot.Props<Value, Multiple>,
+): React.ReactElement {
+	const {
+		id,
+		value: valueProp,
+		defaultValue = null,
+		onValueChange,
+		open: openProp,
+		defaultOpen = false,
+		onOpenChange,
+		name: nameProp,
+		form,
+		autoComplete,
+		disabled: disabledProp = false,
+		readOnly = false,
+		required = false,
+		modal = true,
+		actionsRef,
+		inputRef,
+		onOpenChangeComplete,
+		items,
+		multiple = false,
+		itemToStringLabel,
+		itemToStringValue,
+		isItemEqualToValue = defaultItemEquality,
+		highlightItemOnHover = true,
+		children,
+	} = props;
+
+	const { clearErrors } = useFormContext();
+	const {
+		setDirty,
+		setTouched,
+		setFocused,
+		validityData,
+		setFilled,
+		name: fieldName,
+		disabled: fieldDisabled,
+		validation,
+		validationMode,
+	} = useFieldRootContext();
+
+	const generatedId = useLabelableId({ id });
+
+	const disabled = fieldDisabled || disabledProp;
+	const name = fieldName ?? nameProp;
+
+	const [value, setValueUnwrapped] = useControlled({
+		controlled: valueProp,
+		default: multiple ? (defaultValue ?? EMPTY_ARRAY) : defaultValue,
+		name: 'Select',
+		state: 'value',
+	});
+
+	const [open, setOpenUnwrapped] = useControlled({
+		controlled: openProp,
+		default: defaultOpen,
+		name: 'Select',
+		state: 'open',
+	});
+
+	const listRef = React.useRef<Array<HTMLElement | null>>([]);
+	const labelsRef = React.useRef<Array<string | null>>([]);
+	const popupRef = React.useRef<HTMLDivElement | null>(null);
+	const scrollHandlerRef = React.useRef<((el: HTMLDivElement) => void) | null>(null);
+	const scrollArrowsMountedCountRef = React.useRef(0);
+	const valueRef = React.useRef<HTMLSpanElement | null>(null);
+	const valuesRef = React.useRef<Array<any>>([]);
+	const typingRef = React.useRef(false);
+	const firstItemTextRef = React.useRef<HTMLElement | null>(null);
+	const selectedItemTextRef = React.useRef<HTMLElement | null>(null);
+	const selectionRef = React.useRef({
+		allowSelectedMouseUp: false,
+		allowUnselectedMouseUp: false,
+		dragY: 0,
+	});
+	const alignItemWithTriggerActiveRef = React.useRef(false);
+	const initialValueRef = React.useRef(value);
+
+	const { mounted, setMounted, transitionStatus } = useTransitionStatus(open);
+	const { openMethod, triggerProps: interactionTypeProps } = useOpenInteractionType(open);
+
+	const store = useRefWithInit(
+		() =>
+			new ReactStore<StoreState, SelectStoreContext, typeof selectors>(
+				{
+					id: generatedId,
+					labelId: undefined,
+					modal,
+					multiple,
+					itemToStringLabel,
+					itemToStringValue,
+					isItemEqualToValue,
+					value,
+					open,
+					mounted,
+					transitionStatus,
+					items,
+					forceMount: false,
+					openMethod: null,
+					activeIndex: null,
+					selectedIndex: null,
+					popupProps: EMPTY_OBJECT,
+					triggerProps: EMPTY_OBJECT,
+					triggerElement: null,
+					positionerElement: null,
+					listElement: null,
+					popupSide: null,
+					scrollUpArrowVisible: false,
+					scrollDownArrowVisible: false,
+					hasScrollArrows: false,
+				},
+				{
+					setValue: NOOP,
+					setOpen: NOOP,
+					handleScrollArrowVisibility: NOOP,
+					onOpenChangeComplete: NOOP,
+					listRef,
+					popupRef,
+					scrollHandlerRef,
+					scrollArrowsMountedCountRef,
+					valueRef,
+					valuesRef,
+					labelsRef,
+					typingRef,
+					selectionRef,
+					firstItemTextRef,
+					selectedItemTextRef,
+					alignItemWithTriggerActiveRef,
+					initialValueRef,
+				},
+				selectors,
+			),
+	).current;
+
+	const activeIndex = store.useState('activeIndex');
+	const selectedIndex = store.useState('selectedIndex');
+	const triggerElement = store.useState('triggerElement');
+	const positionerElement = store.useState('positionerElement');
+
+	const previousOpenMethod = usePreviousValue(openMethod);
+	const renderedOpenMethod = openMethod ?? previousOpenMethod;
+
+	const serializedValue = React.useMemo(() => {
+		// In multiple mode the shared input is nameless; per-value entries are submitted via
+		// `hiddenInputs`. Its value is therefore irrelevant, and passing the whole array to
+		// `stringifyAsValue` would invoke a user `itemToStringValue` with an array it doesn't expect.
+		if (multiple) {
+			return '';
+		}
+		return stringifyAsValue(value, itemToStringValue);
+	}, [multiple, value, itemToStringValue]);
+
+	const fieldStringValue = React.useMemo(() => {
+		if (multiple && Array.isArray(value)) {
+			return value.map((currentValue) => stringifyAsValue(currentValue, itemToStringValue));
+		}
+		return stringifyAsValue(value, itemToStringValue);
+	}, [multiple, value, itemToStringValue]);
+
+	const controlRef = useValueAsRef(triggerElement);
+	const getStringifiedValueForForm = useStableCallback(() => fieldStringValue);
+
+	useRegisterFieldControl(
+		controlRef,
+		generatedId,
+		value,
+		getStringifiedValueForForm,
+		!disabled,
+		nameProp,
+	);
+
+	// Mirror the `hasSelectedValue` store selector so the Field's filled state agrees with the
+	// trigger/value placeholder semantics (a value serializing to `''` counts as empty).
+	const hasSelectedValue = multiple
+		? Array.isArray(value) && value.length > 0
+		: value != null && serializedValue !== '';
+
+	useIsoLayoutEffect(() => {
+		setFilled(hasSelectedValue);
+	}, [hasSelectedValue, setFilled]);
+
+	useIsoLayoutEffect(
+		function syncSelectedIndex() {
+			const nextIndex = findSelectionIndex(valuesRef.current, value, isItemEqualToValue, multiple);
+
+			if (nextIndex === null) {
+				selectedItemTextRef.current = null;
+			}
+
+			if (open) {
+				return;
+			}
+
+			store.set('selectedIndex', nextIndex);
+		},
+		[multiple, open, value, isItemEqualToValue, store],
+	);
+
+	useValueChanged(value, () => {
+		clearErrors(name);
+		setDirty(isSelectedValueDirty(value, validityData.initialValue, isItemEqualToValue));
+
+		validation.change(value);
+	});
+
+	const setOpen = useStableCallback(
+		(nextOpen: boolean, eventDetails: SelectRoot.ChangeEventDetails) => {
+			onOpenChange?.(nextOpen, eventDetails);
+
+			if (eventDetails.isCanceled) {
+				return;
+			}
+
+			setOpenUnwrapped(nextOpen);
+
+			if (
+				!nextOpen &&
+				(eventDetails.reason === REASONS.focusOut || eventDetails.reason === REASONS.outsidePress)
+			) {
+				setTouched(true);
+				setFocused(false);
+
+				if (validationMode === 'onBlur') {
+					validation.commit(value);
+				}
+			}
+		},
+	);
+
+	const handleUnmount = useStableCallback(() => {
+		setMounted(false);
+		store.update({
+			activeIndex: null,
+			openMethod: null,
+			scrollUpArrowVisible: false,
+			scrollDownArrowVisible: false,
+		});
+		onOpenChangeComplete?.(false);
+	});
+
+	useOpenChangeComplete({
+		enabled: !actionsRef,
+		open,
+		ref: popupRef,
+		onComplete() {
+			if (!open) {
+				handleUnmount();
+			}
+		},
+	});
+
+	React.useImperativeHandle(actionsRef, () => ({ unmount: handleUnmount }), [handleUnmount]);
+
+	const setValue = useStableCallback(
+		(nextValue: any, eventDetails: SelectRoot.ChangeEventDetails) => {
+			onValueChange?.(nextValue, eventDetails);
+
+			if (eventDetails.isCanceled) {
+				return;
+			}
+
+			setValueUnwrapped(nextValue);
+		},
+	);
+
+	const handleScrollArrowVisibility = useStableCallback((scroller: HTMLElement) => {
+		const maxScrollTop = getMaxScrollOffset(scroller.scrollHeight, scroller.clientHeight);
+		const scrollTop = normalizeScrollOffset(scroller.scrollTop, maxScrollTop);
+		const shouldShowUp = scrollTop > 0;
+		const shouldShowDown = scrollTop < maxScrollTop;
+
+		store.set('scrollUpArrowVisible', shouldShowUp);
+		store.set('scrollDownArrowVisible', shouldShowDown);
+	});
+
+	const floatingContext = useFloatingRootContext({
+		open,
+		onOpenChange: setOpen,
+		elements: {
+			reference: triggerElement,
+			floating: positionerElement,
+		},
+	});
+
+	// `readOnly` locks the value, not the interaction: the popup can be opened and browsed so the
+	// user can see the available options and which one is selected. Committing a value is blocked
+	// separately in `SelectItem` and in the hidden input's autofill handler.
+	const click = useClick(floatingContext, {
+		enabled: !disabled,
+		event: 'mousedown',
+	});
+
+	const dismiss = useDismiss(floatingContext);
+
+	const listNavigation = useListNavigation(floatingContext, {
+		enabled: !disabled,
+		listRef,
+		activeIndex,
+		selectedIndex,
+		disabledIndices: EMPTY_ARRAY,
+		onNavigate(nextActiveIndex) {
+			// Retain the highlight while transitioning out.
+			if (nextActiveIndex === null && !open) {
+				return;
+			}
+
+			store.set('activeIndex', nextActiveIndex);
+		},
+		focusItemOnHover: highlightItemOnHover,
+	});
+
+	const typeahead = useTypeahead(floatingContext, {
+		// Typeahead on an open popup only moves the highlight, so it remains available while
+		// `readOnly`. The closed-trigger variant commits a value instead, so it doesn't.
+		enabled: !disabled && (open || (!readOnly && !multiple)),
+		listRef: labelsRef,
+		activeIndex,
+		selectedIndex,
+		// Skip disabled items while matching so typeahead advances to the next selectable item
+		// (a click can never select a disabled item and native `<select>` skips them too). Resolve
+		// the disabled state from the element via the attribute-only `isElementDisabled` so the
+		// hidden, force-mounted items used for closed-trigger typeahead aren't dropped by the
+		// `elementsRef`/visibility filter that `disabledIndices` deliberately sidesteps.
+		disabledIndices: (index) => isElementDisabled(listRef.current[index]),
+		onMatch(index) {
+			if (open) {
+				store.set('activeIndex', index);
+			} else {
+				setValue(valuesRef.current[index], createChangeEventDetails(REASONS.none));
+			}
+		},
+		onTyping(typing) {
+			typingRef.current = typing;
+		},
+	});
+
+	// `Select.Trigger` applies the id itself from the store, so it's deliberately not merged here.
+	const mergedTriggerProps = React.useMemo(
+		() =>
+			mergeProps(
+				typeahead.reference,
+				listNavigation.reference,
+				dismiss.reference,
+				click.reference,
+				interactionTypeProps,
+			),
+		[
+			click.reference,
+			typeahead.reference,
+			listNavigation.reference,
+			dismiss.reference,
+			interactionTypeProps,
+		],
+	);
+
+	const popupProps = React.useMemo(
+		() =>
+			mergeProps(
+				FOCUSABLE_POPUP_PROPS,
+				typeahead.floating,
+				listNavigation.floating,
+				dismiss.floating,
+			),
+		[typeahead.floating, listNavigation.floating, dismiss.floating],
+	);
+
+	const itemProps =
+		(listNavigation.item as React.HTMLProps<HTMLElement> | undefined) ?? EMPTY_OBJECT;
+
+	store.useContextCallback('setValue', setValue);
+	store.useContextCallback('setOpen', setOpen);
+	store.useContextCallback('handleScrollArrowVisibility', handleScrollArrowVisibility);
+	store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
+
+	// The prop bags must be in the store before the parts render. `useSyncedValues` writes in a
+	// layout effect, after all descendants have rendered.
+	useOnFirstRender(() => {
+		store.update({
+			popupProps,
+			triggerProps: mergedTriggerProps,
+		});
+	});
+
+	store.useSyncedValues({
+		id: generatedId,
+		modal,
+		multiple,
+		value,
+		open,
+		mounted,
+		transitionStatus,
+		popupProps,
+		triggerProps: mergedTriggerProps,
+		items,
+		itemToStringLabel,
+		itemToStringValue,
+		isItemEqualToValue,
+		openMethod: renderedOpenMethod,
+	});
+
+	const rootPropsContextValue: SelectRootPropsContextValue = React.useMemo(
+		() => ({
+			disabled,
+			readOnly,
+			required,
+			multiple,
+			highlightItemOnHover,
+			itemProps,
+		}),
+		[disabled, readOnly, required, multiple, highlightItemOnHover, itemProps],
+	);
+
+	const ref = useMergedRefs(inputRef, validation.inputRef);
+
+	const hiddenInputName = multiple ? undefined : name;
+
+	const hiddenInputs = React.useMemo(() => {
+		if (!multiple || !Array.isArray(value) || !name) {
+			return null;
+		}
+
+		return value.map((v) => {
+			const currentSerializedValue = stringifyAsValue(v, itemToStringValue);
+			return (
+				<input
+					key={currentSerializedValue}
+					type="hidden"
+					form={form}
+					name={name}
+					value={currentSerializedValue}
+					disabled={disabled}
+				/>
+			);
+		});
+	}, [multiple, value, form, name, itemToStringValue, disabled]);
+
+	return (
+		<SelectRootContext.Provider value={store}>
+			<SelectRootPropsContext.Provider value={rootPropsContextValue}>
+				<SelectFloatingContext.Provider value={floatingContext}>
+					{children}
+				</SelectFloatingContext.Provider>
+			</SelectRootPropsContext.Provider>
+			<input
+				{...validation.getValidationProps(disabled, {
+					onFocus() {
+						// Move focus to the trigger element when the hidden input is focused.
+						store.state.triggerElement?.focus({
+							// Supported in Chrome from 144 (January 2026)
+							focusVisible: true,
+						} as FocusOptions & { focusVisible?: boolean });
+					},
+					// Handle browser autofill.
+					onChange(event: React.ChangeEvent<HTMLInputElement>) {
+						// Workaround for https://github.com/react/react/issues/9023
+						if (event.defaultPrevented || disabled || readOnly) {
+							return;
+						}
+
+						const nextValue = event.currentTarget.value;
+						const details = createChangeEventDetails(REASONS.none, event);
+
+						function handleChange() {
+							if (multiple) {
+								// Browser autofill only writes a single scalar value.
+								return;
+							}
+
+							// Preserve the original serialized matching, then fall back to rendered text,
+							// which browsers can autofill for primitive values like
+							// `value="US">United States`.
+							const nextValueLower = nextValue.toLowerCase();
+							let matchingIndex = valuesRef.current.findIndex(
+								(candidate) =>
+									stringifyAsValue(candidate, itemToStringValue).toLowerCase() === nextValueLower ||
+									stringifyAsLabel(candidate, itemToStringLabel).toLowerCase() === nextValueLower,
+							);
+
+							if (matchingIndex === -1) {
+								matchingIndex = valuesRef.current.findIndex((_, index) => {
+									const renderedLabel = labelsRef.current[index];
+									return renderedLabel != null && renderedLabel.toLowerCase() === nextValueLower;
+								});
+							}
+
+							const matchingValue = valuesRef.current[matchingIndex];
+							if (matchingValue != null) {
+								// `setValue` may be canceled by `onValueChange`; rely on `useValueChanged` to
+								// mark the field dirty and run validation only when the value actually changes.
+								setValue(matchingValue, details);
+							}
+						}
+
+						store.set('forceMount', true);
+						queueMicrotask(handleChange);
+					},
+				})}
+				id={generatedId && hiddenInputName == null ? `${generatedId}-hidden-input` : undefined}
+				form={form}
+				name={hiddenInputName}
+				autoComplete={autoComplete}
+				value={serializedValue}
+				disabled={disabled}
+				required={required && !(multiple && hasSelectedValue)}
+				readOnly={readOnly}
+				ref={ref}
+				style={name ? visuallyHiddenInput : visuallyHidden}
+				tabIndex={-1}
+				aria-hidden
+				suppressHydrationWarning
+			/>
+			{hiddenInputs}
+		</SelectRootContext.Provider>
+	);
+}
+
+type SelectValueType<Value, Multiple extends boolean | undefined> = Multiple extends true
+	? Value[]
+	: Value;
+
+export interface SelectRootProps<Value, Multiple extends boolean | undefined = false> {
+	children?: React.OctaneNode;
+	/**
+	 * A ref to access the hidden input element.
+	 */
+	inputRef?: React.Ref<HTMLInputElement> | undefined;
+	/**
+	 * Identifies the field when a form is submitted.
+	 */
+	name?: string | undefined;
+	/**
+	 * Identifies the form that owns the hidden input.
+	 * Useful when the select is rendered outside the form.
+	 */
+	form?: string | undefined;
+	/**
+	 * Provides a hint to the browser for autofill.
+	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete
+	 */
+	autoComplete?: string | undefined;
+	/**
+	 * The id of the Select.
+	 */
+	id?: string | undefined;
+	/**
+	 * Whether the user must choose a value before submitting a form.
+	 * @default false
+	 */
+	required?: boolean | undefined;
+	/**
+	 * Whether the user should be unable to choose a different option from the select popup.
+	 * @default false
+	 */
+	readOnly?: boolean | undefined;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * Whether multiple items can be selected.
+	 * @default false
+	 */
+	multiple?: Multiple | undefined;
+	/**
+	 * Whether moving the pointer over items should highlight them.
+	 * Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
+	 * @default true
+	 */
+	highlightItemOnHover?: boolean | undefined;
+	/**
+	 * Whether the select popup is initially open.
+	 *
+	 * To render a controlled select popup, use the `open` prop instead.
+	 * @default false
+	 */
+	defaultOpen?: boolean | undefined;
+	/**
+	 * Event handler called when the select popup is opened or closed.
+	 */
+	onOpenChange?: ((open: boolean, eventDetails: SelectRootChangeEventDetails) => void) | undefined;
+	/**
+	 * Event handler called after any animations complete when the select popup is opened or closed.
+	 */
+	onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+	/**
+	 * Whether the select popup is currently open.
+	 */
+	open?: boolean | undefined;
+	/**
+	 * Determines if the select enters a modal state when open.
+	 * - `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled.
+	 * - `false`: user interaction with the rest of the document is allowed.
+	 *
+	 * On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+	 * @default true
+	 */
+	modal?: boolean | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `unmount`: Manually unmounts the select.
+	 * Call this after any externally controlled closing animation finishes.
+	 */
+	actionsRef?: React.RefObject<SelectRootActions | null> | undefined;
+	/**
+	 * Data structure of the items rendered in the select popup.
+	 * When specified, `<Select.Value>` renders the label of the selected item instead of the raw value.
+	 * @example
+	 * ```tsx
+	 * const items = {
+	 *   sans: 'Sans-serif',
+	 *   serif: 'Serif',
+	 *   mono: 'Monospace',
+	 *   cursive: 'Cursive',
+	 * };
+	 * <Select.Root items={items} />
+	 * ```
+	 */
+	items?:
+		| Record<string, React.OctaneNode>
+		| ReadonlyArray<{ label: React.OctaneNode; value: any }>
+		| ReadonlyArray<Group<any>>
+		| undefined;
+	/**
+	 * When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for display in the trigger.
+	 * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+	 */
+	itemToStringLabel?: ((itemValue: Value) => string) | undefined;
+	/**
+	 * When the item values are objects (`<Select.Item value={object}>`), this function converts the object value to a string representation for form submission.
+	 * If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.
+	 */
+	itemToStringValue?: ((itemValue: Value) => string) | undefined;
+	/**
+	 * Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially.
+	 * Defaults to `Object.is` comparison.
+	 */
+	isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
+	/**
+	 * The uncontrolled value of the select when it's initially rendered.
+	 *
+	 * To render a controlled select, use the `value` prop instead.
+	 */
+	defaultValue?: SelectValueType<Value, Multiple> | null | undefined;
+	/**
+	 * The value of the select. Use when controlled.
+	 */
+	value?: SelectValueType<Value, Multiple> | null | undefined;
+	/**
+	 * Event handler called when the value of the select changes.
+	 */
+	onValueChange?:
+		| ((
+				value: SelectValueType<Value, Multiple> | (Multiple extends true ? never : null),
+				eventDetails: SelectRootChangeEventDetails,
+		  ) => void)
+		| undefined;
+}
+
+export interface SelectRootState {}
+
+export interface SelectRootActions {
+	unmount: () => void;
+}
+
+export type SelectRootChangeEventReason =
+	| typeof REASONS.triggerPress
+	| typeof REASONS.outsidePress
+	| typeof REASONS.escapeKey
+	| typeof REASONS.windowResize
+	| typeof REASONS.itemPress
+	| typeof REASONS.focusOut
+	| typeof REASONS.listNavigation
+	| typeof REASONS.cancelOpen
+	| typeof REASONS.none;
+
+export type SelectRootChangeEventDetails = BaseUIChangeEventDetails<SelectRootChangeEventReason>;
+
+export namespace SelectRoot {
+	export type Props<Value, Multiple extends boolean | undefined = false> = SelectRootProps<
+		Value,
+		Multiple
+	>;
+	export type State = SelectRootState;
+	export type Actions = SelectRootActions;
+	export type ChangeEventReason = SelectRootChangeEventReason;
+	export type ChangeEventDetails = SelectRootChangeEventDetails;
+}