@octanejs/base-ui 0.1.50 → 0.1.51

package/src/autocomplete/root/AutocompleteRoot.tsrx

@@ -0,0 +1,296 @@
+'use client';
+import * as React from 'octane';
+import { AriaCombobox, type AriaComboboxState } from '../../combobox/root/AriaCombobox.tsrx';
+import { useCoreFilter } from '../../combobox/root/utils/useFilter';
+import type { BaseUIChangeEventDetails } from '../../internals/createBaseUIEventDetails';
+import { stringifyAsLabel, type Group } from '../../internals/resolveValueLabel.tsrx';
+import { REASONS } from '../../internals/reasons';
+
+/**
+ * Groups all parts of the autocomplete.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete)
+ */
+export function AutocompleteRoot<Items extends readonly { items: readonly any[] }[]>(
+	props: Omit<AutocompleteRoot.Props<Items[number]['items'][number]>, 'items'> & {
+		/**
+		 * The items to be displayed in the list.
+		 * Can be either a flat array of items or an array of groups with items.
+		 * Nullish entries are not supported: remove them from the data before passing it.
+		 */
+		items: Items;
+	},
+): React.ReactElement;
+export function AutocompleteRoot<ItemValue>(
+	props: Omit<AutocompleteRoot.Props<ItemValue>, 'items'> & {
+		/**
+		 * The items to be displayed in the list.
+		 * Can be either a flat array of items or an array of groups with items.
+		 * Nullish entries are not supported: remove them from the data before passing it.
+		 */
+		items?: readonly ItemValue[] | undefined;
+	},
+): React.ReactElement;
+export function AutocompleteRoot<ItemValue>(
+	props: AutocompleteRoot.Props<ItemValue>,
+): React.ReactElement {
+	const {
+		openOnInputClick = false,
+		value,
+		defaultValue,
+		onValueChange,
+		mode = 'list',
+		itemToStringValue,
+		...other
+	} = props;
+
+	// Inline completion writes the highlighted label into the input, which `readOnly` must prevent.
+	const enableInline = (mode === 'inline' || mode === 'both') && !props.readOnly;
+	const staticItems = mode === 'inline' || mode === 'none';
+
+	// Mirror the typed value for uncontrolled usage so we can compose the temporary
+	// inline input value.
+	const isControlled = value !== undefined;
+	const [internalValue, setInternalValue] = React.useState(defaultValue ?? '');
+	const [inlineInputValue, setInlineInputValue] = React.useState('');
+
+	React.useEffect(() => {
+		if (isControlled || !enableInline) {
+			setInlineInputValue('');
+		}
+	}, [value, isControlled, enableInline]);
+
+	// Compose the input value shown to the user: inline value takes precedence when present.
+	let resolvedInputValue: typeof value;
+	if (enableInline && inlineInputValue !== '') {
+		resolvedInputValue = inlineInputValue;
+	} else if (isControlled) {
+		resolvedInputValue = value ?? '';
+	} else {
+		resolvedInputValue = internalValue;
+	}
+
+	const collator = useCoreFilter({ locale: other.locale });
+
+	const resolvedQuery = String((isControlled ? value : internalValue) ?? '').trim();
+	const resolvedFilter =
+		staticItems || other.filter === null ? null : (other.filter ?? collator.contains);
+
+	function handleValueChange(nextValue: string, eventDetails: AutocompleteRoot.ChangeEventDetails) {
+		setInlineInputValue('');
+		if (!isControlled) {
+			setInternalValue(nextValue);
+		}
+		onValueChange?.(nextValue, eventDetails);
+	}
+
+	function handleItemHighlighted(
+		highlightedValue: any,
+		eventDetails: AriaCombobox.HighlightEventDetails,
+	) {
+		props.onItemHighlighted?.(highlightedValue, eventDetails);
+
+		if (eventDetails.reason === REASONS.pointer) {
+			return;
+		}
+
+		setInlineInputValue(
+			enableInline && highlightedValue != null
+				? stringifyAsLabel(highlightedValue, itemToStringValue)
+				: '',
+		);
+	}
+
+	return (
+		<AriaCombobox
+			{...other}
+			itemToStringLabel={itemToStringValue}
+			openOnInputClick={openOnInputClick}
+			selectionMode="none"
+			fillInputOnItemPress
+			filter={resolvedFilter}
+			filterQuery={
+				// Inline completion temporarily changes the displayed input without changing this query.
+				mode === 'both' ? resolvedQuery : undefined
+			}
+			autoComplete={mode}
+			inputValue={resolvedInputValue}
+			defaultInputValue={defaultValue}
+			onInputValueChange={handleValueChange}
+			onItemHighlighted={handleItemHighlighted}
+		/>
+	);
+}
+
+export interface AutocompleteRootState extends AriaComboboxState {}
+
+export interface AutocompleteRootActions {
+	unmount: () => void;
+}
+
+export type AutocompleteRootChangeEventReason = AriaCombobox.ChangeEventReason;
+export type AutocompleteRootChangeEventDetails =
+	BaseUIChangeEventDetails<AutocompleteRootChangeEventReason>;
+
+export type AutocompleteRootHighlightEventReason = AriaCombobox.HighlightEventReason;
+export type AutocompleteRootHighlightEventDetails = AriaCombobox.HighlightEventDetails;
+
+export interface AutocompleteRootProps<ItemValue> extends Omit<
+	AriaCombobox.Props<ItemValue, 'none'>,
+	| 'selectionMode'
+	| 'selectedValue'
+	| 'defaultSelectedValue'
+	| 'onSelectedValueChange'
+	| 'fillInputOnItemPress'
+	| 'itemToStringValue'
+	| 'isItemEqualToValue'
+	// Different names
+	| 'inputValue' // value
+	| 'defaultInputValue' // defaultValue
+	| 'onInputValueChange' // onValueChange
+	| 'autoComplete' // mode
+	| 'formAutoComplete'
+	| 'itemToStringLabel' // itemToStringValue
+	// Custom JSDoc
+	| 'inline'
+	| 'autoHighlight'
+	| 'keepHighlight'
+	| 'highlightItemOnHover'
+	| 'actionsRef'
+	| 'onOpenChange'
+	| 'openOnInputClick'
+	| 'form'
+	| 'items'
+	| 'filteredItems'
+	| 'filter'
+> {
+	/**
+	 * Identifies the form that owns the internal input.
+	 * Useful when the autocomplete is rendered outside the form.
+	 */
+	form?: string | undefined;
+	/**
+	 * The items to be displayed in the list.
+	 * Can be either a flat array of items or an array of groups with items.
+	 * Nullish entries are not supported: remove them from the data before passing it.
+	 */
+	items?: readonly ItemValue[] | readonly Group<ItemValue>[] | undefined;
+	/**
+	 * Filtered items to display in the list.
+	 * When provided, the list uses these items instead of filtering the `items` prop internally.
+	 * When `items` is also provided, this array must preserve its flat or grouped structure.
+	 * Nullish entries are not supported, as in `items`.
+	 * Use when you want to control filtering logic externally with the `useFilter()` hook.
+	 */
+	filteredItems?: readonly ItemValue[] | readonly Group<ItemValue>[] | undefined;
+	/**
+	 * Filter function used to match items against the input query.
+	 */
+	filter?: AriaCombobox.Props<ItemValue, 'none'>['filter'] | undefined;
+	/**
+	 * Controls how the autocomplete behaves with respect to list filtering and inline autocompletion.
+	 * - `list` (default): items are dynamically filtered based on the input value. The input value does not change based on the active item.
+	 * - `both`: items are dynamically filtered based on the input value, which will temporarily change based on the active item (inline autocompletion).
+	 * - `inline`: items are static (not filtered), and the input value will temporarily change based on the active item (inline autocompletion).
+	 * - `none`: items are static (not filtered), and the input value will not change based on the active item.
+	 * @default 'list'
+	 */
+	mode?: 'list' | 'both' | 'inline' | 'none' | undefined;
+	/**
+	 * Whether the list is rendered inline without using the component's own popup.
+	 *
+	 * Specify `open` unconditionally in conjunction with this prop so the list is considered
+	 * visible: `<Autocomplete.Root inline open>`
+	 * @default false
+	 */
+	inline?: boolean | undefined;
+	/**
+	 * Whether the first matching item is highlighted automatically.
+	 * - `true`: highlight after the user types and keep the highlight while the query changes.
+	 * - `'always'`: always highlight the first item.
+	 * @default false
+	 */
+	autoHighlight?: boolean | 'always' | undefined;
+	/**
+	 * Whether the highlighted item should be preserved when the pointer leaves the list.
+	 * @default false
+	 */
+	keepHighlight?: 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;
+	/**
+	 * The uncontrolled input value of the autocomplete when it's initially rendered.
+	 *
+	 * To render a controlled autocomplete, use the `value` prop instead.
+	 */
+	defaultValue?:
+		| AriaCombobox.Props<React.ComponentProps<'input'>['defaultValue'], 'none'>['defaultInputValue']
+		| undefined;
+	/**
+	 * The input value of the autocomplete. Use when controlled.
+	 */
+	value?:
+		AriaCombobox.Props<React.ComponentProps<'input'>['value'], 'none'>['inputValue'] | undefined;
+	/**
+	 * Event handler called when the input value of the autocomplete changes.
+	 */
+	onValueChange?:
+		((value: string, eventDetails: AutocompleteRootChangeEventDetails) => void) | undefined;
+	/**
+	 * Whether clicking an item should submit the autocomplete's owning form.
+	 * By default, clicking an item via a pointer or <kbd>Enter</kbd> key does not submit the owning form.
+	 * Useful when the autocomplete is used as a single-field form search input.
+	 * @default false
+	 */
+	submitOnItemClick?: AriaCombobox.Props<ItemValue, 'none'>['submitOnItemClick'] | undefined;
+	/**
+	 * When the item values are objects (`<Autocomplete.Item value={object}>`), this function converts the object value to a string representation for both display in the input and form submission.
+	 * If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop.
+	 */
+	itemToStringValue?: ((itemValue: ItemValue) => string) | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `unmount`: Manually unmounts the autocomplete.
+	 * Call this after any externally controlled closing animation finishes.
+	 */
+	actionsRef?: React.RefObject<AutocompleteRootActions | null> | undefined;
+	/**
+	 * Event handler called when the popup is opened or closed.
+	 */
+	onOpenChange?:
+		((open: boolean, eventDetails: AutocompleteRootChangeEventDetails) => 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: ItemValue | undefined,
+				eventDetails: AutocompleteRootHighlightEventDetails,
+		  ) => void)
+		| undefined;
+	/**
+	 * Whether the popup opens when clicking the input.
+	 * @default false
+	 */
+	openOnInputClick?: boolean | undefined;
+}
+
+export namespace AutocompleteRoot {
+	export type Props<ItemValue> = AutocompleteRootProps<ItemValue>;
+	export type State = AutocompleteRootState;
+	export type Actions = AutocompleteRootActions;
+	export type ChangeEventReason = AutocompleteRootChangeEventReason;
+	export type ChangeEventDetails = AutocompleteRootChangeEventDetails;
+	export type HighlightEventReason = AutocompleteRootHighlightEventReason;
+	export type HighlightEventDetails = AutocompleteRootHighlightEventDetails;
+}

package/src/autocomplete/separator/AutocompleteSeparator.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 AutocompleteSeparatorProps extends BaseUIComponentProps<
+	'div',
+	AutocompleteSeparatorState
+> {
+	/**
+	 * The orientation of the separator.
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation | undefined;
+}
+
+export interface AutocompleteSeparatorState {
+	/**
+	 * The orientation of the separator.
+	 */
+	orientation: Orientation;
+}
+
+/**
+ * A visual separator between items or groups.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete)
+ */
+export const AutocompleteSeparator = ListboxSeparator as React.FunctionComponent<
+	AutocompleteSeparatorProps & React.RefAttributes<HTMLDivElement>
+>;
+
+export namespace AutocompleteSeparator {
+	export type Props = AutocompleteSeparatorProps;
+	export type State = AutocompleteSeparatorState;
+}

package/src/autocomplete/trigger/AutocompleteTrigger.tsrx

@@ -0,0 +1,57 @@
+'use client';
+import type * as React from 'octane';
+import { ComboboxTrigger } from '../../combobox/trigger/ComboboxTrigger.tsrx';
+import type { FieldRootState } from '../../field/root/FieldRoot.tsrx';
+import type { Side } from '../../internals/useAnchorPositioning';
+import type { BaseUIComponentProps, NativeButtonProps } from '../../internals/types';
+
+/**
+ * A button that opens the popup.
+ * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete)
+ */
+export const AutocompleteTrigger = ComboboxTrigger as AutocompleteTrigger;
+
+export interface AutocompleteTriggerState extends FieldRootState {
+	/**
+	 * Whether the popup is open.
+	 */
+	open: boolean;
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: 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 component should ignore user edits.
+	 */
+	readOnly: boolean;
+}
+
+export interface AutocompleteTriggerProps
+	extends NativeButtonProps, BaseUIComponentProps<'button', AutocompleteTriggerState> {
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+}
+
+export interface AutocompleteTrigger {
+	(
+		componentProps: AutocompleteTriggerProps & React.RefAttributes<HTMLButtonElement>,
+	): React.ReactElement;
+}
+
+export namespace AutocompleteTrigger {
+	export type State = AutocompleteTriggerState;
+	export type Props = AutocompleteTriggerProps;
+}

package/src/autocomplete/trigger/AutocompleteTriggerDataAttributes.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 trigger 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 trigger 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/autocomplete/value/AutocompleteValue.tsrx

@@ -0,0 +1,38 @@
+'use client';
+import * as React from 'octane';
+import { useComboboxInputValueContext } from '../../combobox/root/ComboboxRootContext.tsrx';
+
+/**
+ * The current value of the autocomplete.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete)
+ */
+export function AutocompleteValue(props: AutocompleteValue.Props): React.ReactElement {
+	const { children } = props;
+
+	const inputValue = useComboboxInputValueContext();
+
+	let returnValue = null;
+	if (typeof children === 'function' && !React.isChildrenBlock(children)) {
+		returnValue = children(String(inputValue));
+	} else if (children != null) {
+		returnValue = children;
+	} else {
+		returnValue = inputValue;
+	}
+
+	return <React.Fragment>{returnValue}</React.Fragment>;
+}
+
+export interface AutocompleteValueState {}
+
+export interface AutocompleteValueProps {
+	children?:
+		NonNullable<React.OctaneNode> | null | undefined | ((value: string) => React.OctaneNode);
+}
+
+export namespace AutocompleteValue {
+	export type State = AutocompleteValueState;
+	export type Props = AutocompleteValueProps;
+}

package/src/avatar/fallback/AvatarFallback.tsrx

@@ -0,0 +1,68 @@
+'use client';
+import * as React from 'octane';
+import { useTimeout } from '@octanejs/base-ui-utils/useTimeout';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { useAvatarRootContext } from '../root/AvatarRootContext';
+import type { AvatarRootState } from '../root/AvatarRoot.tsrx';
+import { avatarStateAttributesMapping } from '../root/stateAttributesMapping';
+
+/**
+ * Rendered when the image fails to load or when no image is provided.
+ * Renders a `<span>` element.
+ *
+ * Documentation: [Base UI Avatar](https://base-ui.com/react/components/avatar)
+ */
+export const AvatarFallback = function AvatarFallback(
+	componentPropsWithRef: React.PropsWithoutRef<AvatarFallback.Props> & {
+		ref?: React.Ref<HTMLSpanElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { className, render, delay = 0, style, ...elementProps } = componentProps;
+
+	const { imageLoadingStatus } = useAvatarRootContext();
+	const [delayPassed, setDelayPassed] = React.useState(delay === 0);
+	const timeout = useTimeout();
+
+	React.useEffect(() => {
+		if (delay > 0) {
+			timeout.start(delay, () => setDelayPassed(true));
+		} else {
+			// Once the fallback is shown without a delay, keep it visible. Otherwise a later
+			// change from no delay to a number would re-hide an already-visible fallback.
+			setDelayPassed(true);
+		}
+		return timeout.clear;
+	}, [timeout, delay]);
+
+	const state: AvatarFallbackState = {
+		imageLoadingStatus,
+	};
+
+	const element = useRenderElement('span', componentProps, {
+		state,
+		ref: forwardedRef,
+		props: elementProps,
+		stateAttributesMapping: avatarStateAttributesMapping,
+		enabled: imageLoadingStatus !== 'loaded' && (delay === 0 || delayPassed),
+	});
+
+	return element;
+};
+
+export interface AvatarFallbackState extends AvatarRootState {}
+
+export interface AvatarFallbackProps extends BaseUIComponentProps<'span', AvatarFallbackState> {
+	/**
+	 * How long to wait before showing the fallback. Specified in milliseconds.
+	 *
+	 * @default 0
+	 */
+	delay?: number | undefined;
+}
+
+export namespace AvatarFallback {
+	export type State = AvatarFallbackState;
+	export type Props = AvatarFallbackProps;
+}