@octanejs/base-ui 0.1.15 → 0.1.17

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

@@ -0,0 +1,437 @@
+// The two-dimensional half of `.base-ui/packages/react/src/floating-ui-react/utils/composite.ts`
+// (v1.6.0): the grid navigation algorithm and the cell-map helpers that let a spanning or densely
+// packed item occupy more than one cell. Both `gridNavigation` entry points
+// (`../floating/gridNavigation`, `./gridNavigation`) build on these, and nothing else does — a
+// composite that never passes `grid` leaves this module out of its bundle entirely, which is the
+// point of the injection.
+//
+// Upstream keeps this in the same module as the one-dimensional list algebra; this binding already
+// vendors that into `./list-utils`, so the grid half sits beside it rather than folding back in.
+// That also keeps `list-utils` free of a cycle: it imports `isElementVisible` from
+// `../floating/composite`, and nothing imports this file back.
+//
+// octane adaptations: `React.KeyboardEvent` is the NATIVE `KeyboardEvent`.
+// `createGridCellMap`'s invalid-width check is dev-only upstream; it throws unconditionally here,
+// because this binding carries no `process.env.NODE_ENV` branches and the production fallthrough
+// upstream accepts is an infinite placement loop, not a degraded layout.
+import { floor, type Dimensions } from '@floating-ui/utils';
+
+import { ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP } from './keys';
+import {
+	findNonDisabledListIndex,
+	isDifferentGridRow,
+	isIndexOutOfListBounds,
+	isListIndexDisabled,
+	stopEvent,
+	type DisabledIndices,
+} from './list-utils';
+
+export function getGridNavigatedIndex(
+	list: Array<HTMLElement | null>,
+	{
+		event,
+		orientation,
+		loopFocus,
+		onLoop,
+		rtl,
+		cols,
+		disabledIndices,
+		minIndex,
+		maxIndex,
+		prevIndex,
+		stopEvent: stop = false,
+	}: {
+		event: KeyboardEvent;
+		orientation: 'horizontal' | 'vertical' | 'both';
+		loopFocus: boolean;
+		onLoop?: ((event: KeyboardEvent, prevIndex: number, nextIndex: number) => number) | undefined;
+		rtl: boolean;
+		cols: number;
+		disabledIndices: DisabledIndices | undefined;
+		minIndex: number;
+		maxIndex: number;
+		prevIndex: number;
+		stopEvent?: boolean | undefined;
+	},
+): number {
+	let nextIndex = prevIndex;
+
+	let verticalDirection: 'up' | 'down' | undefined;
+	if (event.key === ARROW_UP) {
+		verticalDirection = 'up';
+	} else if (event.key === ARROW_DOWN) {
+		verticalDirection = 'down';
+	}
+
+	if (verticalDirection) {
+		// -------------------------------------------------------------------------
+		// Detect row structure only when handling vertical navigation. This keeps
+		// the non-vertical key paths free from row inference work.
+		// -------------------------------------------------------------------------
+		const rows: number[][] = [];
+		const rowIndexMap: number[] = [];
+		let hasRoleRow = false;
+		let visibleItemCount = 0;
+		{
+			let currentRowEl: Element | null = null;
+			let currentRowIndex = -1;
+
+			list.forEach((el, idx) => {
+				if (el == null) {
+					return;
+				}
+
+				visibleItemCount += 1;
+
+				const rowEl = el.closest('[role="row"]');
+				if (rowEl) {
+					hasRoleRow = true;
+				}
+
+				if (rowEl !== currentRowEl || currentRowIndex === -1) {
+					currentRowEl = rowEl;
+					currentRowIndex += 1;
+					rows[currentRowIndex] = [];
+				}
+				rows[currentRowIndex].push(idx);
+				rowIndexMap[idx] = currentRowIndex;
+			});
+		}
+
+		let hasDomRows = false;
+		let inferredDomCols = 0;
+
+		if (hasRoleRow) {
+			for (const row of rows) {
+				const rowLength = row.length;
+
+				if (rowLength > inferredDomCols) {
+					inferredDomCols = rowLength;
+				}
+
+				if (rowLength !== cols) {
+					hasDomRows = true;
+				}
+			}
+		}
+
+		const hasVirtualizedGaps = hasDomRows && visibleItemCount < list.length;
+		const verticalCols = inferredDomCols || cols;
+
+		const navigateVertically = (direction: 'up' | 'down') => {
+			if (!hasDomRows || prevIndex === -1) {
+				return undefined;
+			}
+
+			const currentRow = rowIndexMap[prevIndex];
+			if (currentRow == null) {
+				return undefined;
+			}
+
+			const colInRow = rows[currentRow].indexOf(prevIndex);
+			const step = direction === 'up' ? -1 : 1;
+
+			for (let nextRow = currentRow + step, i = 0; i < rows.length; i += 1, nextRow += step) {
+				if (nextRow < 0 || nextRow >= rows.length) {
+					if (!loopFocus || hasVirtualizedGaps) {
+						return undefined;
+					}
+					nextRow = nextRow < 0 ? rows.length - 1 : 0;
+					if (onLoop) {
+						const clampedCol = Math.min(colInRow, rows[nextRow].length - 1);
+						const targetItemIndex = rows[nextRow][clampedCol] ?? rows[nextRow][0];
+						const returnedItemIndex = onLoop(event, prevIndex, targetItemIndex);
+						nextRow = rowIndexMap[returnedItemIndex] ?? nextRow;
+					}
+				}
+
+				const targetRow = rows[nextRow];
+				for (let col = Math.min(colInRow, targetRow.length - 1); col >= 0; col -= 1) {
+					const candidate = targetRow[col];
+					if (!isListIndexDisabled(list, candidate, disabledIndices)) {
+						return candidate;
+					}
+				}
+			}
+
+			return undefined;
+		};
+
+		const navigateVerticallyWithInferredRows = (direction: 'up' | 'down') => {
+			if (!hasVirtualizedGaps || prevIndex === -1) {
+				return undefined;
+			}
+
+			const colInRow = prevIndex % verticalCols;
+			const rowStep = direction === 'up' ? -verticalCols : verticalCols;
+			const lastRowStart = maxIndex - (maxIndex % verticalCols);
+			const rowCount = floor(maxIndex / verticalCols) + 1;
+
+			for (
+				let rowStart = prevIndex - colInRow + rowStep, i = 0;
+				i < rowCount;
+				i += 1, rowStart += rowStep
+			) {
+				if (rowStart < 0 || rowStart > maxIndex) {
+					if (!loopFocus) {
+						return undefined;
+					}
+					rowStart = rowStart < 0 ? lastRowStart : 0;
+				}
+
+				const rowEnd = Math.min(rowStart + verticalCols - 1, maxIndex);
+				for (
+					let candidate = Math.min(rowStart + colInRow, rowEnd);
+					candidate >= rowStart;
+					candidate -= 1
+				) {
+					if (!isListIndexDisabled(list, candidate, disabledIndices)) {
+						return candidate;
+					}
+				}
+			}
+
+			return undefined;
+		};
+
+		if (stop) {
+			stopEvent(event);
+		}
+
+		const verticalCandidate =
+			navigateVertically(verticalDirection) ??
+			navigateVerticallyWithInferredRows(verticalDirection);
+
+		if (verticalCandidate !== undefined) {
+			nextIndex = verticalCandidate;
+		} else if (prevIndex === -1) {
+			nextIndex = verticalDirection === 'up' ? maxIndex : minIndex;
+		} else {
+			nextIndex = findNonDisabledListIndex(list, {
+				startingIndex: prevIndex,
+				amount: verticalCols,
+				decrement: verticalDirection === 'up',
+				disabledIndices,
+			});
+
+			if (loopFocus) {
+				if (verticalDirection === 'up' && (prevIndex - verticalCols < minIndex || nextIndex < 0)) {
+					const col = prevIndex % verticalCols;
+					const maxCol = maxIndex % verticalCols;
+					const offset = maxIndex - (maxCol - col);
+
+					if (maxCol === col) {
+						nextIndex = maxIndex;
+					} else {
+						nextIndex = maxCol > col ? offset : offset - verticalCols;
+					}
+					if (onLoop) {
+						nextIndex = onLoop(event, prevIndex, nextIndex);
+					}
+				}
+
+				if (verticalDirection === 'down' && prevIndex + verticalCols > maxIndex) {
+					nextIndex = findNonDisabledListIndex(list, {
+						startingIndex: (prevIndex % verticalCols) - verticalCols,
+						amount: verticalCols,
+						disabledIndices,
+					});
+					if (onLoop) {
+						nextIndex = onLoop(event, prevIndex, nextIndex);
+					}
+				}
+			}
+		}
+
+		if (isIndexOutOfListBounds(list, nextIndex)) {
+			nextIndex = prevIndex;
+		}
+	}
+
+	// Remains on the same row/column.
+	if (orientation === 'both') {
+		const prevRow = floor(prevIndex / cols);
+
+		if (event.key === (rtl ? ARROW_LEFT : ARROW_RIGHT)) {
+			if (stop) {
+				stopEvent(event);
+			}
+
+			if (prevIndex % cols !== cols - 1) {
+				nextIndex = findNonDisabledListIndex(list, {
+					startingIndex: prevIndex,
+					disabledIndices,
+				});
+
+				if (loopFocus && isDifferentGridRow(nextIndex, cols, prevRow)) {
+					nextIndex = findNonDisabledListIndex(list, {
+						startingIndex: prevIndex - (prevIndex % cols) - 1,
+						disabledIndices,
+					});
+					if (onLoop) {
+						nextIndex = onLoop(event, prevIndex, nextIndex);
+					}
+				}
+			} else if (loopFocus) {
+				nextIndex = findNonDisabledListIndex(list, {
+					startingIndex: prevIndex - (prevIndex % cols) - 1,
+					disabledIndices,
+				});
+				if (onLoop) {
+					nextIndex = onLoop(event, prevIndex, nextIndex);
+				}
+			}
+
+			if (isDifferentGridRow(nextIndex, cols, prevRow)) {
+				nextIndex = prevIndex;
+			}
+		}
+
+		if (event.key === (rtl ? ARROW_RIGHT : ARROW_LEFT)) {
+			if (stop) {
+				stopEvent(event);
+			}
+
+			if (prevIndex % cols !== 0) {
+				nextIndex = findNonDisabledListIndex(list, {
+					startingIndex: prevIndex,
+					decrement: true,
+					disabledIndices,
+				});
+
+				if (loopFocus && isDifferentGridRow(nextIndex, cols, prevRow)) {
+					nextIndex = findNonDisabledListIndex(list, {
+						startingIndex: prevIndex + (cols - (prevIndex % cols)),
+						decrement: true,
+						disabledIndices,
+					});
+					if (onLoop) {
+						nextIndex = onLoop(event, prevIndex, nextIndex);
+					}
+				}
+			} else if (loopFocus) {
+				nextIndex = findNonDisabledListIndex(list, {
+					startingIndex: prevIndex + (cols - (prevIndex % cols)),
+					decrement: true,
+					disabledIndices,
+				});
+				if (onLoop) {
+					nextIndex = onLoop(event, prevIndex, nextIndex);
+				}
+			}
+
+			if (isDifferentGridRow(nextIndex, cols, prevRow)) {
+				nextIndex = prevIndex;
+			}
+		}
+
+		const lastRow = floor(maxIndex / cols) === prevRow;
+
+		if (isIndexOutOfListBounds(list, nextIndex)) {
+			if (loopFocus && lastRow) {
+				nextIndex =
+					event.key === (rtl ? ARROW_RIGHT : ARROW_LEFT)
+						? maxIndex
+						: findNonDisabledListIndex(list, {
+								startingIndex: prevIndex - (prevIndex % cols) - 1,
+								disabledIndices,
+							});
+				if (onLoop) {
+					nextIndex = onLoop(event, prevIndex, nextIndex);
+				}
+			} else {
+				nextIndex = prevIndex;
+			}
+		}
+	}
+
+	return nextIndex;
+}
+
+/** For each cell index, gets the item index that occupies that cell */
+export function createGridCellMap(
+	sizes: Dimensions[],
+	cols: number,
+	dense: boolean,
+): Array<number | undefined> {
+	const cellMap: (number | undefined)[] = [];
+	let startIndex = 0;
+	sizes.forEach(({ width, height }, index) => {
+		if (width > cols) {
+			// octane: dev-only upstream. Left unguarded because the alternative is the placement loop
+			// below spinning forever.
+			throw new Error(
+				`[Floating UI]: Invalid grid - item width at index ${index} is greater than grid columns`,
+			);
+		}
+		let itemPlaced = false;
+		if (dense) {
+			startIndex = 0;
+		}
+		while (!itemPlaced) {
+			const targetCells: number[] = [];
+			for (let i = 0; i < width; i += 1) {
+				for (let j = 0; j < height; j += 1) {
+					targetCells.push(startIndex + i + j * cols);
+				}
+			}
+			if (
+				(startIndex % cols) + width <= cols &&
+				targetCells.every((cell) => cellMap[cell] == null)
+			) {
+				targetCells.forEach((cell) => {
+					cellMap[cell] = index;
+				});
+				itemPlaced = true;
+			} else {
+				startIndex += 1;
+			}
+		}
+	});
+
+	// convert into a non-sparse array
+	return [...cellMap];
+}
+
+/** Gets cell index of an item's corner or -1 when index is -1. */
+export function getGridCellIndexOfCorner(
+	index: number,
+	sizes: Dimensions[],
+	cellMap: (number | undefined)[],
+	cols: number,
+	corner: 'tl' | 'tr' | 'bl' | 'br',
+): number {
+	if (index === -1) {
+		return -1;
+	}
+
+	const firstCellIndex = cellMap.indexOf(index);
+	const sizeItem = sizes[index];
+
+	switch (corner) {
+		case 'tl':
+			return firstCellIndex;
+		case 'tr':
+			if (!sizeItem) {
+				return firstCellIndex;
+			}
+			return firstCellIndex + sizeItem.width - 1;
+		case 'bl':
+			if (!sizeItem) {
+				return firstCellIndex;
+			}
+			return firstCellIndex + (sizeItem.height - 1) * cols;
+		case 'br':
+			return cellMap.lastIndexOf(index);
+		default:
+			return -1;
+	}
+}
+
+/** Gets all cell indices that correspond to the specified indices */
+export function getGridCellIndices(
+	indices: (number | undefined)[],
+	cellMap: (number | undefined)[],
+): number[] {
+	return cellMap.flatMap((index, cellIndex) => (indices.includes(index) ? [cellIndex] : []));
+}

package/src/utils/composite/gridNavigation.ts

@@ -0,0 +1,127 @@
+// Ported from .base-ui/packages/react/src/internals/composite/root/gridNavigation.ts (v1.6.0).
+// The navigator a composite passes to `useCompositeRoot`'s `grid` option — distinct from
+// `../floating/gridNavigation`, which is the 1x1 navigator `useListNavigation` injects for itself.
+//
+// octane adaptations: the event is the NATIVE `KeyboardEvent`, and `React.RefObject<T>` is a plain
+// `{ current: T }`. Not a hook, so no slot.
+import {
+	createGridCellMap,
+	getGridCellIndexOfCorner,
+	getGridCellIndices,
+	getGridNavigatedIndex,
+} from './grid-utils';
+import { isListIndexDisabled } from './list-utils';
+import { ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT } from './keys';
+
+type CompositeGridElementsRef = { current: Array<HTMLElement | null> };
+type CompositeGridOnLoop = (event: KeyboardEvent, prevIndex: number, nextIndex: number) => number;
+
+export interface CompositeGridItemSize {
+	width: number;
+	height: number;
+}
+
+export interface CompositeGridConfig {
+	cols: number;
+	dense?: boolean | undefined;
+	itemSizes?: CompositeGridItemSize[] | undefined;
+}
+
+export interface CompositeGridNavigationState {
+	event: KeyboardEvent;
+	elementsRef: CompositeGridElementsRef;
+	highlightedIndex: number;
+	minIndex: number;
+	maxIndex: number;
+	orientation: 'horizontal' | 'vertical' | 'both';
+	loopFocus: boolean;
+	onLoop?: CompositeGridOnLoop | undefined;
+	disabledIndices?: number[] | undefined;
+	rtl: boolean;
+}
+
+export type CompositeGridNavigator = (state: CompositeGridNavigationState) => number;
+
+/**
+ * Builds the grid navigation handler passed to `CompositeRoot`/`useCompositeRoot`
+ * via the `grid` prop. Importing and calling this is the opt-in for grid
+ * navigation: composites that don't pass `grid` never reference the algorithm,
+ * so bundlers tree-shake the grid helpers out.
+ */
+export function gridNavigation(config: CompositeGridConfig): CompositeGridNavigator {
+	const { cols, dense = false, itemSizes } = config;
+
+	return (state) => {
+		const {
+			disabledIndices,
+			elementsRef,
+			event,
+			highlightedIndex,
+			loopFocus,
+			maxIndex,
+			minIndex,
+			onLoop,
+			orientation,
+			rtl,
+		} = state;
+
+		const sizes =
+			itemSizes ||
+			Array.from({ length: elementsRef.current.length }, () => ({
+				width: 1,
+				height: 1,
+			}));
+		// Work in hypothetical 1x1 cell indices, then convert back to item indices.
+		const cellMap = createGridCellMap(sizes, cols, dense);
+		const minGridIndex = cellMap.findIndex(
+			(index) => index != null && !isListIndexDisabled(elementsRef.current, index, disabledIndices),
+		);
+		const maxGridIndex = cellMap.reduce(
+			(foundIndex: number, index, cellIndex) =>
+				index != null && !isListIndexDisabled(elementsRef.current, index, disabledIndices)
+					? cellIndex
+					: foundIndex,
+			-1,
+		);
+		const cellIndex = getGridNavigatedIndex(
+			cellMap.map((itemIndex) => (itemIndex != null ? elementsRef.current[itemIndex] : null)),
+			{
+				event,
+				orientation,
+				loopFocus,
+				onLoop,
+				cols,
+				// Treat undefined gaps as disabled so navigation cannot land in them.
+				disabledIndices: getGridCellIndices(
+					[
+						...(disabledIndices ||
+							elementsRef.current.map((_, index) =>
+								isListIndexDisabled(elementsRef.current, index) ? index : undefined,
+							)),
+						undefined,
+					],
+					cellMap,
+				),
+				minIndex: minGridIndex,
+				maxIndex: maxGridIndex,
+				prevIndex: getGridCellIndexOfCorner(
+					highlightedIndex > maxIndex ? minIndex : highlightedIndex,
+					sizes,
+					cellMap,
+					cols,
+					// Choose the corner closest to the movement direction so spanning items
+					// do not immediately resolve back to themselves.
+					event.key === ARROW_DOWN
+						? 'bl'
+						: event.key === (rtl ? ARROW_LEFT : ARROW_RIGHT)
+							? 'tr'
+							: 'tl',
+				),
+				rtl,
+			},
+		);
+
+		// Navigated cell will never be nullish.
+		return cellMap[cellIndex] as number;
+	};
+}

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

@@ -1,7 +1,18 @@
 // 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).
+// (`.base-ui/packages/react/src/floating-ui-react/utils/composite.ts`, re-exported through
+// `internals/composite/composite.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.
+//
+// Signatures follow Base UI 1.6.0 exactly: the index helpers take the item ARRAY, while
+// `getMinListIndex`/`getMaxListIndex` take the REF (they need `listRef.current.length` at call
+// time). `isListIndexDisabled` is likewise the 1.6.0 body: an explicit `disabledIndices` hit wins,
+// an invisible element is always disabled, and the `disabled`/`aria-disabled` attribute fallback
+// applies only when the consumer passed no `disabledIndices` at all. `useListNavigation` depends on
+// that last clause — it deliberately omits `disabledIndices` when picking the item to focus on open
+// so attribute-disabled items are still skipped for consumers passing an empty array.
+import { isElementVisible } from '../floating/composite';
+
+export type DisabledIndices = ReadonlyArray<number> | ((index: number) => boolean);
 
 export function getTarget(event: any): EventTarget | null {
 	if ('composedPath' in event) {
@@ -15,36 +26,53 @@ export function stopEvent(event: any): void {
 	event.stopPropagation();
 }
 
-export function isIndexOutOfListBounds(listRef: { current: any[] }, index: number): boolean {
-	return index < 0 || index >= listRef.current.length;
+export function isDifferentGridRow(index: number, cols: number, prevRow: number): boolean {
+	return Math.floor(index / cols) !== prevRow;
+}
+
+export function isIndexOutOfListBounds(
+	list: ReadonlyArray<HTMLElement | null>,
+	index: number,
+): boolean {
+	return index < 0 || index >= list.length;
 }
 
 export function isListIndexDisabled(
-	listRef: { current: any[] },
+	list: ReadonlyArray<HTMLElement | null>,
 	index: number,
-	disabledIndices?: number[] | ((index: number) => boolean),
+	disabledIndices?: DisabledIndices | undefined,
 ): boolean {
-	if (typeof disabledIndices === 'function') {
-		return disabledIndices(index);
+	const isExplicitlyDisabled =
+		typeof disabledIndices === 'function'
+			? disabledIndices(index)
+			: (disabledIndices?.includes(index) ?? false);
+
+	if (isExplicitlyDisabled) {
+		return true;
 	}
-	if (disabledIndices) {
-		return disabledIndices.includes(index);
+
+	const element = list[index];
+	if (!element) {
+		return false;
 	}
-	const element = listRef.current[index];
+
+	if (!isElementVisible(element)) {
+		return true;
+	}
+
 	return (
-		element == null ||
-		element.hasAttribute('disabled') ||
-		element.getAttribute('aria-disabled') === 'true'
+		!disabledIndices &&
+		(element.hasAttribute('disabled') || element.getAttribute('aria-disabled') === 'true')
 	);
 }
 
 export function findNonDisabledListIndex(
-	listRef: { current: any[] },
+	list: ReadonlyArray<HTMLElement | null>,
 	options: {
-		startingIndex?: number;
-		decrement?: boolean;
-		disabledIndices?: number[] | ((index: number) => boolean);
-		amount?: number;
+		startingIndex?: number | undefined;
+		decrement?: boolean | undefined;
+		disabledIndices?: DisabledIndices | undefined;
+		amount?: number | undefined;
 	} = {},
 ): number {
 	const { startingIndex = -1, decrement = false, disabledIndices, amount = 1 } = options;
@@ -53,24 +81,24 @@ export function findNonDisabledListIndex(
 		index += decrement ? -amount : amount;
 	} while (
 		index >= 0 &&
-		index <= listRef.current.length - 1 &&
-		isListIndexDisabled(listRef, index, disabledIndices)
+		index <= list.length - 1 &&
+		isListIndexDisabled(list, index, disabledIndices)
 	);
 	return index;
 }
 
 export function getMinListIndex(
-	listRef: { current: any[] },
-	disabledIndices: number[] | ((index: number) => boolean) | undefined,
+	listRef: { current: ReadonlyArray<HTMLElement | null> },
+	disabledIndices?: DisabledIndices | undefined,
 ): number {
-	return findNonDisabledListIndex(listRef, { disabledIndices });
+	return findNonDisabledListIndex(listRef.current, { disabledIndices });
 }
 
 export function getMaxListIndex(
-	listRef: { current: any[] },
-	disabledIndices: number[] | ((index: number) => boolean) | undefined,
+	listRef: { current: ReadonlyArray<HTMLElement | null> },
+	disabledIndices?: DisabledIndices | undefined,
 ): number {
-	return findNonDisabledListIndex(listRef, {
+	return findNonDisabledListIndex(listRef.current, {
 		decrement: true,
 		startingIndex: listRef.current.length,
 		disabledIndices,