@sapudex/web-components 2.51.0 → 2.52.0

package/dist/SelectBase.js

@@ -7,19 +7,21 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot-strict.js";
 import executeTemplate from "@ui5/webcomponents-base/dist/renderer/executeTemplate.js";
-import { isEscape, isDown, isUp, isHome, isEnd, isTabNext, isTabPrevious, isLeft, isRight, } from "@ui5/webcomponents-base/dist/Keys.js";
+import { 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 "@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 ResizeHandler from "@ui5/webcomponents-base/delegate/ResizeHandler.js";
 import UDExSearchableListBase from "./SearchableListBase.js";
 import UDExValueState from "./types/common.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 { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
 /**
  * @class
  *
@@ -52,6 +54,22 @@ class UDExSelectBase extends UDExSearchableListBase {
          * @private
          */
         this._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
+         */
+        this._navigating = 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
+         */
+        this._liveRegionText = "";
         this._paneWidthVariableName = "--udex-dropdown-pane-width";
         this._labelBaseClass = "udex-text-field__label";
         this._dropdownClass = "udex-select-box__dropdown";
@@ -62,6 +80,7 @@ class UDExSelectBase extends UDExSearchableListBase {
         this._inputValue = "";
         this._lastSelectedItemId = "";
         this._listKeyDownListenerAdded = false;
+        this._activeDescendantItem = null;
         this._handleResizeBound = this._handleResize.bind(this);
         this._handleListKeyDownBound = this._handleListKeyDownCapture.bind(this);
     }
@@ -84,6 +103,7 @@ class UDExSelectBase extends UDExSearchableListBase {
         }
     }
     onAfterRendering() {
+        super.onAfterRendering();
         this._popover = this.getPopover();
         this._search = this.getSearch();
         this._list = this.getList();
@@ -91,6 +111,10 @@ class UDExSelectBase extends UDExSearchableListBase {
         this.handleDirection();
         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) {
             this._requestRender = false;
@@ -103,6 +127,98 @@ class UDExSelectBase extends UDExSearchableListBase {
     _handleResize() {
         this.updatePopoverWidth();
     }
+    /**
+     * Given a candidate index, skips over a non-interactive non-collapsible header if needed.
+     * Returns the effective target index.
+     */
+    _skipNonInteractive(items, raw, lastIndex, direction) {
+        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, scroll = true) {
+        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("._udex-active-descendant")
+            .forEach(el => {
+            el.classList.remove("_udex-active-descendant");
+            el.removeAttribute("_active-descendant");
+        });
+        if (!item) {
+            this._search.removeAttribute("aria-activedescendant");
+            this._liveRegionText = "";
+            return;
+        }
+        item.classList.add("_udex-active-descendant");
+        item.setAttribute("_active-descendant", "");
+        this._search.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("[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() {
+        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, nextIndex) {
+        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) {
         const items = this._list?.getKeyboardNavigationItems();
         if (isLetterKey(e.key)) {
@@ -153,39 +269,40 @@ class UDExSelectBase extends UDExSearchableListBase {
         if (!items) {
             return;
         }
-        if (isRight(e)) {
+        if (isRight(e) || isLeft(e)) {
             e.preventDefault();
-            if (this._handleGroupHeaderCollapse(e.target, 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)
+                : null;
+            if (activeHeader && this._handleGroupHeaderCollapse(activeHeader, isLeft(e))) {
                 return;
             }
-            this._handleArrowRightInRow(e.target);
-            return;
-        }
-        if (isLeft(e)) {
-            e.preventDefault();
-            if (this._handleGroupHeaderCollapse(e.target, true)) {
-                return;
+            // Fall through to icon-row navigation when focus is on an icon button
+            if (isRight(e)) {
+                this._handleArrowRightInRow(e.target);
+            }
+            else {
+                this._handleArrowLeftInRow(e.target);
             }
-            this._handleArrowLeftInRow(e.target);
-            return;
-        }
-        const iconSlot = this._getIconButtonSlot(e.target);
-        const effectiveTarget = iconSlot
-            ? e.target.parentElement
-            : undefined;
-        this.handleListNavigationKeys(e, items, effectiveTarget);
-    }
-    handleListNavigationKeys(e, items, effectiveTarget) {
-        const currentSelectedIndex = this._list?.getCurrentIndex(items, effectiveTarget ?? e.target);
-        const lastItemIndex = items.length - 1;
-        if (isDown(e)) {
-            e.preventDefault();
-            this.handleDownKeyPress(items, currentSelectedIndex, lastItemIndex);
             return;
         }
-        if (isUp(e)) {
+        if (isDown(e) || 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;
+            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)) {
@@ -195,21 +312,17 @@ class UDExSelectBase extends UDExSearchableListBase {
         }
         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, lastItemIndex) {
-        if (this.showImageFlags) {
-            this.handleImagePosition(items, lastItemIndex);
-        }
-        this._selectedOption = items[lastItemIndex].label;
+        this._navigateToIndex(items, lastItemIndex);
     }
     handleHomeKeyPress(items) {
         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, currentSelectedIndex, lastItemIndex) {
         const nextIndex = currentSelectedIndex + 1;
@@ -257,6 +370,7 @@ class UDExSelectBase extends UDExSearchableListBase {
     handleEscKeyPress(e) {
         e.preventDefault();
         e.stopPropagation();
+        this._setActiveDescendant(null);
         this.closeDropdown();
         this._search.focus();
         this._selectedOption = "";
@@ -267,9 +381,30 @@ class UDExSelectBase extends UDExSearchableListBase {
         this._lastSelectedItemId = this.getDataTokenId(item);
         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.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) {
         const items = this._list?.getKeyboardNavigationItems();
@@ -281,31 +416,135 @@ 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();
         }
         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)
+                : null;
+            if (activeHeader) {
+                this._handleGroupHeaderCollapse(activeHeader, 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);
+                }
+                else {
+                    this._handleArrowLeftInRow(this._activeDescendantItem);
+                }
+            }
+            return;
+        }
+        // Sync _selectedOption display for the first item (used when popover just opened via click).
+        if (!this._activeDescendantItem && hasItems) {
+            this._selectedOption = items[firstIndex].label;
         }
     }
     handleSearchChange(e) {
@@ -319,6 +558,14 @@ class UDExSelectBase extends UDExSearchableListBase {
             this.openDropdown();
         }
     }
+    onSearch(value) {
+        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";
@@ -334,11 +581,81 @@ class UDExSelectBase extends UDExSearchableListBase {
         this.fireEventDropdownBeforeOpen();
     }
     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.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() {
+        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) {
+        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;
+        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");
     }
@@ -372,11 +689,14 @@ 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;
         }
     }
     inputFocusIn() {
@@ -436,11 +756,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
@@ -467,7 +789,12 @@ class UDExSelectBase extends UDExSearchableListBase {
         const iconSlot = this._getIconButtonSlot(target);
         if (!iconSlot) {
             const firstIcon = target.querySelector("[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") {
@@ -492,7 +819,18 @@ class UDExSelectBase extends UDExSearchableListBase {
             firstIcon?.focus();
         }
         else if (iconSlot === "firstIcon") {
-            this._list.focusItem(parentItem);
+            // 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);
+            const renderedItem = navItems?.find(i => (i.getAttribute("data-token-id") ?? i._id) === tokenId);
+            if (renderedItem) {
+                this._setActiveDescendant(renderedItem);
+            }
+            else {
+                this._list.focusItem(parentItem);
+            }
+            this._search.focus();
         }
     }
     _handleListKeyDownCapture(e) {
@@ -533,7 +871,7 @@ 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() {
@@ -543,15 +881,11 @@ class UDExSelectBase extends UDExSearchableListBase {
             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.focus();
     }
     _firstFocusableIn(el) {
         if (!(el instanceof HTMLElement)) {
@@ -580,11 +914,49 @@ 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) {
+        const parts = [];
+        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() {
         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);
     }
     get trigger() {
@@ -624,6 +996,15 @@ class UDExSelectBase extends UDExSearchableListBase {
     get listboxRole() {
         return this._listBoxRole;
     }
+    get listAriaControlsId() {
+        return this._list?.id || this.popoverId;
+    }
+    get _activeDescendantMode() {
+        return true;
+    }
+    get isTreeStructure() {
+        return this._filteredItems.some(e => e.isGroup);
+    }
     get hideDropdownSearch() {
         return true;
     }
@@ -686,6 +1067,12 @@ __decorate([
 __decorate([
     property({ type: Boolean, noAttribute: true })
 ], UDExSelectBase.prototype, "_requestRender", void 0);
+__decorate([
+    property({ type: Boolean })
+], UDExSelectBase.prototype, "_navigating", void 0);
+__decorate([
+    property({ type: String, noAttribute: true })
+], UDExSelectBase.prototype, "_liveRegionText", void 0);
 __decorate([
     slot({ type: HTMLElement })
 ], UDExSelectBase.prototype, "footer", void 0);