@lumx/vue 4.17.1-alpha.2 → 4.17.1-alpha.3

package/_internal/packages/lumx-core/src/js/utils/focus/setupFocusTrap.js

@@ -0,0 +1,83 @@
+import { makeListenerTowerContext } from "../function/listenerTower.js";
+import { getFirstAndLastFocusable } from "./getFirstAndLastFocusable.js";
+//#region ../lumx-core/src/js/utils/focus/setupFocusTrap.ts
+/**
+* Shared listener tower for focus traps.
+*
+* When multiple traps are activated, only the last registered one is active. When it tears down, the previously
+* registered trap is re-enabled.
+*/
+var FOCUS_TRAPS = makeListenerTowerContext();
+/**
+* Trap 'Tab' focus switch inside the `focusZoneElement`.
+*
+* Setup behavior:
+* 1. Focus `focusElement` if provided and contained in the zone.
+* 2. Otherwise focus the first focusable descendant.
+* 3. Otherwise focus the zone element itself (falling back to setting `tabindex="-1"` if needed) so that
+*    keyboard users (especially screen reader users) land inside the trapped region (e.g. an empty dialog).
+*
+* Tab key behavior:
+* - With at least one focusable descendant: focus cycles between the first and last focusable in the zone.
+* - With no focusable descendant: Tab is swallowed and focus is restored to the zone element itself.
+*
+* Multiple traps stack — only the latest one is active; previous traps re-enable when the latest is torn down.
+*
+* @param options Trap configuration.
+* @param signal  AbortSignal used to tear down the trap.
+*/
+function setupFocusTrap(options, signal) {
+	const { focusZoneElement, focusElement } = options;
+	if (!focusZoneElement || signal.aborted) return;
+	const rootNode = focusZoneElement.getRootNode();
+	let addedTabIndex = false;
+	/** Make the zone element programmatically focusable (so we can fall back to it). */
+	const ensureZoneIsFocusable = () => {
+		if (!focusZoneElement.hasAttribute("tabindex")) {
+			focusZoneElement.setAttribute("tabindex", "-1");
+			addedTabIndex = true;
+		}
+	};
+	/** Focus the zone element itself as a last-resort fallback. */
+	const focusZoneFallback = () => {
+		ensureZoneIsFocusable();
+		focusZoneElement.focus({ preventScroll: true });
+	};
+	const trapTabFocusInFocusZone = (evt) => {
+		if (evt.key !== "Tab") return;
+		const focusable = getFirstAndLastFocusable(focusZoneElement);
+		if (!focusable.first) {
+			evt.preventDefault();
+			focusZoneFallback();
+			return;
+		}
+		const { activeElement } = rootNode;
+		if (!activeElement || !evt.shiftKey && activeElement === focusable.last || !focusZoneElement.contains(activeElement)) {
+			focusable.first.focus();
+			evt.preventDefault();
+			return;
+		}
+		if (evt.shiftKey && activeElement === focusable.first) {
+			focusable.last.focus();
+			evt.preventDefault();
+		}
+	};
+	const keydownHandler = trapTabFocusInFocusZone;
+	const focusTrap = {
+		enable: () => rootNode.addEventListener("keydown", keydownHandler),
+		disable: () => rootNode.removeEventListener("keydown", keydownHandler)
+	};
+	if (focusElement && focusZoneElement.contains(focusElement)) focusElement.focus({ preventScroll: true });
+	else {
+		const firstFocusable = getFirstAndLastFocusable(focusZoneElement).first;
+		if (firstFocusable) firstFocusable.focus({ preventScroll: true });
+		else focusZoneFallback();
+	}
+	FOCUS_TRAPS.register(focusTrap);
+	signal.addEventListener("abort", () => {
+		FOCUS_TRAPS.unregister(focusTrap);
+		if (addedTabIndex) focusZoneElement.removeAttribute("tabindex");
+	}, { once: true });
+}
+//#endregion
+export { setupFocusTrap };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/createActiveItemState.js

@@ -0,0 +1,38 @@
+//#region ../lumx-core/src/js/utils/focusNavigation/createActiveItemState.ts
+/**
+* Create shared active item state with cleanup on abort.
+*
+* Callback invocation:
+* - `setActive(item)`: calls `onDeactivate(previous)` then `onActivate(item)`.
+* - `clear()`: calls `onDeactivate(current)` then `onClear()`.
+* - On `signal.abort()`: same as `clear()`.
+*
+* @param callbacks Focus state change callbacks.
+* @param signal AbortSignal for cleanup.
+* @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
+*/
+function createActiveItemState(callbacks, signal, initialItem) {
+	let activeItem = initialItem ?? null;
+	function clear() {
+		if (activeItem) {
+			callbacks.onDeactivate(activeItem);
+			activeItem = null;
+		}
+		callbacks.onClear?.();
+	}
+	signal.addEventListener("abort", clear);
+	return {
+		get active() {
+			return activeItem;
+		},
+		setActive(item) {
+			if (activeItem === item) return;
+			if (activeItem) callbacks.onDeactivate(activeItem);
+			activeItem = item;
+			if (item) callbacks.onActivate(item);
+		},
+		clear
+	};
+}
+//#endregion
+export { createActiveItemState };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/createGridFocusNavigation.js

@@ -0,0 +1,182 @@
+import { createPendingNavigation } from "./createPendingNavigation.js";
+import { createSelectorTreeWalker } from "../browser/createSelectorTreeWalker.js";
+import { createActiveItemState } from "./createActiveItemState.js";
+import { lastDescendant } from "../browser/lastDescendant.js";
+import { first } from "../iterable/first.js";
+//#region ../lumx-core/src/js/utils/focusNavigation/createGridFocusNavigation.ts
+/**
+* Create a focus navigation controller for a 2D grid.
+*
+* Resolves rows and cells by querying the DOM and commits focus by updating the
+* active-item state (which fires {@link FocusNavigationCallbacks}).
+*
+* Supports Up/Down between rows (with column memory) and Left/Right between cells
+* (with wrapping across rows).
+*
+* @param options Grid navigation options (container, rowSelector, cellSelector, wrap).
+* @param callbacks Callbacks for focus state changes.
+* @param signal AbortSignal for cleanup.
+* @returns FocusNavigationController instance.
+*/
+function createGridFocusNavigation(options, callbacks, signal) {
+	const { container, rowSelector, cellSelector, wrap = false } = options;
+	const state = createActiveItemState(callbacks, signal);
+	const isNavigableRow = (row) => row.querySelector(cellSelector) !== null;
+	const getFirstCell = (row) => row.querySelector(cellSelector);
+	const getRowCells = (row) => Array.from(row.querySelectorAll(cellSelector));
+	/** Lazily walk navigable rows from `start` in a `direction`, projecting each row through `dive`. */
+	function* findRows(start = "first", direction = "next", dive) {
+		const walker = createSelectorTreeWalker(container, rowSelector);
+		if (start instanceof HTMLElement) walker.currentNode = start;
+		else if (start === "last") walker.currentNode = lastDescendant(container);
+		let node;
+		do {
+			node = direction === "next" ? walker.nextNode() : walker.previousNode();
+			if (node && isNavigableRow(node)) {
+				const result = dive ? dive(node) : node;
+				if (result) yield result;
+			}
+		} while (node);
+	}
+	const findFirstVisibleRow = () => first(findRows());
+	const findLastVisibleRow = () => first(findRows("last", "prev"));
+	function findParentRow(cell) {
+		const row = cell.closest(rowSelector);
+		return row && container.contains(row) ? row : null;
+	}
+	/** Deferred navigation intent (replayed once cells are committed to the DOM). */
+	const pending = createPendingNavigation(signal);
+	/** Remembered column index for Up/Down navigation (column memory). */
+	let rememberedCol = 0;
+	/** Activate the cell at the given column in a row element. */
+	function focusCellInRow(row, col) {
+		const cells = getRowCells(row);
+		if (cells.length === 0) return false;
+		const clampedCol = Math.min(col, cells.length - 1);
+		state.setActive(cells[clampedCol]);
+		return true;
+	}
+	/** Activate the given cell (validates it is in the grid, updates column memory). */
+	function activateCell(item) {
+		const row = findParentRow(item);
+		if (!row) return false;
+		const col = getRowCells(row).indexOf(item);
+		if (col === -1) return false;
+		rememberedCol = col;
+		state.setActive(item);
+		return true;
+	}
+	/** Got to first cell in first row */
+	function goToFirst() {
+		const row = findFirstVisibleRow();
+		if (!row) return false;
+		rememberedCol = 0;
+		return focusCellInRow(row, 0);
+	}
+	/** Got to first cell in last row */
+	function goToLast() {
+		const row = findLastVisibleRow();
+		if (!row) return false;
+		rememberedCol = 0;
+		return focusCellInRow(row, 0);
+	}
+	/** Navigate horizontally (left or right) within cells, wrapping across rows. */
+	function goHorizontal(step) {
+		if (!state.active) return false;
+		const currentRow = findParentRow(state.active);
+		if (!currentRow) return false;
+		const cells = getRowCells(currentRow);
+		const col = cells.indexOf(state.active);
+		if (col === -1) return false;
+		const nextCol = col + step;
+		if (nextCol >= 0 && nextCol < cells.length) {
+			rememberedCol = nextCol;
+			state.setActive(cells[nextCol]);
+			return true;
+		}
+		if (!wrap) return false;
+		const targetRow = first(findRows(currentRow, step > 0 ? "next" : "prev")) ?? (step > 0 ? findFirstVisibleRow() : findLastVisibleRow());
+		if (!targetRow) return false;
+		const targetCells = getRowCells(targetRow);
+		if (targetCells.length === 0) return false;
+		const targetCol = step > 0 ? 0 : targetCells.length - 1;
+		rememberedCol = targetCol;
+		state.setActive(targetCells[targetCol]);
+		return true;
+	}
+	/** Navigate vertically (up or down) between rows with column memory. */
+	function goVertical(direction) {
+		if (!state.active) return direction === "next" ? goToFirst() : goToLast();
+		const currentRow = findParentRow(state.active);
+		if (!currentRow) return false;
+		const adjacentRow = first(findRows(currentRow, direction));
+		if (adjacentRow) return focusCellInRow(adjacentRow, rememberedCol);
+		if (wrap) {
+			const wrapRow = direction === "next" ? findFirstVisibleRow() : findLastVisibleRow();
+			if (wrapRow) return focusCellInRow(wrapRow, rememberedCol);
+		}
+		return false;
+	}
+	const selectors = {
+		get activeItem() {
+			return state.active;
+		},
+		get hasNavigableItems() {
+			return first(findRows()) !== null;
+		},
+		getFirst: () => first(findRows("first", "next", getFirstCell)),
+		getLast: () => first(findRows("last", "prev", getFirstCell)),
+		getMatching: (predicate) => first(findRows("first", "next", (row) => getRowCells(row).find(predicate)))
+	};
+	return {
+		type: "grid",
+		selectors,
+		goToOffset(offset) {
+			if (offset === 0) return state.active !== null;
+			const visibleRows = Array.from(findRows());
+			if (visibleRows.length === 0) return false;
+			if (!state.active) {
+				const startIdx = offset > 0 ? 0 : visibleRows.length - 1;
+				const remainingOffset = offset > 0 ? offset - 1 : offset + 1;
+				return focusCellInRow(visibleRows[Math.max(0, Math.min(startIdx + remainingOffset, visibleRows.length - 1))], rememberedCol);
+			}
+			const currentRow = findParentRow(state.active);
+			if (!currentRow) return false;
+			const rowIdx = visibleRows.indexOf(currentRow);
+			if (rowIdx === -1) return false;
+			const targetIdx = Math.max(0, Math.min(rowIdx + offset, visibleRows.length - 1));
+			if (targetIdx === rowIdx) return false;
+			return focusCellInRow(visibleRows[targetIdx], rememberedCol);
+		},
+		clear() {
+			state.clear();
+			pending.clear();
+		},
+		goTo(resolve) {
+			const target = resolve(selectors);
+			if (target && activateCell(target)) {
+				pending.clear();
+				return true;
+			}
+			pending.defer(() => this.goTo(resolve));
+			return false;
+		},
+		flushPendingNavigation() {
+			pending.flush();
+		},
+		goUp() {
+			return goVertical("prev");
+		},
+		goDown() {
+			return goVertical("next");
+		},
+		goLeft() {
+			return goHorizontal(-1);
+		},
+		goRight() {
+			return goHorizontal(1);
+		}
+	};
+}
+//#endregion
+export { createGridFocusNavigation };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/createListFocusNavigation.js

@@ -0,0 +1,151 @@
+import { createPendingNavigation } from "./createPendingNavigation.js";
+import { createSelectorTreeWalker } from "../browser/createSelectorTreeWalker.js";
+//#region ../lumx-core/src/js/utils/focusNavigation/createListFocusNavigation.ts
+/**
+* Create a focus navigation controller for a 1D list.
+*
+* This controller is **stateless** — it does not maintain an internal reference to
+* the active item. Instead it reads the active item from the DOM each time via the
+* `getActiveItem` callback provided in the options. This avoids any desync between
+* the controller's internal state and the actual DOM.
+*
+* @param options List navigation options (container, itemSelector, direction, wrap, getActiveItem).
+* @param callbacks Callbacks for focus state changes.
+* @param signal AbortSignal for cleanup.
+* @returns ListFocusNavigationController instance.
+*/
+function createListFocusNavigation(options, callbacks, signal) {
+	const { container, itemSelector, direction = "vertical", wrap = false, itemDisabledSelector, getActiveItem = () => null } = options;
+	/** Combined CSS selector matching enabled (non-disabled) items. */
+	const enabledItemSelector = itemDisabledSelector ? `${itemSelector}:not(${itemDisabledSelector})` : itemSelector;
+	/** Create a TreeWalker over items in the container. */
+	function createItemWalker(enabledOnly = true) {
+		return createSelectorTreeWalker(container, enabledOnly ? enabledItemSelector : itemSelector);
+	}
+	/** Find the first enabled item in the container. */
+	function findFirstEnabled() {
+		return container.querySelector(enabledItemSelector);
+	}
+	/** Find the last enabled item in the container. */
+	function findLastEnabled() {
+		const items = container.querySelectorAll(enabledItemSelector);
+		return items.length > 0 ? items[items.length - 1] : null;
+	}
+	const pending = createPendingNavigation(signal);
+	/** Find item at offset (lazily walk nodes) */
+	function findAtOffset(offset) {
+		const forward = offset > 0;
+		const stepsNeeded = Math.abs(offset);
+		const active = getActiveItem();
+		const walker = createItemWalker();
+		const step = forward ? () => walker.nextNode() : () => walker.previousNode();
+		let target = null;
+		let remaining = stepsNeeded;
+		if (active) walker.currentNode = active;
+		else if (!forward) {
+			target = walker.lastChild();
+			if (!target) return null;
+			remaining -= 1;
+		}
+		for (let i = 0; i < remaining; i++) {
+			const next = step();
+			if (next) target = next;
+			else if (active && wrap) {
+				const wrapped = forward ? findFirstEnabled() : findLastEnabled();
+				if (!wrapped || wrapped === active) break;
+				target = wrapped;
+				walker.currentNode = wrapped;
+			} else break;
+		}
+		return target;
+	}
+	function findMatching(predicate) {
+		const walker = createItemWalker(false);
+		let node = walker.nextNode();
+		while (node) {
+			if (predicate(node)) return node;
+			node = walker.nextNode();
+		}
+		return null;
+	}
+	/** Clear the active item and discard any pending navigation intent. */
+	function clear() {
+		const current = getActiveItem();
+		if (current) callbacks.onDeactivate(current);
+		pending.clear();
+		callbacks.onClear?.();
+	}
+	signal.addEventListener("abort", clear);
+	const selectors = {
+		enabledItemSelector,
+		get activeItem() {
+			return getActiveItem();
+		},
+		get hasNavigableItems() {
+			return container.querySelector(enabledItemSelector) !== null;
+		},
+		getFirst: findFirstEnabled,
+		getLast: findLastEnabled,
+		getMatching: findMatching,
+		findNearestEnabled(anchor) {
+			if (!container.contains(anchor)) return findFirstEnabled();
+			if (anchor instanceof HTMLElement && anchor.matches(enabledItemSelector)) return anchor;
+			const walker = createItemWalker();
+			walker.currentNode = anchor;
+			const next = walker.nextNode();
+			if (next instanceof HTMLElement) return next;
+			walker.currentNode = anchor;
+			return walker.previousNode();
+		}
+	};
+	/**
+	* Navigate via a resolver. The resolver receives the selectors to find the target.
+	* If the target is valid, focus is committed (deactivate current, activate target).
+	* If the target is not resolvable yet, the intent is deferred for later replay.
+	*/
+	function goTo(resolve) {
+		const target = resolve(selectors);
+		if (target && target.matches(itemSelector) && container.contains(target)) {
+			const current = getActiveItem();
+			if (current !== target) {
+				if (current) callbacks.onDeactivate(current);
+				callbacks.onActivate(target);
+			}
+			pending.clear();
+			return true;
+		}
+		pending.defer(() => goTo(resolve));
+		return false;
+	}
+	/** Go to the item at the given offset from the active item. */
+	function goToOffset(offset) {
+		if (offset === 0) return getActiveItem() !== null;
+		const target = findAtOffset(offset);
+		if (!target) return false;
+		return goTo(() => target);
+	}
+	return {
+		type: "list",
+		selectors,
+		goToOffset,
+		clear,
+		goTo,
+		flushPendingNavigation() {
+			pending.flush();
+		},
+		goUp() {
+			return direction === "vertical" ? goToOffset(-1) : false;
+		},
+		goDown() {
+			return direction === "vertical" ? goToOffset(1) : false;
+		},
+		goLeft() {
+			return direction === "horizontal" ? goToOffset(-1) : false;
+		},
+		goRight() {
+			return direction === "horizontal" ? goToOffset(1) : false;
+		}
+	};
+}
+//#endregion
+export { createListFocusNavigation };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/createPendingNavigation.js

@@ -0,0 +1,23 @@
+//#region ../lumx-core/src/js/utils/focusNavigation/createPendingNavigation.ts
+/** Create a pending navigation store; discards intent on abort. */
+function createPendingNavigation(signal) {
+	let pending = null;
+	const clear = () => {
+		pending = null;
+	};
+	signal.addEventListener("abort", clear);
+	return {
+		get hasPending() {
+			return pending !== null;
+		},
+		defer(navigate) {
+			pending = navigate;
+		},
+		flush() {
+			if (pending?.()) pending = null;
+		},
+		clear
+	};
+}
+//#endregion
+export { createPendingNavigation };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/setupRovingTabIndex.js

@@ -0,0 +1,167 @@
+import { createListFocusNavigation } from "./createListFocusNavigation.js";
+import { querySelectorInclusive } from "../browser/querySelectorInclusive.js";
+import { trackContainerFocus } from "../browser/trackContainerFocus.js";
+//#region ../lumx-core/src/js/utils/focusNavigation/setupRovingTabIndex.ts
+/**
+* Set up the roving tabindex pattern on a container element.
+*
+* - Keyboard navigation (Arrow keys, Home, End)
+* - tabindex management (`0` on active, `-1` on others)
+* - Mount normalization (single-tabstop invariant)
+* - DOM mutation handling via MutationObserver:
+*   removal recovery, insertion normalization, disabled-state changes
+*
+* Torn down when `signal` is aborted.
+*/
+function setupRovingTabIndex(options, signal) {
+	const { container, itemSelector, direction = "horizontal", itemDisabledSelector, itemSelectedAttr = "aria-selected", onItemFocused } = options;
+	const itemActiveSelector = `${itemSelector}[tabindex="0"]`;
+	let itemSelectedSelector = `${itemSelector}[${itemSelectedAttr}=true]`;
+	if (itemDisabledSelector) itemSelectedSelector += `:not(${itemDisabledSelector})`;
+	const containerFocus = trackContainerFocus(container, signal);
+	const nav = createListFocusNavigation({
+		type: "list",
+		container,
+		itemSelector,
+		direction,
+		wrap: true,
+		itemDisabledSelector,
+		getActiveItem: () => container.querySelector(itemActiveSelector)
+	}, {
+		onActivate(item) {
+			item.setAttribute("tabindex", "0");
+			item.focus();
+			onItemFocused?.(item);
+		},
+		onDeactivate(item) {
+			item.setAttribute("tabindex", "-1");
+		}
+	}, signal);
+	/** Set tabindex only when the value actually changes to avoid unnecessary DOM mutations. */
+	function setTabIndex(item, value) {
+		if (item.getAttribute("tabindex") !== value) item.setAttribute("tabindex", value);
+	}
+	/** Assign tabindex across `items`, ensuring at most one `tabindex="0"` */
+	function normalizeItems(items, hasExistingTabStop) {
+		let hasTabStop = hasExistingTabStop;
+		for (const item of items) {
+			if (!container.contains(item)) continue;
+			if (!(itemDisabledSelector ? item.matches(itemDisabledSelector) : false) && !hasTabStop) {
+				setTabIndex(item, "0");
+				hasTabStop = true;
+			} else setTabIndex(item, "-1");
+		}
+		if (!hasTabStop) {
+			const fallback = container.querySelector(nav.selectors.enabledItemSelector);
+			if (fallback) setTabIndex(fallback, "0");
+		}
+	}
+	/** Enforce the single-tabstop invariant across all items. */
+	function normalizeAllItems() {
+		const items = Array.from(container.querySelectorAll(itemSelector));
+		const { activeItem } = nav.selectors;
+		let preferredTabStopIndex = activeItem && items.indexOf(activeItem);
+		if (!preferredTabStopIndex || preferredTabStopIndex === -1) preferredTabStopIndex = items.findIndex((item) => item.matches(itemSelectedSelector));
+		if (preferredTabStopIndex && preferredTabStopIndex > 0) {
+			const [preferredItem] = items.splice(preferredTabStopIndex, 1);
+			items.unshift(preferredItem);
+		}
+		normalizeItems(items, false);
+	}
+	/** Ensure a tab stop exists; find a fallback near `anchor` and optionally move focus to it. */
+	function ensureTabStop(shouldFocus, anchor) {
+		if (container.querySelector(itemActiveSelector)) return;
+		const fallback = (anchor && nav.selectors.findNearestEnabled(anchor)) ?? container.querySelector(nav.selectors.enabledItemSelector);
+		if (!fallback) return;
+		if (shouldFocus) nav.goTo(() => fallback);
+		else setTabIndex(fallback, "0");
+	}
+	normalizeAllItems();
+	const observer = new MutationObserver((mutations) => {
+		let removedActiveItem = null;
+		let removalAnchor = null;
+		let newSelectedItem = null;
+		const disabledTargets = [];
+		const insertedItems = [];
+		for (const mutation of mutations) {
+			if (mutation.type === "childList") {
+				if (!removedActiveItem) for (const removedNode of mutation.removedNodes) {
+					const { value: firstMatch } = querySelectorInclusive(removedNode, itemActiveSelector).next();
+					if (firstMatch) {
+						removedActiveItem = firstMatch;
+						removalAnchor = mutation.nextSibling ?? mutation.previousSibling ?? null;
+						break;
+					}
+				}
+				for (const addedNode of mutation.addedNodes) for (const item of querySelectorInclusive(addedNode, itemSelector)) insertedItems.push(item);
+			}
+			const target = mutation.target;
+			if (mutation.type === "attributes" && target.matches(itemSelector)) {
+				if (mutation.attributeName === itemSelectedAttr && target.getAttribute(itemSelectedAttr) === "true") newSelectedItem = target;
+				else if (itemDisabledSelector && target.matches(itemDisabledSelector)) disabledTargets.push(target);
+			}
+		}
+		if (removedActiveItem) {
+			const shouldMoveFocus = containerFocus.hasFocus;
+			containerFocus.reset();
+			ensureTabStop(shouldMoveFocus, removalAnchor);
+		}
+		if (insertedItems.length > 0) normalizeItems(insertedItems, container.querySelector(itemActiveSelector) !== null);
+		if (disabledTargets.length > 0) {
+			const currentActive = nav.selectors.activeItem;
+			for (const target of disabledTargets) setTabIndex(target, "-1");
+			ensureTabStop(!!(currentActive && disabledTargets.includes(currentActive) && containerFocus.hasFocus));
+		}
+		if (newSelectedItem) {
+			const currentTabStop = container.querySelector(itemActiveSelector);
+			if (currentTabStop && currentTabStop !== newSelectedItem) setTabIndex(currentTabStop, "-1");
+			setTabIndex(newSelectedItem, "0");
+		}
+	});
+	observer.observe(container, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [
+			"aria-disabled",
+			"disabled",
+			itemSelectedAttr
+		]
+	});
+	signal.addEventListener("abort", () => observer.disconnect());
+	container.addEventListener("keydown", (evt) => {
+		if (!nav.selectors.activeItem) {
+			const target = evt.target;
+			if (target.matches(itemSelector) && container.contains(target)) nav.goTo(() => target);
+		}
+		let handled = false;
+		switch (evt.key) {
+			case "ArrowRight":
+				handled = nav.goRight();
+				break;
+			case "ArrowLeft":
+				handled = nav.goLeft();
+				break;
+			case "ArrowDown":
+				handled = nav.goDown();
+				break;
+			case "ArrowUp":
+				handled = nav.goUp();
+				break;
+			case "Home":
+				handled = nav.goTo((s) => s.getFirst());
+				break;
+			case "End":
+				handled = nav.goTo((s) => s.getLast());
+				break;
+			default: break;
+		}
+		if (handled) {
+			evt.preventDefault();
+			evt.stopPropagation();
+		}
+	}, { signal });
+	return nav;
+}
+//#endregion
+export { setupRovingTabIndex };

package/_internal/packages/lumx-core/src/js/utils/focusNavigation/types.d.ts

@@ -0,0 +1,40 @@
+//#region ../lumx-core/src/js/utils/focusNavigation/types.d.ts
+/** Pure, side-effect-free selection layer for focus navigation. */
+interface FocusNavigationSelectors {
+  readonly activeItem: HTMLElement | null;
+  readonly hasNavigableItems: boolean;
+  getFirst(): HTMLElement | null;
+  getLast(): HTMLElement | null;
+  getMatching(predicate: (item: HTMLElement) => boolean): HTMLElement | null;
+}
+/**
+ * Focus navigation controller — the mover layer. Every method commits focus via
+ * {@link FocusNavigationCallbacks}. The pure read layer lives behind {@link selectors}.
+ *
+ * To move focus to the first/last navigable item:
+ * `goTo((s) => s.getFirst())` / `goTo((s) => s.getLast())`.
+ */
+interface FocusNavigationController<Selectors extends FocusNavigationSelectors = FocusNavigationSelectors> {
+  readonly type: 'list' | 'grid';
+  readonly selectors: Selectors;
+  goToOffset(offset: number): boolean;
+  clear(): void;
+  goUp(): boolean;
+  goDown(): boolean;
+  goLeft(): boolean;
+  goRight(): boolean;
+  /**
+   * Navigate via a resolver, deferring when the target is not yet in the DOM.
+   * ```ts
+   * nav.goTo((sel) => sel.getMatching(isSelected) ?? sel.getFirst());
+   * ```
+   */
+  goTo(resolve: (selectors: Selectors) => HTMLElement | null): boolean;
+  /**
+   * Replay the pending navigation intent stored by {@link goTo}.
+   * No-op when nothing is pending.
+   */
+  flushPendingNavigation(): void;
+}
+//#endregion
+export { FocusNavigationController };