@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/a11y/focus.js

@@ -0,0 +1,282 @@
+/**
+ * Focus Management Utilities
+ *
+ * Provides focus trapping, focus restoration, and skip-link helpers
+ * for accessible modal dialogs, drawers, and navigation patterns.
+ * All DOM operations are SSR-safe.
+ *
+ * @module @pwfabric/runtime/a11y/focus
+ */
+// ============================================================
+// CONSTANTS
+// ============================================================
+/**
+ * Selector for elements that can receive focus.
+ * Covers interactive HTML elements and elements with explicit tabindex.
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable]',
+    'details > summary',
+    'audio[controls]',
+    'video[controls]',
+].join(', ');
+// ============================================================
+// FOCUS TRAP MANAGER
+// ============================================================
+/**
+ * Manages focus trapping within a container element.
+ *
+ * When activated, Tab and Shift+Tab keypresses are intercepted to
+ * keep focus cycling within the container's focusable elements.
+ * Optionally deactivates on Escape key press.
+ *
+ * Used for modal dialogs, slide-over panels, and other overlay patterns
+ * that require focus to remain within the component for accessibility.
+ */
+export class FocusTrapManager {
+    active;
+    config;
+    previousFocus;
+    boundHandleKeyDown;
+    constructor() {
+        this.active = false;
+        this.config = null;
+        this.previousFocus = null;
+        this.boundHandleKeyDown = this.handleKeyDown.bind(this);
+    }
+    /**
+     * Activate the focus trap with the given configuration.
+     *
+     * Saves the currently focused element, attaches a keydown listener,
+     * and moves focus to the initial focus target (if specified) or the
+     * first focusable element in the container.
+     *
+     * @param config - Focus trap configuration
+     */
+    activate(config) {
+        if (typeof document === 'undefined')
+            return;
+        if (!config.container)
+            return;
+        if (this.active) {
+            this.deactivate();
+        }
+        this.config = {
+            ...config,
+            returnFocus: config.returnFocus ?? true,
+            escapeDeactivates: config.escapeDeactivates ?? true,
+        };
+        this.previousFocus = document.activeElement;
+        this.active = true;
+        document.addEventListener('keydown', this.boundHandleKeyDown);
+        // Determine and apply initial focus
+        const initialTarget = this.resolveInitialFocus();
+        if (initialTarget) {
+            initialTarget.focus();
+        }
+        else {
+            // Fall back to the first focusable element
+            const focusable = this.getFocusableElements();
+            if (focusable.length > 0) {
+                focusable[0]?.focus();
+            }
+        }
+    }
+    /**
+     * Deactivate the focus trap and optionally return focus to the
+     * previously focused element.
+     */
+    deactivate() {
+        if (typeof document === 'undefined')
+            return;
+        if (!this.active)
+            return;
+        this.active = false;
+        document.removeEventListener('keydown', this.boundHandleKeyDown);
+        if (this.config?.returnFocus && this.previousFocus instanceof HTMLElement) {
+            this.previousFocus.focus();
+        }
+        this.config = null;
+        this.previousFocus = null;
+    }
+    /**
+     * Check whether the focus trap is currently active.
+     *
+     * @returns `true` if the trap is active
+     */
+    isActive() {
+        return this.active;
+    }
+    /**
+     * Dispose of the focus trap, deactivating it and cleaning up resources.
+     */
+    dispose() {
+        this.deactivate();
+    }
+    // ============================================================
+    // PRIVATE METHODS
+    // ============================================================
+    /**
+     * Resolve the initial focus target from the config.
+     * Handles both HTMLElement references and CSS selector strings.
+     */
+    resolveInitialFocus() {
+        if (!this.config?.initialFocus || !this.config.container)
+            return null;
+        if (typeof this.config.initialFocus === 'string') {
+            return this.config.container.querySelector(this.config.initialFocus);
+        }
+        return this.config.initialFocus;
+    }
+    /**
+     * Get all focusable elements within the trap container, sorted in DOM order.
+     *
+     * @returns Array of focusable HTMLElements
+     */
+    getFocusableElements() {
+        if (!this.config?.container)
+            return [];
+        const elements = this.config.container.querySelectorAll(FOCUSABLE_SELECTOR);
+        return Array.from(elements).filter((el) => {
+            // Filter out elements that are not visible
+            return el.offsetParent !== null || el.offsetWidth > 0 || el.offsetHeight > 0;
+        });
+    }
+    /**
+     * Handle keydown events to trap Tab focus and optionally deactivate on Escape.
+     */
+    handleKeyDown(event) {
+        if (!this.active || !this.config)
+            return;
+        // Handle Escape
+        if (event.key === 'Escape' && this.config.escapeDeactivates) {
+            event.preventDefault();
+            this.deactivate();
+            return;
+        }
+        // Handle Tab / Shift+Tab
+        if (event.key !== 'Tab')
+            return;
+        const focusable = this.getFocusableElements();
+        if (focusable.length === 0) {
+            event.preventDefault();
+            return;
+        }
+        const firstElement = focusable[0];
+        const lastElement = focusable[focusable.length - 1];
+        if (event.shiftKey) {
+            // Shift+Tab: wrap from first to last
+            if (document.activeElement === firstElement ||
+                !this.config.container?.contains(document.activeElement)) {
+                event.preventDefault();
+                lastElement?.focus();
+            }
+        }
+        else {
+            // Tab: wrap from last to first
+            if (document.activeElement === lastElement ||
+                !this.config.container?.contains(document.activeElement)) {
+                event.preventDefault();
+                firstElement?.focus();
+            }
+        }
+    }
+}
+// ============================================================
+// FOCUS RESTORER
+// ============================================================
+/**
+ * Manages a stack of focus positions for nested focus contexts.
+ *
+ * Useful when opening nested dialogs or panels where each level
+ * needs to save and restore the previous focus target.
+ */
+export class FocusRestorer {
+    stack;
+    constructor() {
+        this.stack = [];
+    }
+    /**
+     * Save the currently focused element onto the stack.
+     */
+    save() {
+        if (typeof document === 'undefined')
+            return;
+        const activeElement = document.activeElement;
+        if (activeElement) {
+            this.stack.push(activeElement);
+        }
+    }
+    /**
+     * Pop the most recently saved element from the stack and restore focus to it.
+     */
+    restore() {
+        if (typeof document === 'undefined')
+            return;
+        const element = this.stack.pop();
+        if (element instanceof HTMLElement) {
+            element.focus();
+        }
+    }
+}
+// ============================================================
+// SKIP LINK HELPER
+// ============================================================
+/**
+ * Create a skip-to-content link configuration.
+ *
+ * Returns the href, label, and click handler for a skip link that
+ * jumps focus to the element with the specified ID. The target element
+ * is given a `tabindex` of `-1` if it does not already have one so
+ * it can receive programmatic focus.
+ *
+ * @param targetId - The ID of the element to skip to
+ * @returns Skip link configuration object
+ */
+export function createSkipLink(targetId) {
+    return {
+        href: `#${targetId}`,
+        label: 'Skip to content',
+        handleClick: (e) => {
+            if (typeof document === 'undefined')
+                return;
+            e.preventDefault();
+            const target = document.getElementById(targetId);
+            if (target) {
+                // Ensure the element can receive focus
+                if (!target.hasAttribute('tabindex')) {
+                    target.setAttribute('tabindex', '-1');
+                }
+                target.focus();
+                target.scrollIntoView({ behavior: 'smooth' });
+            }
+        },
+    };
+}
+// ============================================================
+// FACTORY FUNCTIONS
+// ============================================================
+/**
+ * Create a new FocusTrapManager instance.
+ *
+ * @returns A new FocusTrapManager
+ */
+export function createFocusTrap() {
+    return new FocusTrapManager();
+}
+/**
+ * Create a new FocusRestorer instance.
+ *
+ * @returns A new FocusRestorer
+ */
+export function createFocusRestorer() {
+    return new FocusRestorer();
+}
+//# sourceMappingURL=focus.js.map

package/dist/a11y/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../../src/a11y/focus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Focus Management Utilities\n *\n * Provides focus trapping, focus restoration, and skip-link helpers\n * for accessible modal dialogs, drawers, and navigation patterns.\n * All DOM operations are SSR-safe.\n *\n * @module @pwfabric/runtime/a11y/focus\n */\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/** Configuration for a focus trap */\nexport interface FocusTrapConfig {\n  /** The container element to trap focus within */\n  container: HTMLElement | null\n  /** Initial element to focus, or a CSS selector to find it */\n  initialFocus?: HTMLElement | string\n  /** Whether to return focus to the previously focused element on deactivate (default true) */\n  returnFocus?: boolean\n  /** Whether pressing Escape deactivates the trap (default true) */\n  escapeDeactivates?: boolean\n}\n\n// ============================================================\n// CONSTANTS\n// ============================================================\n\n/**\n * Selector for elements that can receive focus.\n * Covers interactive HTML elements and elements with explicit tabindex.\n */\nconst FOCUSABLE_SELECTOR = [\n  'a[href]',\n  'area[href]',\n  'button:not([disabled])',\n  'input:not([disabled])',\n  'select:not([disabled])',\n  'textarea:not([disabled])',\n  '[tabindex]:not([tabindex=\"-1\"])',\n  '[contenteditable]',\n  'details > summary',\n  'audio[controls]',\n  'video[controls]',\n].join(', ')\n\n// ============================================================\n// FOCUS TRAP MANAGER\n// ============================================================\n\n/**\n * Manages focus trapping within a container element.\n *\n * When activated, Tab and Shift+Tab keypresses are intercepted to\n * keep focus cycling within the container's focusable elements.\n * Optionally deactivates on Escape key press.\n *\n * Used for modal dialogs, slide-over panels, and other overlay patterns\n * that require focus to remain within the component for accessibility.\n */\nexport class FocusTrapManager {\n  private active: boolean\n  private config: FocusTrapConfig | null\n  private previousFocus: Element | null\n  private readonly boundHandleKeyDown: (event: KeyboardEvent) => void\n\n  constructor() {\n    this.active = false\n    this.config = null\n    this.previousFocus = null\n    this.boundHandleKeyDown = this.handleKeyDown.bind(this)\n  }\n\n  /**\n   * Activate the focus trap with the given configuration.\n   *\n   * Saves the currently focused element, attaches a keydown listener,\n   * and moves focus to the initial focus target (if specified) or the\n   * first focusable element in the container.\n   *\n   * @param config - Focus trap configuration\n   */\n  activate(config: FocusTrapConfig): void {\n    if (typeof document === 'undefined') return\n    if (!config.container) return\n    if (this.active) {\n      this.deactivate()\n    }\n\n    this.config = {\n      ...config,\n      returnFocus: config.returnFocus ?? true,\n      escapeDeactivates: config.escapeDeactivates ?? true,\n    }\n    this.previousFocus = document.activeElement\n    this.active = true\n\n    document.addEventListener('keydown', this.boundHandleKeyDown)\n\n    // Determine and apply initial focus\n    const initialTarget = this.resolveInitialFocus()\n    if (initialTarget) {\n      initialTarget.focus()\n    } else {\n      // Fall back to the first focusable element\n      const focusable = this.getFocusableElements()\n      if (focusable.length > 0) {\n        focusable[0]?.focus()\n      }\n    }\n  }\n\n  /**\n   * Deactivate the focus trap and optionally return focus to the\n   * previously focused element.\n   */\n  deactivate(): void {\n    if (typeof document === 'undefined') return\n    if (!this.active) return\n\n    this.active = false\n    document.removeEventListener('keydown', this.boundHandleKeyDown)\n\n    if (this.config?.returnFocus && this.previousFocus instanceof HTMLElement) {\n      this.previousFocus.focus()\n    }\n\n    this.config = null\n    this.previousFocus = null\n  }\n\n  /**\n   * Check whether the focus trap is currently active.\n   *\n   * @returns `true` if the trap is active\n   */\n  isActive(): boolean {\n    return this.active\n  }\n\n  /**\n   * Dispose of the focus trap, deactivating it and cleaning up resources.\n   */\n  dispose(): void {\n    this.deactivate()\n  }\n\n  // ============================================================\n  // PRIVATE METHODS\n  // ============================================================\n\n  /**\n   * Resolve the initial focus target from the config.\n   * Handles both HTMLElement references and CSS selector strings.\n   */\n  private resolveInitialFocus(): HTMLElement | null {\n    if (!this.config?.initialFocus || !this.config.container) return null\n\n    if (typeof this.config.initialFocus === 'string') {\n      return this.config.container.querySelector<HTMLElement>(this.config.initialFocus)\n    }\n\n    return this.config.initialFocus\n  }\n\n  /**\n   * Get all focusable elements within the trap container, sorted in DOM order.\n   *\n   * @returns Array of focusable HTMLElements\n   */\n  private getFocusableElements(): HTMLElement[] {\n    if (!this.config?.container) return []\n\n    const elements = this.config.container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)\n    return Array.from(elements).filter((el) => {\n      // Filter out elements that are not visible\n      return el.offsetParent !== null || el.offsetWidth > 0 || el.offsetHeight > 0\n    })\n  }\n\n  /**\n   * Handle keydown events to trap Tab focus and optionally deactivate on Escape.\n   */\n  private handleKeyDown(event: KeyboardEvent): void {\n    if (!this.active || !this.config) return\n\n    // Handle Escape\n    if (event.key === 'Escape' && this.config.escapeDeactivates) {\n      event.preventDefault()\n      this.deactivate()\n      return\n    }\n\n    // Handle Tab / Shift+Tab\n    if (event.key !== 'Tab') return\n\n    const focusable = this.getFocusableElements()\n    if (focusable.length === 0) {\n      event.preventDefault()\n      return\n    }\n\n    const firstElement = focusable[0]\n    const lastElement = focusable[focusable.length - 1]\n\n    if (event.shiftKey) {\n      // Shift+Tab: wrap from first to last\n      if (\n        document.activeElement === firstElement ||\n        !this.config.container?.contains(document.activeElement)\n      ) {\n        event.preventDefault()\n        lastElement?.focus()\n      }\n    } else {\n      // Tab: wrap from last to first\n      if (\n        document.activeElement === lastElement ||\n        !this.config.container?.contains(document.activeElement)\n      ) {\n        event.preventDefault()\n        firstElement?.focus()\n      }\n    }\n  }\n}\n\n// ============================================================\n// FOCUS RESTORER\n// ============================================================\n\n/**\n * Manages a stack of focus positions for nested focus contexts.\n *\n * Useful when opening nested dialogs or panels where each level\n * needs to save and restore the previous focus target.\n */\nexport class FocusRestorer {\n  private stack: Element[]\n\n  constructor() {\n    this.stack = []\n  }\n\n  /**\n   * Save the currently focused element onto the stack.\n   */\n  save(): void {\n    if (typeof document === 'undefined') return\n\n    const activeElement = document.activeElement\n    if (activeElement) {\n      this.stack.push(activeElement)\n    }\n  }\n\n  /**\n   * Pop the most recently saved element from the stack and restore focus to it.\n   */\n  restore(): void {\n    if (typeof document === 'undefined') return\n\n    const element = this.stack.pop()\n    if (element instanceof HTMLElement) {\n      element.focus()\n    }\n  }\n}\n\n// ============================================================\n// SKIP LINK HELPER\n// ============================================================\n\n/**\n * Create a skip-to-content link configuration.\n *\n * Returns the href, label, and click handler for a skip link that\n * jumps focus to the element with the specified ID. The target element\n * is given a `tabindex` of `-1` if it does not already have one so\n * it can receive programmatic focus.\n *\n * @param targetId - The ID of the element to skip to\n * @returns Skip link configuration object\n */\nexport function createSkipLink(targetId: string): {\n  href: string\n  label: string\n  handleClick: (e: Event) => void\n} {\n  return {\n    href: `#${targetId}`,\n    label: 'Skip to content',\n    handleClick: (e: Event) => {\n      if (typeof document === 'undefined') return\n\n      e.preventDefault()\n      const target = document.getElementById(targetId)\n      if (target) {\n        // Ensure the element can receive focus\n        if (!target.hasAttribute('tabindex')) {\n          target.setAttribute('tabindex', '-1')\n        }\n        target.focus()\n        target.scrollIntoView({ behavior: 'smooth' })\n      }\n    },\n  }\n}\n\n// ============================================================\n// FACTORY FUNCTIONS\n// ============================================================\n\n/**\n * Create a new FocusTrapManager instance.\n *\n * @returns A new FocusTrapManager\n */\nexport function createFocusTrap(): FocusTrapManager {\n  return new FocusTrapManager()\n}\n\n/**\n * Create a new FocusRestorer instance.\n *\n * @returns A new FocusRestorer\n */\nexport function createFocusRestorer(): FocusRestorer {\n  return new FocusRestorer()\n}\n"]}

package/dist/a11y/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Accessibility (a11y) Module
+ *
+ * Provides runtime accessibility utilities for the PWFabric platform:
+ * - Screen reader announcements via ARIA live regions
+ * - Focus trapping, restoration, and skip links
+ * - Keyboard navigation for composite widgets
+ * - WCAG 2.0 color contrast checking
+ *
+ * All DOM operations are SSR-safe (no-op when `document` is unavailable).
+ *
+ * @module @pwfabric/runtime/a11y
+ */
+export type { AnnouncementLevel, LiveRegionConfig } from './announcer.js';
+export { LiveRegionAnnouncer, createAnnouncer } from './announcer.js';
+export type { FocusTrapConfig } from './focus.js';
+export { FocusTrapManager, FocusRestorer, createSkipLink, createFocusTrap, createFocusRestorer, } from './focus.js';
+export type { ArrowDirection, KeyboardNavConfig } from './keyboard.js';
+export { KeyboardNavigationManager, RovingTabIndex, createKeyboardNav, createRovingTabIndex, } from './keyboard.js';
+export type { ContrastResult } from './contrast.js';
+export { hexToRgb, relativeLuminance, contrastRatio, checkContrast, meetsWCAG } from './contrast.js';

package/dist/a11y/index.js

@@ -0,0 +1,18 @@
+/**
+ * Accessibility (a11y) Module
+ *
+ * Provides runtime accessibility utilities for the PWFabric platform:
+ * - Screen reader announcements via ARIA live regions
+ * - Focus trapping, restoration, and skip links
+ * - Keyboard navigation for composite widgets
+ * - WCAG 2.0 color contrast checking
+ *
+ * All DOM operations are SSR-safe (no-op when `document` is unavailable).
+ *
+ * @module @pwfabric/runtime/a11y
+ */
+export { LiveRegionAnnouncer, createAnnouncer } from './announcer.js';
+export { FocusTrapManager, FocusRestorer, createSkipLink, createFocusTrap, createFocusRestorer, } from './focus.js';
+export { KeyboardNavigationManager, RovingTabIndex, createKeyboardNav, createRovingTabIndex, } from './keyboard.js';
+export { hexToRgb, relativeLuminance, contrastRatio, checkContrast, meetsWCAG } from './contrast.js';
+//# sourceMappingURL=index.js.map

package/dist/a11y/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/a11y/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAIrE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAInB,OAAO,EACL,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AAItB,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA","sourcesContent":["/**\n * Accessibility (a11y) Module\n *\n * Provides runtime accessibility utilities for the PWFabric platform:\n * - Screen reader announcements via ARIA live regions\n * - Focus trapping, restoration, and skip links\n * - Keyboard navigation for composite widgets\n * - WCAG 2.0 color contrast checking\n *\n * All DOM operations are SSR-safe (no-op when `document` is unavailable).\n *\n * @module @pwfabric/runtime/a11y\n */\n\n// Announcer - Screen reader live region management\nexport type { AnnouncementLevel, LiveRegionConfig } from './announcer.js'\nexport { LiveRegionAnnouncer, createAnnouncer } from './announcer.js'\n\n// Focus - Focus management utilities\nexport type { FocusTrapConfig } from './focus.js'\nexport {\n  FocusTrapManager,\n  FocusRestorer,\n  createSkipLink,\n  createFocusTrap,\n  createFocusRestorer,\n} from './focus.js'\n\n// Keyboard - Keyboard navigation manager\nexport type { ArrowDirection, KeyboardNavConfig } from './keyboard.js'\nexport {\n  KeyboardNavigationManager,\n  RovingTabIndex,\n  createKeyboardNav,\n  createRovingTabIndex,\n} from './keyboard.js'\n\n// Contrast - WCAG color contrast checking\nexport type { ContrastResult } from './contrast.js'\nexport { hexToRgb, relativeLuminance, contrastRatio, checkContrast, meetsWCAG } from './contrast.js'\n"]}

package/dist/a11y/keyboard.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Keyboard Navigation Manager
+ *
+ * Provides arrow-key navigation for composite widgets (tabs, menus,
+ * listboxes) and roving tabindex management. All DOM operations are
+ * SSR-safe.
+ *
+ * @module @pwfabric/runtime/a11y/keyboard
+ */
+/** Direction(s) in which arrow key navigation operates */
+export type ArrowDirection = 'horizontal' | 'vertical' | 'both';
+/** Configuration for keyboard navigation */
+export interface KeyboardNavConfig {
+    /** Container element holding navigable items */
+    container: HTMLElement | null;
+    /** Direction of arrow key navigation */
+    direction: ArrowDirection;
+    /** Whether navigation wraps around at boundaries (default true) */
+    loop?: boolean;
+    /** CSS selector for navigable items (default '[role="option"], [role="tab"], button, a') */
+    selector?: string;
+}
+/**
+ * Manages keyboard navigation within a composite widget.
+ *
+ * Listens for arrow key events on a container and moves focus
+ * between child items matching a configurable selector. Supports
+ * horizontal, vertical, or both directional navigation with
+ * optional looping at boundaries.
+ */
+export declare class KeyboardNavigationManager {
+    private config;
+    private currentIndex;
+    private readonly boundHandleKeyDown;
+    constructor();
+    /**
+     * Activate keyboard navigation on the given container.
+     *
+     * @param config - Keyboard navigation configuration
+     */
+    activate(config: KeyboardNavConfig): void;
+    /**
+     * Deactivate keyboard navigation and remove event listeners.
+     */
+    deactivate(): void;
+    /**
+     * Move focus to the next item in the navigation order.
+     */
+    focusNext(): void;
+    /**
+     * Move focus to the previous item in the navigation order.
+     */
+    focusPrevious(): void;
+    /**
+     * Move focus to the first item.
+     */
+    focusFirst(): void;
+    /**
+     * Move focus to the last item.
+     */
+    focusLast(): void;
+    /**
+     * Get the current focused item index.
+     *
+     * @returns The zero-based index of the currently focused item
+     */
+    getCurrentIndex(): number;
+    /**
+     * Dispose of the keyboard navigation manager, removing all listeners.
+     */
+    dispose(): void;
+    /**
+     * Handle keydown events for arrow key navigation and Home/End support.
+     */
+    private handleKeyDown;
+    /**
+     * Query navigable items from the container, filtered to visible elements.
+     *
+     * @returns Array of focusable HTMLElements within the container
+     */
+    private getItems;
+}
+/**
+ * Manages roving tabindex for composite widgets.
+ *
+ * In the roving tabindex pattern, only one item within a group
+ * has `tabindex="0"` (making it tabbable), while all other items
+ * have `tabindex="-1"`. This allows the group to participate in
+ * the page tab order as a single stop, with arrow keys used to
+ * navigate between items within the group.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
+ */
+export declare class RovingTabIndex {
+    private container;
+    private selector;
+    /**
+     * @param selector - CSS selector for items managed by roving tabindex
+     */
+    constructor(selector?: string);
+    /**
+     * Attach roving tabindex management to a container.
+     *
+     * Sets `tabindex="-1"` on all matching items except the first,
+     * which gets `tabindex="0"`.
+     *
+     * @param container - The container element
+     */
+    attach(container: HTMLElement): void;
+    /**
+     * Detach roving tabindex management, restoring all items to `tabindex="0"`.
+     */
+    detach(): void;
+    /**
+     * Set a specific element as the active (tabbable) item.
+     *
+     * The target receives `tabindex="0"` and all sibling items
+     * receive `tabindex="-1"`.
+     *
+     * @param element - The element to make active
+     */
+    setActive(element: HTMLElement): void;
+    /**
+     * Dispose of the roving tabindex manager.
+     */
+    dispose(): void;
+    /**
+     * Query managed items from the container.
+     */
+    private getItems;
+}
+/**
+ * Create a new KeyboardNavigationManager instance.
+ *
+ * @returns A new KeyboardNavigationManager
+ */
+export declare function createKeyboardNav(): KeyboardNavigationManager;
+/**
+ * Create a new RovingTabIndex instance.
+ *
+ * @param selector - CSS selector for managed items
+ * @returns A new RovingTabIndex
+ */
+export declare function createRovingTabIndex(selector?: string): RovingTabIndex;