@octanejs/base-ui 0.1.14 → 0.1.16

package/src/utils/floating/useTypeahead.ts

@@ -0,0 +1,287 @@
+// Ported from .base-ui/packages/react/src/floating-ui-react/hooks/useTypeahead.ts (v1.6.0). Matches
+// list items as the user types, the way a native `<select>` does — usually paired with
+// `useListNavigation`. Returns an `ElementProps` bag whose `onKeyDown`/`onBlur` the reference and
+// the floating element both merge.
+//
+// octane adaptations: handlers receive the NATIVE event, so `event.nativeEvent` collapses to
+// `event`; `useIsoLayoutEffect` is octane's `useLayoutEffect`; every composed hook threads an
+// explicit slot.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { EMPTY_ARRAY } from '../empty';
+import { useStableCallback } from '../useStableCallback';
+import { useTimeout } from '../useTimeout';
+import { isListIndexDisabled, stopEvent, type DisabledIndices } from '../composite/list-utils';
+import { isElementVisible } from './composite';
+import { contains } from './element';
+import type { ElementProps, FloatingContext, FloatingRootContext } from './types';
+
+export interface UseTypeaheadProps {
+	/**
+	 * A ref which contains an array of strings whose indices match the HTML
+	 * elements of the list.
+	 * @default empty list
+	 */
+	listRef: { current: Array<string | null> };
+	/**
+	 * The index of the active (focused or highlighted) item in the list.
+	 * @default null
+	 */
+	activeIndex: number | null;
+	/**
+	 * Callback invoked with the matching index if found as the user types.
+	 */
+	onMatch?: ((index: number) => void) | undefined;
+	/**
+	 * Optional list of item elements that correspond to `listRef` indices.
+	 * When an element exists for an index, typeahead skips it if it is hidden by
+	 * `display: none`, `visibility: hidden|collapse`, or other
+	 * browser-reported visibility checks.
+	 */
+	elementsRef?: { current: Array<HTMLElement | null> } | undefined;
+	/**
+	 * Indices that are disabled, either as an array or a predicate (the same shape as
+	 * `useListNavigation`'s `disabledIndices`). Disabled items are skipped while matching,
+	 * so a single keypress advances to the next selectable item (matching native `<select>`
+	 * and arrow-key navigation). The disabled check doesn't read `elementsRef`, so consumers
+	 * whose items stay mounted-but-hidden while closed can still skip disabled items without
+	 * passing `elementsRef`.
+	 */
+	disabledIndices?: DisabledIndices | undefined;
+	/**
+	 * Callback invoked with the current typing activity as the user types.
+	 */
+	onTyping?: ((isTyping: boolean) => void) | undefined;
+	/**
+	 * Whether the hook is enabled, including all internal effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean | undefined;
+	/**
+	 * The number of milliseconds to wait before resetting the typed string.
+	 * @default 750
+	 */
+	resetMs?: number | undefined;
+	/**
+	 * The index of the selected item in the list, if available.
+	 * @default null
+	 */
+	selectedIndex?: number | null | undefined;
+}
+
+/**
+ * Provides a matching callback that can be used to focus an item as the user
+ * types, often used in tandem with `useListNavigation()`.
+ * @see https://floating-ui.com/docs/useTypeahead
+ */
+export function useTypeahead(...args: any[]): ElementProps {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTypeahead');
+	const context = user[0] as FloatingRootContext | FloatingContext;
+	const props = user[1] as UseTypeaheadProps;
+
+	const {
+		listRef,
+		elementsRef,
+		activeIndex,
+		onMatch: onMatchProp,
+		disabledIndices,
+		onTyping,
+		enabled = true,
+		resetMs = 750,
+		selectedIndex = null,
+	} = props;
+
+	const store = (context && 'rootStore' in context ? context.rootStore : context) as any;
+
+	const open = store.useState('open', subSlot(slot, 'open'));
+
+	const timeout = useTimeout(subSlot(slot, 'to'));
+	const stringRef = useRef('', subSlot(slot, 'str'));
+	const prevIndexRef = useRef<number | null>(
+		selectedIndex ?? activeIndex ?? -1,
+		subSlot(slot, 'prev'),
+	);
+	const matchIndexRef = useRef<number | null>(null, subSlot(slot, 'match'));
+
+	const onKeyDown = useStableCallback(
+		(event: KeyboardEvent) => {
+			function isVisible(index: number) {
+				const element = elementsRef?.current[index];
+				return !element || isElementVisible(element);
+			}
+
+			function isItemAvailable(index: number) {
+				if (!isVisible(index)) {
+					return false;
+				}
+				// Visibility is handled above; pass an empty element list so `isListIndexDisabled`
+				// resolves only the explicit `disabledIndices` (array/predicate) and skips its own
+				// visibility/attribute fallbacks. Consumers that don't opt in keep matching every
+				// visible item.
+				return disabledIndices == null || !isListIndexDisabled(EMPTY_ARRAY, index, disabledIndices);
+			}
+
+			function getMatchingIndex(list: Array<string | null>, string: string, startIndex = 0) {
+				if (list.length === 0) {
+					return -1;
+				}
+
+				const normalizedStartIndex = ((startIndex % list.length) + list.length) % list.length;
+				const lowerString = string.toLowerCase();
+
+				for (let offset = 0; offset < list.length; offset += 1) {
+					const index = (normalizedStartIndex + offset) % list.length;
+					const text = list[index];
+					if (!text?.toLowerCase().startsWith(lowerString) || !isItemAvailable(index)) {
+						continue;
+					}
+					return index;
+				}
+				return -1;
+			}
+
+			const listContent = listRef.current;
+
+			if (stringRef.current.length > 0 && event.key === ' ') {
+				// Space should continue the in-progress typeahead session.
+				stopEvent(event);
+				onTyping?.(true);
+			}
+
+			if (stringRef.current.length > 0 && stringRef.current[0] !== ' ') {
+				if (getMatchingIndex(listContent, stringRef.current) === -1 && event.key !== ' ') {
+					onTyping?.(false);
+				}
+			}
+
+			if (
+				listContent == null ||
+				// Character key.
+				event.key.length !== 1 ||
+				// Modifier key.
+				event.ctrlKey ||
+				event.metaKey ||
+				event.altKey
+			) {
+				return;
+			}
+
+			if (open && event.key !== ' ') {
+				stopEvent(event);
+				onTyping?.(true);
+			}
+
+			// Capture whether this is a new typing session before mutating the string.
+			const isNewSession = stringRef.current === '';
+			if (isNewSession) {
+				prevIndexRef.current = selectedIndex ?? activeIndex ?? -1;
+			}
+
+			// Bail out if the list contains a word like "llama" or "aaron". TODO:
+			// allow it in this case, too. Unavailable items are skipped while matching, so
+			// they must be ignored here as well — otherwise a hidden or disabled double-letter
+			// label would block rapid cycling through the available items.
+			const allowRapidSuccessionOfFirstLetter = listContent.every((text, index) =>
+				text && isItemAvailable(index) ? text[0]?.toLowerCase() !== text[1]?.toLowerCase() : true,
+			);
+
+			// Allows the user to cycle through items that start with the same letter
+			// in rapid succession.
+			if (allowRapidSuccessionOfFirstLetter && stringRef.current === event.key) {
+				stringRef.current = '';
+				prevIndexRef.current = matchIndexRef.current;
+			}
+
+			stringRef.current += event.key;
+			timeout.start(resetMs, () => {
+				stringRef.current = '';
+				prevIndexRef.current = matchIndexRef.current;
+				onTyping?.(false);
+			});
+
+			// Compute the starting index for this search.
+			// If this is a new typing session (string is empty), base it on the current
+			// selection/active item; otherwise continue from the last matched index.
+			const prevIndex = isNewSession ? (selectedIndex ?? activeIndex ?? -1) : prevIndexRef.current;
+			const startIndex = (prevIndex ?? 0) + 1;
+
+			const index = getMatchingIndex(listContent, stringRef.current, startIndex);
+
+			if (index !== -1) {
+				onMatchProp?.(index);
+				matchIndexRef.current = index;
+			} else if (event.key !== ' ') {
+				stringRef.current = '';
+				onTyping?.(false);
+			}
+		},
+		subSlot(slot, 'okd'),
+	);
+
+	const onBlur = useStableCallback(
+		(event: FocusEvent) => {
+			const next = event.relatedTarget as Element | null;
+			const currentDomReferenceElement = store.select('domReferenceElement');
+			const currentFloatingElement = store.select('floatingElement');
+			const withinComposite =
+				contains(currentDomReferenceElement, next) || contains(currentFloatingElement, next);
+
+			// Keep the session if focus moves within the composite (reference <-> floating).
+			if (withinComposite) {
+				return;
+			}
+
+			// End the current typing session when focus leaves the composite entirely.
+			timeout.clear();
+			stringRef.current = '';
+			prevIndexRef.current = matchIndexRef.current;
+			onTyping?.(false);
+		},
+		subSlot(slot, 'ob'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (!open && selectedIndex !== null) {
+				return;
+			}
+
+			timeout.clear();
+			matchIndexRef.current = null;
+
+			if (stringRef.current !== '') {
+				stringRef.current = '';
+			}
+		},
+		[open, selectedIndex, timeout],
+		subSlot(slot, 'e:reset'),
+	);
+
+	useLayoutEffect(
+		() => {
+			// Sync arrow key navigation but not typeahead navigation.
+			if (open && stringRef.current === '') {
+				prevIndexRef.current = selectedIndex ?? activeIndex ?? -1;
+			}
+		},
+		[open, selectedIndex, activeIndex],
+		subSlot(slot, 'e:sync'),
+	);
+
+	const sharedProps = useMemo(
+		() => ({ onKeyDown, onBlur }),
+		[onKeyDown, onBlur],
+		subSlot(slot, 'shared'),
+	);
+
+	return useMemo(
+		() => (enabled ? { reference: sharedProps, floating: sharedProps } : {}),
+		[enabled, sharedProps],
+		subSlot(slot, 'out'),
+	);
+}

package/src/utils/getCssDimensions.ts

@@ -0,0 +1,28 @@
+// Ported from .base-ui/packages/react/src/utils/getCssDimensions.ts (v1.6.0). Base UI reads this
+// from `@floating-ui/utils`; `round` is inlined here rather than adding an import.
+import { isHTMLElement } from './dom';
+
+export interface Dimensions {
+	width: number;
+	height: number;
+}
+
+export function getCssDimensions(element: Element): Dimensions {
+	const css = getComputedStyle(element);
+	// In testing environments the `width`/`height` properties are empty strings for SVG elements,
+	// which would parse to NaN. Fall back to 0.
+	let width = parseFloat(css.width) || 0;
+	let height = parseFloat(css.height) || 0;
+	const hasOffset = isHTMLElement(element);
+	const offsetWidth = hasOffset ? (element as HTMLElement).offsetWidth : width;
+	const offsetHeight = hasOffset ? (element as HTMLElement).offsetHeight : height;
+	const shouldFallback =
+		Math.round(width * 2) / 2 !== offsetWidth || Math.round(height * 2) / 2 !== offsetHeight;
+
+	if (shouldFallback) {
+		width = offsetWidth;
+		height = offsetHeight;
+	}
+
+	return { width, height };
+}

package/src/utils/getPseudoElementBounds.ts

@@ -0,0 +1,54 @@
+// Ported from .base-ui/packages/react/src/utils/getPseudoElementBounds.ts (v1.6.0). Returns an
+// element's bounding box widened to cover its `::before`/`::after` pseudo-elements, so hit-testing
+// (safe-polygon / mouse-tracking) accounts for decorations drawn outside the box.
+//
+// Pure — no renderer API is involved, so this is a straight transcription.
+import { ownerWindow } from './owner';
+import { platform } from './platform';
+
+interface ElementBounds {
+	left: number;
+	right: number;
+	top: number;
+	bottom: number;
+}
+
+export function getPseudoElementBounds(element: HTMLElement): ElementBounds {
+	const elementRect = element.getBoundingClientRect();
+	const win = ownerWindow(element);
+
+	// Avoid "Not implemented: window.getComputedStyle(elt, pseudoElt)" in jsdom.
+	if (platform.env.jsdom) {
+		return elementRect;
+	}
+
+	const beforeStyles = win.getComputedStyle(element, '::before');
+	const afterStyles = win.getComputedStyle(element, '::after');
+
+	const hasPseudoElements = beforeStyles.content !== 'none' || afterStyles.content !== 'none';
+
+	if (!hasPseudoElements) {
+		return elementRect;
+	}
+
+	// Get dimensions of pseudo-elements
+	const beforeWidth = parseFloat(beforeStyles.width) || 0;
+	const beforeHeight = parseFloat(beforeStyles.height) || 0;
+	const afterWidth = parseFloat(afterStyles.width) || 0;
+	const afterHeight = parseFloat(afterStyles.height) || 0;
+
+	// Calculate max dimensions including pseudo-elements
+	const totalWidth = Math.max(elementRect.width, beforeWidth, afterWidth);
+	const totalHeight = Math.max(elementRect.height, beforeHeight, afterHeight);
+
+	// Calculate the differences to extend the bounds
+	const widthDiff = totalWidth - elementRect.width;
+	const heightDiff = totalHeight - elementRect.height;
+
+	return {
+		left: elementRect.left - widthDiff / 2,
+		right: elementRect.right + widthDiff / 2,
+		top: elementRect.top - heightDiff / 2,
+		bottom: elementRect.bottom + heightDiff / 2,
+	};
+}

package/src/utils/platform.ts

@@ -28,6 +28,13 @@ function isAndroid(): boolean {
 	return /Android/.test(ua());
 }
 
+function isMac(): boolean {
+	if (typeof navigator === 'undefined') {
+		return false;
+	}
+	return /^Mac/.test(navigator.platform ?? '') && !isIOS();
+}
+
 function isJsdom(): boolean {
 	return /jsdom/i.test(ua());
 }
@@ -40,6 +47,9 @@ export const platform = {
 		get android() {
 			return isAndroid();
 		},
+		get mac() {
+			return isMac();
+		},
 	},
 	engine: {
 		get webkit() {

package/src/utils/popups/index.ts

@@ -2,3 +2,9 @@
 export * from './store';
 export * from './popupStoreUtils';
 export * from './popupTriggerMap';
+export {
+	createInlineMiddleware,
+	getInlineRectTriggerProps,
+	updateInlineRectCoords,
+	type InlineRectCoords,
+} from './inlineRect';

package/src/utils/popups/inlineRect.ts

@@ -0,0 +1,289 @@
+// Ported from .base-ui/packages/react/src/utils/popups/inlineRect.ts (v1.6.0). Floating UI ships an
+// `inline()` middleware; this local version mirrors its line-rect selection while adding trigger
+// identity checks, delayed-open hit-line reuse, and better left/right edge grouping for Preview
+// Card's reusable trigger model. Pure geometry plus a floating-ui middleware — transcribed as-is,
+// with React's ref types collapsed to plain `{ current }` objects and native event handlers.
+import { isElement } from '../dom';
+
+export interface InlineRectCoords {
+	/** The x position in viewport coordinates. */
+	x: number;
+	/** The y position in viewport coordinates. */
+	y: number;
+	/** The line index under the pointer when coordinates were captured. */
+	lineIndex?: number | undefined;
+	/** The trigger element whose rects produced these coordinates. */
+	element: Element;
+}
+
+interface RectLike {
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+	width: number;
+	height: number;
+}
+
+interface ClientRectLike extends RectLike {
+	x: number;
+	y: number;
+}
+
+interface ClientRectsReference {
+	getClientRects(): ArrayLike<RectLike>;
+}
+
+function createRect(left: number, top: number, right: number, bottom: number): ClientRectLike {
+	return {
+		left,
+		top,
+		right,
+		bottom,
+		x: left,
+		y: top,
+		width: right - left,
+		height: bottom - top,
+	};
+}
+
+function copyRect(rect: RectLike): RectLike {
+	return {
+		left: rect.left,
+		top: rect.top,
+		right: rect.right,
+		bottom: rect.bottom,
+		width: rect.width,
+		height: rect.height,
+	};
+}
+
+function getLineRects(rects: ArrayLike<RectLike>) {
+	const lines: RectLike[] = [];
+	let previousRect: RectLike | undefined;
+	let left = Number.POSITIVE_INFINITY;
+	let top = Number.POSITIVE_INFINITY;
+	let right = Number.NEGATIVE_INFINITY;
+	let bottom = Number.NEGATIVE_INFINITY;
+
+	for (const rect of Array.from(rects).sort((a, b) => a.top - b.top)) {
+		left = Math.min(left, rect.left);
+		top = Math.min(top, rect.top);
+		right = Math.max(right, rect.right);
+		bottom = Math.max(bottom, rect.bottom);
+
+		if (!previousRect || rect.top - previousRect.top > previousRect.height / 2) {
+			lines.push(copyRect(rect));
+		} else {
+			const line = lines[lines.length - 1];
+			line.left = Math.min(line.left, rect.left);
+			line.right = Math.max(line.right, rect.right);
+			line.bottom = Math.max(line.bottom, rect.bottom);
+			line.width = line.right - line.left;
+			line.height = line.bottom - line.top;
+		}
+
+		previousRect = rect;
+	}
+
+	return {
+		lines,
+		fallback: createRect(left, top, right, bottom),
+	};
+}
+
+function findLineIndex(lines: RectLike[], x: number, y: number) {
+	return lines.findIndex(
+		(lineRect) =>
+			x > lineRect.left - 2 &&
+			x < lineRect.right + 2 &&
+			y > lineRect.top - 2 &&
+			y < lineRect.bottom + 2,
+	);
+}
+
+function createClientRect(rect: RectLike) {
+	return createRect(rect.left, rect.top, rect.right, rect.bottom);
+}
+
+function getInlineRectCoords(
+	element: Element,
+	clientX: number,
+	clientY: number,
+): InlineRectCoords | undefined {
+	const { lines } = getLineRects(element.getClientRects());
+
+	if (lines.length < 2) {
+		return undefined;
+	}
+
+	const lineIndex = findLineIndex(lines, clientX, clientY);
+
+	return {
+		x: clientX,
+		y: clientY,
+		lineIndex: lineIndex === -1 ? undefined : lineIndex,
+		element,
+	};
+}
+
+function getInlineReferenceRect(
+	reference: ClientRectsReference,
+	placement: string,
+	coords: InlineRectCoords | undefined,
+): ClientRectLike | null {
+	const { lines, fallback } = getLineRects(reference.getClientRects());
+
+	if (lines.length < 2) {
+		return null;
+	}
+
+	const x = coords?.x;
+	const y = coords?.y;
+	const side = placement[0];
+
+	if (coords?.lineIndex != null && lines[coords.lineIndex]) {
+		return createClientRect(lines[coords.lineIndex]);
+	}
+
+	if (x != null && y != null) {
+		const lineIndex = findLineIndex(lines, x, y);
+
+		if (lineIndex !== -1) {
+			return createClientRect(lines[lineIndex]);
+		}
+	}
+
+	if (lines.length === 2 && lines[0].left > lines[1].right && x != null && y != null) {
+		return fallback;
+	}
+
+	if (side === 't' || side === 'b') {
+		const firstRect = lines[0];
+		const lastRect = lines[lines.length - 1];
+		const targetRect = side === 't' ? firstRect : lastRect;
+
+		return createRect(targetRect.left, firstRect.top, targetRect.right, lastRect.bottom);
+	}
+
+	const isLeft = side === 'l';
+	let left = lines[0].left;
+	let right = lines[0].right;
+	let edge = isLeft ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+	let targetFirstRect = lines[0];
+	let targetLastRect = lines[0];
+
+	for (const rect of lines) {
+		left = Math.min(left, rect.left);
+		right = Math.max(right, rect.right);
+
+		const nextEdge = isLeft ? rect.left : rect.right;
+
+		if ((isLeft && nextEdge < edge) || (!isLeft && nextEdge > edge)) {
+			edge = nextEdge;
+			targetFirstRect = rect;
+			targetLastRect = rect;
+		} else if (nextEdge === edge) {
+			targetLastRect = rect;
+		}
+	}
+
+	return createRect(left, targetFirstRect.top, right, targetLastRect.bottom);
+}
+
+function getContextElement(reference: any): Element | undefined {
+	if ('contextElement' in reference && reference.contextElement) {
+		return reference.contextElement;
+	}
+
+	return isElement(reference) ? (reference as Element) : undefined;
+}
+
+export function getInlineRectTriggerProps(
+	coordsRef: { current: InlineRectCoords | undefined },
+	isOpen: boolean,
+): Record<string, any> {
+	function updateCoords(event: MouseEvent) {
+		updateInlineRectCoords(coordsRef, event.currentTarget as Element, event.clientX, event.clientY);
+	}
+
+	function updateCoordsIfClosed(event: MouseEvent) {
+		if (!isOpen) {
+			updateCoords(event);
+		}
+	}
+
+	return {
+		onFocus() {
+			coordsRef.current = undefined;
+		},
+		onMouseEnter: updateCoordsIfClosed,
+		onMouseMove: updateCoordsIfClosed,
+	};
+}
+
+export function updateInlineRectCoords(
+	coordsRef: { current: InlineRectCoords | undefined },
+	element: Element,
+	clientX: number,
+	clientY: number,
+) {
+	const nextCoords = getInlineRectCoords(element, clientX, clientY);
+	coordsRef.current = nextCoords;
+	return nextCoords;
+}
+
+export function createInlineMiddleware(coordsRef: { current: InlineRectCoords | undefined }): any {
+	return {
+		name: 'inline',
+		async fn(state: any) {
+			const reference = state.elements.reference;
+
+			if (
+				typeof (reference as Partial<ClientRectsReference> | null)?.getClientRects !== 'function'
+			) {
+				return {};
+			}
+
+			const contextElement = getContextElement(reference);
+			const coords = coordsRef.current;
+			const currentCoords =
+				coords?.element === reference || coords?.element === contextElement ? coords : undefined;
+			const rect = getInlineReferenceRect(
+				reference as ClientRectsReference,
+				state.placement,
+				currentCoords,
+			);
+
+			if (!rect || typeof state.platform.getElementRects !== 'function') {
+				return {};
+			}
+
+			const resetRects = await state.platform.getElementRects({
+				reference: {
+					contextElement,
+					getBoundingClientRect() {
+						return rect;
+					},
+				},
+				floating: state.elements.floating,
+				strategy: state.strategy,
+			});
+
+			if (
+				state.rects.reference.x === resetRects.reference.x &&
+				state.rects.reference.y === resetRects.reference.y &&
+				state.rects.reference.width === resetRects.reference.width &&
+				state.rects.reference.height === resetRects.reference.height
+			) {
+				return {};
+			}
+
+			return {
+				reset: {
+					rects: resetRects,
+				},
+			};
+		},
+	};
+}