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

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

@@ -0,0 +1,566 @@
+import { KEYBOARD, KEYBOARD_MODIFIERS } from "../../constants/index";
+import { Logger } from "../../../services/logger/index";
+import { KEY_TRIGGERS, FOCUS_STRATEGY } from "./_constants";
+import { applyRovingTabindex } from "./focus/roving-tabindex";
+import { applyAriaActiveDescendant } from "./focus/aria-activedescendant";
+import { setupLinearNavigation } from "./navigation/linear-navigation";
+import { setupGridNavigation } from "./navigation/grid-navigation";
+// ─── 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 |
+ */
+export 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;
+    }
+}

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

@@ -0,0 +1,30 @@
+import { ORIENTATIONS } from "../../../types/index";
+// ─── Key trigger constants ────────────────────────────────────────────────────
+/**
+ * Event type constants for key bindings.
+ * Use instead of hard-coded `'keydown'` / `'keyup'` strings.
+ */
+export const KEY_TRIGGERS = {
+    KEYDOWN: 'keydown',
+    KEYUP: 'keyup',
+};
+// ─── Orientation constants ────────────────────────────────────────────────────
+export 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.
+ */
+export const FOCUS_STRATEGY = {
+    ROVING_TABINDEX: 'roving-tabindex',
+    ARIA_ACTIVE_DESCENDANT: 'aria-activedescendant',
+};
+// ─── Navigation boundary constants (internal) ────────────────────────────────
+export const NAV_BOUNDARY = {
+    FIRST: 'first',
+    LAST: 'last',
+};

package/dist/collection/utils/a11y/keyboard/focus/aria-activedescendant.js

@@ -0,0 +1,41 @@
+function isHTMLElement(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.
+ */
+export 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.
+ */
+export 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. */
+export function applyGridAriaActiveDescendant(items, row, col, container, idPrefix) {
+    const flat = items.flat().filter(isHTMLElement);
+    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' });
+}

package/dist/collection/utils/a11y/keyboard/focus/resolve.js

@@ -0,0 +1,48 @@
+import { FOCUS_STRATEGY } from "../_constants";
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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 };
+}