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

package/dist/types/mixins/menu-behavior.mixin.d.ts

@@ -11,7 +11,6 @@ import { MixedInCtor } from '../stencil-public-runtime';
  * - Computation of aria-selected and tabIndex attributes for accessibility.
  * - A method to handle keyboard navigation (Arrow keys, Enter, Space) within the menu context.
  *
- *
  * @typeParam B - The base constructor type.
  * @param {B} Base - The base component class to be extended.
  * @returns {MenuBehaviorMixin} - A class with injected menu behaviors.
@@ -56,6 +55,11 @@ export declare const MenuItemBehavior: <B extends MixedInCtor>(Base: B) => {
         disabled: boolean;
         selected: boolean;
         activeItem: boolean;
+        /**
+         * Finds the closest parent element with a role of 'menu' or 'listbox'.
+         * @returns {HTMLElement | null} - The parent menu or listbox element, or null if not found.
+         */
+        readonly parent: HTMLElement | null;
         /**
          * Detects the ARIA role of the nearest parent menu or listbox.
          * @returns {MenuRole | null} - 'menu', 'listbox', or null if not found.

package/dist/types/types/form.d.ts

@@ -3,4 +3,28 @@ export interface IFormValidator {
     isValid: (el: HTMLElement) => boolean;
     message: string;
 }
+/**
+ * Interface that define and centralize some props to the form components.
+ * In this way we standardize the props and avoid repetition.
+ * @public
+ * @interface IFormProps
+ * @augments {IFormProps}
+ * @property {string} name - Name of the form control, submitted as a key in the form data.
+ * @property {boolean} disabled - Disables the control. Defaults to `false`.
+ * @property {boolean} required - Marks the control as required for form submission. Defaults to `false`.
+ * @property {string} info - Tooltip content attached to the label. Rendered via `bds-typography` `tooltipText` prop.
+ * @property {boolean} error - When `true`, applies the error visual state.
+ * @property {string} errorMessage - Message shown below the input when `error` is `true`. Replaces `helperText`.
+ * @property {string} label - Label displayed next to the input. Defaults to `""`.
+ * @property {string} helperText - Help text displayed below the input. Defaults to `""`.
+ * @example
+ * export interface IToggle extends IFormProps {}
+ */
+export interface IFormProps {
+    info?: string;
+    error?: boolean;
+    errorMessage?: string;
+    label?: string;
+    helperText?: string;
+}
 //# sourceMappingURL=form.d.ts.map

package/dist/types/types/index.d.ts

@@ -3,7 +3,8 @@ export * from './form';
 export * from './size';
 export * from './states';
 export * from './stylesMap';
-export * from './IFormProps';
+export * from './orientation';
 export * from './menu';
 export * from './links';
+export * from './orientation';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/types/orientation.d.ts

@@ -0,0 +1,6 @@
+export declare const ORIENTATIONS: {
+    readonly HORIZONTAL: "horizontal";
+    readonly VERTICAL: "vertical";
+};
+export type Orientation = (typeof ORIENTATIONS)[keyof typeof ORIENTATIONS];
+//# sourceMappingURL=orientation.d.ts.map

package/dist/types/utils/a11y/index.d.ts

@@ -1,2 +1,6 @@
 export * from './attributes';
+export * from './keyboard/_constants';
+export * from './keyboard/types';
+export { KeyboardController } from './keyboard/KeyboardController';
+export { KEYBOARD, KEYBOARD_MODIFIERS } from '../constants';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/utils/a11y/keyboard/KeyboardController.d.ts

@@ -0,0 +1,321 @@
+import type { KeyBindingHandler, KeyBindingOptions, LinearNavigationConfig, GridNavigationConfig } from './types';
+/**
+ * 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 declare class KeyboardController {
+    private readonly _bindings;
+    private readonly _allowedKeys;
+    private readonly _pressedKeys;
+    private readonly _defaults;
+    private readonly _logger;
+    private _abortController;
+    private _root;
+    private _strategyType;
+    private _idPrefix;
+    /**
+     * @param defaults - Default options applied to every binding registered via `set()`.
+     *   Defaults to `{ preventDefault: true }` to prevent browser scrolling on arrow keys.
+     */
+    constructor(defaults?: KeyBindingOptions);
+    /**
+     * 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: HTMLElement): 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(): void;
+    private _ensureAttached;
+    private _rebuildAllowedKeys;
+    private _dispatchKeyEvent;
+    private _matchesTrigger;
+    /**
+     * 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: string | string[], handler: KeyBindingHandler, options?: KeyBindingOptions): 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: KeyBindingHandler, options?: KeyBindingOptions): this;
+    /**
+     * 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: (event: FocusEvent) => void): 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: HTMLElement[], activeIndex: number): 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: HTMLElement[], activeIndex: number, options?: {
+        idPrefix?: string;
+        container?: HTMLElement;
+    }): 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: HTMLElement[], activeIndex: number): this;
+    /**
+     * 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: LinearNavigationConfig): 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: GridNavigationConfig): 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: string | string[]): this;
+}
+//# sourceMappingURL=KeyboardController.d.ts.map

package/dist/types/utils/a11y/keyboard/_constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Event type constants for key bindings.
+ * Use instead of hard-coded `'keydown'` / `'keyup'` strings.
+ */
+export declare const KEY_TRIGGERS: {
+    readonly KEYDOWN: "keydown";
+    readonly KEYUP: "keyup";
+};
+export declare const KEYBOARD_ORIENTATIONS: {
+    readonly BOTH: "both";
+    readonly HORIZONTAL: "horizontal";
+    readonly VERTICAL: "vertical";
+};
+/**
+ * Focus management technique identifiers for `KeyboardController`.
+ * Use these constants instead of raw string literals when setting or comparing
+ * the focus strategy type.
+ */
+export declare const FOCUS_STRATEGY: {
+    readonly ROVING_TABINDEX: "roving-tabindex";
+    readonly ARIA_ACTIVE_DESCENDANT: "aria-activedescendant";
+};
+export declare const NAV_BOUNDARY: {
+    readonly FIRST: "first";
+    readonly LAST: "last";
+};
+export type NavBoundary = (typeof NAV_BOUNDARY)[keyof typeof NAV_BOUNDARY];
+//# sourceMappingURL=_constants.d.ts.map

package/dist/types/utils/a11y/keyboard/focus/aria-activedescendant.d.ts

@@ -0,0 +1,17 @@
+import type { GridNavigationItems } from '../types';
+/**
+ * Ensures every item in the list has an `id` attribute.
+ * Auto-generates one with a unique suffix when an item lacks it.
+ */
+export declare function ensureItemIds(items: HTMLElement[], prefix: string): void;
+/**
+ * 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 declare function applyAriaActiveDescendant(items: HTMLElement[], activeIndex: number, container: HTMLElement, idPrefix: string): void;
+/** Applies aria-activedescendant to a 2D grid container. */
+export declare function applyGridAriaActiveDescendant(items: GridNavigationItems, row: number, col: number, container: HTMLElement, idPrefix: string): void;
+//# sourceMappingURL=aria-activedescendant.d.ts.map

package/dist/types/utils/a11y/keyboard/focus/resolve.d.ts

@@ -0,0 +1,23 @@
+import type { GridNavigationItems, FocusStrategyType } from '../types';
+/**
+ * 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 declare function resolveCurrentIndex(items: HTMLElement[], strategyType: FocusStrategyType, container: HTMLElement | null): number;
+/**
+ * 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 declare function resolveGridCurrentPos(items: GridNavigationItems, strategyType: FocusStrategyType, container: HTMLElement | null): {
+    row: number;
+    col: number;
+};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/types/utils/a11y/keyboard/focus/roving-tabindex.d.ts

@@ -0,0 +1,20 @@
+import type { GridNavigationItems } from '../types';
+/**
+ * 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 declare function applyRovingTabindex(items: HTMLElement[], activeIndex: number): void;
+/**
+ * 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 declare function initRovingTabindex(items: HTMLElement[], activeIndex: number): void;
+/** Applies roving tabindex to a 2D grid. Moves real DOM focus to `(row, col)`. */
+export declare function applyGridRovingTabindex(items: GridNavigationItems, row: number, col: number): void;
+/** Sets tabindex attributes on a 2D grid without stealing focus; use during initialization. */
+export declare function initGridRovingTabindex(items: GridNavigationItems, row: number, col: number): void;
+//# sourceMappingURL=roving-tabindex.d.ts.map

package/dist/types/utils/a11y/keyboard/navigation/grid-navigation.d.ts

@@ -0,0 +1,9 @@
+import type { GridNavigationConfig, KeyBindingHandler, KeyBindingOptions, FocusStrategyType } from '../types';
+export interface GridNavigationAccess {
+    root: HTMLElement | null;
+    abortController: AbortController | null;
+    register(key: string | string[], handler: KeyBindingHandler, options?: KeyBindingOptions): void;
+    onStrategyResolved(type: FocusStrategyType, prefix: string): void;
+}
+export declare function setupGridNavigation(config: GridNavigationConfig, ctrl: GridNavigationAccess): void;
+//# sourceMappingURL=grid-navigation.d.ts.map

package/dist/types/utils/a11y/keyboard/navigation/linear-navigation.d.ts

@@ -0,0 +1,13 @@
+import type { LinearNavigationConfig, KeyBindingHandler, KeyBindingOptions, FocusStrategyType } from '../types';
+export interface LinearNavigationAccess {
+    root: HTMLElement | null;
+    abortController: AbortController | null;
+    register(key: string | string[], handler: KeyBindingHandler, options?: KeyBindingOptions): void;
+    onStrategyResolved(type: FocusStrategyType, prefix: string): void;
+}
+/**
+ * Registers all key bindings for linear list navigation on the given controller.
+ * Called internally by `KeyboardController.setLinearNavigation`.
+ */
+export declare function setupLinearNavigation(config: LinearNavigationConfig, ctrl: LinearNavigationAccess): void;
+//# sourceMappingURL=linear-navigation.d.ts.map

package/dist/types/utils/a11y/keyboard/types/IKeyboardController.d.ts

@@ -0,0 +1,125 @@
+import type { KEYBOARD } from "../../../constants/index";
+import type { KeyBindingHandler, KeyBindingTrigger, KeyboardOrientation, FocusStrategyType } from './types';
+export type GridNavigationItems = Array<Array<HTMLElement | null | undefined>>;
+/**
+ * Focus management technique used during linear/grid navigation.
+ *
+ * ### `roving-tabindex` (default)
+ * Moves real DOM focus between items. Sets `tabindex="0"` on the active item
+ * and `tabindex="-1"` on the rest. Use `:focus-visible` for active styling.
+ * Ideal for: toolbars, tab lists, radio groups, button groups.
+ *
+ * ### `aria-activedescendant`
+ * The **container** keeps DOM focus at all times. Navigation updates
+ * `aria-activedescendant` on the container to point to the active item's `id`.
+ * Item `id`s are auto-generated using `idPrefix` when missing.
+ * Use `onItemActive` in `setLinearNavigation` to apply custom active styling.
+ * Ideal for: listboxes, comboboxes, grids with many rows.
+ */
+export type FocusStrategy = {
+    type: Extract<FocusStrategyType, 'roving-tabindex'>;
+} | {
+    type: Extract<FocusStrategyType, 'aria-activedescendant'>;
+    idPrefix?: string;
+};
+/**
+ * Configuration object for {@link KeyboardController.setLinearNavigation}.
+ */
+export interface LinearNavigationConfig {
+    /**
+     * Navigable items - either a CSS selector string or a function returning elements.
+     *
+     * - **String**: evaluated as `querySelectorAll` against the attached root on every keydown.
+     * - **Function**: called lazily on every keydown - safe to query the DOM each time.
+     */
+    items: string | (() => HTMLElement[]);
+    /**
+     * Which arrow keys drive navigation.
+     * - `'horizontal'`: ArrowLeft / ArrowRight
+     * - `'vertical'`:   ArrowUp / ArrowDown
+     * - `'both'`:       all four arrow keys (default)
+     */
+    orientation?: KeyboardOrientation;
+    /** Whether navigation wraps around at the boundaries. Defaults to `true`. */
+    wrap?: boolean;
+    /** Focus management technique. Defaults to `{ type: 'roving-tabindex' }`. */
+    focusStrategy?: FocusStrategy;
+    /**
+     * CSS selector evaluated against the navigable items to find the initially
+     * active one on first render. Applies to both focus strategies.
+     * Falls back to the first item (roving-tabindex) or nothing (aria-activedescendant).
+     */
+    initialActiveSelector?: string;
+    /**
+     * Called with `(nextIndex, items)` instead of the default focus behaviour.
+     * Use when navigation must also update component state.
+     */
+    onNavigate?: (nextIndex: number, items: HTMLElement[]) => void;
+    /**
+     * Called whenever an item becomes active. **Only used with `aria-activedescendant`.**
+     * `prevItem` is `null` during initialization.
+     */
+    onItemActive?: (activeItem: HTMLElement, prevItem: HTMLElement | null) => void;
+    /** Called when the user activates the focused item (Enter / Space by default). */
+    onActivate?: KeyBindingHandler;
+    /** Which keys trigger `onActivate`. Defaults to `[KEYBOARD.Enter, KEYBOARD.Space]`. */
+    activateKeys?: Array<typeof KEYBOARD.Enter | typeof KEYBOARD.Space>;
+    /**
+     * Minimum milliseconds between navigation steps when an arrow key is held.
+     * Prevents navigation from running at the full browser key-repeat rate (~50 ms).
+     * Defaults to `100` ms (~10 items/second). Set to `0` to disable throttling.
+     */
+    repeatThrottleMs?: number;
+    /** Registered for Escape. */
+    onEscape?: KeyBindingHandler;
+}
+/**
+ * Configuration object for {@link KeyboardController.setGridNavigation}.
+ */
+export interface GridNavigationConfig {
+    /**
+     * Items as a 2D array `[row][col]` or a function returning one.
+     * `null` / `undefined` cells are skipped. Re-evaluated on every keydown.
+     */
+    items: GridNavigationItems | (() => GridNavigationItems);
+    /**
+     * Whether horizontal arrow keys wrap from the last column of a row to the
+     * first column of the next row (and vice versa). Defaults to `false`.
+     */
+    wrap?: boolean;
+    /** Focus management technique. Defaults to `{ type: 'roving-tabindex' }`. */
+    focusStrategy?: FocusStrategy;
+    /**
+     * CSS selector evaluated against grid cells to find the initially active one.
+     * Falls back to the first available cell.
+     */
+    initialActiveSelector?: string;
+    /** Called with `(row, col, items)` instead of the default focus behavior. */
+    onNavigate?: (row: number, col: number, items: GridNavigationItems) => void;
+    /** Called when the user activates the focused cell (Enter / Space by default). */
+    onActivate?: KeyBindingHandler;
+    /** Which keys trigger `onActivate`. Defaults to `[KEYBOARD.Enter, KEYBOARD.Space]`. */
+    activateKeys?: Array<typeof KEYBOARD.Enter | typeof KEYBOARD.Space>;
+    /** Called on `PageUp` - e.g. navigate to the previous month in a calendar. */
+    onPageUp?: KeyBindingHandler;
+    /** Called on `PageDown` - e.g. navigate to the next month in a calendar. */
+    onPageDown?: KeyBindingHandler;
+    /** Registered for Escape. */
+    onEscape?: KeyBindingHandler;
+    /**
+     * Minimum milliseconds between navigation steps when an arrow key is held.
+     * Defaults to `100` ms (~10 cells/second). Set to `0` to disable throttling.
+     */
+    repeatThrottleMs?: number;
+}
+export interface KeyBindingOptions {
+    /** Event type(s) that trigger the handler. Defaults to `['keydown']`. */
+    triggers?: KeyBindingTrigger[];
+    /** Whether the handler fires on auto-repeated keydown events. Defaults to `false`. */
+    repeat?: boolean;
+    /** Call `event.preventDefault()` before invoking the handler. Defaults to `true`. */
+    preventDefault?: boolean;
+    /** Call `event.stopPropagation()` before invoking the handler. Defaults to `false`. */
+    stopPropagation?: boolean;
+}
+//# sourceMappingURL=IKeyboardController.d.ts.map

package/dist/types/utils/a11y/keyboard/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './IKeyboardController';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/utils/a11y/keyboard/types/types.d.ts

@@ -0,0 +1,6 @@
+import type { KEY_TRIGGERS, KEYBOARD_ORIENTATIONS, FOCUS_STRATEGY } from '../_constants';
+export type KeyBindingHandler = (event: KeyboardEvent) => void;
+export type KeyBindingTrigger = (typeof KEY_TRIGGERS)[keyof typeof KEY_TRIGGERS];
+export type KeyboardOrientation = (typeof KEYBOARD_ORIENTATIONS)[keyof typeof KEYBOARD_ORIENTATIONS];
+export type FocusStrategyType = (typeof FOCUS_STRATEGY)[keyof typeof FOCUS_STRATEGY];
+//# sourceMappingURL=types.d.ts.map