WRR-1063: Add optional options.preventScroll parameter to focus function to prevent scroll by focus

.travis.yml

@@ -1,7 +1,7 @@
 dist: jammy
 language: node_js
 node_js:
-    - lts/*
+    - 21
 sudo: false
 before_install:
     - sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

packages/spotlight/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 The following is a curated list of changes in the Enact spotlight module, newest changes on the top.
 
+## [unreleased]
+
+### Added
+
+- `spotlight` an optional `options.preventScroll` parameter to `focus` function to prevent scrolling by focus
+
 ## [5.0.0-alpha.2] - 2024-10-08
 
 ### Fixed

packages/spotlight/src/spotlight.js

@@ -197,7 +197,7 @@
 		}
 	}
 
-	function focusElement (elem, containerIds, fromPointer) {
+	function focusElement (elem, containerIds, fromPointer, preventScroll) {
 		if (!elem) {
 			return false;
 		}
@@ -214,7 +214,7 @@
 			return true;
 		}
 
-		const focusOptions = isWithinOverflowContainer(elem, containerIds) ? {preventScroll: true} : null;
+		const focusOptions = preventScroll || isWithinOverflowContainer(elem, containerIds) ? {preventScroll: true} : null;
 
 		let silentFocus = function () {
 			elem.focus(focusOptions);
@@ -750,16 +750,19 @@
 		 * @param {String|Node} [elem] The spotlight ID or selector for either a spottable
 		 *  component or a spotlight container, or spottable node. If not supplied, the default
 		 *  container will be focused.
-		 * @param {Object} [containerOption] The object including `enterTo` and `toOuterContainer`.
-		 *  It works when the first parameter `elem` is either a spotlight container ID or a spotlight container node.
-		 * @param {('last-focused'|'default-element'|'topmost')} [containerOption.enterTo] Specifies preferred
+		 * @param {Object} [options] The object including `enterTo`, `toOuterContainer`, and `preventScroll`.
+		 *  `enterTo` and `toOuterContainer` work when the first parameter `elem` is either
+		 *  a spotlight container ID or a spotlight container node.
+		 * @param {('last-focused'|'default-element'|'topmost')} [options.enterTo] Specifies preferred
 		 *  `enterTo` configuration.
-		 * @param {Boolean} [containerOption.toOuterContainer] If the proper target is not found, search one
+		 * @param {Boolean} [options.toOuterContainer] If the proper target is not found, search one
 		 *  recursively to outer container.
+		 * @param {Boolean} [options.preventScroll] Prevents the focused element from an automatic scrolling
+		 *  into view after focusing the element.
 		 * @returns {Boolean} `true` if focus successful, `false` if not.
 		 * @public
 		 */
-		focus: function (elem, containerOption = {}) {
+		focus: function (elem, options = {}) {
 			let target = elem;
 			let wasContainerId = false;
 			let currentContainerNode = null;
@@ -768,7 +771,7 @@
 				target = getTargetByContainer();
 			} else if (typeof elem === 'string') {
 				if (getContainerConfig(elem)) {
-					target = getTargetByContainer(elem, containerOption.enterTo);
+					target = getTargetByContainer(elem, options.enterTo);
 					wasContainerId = true;
 					currentContainerNode = getContainerNode(elem);
 				} else if (/^[\w\d-]+$/.test(elem)) {
@@ -778,14 +781,14 @@
 					target = getTargetBySelector(elem);
 				}
 			} else if (isContainer(elem)) {
-				target = getTargetByContainer(getContainerId(elem), containerOption.enterTo);
+				target = getTargetByContainer(getContainerId(elem), options.enterTo);
 				currentContainerNode = elem;
 			}
 
 			const nextContainerIds = getContainersForNode(target);
 			const nextContainerId = last(nextContainerIds);
 			if (isNavigable(target, nextContainerId, true)) {
-				const focused = focusElement(target, nextContainerIds);
+				const focused = focusElement(target, nextContainerIds, false, options.preventScroll);
 
 				if (!focused && wasContainerId) {
 					setLastContainer(elem);
@@ -798,11 +801,11 @@
 				setLastContainer(elem);
 			}
 
-			if (containerOption.toOuterContainer && currentContainerNode) {
+			if (options.toOuterContainer && currentContainerNode) {
 				const outerContainer = getContainersForNode(currentContainerNode.parentElement).pop();
 
 				if (outerContainer) {
-					return this.focus(outerContainer, containerOption);
+					return this.focus(outerContainer, options);
 				}
 			}
 

packages/spotlight/src/tests/spotlight-specs.js

@@ -138,6 +138,16 @@ describe('Spotlight', () => {
 				expect(fn).toBeCalled();
 			}
 		));
+
+		test('should pass preventScroll option', testScenario(
+			scenarios.complexTree,
+			(root) => {
+				const fn = mockFocus(root.querySelector('[data-spotlight-id="s1"]'));
+				Spotlight.focus('s1', {preventScroll: true});
+
+				expect(fn).toHaveBeenCalledWith({preventScroll: true});
+			}
+		));
 	});
 
 	describe('#move', () => {

packages/ui/CHANGELOG.md

@@ -1436,7 +1436,6 @@ libraries.
 
 - Renamed `ui/Group` prop `select` to `childSelect` and added prop `select` to support selection types
 
-
 ## [1.0.0-alpha.2] - 2016-10-21
 
 This version includes a lot of refactoring from the previous release. Developers need to switch to the new enact-dev command-line tool.