fix doclets

Author: dan-ichim-lgp

packages/spotlight/src/container.js

@@ -311,6 +311,61 @@ const getOwnedNodes = (node, selector) => {
 	return [];
 };
 
+/**
+ * Returns the nearest `[aria-owns]` owner whose owned subtree contains `containerNode`.
+ *
+ * @param   {Node}    containerNode  Popup container node or descendant
+ * @returns {Node|null}              Owner element, or null
+ * @memberof spotlight/container
+ * @private
+ */
+const getPopupOwnerElement = (containerNode) => {
+	if (!containerNode) {
+		return null;
+	}
+
+	const owners = document.querySelectorAll('[aria-owns]');
+	for (const owner of owners) {
+		if (getOwnedNodes(owner, '*').some(n => n.contains(containerNode))) {
+			return owner;
+		}
+	}
+
+	return null;
+};
+
+/**
+ * Returns IDs of `self-only` spotlight containers reachable through the `aria-owns` of
+ * `ownerNode`, excluding `excludeContainerId`.
+ *
+ * @param   {Node}      ownerNode            Owner element carrying `aria-owns`
+ * @param   {String}    excludeContainerId   Container ID to skip
+ * @returns {String[]}                       Owned self-only container IDs
+ * @memberof spotlight/container
+ * @private
+ */
+const getOwnedSelfOnlyContainerIds = (ownerNode, excludeContainerId) => {
+	const ownedContainerSelector = '[data-spotlight-container][data-spotlight-id]';
+	const ids = [];
+
+	for (const ownedNode of getOwnedNodes(ownerNode, '*')) {
+		const containerNodes = [
+			...(ownedNode.matches?.(ownedContainerSelector) ? [ownedNode] : []),
+			...ownedNode.querySelectorAll(ownedContainerSelector)
+		];
+		for (const containerNode of containerNodes) {
+			const id = getContainerId(containerNode);
+			if (!id || id === excludeContainerId) continue;
+			const cfg = getContainerConfig(id);
+			if (cfg?.restrict === 'self-only') {
+				ids.push(id);
+			}
+		}
+	}
+
+	return ids;
+};
+
 /**
  * Determines all spottable elements and containers that are directly contained by the container
  * identified by `containerId` and no other subcontainers.
@@ -1146,6 +1201,8 @@ export {
 	addContainer,
 	containerAttribute,
 	getOwnedNodes,
+	getOwnedSelfOnlyContainerIds,
+	getPopupOwnerElement,
 	configureDefaults,
 	configureContainer,
 	getContainerFocusTarget,

packages/spotlight/src/spotlight.js

@@ -41,7 +41,8 @@ import {
 	getContainerNode,
 	getContainersForNode,
 	getLastContainer,
-	getOwnedNodes,
+	getOwnedSelfOnlyContainerIds,
+	getPopupOwnerElement,
 	getSpottableDescendants,
 	isContainer,
 	isContainer5WayHoldable,
@@ -98,19 +99,12 @@ const isRight = is('right');
 const isTab = is('tab');
 const isUp = is('up');
 
-// Two elements whose vertical centers are within this many pixels are treated as being on the same
-// visual row, so horizontal position decides Tab order between them. 24 px covers typical
-// line-height variance (e.g. 20 px text + 4 px leading) while still separating distinct rows.
+// Vertical centers within this distance share a Tab row; horizontal position breaks ties.
 const TAB_ROW_THRESHOLD = 24;
 
-// Per-keypress cache for getLinearTargetsInContainer. Keyed by containerId; populated lazily
-// during one synchronous Tab onKeyDown call and cleared before the next. The DOM cannot change
-// between two synchronous calls within the same event handler, so no further invalidation logic
-// is needed.
+// Per-keypress cache for getLinearTargetsInContainer, scoped to one handleTab call.
 let _linearTargetsCache = null;
 
-// Populated by the Spotlight IIFE; exported for unit tests only.
-// Not part of the public Spotlight API — import from this module path directly in tests.
 let _tabNavTestHooks = {};
 
 /**
@@ -537,65 +531,13 @@ const Spotlight = (function () {
 		return false;
 	}
 
-	function getPopupOwnerElement (containerNode) {
-		if (!containerNode) {
-			return null;
-		}
-
-		const owners = document.querySelectorAll('[aria-owns]');
-		for (const owner of owners) {
-			if (getOwnedNodes(owner, '*').some(n => n.contains(containerNode))) {
-				return owner;
-			}
-		}
-
-		return null;
-	}
-
-	/*
-	 * Returns the IDs of all `self-only` spotlight containers reachable through the `aria-owns`
-	 * of `ownerNode`, excluding `excludeContainerId`. Handles both the common case where
-	 * `aria-owns` points to a float-layer wrapper div (so containers are found via querySelector)
-	 * and the direct case where `aria-owns` points to the container node itself.
-	 */
-	function getOwnedSelfOnlyContainerIds (ownerNode, excludeContainerId) {
-		const containerSelector = '[data-spotlight-container][data-spotlight-id]';
-		const ids = [];
-
-		for (const ownedNode of getOwnedNodes(ownerNode, '*')) {
-			const containerNodes = [
-				...(ownedNode.matches?.(containerSelector) ? [ownedNode] : []),
-				...ownedNode.querySelectorAll(containerSelector)
-			];
-			for (const containerNode of containerNodes) {
-				const id = getContainerId(containerNode);
-				if (!id || id === excludeContainerId) continue;
-				const cfg = getContainerConfig(id);
-				if (cfg?.restrict === 'self-only') {
-					ids.push(id);
-				}
-			}
-		}
-
-		return ids;
-	}
-
-	// Returns the nearest ancestor (including self) that carries `aria-owns`, or null when the
-	// node is missing, reaches the body, or has no such ancestor. Used to identify popup owners.
-	function getAriaOwnerNode (target) {
-		const ownerNode = target?.closest('[aria-owns]');
-		return ownerNode && ownerNode !== document.body ? ownerNode : null;
-	}
-
 	function resolveTargetToOpenPopupItem (target, currentPopupContainerId, isForward) {
-		const ownerNode = getAriaOwnerNode(target);
-		if (!ownerNode) {
+		const ownerNode = target?.closest?.('[aria-owns]');
+		if (!ownerNode || ownerNode === document.body) {
 			return target;
 		}
 
 		for (const popupContainerId of getOwnedSelfOnlyContainerIds(ownerNode, currentPopupContainerId)) {
-			// Preserve linear order when entering another open dropdown: Tab forward starts at
-			// first option, Shift+Tab starts at last option.
 			const popupTargets = getLinearTargetsInContainer(popupContainerId);
 			const popupTargetEntry = isForward ? popupTargets[0] : popupTargets[popupTargets.length - 1];
 			const popupTarget = popupTargetEntry?.target || getTargetByContainer(popupContainerId);
@@ -639,10 +581,7 @@ const Spotlight = (function () {
 				comesBeforeInTabOrder(ax, ay, cx, cy, isRtl) :
 				comesBeforeInTabOrder(cx, cy, ax, ay, isRtl);
 			if (inOrder) {
-				// Return the first in-order target regardless of whether it is a popup owner.
-				// resolveTargetToOpenPopupItem will redirect into an open popup when appropriate.
-				// Deferring popup owners as a fallback causes plain controls later in visual
-				// order to win instead, which breaks the expected a→b→c traversal chain.
+				// Do not defer popup owners; resolveTargetToOpenPopupItem redirects into open popups.
 				return target;
 			}
 		}
@@ -666,8 +605,6 @@ const Spotlight = (function () {
 		const isRtl = isRtlDocument();
 		const rootTargets = getLinearTargetsInContainer(rootContainerId);
 
-		// For forward Tab, prefer continuity from the actual focused option so the next nearby
-		// control in visual order wins after the popup boundary.
 		if (isForward) {
 			const fallbackTarget = findLinearTabExitTargetInTargets(
 				rootTargets,
@@ -681,14 +618,9 @@ const Spotlight = (function () {
 			}
 		}
 
-		// Anchor exit traversal to the popup owner first so Tab completes the opened dropdown and
-		// then continues through surrounding nearby controls in the base layout order.
 		if (popupOwner) {
 			const ownerRect = getRect(popupOwner);
-			// Use top+1 rather than the vertical center so the anchor sits at the leading edge of
-			// the owner's bounding box. This keeps controls that are visually level with the top
-			// of the trigger button in the same TAB_ROW_THRESHOLD band, preventing them from
-			// being incorrectly classified as a separate row when the owner button is tall.
+			// top+1 keeps row-level neighbors in the same TAB_ROW_THRESHOLD band as a tall owner button.
 			const ownerTarget = findLinearTabExitTargetInTargets(
 				rootTargets,
 				ownerRect.center.x,
@@ -701,7 +633,6 @@ const Spotlight = (function () {
 			}
 		}
 
-		// Reverse Shift+Tab fallback keeps previous behavior when owner-based handoff has no match.
 		if (!isForward) {
 			const fallbackTarget = findLinearTabExitTargetInTargets(
 				rootTargets,
@@ -717,6 +648,20 @@ const Spotlight = (function () {
 		return null;
 	}
 
+	function getLinearTargetContainerId (target) {
+		// Prefer DOM ancestry over getContainersForNode so aria-owns owners stay in root Tab order.
+		const containerNode = target?.closest?.('[data-spotlight-container][data-spotlight-id]');
+		if (containerNode) {
+			const domContainerId = getContainerId(containerNode);
+			if (domContainerId) {
+				return domContainerId;
+			}
+		}
+
+		const containerIds = getContainersForNode(target);
+		return last(containerIds);
+	}
+
 	function getLinearTargetsInContainer (containerId) {
 		if (_linearTargetsCache?.has(containerId)) {
 			return _linearTargetsCache.get(containerId);
@@ -725,20 +670,6 @@ const Spotlight = (function () {
 		const isRtl = isRtlDocument();
 		const visitedContainers = new Set();
 		const visitedTargets = new Set();
-		const getLinearTargetContainerId = (target) => {
-			// Resolve by DOM ancestry first so popup owners linked through aria-owns are treated as
-			// part of their visual/root context rather than being pulled into an owned self-only popup.
-			const containerNode = target?.closest?.('[data-spotlight-container][data-spotlight-id]');
-			if (containerNode) {
-				const domContainerId = getContainerId(containerNode);
-				if (domContainerId) {
-					return domContainerId;
-				}
-			}
-
-			const containerIds = getContainersForNode(target);
-			return last(containerIds);
-		};
 
 		const gatherSpottableLeaves = (id) => {
 			if (!id || visitedContainers.has(id)) {
@@ -785,7 +716,6 @@ const Spotlight = (function () {
 	function spotLinear (isForward) {
 		let currentFocusedElement = getCurrent();
 
-		// If there is no currently focused spottable target, bootstrap focus first.
 		if (!currentFocusedElement) {
 			if (!restoreFocus()) {
 				return false;
@@ -796,17 +726,6 @@ const Spotlight = (function () {
 			}
 		}
 
-		const currentContainerIds = getContainersForNode(currentFocusedElement);
-		if (!currentContainerIds.length) {
-			if (!restoreFocus()) {
-				return false;
-			}
-			currentFocusedElement = getCurrent();
-			if (!currentFocusedElement) {
-				return false;
-			}
-		}
-
 		const searchContainerId = getLinearTabSearchContainerId(currentFocusedElement);
 		const linearTargets = getLinearTargetsInContainer(searchContainerId);
 		if (!linearTargets.length) {
@@ -859,21 +778,8 @@ const Spotlight = (function () {
 	}
 
 	/*
-	 * Shared Tab/Shift+Tab handler: resets pointer mode, runs the linear traversal with a
-	 * fresh per-keypress cache, and calls preventDefault when focus actually moved.
-	 * Returns true when spotLinear successfully moved focus.
-	 */
-	/*
-	 * Unified Tab/Shift+Tab handler.  All Tab-specific dispatch that previously lived inline in
-	 * onKeyDown is consolidated here so the 5-way path stays uncluttered.
-	 *
-	 * When shouldPreventNavigation() is true (paused or no containers), notifyKeyDown is called
-	 * without the pointer callback and navigation still runs.  preventDefault is called when focus
-	 * moved OR when Spotlight is actively paused (modal open) to prevent the browser from
-	 * escaping the overlay even when no Spotlight target was found.
-	 *
-	 * When the pointer moved during this key press, notifyKeyDown already resets pointer mode so
-	 * navigation is skipped cleanly without an extra setPointerMode call.
+	 * Tab/Shift+Tab handler. Runs spotLinear with a per-keypress target cache and calls
+	 * preventDefault when focus moved or when paused (to keep Tab inside a modal overlay).
 	 */
 	function handleTab (evt) {
 		const keyCode = evt.keyCode;
@@ -1429,23 +1335,16 @@ const Spotlight = (function () {
 
 	};
 
-	// Expose internals for unit tests without polluting the public Spotlight API.
 	_tabNavTestHooks = {
 		findLinearTabExitTarget,
 		getLinearTabSearchContainerId,
 		comesBeforeInTabOrder,
-		getPopupOwnerElement,
 		resolveTargetToOpenPopupItem,
 		isTargetInSelfOnlyContainer,
 		findLinearTabExitTargetInTargets,
+		getLinearTargetContainerId,
 		getLinearTargetsInContainer,
-		spotLinear,
-		onAcceleratedKeyDown,
-		onBlur,
-		onFocus,
-		handleWebOSMouseEvent,
-		handleKeyboardStateChangeEvent,
-		onKeyUp
+		spotLinear
 	};
 
 	return exports;