@bquery/bquery 1.6.0 → 1.7.0

package/src/a11y/roving-tab-index.ts

@@ -0,0 +1,164 @@
+/**
+ * Roving tab index utility for arrow-key navigation within groups.
+ *
+ * Implements the WAI-ARIA roving tabindex pattern: only one item
+ * in the group has tabindex="0" (the active item), while all others
+ * have tabindex="-1". Arrow keys move focus between items.
+ *
+ * @module bquery/a11y
+ */
+
+import type { RovingTabIndexHandle, RovingTabIndexOptions } from './types';
+
+/**
+ * Sets up roving tab index navigation for a group of elements.
+ *
+ * Only the active item receives `tabindex="0"`, making it the only
+ * tabbable element in the group. Arrow keys move focus between items,
+ * and Home/End jump to the first/last item.
+ *
+ * @param container - The parent element containing the navigable items
+ * @param itemSelector - CSS selector for the navigable items within the container
+ * @param options - Configuration options
+ * @returns A handle with `destroy()`, `focusItem()`, and `activeIndex()`
+ *
+ * @example
+ * ```ts
+ * import { rovingTabIndex } from '@bquery/bquery/a11y';
+ *
+ * const toolbar = document.querySelector('[role="toolbar"]');
+ * const handle = rovingTabIndex(toolbar, 'button', {
+ *   orientation: 'horizontal',
+ *   wrap: true,
+ * });
+ *
+ * // Later, clean up
+ * handle.destroy();
+ * ```
+ */
+export const rovingTabIndex = (
+  container: HTMLElement,
+  itemSelector: string,
+  options: RovingTabIndexOptions = {}
+): RovingTabIndexHandle => {
+  const { wrap = true, orientation = 'vertical', onActivate } = options;
+
+  let currentIndex = 0;
+  const originalTabIndexes = new Map<HTMLElement, string | null>();
+
+  const getItems = (): HTMLElement[] => {
+    return Array.from(container.querySelectorAll(itemSelector)) as HTMLElement[];
+  };
+
+  const trackItems = (items: HTMLElement[]): void => {
+    for (const item of items) {
+      if (!originalTabIndexes.has(item)) {
+        originalTabIndexes.set(item, item.getAttribute('tabindex'));
+      }
+    }
+  };
+
+  const setActiveItem = (index: number): void => {
+    const items = getItems();
+    if (items.length === 0) return;
+    trackItems(items);
+
+    // Clamp index
+    const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
+
+    // Update tabindex on all items
+    for (let i = 0; i < items.length; i++) {
+      items[i].setAttribute('tabindex', i === clampedIndex ? '0' : '-1');
+    }
+
+    currentIndex = clampedIndex;
+    items[clampedIndex].focus();
+    onActivate?.(items[clampedIndex], clampedIndex);
+  };
+
+  const isRelevantKey = (key: string): boolean => {
+    if (key === 'Home' || key === 'End') return true;
+
+    switch (orientation) {
+      case 'horizontal':
+        return key === 'ArrowLeft' || key === 'ArrowRight';
+      case 'vertical':
+        return key === 'ArrowUp' || key === 'ArrowDown';
+      case 'both':
+        return (
+          key === 'ArrowLeft' || key === 'ArrowRight' || key === 'ArrowUp' || key === 'ArrowDown'
+        );
+      default:
+        return false;
+    }
+  };
+
+  const handleKeyDown = (event: KeyboardEvent): void => {
+    if (!isRelevantKey(event.key)) return;
+
+    const items = getItems();
+    if (items.length === 0) return;
+
+    event.preventDefault();
+
+    let nextIndex = currentIndex;
+
+    switch (event.key) {
+      case 'ArrowDown':
+      case 'ArrowRight':
+        nextIndex = currentIndex + 1;
+        if (nextIndex >= items.length) {
+          nextIndex = wrap ? 0 : items.length - 1;
+        }
+        break;
+
+      case 'ArrowUp':
+      case 'ArrowLeft':
+        nextIndex = currentIndex - 1;
+        if (nextIndex < 0) {
+          nextIndex = wrap ? items.length - 1 : 0;
+        }
+        break;
+
+      case 'Home':
+        nextIndex = 0;
+        break;
+
+      case 'End':
+        nextIndex = items.length - 1;
+        break;
+    }
+
+    setActiveItem(nextIndex);
+  };
+
+  // Initialize: set tabindex on all items
+  const items = getItems();
+  trackItems(items);
+  for (let i = 0; i < items.length; i++) {
+    items[i].setAttribute('tabindex', i === 0 ? '0' : '-1');
+  }
+
+  container.addEventListener('keydown', handleKeyDown);
+
+  return {
+    destroy: () => {
+      container.removeEventListener('keydown', handleKeyDown);
+      // Restore original tabindex values
+      for (const [item, originalTabIndex] of originalTabIndexes) {
+        if (originalTabIndex === null) {
+          item.removeAttribute('tabindex');
+        } else {
+          item.setAttribute('tabindex', originalTabIndex);
+        }
+      }
+      originalTabIndexes.clear();
+    },
+
+    focusItem: (index: number) => {
+      setActiveItem(index);
+    },
+
+    activeIndex: () => currentIndex,
+  };
+};

package/src/a11y/skip-link.ts

@@ -0,0 +1,255 @@
+/**
+ * Auto-generated skip navigation link utility.
+ *
+ * Creates a visually-hidden (but keyboard-focusable) "Skip to content"
+ * link that becomes visible on focus, letting keyboard users bypass
+ * repeated navigation.
+ *
+ * @module bquery/a11y
+ */
+
+import type { SkipLinkHandle, SkipLinkOptions } from './types';
+
+/** Default CSS for the skip link — visually hidden until focused. */
+const DEFAULT_STYLES = `
+  position: absolute;
+  top: -9999px;
+  left: -9999px;
+  z-index: 999999;
+  padding: 0.5em 1em;
+  background: #000;
+  color: #fff;
+  font-size: 1rem;
+  text-decoration: none;
+  border-radius: 0 0 4px 0;
+  outline: 2px solid #4A90D9;
+  outline-offset: 2px;
+`;
+
+const FOCUSED_STYLES = `
+  top: 0;
+  left: 0;
+`;
+
+let skipTargetIdCounter = 0;
+const generatedSkipTargetRefs = new Map<string, { count: number; target: HTMLElement }>();
+
+const hasSkipLinkEnvironment = (): boolean => {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  return (
+    typeof document.createElement === 'function' &&
+    typeof document.querySelector === 'function' &&
+    typeof document.getElementById === 'function' &&
+    document.body !== null &&
+    document.body !== undefined
+  );
+};
+
+const createNoopSkipLinkHandle = (): SkipLinkHandle => ({
+  destroy: () => {},
+  element: null,
+});
+
+/**
+ * Creates a skip navigation link that jumps to the specified target.
+ *
+ * The link is visually hidden by default and becomes visible when
+ * it receives keyboard focus. This follows the WCAG 2.4.1 "Bypass Blocks"
+ * success criterion.
+ *
+ * @param targetSelector - CSS selector for the main content area (e.g. `'#main'`, `'main'`)
+ * @param options - Configuration options
+ * @returns A handle with `destroy()` method and reference to the created element
+ *
+ * @example
+ * ```ts
+ * import { skipLink } from '@bquery/bquery/a11y';
+ *
+ * // Creates a "Skip to main content" link pointing to <main>
+ * const handle = skipLink('#main-content');
+ *
+ * // Custom text
+ * const handle2 = skipLink('#content', { text: 'Jump to content' });
+ *
+ * // Remove when no longer needed
+ * handle.destroy();
+ * ```
+ */
+export const skipLink = (targetSelector: string, options: SkipLinkOptions = {}): SkipLinkHandle => {
+  if (!hasSkipLinkEnvironment()) {
+    return createNoopSkipLinkHandle();
+  }
+
+  const { text = 'Skip to main content', className = 'bq-skip-link' } = options;
+  let trackedGeneratedTargetId: string | undefined;
+  let trackedFocusTarget:
+    | { target: HTMLElement; hadTabIndex: boolean; previousTabIndex: string | null }
+    | undefined;
+  const safeQuerySelector = (selector: string): HTMLElement | null => {
+    try {
+      return document.querySelector(selector) as HTMLElement | null;
+    } catch {
+      return null;
+    }
+  };
+  const releaseTrackedGeneratedTargetId = (): void => {
+    if (!trackedGeneratedTargetId) return;
+
+    const entry = generatedSkipTargetRefs.get(trackedGeneratedTargetId);
+    const remainingRefs = (entry?.count ?? 0) - 1;
+    if (remainingRefs <= 0) {
+      generatedSkipTargetRefs.delete(trackedGeneratedTargetId);
+      if (entry?.target.isConnected && entry.target.id === trackedGeneratedTargetId) {
+        entry.target.removeAttribute('id');
+      }
+    } else {
+      generatedSkipTargetRefs.set(trackedGeneratedTargetId, {
+        count: remainingRefs,
+        target: entry!.target,
+      });
+    }
+
+    trackedGeneratedTargetId = undefined;
+  };
+  const restoreTrackedFocusTarget = (): void => {
+    if (!trackedFocusTarget) return;
+
+    const { target, hadTabIndex, previousTabIndex } = trackedFocusTarget;
+    if (target.isConnected) {
+      if (hadTabIndex) {
+        target.setAttribute('tabindex', previousTabIndex ?? '');
+      } else {
+        target.removeAttribute('tabindex');
+      }
+    }
+
+    trackedFocusTarget = undefined;
+  };
+  const ensureTargetFocusable = (target: HTMLElement): void => {
+    if (trackedFocusTarget?.target === target) {
+      return;
+    }
+
+    restoreTrackedFocusTarget();
+
+    if (target.hasAttribute('tabindex')) {
+      trackedFocusTarget = {
+        target,
+        hadTabIndex: true,
+        previousTabIndex: target.getAttribute('tabindex'),
+      };
+      return;
+    }
+
+    if (target.tabIndex !== -1) {
+      return;
+    }
+
+    trackedFocusTarget = {
+      target,
+      hadTabIndex: false,
+      previousTabIndex: null,
+    };
+    target.setAttribute('tabindex', '-1');
+  };
+  const trackGeneratedTargetId = (target: HTMLElement, id: string): void => {
+    if (trackedGeneratedTargetId === id) return;
+    releaseTrackedGeneratedTargetId();
+    const entry = generatedSkipTargetRefs.get(id);
+    generatedSkipTargetRefs.set(id, {
+      count: (entry?.count ?? 0) + 1,
+      target,
+    });
+    trackedGeneratedTargetId = id;
+  };
+  const resolveTarget = (): HTMLElement | null => {
+    if (targetSelector.startsWith('#')) {
+      const id = targetSelector.slice(1);
+      const byId = id ? (document.getElementById(id) as HTMLElement | null) : null;
+      if (byId) {
+        return byId;
+      }
+
+      return safeQuerySelector(targetSelector);
+    }
+
+    const byId = document.getElementById(targetSelector) as HTMLElement | null;
+    if (byId) {
+      return byId;
+    }
+
+    return safeQuerySelector(targetSelector);
+  };
+
+  const ensureTargetId = (target: HTMLElement): string => {
+    if (target.id) {
+      const generatedTarget = generatedSkipTargetRefs.get(target.id);
+      if (generatedTarget?.target === target) {
+        trackGeneratedTargetId(target, target.id);
+      }
+      return target.id;
+    }
+
+    let generatedTargetId: string;
+    do {
+      skipTargetIdCounter += 1;
+      generatedTargetId = `bq-skip-target-${skipTargetIdCounter}`;
+    } while (document.getElementById(generatedTargetId) !== null);
+
+    target.id = generatedTargetId;
+    trackGeneratedTargetId(target, generatedTargetId);
+    return generatedTargetId;
+  };
+
+  const link = document.createElement('a');
+  const initialTarget = resolveTarget();
+  link.href = targetSelector.startsWith('#')
+    ? targetSelector
+    : initialTarget
+      ? `#${ensureTargetId(initialTarget)}`
+      : `#${targetSelector}`;
+  link.textContent = text;
+  link.className = className;
+  link.setAttribute('style', DEFAULT_STYLES);
+
+  link.addEventListener('focus', () => {
+    link.setAttribute('style', DEFAULT_STYLES + FOCUSED_STYLES);
+  });
+
+  link.addEventListener('blur', () => {
+    link.setAttribute('style', DEFAULT_STYLES);
+  });
+
+  link.addEventListener('click', (e) => {
+    e.preventDefault();
+
+    const target = resolveTarget();
+    if (!target) {
+      return;
+    }
+
+    link.href = `#${ensureTargetId(target)}`;
+    // Make the target focusable if it isn't already
+    ensureTargetFocusable(target);
+    target.focus();
+  });
+
+  // Insert as the first child of <body>
+  if (document.body.firstChild) {
+    document.body.insertBefore(link, document.body.firstChild);
+  } else {
+    document.body.appendChild(link);
+  }
+
+  return {
+    destroy: () => {
+      restoreTrackedFocusTarget();
+      releaseTrackedGeneratedTargetId();
+      link.remove();
+    },
+    element: link,
+  };
+};

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();
+};