@octanejs/base-ui 0.1.1

package/src/utils/composite/keys.ts

@@ -0,0 +1,179 @@
+// Ported from .base-ui/packages/react/src/internals/composite/composite.ts (the constants,
+// `isNativeInput`, `scrollIntoViewIfNeeded`) + `@base-ui/utils/isElementDisabled`. Pure DOM
+// helpers — framework-agnostic, ported verbatim.
+
+// .base-ui/…/composite/constants.ts — marks the item that should hold the initial tab stop.
+export const ACTIVE_COMPOSITE_ITEM = 'data-composite-item-active';
+
+export const ARROW_UP = 'ArrowUp';
+export const ARROW_DOWN = 'ArrowDown';
+export const ARROW_LEFT = 'ArrowLeft';
+export const ARROW_RIGHT = 'ArrowRight';
+export const HOME = 'Home';
+export const END = 'End';
+export const PAGE_UP = 'PageUp';
+export const PAGE_DOWN = 'PageDown';
+
+export const HORIZONTAL_KEYS = new Set([ARROW_LEFT, ARROW_RIGHT]);
+export const HORIZONTAL_KEYS_WITH_EXTRA_KEYS = new Set([ARROW_LEFT, ARROW_RIGHT, HOME, END]);
+export const VERTICAL_KEYS = new Set([ARROW_UP, ARROW_DOWN]);
+export const VERTICAL_KEYS_WITH_EXTRA_KEYS = new Set([ARROW_UP, ARROW_DOWN, HOME, END]);
+export const ARROW_KEYS = new Set([...HORIZONTAL_KEYS, ...VERTICAL_KEYS]);
+export const COMPOSITE_KEYS = new Set([...ARROW_KEYS, HOME, END]);
+
+export const SHIFT = 'Shift' as const;
+export const CONTROL = 'Control' as const;
+export const ALT = 'Alt' as const;
+export const META = 'Meta' as const;
+export const MODIFIER_KEYS = new Set([SHIFT, CONTROL, ALT, META] as const);
+export type ModifierKey = 'Shift' | 'Control' | 'Alt' | 'Meta';
+
+export type TextDirection = 'ltr' | 'rtl';
+
+function isHTMLElement(el: unknown): el is HTMLElement {
+	return el != null && el instanceof HTMLElement;
+}
+
+function isInputElement(element: EventTarget): element is HTMLInputElement {
+	return isHTMLElement(element) && element.tagName === 'INPUT';
+}
+
+export function isNativeInput(
+	element: EventTarget,
+): element is HTMLElement & (HTMLInputElement | HTMLTextAreaElement) {
+	if (isInputElement(element) && element.selectionStart != null) {
+		return true;
+	}
+	if (isHTMLElement(element) && element.tagName === 'TEXTAREA') {
+		return true;
+	}
+	return false;
+}
+
+export function isElementDisabled(element: HTMLElement | null): boolean {
+	return (
+		element == null ||
+		element.hasAttribute('disabled') ||
+		element.getAttribute('aria-disabled') === 'true'
+	);
+}
+
+export function scrollIntoViewIfNeeded(
+	scrollContainer: HTMLElement | null,
+	element: HTMLElement | null,
+	direction: TextDirection,
+	orientation: 'horizontal' | 'vertical' | 'both',
+): void {
+	if (!scrollContainer || !element || !element.scrollTo) {
+		return;
+	}
+
+	let targetX = scrollContainer.scrollLeft;
+	let targetY = scrollContainer.scrollTop;
+
+	const isOverflowingX = scrollContainer.clientWidth < scrollContainer.scrollWidth;
+	const isOverflowingY = scrollContainer.clientHeight < scrollContainer.scrollHeight;
+
+	if (isOverflowingX && orientation !== 'vertical') {
+		const elementOffsetLeft = getOffset(scrollContainer, element, 'left');
+		const containerStyles = getStyles(scrollContainer);
+		const elementStyles = getStyles(element);
+
+		if (direction === 'ltr') {
+			if (
+				elementOffsetLeft + element.offsetWidth + elementStyles.scrollMarginRight >
+				scrollContainer.scrollLeft +
+					scrollContainer.clientWidth -
+					containerStyles.scrollPaddingRight
+			) {
+				targetX =
+					elementOffsetLeft +
+					element.offsetWidth +
+					elementStyles.scrollMarginRight -
+					scrollContainer.clientWidth +
+					containerStyles.scrollPaddingRight;
+			} else if (
+				elementOffsetLeft - elementStyles.scrollMarginLeft <
+				scrollContainer.scrollLeft + containerStyles.scrollPaddingLeft
+			) {
+				targetX =
+					elementOffsetLeft - elementStyles.scrollMarginLeft - containerStyles.scrollPaddingLeft;
+			}
+		}
+
+		if (direction === 'rtl') {
+			if (
+				elementOffsetLeft - elementStyles.scrollMarginRight <
+				scrollContainer.scrollLeft + containerStyles.scrollPaddingLeft
+			) {
+				targetX =
+					elementOffsetLeft - elementStyles.scrollMarginLeft - containerStyles.scrollPaddingLeft;
+			} else if (
+				elementOffsetLeft + element.offsetWidth + elementStyles.scrollMarginRight >
+				scrollContainer.scrollLeft +
+					scrollContainer.clientWidth -
+					containerStyles.scrollPaddingRight
+			) {
+				targetX =
+					elementOffsetLeft +
+					element.offsetWidth +
+					elementStyles.scrollMarginRight -
+					scrollContainer.clientWidth +
+					containerStyles.scrollPaddingRight;
+			}
+		}
+	}
+
+	if (isOverflowingY && orientation !== 'horizontal') {
+		const elementOffsetTop = getOffset(scrollContainer, element, 'top');
+		const containerStyles = getStyles(scrollContainer);
+		const elementStyles = getStyles(element);
+
+		if (
+			elementOffsetTop - elementStyles.scrollMarginTop <
+			scrollContainer.scrollTop + containerStyles.scrollPaddingTop
+		) {
+			targetY = elementOffsetTop - elementStyles.scrollMarginTop - containerStyles.scrollPaddingTop;
+		} else if (
+			elementOffsetTop + element.offsetHeight + elementStyles.scrollMarginBottom >
+			scrollContainer.scrollTop + scrollContainer.clientHeight - containerStyles.scrollPaddingBottom
+		) {
+			targetY =
+				elementOffsetTop +
+				element.offsetHeight +
+				elementStyles.scrollMarginBottom -
+				scrollContainer.clientHeight +
+				containerStyles.scrollPaddingBottom;
+		}
+	}
+
+	scrollContainer.scrollTo({ left: targetX, top: targetY, behavior: 'auto' });
+}
+
+function getOffset(ancestor: HTMLElement, element: HTMLElement, side: 'left' | 'top'): number {
+	const propName = side === 'left' ? 'offsetLeft' : 'offsetTop';
+	let result = 0;
+	let el = element;
+	while (el.offsetParent) {
+		result += el[propName];
+		if (el.offsetParent === ancestor) {
+			break;
+		}
+		el = el.offsetParent as HTMLElement;
+	}
+	return result;
+}
+
+function getStyles(element: HTMLElement): Record<string, number> {
+	const styles = getComputedStyle(element);
+	return {
+		scrollMarginTop: parseFloat(styles.scrollMarginTop) || 0,
+		scrollMarginRight: parseFloat(styles.scrollMarginRight) || 0,
+		scrollMarginBottom: parseFloat(styles.scrollMarginBottom) || 0,
+		scrollMarginLeft: parseFloat(styles.scrollMarginLeft) || 0,
+		scrollPaddingTop: parseFloat(styles.scrollPaddingTop) || 0,
+		scrollPaddingRight: parseFloat(styles.scrollPaddingRight) || 0,
+		scrollPaddingBottom: parseFloat(styles.scrollPaddingBottom) || 0,
+		scrollPaddingLeft: parseFloat(styles.scrollPaddingLeft) || 0,
+	};
+}

package/src/utils/composite/list-utils.ts

@@ -0,0 +1,78 @@
+// Vendored list-navigation helpers — Base UI itself vendors these from `floating-ui-react`
+// (`.base-ui/packages/react/src/floating-ui-react/utils.ts`); octane's `@octanejs/floating-ui`
+// implements the identical functions but does not export them publicly, so we keep a small
+// self-contained copy here (matching the octane port's implementations verbatim).
+
+export function getTarget(event: any): EventTarget | null {
+	if ('composedPath' in event) {
+		return event.composedPath()[0];
+	}
+	return event.target;
+}
+
+export function stopEvent(event: any): void {
+	event.preventDefault();
+	event.stopPropagation();
+}
+
+export function isIndexOutOfListBounds(listRef: { current: any[] }, index: number): boolean {
+	return index < 0 || index >= listRef.current.length;
+}
+
+export function isListIndexDisabled(
+	listRef: { current: any[] },
+	index: number,
+	disabledIndices?: number[] | ((index: number) => boolean),
+): boolean {
+	if (typeof disabledIndices === 'function') {
+		return disabledIndices(index);
+	}
+	if (disabledIndices) {
+		return disabledIndices.includes(index);
+	}
+	const element = listRef.current[index];
+	return (
+		element == null ||
+		element.hasAttribute('disabled') ||
+		element.getAttribute('aria-disabled') === 'true'
+	);
+}
+
+export function findNonDisabledListIndex(
+	listRef: { current: any[] },
+	options: {
+		startingIndex?: number;
+		decrement?: boolean;
+		disabledIndices?: number[] | ((index: number) => boolean);
+		amount?: number;
+	} = {},
+): number {
+	const { startingIndex = -1, decrement = false, disabledIndices, amount = 1 } = options;
+	let index = startingIndex;
+	do {
+		index += decrement ? -amount : amount;
+	} while (
+		index >= 0 &&
+		index <= listRef.current.length - 1 &&
+		isListIndexDisabled(listRef, index, disabledIndices)
+	);
+	return index;
+}
+
+export function getMinListIndex(
+	listRef: { current: any[] },
+	disabledIndices: number[] | ((index: number) => boolean) | undefined,
+): number {
+	return findNonDisabledListIndex(listRef, { disabledIndices });
+}
+
+export function getMaxListIndex(
+	listRef: { current: any[] },
+	disabledIndices: number[] | ((index: number) => boolean) | undefined,
+): number {
+	return findNonDisabledListIndex(listRef, {
+		decrement: true,
+		startingIndex: listRef.current.length,
+		disabledIndices,
+	});
+}

package/src/utils/composite/useCompositeItem.ts

@@ -0,0 +1,58 @@
+// Ported from .base-ui/packages/react/src/internals/composite/item/useCompositeItem.ts.
+// Gives a composite item its roving `tabIndex` (0 when highlighted, -1 otherwise) and the
+// focus/hover handlers that move the highlight. `useMergedRefs` → octane `useComposedRefs`.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useComposedRefs } from '../composeRefs';
+import { useCompositeRootContext } from '../CompositeRootContext';
+import { useCompositeListItem, type UseCompositeListItemParameters } from './useCompositeListItem';
+
+export interface UseCompositeItemParameters<Metadata> extends Pick<
+	UseCompositeListItemParameters<Metadata>,
+	'metadata' | 'indexGuessBehavior'
+> {}
+
+export function useCompositeItem<Metadata>(...args: any[]): {
+	compositeProps: Record<string, any>;
+	compositeRef: (node: HTMLElement | null) => void;
+	index: number;
+} {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCompositeItem');
+	const params = (user[0] as UseCompositeItemParameters<Metadata>) ?? {};
+
+	const { highlightItemOnHover, highlightedIndex, onHighlightedIndexChange } =
+		useCompositeRootContext();
+	const { ref, index } = useCompositeListItem(params, subSlot(slot, 'li'));
+
+	const isHighlighted = highlightedIndex === index;
+
+	const itemRef = useRef<HTMLElement | null>(null, subSlot(slot, 'itemRef'));
+	const mergedRef = useComposedRefs(ref, itemRef, subSlot(slot, 'merged'));
+
+	const compositeProps: Record<string, any> = {
+		tabIndex: isHighlighted ? 0 : -1,
+		onFocus() {
+			onHighlightedIndexChange(index);
+		},
+		onMouseMove() {
+			const item = itemRef.current;
+			if (!highlightItemOnHover || !item) {
+				return;
+			}
+			const disabled = item.hasAttribute('disabled') || (item as any).ariaDisabled === 'true';
+			if (!isHighlighted && !disabled) {
+				item.focus();
+			}
+		},
+	};
+
+	return {
+		compositeProps,
+		compositeRef: mergedRef as (node: HTMLElement | null) => void,
+		index,
+	};
+}

package/src/utils/composite/useCompositeListItem.ts

@@ -0,0 +1,108 @@
+// Ported from .base-ui/packages/react/src/internals/composite/list/useCompositeListItem.ts.
+// Registers a list item with the CompositeList and resolves its DOM-order `index` (via the
+// list's `subscribeMapChange`), stashing the element in `elementsRef[index]`.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useLayoutEffect, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useCompositeListContext } from './CompositeListContext';
+
+export enum IndexGuessBehavior {
+	None,
+	GuessFromOrder,
+}
+
+export interface UseCompositeListItemParameters<Metadata> {
+	index?: number;
+	label?: string | null;
+	metadata?: Metadata;
+	textRef?: { current: HTMLElement | null };
+	indexGuessBehavior?: IndexGuessBehavior;
+}
+
+export interface UseCompositeListItemReturnValue {
+	ref: (node: HTMLElement | null) => void;
+	index: number;
+}
+
+export function useCompositeListItem<Metadata>(...args: any[]): UseCompositeListItemReturnValue {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCompositeListItem');
+	const params = (user[0] as UseCompositeListItemParameters<Metadata>) ?? {};
+	const { label, metadata, textRef, indexGuessBehavior, index: externalIndex } = params;
+
+	const { register, unregister, subscribeMapChange, elementsRef, labelsRef, nextIndexRef } =
+		useCompositeListContext();
+
+	const indexRef = useRef(-1, subSlot(slot, 'idxRef'));
+	const [index, setIndex] = useState<number>(
+		externalIndex ??
+			(indexGuessBehavior === IndexGuessBehavior.GuessFromOrder
+				? () => {
+						if (indexRef.current === -1) {
+							const newIndex = nextIndexRef.current;
+							nextIndexRef.current += 1;
+							indexRef.current = newIndex;
+						}
+						return indexRef.current;
+					}
+				: -1),
+		subSlot(slot, 'idx'),
+	);
+
+	const componentRef = useRef<Element | null>(null, subSlot(slot, 'node'));
+
+	const ref = useCallback(
+		(node: HTMLElement | null) => {
+			componentRef.current = node;
+			if (index !== -1 && node !== null) {
+				elementsRef.current[index] = node;
+				if (labelsRef) {
+					const isLabelDefined = label !== undefined;
+					labelsRef.current[index] = isLabelDefined
+						? (label as string | null)
+						: (textRef?.current?.textContent ?? node.textContent);
+				}
+			}
+		},
+		[index, elementsRef, labelsRef, label, textRef],
+		subSlot(slot, 'ref'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (externalIndex != null) {
+				return undefined;
+			}
+			const node = componentRef.current;
+			if (node) {
+				register(node, metadata as Metadata);
+				return () => {
+					unregister(node);
+				};
+			}
+			return undefined;
+		},
+		[externalIndex, register, unregister, metadata],
+		subSlot(slot, 'e:reg'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (externalIndex != null) {
+				return undefined;
+			}
+			return subscribeMapChange((map) => {
+				const i = componentRef.current ? map.get(componentRef.current)?.index : null;
+				if (i != null) {
+					setIndex(i);
+				}
+			});
+		},
+		[externalIndex, subscribeMapChange, setIndex],
+		subSlot(slot, 'e:sub'),
+	);
+
+	return { ref, index };
+}