@telesign/boreal-web-components 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/collection/utils/a11y/keyboard/focus/roving-tabindex.js

@@ -0,0 +1,55 @@
+function isHTMLElement(cell) {
+    return cell != null;
+}
+/**
+ * Applies the **roving tabindex** technique with real DOM focus.
+ *
+ * Order matters for key-repeat: set `tabindex="0"` and call `.focus()` on the
+ * new item first, then demote the previous item. This ensures focus is never
+ * momentarily absent between steps.
+ */
+export function applyRovingTabindex(items, activeIndex) {
+    const next = items[activeIndex];
+    if (next == null)
+        return;
+    const prevIndex = items.findIndex(item => item.getAttribute('tabindex') === '0');
+    next.setAttribute('tabindex', '0');
+    next.focus();
+    if (prevIndex !== -1 && prevIndex !== activeIndex) {
+        items[prevIndex].setAttribute('tabindex', '-1');
+    }
+}
+/**
+ * Initializes the **roving tabindex** technique without stealing focus.
+ * Only sets tabindex attributes; use during component initialization to
+ * avoid moving DOM focus away from the previously focused element.
+ */
+export function initRovingTabindex(items, activeIndex) {
+    const activeItem = items[activeIndex];
+    if (activeItem == null)
+        return;
+    items.forEach(item => item.setAttribute('tabindex', '-1'));
+    activeItem.setAttribute('tabindex', '0');
+}
+/** Applies roving tabindex to a 2D grid. Moves real DOM focus to `(row, col)`. */
+export function applyGridRovingTabindex(items, row, col) {
+    items
+        .flat()
+        .filter(isHTMLElement)
+        .forEach(item => item.setAttribute('tabindex', '-1'));
+    const cell = items[row]?.[col];
+    if (cell != null) {
+        cell.setAttribute('tabindex', '0');
+        cell.focus();
+    }
+}
+/** Sets tabindex attributes on a 2D grid without stealing focus; use during initialization. */
+export function initGridRovingTabindex(items, row, col) {
+    items
+        .flat()
+        .filter(isHTMLElement)
+        .forEach(item => item.setAttribute('tabindex', '-1'));
+    const cell = items[row]?.[col];
+    if (cell != null)
+        cell.setAttribute('tabindex', '0');
+}

package/dist/collection/utils/a11y/keyboard/navigation/grid-navigation.js

@@ -0,0 +1,194 @@
+import { KEYBOARD } from "../../../constants/index";
+import { FOCUS_STRATEGY } from "../_constants";
+import { applyGridRovingTabindex, initGridRovingTabindex } from "../focus/roving-tabindex";
+import { applyGridAriaActiveDescendant } from "../focus/aria-activedescendant";
+import { resolveGridCurrentPos } from "../focus/resolve";
+function isHTMLElement(cell) {
+    return cell != null;
+}
+function getPositions(items) {
+    const positions = [];
+    items.forEach((rowItems, row) => {
+        rowItems.forEach((cell, col) => {
+            if (isHTMLElement(cell))
+                positions.push({ row, col, cell });
+        });
+    });
+    return positions;
+}
+function getRowPositions(items, row) {
+    return (items[row]
+        ?.map((cell, col) => (isHTMLElement(cell) ? { row, col, cell } : null))
+        .filter((pos) => pos != null) ?? []);
+}
+function getCell(items, row, col) {
+    if (row < 0 || col < 0)
+        return null;
+    const cell = items.at(row)?.at(col);
+    return isHTMLElement(cell) ? cell : null;
+}
+function closestColumn(positions, col) {
+    return positions.reduce((closest, position) => {
+        if (closest == null)
+            return position;
+        return Math.abs(position.col - col) < Math.abs(closest.col - col) ? position : closest;
+    }, null);
+}
+function findRowWithCells(items, startRow, step, wrap) {
+    const rowCount = items.length;
+    let row = startRow;
+    for (let checked = 0; checked < rowCount; checked++) {
+        if (row < 0 || row >= rowCount) {
+            if (!wrap)
+                return -1;
+            row = row < 0 ? rowCount - 1 : 0;
+        }
+        if (getRowPositions(items, row).length > 0)
+            return row;
+        row += step;
+    }
+    return -1;
+}
+export function setupGridNavigation(config, ctrl) {
+    const { wrap = false, focusStrategy = { type: FOCUS_STRATEGY.ROVING_TABINDEX }, initialActiveSelector, onNavigate, onActivate, activateKeys = [KEYBOARD.Enter, KEYBOARD.Space], onPageUp, onPageDown, onEscape, repeatThrottleMs = 100, } = config;
+    const strategyType = focusStrategy.type;
+    const idPrefix = focusStrategy.type === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT
+        ? (focusStrategy.idPrefix ?? `${ctrl.root?.tagName.toLowerCase() ?? 'bds-grid'}-item`)
+        : 'bds-grid-item';
+    ctrl.onStrategyResolved(strategyType, idPrefix);
+    const resolveItems = typeof config.items === 'function' ? config.items : () => config.items;
+    const applyFocus = (items, row, col) => {
+        const cell = items[row]?.[col];
+        if (cell == null)
+            return;
+        if (onNavigate != null) {
+            onNavigate(row, col, items);
+            return;
+        }
+        if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+            if (ctrl.root != null)
+                applyGridAriaActiveDescendant(items, row, col, ctrl.root, idPrefix);
+        }
+        else {
+            applyGridRovingTabindex(items, row, col);
+        }
+    };
+    const move = (dRow, dCol) => {
+        const items = resolveItems();
+        const positions = getPositions(items);
+        if (positions.length === 0)
+            return;
+        let { row, col } = resolveGridCurrentPos(items, strategyType, ctrl.root);
+        const currentCell = getCell(items, row, col);
+        if (!isHTMLElement(currentCell)) {
+            row = positions[0].row;
+            col = positions[0].col;
+        }
+        if (dRow !== 0) {
+            const nextRow = findRowWithCells(items, row + dRow, dRow > 0 ? 1 : -1, wrap);
+            if (nextRow === -1)
+                return;
+            const nextCell = closestColumn(getRowPositions(items, nextRow), col);
+            if (nextCell != null)
+                applyFocus(items, nextCell.row, nextCell.col);
+            return;
+        }
+        const rowPositions = getRowPositions(items, row);
+        const currentRowIndex = rowPositions.findIndex(position => position.col === col);
+        const nextRowIndex = currentRowIndex + dCol;
+        if (nextRowIndex >= 0 && nextRowIndex < rowPositions.length) {
+            const nextCell = rowPositions[nextRowIndex];
+            applyFocus(items, nextCell.row, nextCell.col);
+            return;
+        }
+        if (wrap && items.length > 1) {
+            const nextRow = findRowWithCells(items, row + dCol, dCol > 0 ? 1 : -1, true);
+            if (nextRow === -1)
+                return;
+            const nextRowPositions = getRowPositions(items, nextRow);
+            const nextCell = dCol > 0 ? nextRowPositions[0] : nextRowPositions[nextRowPositions.length - 1];
+            applyFocus(items, nextCell.row, nextCell.col);
+            return;
+        }
+        const edgeCell = dCol > 0 ? rowPositions[rowPositions.length - 1] : rowPositions[0];
+        applyFocus(items, edgeCell.row, edgeCell.col);
+    };
+    const moveToEdge = (boundary) => {
+        const items = resolveItems();
+        const positions = getPositions(items);
+        if (positions.length === 0)
+            return;
+        let { row } = resolveGridCurrentPos(items, strategyType, ctrl.root);
+        if (row === -1 || getRowPositions(items, row).length === 0)
+            row = positions[0].row;
+        switch (boundary) {
+            case 'row-start': {
+                const first = getRowPositions(items, row)[0];
+                applyFocus(items, first.row, first.col);
+                break;
+            }
+            case 'row-end': {
+                const rowPositions = getRowPositions(items, row);
+                const last = rowPositions[rowPositions.length - 1];
+                applyFocus(items, last.row, last.col);
+                break;
+            }
+            case 'grid-start':
+                applyFocus(items, positions[0].row, positions[0].col);
+                break;
+            case 'grid-end': {
+                const last = positions[positions.length - 1];
+                applyFocus(items, last.row, last.col);
+                break;
+            }
+        }
+    };
+    let lastRepeatTime = 0;
+    const withThrottle = (fn) => (e) => {
+        if (e.repeat && repeatThrottleMs > 0) {
+            const now = Date.now();
+            if (now - lastRepeatTime < repeatThrottleMs)
+                return;
+            lastRepeatTime = now;
+        }
+        fn();
+    };
+    ctrl.register(KEYBOARD.ArrowLeft, withThrottle(() => move(0, -1)), { repeat: true });
+    ctrl.register(KEYBOARD.ArrowRight, withThrottle(() => move(0, +1)), { repeat: true });
+    ctrl.register(KEYBOARD.ArrowUp, withThrottle(() => move(-1, 0)), { repeat: true });
+    ctrl.register(KEYBOARD.ArrowDown, withThrottle(() => move(+1, 0)), { repeat: true });
+    ctrl.register(KEYBOARD.Home, () => moveToEdge('row-start'));
+    ctrl.register(KEYBOARD.End, () => moveToEdge('row-end'));
+    ctrl.register(['control', KEYBOARD.Home], () => moveToEdge('grid-start'));
+    ctrl.register(['control', KEYBOARD.End], () => moveToEdge('grid-end'));
+    if (onActivate != null && activateKeys.length > 0)
+        ctrl.register(activateKeys, onActivate);
+    if (onPageUp != null)
+        ctrl.register(KEYBOARD.PageUp, onPageUp);
+    if (onPageDown != null)
+        ctrl.register(KEYBOARD.PageDown, onPageDown);
+    if (onEscape != null)
+        ctrl.register(KEYBOARD.Escape, onEscape);
+    if (ctrl.root != null && ctrl.abortController != null) {
+        const items = resolveItems();
+        const positions = getPositions(items);
+        if (positions.length > 0) {
+            const selected = initialActiveSelector != null
+                ? positions.find(position => position.cell.matches(initialActiveSelector))
+                : undefined;
+            const initial = selected ?? positions[0];
+            if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+                applyGridAriaActiveDescendant(items, initial.row, initial.col, ctrl.root, idPrefix);
+                const root = ctrl.root;
+                const { signal } = ctrl.abortController;
+                root.addEventListener('mousedown', (e) => {
+                    e.preventDefault();
+                    root.focus();
+                }, { signal });
+            }
+            else {
+                initGridRovingTabindex(items, initial.row, initial.col);
+            }
+        }
+    }
+}

package/dist/collection/utils/a11y/keyboard/navigation/linear-navigation.js

@@ -0,0 +1,137 @@
+import { KEYBOARD } from "../../../constants/index";
+import { KEYBOARD_ORIENTATIONS, NAV_BOUNDARY, FOCUS_STRATEGY } from "../_constants";
+import { applyRovingTabindex, initRovingTabindex } from "../focus/roving-tabindex";
+import { applyAriaActiveDescendant } from "../focus/aria-activedescendant";
+import { resolveCurrentIndex } from "../focus/resolve";
+// ─── Setup ────────────────────────────────────────────────────────────────────
+/**
+ * Registers all key bindings for linear list navigation on the given controller.
+ * Called internally by `KeyboardController.setLinearNavigation`.
+ */
+export function setupLinearNavigation(config, ctrl) {
+    const { orientation = KEYBOARD_ORIENTATIONS.BOTH, wrap = true, focusStrategy = { type: FOCUS_STRATEGY.ROVING_TABINDEX }, initialActiveSelector, onNavigate, onItemActive, onActivate, activateKeys = [KEYBOARD.Enter, KEYBOARD.Space], onEscape, repeatThrottleMs = 100, } = config;
+    const strategyType = focusStrategy.type;
+    const idPrefix = focusStrategy.type === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT
+        ? (focusStrategy.idPrefix ?? `${ctrl.root?.tagName.toLowerCase() ?? 'bds-nav'}-item`)
+        : 'bds-nav-item';
+    ctrl.onStrategyResolved(strategyType, idPrefix);
+    const resolveItems = typeof config.items === 'function'
+        ? config.items
+        : () => Array.from(ctrl.root?.querySelectorAll(config.items) ?? []);
+    let prevIndex = -1;
+    const move = (delta, eventTarget) => {
+        const items = resolveItems();
+        if (items.length === 0)
+            return;
+        let current = resolveCurrentIndex(items, strategyType, ctrl.root);
+        // Fallback: in test environments document.activeElement may not reflect
+        // the dispatched event target, so use the event target when current is unresolved.
+        if (current === -1 && eventTarget != null) {
+            current = items.indexOf(eventTarget);
+        }
+        let next;
+        if (delta === NAV_BOUNDARY.FIRST) {
+            next = 0;
+        }
+        else if (delta === NAV_BOUNDARY.LAST) {
+            next = items.length - 1;
+        }
+        else {
+            // When current is -1 (nothing active yet), treat as position -1 so
+            // +1 lands on 0 and -1 lands on the last item (with wrap) or 0 (no wrap).
+            const raw = (current === -1 ? (delta === 1 ? -1 : 0) : current) + delta;
+            if (raw < 0)
+                next = wrap ? items.length - 1 : 0;
+            else if (raw >= items.length)
+                next = wrap ? 0 : items.length - 1;
+            else
+                next = raw;
+        }
+        // Call onItemActive before focus strategies (so component can update state).
+        // Only used with aria-activedescendant since roving-tabindex uses :focus-visible.
+        if (onItemActive != null && strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+            const prevItem = prevIndex >= 0 ? items[prevIndex] : null;
+            onItemActive(items[next], prevItem);
+        }
+        if (onNavigate != null) {
+            onNavigate(next, items);
+        }
+        else if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+            if (ctrl.root != null)
+                applyAriaActiveDescendant(items, next, ctrl.root, idPrefix);
+        }
+        else {
+            applyRovingTabindex(items, next);
+        }
+        prevIndex = next;
+    };
+    const target = (e) => e.target;
+    // Throttle for key-repeat: the browser fires repeat events every ~50 ms
+    // (20/sec), which is too fast for smooth visual navigation. We limit repeat
+    // events to at most one per `repeatThrottleMs` (default 100 ms ≈ 10/sec).
+    let lastRepeatTime = 0;
+    const withThrottle = (fn) => (e) => {
+        if (e.repeat && repeatThrottleMs > 0) {
+            const now = Date.now();
+            if (now - lastRepeatTime < repeatThrottleMs)
+                return;
+            lastRepeatTime = now;
+        }
+        fn(e);
+    };
+    // Arrow keys always repeat — holding a key navigates continuously.
+    if (orientation === KEYBOARD_ORIENTATIONS.HORIZONTAL || orientation === KEYBOARD_ORIENTATIONS.BOTH) {
+        ctrl.register(KEYBOARD.ArrowLeft, withThrottle(e => move(-1, target(e))), { repeat: true });
+        ctrl.register(KEYBOARD.ArrowRight, withThrottle(e => move(+1, target(e))), { repeat: true });
+    }
+    if (orientation === KEYBOARD_ORIENTATIONS.VERTICAL || orientation === KEYBOARD_ORIENTATIONS.BOTH) {
+        ctrl.register(KEYBOARD.ArrowUp, withThrottle(e => move(-1, target(e))), { repeat: true });
+        ctrl.register(KEYBOARD.ArrowDown, withThrottle(e => move(+1, target(e))), { repeat: true });
+    }
+    ctrl.register(KEYBOARD.Home, () => move(NAV_BOUNDARY.FIRST));
+    ctrl.register(KEYBOARD.End, () => move(NAV_BOUNDARY.LAST));
+    if (onActivate != null && activateKeys.length > 0)
+        ctrl.register(activateKeys, onActivate);
+    if (onEscape != null)
+        ctrl.register(KEYBOARD.Escape, onEscape);
+    if (ctrl.root != null && ctrl.abortController != null) {
+        const root = ctrl.root;
+        const { signal } = ctrl.abortController;
+        if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+            // Keep DOM focus on the container at all times (ARIA APG listbox pattern).
+            root.addEventListener('mousedown', (e) => {
+                e.preventDefault();
+                root.focus();
+            }, { signal });
+        }
+        // Auto-initialize focus state so the component doesn't need to manage
+        // tabIndex or aria-activedescendant manually after setLinearNavigation.
+        const items = resolveItems();
+        if (items.length > 0) {
+            let initial = resolveCurrentIndex(items, strategyType, root);
+            if (initial === -1 && initialActiveSelector != null) {
+                initial = items.findIndex(item => item.matches(initialActiveSelector));
+            }
+            // For roving-tabindex: always fall back to 0 — something must have tabindex="0".
+            // For aria-activedescendant: only initialize if a match was found.
+            const initialIndex = initial !== -1 ? initial : strategyType === FOCUS_STRATEGY.ROVING_TABINDEX ? 0 : -1;
+            if (initialIndex !== -1) {
+                if (onItemActive != null && strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+                    onItemActive(items[initialIndex], null);
+                }
+                prevIndex = initialIndex;
+                if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+                    applyAriaActiveDescendant(items, initialIndex, root, idPrefix);
+                }
+                else {
+                    initRovingTabindex(items, initialIndex);
+                }
+            }
+            else {
+                // aria-activedescendant with no pre-selected item: ensure items are not
+                // directly focusable (container holds focus via tabindex="0").
+                items.forEach(item => item.setAttribute('tabindex', '-1'));
+            }
+        }
+    }
+}

package/dist/collection/utils/a11y/keyboard/types/IKeyboardController.js

@@ -0,0 +1 @@
+export {};

package/dist/collection/utils/a11y/keyboard/types/index.js

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './IKeyboardController';

package/dist/collection/utils/a11y/keyboard/types/types.js

@@ -0,0 +1 @@
+export {};

package/dist/collection/utils/constants/common/Keys.js

@@ -1,28 +1,33 @@
 /**
- * Default keyboard keys.
- * Add more keys to the `KEYBOARD` object to add more keyboard shortcuts.
- * This prevents key name typing errors and provides a centralized definition of the keys available for implementation.
- * Can use this page to find the keycodes: https://keycode.info/
+ * Keyboard key values matching `KeyboardEvent.key` exactly (W3C UI Events spec).
+ * Use in direct `event.key` comparisons and `.set()` bindings.
  */
 export const KEYBOARD = {
-    Enter: {
-        key: 'Enter',
-        code: 13,
-    },
-    Escape: {
-        key: 'Escape',
-        code: 27,
-    },
-    Space: {
-        key: ' ',
-        code: 32,
-    },
-    ArrowUp: {
-        key: 'ArrowUp',
-        code: 38,
-    },
-    ArrowDown: {
-        key: 'ArrowDown',
-        code: 40,
-    },
+    // Navigation
+    ArrowUp: 'ArrowUp',
+    ArrowDown: 'ArrowDown',
+    ArrowLeft: 'ArrowLeft',
+    ArrowRight: 'ArrowRight',
+    Home: 'Home',
+    End: 'End',
+    // Action
+    Enter: 'Enter',
+    Escape: 'Escape',
+    Space: ' ',
+    Delete: 'Delete',
+    Backspace: 'Backspace',
+    // Paging
+    PageUp: 'PageUp',
+    PageDown: 'PageDown',
+};
+/**
+ * Modifier key identifiers in lowercase — match `event.key.toLowerCase()`.
+ * Never compared against `event.key` directly; detected via `event.altKey`, `event.ctrlKey`, etc.
+ * Use in `.set()` chord bindings: `.set([KEYBOARD_MODIFIERS.Control, KEYBOARD.ArrowRight], handler)`.
+ */
+export const KEYBOARD_MODIFIERS = {
+    Alt: 'alt',
+    Control: 'control',
+    Meta: 'meta',
+    Shift: 'shift',
 };

package/dist/collection/utils/dom/elements.js

@@ -20,3 +20,66 @@ export function hasSlotContent(el, slotName) {
         return false;
     });
 }
+/**
+ * Method to return clean text from html element, removing extra spaces and line breaks.
+ * Removing tags and getting only the text content.
+ *
+ * @param el - HTML element to extract text from.
+ * @returns string with the clean text content of the element.
+ */
+export function getCleanText(el) {
+    const textContent = el;
+    if (textContent !== null) {
+        return textContent.textContent?.trim() || '';
+    }
+    return '';
+}
+/**
+ * Method to update a property of an HTML element, checking if the element is not null before updating.
+ *
+ * @param el - HTML element to update.
+ * @param prop - Property name to update.
+ * @param value - Value to set for the property.
+ */
+export function updateElementProp(el, prop, value) {
+    if (el !== null) {
+        el[prop] = value;
+    }
+}
+/**
+ * Method to update an attribute of an HTML element, checking if the element is not null before updating.
+ * This method is used to update attributes that are not reflected as properties in the DOM, such as ARIA attributes.
+ *
+ * @param el - HTML element to update.
+ * @param attr - Attribute name to update.
+ * @param value - Value to set for the attribute.
+ */
+export function updateElementAttr(el, attr, value) {
+    if (el !== null && el !== undefined) {
+        el.setAttribute(attr, value);
+    }
+}
+/**
+ * Method to add an event listener to an HTML element, checking if the element is not null before adding the listener.
+ *
+ * @param el - HTML element to add the event listener to.
+ * @param event - Event name to listen for.
+ * @param handler - Event handler function or object to handle the event.
+ */
+export function addElementListener(el, event, handler) {
+    if (el !== null && el !== undefined) {
+        el.addEventListener(event, handler);
+    }
+}
+/**
+ * Method to remove an event listener from an HTML element, checking if the element is not null before removing the listener.
+ *
+ * @param el - HTML element to remove the event listener from.
+ * @param event - Event name to stop listening for.
+ * @param handler - Event handler function or object that was used to handle the event.
+ */
+export function removeElementListener(el, event, handler) {
+    if (el !== null && el !== undefined) {
+        el.removeEventListener(event, handler);
+    }
+}

package/dist/collection/utils/menu/menu-item.utils.js

@@ -25,20 +25,18 @@ export function resolveAriaSelected(role, selected) {
  * Resolves the tabIndex attribute for keyboard navigation.
  * @param {MenuItemRole} role - The role of the item.
  * @param {boolean} disabled - Whether the item is currently disabled.
- * @param {boolean} selected - Whether the item is currently selected.
  * @param {boolean} active - Whether the item is currently active.
  * @returns {number} - Returns 0 for focusable menu items, or -1 for disabled/options.
  * @example
  * const index = resolveTabIndex('menuitem', false); // returns 0
  * const indexDisabled = resolveTabIndex('menuitem', true); // returns -1
  */
-export function resolveTabIndex(role, disabled, selected, active) {
+export function resolveTabIndex(role, disabled, active) {
     if (disabled)
         return -1;
-    if (role === 'option')
-        return selected || active ? 0 : -1;
-    if (role === 'menuitem')
+    if (role === 'option' || role === 'menuitem') {
         return active ? 0 : -1;
+    }
     return -1;
 }
 /**
@@ -46,6 +44,7 @@ export function resolveTabIndex(role, disabled, selected, active) {
  * @param {KeyboardEvent} event - The keyboard event object from the listener.
  * @param {HTMLElement[]} items - An array of focusable HTML elements within the menu.
  * @param {number} currentIndex - The index of the currently focused item.
+ * @param {boolean} selected - The current selection state of the item (used for activation logic).
  * @returns {void}
  * @example
  * handleMenuKeyNavigation(event, menuItems, 2);
@@ -55,16 +54,18 @@ export function handleMenuKeyNavigation(event, items, currentIndex) {
         return;
     let nextIndex = -1;
     switch (event.key) {
-        case KEYBOARD.ArrowDown.key:
+        case KEYBOARD.ArrowDown:
             nextIndex = (currentIndex + 1) % items.length;
             break;
-        case KEYBOARD.ArrowUp.key:
+        case KEYBOARD.ArrowUp:
             nextIndex = (currentIndex - 1 + items.length) % items.length;
             break;
         default:
             return;
     }
+    items.forEach(item => item.removeAttribute('active-item'));
     items[nextIndex].focus();
+    items[nextIndex].setAttribute('active-item', '');
 }
 /** Prevents default browser behavior for specific navigation keys.
  * @param {KeyboardEvent} e - The keyboard event to evaluate.
@@ -74,7 +75,7 @@ export function handleMenuKeyNavigation(event, items, currentIndex) {
  * preventNavigationKeys(event);
  */
 export function preventNavigationKeys(e) {
-    const navigationKeys = [KEYBOARD.ArrowDown.key, KEYBOARD.ArrowUp.key, KEYBOARD.Enter.key, KEYBOARD.Space.key];
+    const navigationKeys = [KEYBOARD.ArrowDown, KEYBOARD.ArrowUp, KEYBOARD.Enter, KEYBOARD.Space];
     if (navigationKeys.includes(e.key)) {
         e.preventDefault();
     }

package/dist/collection/utils/testing/helpers.js

@@ -14,3 +14,13 @@ export function assertExists(condition, message) {
         throw new Error(message);
     }
 }
+/**
+ * Dispatches a `keydown` event on the given element.
+ *
+ * @param el The target element.
+ * @param key The `KeyboardEvent.key` value to dispatch.
+ * @param init Optional overrides merged on top of the defaults (`bubbles: true`, `cancelable: true`).
+ */
+export function dispatchKey(el, key, init = {}) {
+    el.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init, key }));
+}