@sapudex/web-components 2.51.0 → 2.52.0

package/src/SelectBase.ts

@@ -3,16 +3,19 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
 import executeTemplate from "@ui5/webcomponents-base/dist/renderer/executeTemplate.js";
 import type { ChangeInfo, Slot } from "@ui5/webcomponents-base/dist/UI5Element.js";
 import {
-  isEscape, isDown, isUp, isHome, isEnd, isTabNext, isTabPrevious, isLeft, isRight,
+  isEscape, isDown, isUp, isHome, isEnd, isTabNext, isTabPrevious, isLeft, isRight, isEnter, isSpace,
 } from "@ui5/webcomponents-base/dist/Keys.js";
 import { getAllAccessibleNameRefTexts } from "@ui5/webcomponents-base/dist/util/AccessibilityTextsHelper.js";
+import { cleanLabel } from "./utils/listItemLabelUtils.js";
 import type { UDExListItemBase } from "./List.js";
 import type Popover from "@ui5/webcomponents/dist/Popover.js";
 import type UDExList from "./List.js";
 import type UDExSearch from "./Search.js";
 import "@ui5/webcomponents-icons/dist/decline.js";
 import "@ui5/webcomponents-icons/dist/navigation-down-arrow.js";
-import { COUNTRY_SELECT, STARS } from "./generated/i18n/i18n-defaults.js";
+import {
+  COUNTRY_SELECT, STARS, SELECTED, UNSELECTED, INDETERMINATE, DISABLED,
+} from "./generated/i18n/i18n-defaults.js";
 import SearchableListBaseTemplate from "./SearchableListBaseTemplate.js";
 import CountrySelectorTemplate from "./CountrySelectorTemplate.js";
 import type { ResizeObserverCallback } from "@ui5/webcomponents-base/delegate/ResizeHandler.js";
@@ -20,10 +23,11 @@ import ResizeHandler from "@ui5/webcomponents-base/delegate/ResizeHandler.js";
 import UDExSearchableListBase from "./SearchableListBase.js";
 import UDExValueState from "./types/common.js";
 import type { UDExSearchableListBaseEvents } from "./SearchableListBase.js";
-import { getTokensCountText } from "@ui5/webcomponents/dist/Tokenizer.js";
+import Tokenizer, { getTokensCountText } from "@ui5/webcomponents/dist/Tokenizer.js";
 import isLetterKey from "./utils/isLetterKeyPressed.js";
 import translate from "./utils/translate.js";
 import type { AriaAutoComplete, AriaHasPopup } from "@ui5/webcomponents-base/dist/types.js";
+import { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
 
 type UDExSelectBaseEvents = {
   "open": void,
@@ -164,6 +168,26 @@ class UDExSelectBase extends UDExSearchableListBase {
   @property({ type: Boolean, noAttribute: true })
     _requestRender = false;
 
+  /**
+   * True while keyboard list navigation is active (aria-activedescendant set).
+   * Used in CSS to suppress the input focus ring and show the active item ring.
+   *
+   * @private
+   */
+  @property({ type: Boolean })
+    _navigating: boolean = false;
+
+  /**
+   * Text read by screen readers when the active item changes.
+   * Announced via an aria-live="assertive" region in the template.
+   * This works regardless of shadow DOM / popover teleportation because
+   * the live region lives inside SelectBox's own shadow root.
+   *
+   * @private
+   */
+  @property({ type: String, noAttribute: true })
+    _liveRegionText: string = "";
+
   /**
    * Defines the footer content for the component dropdown.
    * Place any content (e.g. an action button) here. Clicking footer content does not close the dropdown —
@@ -190,6 +214,7 @@ class UDExSelectBase extends UDExSearchableListBase {
   _handleResizeBound: ResizeObserverCallback;
   _handleListKeyDownBound: (e: KeyboardEvent) => void;
   _listKeyDownListenerAdded: boolean = false;
+  _activeDescendantItem: UDExListItemBase | null = null;
 
   constructor() {
     super();
@@ -219,6 +244,7 @@ class UDExSelectBase extends UDExSearchableListBase {
   }
 
   onAfterRendering() {
+    super.onAfterRendering();
     this._popover = this.getPopover();
     this._search = this.getSearch();
     this._list = this.getList();
@@ -227,6 +253,10 @@ class UDExSelectBase extends UDExSearchableListBase {
 
     if (this._list) {
       this._list._scrollIntoView = "Nearest";
+      // Set a stable HTML id on the udex-list host so aria-controls can reference it.
+      if (!this._list.id) {
+        this._list.id = `${this._id}-list`;
+      }
     }
 
     if (this._requestRender) {
@@ -243,6 +273,104 @@ class UDExSelectBase extends UDExSearchableListBase {
     this.updatePopoverWidth();
   }
 
+  /**
+   * Given a candidate index, skips over a non-interactive non-collapsible header if needed.
+   * Returns the effective target index.
+   */
+  _skipNonInteractive(items: UDExListItemBase[], raw: number, lastIndex: number, direction: "down" | "up"): number {
+    if (!items[raw]?.nonInteractive || items[raw].collapsible) {
+      return raw;
+    }
+    if (direction === "down") {
+      return raw + 1 > lastIndex ? 0 : raw + 1;
+    }
+    return raw === 0 ? lastIndex : raw - 1;
+  }
+
+  /**
+   * Sets or clears the aria-activedescendant on the combobox input and updates
+   * the aria-live region so JAWS/VoiceOver announce the item name and position.
+   * The live region is the primary announcement mechanism because aria-activedescendant
+   * across a UI5 Popover (which teleports content to document.body) is unreliable —
+   * screen readers cannot follow the ID reference across shadow root boundaries.
+   */
+  _setActiveDescendant(item: UDExListItemBase | null, scroll = true): void {
+    this._activeDescendantItem = item;
+
+    // Query the SelectBox's OWN shadow DOM for all elements bearing the class —
+    // this reaches the rendered udex-list-group-header / udex-list-item elements
+    // regardless of whether they are the current or a previously stale instance.
+    this.shadowRoot?.querySelectorAll<HTMLElement>("._udex-active-descendant")
+      .forEach(el => {
+        el.classList.remove("_udex-active-descendant");
+        el.removeAttribute("_active-descendant");
+      });
+
+    if (!item) {
+      (this._search as HTMLElement).removeAttribute("aria-activedescendant");
+      this._liveRegionText = "";
+      return;
+    }
+
+    item.classList.add("_udex-active-descendant");
+    item.setAttribute("_active-descendant", "");
+    (this._search as HTMLElement).setAttribute("aria-activedescendant", item._id);
+
+    // Update the live region with tree-aware position and state so JAWS/VoiceOver
+    // announce the active item regardless of whether the popover is teleported to document.body.
+    if (this._list) {
+      const label = cleanLabel(item.label ?? "");
+      const supporting = item.supportingText ? cleanLabel(item.supportingText) : "";
+      const stateParts = this._itemStateLabels(item);
+      const posText = this._treePositionText(item);
+      this._liveRegionText = [label, supporting, posText, ...stateParts].filter(Boolean).join(", ");
+    }
+
+    if (scroll && this._list?._scrollIntoView) {
+      // Only scroll if the item is not already fully visible in the dropdown.
+      const popoverContent = this._popover?.shadowRoot?.querySelector<HTMLElement>("[part=content]");
+      if (popoverContent) {
+        const itemRect = item.getBoundingClientRect();
+        const containerRect = popoverContent.getBoundingClientRect();
+        const isVisible = itemRect.top >= containerRect.top && itemRect.bottom <= containerRect.bottom;
+        if (!isVisible) {
+          this._list.scrollToItem(item);
+        }
+      } else {
+        this._list.scrollToItem(item);
+      }
+    }
+  }
+
+  /**
+   * Activates the first navigable item as the aria-activedescendant without moving DOM focus.
+   */
+  _activateFirstItem(): void {
+    const items = this._list?.getKeyboardNavigationItems();
+    if (!items?.length) { return; }
+    const firstIndex = (items[0]?.nonInteractive && !items[0]?.collapsible) ? 1 : 0;
+    this._list.setTabIndexByIndex(items, firstIndex);
+    this._setActiveDescendant(items[firstIndex], false);
+  }
+
+  /**
+   * Navigates to the item at the given index, updating aria-activedescendant and _selectedOption.
+   */
+  _navigateToIndex(items: UDExListItemBase[], nextIndex: number): void {
+    const currentIndex = this._activeDescendantItem
+      ? this._list.getCurrentIndex(items, this._activeDescendantItem)
+      : -1;
+    if (currentIndex >= 0) {
+      this._list.unsetTabIndexByIndex(items, currentIndex);
+    }
+    this._list.setTabIndexByIndex(items, nextIndex);
+    this._selectedOption = items[nextIndex].label;
+    if (this.showImageFlags) {
+      this.handleImagePosition(items, nextIndex);
+    }
+    this._setActiveDescendant(items[nextIndex]);
+  }
+
   handleKeyDownDropdown(e: KeyboardEvent) {
     const items = this._list?.getKeyboardNavigationItems();
 
@@ -301,78 +429,65 @@ class UDExSelectBase extends UDExSearchableListBase {
       return;
     }
 
-    if (isRight(e)) {
+    if (isRight(e) || isLeft(e)) {
       e.preventDefault();
-      if (this._handleGroupHeaderCollapse(e.target as HTMLElement, false)) {
+      // Resolve the collapsible group header from the active descendant (not e.target,
+      // since DOM focus stays on the input and e.target is the input element).
+      const activeHeader = this._activeDescendantItem
+        ? this._resolveCollapsibleGroupHeader(this._activeDescendantItem as unknown as HTMLElement)
+        : null;
+      if (activeHeader && this._handleGroupHeaderCollapse(activeHeader as unknown as HTMLElement, isLeft(e))) {
         return;
       }
-      this._handleArrowRightInRow(e.target as HTMLElement);
-      return;
-    }
-
-    if (isLeft(e)) {
-      e.preventDefault();
-      if (this._handleGroupHeaderCollapse(e.target as HTMLElement, true)) {
-        return;
+      // Fall through to icon-row navigation when focus is on an icon button
+      if (isRight(e)) {
+        this._handleArrowRightInRow(e.target as HTMLElement);
+      } else {
+        this._handleArrowLeftInRow(e.target as HTMLElement);
       }
-      this._handleArrowLeftInRow(e.target as HTMLElement);
       return;
     }
 
-    const iconSlot = this._getIconButtonSlot(e.target as HTMLElement);
-    const effectiveTarget = iconSlot
-      ? (e.target as HTMLElement).parentElement as UDExListItemBase | undefined
-      : undefined;
-
-    this.handleListNavigationKeys(e, items, effectiveTarget);
-  }
-
-  handleListNavigationKeys(e: KeyboardEvent, items: UDExListItemBase[], effectiveTarget?: UDExListItemBase) {
-    const currentSelectedIndex = this._list?.getCurrentIndex(items, effectiveTarget ?? e.target as UDExListItemBase);
-    const lastItemIndex = items.length - 1;
-
-    if (isDown(e)) {
+    if (isDown(e) || isUp(e)) {
       e.preventDefault();
-      this.handleDownKeyPress(items, currentSelectedIndex, lastItemIndex);
-
-      return;
-    }
-
-    if (isUp(e)) {
-      e.preventDefault();
-      this.handleUpKeyPress(items, currentSelectedIndex, lastItemIndex);
-
+      const lastIndex = items.length - 1;
+      const currentItem = this._activeDescendantItem;
+      const currentIndex = currentItem ? this._list.getCurrentIndex(items, currentItem) : -1;
+
+      let nextIndex: number;
+      if (isDown(e)) {
+        const raw = currentIndex + 1 > lastIndex ? 0 : currentIndex + 1;
+        nextIndex = this._skipNonInteractive(items, raw, lastIndex, "down");
+      } else {
+        const raw = currentIndex - 1 < 0 ? lastIndex : currentIndex - 1;
+        nextIndex = this._skipNonInteractive(items, raw, lastIndex, "up");
+      }
+      this._navigateToIndex(items, nextIndex);
       return;
     }
 
     if (isHome(e)) {
       e.preventDefault();
       this.handleHomeKeyPress(items);
-
       return;
     }
 
     if (isEnd(e)) {
       e.preventDefault();
-      this.handleEndKeyPress(items, lastItemIndex);
+      this.handleEndKeyPress(items, items.length - 1);
     }
+
+    // Icon-button slot: Up/Down while an icon button is focused (handled by capture listener).
+    // _handleListKeyDownCapture fires first via capture; nothing else needed here.
   }
 
   handleEndKeyPress(items: UDExListItemBase[], lastItemIndex: number) {
-    if (this.showImageFlags) {
-      this.handleImagePosition(items, lastItemIndex);
-    }
-
-    this._selectedOption = items[lastItemIndex].label;
+    this._navigateToIndex(items, lastItemIndex);
   }
 
   handleHomeKeyPress(items: UDExListItemBase[]) {
     const firstIndex = (items[0]?.nonInteractive && !items[0]?.collapsible) ? 1 : 0;
-    this._selectedOption = items[firstIndex].label;
-
-    if (this.showImageFlags) {
-      this.handleImagePosition(items, firstIndex);
-    }
+    this._navigateToIndex(items, firstIndex);
   }
 
   handleDownKeyPress(items: UDExListItemBase[], currentSelectedIndex: number, lastItemIndex: number) {
@@ -430,6 +545,7 @@ class UDExSelectBase extends UDExSearchableListBase {
   handleEscKeyPress(e: KeyboardEvent) {
     e.preventDefault();
     e.stopPropagation();
+    this._setActiveDescendant(null);
     this.closeDropdown();
     this._search.focus();
     this._selectedOption = "";
@@ -442,9 +558,35 @@ class UDExSelectBase extends UDExSearchableListBase {
     this.resetSearchState();
 
     if (this.modeSingleSelect) {
+      // SingleSelect closes the dropdown — clear active descendant.
+      this._setActiveDescendant(null);
       this._search.focus();
       this.closeDropdown();
+      return;
+    }
+
+    // MultiSelect: ensure active descendant tracks the interacted item so there
+    // is only one ring. Find the rendered item in the navigation list by matching
+    // data-token-id (the source item's _id set by the template) since e.detail.item
+    // is the source element, not the rendered udex-list-item.
+    const tokenId = this.getDataTokenId(item);
+    const navItems = this._list?.getKeyboardNavigationItems();
+    const renderedItem = navItems?.find(
+      i => (i.getAttribute("data-token-id") ?? i._id) === tokenId,
+    );
+    if (renderedItem && renderedItem !== this._activeDescendantItem) {
+      this._setActiveDescendant(renderedItem);
     }
+
+    // Return DOM focus to the input so the clicked item loses its :focus ring.
+    // Without this, the browser keeps focus on the item (from the click) and a
+    // second ring appears when arrow keys move _activeDescendantItem elsewhere.
+    (this._search as HTMLElement).focus();
+
+    // Re-announce with the updated checked/unchecked state. The rendered item's
+    // `selected` prop is updated on the next render cycle (template re-render),
+    // so we wait for it before re-reading state labels.
+    renderFinished().then(() => this._announceCurrentOrFirst()).catch(() => {});
   }
 
   onKeyDownSearch(e: KeyboardEvent) {
@@ -457,13 +599,37 @@ class UDExSelectBase extends UDExSearchableListBase {
     const isEscAndPopoverOpened = isEscape(e) && popoverOpened;
     const isDownAndPopoverClosed = isDown(e) && !popoverOpened;
     const isDownAndPopoverOpened = isDown(e) && popoverOpened;
+    const isUpAndPopoverOpened = isUp(e) && popoverOpened;
+
+    // Tab while popup is open: move focus to the first footer element if one exists,
+    // otherwise close the dropdown and move past the component.
+    if (popoverOpened && isTabNext(e)) {
+      e.preventDefault();
+      if (this.hasFooter) {
+        this._setActiveDescendant(null);
+        (this._firstFocusableIn(this.footer[0]) ?? this.footer[0])?.focus();
+      } else {
+        this.closeDropdown();
+        this._moveFocusAfterComponent();
+      }
+      return;
+    }
+
+    // Shift+Tab while popup is open: close the dropdown.
+    // DOM focus stays on the search input throughout (our aria-activedescendant model
+    // never moves focus away from the input), so no explicit re-focus is needed.
+    if (popoverOpened && isTabPrevious(e)) {
+      e.preventDefault();
+      this._setActiveDescendant(null);
+      this.closeDropdown();
+      return;
+    }
 
     if (!hasItems) {
       return;
     }
 
     const firstIndex = (items[0]?.nonInteractive && !items[0]?.collapsible) ? 1 : 0;
-    const firstItem = items[firstIndex];
 
     if (isEscAndPopoverOpened) {
       return this.closeDropdown();
@@ -472,21 +638,104 @@ class UDExSelectBase extends UDExSearchableListBase {
     if (isDownAndPopoverClosed) {
       e.preventDefault();
       this.openDropdown();
-      this.focusFirstItem();
-      this._selectedOption = firstItem.label;
+      this._activateFirstItem();
       if (this.showImageFlags) {
-        this.handleImagePosition(items, 0);
+        this.handleImagePosition(items, firstIndex);
       }
       return;
     }
 
     if (isDownAndPopoverOpened) {
       e.preventDefault();
-      if (this.showImageFlags) {
-        this.handleImagePosition(items, 0);
+      if (this._activeDescendantItem) {
+        const lastIndex = items.length - 1;
+        const currentIndex = this._list.getCurrentIndex(items, this._activeDescendantItem);
+        const raw = currentIndex + 1 > lastIndex ? 0 : currentIndex + 1;
+        const nextIndex = this._skipNonInteractive(items, raw, lastIndex, "down");
+        this._navigateToIndex(items, nextIndex);
+      } else {
+        this._activateFirstItem();
+        // Also update _selectedOption so the input reflects the active item.
+        const activeIdx = (items[0]?.nonInteractive && !items[0]?.collapsible) ? 1 : 0;
+        this._selectedOption = items[activeIdx].label;
+        if (this.showImageFlags) {
+          this.handleImagePosition(items, activeIdx);
+        }
       }
-      this._selectedOption = firstItem.label;
-      return this.focusFirstItem();
+      return;
+    }
+
+    if (isUpAndPopoverOpened) {
+      e.preventDefault();
+      if (this._activeDescendantItem) {
+        const lastIndex = items.length - 1;
+        const currentIndex = this._list.getCurrentIndex(items, this._activeDescendantItem);
+        const raw = currentIndex - 1 < 0 ? lastIndex : currentIndex - 1;
+        const nextIndex = this._skipNonInteractive(items, raw, lastIndex, "up");
+        this._navigateToIndex(items, nextIndex);
+      } else {
+        this._navigateToIndex(items, items.length - 1);
+      }
+      return;
+    }
+
+    if (popoverOpened && isHome(e)) {
+      e.preventDefault();
+      const homeIndex = (items[0]?.nonInteractive && !items[0]?.collapsible) ? 1 : 0;
+      this._navigateToIndex(items, homeIndex);
+      return;
+    }
+
+    if (popoverOpened && isEnd(e)) {
+      e.preventDefault();
+      this._navigateToIndex(items, items.length - 1);
+      return;
+    }
+
+    // Enter/Space: select the active descendant item (or toggle for MultiSelect).
+    if (popoverOpened && this._activeDescendantItem && (isEnter(e) || isSpace(e))) {
+      e.preventDefault();
+      const activeItem = this._activeDescendantItem;
+      if (activeItem.isGroup) {
+        // Group header: fire header-press (same event the click handler fires) so
+        // handleHeaderPress → onHeaderPress → handleGroupHeaderSelection runs.
+        activeItem.fireDecoratorEvent("header-press", { item: activeItem });
+      } else {
+        // Leaf item: fire item-press so the list handles selection consistently.
+        // Do NOT toggle .selected directly — handleItemClick (called via onItemPress)
+        // handles the toggle, and double-toggling would be a no-op.
+        activeItem.fireDecoratorEvent("item-press", {
+          selected: activeItem.selected,
+          item: activeItem,
+        });
+      }
+      return;
+    }
+
+    // Left/Right: collapse/expand the active group header when popup is open.
+    if (popoverOpened && (isLeft(e) || isRight(e))) {
+      e.preventDefault();
+      const activeHeader = this._activeDescendantItem
+        ? this._resolveCollapsibleGroupHeader(this._activeDescendantItem as unknown as HTMLElement)
+        : null;
+      if (activeHeader) {
+        this._handleGroupHeaderCollapse(activeHeader as unknown as HTMLElement, isLeft(e));
+        return;
+      }
+      // Fall through to icon-row navigation when the active item has icon slots.
+      if (this._activeDescendantItem) {
+        if (isRight(e)) {
+          this._handleArrowRightInRow(this._activeDescendantItem as unknown as HTMLElement);
+        } else {
+          this._handleArrowLeftInRow(this._activeDescendantItem as unknown as HTMLElement);
+        }
+      }
+      return;
+    }
+
+    // Sync _selectedOption display for the first item (used when popover just opened via click).
+    if (!this._activeDescendantItem && hasItems) {
+      this._selectedOption = items[firstIndex].label;
     }
   }
 
@@ -505,6 +754,15 @@ class UDExSelectBase extends UDExSearchableListBase {
     }
   }
 
+  override onSearch(value: string): void {
+    super.onSearch(value);
+    // Route search result count into the shared live region so SelectBox
+    // only needs one aria-live span (no separate polite span in the template).
+    if (this._accSearchResultInfo) {
+      this._liveRegionText = this._accSearchResultInfo;
+    }
+  }
+
   handleDirection() {
     const directionStyles = window.getComputedStyle(this).getPropertyValue("direction");
     this._direction = directionStyles || "ltr";
@@ -523,12 +781,83 @@ class UDExSelectBase extends UDExSearchableListBase {
   }
 
   handleDropdownOpen() {
-    if (!this.activeItem) {
+    // Scroll to the previously selected/active item if there is one,
+    // otherwise scroll to top. Do NOT pre-activate any item — that is done
+    // by the first ArrowDown so that ArrowDown[1]=item[0], ArrowDown[2]=item[1].
+    if (this.activeItem) {
+      const items = this._list?.getKeyboardNavigationItems();
+      const active = items?.find(i => !i.isGroup && (i as any).selected);
+      if (active && this._list?._scrollIntoView) {
+        this._list.scrollToItem(active);
+      } else {
+        this._dropdownScrollToTop();
+      }
+    } else {
       this._dropdownScrollToTop();
     }
+
+    // Announce the visually focused item (fake focus outline on first item).
+    // Using polite politeness — it waits for the AT to finish announcing
+    // "expanded" before reading the item, so no timeout is needed.
+    // Clear first so the mutation fires even if the text is unchanged from
+    // the previous open, then populate after render completes.
+    this._liveRegionText = "";
+    renderFinished().then(() => this._announceCurrentOrFirst()).catch(() => {});
+
     this.fireEventDropdownOpen();
   }
 
+  /**
+   * Announces the currently active descendant item (if set), or the first
+   * navigable item as a fallback. Used on open and after state changes.
+   */
+  _announceCurrentOrFirst(): void {
+    const items = this._list?.getKeyboardNavigationItems();
+    if (!items?.length) { return; }
+    const item = this._activeDescendantItem ?? items.find(i => !i.nonInteractive || i.collapsible) ?? items[0];
+    if (!item) { return; }
+    const label = cleanLabel(item.label ?? "");
+    const stateParts = this._itemStateLabels(item);
+    const posText = this._treePositionText(item);
+    this._liveRegionText = [label, posText, ...stateParts].filter(Boolean).join(", ");
+  }
+
+  /**
+   * Returns the positional announcement text for an item, tree-aware when the
+   * list has groups. Matches the JAWS reading pattern of FilterMenu:
+   *   group header → "level 0, X of Y"  (Y = total navigable groups)
+   *   group child  → "level 1, X of Y"  (Y = siblings in that group)
+   *   flat item    → "X of Y"           (Y = total items, no level prefix)
+   */
+  _treePositionText(item: UDExListItemBase): string {
+    if (!this.isTreeStructure) {
+      const items = this._list?.getKeyboardNavigationItems() ?? [];
+      const pos = items.indexOf(item);
+      return pos >= 0 ? `${pos + 1} of ${items.length}` : "";
+    }
+
+    if (item.isGroup) {
+      // Position among navigable group headers.
+      const groups = (this._list?.getKeyboardNavigationItems() ?? []).filter(i => i.isGroup);
+      const pos = groups.indexOf(item);
+      return pos >= 0 ? `level 0, ${pos + 1} of ${groups.length}` : "level 0";
+    }
+
+    // Child item — find parent group and count siblings visible in navigation.
+    const parentGroup = item.parentElement as UDExListItemBase | null;
+    if (parentGroup?.isGroup) {
+      const navItems = this._list?.getKeyboardNavigationItems() ?? [];
+      const siblings = navItems.filter(i => !i.isGroup && i.parentElement === parentGroup);
+      const pos = siblings.indexOf(item);
+      return pos >= 0 ? `level 1, ${pos + 1} of ${siblings.length}` : "level 1";
+    }
+
+    // Fallback: flat position.
+    const all = this._list?.getKeyboardNavigationItems() ?? [];
+    const pos = all.indexOf(item);
+    return pos >= 0 ? `${pos + 1} of ${all.length}` : "";
+  }
+
   fireEventDropdownBeforeOClose() {
     this.fireDecoratorEvent("before-close");
   }
@@ -568,12 +897,15 @@ class UDExSelectBase extends UDExSearchableListBase {
     this._popover.opener = this._trigger;
     this._popover.open = true;
     this._open = true;
+    this._navigating = true;
+    this._focused = false;
   }
 
   closeDropdown() {
     if (this._popover.open) {
       this._open = false;
       this._popover.open = false;
+      this._navigating = false;
     }
   }
 
@@ -643,11 +975,13 @@ class UDExSelectBase extends UDExSearchableListBase {
     if (collapse && !header.collapsed) {
       header.collapsed = true;
       this._list.setCollapsedItems(true, header);
+      renderFinished().then(() => this._announceCurrentOrFirst()).catch(() => {});
       return true;
     }
     if (!collapse && header.collapsed) {
       header.collapsed = false;
       this._list.setCollapsedItems(false, header);
+      renderFinished().then(() => this._announceCurrentOrFirst()).catch(() => {});
       return true;
     }
     // Target is a collapsible header but already in the requested state — still consume
@@ -676,7 +1010,12 @@ class UDExSelectBase extends UDExSearchableListBase {
     const iconSlot = this._getIconButtonSlot(target);
     if (!iconSlot) {
       const firstIcon = target.querySelector<HTMLElement>("[slot=\"firstIcon\"]");
-      firstIcon?.focus();
+      if (firstIcon) {
+        // Entering icon row: clear the active descendant ring so the list item
+        // doesn't show two simultaneous outlines alongside the icon's :focus ring.
+        this._setActiveDescendant(null);
+        firstIcon.focus();
+      }
       return;
     }
     if (iconSlot === "firstIcon") {
@@ -697,7 +1036,17 @@ class UDExSelectBase extends UDExSearchableListBase {
       const firstIcon = parentItem.querySelector<HTMLElement>("[slot=\"firstIcon\"]");
       firstIcon?.focus();
     } else if (iconSlot === "firstIcon") {
-      this._list.focusItem(parentItem as UDExListItemBase);
+      // Return to the list item: restore the active descendant ring and return
+      // DOM focus to the input so the icon's :focus ring is cleared.
+      const navItems = this._list?.getKeyboardNavigationItems();
+      const tokenId = this.getDataTokenId(parentItem as UDExListItemBase);
+      const renderedItem = navItems?.find(i => (i.getAttribute("data-token-id") ?? i._id) === tokenId);
+      if (renderedItem) {
+        this._setActiveDescendant(renderedItem);
+      } else {
+        this._list.focusItem(parentItem as UDExListItemBase);
+      }
+      (this._search as HTMLElement).focus();
     }
   }
 
@@ -735,25 +1084,22 @@ class UDExSelectBase extends UDExSearchableListBase {
 
     this._list.unsetTabIndexByIndex(items, currentIndex);
     this._list.setTabIndexByIndex(items, targetIndex);
-    this._list.focusItem(items[targetIndex]);
+    this._setActiveDescendant(items[targetIndex]);
     this._selectedOption = items[targetIndex].label;
   }
 
   _focusLastListItem() {
     const items = this._list?.getKeyboardNavigationItems();
     if (!items || items.length === 0) {
-      this._search.focus();
+      (this._search as HTMLElement).focus();
       return;
     }
     const lastIndex = items.length - 1;
-    const lastItem = items[lastIndex];
     this._list.setTabIndexByIndex(items, lastIndex);
-    this._selectedOption = lastItem.label;
-    if (lastItem.isGroup) {
-      this._list.focusHeader(lastItem);
-    } else {
-      this._list.focusItem(lastItem);
-    }
+    this._selectedOption = items[lastIndex].label;
+    this._setActiveDescendant(items[lastIndex]);
+    // Return DOM focus to the search input (aria-activedescendant model).
+    (this._search as HTMLElement).focus();
   }
 
   _firstFocusableIn(el: Element | undefined): HTMLElement | null {
@@ -786,11 +1132,50 @@ class UDExSelectBase extends UDExSearchableListBase {
     findAndFocus(this);
   }
 
+  /**
+   * Builds the state portion of the live region announcement for a navigation item.
+   * Returns an array of state strings (e.g. ["collapsed", "Checked"]) to be joined
+   * with the label and position. Handles:
+   *   - collapsible group headers: expanded / collapsed
+   *   - MultiSelect: Checked / Unchecked / Indeterminate
+   *   - SingleSelect (tree): Selected / Unselected
+   *   - disabled: Disabled
+   */
+  _itemStateLabels(item: UDExListItemBase): string[] {
+    const parts: string[] = [];
+
+    if (item.collapsible) {
+      // Use plain English — matches what AT announce for aria-expanded.
+      parts.push(item.expanded ? "expanded" : "collapsed");
+    }
+
+    if (item.disabled) {
+      parts.push(translate(UDExSearchableListBase, DISABLED));
+    } else if (item.modeMultiSelect || (item.isGroup && this.modeMultiSelect)) {
+      if (item.indeterminate) {
+        parts.push(translate(UDExSearchableListBase, INDETERMINATE));
+      } else {
+        parts.push(translate(UDExSearchableListBase, item.selected ? SELECTED : UNSELECTED));
+      }
+    } else if (this.isTreeStructure && item.selected) {
+      // SingleSelect tree: only announce "Selected" when the item is actually selected.
+      parts.push(translate(UDExSearchableListBase, SELECTED));
+    }
+
+    return parts;
+  }
+
   get ariaDescribedbyText(): string {
     if (this.modeSingleSelect) {
-      return this._selectedOption;
+      return this._navigating ? "" : this._selectedOption;
     }
     const tags = this.selectedItems.filter(item => !item.isGroup);
+    // Tokenizer.i18nBundle may not be loaded yet on direct page load.
+    // Return empty string until the bundle is available; the component re-renders
+    // once i18n is ready and will pick up the correct text.
+    if (!Tokenizer.i18nBundle) {
+      return "";
+    }
     return getTokensCountText(tags.length);
   }
 
@@ -840,6 +1225,18 @@ class UDExSelectBase extends UDExSearchableListBase {
     return this._listBoxRole;
   }
 
+  get listAriaControlsId(): string {
+    return this._list?.id || this.popoverId;
+  }
+
+  override get _activeDescendantMode(): boolean {
+    return true;
+  }
+
+  override get isTreeStructure(): boolean {
+    return this._filteredItems.some(e => e.isGroup);
+  }
+
   get hideDropdownSearch(): boolean {
     return true;
   }