@bquery/bquery 1.6.0 → 1.8.1

package/dist/untrack-D0fnO5k2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrack-D0fnO5k2.js","names":[],"sources":["../src/reactive/computed.ts","../src/reactive/untrack.ts"],"sourcesContent":["/**\n * Computed reactive values.\n */\n\nimport {\n  clearDependencies,\n  getCurrentObserver,\n  registerDependency,\n  scheduleObserver,\n  track,\n  withoutCurrentObserver,\n  type ReactiveSource,\n} from './internals';\nimport { getActiveScope, hasScopeDisposer } from './scope';\n\n/**\n * A computed value that derives from other reactive sources.\n *\n * Computed values are lazily evaluated and cached. They only\n * recompute when their dependencies change.\n *\n * @template T - The type of the computed value\n */\nexport class Computed<T> implements ReactiveSource {\n  private cachedValue!: T;\n  private hasCachedValue = false;\n  private dirty = true;\n  private disposed = false;\n  private subscribers = new Set<() => void>();\n  private readonly markDirty = () => {\n    if (this.disposed) {\n      return;\n    }\n    this.dirty = true;\n    // Create snapshot to avoid issues with subscribers modifying the set during iteration\n    const subscribersSnapshot = Array.from(this.subscribers);\n    for (const subscriber of subscribersSnapshot) {\n      scheduleObserver(subscriber);\n    }\n  };\n\n  /**\n   * Creates a new computed value.\n   * @param compute - Function that computes the value\n   */\n  constructor(private readonly compute: () => T) {}\n\n  /**\n   * Gets the computed value, recomputing if dependencies changed.\n   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.\n   */\n  get value(): T {\n    if (this.disposed) {\n      if (!this.hasCachedValue) {\n        this.cachedValue = withoutCurrentObserver(() => this.compute());\n        this.hasCachedValue = true;\n      }\n      return this.cachedValue;\n    }\n\n    const current = getCurrentObserver();\n    if (current) {\n      this.subscribers.add(current);\n      registerDependency(current, this);\n    }\n    if (this.dirty) {\n      this.dirty = false;\n      // Clear old dependencies before recomputing\n      clearDependencies(this.markDirty);\n      this.cachedValue = track(this.markDirty, this.compute);\n      this.hasCachedValue = true;\n    }\n    return this.cachedValue;\n  }\n\n  /**\n   * Reads the current computed value without tracking.\n   * Useful when you need the value but don't want to create a dependency.\n   *\n   * @returns The current cached value (recomputes if dirty)\n   */\n  peek(): T {\n    if (this.disposed) {\n      if (!this.hasCachedValue) {\n        this.cachedValue = withoutCurrentObserver(() => this.compute());\n        this.hasCachedValue = true;\n      }\n      return this.cachedValue;\n    }\n\n    if (this.dirty) {\n      this.dirty = false;\n      // Clear old dependencies before recomputing\n      clearDependencies(this.markDirty);\n      this.cachedValue = track(this.markDirty, this.compute);\n      this.hasCachedValue = true;\n    }\n    return this.cachedValue;\n  }\n\n  /**\n   * Removes an observer from this computed's subscriber set.\n   * @internal\n   */\n  unsubscribe(observer: () => void): void {\n    this.subscribers.delete(observer);\n  }\n\n  /**\n   * Disposes the computed value by unsubscribing its internal observer\n   * from all upstream dependencies and clearing subscribers.\n   */\n  dispose(): void {\n    this.disposed = true;\n    if (this.dirty) {\n      this.hasCachedValue = false;\n    }\n    this.dirty = false;\n    clearDependencies(this.markDirty);\n    this.subscribers.clear();\n  }\n}\n\n/**\n * Creates a new computed value.\n *\n * If created inside an {@link effectScope}, the computed value is automatically\n * collected and will be disposed when the scope stops.\n *\n * @template T - The type of the computed value\n * @param fn - Function that computes the value from reactive sources\n * @returns A new Computed instance\n */\nexport const computed = <T>(fn: () => T): Computed<T> => {\n  const c = new Computed(fn);\n\n  // Auto-register with the current scope so scope.stop() disposes this computed\n  const scope = getActiveScope();\n  if (hasScopeDisposer(scope)) {\n    scope._addDisposer(() => c.dispose());\n  }\n\n  return c;\n};\n","/**\n * Dependency tracking control helpers.\n */\n\nimport { withoutCurrentObserver } from './internals';\n\n/**\n * Executes a function without tracking any signal dependencies.\n * Useful when reading a signal value without creating a reactive dependency.\n *\n * This implementation temporarily hides the current observer rather than\n * disabling tracking globally. This ensures that nested reactive internals\n * (e.g., computed recomputation triggered during untrack) can still properly\n * track their own dependencies.\n *\n * @template T - The return type of the function\n * @param fn - The function to execute without tracking\n * @returns The result of the function\n *\n * @example\n * ```ts\n * const count = signal(0);\n * effect(() => {\n *   // This read creates a dependency\n *   console.log(count.value);\n *   // This read does not create a dependency\n *   const snapshot = untrack(() => count.value);\n * });\n * ```\n */\nexport const untrack = <T>(fn: () => T): T => withoutCurrentObserver(fn);\n"],"mappings":";AAuBA,IAAa,IAAb,MAAmD;AAAA,EAsBjD,YAAY,GAAmC;AAAlB,SAAA,UAAA,yBApBJ,iBACT,oBACG,uBACG,oBAAI,IAAA,0BACS;AACjC,UAAI,KAAK,SACP;AAEF,WAAK,QAAQ;AAEb,YAAM,IAAsB,MAAM,KAAK,KAAK,WAAA;AAC5C,iBAAW,KAAc,EACvB,CAAA,EAAiB,CAAA;AAAA;;EAcrB,IAAI,QAAW;AACb,QAAI,KAAK;AACP,aAAK,KAAK,mBACR,KAAK,cAAc,EAAA,MAA6B,KAAK,QAAA,CAAS,GAC9D,KAAK,iBAAiB,KAEjB,KAAK;AAGd,UAAM,IAAU,EAAA;AAChB,WAAI,MACF,KAAK,YAAY,IAAI,CAAA,GACrB,EAAmB,GAAS,IAAA,IAE1B,KAAK,UACP,KAAK,QAAQ,IAEb,EAAkB,KAAK,SAAA,GACvB,KAAK,cAAc,EAAM,KAAK,WAAW,KAAK,OAAA,GAC9C,KAAK,iBAAiB,KAEjB,KAAK;AAAA;EASd,OAAU;AACR,WAAI,KAAK,YACF,KAAK,mBACR,KAAK,cAAc,EAAA,MAA6B,KAAK,QAAA,CAAS,GAC9D,KAAK,iBAAiB,KAEjB,KAAK,gBAGV,KAAK,UACP,KAAK,QAAQ,IAEb,EAAkB,KAAK,SAAA,GACvB,KAAK,cAAc,EAAM,KAAK,WAAW,KAAK,OAAA,GAC9C,KAAK,iBAAiB,KAEjB,KAAK;AAAA;EAOd,YAAY,GAA4B;AACtC,SAAK,YAAY,OAAO,CAAA;AAAA;EAO1B,UAAgB;AACd,SAAK,WAAW,IACZ,KAAK,UACP,KAAK,iBAAiB,KAExB,KAAK,QAAQ,IACb,EAAkB,KAAK,SAAA,GACvB,KAAK,YAAY,MAAA;AAAA;GAcR,IAAA,CAAe,MAA6B;AACvD,QAAM,IAAI,IAAI,EAAS,CAAA,GAGjB,IAAQ,EAAA;AACd,SAAI,EAAiB,CAAA,KACnB,EAAM,aAAA,MAAmB,EAAE,QAAA,CAAS,GAG/B;GChHI,IAAA,CAAc,MAAmB,EAAuB,CAAA"}

package/dist/view/custom-directives.d.ts

@@ -0,0 +1,20 @@
+import type { DirectiveHandler } from './types';
+/**
+ * Function signature used to resolve custom directives without coupling the
+ * view pipeline directly to the plugin module.
+ * @internal
+ */
+export type CustomDirectiveResolver = (name: string) => DirectiveHandler | undefined;
+/**
+ * Registers the resolver used by the view pipeline for custom directives.
+ *
+ * Pass `null` to unregister the current resolver and reset to the default behavior.
+ * @internal
+ */
+export declare const registerCustomDirectiveResolver: (resolver: CustomDirectiveResolver | null) => void;
+/**
+ * Returns a custom directive handler when one is registered.
+ * @internal
+ */
+export declare const getCustomDirective: (name: string) => DirectiveHandler | undefined;
+//# sourceMappingURL=custom-directives.d.ts.map

package/dist/view/custom-directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-directives.d.ts","sourceRoot":"","sources":["../../src/view/custom-directives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;AAIrF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,UAAU,uBAAuB,GAAG,IAAI,KAAG,IAE1F,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,gBAAgB,GAAG,SAEpE,CAAC"}

package/dist/view/evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/view/evaluate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA4D9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAO,IAGvC,CAAC;AA8BF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,GAAG,OAAO,EAAE,YAAY,MAAM,EAAE,SAAS,cAAc,KAAG,CAoBnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,EAAE,YAAY,MAAM,EAAE,SAAS,cAAc,KAAG,CAiBtF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,YAAY,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAqH/E,CAAC"}
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/view/evaluate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA4D9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAO,IAGvC,CAAC;AA8BF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,GAAG,OAAO,EAAE,YAAY,MAAM,EAAE,SAAS,cAAc,KAAG,CAoBnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,OAAO,EAAE,YAAY,MAAM,EAAE,SAAS,cAAc,KAAG,CAiBtF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,YAAY,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAsH/E,CAAC"}

package/dist/view/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/view/process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,gBAAgB,CAAC;IACrB,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,GAAG,EAAE,gBAAgB,CAAC;IACtB,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAC7C,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,IAAI,OAAO,EACX,SAAS,cAAc,EACvB,QAAQ,MAAM,EACd,UAAU,SAAS,EAAE,EACrB,UAAU,iBAAiB,KAC1B,IAyCF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,OAAO,EACX,SAAS,cAAc,EACvB,QAAQ,MAAM,EACd,UAAU,SAAS,EAAE,EACrB,UAAU,iBAAiB,KAC1B,IAWF,CAAC"}
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/view/process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,gBAAgB,CAAC;IACrB,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,gBAAgB,CAAC;IACxB,GAAG,EAAE,gBAAgB,CAAC;IACtB,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,gBAAgB,CAAC;IAC7C,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,IAAI,OAAO,EACX,SAAS,cAAc,EACvB,QAAQ,MAAM,EACd,UAAU,SAAS,EAAE,EACrB,UAAU,iBAAiB,KAC1B,IAuDF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,OAAO,EACX,SAAS,cAAc,EACvB,QAAQ,MAAM,EACd,UAAU,SAAS,EAAE,EACrB,UAAU,iBAAiB,KAC1B,IAWF,CAAC"}

package/dist/view.es.mjs

@@ -1,13 +1,13 @@
-import { t as r } from "./effect-AFRW_Plg.js";
-import { d as o, f as e } from "./reactive-DSkct0dO.js";
-import { n as s } from "./core-BGQJVw0-.js";
-import { n as f, r as c, t as i } from "./view-C70lA3vf.js";
+import { n as a, r as o } from "./core-DdtZHzsS.js";
+import { D as e } from "./reactive-DwkhUJfP.js";
+import { r as s } from "./untrack-D0fnO5k2.js";
+import { n as c, r as f, t as i } from "./mount-B4Y8bk8Z.js";
 export {
   e as batch,
-  c as clearExpressionCache,
-  o as computed,
+  f as clearExpressionCache,
+  s as computed,
   i as createTemplate,
-  r as effect,
-  f as mount,
-  s as signal
+  o as effect,
+  c as mount,
+  a as signal
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bquery/bquery",
-  "version": "1.6.0",
+  "version": "1.8.1",
   "description": "The jQuery for the Modern Web Platform - Zero build, TypeScript-first library with reactivity, components, and motion",
   "type": "module",
   "main": "./dist/full.umd.js",
@@ -58,6 +58,42 @@
     "./storybook": {
       "import": "./dist/storybook.es.mjs",
       "types": "./dist/storybook/index.d.ts"
+    },
+    "./forms": {
+      "import": "./dist/forms.es.mjs",
+      "types": "./dist/forms/index.d.ts"
+    },
+    "./i18n": {
+      "import": "./dist/i18n.es.mjs",
+      "types": "./dist/i18n/index.d.ts"
+    },
+    "./a11y": {
+      "import": "./dist/a11y.es.mjs",
+      "types": "./dist/a11y/index.d.ts"
+    },
+    "./dnd": {
+      "import": "./dist/dnd.es.mjs",
+      "types": "./dist/dnd/index.d.ts"
+    },
+    "./media": {
+      "import": "./dist/media.es.mjs",
+      "types": "./dist/media/index.d.ts"
+    },
+    "./plugin": {
+      "import": "./dist/plugin.es.mjs",
+      "types": "./dist/plugin/index.d.ts"
+    },
+    "./devtools": {
+      "import": "./dist/devtools.es.mjs",
+      "types": "./dist/devtools/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.es.mjs",
+      "types": "./dist/testing/index.d.ts"
+    },
+    "./ssr": {
+      "import": "./dist/ssr.es.mjs",
+      "types": "./dist/ssr/index.d.ts"
     }
   },
   "files": [
@@ -121,21 +157,21 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^10.2.19",
-    "@storybook/web-components-vite": "^10.2.19",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
-    "bun-types": "^1.3.10",
-    "eslint": "^10.0.3",
+    "@storybook/addon-docs": "^10.3.3",
+    "@storybook/web-components-vite": "^10.3.3",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "bun-types": "^1.3.11",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.4.0",
-    "happy-dom": "^20.8.4",
+    "happy-dom": "^20.8.9",
     "prettier": "^3.8.1",
     "rimraf": "^6.1.3",
-    "storybook": "^10.2.19",
-    "typedoc": "^0.28.17",
+    "storybook": "^10.3.3",
+    "typedoc": "^0.28.18",
     "typescript": "^5.9.3",
-    "vite": "^8.0.0",
+    "vite": "^8.0.3",
     "vitepress": "^1.6.4"
   }
 }

package/src/a11y/announce.ts

@@ -0,0 +1,131 @@
+/**
+ * Screen reader announcement utility using ARIA live regions.
+ *
+ * Creates and manages off-screen live regions to announce dynamic
+ * content changes to assistive technologies.
+ *
+ * @module bquery/a11y
+ */
+
+import type { AnnouncePriority } from './types';
+
+/** Cache for live region containers, keyed by priority. */
+const liveRegions = new Map<AnnouncePriority, HTMLElement>();
+const pendingAnnouncements = new Map<AnnouncePriority, ReturnType<typeof setTimeout>>();
+
+/**
+ * Delay in milliseconds before updating the live region text.
+ * This ensures screen readers detect the content change even when
+ * the same message is announced consecutively — clearing first and
+ * setting after a short timer delay forces a new live-region mutation event.
+ * @internal
+ */
+const ANNOUNCEMENT_DELAY_MS = 50;
+
+/**
+ * Gets or creates a visually-hidden ARIA live region for the given priority.
+ *
+ * @param priority - The aria-live priority level
+ * @returns The live region element
+ * @internal
+ */
+const getOrCreateLiveRegion = (priority: AnnouncePriority): HTMLElement => {
+  const existing = liveRegions.get(priority);
+  if (existing && existing.isConnected) {
+    return existing;
+  }
+
+  const el = document.createElement('div');
+  el.setAttribute('aria-live', priority);
+  el.setAttribute('aria-atomic', 'true');
+  el.setAttribute('role', priority === 'assertive' ? 'alert' : 'status');
+
+  // Visually hidden but accessible to screen readers
+  Object.assign(el.style, {
+    position: 'absolute',
+    width: '1px',
+    height: '1px',
+    padding: '0',
+    margin: '-1px',
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    whiteSpace: 'nowrap',
+    border: '0',
+  });
+
+  document.body.appendChild(el);
+  liveRegions.set(priority, el);
+
+  return el;
+};
+
+/**
+ * Announces a message to screen readers via an ARIA live region.
+ *
+ * The message is injected into a visually-hidden live region element.
+ * Screen readers will pick up the change and announce it to the user.
+ *
+ * @param message - The text message to announce
+ * @param priority - The urgency level: `'polite'` (default) or `'assertive'`
+ *
+ * @example
+ * ```ts
+ * import { announceToScreenReader } from '@bquery/bquery/a11y';
+ *
+ * // Polite announcement (waits for idle)
+ * announceToScreenReader('3 search results found');
+ *
+ * // Assertive announcement (interrupts current speech)
+ * announceToScreenReader('Error: Please fix the form', 'assertive');
+ * ```
+ */
+export const announceToScreenReader = (
+  message: string,
+  priority: AnnouncePriority = 'polite'
+): void => {
+  if (!message) return;
+  if (typeof document === 'undefined' || !document.body) return;
+
+  const region = getOrCreateLiveRegion(priority);
+  const pendingTimeout = pendingAnnouncements.get(priority);
+  if (pendingTimeout !== undefined) {
+    clearTimeout(pendingTimeout);
+  }
+
+  // Clear first, then set after a short timer delay to ensure screen readers
+  // detect the change even if the same message is announced twice.
+  region.textContent = '';
+
+  // Use setTimeout to ensure the DOM update triggers a live region change event
+  const timeout = setTimeout(() => {
+    pendingAnnouncements.delete(priority);
+    if (region.isConnected) {
+      region.textContent = message;
+    }
+  }, ANNOUNCEMENT_DELAY_MS);
+
+  pendingAnnouncements.set(priority, timeout);
+};
+
+/**
+ * Removes all live region elements created by `announceToScreenReader`.
+ * Useful for cleanup in tests or when unmounting an application.
+ *
+ * @example
+ * ```ts
+ * import { clearAnnouncements } from '@bquery/bquery/a11y';
+ *
+ * clearAnnouncements();
+ * ```
+ */
+export const clearAnnouncements = (): void => {
+  for (const timeout of pendingAnnouncements.values()) {
+    clearTimeout(timeout);
+  }
+  pendingAnnouncements.clear();
+
+  for (const [, el] of liveRegions) {
+    el.remove();
+  }
+  liveRegions.clear();
+};

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';