@octanejs/base-ui 0.1.50 → 0.1.52

package/src/combobox/items/createItems.ts

@@ -0,0 +1,168 @@
+/** @jsxImportSource octane */
+import type * as React from 'octane';
+import { EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import { error } from '@octanejs/base-ui-utils/error';
+import { flattenLeafItems, stringifyAsLabel } from '../../internals/resolveValueLabel.tsrx';
+import type { ItemEqualityComparer } from '../../internals/itemEquality';
+import { findCollectionItem, type ComboboxItemCollection } from './itemCollection';
+
+export type ComboboxPrimitiveValue = string | number | bigint | boolean;
+
+type RemoveIndexSignature<Type> = {
+	[
+		Key in keyof Type as string extends Key
+			? never
+			: number extends Key
+				? never
+				: symbol extends Key
+					? never
+					: Key
+	]: Type[Key];
+};
+
+/** Whether any constituent of `Item` explicitly declares an `items` field that may be an array. */
+type HasGroupShape<Item> = Item extends object
+	? 'items' extends keyof RemoveIndexSignature<Item>
+		? [Extract<NonNullable<Item['items']>, ReadonlyArray<unknown>>] extends [never]
+			? never[] extends NonNullable<Item['items']>
+				? true
+				: never
+			: true
+		: never
+	: never;
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type GroupShapedItemsError =
+	'Base UI: items passed to createItems() cannot have an `items` array property because it marks a group. Rename the field or cast the data.';
+
+type RejectGroupShapedItems<Item> =
+	IsAny<Item> extends true
+		? unknown
+		: true extends HasGroupShape<Item>
+			? GroupShapedItemsError
+			: unknown;
+
+// The group-shape guard stays outside this union because folding it in breaks tsc's leaf-item
+// inference for grouped data.
+type ComboboxItemsData<Item> =
+	| readonly { items: ReadonlyArray<Item> }[]
+	| (Extract<Item, { items: ReadonlyArray<unknown> }> extends never ? readonly Item[] : never);
+
+export interface CreateComboboxItemsOptions<
+	Item,
+	Value extends ComboboxPrimitiveValue = ComboboxPrimitiveValue,
+> {
+	/**
+	 * Projects an item to the primitive value that identifies it, used as the item's
+	 * selection value.
+	 *
+	 * `null` and `undefined` are reserved for no selection, and each item must derive a unique
+	 * value. Prefer stable IDs from your application data.
+	 */
+	getValue: (item: Item) => Value;
+	/**
+	 * Projects an item to the label string that represents it in the input and when matching the
+	 * typed query. The root's `itemToStringLabel` prop is the fallback for values whose item is in
+	 * neither the data nor the current `filteredItems`.
+	 */
+	getLabel: (item: Item) => string;
+}
+
+/**
+ * Creates a collection for the root's `items` prop. Values and labels are derived on first use.
+ *
+ * Accepts either a flat item array or an array of groups. The `getValue` and `getLabel` accessors
+ * receive items, not groups.
+ *
+ * Items cannot have an `items` array property because they would be interpreted as groups.
+ * Rename that field or cast the data when the runtime values are known not to contain arrays.
+ *
+ * The data must not contain nullish entries: remove them before creating the collection, as for
+ * the root's `items` prop.
+ *
+ * Create static collections at module scope. Wrap dynamic collections in `React.useMemo()` keyed
+ * by their data.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ *
+ * @param data The flat or grouped source items, or `undefined` while they are loading.
+ * @param options Functions that derive each source item's selection value and display label.
+ * @returns A collection whose selection value is the `getValue` accessor's return value.
+ */
+export function createComboboxItems<Item, Value extends ComboboxPrimitiveValue>(
+	/** @type ComboboxItemsData<Item> | undefined */
+	data: (ComboboxItemsData<Item> & RejectGroupShapedItems<Item>) | undefined,
+	options: CreateComboboxItemsOptions<Item, Value>,
+): ComboboxItemCollection<Item, Value> {
+	const { getValue, getLabel } = options;
+
+	let valueToItem: Map<Value, Item> | null = null;
+
+	// Lazily indexes the collection's own `data`, so the accessors never run at creation.
+	function ensureDerived() {
+		if (valueToItem === null) {
+			const derived = new Map<Value, Item>();
+
+			const leafItems = data ? flattenLeafItems<Item>(data) : EMPTY_ARRAY;
+
+			for (const item of leafItems) {
+				// Skipped defensively: the data is documented as free of nullish entries.
+				if (item == null) {
+					continue;
+				}
+
+				const derivedValue = getValue(item);
+				// First occurrence wins, so a duplicated derived value resolves to one stable label.
+				if (!derived.has(derivedValue)) {
+					derived.set(derivedValue, item);
+				} else if (process.env.NODE_ENV !== 'production') {
+					error(
+						`Two items passed to createItems() derived the value ${String(derivedValue)}, so selection and label ` +
+							'resolution cannot tell them apart: the first item wins the label and every item ' +
+							'carrying the value renders as selected. Return a unique value from `getValue`.',
+					);
+				}
+			}
+
+			valueToItem = derived;
+		}
+
+		return valueToItem;
+	}
+
+	// A pure projection with stable identity: the root feeds it to memos and effects, and the
+	// collection never stores items it does not own.
+	function value(item: Item): Value {
+		if (item == null) {
+			return item as unknown as Value;
+		}
+		return getValue(item);
+	}
+
+	return {
+		// Passed through rather than defaulted: data that has not loaded must stay the absence of
+		// items rather than an empty list that filters everything away.
+		data,
+		value,
+		hasValue(itemValue: Value, isEqual: ItemEqualityComparer<Value>) {
+			return findCollectionItem(ensureDerived(), itemValue, isEqual) !== undefined;
+		},
+		itemLabel: getLabel,
+		label(
+			itemValue: Value,
+			isEqual: ItemEqualityComparer<Value>,
+			fallback?: ((itemValue: Value) => string) | undefined,
+		) {
+			const item = findCollectionItem(ensureDerived(), itemValue, isEqual);
+			if (item !== undefined) {
+				return getLabel(item);
+			}
+
+			return stringifyAsLabel(itemValue, fallback);
+		},
+	} as unknown as ComboboxItemCollection<Item, Value>;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/combobox/items/itemCollection.ts

@@ -0,0 +1,67 @@
+import type { Group } from '../../internals/resolveValueLabel.tsrx';
+import {
+	compareItemEquality,
+	defaultItemEquality,
+	type ItemEqualityComparer,
+} from '../../internals/itemEquality';
+
+export function findCollectionItem<Item, Value>(
+	valueToItem: Map<Value, Item>,
+	itemValue: Value,
+	isEqual: ItemEqualityComparer<Value>,
+): Item | undefined {
+	const exactItem = valueToItem.get(itemValue);
+	if (exactItem !== undefined || isEqual === defaultItemEquality) {
+		return exactItem;
+	}
+
+	for (const [derivedValue, item] of valueToItem) {
+		if (compareItemEquality(derivedValue, itemValue, isEqual)) {
+			return item;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * An opaque collection created by `createItems()`.
+ *
+ * It carries the source item and derived value types so the root can infer the list item and
+ * selection value types.
+ *
+ * Pass it directly to the root's `items` prop; it has no public members.
+ */
+export declare class ComboboxItemCollection<in out Item, Value = Item> {
+	private constructor();
+	private readonly __itemCollectionBrand: (item: Item) => Value;
+}
+
+/**
+ * Internal shape of a collection. The extra members let the root project items to
+ * their values and resolve a selected value back to its label while items are unmounted.
+ */
+export interface ItemCollection<Item = any, Value = any> {
+	/**
+	 * Source items, preserving their flat or grouped structure for collection rendering.
+	 * `undefined` when the data has not loaded, which the root reads as no items prop at all.
+	 */
+	data: readonly Item[] | readonly Group<Item>[] | undefined;
+	/**
+	 * Projects a source item to the value used by selection APIs.
+	 */
+	value: (item: Item) => Value;
+	/** Whether a projected value belongs to the collection's own data. */
+	hasValue: (value: Value, isEqual: ItemEqualityComparer<Value>) => boolean;
+	/** Resolves a source item's label while filtering in the source-item domain. */
+	itemLabel: (item: Item) => string;
+	/**
+	 * Resolves a selected value's label, including values outside the mounted items.
+	 * `fallback` labels the values the collection cannot resolve at all.
+	 */
+	label(
+		valueOrItem: Value,
+		isEqual: ItemEqualityComparer<Value>,
+		fallback?: ((valueOrItem: Value) => string) | undefined,
+	): string;
+}

package/src/combobox/label/ComboboxLabel.tsrx

@@ -0,0 +1,88 @@
+'use client';
+import * as React from 'octane';
+import { error } from '@octanejs/base-ui-utils/error';
+import type { SafeReact } from '@octanejs/base-ui-utils/safeReact';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { FieldRoot } from '../../field/root/FieldRoot.tsrx';
+import { useFieldRootContext } from '../../internals/field-root-context/FieldRootContext';
+import { fieldValidityMapping } from '../../internals/field-constants/constants';
+import { useLabel } from '../../internals/labelable-provider/useLabel';
+import { getDefaultLabelId } from '../../utils/resolveAriaLabelledBy';
+import { useComboboxRootContext } from '../root/ComboboxRootContext.tsrx';
+
+/**
+ * An accessible label that is automatically associated with the combobox trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxLabel = function ComboboxLabel(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxLabel.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+	// Keep label id derived from the root and ignore runtime `id` overrides from untyped consumers.
+	const elementPropsWithoutId = elementProps as typeof elementProps & { id?: string | undefined };
+	delete elementPropsWithoutId.id;
+
+	const fieldRootContext = useFieldRootContext();
+	const store = useComboboxRootContext();
+
+	const inputInsidePopup = store.useState('inputInsidePopup');
+	const triggerElement = store.useState('triggerElement');
+	const inputElement = store.useState('inputElement');
+	const rootId = store.useState('id');
+	const defaultLabelId = getDefaultLabelId(rootId);
+
+	const localControlId = triggerElement?.id ?? (inputInsidePopup ? rootId : undefined);
+
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useEffect(() => {
+			if (!inputElement || inputInsidePopup) {
+				return;
+			}
+
+			const ownerStackMessage = '';
+			const message =
+				'<Combobox.Label> labels <Combobox.Trigger> only. ' +
+				'When <Combobox.Input> is the form control, use a native <label> or <Field.Label> instead.';
+			error(`${message}${ownerStackMessage}`);
+		}, [inputElement, inputInsidePopup]);
+	}
+
+	const labelProps = useLabel({
+		id: defaultLabelId,
+		fallbackControlId: localControlId,
+		setLabelId(nextLabelId) {
+			const resolvedLabelId =
+				typeof nextLabelId === 'function' ? nextLabelId(store.state.labelId) : nextLabelId;
+			store.set('labelId', resolvedLabelId);
+		},
+	});
+
+	return useRenderElement('div', componentProps, {
+		ref: forwardedRef,
+		state: fieldRootContext.state,
+		props: [labelProps, elementProps],
+		stateAttributesMapping: fieldValidityMapping,
+	});
+};
+
+export interface ComboboxLabelState extends FieldRoot.State {}
+
+export interface ComboboxLabelProps extends Omit<
+	BaseUIComponentProps<'div', ComboboxLabelState>,
+	'id'
+> {}
+
+export namespace ComboboxLabel {
+	export type State = ComboboxLabelState;
+	export type Props = ComboboxLabelProps;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/combobox/list/ComboboxList.tsrx

@@ -0,0 +1,152 @@
+'use client';
+import * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import {
+	useComboboxDerivedItemsContext,
+	useComboboxFloatingContext,
+	useComboboxRootContext,
+} from '../root/ComboboxRootContext.tsrx';
+import { useComboboxPositionerContext } from '../positioner/ComboboxPositionerContext.tsrx';
+import { ComboboxCollection } from '../collection/ComboboxCollection.tsrx';
+import { CompositeList } from '../../internals/composite/list/CompositeList.tsrx';
+import { stopEvent } from '../../floating-ui-react/utils';
+import { clickHighlightedItem } from '../utils/parts';
+
+/**
+ * A list container for the items.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxList = function ComboboxList(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxList.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, children, ...elementProps } = componentProps;
+
+	const store = useComboboxRootContext();
+	const floatingRootContext = useComboboxFloatingContext();
+	const hasPositionerContext = Boolean(useComboboxPositionerContext(true));
+	const { filteredItems, hasItems } = useComboboxDerivedItemsContext();
+
+	const selectionMode = store.useState('selectionMode');
+	const grid = store.useState('grid');
+	const readOnly = store.useState('readOnly');
+	const listProps = store.useState('listProps');
+	const virtualized = store.useState('virtualized');
+	const forceMounted = store.useState('forceMounted');
+
+	const multiple = selectionMode === 'multiple';
+	const empty = filteredItems.length === 0;
+
+	const setPositionerElement = useStableCallback((element) => {
+		store.set('positionerElement', element);
+	});
+
+	const setListElement = useStableCallback((element) => {
+		store.set('listElement', element);
+	});
+
+	// Support "closed template" API: if children is a function, implicitly wrap it
+	// with a Combobox.Collection that reads items from context/root.
+	// Ensures this component's `listProps` subscription does not cause <Combobox.Item>
+	// to re-render on every active index change.
+	const resolvedChildren = React.useMemo(() => {
+		if (typeof children === 'function' && !React.isChildrenBlock(children)) {
+			return (
+				<ComboboxCollection>{children as ComboboxCollection.Props['children']}</ComboboxCollection>
+			);
+		}
+		return children;
+	}, [children]);
+
+	const state: ComboboxListState = {
+		empty,
+	};
+
+	const floatingId = floatingRootContext.useState('floatingId');
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: [forwardedRef, setListElement, hasPositionerContext ? null : setPositionerElement],
+		props: [
+			listProps,
+			{
+				children: resolvedChildren,
+				tabIndex: -1,
+				id: floatingId,
+				role: grid ? 'grid' : 'listbox',
+				'aria-multiselectable': multiple ? 'true' : undefined,
+				// On a grid the attribute describes cell editability, not selection, so it's left to the
+				// combobox element in that mode.
+				'aria-readonly': !grid && readOnly ? true : undefined,
+				onKeyDown(event) {
+					if (store.state.disabled || store.state.readOnly) {
+						return;
+					}
+
+					if (event.key === 'Enter') {
+						const activeIndex = store.state.activeIndex;
+
+						if (activeIndex == null) {
+							// Allow form submission when no item is highlighted.
+							return;
+						}
+
+						stopEvent(event);
+						clickHighlightedItem(store, activeIndex, event);
+					}
+				},
+				onKeyDownCapture() {
+					store.context.keyboardActiveRef.current = true;
+				},
+				onPointerMoveCapture() {
+					store.context.keyboardActiveRef.current = false;
+				},
+			},
+			elementProps,
+		],
+	});
+
+	if (virtualized) {
+		return element;
+	}
+
+	// With the `items` prop, typeahead labels are derived from the items so they survive the list
+	// unmounting (unmounting clears the registered labels). Rendered labels only need to be
+	// registered when the list is force-mounted to match browser autofill against rendered text.
+	const labelsRef = hasItems && !forceMounted ? undefined : store.context.labelsRef;
+
+	return (
+		<CompositeList elementsRef={store.context.listRef} labelsRef={labelsRef}>
+			{element}
+		</CompositeList>
+	);
+};
+
+export interface ComboboxListState {
+	/**
+	 * Whether the list is empty.
+	 */
+	empty: boolean;
+}
+
+export interface ComboboxListProps extends Omit<
+	BaseUIComponentProps<'div', ComboboxListState>,
+	'children'
+> {
+	children?:
+		| NonNullable<React.OctaneNode>
+		| null
+		| undefined
+		| ((item: any, index: number) => React.OctaneNode);
+}
+
+export namespace ComboboxList {
+	export type State = ComboboxListState;
+	export type Props = ComboboxListProps;
+}

package/src/combobox/popup/ComboboxPopup.tsrx

@@ -0,0 +1,214 @@
+'use client';
+import * as React from 'octane';
+import type { InteractionType } from '@octanejs/base-ui-utils/useEnhancedClickHandler';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { FloatingFocusManager } from '../../floating-ui-react';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import {
+	useComboboxFloatingContext,
+	useComboboxRootContext,
+} from '../root/ComboboxRootContext.tsrx';
+import { popupStateMapping } from '../../utils/popupStateMapping';
+import { useComboboxPositionerContext } from '../positioner/ComboboxPositionerContext.tsrx';
+import type { Side, Align } from '../../internals/useAnchorPositioning';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+import { transitionStatusMapping } from '../../internals/stateAttributesMapping';
+import type { StateAttributesMapping } from '../../internals/getStateAttributesProps';
+import { contains, getTarget } from '../../floating-ui-react/utils';
+import { getDisabledMountTransitionStyles } from '../../internals/getDisabledMountTransitionStyles';
+import { ComboboxInternalDismissButton } from '../utils/ComboboxInternalDismissButton.tsrx';
+import { getComboboxPopupId } from '../root/utils';
+import { useListEmpty } from '../utils/parts';
+
+const stateAttributesMapping: StateAttributesMapping<ComboboxPopupState> = {
+	...popupStateMapping,
+	...transitionStatusMapping,
+};
+
+/**
+ * A container for the list.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxPopup = function ComboboxPopup(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxPopup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, initialFocus, finalFocus, ...elementProps } = componentProps;
+
+	const store = useComboboxRootContext();
+	const positioning = useComboboxPositionerContext();
+	const floatingRootContext = useComboboxFloatingContext();
+
+	const mounted = store.useState('mounted');
+	const open = store.useState('open');
+	const openMethod = store.useState('openMethod');
+	const popupProps = store.useState('popupProps');
+	const transitionStatus = store.useState('transitionStatus');
+	const inputInsidePopup = store.useState('inputInsidePopup');
+	const inputElement = store.useState('inputElement');
+	const modal = store.useState('modal');
+	const rootId = store.useState('id');
+
+	const empty = useListEmpty();
+	const popupId = elementProps.id ?? (inputInsidePopup ? getComboboxPopupId(rootId) : undefined);
+
+	useIsoLayoutEffect(() => {
+		// Prefer the rendered DOM id, which a `render` prop element or function may override.
+		store.set('popupId', store.context.popupRef.current?.id || popupId);
+		return () => {
+			store.set('popupId', undefined);
+		};
+	}, [store, popupId]);
+
+	useOpenChangeComplete({
+		open,
+		ref: store.context.popupRef,
+		onComplete() {
+			if (open) {
+				store.context.onOpenChangeComplete(true);
+			}
+		},
+	});
+
+	const state: ComboboxPopupState = {
+		open,
+		side: positioning.side,
+		align: positioning.align,
+		anchorHidden: positioning.anchorHidden,
+		transitionStatus,
+		empty,
+	};
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: [forwardedRef, store.context.popupRef],
+		props: [
+			popupProps,
+			{
+				id: popupId,
+				role: inputInsidePopup ? 'dialog' : 'presentation',
+				onFocus(event) {
+					const target = getTarget(event) as Element | null;
+					if (
+						openMethod !== 'touch' &&
+						(contains(store.state.listElement, target) || target === event.currentTarget)
+					) {
+						store.context.inputRef.current?.focus();
+					}
+				},
+			},
+			getDisabledMountTransitionStyles(transitionStatus),
+			elementProps,
+		],
+		stateAttributesMapping,
+	});
+
+	// Default initial focus logic:
+	// If opened by touch, focus the popup element to prevent the virtual keyboard from opening
+	// (this is required for Android specifically as iOS handles this automatically).
+	const computedDefaultInitialFocus = inputInsidePopup
+		? (interactionType: InteractionType) =>
+				interactionType === 'touch' ? store.context.popupRef.current : inputElement
+		: false;
+
+	const resolvedInitialFocus =
+		initialFocus === undefined ? computedDefaultInitialFocus : initialFocus;
+
+	let resolvedFinalFocus: ComboboxPopup.Props['finalFocus'] | boolean | undefined;
+	if (finalFocus != null) {
+		resolvedFinalFocus = finalFocus;
+	} else {
+		resolvedFinalFocus = inputInsidePopup ? undefined : false;
+	}
+
+	const focusManagerModal = !inputInsidePopup || modal;
+
+	return (
+		<FloatingFocusManager
+			context={floatingRootContext}
+			disabled={!mounted}
+			modal={focusManagerModal}
+			openInteractionType={openMethod}
+			initialFocus={resolvedInitialFocus}
+			returnFocus={resolvedFinalFocus}
+			getInsideElements={() => [
+				store.context.startDismissRef.current,
+				store.context.endDismissRef.current,
+			]}
+		>
+			<React.Fragment>
+				{element}
+				{focusManagerModal && <ComboboxInternalDismissButton ref={store.context.endDismissRef} />}
+			</React.Fragment>
+		</FloatingFocusManager>
+	);
+};
+
+export interface ComboboxPopupState {
+	/**
+	 * Whether the component is open.
+	 */
+	open: boolean;
+	/**
+	 * The side of the anchor the component is placed on.
+	 */
+	side: Side;
+	/**
+	 * The alignment of the component relative to the anchor.
+	 */
+	align: Align;
+	/**
+	 * Whether the anchor element is hidden.
+	 */
+	anchorHidden: boolean;
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+	/**
+	 * Whether there are no items to display.
+	 */
+	empty: boolean;
+}
+
+export interface ComboboxPopupProps extends BaseUIComponentProps<'div', ComboboxPopupState> {
+	/**
+	 * Determines the element to focus when the popup is opened.
+	 *
+	 * - `false`: Do not move focus.
+	 * - `true`: Move focus based on the default behavior (first tabbable element or popup).
+	 * - `RefObject`: Move focus to the ref element.
+	 * - `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.
+	 */
+	initialFocus?:
+		| boolean
+		| React.RefObject<HTMLElement | null>
+		| ((openType: InteractionType) => void | boolean | HTMLElement | null)
+		| undefined;
+	/**
+	 * Determines the element to focus when the popup is closed.
+	 *
+	 * - `false`: Do not move focus.
+	 * - `true`: Move focus based on the default behavior (trigger or previously focused element).
+	 * - `RefObject`: Move focus to the ref element.
+	 * - `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) => void | boolean | HTMLElement | null)
+		| undefined;
+}
+
+export namespace ComboboxPopup {
+	export type State = ComboboxPopupState;
+	export type Props = ComboboxPopupProps;
+}