@octanejs/base-ui 0.1.49 → 0.1.51

package/src/internals/composite/composite.ts

@@ -0,0 +1,174 @@
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import type { TextDirection } from '../direction-context/DirectionContext.tsrx';
+
+export {
+	stopEvent,
+	isIndexOutOfListBounds,
+	isListIndexDisabled,
+	findNonDisabledListIndex,
+	getMaxListIndex,
+	getMinListIndex,
+} from '../../floating-ui-react/utils';
+
+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 COMPOSITE_KEYS = new Set([ARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, HOME, END]);
+
+export const SHIFT = 'Shift' as const;
+export const MODIFIER_KEYS = [SHIFT, 'Control', 'Alt', 'Meta'] as const;
+export type ModifierKey = (typeof MODIFIER_KEYS)[number];
+
+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 scrollIntoViewIfNeeded(
+	scrollContainer: HTMLElement | null,
+	element: HTMLElement | null,
+	direction: TextDirection,
+	orientation: 'horizontal' | 'vertical' | 'both',
+) {
+	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
+			) {
+				// overflow to the right, scroll to align right edges
+				targetX =
+					elementOffsetLeft +
+					element.offsetWidth +
+					elementStyles.scrollMarginRight -
+					scrollContainer.clientWidth +
+					containerStyles.scrollPaddingRight;
+			} else if (
+				elementOffsetLeft - elementStyles.scrollMarginLeft <
+				scrollContainer.scrollLeft + containerStyles.scrollPaddingLeft
+			) {
+				// overflow to the left, scroll to align left edges
+				targetX =
+					elementOffsetLeft - elementStyles.scrollMarginLeft - containerStyles.scrollPaddingLeft;
+			}
+		}
+
+		if (direction === 'rtl') {
+			if (
+				elementOffsetLeft - elementStyles.scrollMarginLeft <
+				scrollContainer.scrollLeft + containerStyles.scrollPaddingLeft
+			) {
+				// overflow to the left, scroll to align left edges
+				targetX =
+					elementOffsetLeft - elementStyles.scrollMarginLeft - containerStyles.scrollPaddingLeft;
+			} else if (
+				elementOffsetLeft + element.offsetWidth + elementStyles.scrollMarginRight >
+				scrollContainer.scrollLeft +
+					scrollContainer.clientWidth -
+					containerStyles.scrollPaddingRight
+			) {
+				// overflow to the right, scroll to align right edges
+				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
+		) {
+			// overflow upwards, align top edges
+			targetY = elementOffsetTop - elementStyles.scrollMarginTop - containerStyles.scrollPaddingTop;
+		} else if (
+			elementOffsetTop + element.offsetHeight + elementStyles.scrollMarginBottom >
+			scrollContainer.scrollTop + scrollContainer.clientHeight - containerStyles.scrollPaddingBottom
+		) {
+			// overflow downwards, align bottom edges
+			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') {
+	const propName = side === 'left' ? 'offsetLeft' : 'offsetTop';
+
+	let result = 0;
+
+	while (element.offsetParent) {
+		result += element[propName];
+		if (element.offsetParent === ancestor) {
+			break;
+		}
+		element = element.offsetParent as HTMLElement;
+	}
+
+	return result;
+}
+
+function getStyles(element: HTMLElement) {
+	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/internals/composite/constants.ts

@@ -0,0 +1 @@
+export const ACTIVE_COMPOSITE_ITEM = 'data-composite-item-active';

package/src/internals/composite/index.ts

@@ -0,0 +1,19 @@
+export { CompositeItem } from './item/CompositeItem.tsrx';
+export { CompositeList } from './list/CompositeList.tsrx';
+export type { CompositeMetadata } from './list/CompositeList.tsrx';
+export { CompositeListContext, useCompositeListContext } from './list/CompositeListContext';
+export type { CompositeListContextValue } from './list/CompositeListContext';
+export { CompositeRoot } from './root/CompositeRoot.tsrx';
+export { useCompositeListItem } from './list/useCompositeListItem';
+export type { UseCompositeListItemParameters } from './list/useCompositeListItem';
+export { useCompositeRoot } from './root/useCompositeRoot';
+export type { UseCompositeRootParameters } from './root/useCompositeRoot';
+export { gridNavigation } from './root/gridNavigation';
+export type {
+	CompositeGridConfig,
+	CompositeGridItemSize,
+	CompositeGridNavigationState,
+	CompositeGridNavigator,
+} from './root/gridNavigation';
+export { scrollIntoViewIfNeeded } from './composite';
+export { findNonDisabledListIndex, isListIndexDisabled } from '../../floating-ui-react/utils';

package/src/internals/composite/item/CompositeItem.tsrx

@@ -0,0 +1,57 @@
+'use client';
+import type * as React from 'octane';
+import { EMPTY_OBJECT, EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import { useRenderElement } from '../../useRenderElement.tsrx';
+import { useCompositeItem } from './useCompositeItem';
+import type { BaseUIComponentProps } from '../../types';
+import type { StateAttributesMapping } from '../../getStateAttributesProps';
+
+export function CompositeItem<Metadata, State extends Record<string, any>>(
+	componentProps: CompositeItem.Props<Metadata, State>,
+) {
+	const {
+		render,
+		className,
+		style,
+		state = EMPTY_OBJECT as State,
+		props = EMPTY_ARRAY,
+		refs = EMPTY_ARRAY,
+		metadata,
+		stateAttributesMapping,
+		tag = 'div',
+		...elementProps
+	} = componentProps;
+
+	const { compositeProps, compositeRef } = useCompositeItem({ metadata });
+
+	return useRenderElement(tag, componentProps, {
+		state,
+		// The composite ref attaches first so an outer item wins when nested items share a DOM node.
+		ref: [compositeRef, ...refs],
+		props: [compositeProps, ...props, elementProps],
+		stateAttributesMapping,
+	});
+}
+
+export interface CompositeItemState {}
+
+export interface CompositeItemProps<Metadata, State extends Record<string, any>> extends Pick<
+	BaseUIComponentProps<any, State>,
+	'render' | 'className' | 'style'
+> {
+	children?: React.OctaneNode;
+	metadata?: Metadata | undefined;
+	refs?: React.Ref<HTMLElement | null>[] | undefined;
+	props?: Array<Record<string, any> | (() => Record<string, any>)> | undefined;
+	state?: State | undefined;
+	stateAttributesMapping?: StateAttributesMapping<State> | undefined;
+	tag?: keyof React.JSX.IntrinsicElements | undefined;
+}
+
+export namespace CompositeItem {
+	export type State = CompositeItemState;
+	export type Props<Metadata, TState extends Record<string, any>> = CompositeItemProps<
+		Metadata,
+		TState
+	>;
+}

package/src/internals/composite/item/useCompositeItem.ts

@@ -0,0 +1,50 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useMergedRefs } from '@octanejs/base-ui-utils/useMergedRefs';
+import { useCompositeRootContext } from '../root/CompositeRootContext';
+import {
+	useCompositeListItem,
+	type UseCompositeListItemParameters,
+} from '../list/useCompositeListItem';
+import type { HTMLProps } from '../../types';
+
+export interface UseCompositeItemParameters<Metadata> extends Pick<
+	UseCompositeListItemParameters<Metadata>,
+	'metadata'
+> {}
+
+export function useCompositeItem<Metadata>(params: UseCompositeItemParameters<Metadata> = {}) {
+	const { highlightItemOnHover, highlightedIndex, onHighlightedIndexChange } =
+		useCompositeRootContext();
+	const { ref, index } = useCompositeListItem(params);
+
+	const isHighlighted = highlightedIndex === index;
+
+	const itemRef = React.useRef<HTMLElement | null>(null);
+	const mergedRef = useMergedRefs(ref, itemRef);
+
+	const compositeProps: HTMLProps = {
+		tabIndex: isHighlighted ? 0 : -1,
+		onFocus() {
+			onHighlightedIndexChange(index);
+		},
+		onMouseMove() {
+			const item = itemRef.current;
+			if (!highlightItemOnHover || !item) {
+				return;
+			}
+
+			const disabled = item.hasAttribute('disabled') || item.ariaDisabled === 'true';
+			if (!isHighlighted && !disabled) {
+				item.focus();
+			}
+		},
+	};
+
+	return {
+		compositeProps,
+		compositeRef: mergedRef as React.RefCallback<HTMLElement | null>,
+		index,
+	};
+}

package/src/internals/composite/list/CompositeList.tsrx

@@ -0,0 +1,325 @@
+/* eslint-disable no-bitwise */
+'use client';
+import * as React from 'octane';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { CompositeListContext, type CompositeListRegistration } from './CompositeListContext';
+
+export type CompositeMetadata<CustomMetadata> = {
+	index: number;
+} & CustomMetadata;
+
+interface CompositeListItem<Metadata> {
+	index: number;
+	element: HTMLElement;
+	registration: CompositeListRegistration<Metadata>;
+}
+
+/**
+ * Provides context for a list of items in a composite component.
+ */
+export function CompositeList<Metadata>(props: CompositeList.Props<Metadata>) {
+	const { children, elementsRef, labelsRef, onMapChange: onMapChangeProp } = props;
+
+	const onMapChange = useStableCallback(onMapChangeProp);
+
+	const [, setMapTick] = React.useState(false);
+
+	const listeners = useRefWithInit(createListeners).current;
+	const map = useRefWithInit(createMap<Metadata>).current;
+	const nextIndexRef = React.useRef(0);
+	const isDirtyRef = React.useRef(true);
+	const itemsRef = React.useRef<readonly CompositeListItem<Metadata>[] | null>(null);
+	const mutationObserverRef = React.useRef<MutationObserver | null>(null);
+
+	// Item effects can run without their parent rendering. Schedule one synchronous
+	// parent update for the whole commit so refs are rebuilt before paint and while
+	// the originating React event is still inside `act()` in tests.
+	const scheduleMapUpdate = useStableCallback(() => {
+		if (isDirtyRef.current) {
+			return;
+		}
+
+		isDirtyRef.current = true;
+		setMapTick((tick) => !tick);
+	});
+
+	const register = useStableCallback(
+		(node: Element, registration: CompositeListRegistration<Metadata>) => {
+			map.set(node, registration);
+			scheduleMapUpdate();
+		},
+	);
+
+	const unregister = useStableCallback((node: Element) => {
+		map.delete(node);
+		scheduleMapUpdate();
+	});
+
+	const syncRefs = useStableCallback((items: readonly CompositeListItem<Metadata>[]) => {
+		const nextMap = new Map<Element, CompositeMetadata<Metadata>>();
+
+		elementsRef.current.length = 0;
+		if (labelsRef) {
+			labelsRef.current.length = 0;
+		}
+
+		items.forEach((item) => {
+			nextMap.set(item.element, {
+				...(item.registration.metadata ?? ({} as Metadata)),
+				index: item.index,
+			});
+
+			elementsRef.current[item.index] = item.element;
+
+			if (labelsRef) {
+				labelsRef.current[item.index] =
+					item.registration.label !== undefined
+						? item.registration.label
+						: (item.registration.textRef?.current?.textContent ?? item.element.textContent);
+			}
+		});
+
+		nextIndexRef.current = elementsRef.current.length;
+
+		return nextMap;
+	});
+
+	function observe(sortedNodes: HTMLElement[]) {
+		mutationObserverRef.current?.disconnect();
+		mutationObserverRef.current = null;
+
+		// A single item can't reorder.
+		if (typeof MutationObserver !== 'function' || sortedNodes.length < 2) {
+			return;
+		}
+
+		const mutationObserver = new MutationObserver((entries) => {
+			// Only verify the order after a move: a node that was removed and later
+			// re-added within the same batch. Additions and removals alone can't
+			// change the relative order of the remaining items, and items that mount
+			// or unmount re-sort through `register`/`unregister`.
+			if (!hasMovedNode(entries)) {
+				return;
+			}
+
+			let previousConnectedNode: Element | null = null;
+
+			// If any connected node now appears before the previous connected node,
+			// wrappers/items moved and the index map needs to be rebuilt.
+			for (const node of sortedNodes) {
+				if (!node.isConnected) {
+					continue;
+				}
+
+				if (previousConnectedNode && sortByDocumentPosition(previousConnectedNode, node) > 0) {
+					mutationObserver.disconnect();
+					scheduleMapUpdate();
+					return;
+				}
+
+				previousConnectedNode = node;
+			}
+		});
+
+		mutationObserverRef.current = mutationObserver;
+
+		// A reorder that changes item indexes must invert at least one adjacent pair
+		// from the previous sorted order. Observing each pair's common parent catches
+		// both direct item moves and ancestor wrapper moves at the boundary.
+		const roots = new Set<Element>();
+		for (let i = 1; i < sortedNodes.length; i += 1) {
+			const root = getCommonAncestor(sortedNodes[i - 1], sortedNodes[i]);
+			if (root) {
+				roots.add(root);
+			}
+		}
+
+		roots.forEach((root) => mutationObserver.observe(root, { childList: true }));
+	}
+
+	const flush = useStableCallback(() => {
+		const [items, automaticNodes] = getCompositeListSnapshot(map);
+		const nextMap = syncRefs(items);
+
+		const previousItems = itemsRef.current;
+		const changed =
+			!previousItems ||
+			previousItems.length !== items.length ||
+			items.some((item, index) => {
+				const previousItem = previousItems[index];
+				return (
+					item.index !== previousItem.index ||
+					item.element !== previousItem.element ||
+					item.registration.index !== previousItem.registration.index ||
+					item.registration.metadata !== previousItem.registration.metadata
+				);
+			});
+
+		observe(automaticNodes);
+		itemsRef.current = items;
+		isDirtyRef.current = false;
+
+		if (!changed) {
+			return;
+		}
+
+		listeners.forEach((listener) => listener(nextMap));
+		onMapChange(nextMap);
+	});
+
+	useIsoLayoutEffect(() => {
+		// Re-copy the last committed snapshot when the ref objects change or Strict Mode replays
+		// effects without reattaching callback refs.
+		if (!isDirtyRef.current && itemsRef.current) {
+			syncRefs(itemsRef.current);
+		}
+
+		return () => {
+			elementsRef.current = [];
+			if (labelsRef) {
+				labelsRef.current = [];
+			}
+		};
+	}, [elementsRef, labelsRef, syncRefs]);
+
+	useIsoLayoutEffect(() => {
+		if (isDirtyRef.current) {
+			flush();
+		}
+	});
+
+	useIsoLayoutEffect(() => {
+		return () => {
+			mutationObserverRef.current?.disconnect();
+			// React 18 Strict Mode replays effects without replaying callback refs.
+			// Mark the retained map dirty so the replay rebuilds refs and observation.
+			isDirtyRef.current = true;
+		};
+	}, []);
+
+	const subscribeMapChange = useStableCallback((fn) => {
+		listeners.add(fn);
+		return () => {
+			listeners.delete(fn);
+		};
+	});
+
+	const contextValue = React.useMemo(
+		() => ({ register, unregister, subscribeMapChange, nextIndexRef }),
+		[register, unregister, subscribeMapChange, nextIndexRef],
+	);
+
+	return (
+		<CompositeListContext.Provider value={contextValue}>{children}</CompositeListContext.Provider>
+	);
+}
+
+function createMap<Metadata>() {
+	return new Map<Element, CompositeListRegistration<Metadata>>();
+}
+
+function createListeners() {
+	return new Set<Function>();
+}
+
+function getCompositeListSnapshot<Metadata>(
+	map: Map<Element, CompositeListRegistration<Metadata>>,
+) {
+	const reservedIndices = new Set<number>();
+	const items: CompositeListItem<Metadata>[] = [];
+	const automaticItems: CompositeListItem<Metadata>[] = [];
+
+	map.forEach((registration, node) => {
+		if (!node.isConnected) {
+			return;
+		}
+
+		const index = registration.index;
+		const item = {
+			index: index ?? -1,
+			element: node as HTMLElement,
+			registration,
+		};
+
+		if (index === null) {
+			automaticItems.push(item);
+		} else if (index >= 0) {
+			reservedIndices.add(index);
+			items.push(item);
+		}
+	});
+
+	let nextAutomaticIndex = 0;
+	automaticItems.sort((a, b) => sortByDocumentPosition(a.element, b.element));
+
+	automaticItems.forEach((item) => {
+		while (reservedIndices.has(nextAutomaticIndex)) {
+			nextAutomaticIndex += 1;
+		}
+
+		item.index = nextAutomaticIndex;
+		items.push(item);
+		nextAutomaticIndex += 1;
+	});
+
+	if (reservedIndices.size > 0) {
+		items.sort((a, b) => a.index - b.index);
+	}
+
+	return [items, automaticItems.map((item) => item.element)] as const;
+}
+
+function getCommonAncestor(firstNode: Element, lastNode: Element) {
+	let ancestor = firstNode.parentElement;
+
+	// The `parentElement` walk cannot cross shadow boundaries, so the native
+	// `contains` is sufficient here.
+	while (ancestor && !ancestor.contains(lastNode)) {
+		ancestor = ancestor.parentElement;
+	}
+
+	return ancestor;
+}
+
+function hasMovedNode(entries: MutationRecord[]) {
+	for (const entry of entries) {
+		for (let i = 0; i < entry.removedNodes.length; i += 1) {
+			if (entry.removedNodes[i].isConnected) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+function sortByDocumentPosition(a: Element, b: Element) {
+	// `DOCUMENT_POSITION_CONTAINED_BY` is always reported alongside `FOLLOWING`, and `CONTAINS`
+	// alongside `PRECEDING`, so testing `FOLLOWING` alone orders siblings and nested items alike.
+	return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+}
+
+export interface CompositeListState {}
+
+export interface CompositeListProps<Metadata> {
+	children: React.OctaneNode;
+	/**
+	 * A ref to the list of HTML elements, ordered by their index.
+	 * Explicit indexes can leave empty slots in the array.
+	 * `useListNavigation`'s `listRef` prop.
+	 */
+	elementsRef: React.RefObject<Array<HTMLElement | null>>;
+	/**
+	 * A ref to the list of element labels, ordered by their index.
+	 * `useTypeahead`'s `listRef` prop.
+	 */
+	labelsRef?: React.RefObject<Array<string | null>> | undefined;
+	onMapChange?: ((newMap: Map<Element, CompositeMetadata<Metadata>>) => void) | undefined;
+}
+
+export namespace CompositeList {
+	export type State = CompositeListState;
+	export type Props<Metadata> = CompositeListProps<Metadata>;
+}

package/src/internals/composite/list/CompositeListContext.ts

@@ -0,0 +1,28 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+export interface CompositeListRegistration<Metadata> {
+	metadata: Metadata | null;
+	index: number | null;
+	label: string | null | undefined;
+	textRef: React.RefObject<HTMLElement | null> | undefined;
+}
+
+export interface CompositeListContextValue<Metadata> {
+	register: (node: Element, registration: CompositeListRegistration<Metadata>) => void;
+	unregister: (node: Element) => void;
+	subscribeMapChange: (fn: (map: Map<Element, Metadata>) => void) => () => void;
+	nextIndexRef: React.RefObject<number>;
+}
+
+export const CompositeListContext = React.createContext<CompositeListContextValue<any>>({
+	register: () => {},
+	unregister: () => {},
+	subscribeMapChange: () => () => {},
+	nextIndexRef: { current: 0 },
+});
+
+export function useCompositeListContext() {
+	return React.useContext(CompositeListContext);
+}