@octanejs/base-ui 0.1.49 → 0.1.51

package/src/combobox/input/ComboboxInputDataAttributes.ts

@@ -0,0 +1,55 @@
+import { CommonTriggerDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the corresponding popup is open.
+ */
+export const popupOpen = CommonTriggerDataAttributes.popupOpen;
+/**
+ * Present when the input is pressed.
+ */
+export const pressed = CommonTriggerDataAttributes.pressed;
+/**
+ * Present when the component is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Present when the component is readonly.
+ */
+export const readonly = 'data-readonly';
+/**
+ * Indicates which side the corresponding popup is positioned relative to its anchor.
+ * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null}
+ */
+export const popupSide = 'data-popup-side';
+/**
+ * Present when the component is required.
+ */
+export const required = 'data-required';
+/**
+ * Present when the component is in a valid state (when wrapped in Field.Root).
+ */
+export const valid = 'data-valid';
+/**
+ * Present when the component is in an invalid state (when wrapped in Field.Root).
+ */
+export const invalid = 'data-invalid';
+/**
+ * Present when the component has been touched (when wrapped in Field.Root).
+ */
+export const touched = 'data-touched';
+/**
+ * Present when the component's value has changed (when wrapped in Field.Root).
+ */
+export const dirty = 'data-dirty';
+/**
+ * Present when the component has a value (when wrapped in Field.Root).
+ */
+export const filled = 'data-filled';
+/**
+ * Present when the input is focused (when wrapped in Field.Root).
+ */
+export const focused = 'data-focused';
+/**
+ * Present when the corresponding items list is empty.
+ */
+export const listEmpty = 'data-list-empty';

package/src/combobox/input-group/ComboboxInputGroup.tsrx

@@ -0,0 +1,110 @@
+'use client';
+import type * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useFieldRootContext } from '../../internals/field-root-context/FieldRootContext';
+import type { FieldRoot } from '../../field/root/FieldRoot.tsrx';
+import { useComboboxRootContext } from '../root/ComboboxRootContext.tsrx';
+import type { Side } from '../../internals/useAnchorPositioning';
+import { triggerStateAttributesMapping } from '../utils/stateAttributesMapping';
+import { handleInputPress } from '../utils/handleInputPress';
+import { useListEmpty, usePopupSide } from '../utils/parts';
+import { contains } from '../../floating-ui-react/utils/element';
+
+/**
+ * A wrapper for the input and its associated controls.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxInputGroup = function ComboboxInputGroup(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxInputGroup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+
+	const { state: fieldState } = useFieldRootContext();
+	const store = useComboboxRootContext();
+
+	const open = store.useState('open');
+	const comboboxDisabled = store.useState('disabled');
+	const readOnly = store.useState('readOnly');
+	const hasSelectedValue = store.useState('hasSelectedValue');
+	const selectionMode = store.useState('selectionMode');
+
+	const popupSide = usePopupSide(store);
+	const disabled = comboboxDisabled;
+	const listEmpty = useListEmpty();
+	const placeholder = selectionMode === 'none' ? false : !hasSelectedValue;
+
+	const state: ComboboxInputGroup.State = {
+		...fieldState,
+		open,
+		disabled,
+		readOnly,
+		popupSide,
+		listEmpty,
+		placeholder,
+	};
+
+	const setInputGroupElement = useStableCallback((element: HTMLDivElement | null) => {
+		store.set('inputGroupElement', element);
+	});
+
+	return useRenderElement('div', componentProps, {
+		ref: [forwardedRef, setInputGroupElement],
+		props: [
+			{
+				role: 'group',
+				onMouseDown(event) {
+					handleInputPress(event, store, disabled, (target) => {
+						return contains(store.context.chipsContainerRef.current, target);
+					});
+				},
+			},
+			elementProps,
+		],
+		state,
+		stateAttributesMapping: triggerStateAttributesMapping,
+	});
+};
+
+export interface ComboboxInputGroupState extends FieldRoot.State {
+	/**
+	 * Whether the corresponding popup is open.
+	 */
+	open: boolean;
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the component should ignore user edits.
+	 */
+	readOnly: boolean;
+	/**
+	 * Indicates which side the corresponding popup is positioned relative to its anchor.
+	 */
+	popupSide: Side | null;
+	/**
+	 * Present when the corresponding items list is empty.
+	 */
+	listEmpty: boolean;
+	/**
+	 * Whether the combobox doesn't have a value.
+	 */
+	placeholder: boolean;
+}
+
+export interface ComboboxInputGroupProps extends BaseUIComponentProps<
+	'div',
+	ComboboxInputGroup.State
+> {}
+
+export namespace ComboboxInputGroup {
+	export type State = ComboboxInputGroupState;
+	export type Props = ComboboxInputGroupProps;
+}

package/src/combobox/input-group/ComboboxInputGroupDataAttributes.ts

@@ -0,0 +1,53 @@
+/**
+ * Present when the corresponding popup is open.
+ */
+export const popupOpen = 'data-popup-open';
+/**
+ * Present when the input group is pressed.
+ */
+export const pressed = 'data-pressed';
+/**
+ * Present when the component is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Present when the component is readonly.
+ */
+export const readonly = 'data-readonly';
+/**
+ * Indicates which side the corresponding popup is positioned relative to its anchor.
+ * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start' | null}
+ */
+export const popupSide = 'data-popup-side';
+/**
+ * Present when the component is in a valid state (when wrapped in Field.Root).
+ */
+export const valid = 'data-valid';
+/**
+ * Present when the component is in an invalid state (when wrapped in Field.Root).
+ */
+export const invalid = 'data-invalid';
+/**
+ * Present when the component has been touched (when wrapped in Field.Root).
+ */
+export const touched = 'data-touched';
+/**
+ * Present when the component's value has changed (when wrapped in Field.Root).
+ */
+export const dirty = 'data-dirty';
+/**
+ * Present when the component has a value (when wrapped in Field.Root).
+ */
+export const filled = 'data-filled';
+/**
+ * Present when the component is focused (when wrapped in Field.Root).
+ */
+export const focused = 'data-focused';
+/**
+ * Present when the corresponding items list is empty.
+ */
+export const listEmpty = 'data-list-empty';
+/**
+ * Present when the combobox doesn't have a value.
+ */
+export const placeholder = 'data-placeholder';

package/src/combobox/item/ComboboxItem.tsrx

@@ -0,0 +1,328 @@
+'use client';
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import {
+	useComboboxRootContext,
+	useComboboxHasItemsContext,
+	useComboboxDerivedItemsContext,
+} from '../root/ComboboxRootContext.tsrx';
+import { useCompositeListItem } from '../../internals/composite/list/useCompositeListItem';
+import type { BaseUIComponentProps, HTMLProps, NonNativeButtonProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { ComboboxItemContext } from './ComboboxItemContext';
+import { useButton } from '../../internals/use-button';
+import { useComboboxRowContext } from '../row/ComboboxRowContext';
+import {
+	compareItemEquality,
+	findItemIndex,
+	resolveSelectedIndex,
+} from '../../internals/itemEquality';
+
+interface ComboboxItemInnerProps {
+	componentProps: ComboboxItem.Props;
+	forwardedRef: React.Ref<HTMLDivElement>;
+	/**
+	 * Whether the list is externally virtualized. Passed down from the wrapper (which already
+	 * subscribes to it) so the inner component doesn't re-subscribe to the store.
+	 */
+	virtualized: boolean;
+	/**
+	 * Pre-resolved index for the virtualized fallback (when no `index` prop is provided).
+	 * `undefined` for the common path, where the index is derived from `index` prop or the
+	 * composite list registration order.
+	 */
+	indexFromFilter: number | undefined;
+}
+
+function ComboboxItemInner(props: ComboboxItemInnerProps) {
+	const { componentProps, forwardedRef, virtualized, indexFromFilter } = props;
+	const {
+		render,
+		className,
+		style,
+		value: itemValue = null,
+		index: indexProp,
+		disabled: disabledProp = false,
+		nativeButton = false,
+		...elementProps
+	} = componentProps;
+
+	const textRef = React.useRef<HTMLElement | null>(null);
+	const listItem = useCompositeListItem({
+		guess: true,
+		index: indexProp,
+		textRef,
+	});
+
+	const store = useComboboxRootContext();
+	const isRow = useComboboxRowContext();
+	const hasItems = useComboboxHasItemsContext();
+
+	const selectionMode = store.useState('selectionMode');
+	const rootDisabled = store.useState('disabled');
+	const readOnly = store.useState('readOnly');
+	const isItemEqualToValue = store.useState('isItemEqualToValue');
+
+	const disabled = rootDisabled || disabledProp;
+	const selectable = selectionMode !== 'none';
+	const index = indexProp ?? indexFromFilter ?? listItem.index;
+	const hasRegistered = index !== -1;
+
+	const rootId = store.useState('id');
+	const highlighted = store.useState('isActive', index);
+	const matchesSelectedValue = store.useState('isSelected', itemValue);
+	const itemProps = store.useState('itemProps');
+
+	const itemRef = React.useRef<HTMLDivElement | null>(null);
+
+	const id = rootId != null && hasRegistered ? `${rootId}-${index}` : undefined;
+	const selected = matchesSelectedValue && selectable;
+
+	useIsoLayoutEffect(() => {
+		const shouldRun = hasRegistered && (virtualized || indexProp != null);
+		if (!shouldRun) {
+			return undefined;
+		}
+
+		const list = store.context.listRef.current;
+		list[index] = itemRef.current;
+
+		return () => {
+			delete list[index];
+		};
+	}, [hasRegistered, virtualized, index, indexProp, store]);
+
+	useIsoLayoutEffect(() => {
+		if (!hasRegistered || hasItems) {
+			return undefined;
+		}
+
+		const visibleValues = store.context.valuesRef.current;
+		visibleValues[index] = itemValue;
+
+		return () => {
+			delete visibleValues[index];
+		};
+	}, [hasRegistered, hasItems, index, itemValue, store]);
+
+	useIsoLayoutEffect(() => {
+		if (!hasRegistered || hasItems) {
+			return;
+		}
+
+		// Runs while closed as well (the list can stay mounted via `keepMounted` or a
+		// force-mount) so the index tracks the item's composite position, keeping features
+		// like closed-trigger typeahead in sync when the rendered order changes.
+		const selectedValue = store.state.selectedValue;
+
+		let nextIndex = store.state.selectedIndex;
+		if (store.state.selectionMode === 'multiple' && Array.isArray(selectedValue)) {
+			nextIndex = resolveSelectedIndex(
+				index,
+				itemValue,
+				store.context.valuesRef.current,
+				selectedValue,
+				isItemEqualToValue,
+				nextIndex,
+			);
+		} else if (compareItemEquality(itemValue, selectedValue, isItemEqualToValue)) {
+			nextIndex = index;
+		}
+		store.set('selectedIndex', nextIndex);
+	}, [hasRegistered, hasItems, store, index, itemValue, isItemEqualToValue]);
+
+	const { getButtonProps, buttonRef } = useButton({
+		disabled,
+		focusableWhenDisabled: true,
+		native: nativeButton,
+		composite: true,
+	});
+
+	const state: ComboboxItemState = {
+		disabled,
+		selected,
+		highlighted,
+	};
+
+	function commitSelection(nativeEvent: MouseEvent) {
+		function selectItem() {
+			store.context.handleSelection(nativeEvent, itemValue);
+		}
+
+		if (store.state.submitOnItemClick) {
+			ReactDOM.flushSync(selectItem);
+			store.context.requestSubmit();
+		} else {
+			selectItem();
+		}
+	}
+
+	const defaultProps: HTMLProps = {
+		id,
+		role: isRow ? 'gridcell' : 'option',
+		'aria-selected': selectable ? selected : undefined,
+		// Focusable items steal focus from the input upon mouseup.
+		// Warn if the user renders a natively focusable element like `<button>`,
+		// as it should be a `<div>` instead.
+		tabIndex: undefined,
+		onPointerDownCapture(event) {
+			// The compat `mouseup` only fires for the primary pointer, so a non-primary
+			// touch must not overwrite the shared ref — a mismatch would make the primary
+			// pointer's release read as a drag-select and commit a second time after `click`.
+			if (event.isPrimary) {
+				store.context.pointerDownItemRef.current = event.currentTarget;
+			}
+			event.preventDefault();
+		},
+		onMouseDown(event) {
+			// iOS Safari can emit a synthetic mousedown for touch taps without a preceding
+			// pointerdown. Prevent default here too so tapping an item does not blur the input.
+			event.preventDefault();
+		},
+		onClick(event) {
+			if (disabled || readOnly) {
+				return;
+			}
+
+			commitSelection(event);
+		},
+		onMouseUp(event) {
+			const pointerStartedOnItem = store.context.pointerDownItemRef.current === event.currentTarget;
+			store.context.pointerDownItemRef.current = null;
+
+			if (disabled || readOnly || event.button !== 0 || pointerStartedOnItem || !highlighted) {
+				return;
+			}
+
+			commitSelection(event);
+		},
+	};
+
+	const element = useRenderElement('div', componentProps, {
+		ref: [buttonRef, forwardedRef, listItem.ref, itemRef],
+		state,
+		props: [itemProps, defaultProps, elementProps, getButtonProps],
+	});
+
+	const contextValue: ComboboxItemContext = React.useMemo(
+		() => ({
+			selected,
+			textRef,
+		}),
+		[selected, textRef],
+	);
+
+	return (
+		<ComboboxItemContext.Provider value={contextValue}>{element}</ComboboxItemContext.Provider>
+	);
+}
+
+/**
+ * Resolves the index from the filtered items for the virtualized fallback (no `index` prop).
+ * Isolated here so that this per-keystroke subscription to the derived-items context is only
+ * paid by virtualized items. Those re-render on every input change anyway — the parent
+ * virtualizer re-windows the list as the filtered set changes — so the extra subscription costs
+ * them nothing, while it keeps every non-virtualized item off that context.
+ */
+function ComboboxItemVirtualizedIndex(props: {
+	componentProps: ComboboxItem.Props;
+	forwardedRef: React.Ref<HTMLDivElement>;
+}) {
+	const { componentProps, forwardedRef } = props;
+
+	const store = useComboboxRootContext();
+	const isItemEqualToValue = store.useState('isItemEqualToValue');
+	const { flatFilteredValues } = useComboboxDerivedItemsContext();
+
+	const lookupValue = componentProps.value ?? null;
+	const indexFromFilter = findItemIndex(flatFilteredValues, lookupValue, isItemEqualToValue);
+
+	// Only reached when `virtualized` is true (see the wrapper below).
+	return (
+		<ComboboxItemInner
+			componentProps={componentProps}
+			forwardedRef={forwardedRef}
+			virtualized
+			indexFromFilter={indexFromFilter}
+		/>
+	);
+}
+
+/**
+ * An individual item in the list.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxItem = React.memo(function ComboboxItem(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxItem.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const store = useComboboxRootContext();
+	const virtualized = store.useState('virtualized');
+
+	// `virtualized` (and whether an item provides an explicit `index`) must be stable for an
+	// item's lifetime: the two branches return different component types, so flipping it at
+	// runtime remounts the item and resets its refs and effects.
+	if (virtualized && componentProps.index == null) {
+		return (
+			<ComboboxItemVirtualizedIndex componentProps={componentProps} forwardedRef={forwardedRef} />
+		);
+	}
+
+	return (
+		<ComboboxItemInner
+			componentProps={componentProps}
+			forwardedRef={forwardedRef}
+			virtualized={virtualized}
+			indexFromFilter={undefined}
+		/>
+	);
+});
+
+export interface ComboboxItemState {
+	/**
+	 * Whether the item should ignore user interaction.
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the item is selected.
+	 */
+	selected: boolean;
+	/**
+	 * Whether the item is highlighted.
+	 */
+	highlighted: boolean;
+}
+
+export interface ComboboxItemProps
+	extends NonNativeButtonProps, Omit<BaseUIComponentProps<'div', ComboboxItemState>, 'id'> {
+	children?: React.OctaneNode;
+	/**
+	 * An optional click handler for the item when selected.
+	 * It fires when clicking the item with the pointer, as well as when pressing `Enter` with the keyboard if the item is highlighted when the `Input` or `List` element has focus.
+	 */
+	onClick?: BaseUIComponentProps<'div', ComboboxItemState>['onClick'] | undefined;
+	/**
+	 * The index of the item in the list. Improves performance when specified by avoiding the need to calculate the index automatically from the DOM.
+	 */
+	index?: number | undefined;
+	/**
+	 * A unique value that identifies this item.
+	 * @default null
+	 */
+	value?: any;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+}
+
+export namespace ComboboxItem {
+	export type State = ComboboxItemState;
+	export type Props = ComboboxItemProps;
+}

package/src/combobox/item/ComboboxItemContext.ts

@@ -0,0 +1,20 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+export interface ComboboxItemContext {
+	selected: boolean;
+	textRef: React.RefObject<HTMLElement | null>;
+}
+
+export const ComboboxItemContext = React.createContext<ComboboxItemContext | undefined>(undefined);
+
+export function useComboboxItemContext() {
+	const context = React.useContext(ComboboxItemContext);
+	if (!context) {
+		throw new Error(
+			'Base UI: ComboboxItemContext is missing. ComboboxItem parts must be placed within <Combobox.Item>.',
+		);
+	}
+	return context;
+}

package/src/combobox/item/ComboboxItemDataAttributes.ts

@@ -0,0 +1,12 @@
+/**
+ * Present when the item is selected.
+ */
+export const selected = 'data-selected';
+/**
+ * Present when the item is highlighted.
+ */
+export const highlighted = 'data-highlighted';
+/**
+ * Present when the item is disabled.
+ */
+export const disabled = 'data-disabled';

package/src/combobox/item-indicator/ComboboxItemIndicator.tsrx

@@ -0,0 +1,109 @@
+'use client';
+import * as React from 'octane';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useComboboxItemContext } from '../item/ComboboxItemContext';
+import { type TransitionStatus, useTransitionStatus } from '../../internals/useTransitionStatus';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { transitionStatusMapping } from '../../internals/stateAttributesMapping';
+
+/**
+ * Indicates whether the item is selected.
+ * Renders a `<span>` element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export const ComboboxItemIndicator = function ComboboxItemIndicator(
+	componentPropsWithRef: React.PropsWithoutRef<ComboboxItemIndicator.Props> & {
+		ref?: React.Ref<HTMLSpanElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { selected } = useComboboxItemContext();
+
+	const shouldRender = componentProps.keepMounted || selected;
+	if (!shouldRender) {
+		return null;
+	}
+
+	// eslint-disable-next-line @typescript-eslint/no-use-before-define
+	return <Inner {...componentProps} ref={forwardedRef} />;
+};
+
+// Split the core implementation to avoid paying the hook costs unless the element needs to mount.
+const Inner = React.memo(
+	(
+		componentProps: React.PropsWithoutRef<ComboboxItemIndicator.Props> & {
+			ref?: React.Ref<HTMLSpanElement>;
+		},
+	) => {
+		const forwardedRef = componentProps.ref ?? null;
+		const { render, className, style, keepMounted, ...elementProps } = componentProps;
+
+		const { selected } = useComboboxItemContext();
+
+		const indicatorRef = React.useRef<HTMLSpanElement | null>(null);
+
+		const { transitionStatus, setMounted } = useTransitionStatus(selected);
+
+		const state: ComboboxItemIndicatorState = {
+			selected,
+			transitionStatus,
+		};
+
+		const element = useRenderElement('span', componentProps, {
+			ref: [forwardedRef, indicatorRef],
+			state,
+			props: [
+				{
+					'aria-hidden': true,
+					children: '✔️',
+				},
+				elementProps,
+			],
+			stateAttributesMapping: transitionStatusMapping,
+		});
+
+		useOpenChangeComplete({
+			batch: true,
+			enabled: !selected,
+			open: selected,
+			ref: indicatorRef,
+			onComplete() {
+				if (!selected) {
+					setMounted(false);
+				}
+			},
+		});
+
+		return element;
+	},
+);
+
+export interface ComboboxItemIndicatorProps extends BaseUIComponentProps<
+	'span',
+	ComboboxItemIndicatorState
+> {
+	children?: React.OctaneNode;
+	/**
+	 * Whether to keep the HTML element in the DOM when the item is not selected.
+	 * @default false
+	 */
+	keepMounted?: boolean | undefined;
+}
+
+export interface ComboboxItemIndicatorState {
+	/**
+	 * Whether the item is selected.
+	 */
+	selected: boolean;
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+}
+
+export namespace ComboboxItemIndicator {
+	export type Props = ComboboxItemIndicatorProps;
+	export type State = ComboboxItemIndicatorState;
+}

package/src/combobox/item-indicator/ComboboxItemIndicatorDataAttributes.ts

@@ -0,0 +1,10 @@
+import { TransitionStatusDataAttributes } from '../../internals/stateAttributesMapping';
+
+/**
+ * Present when the indicator begins animating in.
+ */
+export const startingStyle = TransitionStatusDataAttributes.startingStyle;
+/**
+ * Present when the indicator is animating out.
+ */
+export const endingStyle = TransitionStatusDataAttributes.endingStyle;