@bquery/bquery 1.6.0 → 1.7.0

package/src/a11y/audit.ts

@@ -0,0 +1,314 @@
+/**
+ * Development-time accessibility audit utility.
+ *
+ * Scans DOM elements for common accessibility issues such as missing
+ * alt text on images, missing labels on form inputs, empty links/buttons,
+ * and incorrect ARIA usage.
+ *
+ * @module bquery/a11y
+ */
+
+import type { AuditFinding, AuditResult, AuditSeverity } from './types';
+
+/**
+ * Creates a finding object.
+ * @internal
+ */
+const finding = (
+  severity: AuditSeverity,
+  message: string,
+  element: Element,
+  rule: string
+): AuditFinding => ({
+  severity,
+  message,
+  element,
+  rule,
+});
+
+/**
+ * Checks images for missing alt attributes.
+ * @internal
+ */
+const auditImages = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+  const images = container.querySelectorAll('img');
+
+  for (const img of images) {
+    if (!img.hasAttribute('alt')) {
+      findings.push(
+        finding(
+          'error',
+          'Image is missing an alt attribute. Add alt="" for decorative images or a descriptive alt text.',
+          img,
+          'img-alt'
+        )
+      );
+    } else if (img.getAttribute('alt') === '' && !img.hasAttribute('role')) {
+      findings.push(
+        finding(
+          'info',
+          'Image has empty alt text. Consider adding role="presentation" if decorative.',
+          img,
+          'img-decorative'
+        )
+      );
+    }
+  }
+
+  return findings;
+};
+
+/**
+ * Checks form inputs for missing labels.
+ * @internal
+ */
+const auditFormInputs = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+  const inputs = container.querySelectorAll('input, select, textarea');
+
+  for (const input of inputs) {
+    const type = input.getAttribute('type');
+
+    // Hidden, submit, and button inputs don't need labels
+    if (type === 'hidden' || type === 'submit' || type === 'button' || type === 'reset') {
+      continue;
+    }
+
+    const id = input.getAttribute('id');
+    const hasLabel = id ? !!container.querySelector(`label[for="${id}"]`) : false;
+    const hasAriaLabel = input.hasAttribute('aria-label') || input.hasAttribute('aria-labelledby');
+    const hasTitle = input.hasAttribute('title');
+    const isWrappedInLabel = input.closest('label') !== null;
+
+    if (!hasLabel && !hasAriaLabel && !hasTitle && !isWrappedInLabel) {
+      findings.push(
+        finding(
+          'error',
+          `Form input is missing a label. Add a <label for="id">, aria-label, or aria-labelledby attribute.`,
+          input,
+          'input-label'
+        )
+      );
+    }
+  }
+
+  return findings;
+};
+
+/**
+ * Checks for empty interactive elements (buttons, links).
+ * @internal
+ */
+const auditInteractiveElements = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+
+  // Check buttons
+  const buttons = container.querySelectorAll('button');
+  for (const btn of buttons) {
+    const hasText = (btn.textContent ?? '').trim().length > 0;
+    const hasAriaLabel = btn.hasAttribute('aria-label') || btn.hasAttribute('aria-labelledby');
+    const hasTitle = btn.hasAttribute('title');
+
+    if (!hasText && !hasAriaLabel && !hasTitle) {
+      findings.push(
+        finding(
+          'error',
+          'Button has no accessible name. Add text content, aria-label, or title.',
+          btn,
+          'button-name'
+        )
+      );
+    }
+  }
+
+  // Check links
+  const links = container.querySelectorAll('a[href]');
+  for (const link of links) {
+    const hasText = (link.textContent ?? '').trim().length > 0;
+    const hasAriaLabel = link.hasAttribute('aria-label') || link.hasAttribute('aria-labelledby');
+    const hasTitle = link.hasAttribute('title');
+    const hasImage = link.querySelector('img[alt]') !== null;
+
+    if (!hasText && !hasAriaLabel && !hasTitle && !hasImage) {
+      findings.push(
+        finding(
+          'error',
+          'Link has no accessible name. Add text content, aria-label, or title.',
+          link,
+          'link-name'
+        )
+      );
+    }
+  }
+
+  return findings;
+};
+
+/**
+ * Checks heading hierarchy for skipped levels.
+ * @internal
+ */
+const auditHeadings = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+  const headings = container.querySelectorAll('h1, h2, h3, h4, h5, h6');
+
+  let previousLevel = 0;
+
+  for (const heading of headings) {
+    const level = parseInt(heading.tagName.charAt(1), 10);
+
+    if (previousLevel > 0 && level > previousLevel + 1) {
+      findings.push(
+        finding(
+          'warning',
+          `Heading level skipped: <${heading.tagName.toLowerCase()}> follows <h${previousLevel}>. Don't skip heading levels.`,
+          heading,
+          'heading-order'
+        )
+      );
+    }
+
+    if ((heading.textContent ?? '').trim().length === 0) {
+      findings.push(finding('warning', 'Heading element is empty.', heading, 'heading-empty'));
+    }
+
+    previousLevel = level;
+  }
+
+  return findings;
+};
+
+/**
+ * Checks for valid ARIA attribute usage.
+ * @internal
+ */
+const auditAria = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+
+  // Check aria-labelledby references exist
+  const labelled = container.querySelectorAll('[aria-labelledby]');
+  for (const el of labelled) {
+    const ids = (el.getAttribute('aria-labelledby') ?? '').split(/\s+/);
+    for (const id of ids) {
+      if (id && !document.getElementById(id)) {
+        findings.push(
+          finding(
+            'error',
+            `aria-labelledby references "${id}" which does not exist in the document.`,
+            el,
+            'aria-labelledby-ref'
+          )
+        );
+      }
+    }
+  }
+
+  // Check aria-describedby references exist
+  const described = container.querySelectorAll('[aria-describedby]');
+  for (const el of described) {
+    const ids = (el.getAttribute('aria-describedby') ?? '').split(/\s+/);
+    for (const id of ids) {
+      if (id && !document.getElementById(id)) {
+        findings.push(
+          finding(
+            'error',
+            `aria-describedby references "${id}" which does not exist in the document.`,
+            el,
+            'aria-describedby-ref'
+          )
+        );
+      }
+    }
+  }
+
+  return findings;
+};
+
+/**
+ * Checks for sufficient document landmarks.
+ * @internal
+ */
+const auditLandmarks = (container: Element): AuditFinding[] => {
+  const findings: AuditFinding[] = [];
+
+  // Only audit the document body or top-level container
+  if (container === document.body || container === document.documentElement) {
+    const hasMain = !!container.querySelector('main') || !!container.querySelector('[role="main"]');
+
+    if (!hasMain) {
+      findings.push(
+        finding(
+          'warning',
+          'Page is missing a <main> landmark. Add <main> or role="main" to the primary content area.',
+          container,
+          'landmark-main'
+        )
+      );
+    }
+  }
+
+  return findings;
+};
+
+/**
+ * Runs a development-time accessibility audit on a container element.
+ *
+ * Checks for common accessibility issues including:
+ * - Missing alt text on images
+ * - Missing labels on form inputs
+ * - Empty buttons and links
+ * - Heading hierarchy issues
+ * - Invalid ARIA references
+ * - Missing document landmarks
+ *
+ * This is intended as a development tool — not a replacement for
+ * manual testing or professional accessibility audits.
+ *
+ * @param container - The element to audit (defaults to `document.body`)
+ * @returns An audit result with findings, counts, and pass/fail status
+ *
+ * @example
+ * ```ts
+ * import { auditA11y } from '@bquery/bquery/a11y';
+ *
+ * const result = auditA11y();
+ * if (!result.passed) {
+ *   console.warn(`Found ${result.errors} accessibility errors:`);
+ *   for (const f of result.findings) {
+ *     console.warn(`[${f.severity}] ${f.message}`, f.element);
+ *   }
+ * }
+ * ```
+ */
+export const auditA11y = (container?: Element): AuditResult => {
+  if (typeof document === 'undefined' || !document.body) {
+    return {
+      findings: [],
+      errors: 0,
+      warnings: 0,
+      passed: true,
+    };
+  }
+
+  const target = container ?? document.body;
+
+  const allFindings: AuditFinding[] = [
+    ...auditImages(target),
+    ...auditFormInputs(target),
+    ...auditInteractiveElements(target),
+    ...auditHeadings(target),
+    ...auditAria(target),
+    ...auditLandmarks(target),
+  ];
+
+  const errors = allFindings.filter((f) => f.severity === 'error').length;
+  const warnings = allFindings.filter((f) => f.severity === 'warning').length;
+
+  return {
+    findings: allFindings,
+    errors,
+    warnings,
+    passed: errors === 0,
+  };
+};

package/src/a11y/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Accessibility (a11y) utilities module for bQuery.js.
+ *
+ * Provides essential accessibility helpers for building inclusive
+ * web applications: focus trapping, screen reader announcements,
+ * keyboard navigation patterns, skip navigation, media preference
+ * signals, and development-time auditing.
+ *
+ * @module bquery/a11y
+ *
+ * @example
+ * ```ts
+ * import {
+ *   trapFocus,
+ *   announceToScreenReader,
+ *   rovingTabIndex,
+ *   skipLink,
+ *   prefersReducedMotion,
+ *   prefersColorScheme,
+ *   auditA11y,
+ * } from '@bquery/bquery/a11y';
+ *
+ * // Trap focus in a modal
+ * const trap = trapFocus(dialogElement);
+ *
+ * // Announce changes to screen readers
+ * announceToScreenReader('Form submitted successfully');
+ *
+ * // Arrow key navigation in a toolbar
+ * const roving = rovingTabIndex(toolbar, 'button', {
+ *   orientation: 'horizontal',
+ * });
+ *
+ * // Auto-generate skip navigation
+ * const skip = skipLink('#main-content');
+ *
+ * // Reactive media preferences
+ * const reduced = prefersReducedMotion();
+ * const scheme = prefersColorScheme();
+ *
+ * // Development-time audit
+ * const result = auditA11y();
+ * if (!result.passed) console.warn(result.findings);
+ * ```
+ */
+
+export { announceToScreenReader, clearAnnouncements } from './announce';
+export { auditA11y } from './audit';
+export { prefersColorScheme, prefersContrast, prefersReducedMotion } from './media-preferences';
+export { rovingTabIndex } from './roving-tab-index';
+export { skipLink } from './skip-link';
+export { getFocusableElements, releaseFocus, trapFocus } from './trap-focus';
+
+export type {
+  AnnouncePriority,
+  AuditFinding,
+  AuditResult,
+  AuditSeverity,
+  ColorScheme,
+  ContrastPreference,
+  FocusTrapHandle,
+  MediaPreferenceSignal,
+  RovingTabIndexHandle,
+  RovingTabIndexOptions,
+  SkipLinkHandle,
+  SkipLinkOptions,
+  TrapFocusOptions,
+} from './types';

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