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

package/dist/esm/KeyboardController-DcnXb5F5.js

@@ -0,0 +1,1064 @@
+import { K as KEYBOARD, a as KEYBOARD_MODIFIERS } from './Keys-7G4h4DI7.js';
+import { L as Logger } from './Logger-iq2UuV7c.js';
+import { O as ORIENTATIONS } from './orientation-CPvuMm5C.js';
+
+// ─── Key trigger constants ────────────────────────────────────────────────────
+/**
+ * Event type constants for key bindings.
+ * Use instead of hard-coded `'keydown'` / `'keyup'` strings.
+ */
+const KEY_TRIGGERS = {
+    KEYDOWN: 'keydown',
+    KEYUP: 'keyup',
+};
+// ─── Orientation constants ────────────────────────────────────────────────────
+const KEYBOARD_ORIENTATIONS = {
+    ...ORIENTATIONS,
+    BOTH: 'both',
+};
+// ─── Focus strategy constants ─────────────────────────────────────────────────
+/**
+ * Focus management technique identifiers for `KeyboardController`.
+ * Use these constants instead of raw string literals when setting or comparing
+ * the focus strategy type.
+ */
+const FOCUS_STRATEGY = {
+    ROVING_TABINDEX: 'roving-tabindex',
+    ARIA_ACTIVE_DESCENDANT: 'aria-activedescendant',
+};
+// ─── Navigation boundary constants (internal) ────────────────────────────────
+const NAV_BOUNDARY = {
+    FIRST: 'first',
+    LAST: 'last',
+};
+
+function isHTMLElement$2(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.
+ */
+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.
+ */
+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)`. */
+function applyGridRovingTabindex(items, row, col) {
+    items
+        .flat()
+        .filter(isHTMLElement$2)
+        .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. */
+function initGridRovingTabindex(items, row, col) {
+    items
+        .flat()
+        .filter(isHTMLElement$2)
+        .forEach(item => item.setAttribute('tabindex', '-1'));
+    const cell = items[row]?.[col];
+    if (cell != null)
+        cell.setAttribute('tabindex', '0');
+}
+
+function isHTMLElement$1(cell) {
+    return cell != null;
+}
+/**
+ * Ensures every item in the list has an `id` attribute.
+ * Auto-generates one with a unique suffix when an item lacks it.
+ */
+function ensureItemIds(items, prefix) {
+    items.forEach((item, i) => {
+        if (item.id.length === 0) {
+            item.id = `${prefix}-${i}-${Math.random().toString(36).slice(2, 7)}`;
+        }
+    });
+}
+/**
+ * Applies the **aria-activedescendant** technique to a flat list:
+ * - Ensures all items have `id` attributes.
+ * - Sets `tabindex="-1"` on every item (container holds focus).
+ * - Updates `aria-activedescendant` on `container` to point to the active item.
+ * - Scrolls the active item into view.
+ */
+function applyAriaActiveDescendant(items, activeIndex, container, idPrefix) {
+    const activeItem = items[activeIndex];
+    if (activeItem == null)
+        return;
+    ensureItemIds(items, idPrefix);
+    items.forEach(item => item.setAttribute('tabindex', '-1'));
+    container.setAttribute('aria-activedescendant', activeItem.id);
+    activeItem.scrollIntoView({ block: 'nearest' });
+}
+/** Applies aria-activedescendant to a 2D grid container. */
+function applyGridAriaActiveDescendant(items, row, col, container, idPrefix) {
+    const flat = items.flat().filter(isHTMLElement$1);
+    const cell = items[row]?.[col];
+    if (cell == null)
+        return;
+    ensureItemIds(flat, idPrefix);
+    flat.forEach(item => item.setAttribute('tabindex', '-1'));
+    container.setAttribute('aria-activedescendant', cell.id);
+    cell.scrollIntoView({ block: 'nearest' });
+}
+
+/**
+ * Resolves the index of the currently active item for the given strategy type.
+ *
+ * - `'roving-tabindex'`: reads from `document.activeElement`.
+ * - `'aria-activedescendant'`: reads `aria-activedescendant` from the container.
+ *
+ * Returns `-1` when nothing is active yet.
+ */
+function resolveCurrentIndex(items, strategyType, container) {
+    if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+        const activeId = container?.getAttribute('aria-activedescendant');
+        if (activeId == null)
+            return -1;
+        return items.findIndex(item => item.id === activeId);
+    }
+    return items.indexOf(document.activeElement);
+}
+/**
+ * Resolves the `(row, col)` coordinates of the currently active grid cell.
+ *
+ * - `'roving-tabindex'`: matches against `document.activeElement`.
+ * - `'aria-activedescendant'`: reads `aria-activedescendant` from the container.
+ *
+ * Returns `{ row: -1, col: -1 }` when nothing is active yet.
+ */
+function resolveGridCurrentPos(items, strategyType, container) {
+    if (strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+        const activeId = container?.getAttribute('aria-activedescendant');
+        if (activeId != null) {
+            for (let r = 0; r < items.length; r++) {
+                for (let c = 0; c < items[r].length; c++) {
+                    if (items[r][c]?.id === activeId)
+                        return { row: r, col: c };
+                }
+            }
+        }
+        return { row: -1, col: -1 };
+    }
+    const focused = document.activeElement;
+    for (let r = 0; r < items.length; r++) {
+        for (let c = 0; c < items[r].length; c++) {
+            if (items[r][c] === focused)
+                return { row: r, col: c };
+        }
+    }
+    return { row: -1, col: -1 };
+}
+
+// ─── Setup ────────────────────────────────────────────────────────────────────
+/**
+ * Registers all key bindings for linear list navigation on the given controller.
+ * Called internally by `KeyboardController.setLinearNavigation`.
+ */
+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'));
+            }
+        }
+    }
+}
+
+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;
+}
+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);
+            }
+        }
+    }
+}
+
+// ─── Modifier constants ───────────────────────────────────────────────────────
+/** Maps each modifier key name to the `KeyboardEvent` property that indicates it is active. */
+const MODIFIER_CHECKS = {
+    alt: (e) => e.altKey,
+    control: (e) => e.ctrlKey,
+    meta: (e) => e.metaKey,
+    shift: (e) => e.shiftKey,
+};
+/** Returns `true` when `k` is the normalized name of a modifier key (`alt`, `control`, `meta`, `shift`). */
+function isModifier(k) {
+    return k in MODIFIER_CHECKS;
+}
+/**
+ * Shorthand aliases accepted in key expressions.
+ * Normalized before any binding lookup so callers can use familiar names.
+ *
+ * | Alias | Resolves to |
+ * |-------|-------------|
+ * | `ctrl` | `control` |
+ * | `cmd` / `win` | `meta` |
+ * | `option` | `alt` |
+ * | `space` | `' '` (Space character) |
+ */
+const KEY_ALIASES = {
+    ctrl: KEYBOARD_MODIFIERS.Control,
+    cmd: KEYBOARD_MODIFIERS.Meta,
+    win: KEYBOARD_MODIFIERS.Meta,
+    option: KEYBOARD_MODIFIERS.Alt,
+    space: KEYBOARD.Space,
+};
+// ─── Key binding helpers ──────────────────────────────────────────────────────
+/**
+ * Normalizes a raw key token to its canonical lowercase form.
+ *
+ * - Trims surrounding whitespace (except a literal space character).
+ * - Converts to lowercase.
+ * - Applies {@link KEY_ALIASES} (`'ctrl'` → `'control'`, `'space'` → `' '`).
+ *
+ * @param raw - A single key token as typed by the developer (e.g. `'Ctrl'`, `'ArrowLeft'`).
+ * @returns The canonical lowercase key string used internally for binding lookup.
+ */
+function normalizeKey(raw) {
+    if (raw === ' ')
+        return ' '; // preserve the Space key — trim() would erase it
+    const lower = raw.trim().toLowerCase();
+    return KEY_ALIASES[lower] ?? lower;
+}
+/**
+ * Splits a key expression into separate modifier and regular-key arrays.
+ *
+ * Accepts either a `'+'`-separated combination string (`'ctrl+pagedown'`) or
+ * an array of tokens (`['control', 'pagedown']`). Each token is normalized via
+ * {@link normalizeKey} before classification.
+ *
+ * @param input - A key combination string or array of key tokens.
+ * @returns An object with `keys` (non-modifier keys) and `modifiers` (modifier keys).
+ */
+function parseKeys(input) {
+    const tokens = (Array.isArray(input) ? input : input.split('+')).map(normalizeKey);
+    const modifiers = tokens.filter(k => isModifier(k));
+    const keys = tokens.filter(k => !isModifier(k));
+    return { keys, modifiers };
+}
+/**
+ * Produces a deterministic lookup key for a `Map` from a set of regular keys and modifiers.
+ *
+ * Modifiers are sorted in declaration order (`alt`, `control`, `meta`, `shift`) and
+ * regular keys are sorted alphabetically, so `'ctrl+shift+s'` and `'shift+ctrl+s'`
+ * always produce the same string.
+ *
+ * @param keys - Non-modifier key names (already normalized).
+ * @param modifiers - Modifier key names (already normalized).
+ * @returns A canonical string like `'control+shift+s'` used as the `Map` key.
+ */
+function createCombinationKey(keys, modifiers) {
+    const sortedKeys = [...keys].sort();
+    const sortedMods = Object.keys(MODIFIER_CHECKS).filter(m => modifiers.includes(m));
+    return [...sortedMods, ...sortedKeys].join('+');
+}
+// ─── Controller ───────────────────────────────────────────────────────────────
+/**
+ * Manages keyboard interactions on a Stencil host element.
+ *
+ * Provides a **fluent API** to register key bindings and high-level navigation
+ * patterns following [ARIA APG](https://www.w3.org/WAI/ARIA/apg/) conventions.
+ * All event listeners are cleaned up automatically via a single `AbortController`
+ * — no manual `removeEventListener` is ever needed.
+ *
+ * ---
+ *
+ * ### Lifecycle
+ *
+ * ```ts
+ * private readonly _keyboard = new KeyboardController();
+ *
+ * componentDidLoad() {
+ *   this._keyboard.attach(this.el)
+ *     .setLinearNavigation({ items: 'button', orientation: 'horizontal' });
+ * }
+ *
+ * disconnectedCallback() {
+ *   this._keyboard.detach();
+ * }
+ * ```
+ *
+ * ---
+ *
+ * ### Key Binding API
+ *
+ * | Method | Description |
+ * |--------|-------------|
+ * | `set(key, handler, options?)` | Register a single key, chord, or array of independent keys |
+ * | `setActivateHandler(handler)` | Register `Enter` **and** `Space` with one call (ARIA activation pattern) |
+ * | `onFocusOut(handler)` | Register a `focusout` listener that auto-removes on `detach()` |
+ * | `remove(key)` | Unregister a binding at runtime |
+ *
+ * ---
+ *
+ * ### Navigation API
+ *
+ * | Method | Description |
+ * |--------|-------------|
+ * | `setLinearNavigation(config)` | Arrow keys + `Home`/`End` for flat list navigation |
+ * | `setGridNavigation(config)` | 2D arrow-key navigation for grids, calendars, and tables |
+ * | `rovingTabindex(items, index)` | Manually apply roving tabindex to a list |
+ * | `ariaActiveDescendant(items, index, options?)` | Manually apply `aria-activedescendant` to a list |
+ * | `applyFocus(items, index)` | Strategy-agnostic focus — delegates to whichever strategy was configured |
+ */
+class KeyboardController {
+    /**
+     * @param defaults - Default options applied to every binding registered via `set()`.
+     *   Defaults to `{ preventDefault: true }` to prevent browser scrolling on arrow keys.
+     */
+    constructor(defaults = { preventDefault: true }) {
+        this._bindings = new Map();
+        this._allowedKeys = new Set();
+        this._pressedKeys = new Set();
+        this._logger = new Logger();
+        this._abortController = null;
+        this._root = null;
+        this._strategyType = FOCUS_STRATEGY.ROVING_TABINDEX;
+        this._idPrefix = 'bds-nav-item';
+        this._defaults = defaults;
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────────────
+    /**
+     * Attaches the controller to a host element and starts listening for `keydown`
+     * and `keyup` events. If already attached, detaches first.
+     *
+     * Call in `componentDidLoad()`. Supports method chaining.
+     *
+     * @param el - The Stencil host element (`this.el`) to attach to.
+     * @returns `this` for chaining additional configuration calls.
+     *
+     * @example
+     * ```ts
+     * componentDidLoad() {
+     *   this._keyboard.attach(this.el).setLinearNavigation({ items: 'button' });
+     * }
+     * ```
+     */
+    attach(el) {
+        this.detach();
+        this._root = el;
+        this._abortController = new AbortController();
+        const { signal } = this._abortController;
+        const onKey = (e) => this._dispatchKeyEvent(e);
+        const onClear = () => this._pressedKeys.clear();
+        el.addEventListener(KEY_TRIGGERS.KEYDOWN, onKey, { signal });
+        el.addEventListener(KEY_TRIGGERS.KEYUP, onKey, { signal });
+        // Clear pressed-key state when the element loses focus to prevent stale
+        // combinations after Tab+key sequences.
+        el.addEventListener('focusout', onClear, { signal });
+        // Also clear when the window itself loses focus (e.g. Alt+Tab to another app).
+        globalThis.addEventListener('blur', onClear, { signal });
+        return this;
+    }
+    /**
+     * Removes all event listeners registered by this controller and clears
+     * internal key-press state. Safe to call multiple times.
+     *
+     * Call in `disconnectedCallback()`.
+     *
+     * @example
+     * ```ts
+     * disconnectedCallback() {
+     *   this._keyboard.detach();
+     * }
+     * ```
+     */
+    detach() {
+        this._abortController?.abort();
+        this._abortController = null;
+        this._root = null;
+        this._pressedKeys.clear();
+    }
+    _ensureAttached(method) {
+        if (this._root != null && this._abortController != null)
+            return true;
+        this._logger.warn('KeyboardController', `${method}() was called before attach(). Call attach(el) first.`);
+        return false;
+    }
+    _rebuildAllowedKeys() {
+        this._allowedKeys.clear();
+        this._bindings.forEach(binding => {
+            for (const k of [...binding.keys, ...binding.modifiers]) {
+                this._allowedKeys.add(k);
+            }
+        });
+    }
+    // ─── Private ─────────────────────────────────────────────────────────────
+    _dispatchKeyEvent(event) {
+        const key = event.key.toLowerCase();
+        const isDown = event.type === KEY_TRIGGERS.KEYDOWN;
+        const isUp = event.type === KEY_TRIGGERS.KEYUP;
+        // Fast-path: ignore keys that have no registered binding
+        if (!this._allowedKeys.has(key)) {
+            if (!isModifier(key) && isUp)
+                this._pressedKeys.delete(key);
+            return;
+        }
+        if (!isModifier(key) && isDown) {
+            this._pressedKeys.add(key);
+        }
+        const activeModifiers = Object.keys(MODIFIER_CHECKS).filter(mod => MODIFIER_CHECKS[mod](event));
+        const combination = createCombinationKey(Array.from(this._pressedKeys), activeModifiers);
+        let binding = this._bindings.get(combination);
+        // Fallback: when two non-modifier keys are "simultaneously" pressed (e.g. ArrowDown held
+        // while ArrowUp keyup hasn't fired yet), the multi-key combination won't match any
+        // single-key binding. Try matching just the current key + active modifiers.
+        if (binding === undefined && this._pressedKeys.size > 1) {
+            binding = this._bindings.get(createCombinationKey([key], activeModifiers));
+        }
+        if (binding !== undefined) {
+            // Prevent default for all matching keydown events — including auto-repeat —
+            // so held keys (e.g. Space on a checkbox) never trigger browser scroll even
+            // when the handler is intentionally skipped on repeat.
+            if (binding.options.preventDefault && isDown)
+                event.preventDefault();
+            if (this._matchesTrigger(binding, event)) {
+                // Also prevent default on keyup when the binding fires.
+                if (binding.options.preventDefault && isUp)
+                    event.preventDefault();
+                if (binding.options.stopPropagation)
+                    event.stopPropagation();
+                binding.handler(event);
+            }
+        }
+        if (!isModifier(key) && isUp) {
+            this._pressedKeys.delete(key);
+        }
+    }
+    _matchesTrigger(binding, event) {
+        const triggers = binding.options.triggers ?? [KEY_TRIGGERS.KEYDOWN];
+        if (event.type === KEY_TRIGGERS.KEYDOWN && triggers.includes(KEY_TRIGGERS.KEYDOWN)) {
+            return !event.repeat || Boolean(binding.options.repeat);
+        }
+        if (event.type === KEY_TRIGGERS.KEYUP && triggers.includes(KEY_TRIGGERS.KEYUP)) {
+            return true;
+        }
+        return false;
+    }
+    // ─── Public API ──────────────────────────────────────────────────────────
+    /**
+     * Registers a key binding. Supports single keys, chord combinations, and arrays
+     * of independent keys. Returns `this` for chaining.
+     *
+     * **Accepted `key` formats:**
+     *
+     * | Format | Example | Description |
+     * |--------|---------|-------------|
+     * | Single key | `KEYBOARD.Escape` | One key, no modifier |
+     * | Combination string | `'ctrl+pagedown'` | `+`-separated chord |
+     * | Chord array | `['meta', 'k']` | Same as combination string |
+     * | Independent keys | `[KEYBOARD.Enter, KEYBOARD.Space]` | Two separate bindings sharing one handler |
+     *
+     * @param key - Key expression: a single string, a `'+'`-separated chord, or an array of tokens.
+     * @param handler - Callback invoked when the key combination is triggered.
+     * @param options - Optional overrides for `preventDefault`, `stopPropagation`, `repeat`, and `triggers`.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * this._keyboard
+     *   .attach(this.el)
+     *   .set(KEYBOARD.Escape, () => this.close())
+     *   .set('ctrl+k', () => this.openSearch(), { stopPropagation: true })
+     *   .set([KEYBOARD.Enter, KEYBOARD.Space], () => this.activate());
+     * ```
+     */
+    set(key, handler, options) {
+        if (Array.isArray(key)) {
+            const normalized = key.map(normalizeKey);
+            const hasModifier = normalized.some(k => isModifier(k));
+            if (!hasModifier) {
+                normalized.forEach(k => this.set(k, handler, options));
+                return this;
+            }
+        }
+        const { keys, modifiers } = parseKeys(key);
+        const combination = createCombinationKey(keys, modifiers);
+        const mergedOptions = { ...this._defaults, ...options };
+        for (const k of [...keys, ...modifiers]) {
+            this._allowedKeys.add(k);
+        }
+        this._bindings.set(combination, { keys, modifiers, handler, options: mergedOptions });
+        return this;
+    }
+    /**
+     * Registers the same handler for `Enter` **and** `Space` in a single call.
+     *
+     * This follows the [ARIA widget activation pattern](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
+     * where both keys are expected to activate an interactive element.
+     *
+     * @param handler - Callback invoked on `Enter` or `Space` keydown.
+     * @param options - Optional overrides forwarded to the underlying `set()` calls.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * this._keyboard.attach(this.el).setActivateHandler(() => this.toggle());
+     * ```
+     */
+    setActivateHandler(handler, options) {
+        return this.set([KEYBOARD.Enter, KEYBOARD.Space], handler, options);
+    }
+    /**
+     * Registers a `focusout` listener on the attached root element.
+     *
+     * Unlike `blur`, `focusout` bubbles — it fires when focus leaves **any descendant**,
+     * not just the root itself. The listener is removed automatically when `detach()` is called.
+     *
+     * @param handler - Callback invoked when focus leaves the component subtree.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * this._keyboard.attach(this.el).onFocusOut(() => this.closeDropdown());
+     * ```
+     */
+    onFocusOut(handler) {
+        if (this._root == null || this._abortController == null)
+            return this;
+        this._root.addEventListener('focusout', handler, {
+            signal: this._abortController.signal,
+        });
+        return this;
+    }
+    /**
+     * Applies the **roving tabindex** focus technique to a list of elements.
+     *
+     * Sets `tabindex="-1"` on all items and `tabindex="0"` + `.focus()` on the
+     * item at `activeIndex`. The browser's native Tab key then cycles only through
+     * the single active item, keeping focus contained in the widget.
+     *
+     * `activeIndex` is clamped to `[0, items.length - 1]`.
+     *
+     * @param items - The full list of navigable elements.
+     * @param activeIndex - Index of the element that should receive focus.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * // Manually jump to the last item
+     * this._keyboard.rovingTabindex(buttons, buttons.length - 1);
+     * ```
+     */
+    rovingTabindex(items, activeIndex) {
+        if (items.length === 0)
+            return this;
+        const clamped = Math.max(0, Math.min(activeIndex, items.length - 1));
+        applyRovingTabindex(items, clamped);
+        return this;
+    }
+    /**
+     * Applies the **`aria-activedescendant`** focus technique to a list of elements.
+     *
+     * DOM focus stays on the container at all times. Navigation updates the
+     * container's `aria-activedescendant` attribute to point to the active item's `id`.
+     * Item `id`s are auto-generated using `idPrefix` when missing.
+     *
+     * `activeIndex` is clamped to `[0, items.length - 1]`.
+     *
+     * @param items - The full list of navigable option/grid-cell elements.
+     * @param activeIndex - Index of the logically active item.
+     * @param options.idPrefix - Prefix used to generate missing item `id`s. Defaults to `'bds-nav-item'`.
+     * @param options.container - The element that receives `aria-activedescendant`. Defaults to the attached root.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * this._keyboard.ariaActiveDescendant(options, 2, { idPrefix: 'my-option' });
+     * // -> container.setAttribute('aria-activedescendant', 'my-option-2')
+     * ```
+     */
+    ariaActiveDescendant(items, activeIndex, options) {
+        if (items.length === 0)
+            return this;
+        const container = options?.container ?? this._root;
+        if (container == null)
+            return this;
+        const prefix = options?.idPrefix ?? 'bds-nav-item';
+        const clamped = Math.max(0, Math.min(activeIndex, items.length - 1));
+        applyAriaActiveDescendant(items, clamped, container, prefix);
+        return this;
+    }
+    /**
+     * Moves focus to `items[activeIndex]` using whichever strategy was configured
+     * by the last `setLinearNavigation()` or `setGridNavigation()` call
+     * (`roving-tabindex` or `aria-activedescendant`).
+     *
+     * Use this inside `onNavigate` callbacks to stay strategy-agnostic — the component
+     * does not need to know which strategy is active.
+     *
+     * @param items - The full list of navigable elements.
+     * @param activeIndex - Index of the element that should become active.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * setLinearNavigation({
+     *   items: () => this.radioElements,
+     *   onNavigate: (nextIndex, items) => {
+     *     this.value = (items[nextIndex] as HTMLBdsRadioElement).value;
+     *     this._keyboard.applyFocus(items, nextIndex); // works regardless of focus strategy
+     *   },
+     * });
+     * ```
+     */
+    applyFocus(items, activeIndex) {
+        if (this._strategyType === FOCUS_STRATEGY.ARIA_ACTIVE_DESCENDANT) {
+            return this.ariaActiveDescendant(items, activeIndex, { idPrefix: this._idPrefix });
+        }
+        return this.rovingTabindex(items, activeIndex);
+    }
+    /**
+     * Registers arrow-key (`ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`),
+     * `Home`, and `End` bindings for flat list navigation following the
+     * [ARIA Composite Widget pattern](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_general_within).
+     *
+     * Arrow keys support auto-repeat (throttled to ~10 steps/second by default).
+     * Focus strategy (`roving-tabindex` or `aria-activedescendant`) is resolved
+     * from `config.focusStrategy` and stored for use by `applyFocus()`.
+     *
+     * @param config - Navigation options. See {@link LinearNavigationConfig} for all fields.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * // Toolbar: horizontal arrows, roving tabindex, Enter/Space clicks
+     * this._keyboard.attach(this.el).setLinearNavigation({
+     *   items: 'button:not([disabled])',
+     *   orientation: 'horizontal',
+     *   onActivate: () => (document.activeElement as HTMLElement)?.click(),
+     * });
+     *
+     * // Radio group: all arrows, wrap, selection changes on navigate
+     * this._keyboard.attach(this.el).setLinearNavigation({
+     *   items: () => this.radioElements.filter(el => !el.disabled) as HTMLElement[],
+     *   orientation: 'both',
+     *   wrap: true,
+     *   initialActiveSelector: '[checked]',
+     *   onNavigate: (nextIndex, items) => {
+     *     this.value = (items[nextIndex] as HTMLBdsRadioElement).value;
+     *     this._keyboard.applyFocus(items, nextIndex);
+     *   },
+     * });
+     * ```
+     */
+    setLinearNavigation(config) {
+        if (!this._ensureAttached('setLinearNavigation'))
+            return this;
+        setupLinearNavigation(config, {
+            root: this._root,
+            abortController: this._abortController,
+            register: (key, handler, options) => this.set(key, handler, options),
+            onStrategyResolved: (type, prefix) => {
+                this._strategyType = type;
+                this._idPrefix = prefix;
+            },
+        });
+        return this;
+    }
+    /**
+     * Registers 2D arrow-key navigation for grids, calendars, and data tables following the
+     * [ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).
+     *
+     * Registered bindings:
+     * - `ArrowLeft / ArrowRight` — move one column left/right
+     * - `ArrowUp / ArrowDown` — move one row up/down
+     * - `Home / End` — first/last cell in current row
+     * - `Ctrl+Home / Ctrl+End` — first/last cell in the entire grid
+     * - `PageUp / PageDown` — delegated to `config.onPageUp` / `config.onPageDown` (optional)
+     * - `Enter / Space` — delegated to `config.onActivate` (optional)
+     *
+     * Items are provided as a `HTMLElement[][]` (rows × columns). `null`/`undefined`
+     * cells are skipped. The list is re-evaluated on every keydown.
+     *
+     * @param config - Navigation options. See {@link GridNavigationConfig} for all fields.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * // Data table: 2D navigation, Enter selects a cell
+     * this._keyboard.attach(this.el).setGridNavigation({
+     *   items: () => this._getRowsOfCells(),
+     *   wrap: false,
+     *   onActivate: () => this._selectFocusedCell(),
+     * });
+     *
+     * // Calendar: grid navigation + PageUp/Down to change months
+     * this._keyboard.attach(this.el).setGridNavigation({
+     *   items: () => this.weekRows.map(row => row.map(day => day.buttonEl)),
+     *   wrap: true,
+     *   initialActiveSelector: '[data-today]',
+     *   onActivate: () => this.selectFocusedDay(),
+     *   onPageUp:   () => this.prevMonth(),
+     *   onPageDown: () => this.nextMonth(),
+     * });
+     * ```
+     */
+    setGridNavigation(config) {
+        if (!this._ensureAttached('setGridNavigation'))
+            return this;
+        setupGridNavigation(config, {
+            root: this._root,
+            abortController: this._abortController,
+            register: (key, handler, options) => this.set(key, handler, options),
+            onStrategyResolved: (type, prefix) => {
+                this._strategyType = type;
+                this._idPrefix = prefix;
+            },
+        });
+        return this;
+    }
+    /**
+     * Removes a previously registered binding so it no longer fires.
+     *
+     * Pass the same key expression that was used in `set()`. Useful for dynamically
+     * enabling or disabling shortcuts (e.g. disabling `Escape` while a sub-modal is open).
+     *
+     * @param key - The key expression to unregister (same format accepted by `set()`).
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * // Disable Escape while a confirmation dialog is open
+     * this._keyboard.remove(KEYBOARD.Escape);
+     * // Re-enable it after the dialog closes
+     * this._keyboard.set(KEYBOARD.Escape, () => this.close());
+     * ```
+     */
+    remove(key) {
+        const { keys, modifiers } = parseKeys(key);
+        this._bindings.delete(createCombinationKey(keys, modifiers));
+        this._rebuildAllowedKeys();
+        return this;
+    }
+}
+
+export { KeyboardController as K, KEY_TRIGGERS as a };