fix(ui5-toolbar): harden keyboard delegation for nested controls

Improve WCAG toolbar keyboard behavior while preventing regressions
for nested and overflowed controls.

- add key-level ownership hook shouldHandleOwnKeyboardNavigation(event)
- use key-aware delegation in toolbar and overflow key handlers
- preserve native input/textarea/contenteditable navigation (Arrow/Home/End)
- narrow overflow preventDefault to toolbar-consumed navigation only
- refactor navigation item collection for standard and overflow paths
- update keyboard handling documentation in Toolbar
- add cypress regressions for input Home/End in toolbar and overflow
- fix toolbar cypress type check for itemsToOverflow membership assertion

Author: plamenivanov91

packages/main/cypress/specs/Toolbar.cy.tsx

@@ -460,6 +460,89 @@ describe("Toolbar general interaction", () => {
 		});
 	});
 
+	it("Should preserve Home/End behavior for text inputs inside toolbar-item", () => {
+		cy.mount(
+			<Toolbar>
+				<ToolbarButton text="First"></ToolbarButton>
+				<ToolbarItem>
+					<input data-testid="editor" defaultValue="abcdef" />
+				</ToolbarItem>
+				<ToolbarButton text="Last"></ToolbarButton>
+			</Toolbar>
+		);
+
+		cy.get("[data-testid='editor']")
+			.realClick()
+			.then($input => {
+				const input = $input[0] as HTMLInputElement;
+				input.setSelectionRange(3, 3);
+			});
+
+		cy.realPress("Home");
+		cy.get("[data-testid='editor']")
+			.should("be.focused")
+			.then($input => {
+				expect(($input[0] as HTMLInputElement).selectionStart).to.equal(0);
+			});
+
+		cy.get("[data-testid='editor']")
+			.then($input => {
+				const input = $input[0] as HTMLInputElement;
+				input.setSelectionRange(2, 2);
+			});
+
+		cy.realPress("End");
+		cy.get("[data-testid='editor']")
+			.should("be.focused")
+			.then($input => {
+				expect(($input[0] as HTMLInputElement).selectionStart).to.equal(6);
+			});
+	});
+
+	it("Should not suppress input arrow/home/end behavior inside overflow popover", () => {
+		cy.viewport(220, 600);
+
+		cy.mount(
+			<Toolbar>
+				<ToolbarButton text="First"></ToolbarButton>
+				<ToolbarItem overflow-priority="AlwaysOverflow">
+					<input data-testid="overflow-editor" defaultValue="abcdef" />
+				</ToolbarItem>
+				<ToolbarButton text="Last"></ToolbarButton>
+			</Toolbar>
+		);
+
+		cy.get("[ui5-toolbar]")
+			.shadow()
+			.find(".ui5-tb-overflow-btn")
+			.realClick();
+
+		cy.get("[ui5-toolbar]")
+			.shadow()
+			.find(".ui5-overflow-popover")
+			.should("have.prop", "open", true);
+
+		cy.get("[data-testid='overflow-editor']")
+			.realClick()
+			.then($input => {
+				const input = $input[0] as HTMLInputElement;
+				input.setSelectionRange(2, 2);
+			});
+
+		cy.realPress("ArrowLeft");
+		cy.get("[data-testid='overflow-editor']")
+			.should("be.focused")
+			.then($input => {
+				expect(($input[0] as HTMLInputElement).selectionStart).to.equal(1);
+			});
+
+		cy.realPress("Home");
+		cy.get("[data-testid='overflow-editor']")
+			.then($input => {
+				expect(($input[0] as HTMLInputElement).selectionStart).to.equal(0);
+			});
+	});
+
 	it("Should move button with alwaysOverflow priority to overflow popover", () => {
 
 		cy.mount(
@@ -987,7 +1070,7 @@ describe("ToolbarButton", () => {
 			const toolbar = $toolbar[0] as Toolbar;
 			const addButton = document.getElementById("add-btn") as ToolbarButton;
 
-			expect(toolbar.itemsToOverflow.includes(addButton)).to.be.true;
+			expect(toolbar.itemsToOverflow.some(item => item._id === addButton._id)).to.be.true;
 
 			const initialOverflowCount = toolbar.itemsToOverflow.length;
 			const initialItemsWidth = toolbar.itemsWidth;

packages/main/src/Toolbar.ts

@@ -72,7 +72,9 @@ function parsePxValue(styleSet: CSSStyleDeclaration, propertyName: string): numb
  * The `ui5-toolbar` provides advanced keyboard handling.
  *
  * - The control is not interactive, but can contain of interactive elements
- * - [Tab] - iterates through elements
+ * - [Left]/[Right]/[Up]/[Down] - navigate among toolbar items
+ * - [Home]/[End] - move to first/last toolbar item
+ * - [Tab] / [Shift] + [Tab] - move through toolbar items and exit at edges
  *
  * ### ES6 Module Import
  * `import "@ui5/webcomponents/dist/Toolbar.js";`
@@ -594,9 +596,24 @@ class Toolbar extends UI5Element {
 	}
 
 	_getNavigationItems(): Array<ToolbarNavigationItem> {
+		const itemFocusRefs = this._getNavigationItemsFromItems(this.standardItems);
+
+		if (!this.hideOverflowButton && this.overflowButtonDOM) {
+			const overflowButtonFocusRef = this.overflowButtonDOM.getFocusDomRef() as HTMLElement;
+			if (overflowButtonFocusRef && this._isVisible(overflowButtonFocusRef)) {
+				itemFocusRefs.push({
+					focusRef: overflowButtonFocusRef,
+				});
+			}
+		}
+
+		return itemFocusRefs;
+	}
+
+	_getNavigationItemsFromItems(items: Array<ToolbarItemBase>): Array<ToolbarNavigationItem> {
 		const itemFocusRefs: Array<ToolbarNavigationItem> = [];
 
-		this.standardItems
+		items
 			.filter(item => {
 				if (!item.isInteractive || item.hidden || item.isOverflowed) {
 					return false;
@@ -615,15 +632,6 @@ class Toolbar extends UI5Element {
 				});
 			});
 
-		if (!this.hideOverflowButton && this.overflowButtonDOM) {
-			const overflowButtonFocusRef = this.overflowButtonDOM.getFocusDomRef() as HTMLElement;
-			if (overflowButtonFocusRef && this._isVisible(overflowButtonFocusRef)) {
-				itemFocusRefs.push({
-					focusRef: overflowButtonFocusRef,
-				});
-			}
-		}
-
 		return itemFocusRefs;
 	}
 
@@ -644,12 +652,16 @@ class Toolbar extends UI5Element {
 			&& style.visibility !== "hidden";
 	}
 
-	_shouldItemHandleOwnNavigation(item?: ToolbarItemBase | null): boolean {
-		return !!item?.handlesOwnKeyboardNavigation;
+	_shouldItemHandleOwnNavigation(item: ToolbarItemBase | undefined, e: KeyboardEvent): boolean {
+		return !!item?.shouldHandleOwnKeyboardNavigation(e);
 	}
 
 	_shouldChildHandleNavigation(element: HTMLElement, e: KeyboardEvent): boolean {
-		// If element is an input or textarea, check cursor position
+		if (element.isContentEditable) {
+			return isLeft(e) || isRight(e) || isHome(e) || isEnd(e) || isUp(e) || isDown(e);
+		}
+
+		// If element is an input or textarea, preserve native text/caret behavior.
 		if (element.tagName === "INPUT" || element.tagName === "TEXTAREA") {
 			const input = element as HTMLInputElement | HTMLTextAreaElement;
 			const cursorPos = input.selectionStart || 0;
@@ -664,6 +676,18 @@ class Toolbar extends UI5Element {
 			if (isRight(e) && cursorPos < textLength) {
 				return true;
 			}
+
+			if (isHome(e) && cursorPos > 0) {
+				return true;
+			}
+
+			if (isEnd(e) && cursorPos < textLength) {
+				return true;
+			}
+
+			if (element.tagName === "TEXTAREA" && (isUp(e) || isDown(e))) {
+				return true;
+			}
 		}
 
 		return false;
@@ -765,10 +789,33 @@ class Toolbar extends UI5Element {
 	}
 
 	_onoverflowkeydown(e: KeyboardEvent) {
-		// Prevent arrow keys from scrolling the page while focus is inside the overflow popover
-		if (isLeft(e) || isRight(e) || isUp(e) || isDown(e) || isHome(e) || isEnd(e)) {
-			e.preventDefault();
+		const isNavigationKey = isLeft(e) || isRight(e) || isUp(e) || isDown(e) || isHome(e) || isEnd(e);
+		if (!isNavigationKey) {
+			return;
+		}
+
+		const activeElement = getActiveElement();
+		if (!activeElement) {
+			return;
 		}
+
+		const navigationItems = this._getNavigationItemsFromItems(this.overflowItems);
+		const currentIndex = this._getCurrentItemIndex(navigationItems, activeElement as HTMLElement);
+		if (currentIndex === -1) {
+			return;
+		}
+
+		const currentNavigationItem = navigationItems[currentIndex];
+		if (this._shouldItemHandleOwnNavigation(currentNavigationItem?.item, e)) {
+			return;
+		}
+
+		if (this._shouldChildHandleNavigation(activeElement as HTMLElement, e)) {
+			return;
+		}
+
+		// Prevent page scrolling only when toolbar should consume the key.
+		e.preventDefault();
 	}
 
 	_onkeydown(e: KeyboardEvent) {
@@ -795,9 +842,7 @@ class Toolbar extends UI5Element {
 		}
 
 		const currentNavigationItem = navigationItems[currentIndex];
-		if (isNavigationKey
-			&& this._shouldItemHandleOwnNavigation(currentNavigationItem?.item)
-			&& (isUp(e) || isDown(e) || isHome(e) || isEnd(e))) {
+		if (isNavigationKey && this._shouldItemHandleOwnNavigation(currentNavigationItem?.item, e)) {
 			return;
 		}
 

packages/main/src/ToolbarItemBase.ts

@@ -60,6 +60,21 @@ class ToolbarItemBase extends UI5Element {
 	@property({ type: Boolean })
 	handlesOwnKeyboardNavigation = false;
 
+	/**
+	 * Defines whether the toolbar item handles keyboard navigation for a given key.
+	 *
+	 * Override this method in complex toolbar items that need to preserve
+	 * specific key handling.
+	 * @public
+	 * @since 2.22.0
+	 */
+	shouldHandleOwnKeyboardNavigation(e: KeyboardEvent): boolean {
+		if (e.defaultPrevented) {
+			return this.handlesOwnKeyboardNavigation;
+		}
+		return this.handlesOwnKeyboardNavigation;
+	}
+
 	_isOverflowed: boolean = false;
 
 	get isOverflowed(): boolean {

packages/main/src/ToolbarSelect.ts

@@ -74,6 +74,13 @@ class ToolbarSelect extends ToolbarItemBase {
 
 	handlesOwnKeyboardNavigation = true;
 
+	shouldHandleOwnKeyboardNavigation(e: KeyboardEvent): boolean {
+		return e.key === "ArrowUp"
+			|| e.key === "ArrowDown"
+			|| e.key === "Home"
+			|| e.key === "End";
+	}
+
 	/**
 	 * Defines the width of the select.
 	 *