@bquery/bquery 1.6.0 → 1.8.1

package/src/a11y/trap-focus.ts

@@ -0,0 +1,184 @@
+/**
+ * Focus trapping utility for modals, dialogs, and popover content.
+ *
+ * Constrains keyboard focus within a container so that Tab and Shift+Tab
+ * cycle only through the container's focusable elements.
+ *
+ * @module bquery/a11y
+ */
+
+import type { FocusTrapHandle, TrapFocusOptions } from './types';
+
+/** Selector for elements that can receive focus. */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable="true"]',
+  'details > summary',
+  'audio[controls]',
+  'video[controls]',
+].join(', ');
+
+/**
+ * Gets all focusable elements within a container.
+ *
+ * @param container - The container element
+ * @returns Array of focusable elements
+ * @internal
+ */
+export const getFocusableElements = (container: Element): HTMLElement[] => {
+  const elements = Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)) as HTMLElement[];
+  return elements.filter(
+    (el) => !el.hasAttribute('disabled') && el.tabIndex !== -1 && el.getClientRects().length > 0
+  );
+};
+
+/**
+ * Resolves an element from a string selector or returns the element directly.
+ * @internal
+ */
+const resolveElement = (
+  target: HTMLElement | string | undefined,
+  container: Element
+): HTMLElement | null => {
+  if (!target) return null;
+  if (typeof target === 'string') {
+    return container.querySelector(target) as HTMLElement | null;
+  }
+  return target;
+};
+
+/**
+ * Traps keyboard focus within a container element.
+ *
+ * When activated, Tab and Shift+Tab will cycle only through focusable
+ * elements within the container. Useful for modals, dialogs, and
+ * dropdown menus.
+ *
+ * @param container - The DOM element to trap focus within
+ * @param options - Configuration options
+ * @returns A handle with a `release()` method to deactivate the trap
+ *
+ * @example
+ * ```ts
+ * import { trapFocus } from '@bquery/bquery/a11y';
+ *
+ * const dialog = document.querySelector('#my-dialog');
+ * const trap = trapFocus(dialog, { escapeDeactivates: true });
+ *
+ * // Later, release the trap
+ * trap.release();
+ * ```
+ */
+export const trapFocus = (
+  container: HTMLElement,
+  options: TrapFocusOptions = {}
+): FocusTrapHandle => {
+  const { escapeDeactivates = true, onEscape, initialFocus, returnFocus } = options;
+
+  if (
+    typeof document === 'undefined' ||
+    typeof document.addEventListener !== 'function' ||
+    typeof document.removeEventListener !== 'function'
+  ) {
+    let active = false;
+    return {
+      get active() {
+        return active;
+      },
+      release: () => {
+        active = false;
+      },
+    };
+  }
+
+  const previouslyFocused = document.activeElement as HTMLElement | null;
+  let active = true;
+
+  const handleKeyDown = (event: KeyboardEvent): void => {
+    if (!active) return;
+
+    if (event.key === 'Escape' && escapeDeactivates) {
+      event.preventDefault();
+      handle.release();
+      onEscape?.();
+      return;
+    }
+
+    if (event.key !== 'Tab') return;
+
+    const focusable = getFocusableElements(container);
+    if (focusable.length === 0) {
+      event.preventDefault();
+      return;
+    }
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+
+    if (event.shiftKey) {
+      // Shift+Tab: if at first element, wrap to last
+      if (document.activeElement === first || !container.contains(document.activeElement)) {
+        event.preventDefault();
+        last.focus();
+      }
+    } else {
+      // Tab: if at last element, wrap to first
+      if (document.activeElement === last || !container.contains(document.activeElement)) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+  };
+
+  // Attach the event listener
+  document.addEventListener('keydown', handleKeyDown, true);
+
+  // Set initial focus
+  const initialEl = resolveElement(initialFocus, container);
+  if (initialEl) {
+    initialEl.focus();
+  } else {
+    const focusable = getFocusableElements(container);
+    if (focusable.length > 0) {
+      focusable[0].focus();
+    }
+  }
+
+  const handle: FocusTrapHandle = {
+    get active() {
+      return active;
+    },
+
+    release: () => {
+      if (!active) return;
+      active = false;
+      document.removeEventListener('keydown', handleKeyDown, true);
+
+      // Return focus
+      const returnEl = resolveElement(returnFocus, document.body);
+      if (returnEl) {
+        returnEl.focus();
+      } else if (previouslyFocused && previouslyFocused.focus) {
+        previouslyFocused.focus();
+      }
+    },
+  };
+
+  return handle;
+};
+
+/**
+ * Releases a focus trap handle.
+ * This is a convenience function — in most cases, use the `release()`
+ * method on the individual trap handle directly.
+ *
+ * @deprecated Prefer using the handle returned by `trapFocus()` directly.
+ */
+export const releaseFocus = (handle: FocusTrapHandle): void => {
+  handle.release();
+};

package/src/a11y/types.ts

@@ -0,0 +1,183 @@
+/**
+ * Type definitions for the bQuery accessibility (a11y) module.
+ *
+ * @module bquery/a11y
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+// ─── Focus Trap ──────────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring focus trapping behavior.
+ */
+export interface TrapFocusOptions {
+  /**
+   * Element to receive initial focus when the trap activates.
+   * If not provided, the first focusable element is focused.
+   */
+  initialFocus?: HTMLElement | string;
+
+  /**
+   * Element to receive focus when the trap is released.
+   * If not provided, focus returns to the element that was focused
+   * before the trap was activated.
+   */
+  returnFocus?: HTMLElement | string;
+
+  /**
+   * Whether pressing Escape releases the focus trap.
+   * @default true
+   */
+  escapeDeactivates?: boolean;
+
+  /**
+   * Callback invoked when the trap is deactivated via Escape.
+   */
+  onEscape?: () => void;
+}
+
+/**
+ * Handle returned by `trapFocus()` for managing the focus trap lifecycle.
+ */
+export interface FocusTrapHandle {
+  /** Release the focus trap, restoring focus to the previous element. */
+  release: () => void;
+  /** Whether the trap is currently active. */
+  active: boolean;
+}
+
+// ─── Screen Reader Announcements ─────────────────────────────────────────────
+
+/**
+ * Priority level for screen reader announcements.
+ * - `'polite'` — announced when the user is idle (default)
+ * - `'assertive'` — announced immediately, interrupting current speech
+ */
+export type AnnouncePriority = 'polite' | 'assertive';
+
+// ─── Roving Tab Index ────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring roving tab index behavior.
+ */
+export interface RovingTabIndexOptions {
+  /**
+   * Whether navigation wraps around from last to first (and vice versa).
+   * @default true
+   */
+  wrap?: boolean;
+
+  /**
+   * Orientation of the group — determines which arrow keys are used.
+   * - `'horizontal'` — Left/Right arrows
+   * - `'vertical'` — Up/Down arrows
+   * - `'both'` — All arrow keys
+   * @default 'vertical'
+   */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+
+  /**
+   * Callback fired when the active item changes.
+   */
+  onActivate?: (element: Element, index: number) => void;
+}
+
+/**
+ * Handle returned by `rovingTabIndex()` for cleanup.
+ */
+export interface RovingTabIndexHandle {
+  /** Remove event listeners and restore original tabindex values. */
+  destroy: () => void;
+  /** Programmatically focus a specific item by index. */
+  focusItem: (index: number) => void;
+  /** Get the currently active index. */
+  activeIndex: () => number;
+}
+
+// ─── Skip Link ───────────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring auto-generated skip navigation.
+ */
+export interface SkipLinkOptions {
+  /**
+   * Text content of the skip link.
+   * @default 'Skip to main content'
+   */
+  text?: string;
+
+  /**
+   * CSS class applied to the skip link element.
+   * @default 'bq-skip-link'
+   */
+  className?: string;
+}
+
+/**
+ * Handle returned by `skipLink()` for cleanup.
+ */
+export interface SkipLinkHandle {
+  /** Remove the skip link from the DOM. */
+  destroy: () => void;
+  /**
+   * The created skip link element, or `null` when `skipLink()` is called in a
+   * non-DOM environment and returns a no-op handle.
+   */
+  element: HTMLAnchorElement | null;
+}
+
+// ─── Media Preferences ───────────────────────────────────────────────────────
+
+/**
+ * Color scheme preference value.
+ */
+export type ColorScheme = 'light' | 'dark';
+
+/**
+ * Contrast preference value.
+ */
+export type ContrastPreference = 'no-preference' | 'more' | 'less' | 'custom';
+
+/**
+ * Readonly media preference signal with an explicit cleanup hook.
+ */
+export interface MediaPreferenceSignal<T> extends ReadonlySignal<T> {
+  /** Releases underlying media-query listeners. Safe to call multiple times. */
+  destroy(): void;
+}
+
+// ─── Accessibility Audit ─────────────────────────────────────────────────────
+
+/**
+ * Severity level for audit findings.
+ */
+export type AuditSeverity = 'error' | 'warning' | 'info';
+
+/**
+ * A single accessibility audit finding.
+ */
+export interface AuditFinding {
+  /** Severity level of the finding. */
+  severity: AuditSeverity;
+  /** Human-readable description of the issue. */
+  message: string;
+  /** The DOM element with the issue. */
+  element: Element;
+  /** The audit rule that triggered this finding. */
+  rule: string;
+}
+
+/**
+ * Result of an accessibility audit.
+ */
+export interface AuditResult {
+  /** All findings from the audit. */
+  findings: AuditFinding[];
+  /** Number of errors found. */
+  errors: number;
+  /** Number of warnings found. */
+  warnings: number;
+  /** Whether the audit passed (no errors). */
+  passed: boolean;
+}