@octanejs/base-ui 0.1.49 → 0.1.51

package/src/combobox/root/ComboboxRoot.tsrx

@@ -0,0 +1,183 @@
+'use client';
+import * as React from 'octane';
+import { AriaCombobox, type AriaComboboxState } from './AriaCombobox.tsrx';
+
+/**
+ * Groups all parts of the combobox.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export function ComboboxRoot<Value, Multiple extends boolean | undefined = false, Item = Value>(
+	props: ComboboxRoot.Props<Value, Multiple, Item>,
+): React.ReactElement {
+	const {
+		multiple = false as Multiple,
+		defaultValue,
+		value,
+		onValueChange,
+		autoComplete,
+		...other
+	} = props;
+
+	return (
+		<AriaCombobox
+			{...(other as any)}
+			selectionMode={multiple ? 'multiple' : 'single'}
+			selectedValue={value}
+			defaultSelectedValue={defaultValue}
+			onSelectedValueChange={onValueChange}
+			formAutoComplete={autoComplete}
+		/>
+	);
+}
+
+type ModeFromMultiple<Multiple extends boolean | undefined> = Multiple extends true
+	? 'multiple'
+	: 'single';
+
+type ComboboxValueType<Value, Multiple extends boolean | undefined> = Multiple extends true
+	? Value[]
+	: Value;
+
+export type ComboboxRootProps<
+	Value,
+	Multiple extends boolean | undefined = false,
+	Item = Value,
+> = Omit<
+	AriaCombobox.Props<Value, ModeFromMultiple<Multiple>, Item>,
+	| 'fillInputOnItemPress'
+	| 'autoComplete'
+	| 'formAutoComplete'
+	| 'submitOnItemClick'
+	| 'autoHighlight'
+	| 'keepHighlight'
+	| 'highlightItemOnHover'
+	| 'itemToStringLabel'
+	| 'itemToStringValue'
+	| 'isItemEqualToValue'
+	// Different names
+	| 'selectionMode'
+	| 'defaultSelectedValue'
+	| 'selectedValue'
+	| 'onSelectedValueChange'
+	// Custom JSDoc
+	| 'actionsRef'
+	| 'onOpenChange'
+	| 'onInputValueChange'
+	| 'onItemHighlighted'
+> & {
+	/**
+	 * Whether multiple items can be selected.
+	 * @default false
+	 */
+	multiple?: Multiple | 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;
+	/**
+	 * Whether the first matching item is highlighted automatically while filtering.
+	 * @default false
+	 */
+	autoHighlight?: boolean | 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;
+	/**
+	 * When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input.
+	 * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+	 * With a `createItems()` collection, this receives the derived value, and the collection's
+	 * `getLabel` takes precedence for values it can resolve.
+	 */
+	itemToStringLabel?: ((itemValue: Value) => string) | undefined;
+	/**
+	 * When the item values are objects (`<Combobox.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.
+	 * With a `createItems()` collection, this receives the derived value.
+	 */
+	itemToStringValue?: ((itemValue: Value) => string) | undefined;
+	/**
+	 * Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially.
+	 * With a `createItems()` collection, both arguments are derived values.
+	 * Defaults to `Object.is` comparison.
+	 */
+	isItemEqualToValue?: ((itemValue: Value, value: Value) => boolean) | undefined;
+	/**
+	 * The uncontrolled selected value of the combobox when it's initially rendered.
+	 *
+	 * To render a controlled combobox, use the `value` prop instead.
+	 */
+	defaultValue?: ComboboxValueType<Value, Multiple> | null | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `unmount`: Manually unmounts the combobox.
+	 * Call this after any externally controlled closing animation finishes.
+	 */
+	actionsRef?: React.RefObject<ComboboxRoot.Actions | null> | undefined;
+	/**
+	 * Event handler called when the popup is opened or closed.
+	 */
+	onOpenChange?:
+		((open: boolean, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
+	/**
+	 * Event handler called when the input value changes.
+	 */
+	onInputValueChange?:
+		((inputValue: string, eventDetails: ComboboxRoot.ChangeEventDetails) => void) | undefined;
+	/**
+	 * Callback fired when an item is highlighted or unhighlighted.
+	 * Receives the highlighted item value (or `undefined` if no item is highlighted) and event details with a `reason` property describing why the highlight changed.
+	 * The `reason` can be:
+	 * - `'keyboard'`: the highlight changed due to keyboard navigation.
+	 * - `'pointer'`: the highlight changed due to pointer hovering.
+	 * - `'none'`: the highlight changed programmatically.
+	 */
+	onItemHighlighted?:
+		| ((
+				highlightedValue: Value | undefined,
+				eventDetails: ComboboxRoot.HighlightEventDetails,
+		  ) => void)
+		| undefined;
+	/**
+	 * The selected value of the combobox. Use when controlled.
+	 */
+	value?: ComboboxValueType<Value, Multiple> | null | undefined;
+	/**
+	 * Event handler called when the selected value of the combobox changes.
+	 */
+	onValueChange?:
+		| ((
+				value: ComboboxValueType<Value, Multiple> | (Multiple extends true ? never : null),
+				eventDetails: ComboboxRoot.ChangeEventDetails,
+		  ) => void)
+		| undefined;
+};
+
+export interface ComboboxRootState extends AriaComboboxState {}
+
+export type ComboboxRootActions = AriaCombobox.Actions;
+
+export type ComboboxRootChangeEventReason = AriaCombobox.ChangeEventReason;
+export type ComboboxRootChangeEventDetails = AriaCombobox.ChangeEventDetails;
+
+export type ComboboxRootHighlightEventReason = AriaCombobox.HighlightEventReason;
+export type ComboboxRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
+
+export namespace ComboboxRoot {
+	export type Props<
+		Value,
+		Multiple extends boolean | undefined = false,
+		Item = Value,
+	> = ComboboxRootProps<Value, Multiple, Item>;
+	export type State = ComboboxRootState;
+	export type Actions = ComboboxRootActions;
+	export type ChangeEventReason = ComboboxRootChangeEventReason;
+	export type ChangeEventDetails = ComboboxRootChangeEventDetails;
+	export type HighlightEventReason = ComboboxRootHighlightEventReason;
+	export type HighlightEventDetails = ComboboxRootHighlightEventDetails;
+}

package/src/combobox/root/ComboboxRootContext.tsrx

@@ -0,0 +1,66 @@
+'use client';
+import * as React from 'octane';
+import type { ComboboxStore } from '../store';
+import type { FloatingRootContext } from '../../floating-ui-react';
+
+export interface ComboboxDerivedItemsContext {
+	query: string;
+	hasItems: boolean;
+	filteredItems: any[];
+	/**
+	 * `filteredItems` flattened across groups and projected to selection values. Identical to the
+	 * items themselves unless `items` is a `createItems()` collection.
+	 */
+	flatFilteredValues: any[];
+}
+
+export const ComboboxRootContext = React.createContext<ComboboxStore | undefined>(undefined);
+export const ComboboxFloatingContext = React.createContext<FloatingRootContext | undefined>(
+	undefined,
+);
+export const ComboboxDerivedItemsContext = React.createContext<
+	ComboboxDerivedItemsContext | undefined
+>(undefined);
+export const ComboboxHasItemsContext = React.createContext<boolean>(false);
+// `inputValue` can't be placed in the store.
+// https://github.com/mui/base-ui/issues/2703
+export const ComboboxInputValueContext =
+	React.createContext<React.ComponentProps<'input'>['value']>('');
+
+export function useComboboxRootContext() {
+	const context = React.useContext(ComboboxRootContext) as ComboboxStore | undefined;
+	if (!context) {
+		throw new Error(
+			'Base UI: ComboboxRootContext is missing. Combobox parts must be placed within <Combobox.Root>.',
+		);
+	}
+	return context;
+}
+
+export function useComboboxFloatingContext() {
+	const context = React.useContext(ComboboxFloatingContext);
+	if (!context) {
+		throw new Error(
+			'Base UI: ComboboxFloatingContext is missing. Combobox parts must be placed within <Combobox.Root>.',
+		);
+	}
+	return context;
+}
+
+export function useComboboxDerivedItemsContext() {
+	const context = React.useContext(ComboboxDerivedItemsContext);
+	if (!context) {
+		throw new Error(
+			'Base UI: ComboboxItemsContext is missing. Combobox parts must be placed within <Combobox.Root>.',
+		);
+	}
+	return context;
+}
+
+export function useComboboxInputValueContext() {
+	return React.useContext(ComboboxInputValueContext);
+}
+
+export function useComboboxHasItemsContext() {
+	return React.useContext(ComboboxHasItemsContext);
+}

package/src/combobox/root/utils/constants.ts

@@ -0,0 +1,5 @@
+export const NO_ACTIVE_VALUE = Symbol('none');
+export const INITIAL_LAST_HIGHLIGHT: { value: any; index: number } = {
+	value: NO_ACTIVE_VALUE,
+	index: -1,
+} as const;

package/src/combobox/root/utils/index.ts

@@ -0,0 +1,68 @@
+import { stringifyAsLabel } from '../../../internals/resolveValueLabel.tsrx';
+import type { Filter } from './useFilter';
+
+export type FilterItemToString = ((item: any) => string) & {
+	selected?: ((value: any) => string) | undefined;
+};
+
+/**
+ * Derives the default id assigned to `Combobox.Popup` when the input is rendered inside it.
+ * Shared by the popup (which applies it) and the trigger (which references it via `aria-controls`)
+ * so the convention only lives in one place.
+ */
+export function getComboboxPopupId(rootId: string | null | undefined) {
+	return rootId == null ? undefined : `${rootId}-popup`;
+}
+
+/**
+ * Enhanced filter using Intl.Collator for more robust string matching.
+ * Uses the provided `itemToStringLabel` function if available, otherwise falls back to:
+ * • When `item` is an object with a `value` property, that property is used.
+ * • When `item` is a primitive (e.g. `string`), it is used directly.
+ */
+export function createCollatorItemFilter(
+	collatorFilter: Filter,
+	itemToStringLabel?: FilterItemToString,
+) {
+	return (item: any, query: string) => {
+		if (item == null) {
+			return false;
+		}
+
+		return collatorFilter.contains(item, query, itemToStringLabel);
+	};
+}
+
+/**
+ * Enhanced filter for single selection mode using Intl.Collator that shows all items
+ * when query is empty or matches the current selection, making it easier to browse options.
+ */
+export function createSingleSelectionCollatorFilter(
+	collatorFilter: Filter,
+	itemToStringLabel?: FilterItemToString,
+	selectedValue?: any,
+) {
+	return (item: any, query: string) => {
+		if (item == null) {
+			return false;
+		}
+		if (!query) {
+			return true;
+		}
+
+		const selectedValueToString = itemToStringLabel?.selected ?? itemToStringLabel;
+		const selectedString =
+			selectedValue != null ? stringifyAsLabel(selectedValue, selectedValueToString) : '';
+
+		// Handle case-insensitive matching consistently
+		if (
+			selectedString &&
+			collatorFilter.contains(selectedString, query) &&
+			selectedString.length === query.length
+		) {
+			return true;
+		}
+
+		return collatorFilter.contains(item, query, itemToStringLabel);
+	};
+}

package/src/combobox/root/utils/useFilter.ts

@@ -0,0 +1,50 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { createCollatorItemFilter, createSingleSelectionCollatorFilter } from './index';
+import {
+	type Filter,
+	type GetFilterParameters as UseFilterOptions,
+	getFilter,
+} from '../../../internals/filter';
+
+export type { Filter, UseFilterOptions };
+
+/**
+ * Matches items against a query using `Intl.Collator` for robust string matching.
+ */
+export const useCoreFilter = getFilter;
+
+export interface UseComboboxFilterOptions extends UseFilterOptions {
+	/**
+	 * Whether the combobox is in multiple selection mode.
+	 * @default false
+	 */
+	multiple?: boolean | undefined;
+	/**
+	 * The current value of the combobox, used to keep every item visible while the query still
+	 * matches the selection.
+	 */
+	value?: any;
+}
+
+/**
+ * Matches items against a query using `Intl.Collator` for robust string matching.
+ */
+export function useComboboxFilter(options: UseComboboxFilterOptions = {}): Filter {
+	const { multiple = false, value, ...collatorOptions } = options;
+
+	const coreFilter = getFilter(collatorOptions);
+
+	const contains: Filter['contains'] = React.useCallback(
+		(item: any, query: string, itemToString?: (item: any) => string) => {
+			if (multiple) {
+				return createCollatorItemFilter(coreFilter, itemToString)(item, query);
+			}
+			return createSingleSelectionCollatorFilter(coreFilter, itemToString, value)(item, query);
+		},
+		[coreFilter, value, multiple],
+	);
+
+	return React.useMemo(() => ({ ...coreFilter, contains }), [contains, coreFilter]);
+}

package/src/combobox/root/utils/useFilteredItems.ts

@@ -0,0 +1,11 @@
+/** @jsxImportSource octane */
+import { useComboboxDerivedItemsContext } from '../ComboboxRootContext.tsrx';
+
+/**
+ * Returns the internally filtered items.
+ * Treat the result as read-only: it is internal state and may be a shared frozen array.
+ */
+export function useFilteredItems<T>() {
+	const items = useComboboxDerivedItemsContext();
+	return items.filteredItems as T[];
+}

package/src/combobox/row/ComboboxRow.tsrx

@@ -0,0 +1,37 @@
+'use client';
+import * as React from 'octane';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { ComboboxRowContext } from './ComboboxRowContext';
+
+/**
+ * Displays a single row of items in a grid list.
+ * Enable `grid` on the root component to turn the listbox into a grid.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxRow = function ComboboxRow(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxRow.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+
+	const element = useRenderElement('div', componentProps, {
+		ref: forwardedRef,
+		props: [{ role: 'row' }, elementProps],
+	});
+
+	return <ComboboxRowContext.Provider value>{element}</ComboboxRowContext.Provider>;
+};
+
+export interface ComboboxRowState {}
+
+export interface ComboboxRowProps extends BaseUIComponentProps<'div', ComboboxRowState> {}
+
+export namespace ComboboxRow {
+	export type State = ComboboxRowState;
+	export type Props = ComboboxRowProps;
+}

package/src/combobox/row/ComboboxRowContext.ts

@@ -0,0 +1,9 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+export const ComboboxRowContext = React.createContext(false);
+
+export function useComboboxRowContext() {
+	return React.useContext(ComboboxRowContext);
+}

package/src/combobox/separator/ComboboxSeparator.tsrx

@@ -0,0 +1,37 @@
+'use client';
+import type * as React from 'octane';
+import { ListboxSeparator } from '../../utils/listbox-separator/ListboxSeparator.tsrx';
+import type { BaseUIComponentProps, Orientation } from '../../internals/types';
+
+export interface ComboboxSeparatorProps extends BaseUIComponentProps<
+	'div',
+	ComboboxSeparatorState
+> {
+	/**
+	 * The orientation of the separator.
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation | undefined;
+}
+
+export interface ComboboxSeparatorState {
+	/**
+	 * The orientation of the separator.
+	 */
+	orientation: Orientation;
+}
+
+/**
+ * A visual separator between items or groups.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxSeparator = ListboxSeparator as React.FunctionComponent<
+	ComboboxSeparatorProps & React.RefAttributes<HTMLDivElement>
+>;
+
+export namespace ComboboxSeparator {
+	export type Props = ComboboxSeparatorProps;
+	export type State = ComboboxSeparatorState;
+}

package/src/combobox/status/ComboboxStatus.tsrx

@@ -0,0 +1,49 @@
+'use client';
+import type * as React from 'octane';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { useInitialLiveRegionTextMutation } from '../utils/useInitialLiveRegionTextMutation';
+
+/**
+ * Displays a status message whose content changes are announced politely to screen readers.
+ * Useful for conveying the status of an asynchronously loaded list.
+ * This component's root element must remain mounted in the DOM to announce
+ * changes consistently across screen readers. Avoid hiding or removing the
+ * component itself with `display: none`, `hidden`, `aria-hidden`, or conditional
+ * rendering. Prefer updating or conditionally rendering its children instead.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxStatus = function ComboboxStatus(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxStatus.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, children: childrenProp, ...elementProps } = componentProps;
+
+	const statusRef = useInitialLiveRegionTextMutation<HTMLDivElement>();
+
+	return useRenderElement('div', componentProps, {
+		ref: [forwardedRef, statusRef],
+		props: [
+			{
+				children: childrenProp,
+				role: 'status',
+				'aria-live': 'polite',
+				'aria-atomic': true,
+			},
+			elementProps,
+		],
+	});
+};
+
+export interface ComboboxStatusState {}
+
+export interface ComboboxStatusProps extends BaseUIComponentProps<'div', ComboboxStatusState> {}
+
+export namespace ComboboxStatus {
+	export type State = ComboboxStatusState;
+	export type Props = ComboboxStatusProps;
+}