@bquery/bquery 1.5.0 → 1.7.0

package/src/a11y/media-preferences.ts

@@ -0,0 +1,255 @@
+/**
+ * Reactive media preference signals for accessibility.
+ *
+ * Provides reactive signals that track the user's system-level
+ * accessibility preferences (reduced motion, color scheme, contrast).
+ *
+ * @module bquery/a11y
+ */
+
+import { readonly, signal, type ReadonlySignal } from '../reactive/index';
+import type { ColorScheme, ContrastPreference, MediaPreferenceSignal } from './types';
+
+type LegacyMediaQueryList = MediaQueryList & {
+  addListener?: (listener: (event: MediaQueryListEvent | MediaQueryList) => void) => void;
+  removeListener?: (listener: (event: MediaQueryListEvent | MediaQueryList) => void) => void;
+};
+
+const bindMediaQueryListener = (
+  mql: MediaQueryList,
+  handler: (event: MediaQueryListEvent | MediaQueryList) => void
+): (() => void) | undefined => {
+  if (typeof mql.addEventListener === 'function') {
+    mql.addEventListener('change', handler);
+    return (): void => {
+      mql.removeEventListener('change', handler);
+    };
+  }
+
+  const legacyMql = mql as LegacyMediaQueryList;
+  if (typeof legacyMql.addListener === 'function') {
+    legacyMql.addListener(handler);
+    return (): void => {
+      legacyMql.removeListener?.(handler);
+    };
+  }
+
+  return undefined;
+};
+
+const withDestroy = <T>(
+  signalHandle: ReadonlySignal<T>,
+  cleanup: () => void
+): MediaPreferenceSignal<T> => {
+  let destroyImpl = cleanup;
+  const handle = signalHandle as MediaPreferenceSignal<T>;
+  Object.defineProperty(handle, 'destroy', {
+    configurable: true,
+    enumerable: false,
+    value: (): void => {
+      const currentDestroy = destroyImpl;
+      // Make cleanup idempotent so repeated destroy() calls from user code stay safe.
+      destroyImpl = (): void => {};
+      currentDestroy();
+    },
+  });
+  return handle;
+};
+
+/**
+ * Creates a reactive signal that tracks a CSS media query.
+ *
+ * @param query - The media query string
+ * @param initialValue - Fallback value when `matchMedia` is unavailable
+ * @returns A readonly signal handle that updates when the query match changes
+ * @internal
+ */
+const createMediaSignal = (
+  query: string,
+  initialValue: boolean
+): MediaPreferenceSignal<boolean> => {
+  const s = signal(initialValue);
+  let destroy = (): void => {
+    s.dispose();
+  };
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    try {
+      const mql = window.matchMedia(query);
+      s.value = mql.matches;
+
+      const handler = (e: MediaQueryListEvent | MediaQueryList): void => {
+        s.value = e.matches;
+      };
+
+      const cleanupMql = bindMediaQueryListener(mql, handler);
+      if (cleanupMql) {
+        destroy = (): void => {
+          cleanupMql();
+          s.dispose();
+        };
+      }
+    } catch {
+      // matchMedia may throw in non-browser environments
+    }
+  }
+
+  return withDestroy(readonly(s), destroy);
+};
+
+/**
+ * Returns a reactive signal indicating whether the user prefers reduced motion.
+ *
+ * Tracks the `(prefers-reduced-motion: reduce)` media query. Returns `true`
+ * when the user has requested reduced motion in their system settings.
+ *
+ * @returns A readonly reactive signal handle. Call `destroy()` to remove listeners.
+ *
+ * @example
+ * ```ts
+ * import { prefersReducedMotion } from '@bquery/bquery/a11y';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const reduced = prefersReducedMotion();
+ * effect(() => {
+ *   if (reduced.value) {
+ *     console.log('User prefers reduced motion');
+ *   }
+ * });
+ * ```
+ */
+export const prefersReducedMotion = (): MediaPreferenceSignal<boolean> => {
+  return createMediaSignal('(prefers-reduced-motion: reduce)', false);
+};
+
+/**
+ * Returns a reactive signal tracking the user's preferred color scheme.
+ *
+ * Tracks the `(prefers-color-scheme: dark)` media query. Returns `'dark'`
+ * when the user prefers a dark color scheme, `'light'` otherwise.
+ *
+ * @returns A readonly reactive signal handle with `'light'` or `'dark'`
+ *
+ * @example
+ * ```ts
+ * import { prefersColorScheme } from '@bquery/bquery/a11y';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const scheme = prefersColorScheme();
+ * effect(() => {
+ *   document.body.dataset.theme = scheme.value;
+ * });
+ * ```
+ */
+export const prefersColorScheme = (): MediaPreferenceSignal<ColorScheme> => {
+  const s = signal<ColorScheme>('light');
+  let destroy = (): void => {
+    s.dispose();
+  };
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    try {
+      const mql = window.matchMedia('(prefers-color-scheme: dark)');
+      s.value = mql.matches ? 'dark' : 'light';
+
+      const handler = (e: MediaQueryListEvent | MediaQueryList): void => {
+        s.value = e.matches ? 'dark' : 'light';
+      };
+
+      const cleanupMql = bindMediaQueryListener(mql, handler);
+      if (cleanupMql) {
+        destroy = (): void => {
+          cleanupMql();
+          s.dispose();
+        };
+      }
+    } catch {
+      // matchMedia may throw in non-browser environments
+    }
+  }
+
+  return withDestroy(readonly(s), destroy);
+};
+
+/**
+ * Returns a reactive signal tracking the user's contrast preference.
+ *
+ * Tracks the `(prefers-contrast)` media query. Returns:
+ * - `'more'` — user prefers higher contrast
+ * - `'less'` — user prefers lower contrast
+ * - `'custom'` — user has set a custom contrast level
+ * - `'no-preference'` — no explicit preference
+ *
+ * @returns A readonly reactive signal handle
+ *
+ * @example
+ * ```ts
+ * import { prefersContrast } from '@bquery/bquery/a11y';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const contrast = prefersContrast();
+ * effect(() => {
+ *   if (contrast.value === 'more') {
+ *     document.body.classList.add('high-contrast');
+ *   }
+ * });
+ * ```
+ */
+export const prefersContrast = (): MediaPreferenceSignal<ContrastPreference> => {
+  const s = signal<ContrastPreference>('no-preference');
+  let destroy = (): void => {
+    s.dispose();
+  };
+
+  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
+    let mql: MediaQueryList | undefined;
+    let mqlLess: MediaQueryList | undefined;
+    let mqlCustom: MediaQueryList | undefined;
+
+    const update = (): void => {
+      // Defensive guard for environments where matchMedia setup fails before
+      // listeners are attached; update() is only expected to run after init.
+      if (!mql || !mqlLess || !mqlCustom) {
+        return;
+      }
+
+      if (mql.matches) {
+        s.value = 'more';
+      } else if (mqlLess.matches) {
+        s.value = 'less';
+      } else if (mqlCustom.matches) {
+        s.value = 'custom';
+      } else {
+        s.value = 'no-preference';
+      }
+    };
+
+    // Listen for changes on the contrast preference variants
+    try {
+      mql = window.matchMedia('(prefers-contrast: more)');
+      mqlLess = window.matchMedia('(prefers-contrast: less)');
+      mqlCustom = window.matchMedia('(prefers-contrast: custom)');
+      update();
+      const cleanupFns = [mql, mqlLess, mqlCustom]
+        .map((entry) =>
+          bindMediaQueryListener(entry, () => {
+            update();
+          })
+        )
+        .filter((cleanup): cleanup is () => void => cleanup !== undefined);
+
+      if (cleanupFns.length > 0) {
+        destroy = (): void => {
+          for (const cleanup of cleanupFns) {
+            cleanup();
+          }
+          s.dispose();
+        };
+      }
+    } catch {
+      // matchMedia may throw in non-browser environments
+    }
+  }
+
+  return withDestroy(readonly(s), destroy);
+};

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,
+  };
+};