@bquery/bquery 1.5.0 → 1.7.0

package/README.md

@@ -20,7 +20,7 @@
 
 **The jQuery for the modern Web Platform.**
 
-bQuery.js is a slim, TypeScript-first library that combines jQuery's direct DOM workflow with modern features like reactivity, async data composables, Web Components, motion utilities, routing, stores, and declarative views — without a mandatory build step.
+bQuery.js is a slim, TypeScript-first library that combines jQuery's direct DOM workflow with modern features like reactivity, async data composables, Web Components, motion utilities, routing, stores, declarative views, accessibility helpers, forms, i18n, media signals, drag-and-drop, plugins, devtools, testing utilities, and SSR — without a mandatory build step.
 
 ## Highlights
 
@@ -30,7 +30,7 @@ bQuery.js is a slim, TypeScript-first library that combines jQuery's direct DOM
 - **Modular**: the core stays small; extra modules are opt-in.
 - **TypeScript-first**: clear types and strong IDE support.
 - **Tree-shakeable**: import only what you need.
-- **Storybook-ready**: default components can be previewed and developed in Storybook.
+- **Storybook-ready**: default components can be previewed and developed in Storybook with dedicated story template helpers.
 
 ## Installation
 
@@ -112,6 +112,7 @@ import {
 
 // Components only
 import {
+  bool,
   component,
   defineComponent,
   html,
@@ -122,7 +123,7 @@ import {
 import { transition, spring, animate, timeline } from '@bquery/bquery/motion';
 
 // Security only
-import { sanitize } from '@bquery/bquery/security';
+import { sanitize, sanitizeHtml, trusted } from '@bquery/bquery/security';
 
 // Platform only
 import { storage, cache, useCookie, definePageMeta, useAnnouncer } from '@bquery/bquery/platform';
@@ -131,21 +132,49 @@ import { storage, cache, useCookie, definePageMeta, useAnnouncer } from '@bquery
 import { createRouter, navigate } from '@bquery/bquery/router';
 import { createStore, defineStore } from '@bquery/bquery/store';
 import { mount, createTemplate } from '@bquery/bquery/view';
+
+// Forms, i18n, accessibility, drag & drop, media
+import { createForm, required, email } from '@bquery/bquery/forms';
+import { createI18n } from '@bquery/bquery/i18n';
+import { trapFocus, rovingTabIndex } from '@bquery/bquery/a11y';
+import { draggable, droppable, sortable } from '@bquery/bquery/dnd';
+import { mediaQuery, useViewport, clipboard } from '@bquery/bquery/media';
+
+// Plugins, devtools, testing, SSR
+import { use } from '@bquery/bquery/plugin';
+import { enableDevtools, inspectSignals } from '@bquery/bquery/devtools';
+import { renderComponent, fireEvent, waitFor } from '@bquery/bquery/testing';
+import { renderToString, hydrateMount, serializeStoreState } from '@bquery/bquery/ssr';
+
+// Storybook helpers
+import { storyHtml, when } from '@bquery/bquery/storybook';
 ```
 
 ## Modules at a glance
 
-| Module        | Description                                        | Size (gzip) |
-| ------------- | -------------------------------------------------- | ----------- |
-| **Core**      | Selectors, DOM manipulation, events, utilities     | ~11.3 KB    |
-| **Reactive**  | `signal`, `computed`, `effect`, async data/fetch   | ~0.3 KB     |
-| **Component** | Lightweight Web Components with props + defaults   | ~1.9 KB     |
-| **Motion**    | View transitions, FLIP, timelines, scroll, springs | ~4.0 KB     |
-| **Security**  | HTML sanitizing, Trusted Types, CSP                | ~0.7 KB     |
-| **Platform**  | Storage, cache, cookies, meta, announcers, config  | ~2.2 KB     |
-| **Router**    | SPA routing, navigation guards, history API        | ~2.2 KB     |
-| **Store**     | Signal-based state management, persistence         | ~0.3 KB     |
-| **View**      | Declarative DOM bindings, directives               | ~4.3 KB     |
+| Module        | Description                                                                           |
+| ------------- | ------------------------------------------------------------------------------------- |
+| **Core**      | Selectors, DOM manipulation, events, traversal, and typed utilities                   |
+| **Reactive**  | `signal`, `computed`, `effect`, batching, async data, and fetch composables           |
+| **Component** | Typed Web Components with scoped reactivity and configurable Shadow DOM               |
+| **Storybook** | Safe story template helpers with boolean-attribute shorthand                          |
+| **Motion**    | View transitions, FLIP, morphing, parallax, typewriter, springs, and timelines        |
+| **Security**  | HTML sanitization, Trusted Types, CSP helpers, and trusted fragment composition       |
+| **Platform**  | Storage, cache, cookies, page metadata, announcers, and shared runtime config         |
+| **Router**    | SPA routing, constrained params, redirects, guards, `useRoute()`, and `<bq-link>`     |
+| **Store**     | Signal-based state management, persistence, migrations, and action hooks              |
+| **View**      | Declarative DOM bindings, directives, and plugin-provided custom directives           |
+| **Forms**     | Reactive form state with sync/async validation and submit handling                    |
+| **i18n**      | Reactive locales, interpolation, pluralization, lazy loading, and Intl formatting     |
+| **A11y**      | Focus traps, live-region announcements, roving tabindex, skip links, and audits       |
+| **DnD**       | Draggable elements, droppable zones, and sortable lists                               |
+| **Media**     | Reactive browser/device signals for viewport, network, battery, geolocation, and more |
+| **Plugin**    | Global plugin registration for custom directives and Web Components                   |
+| **Devtools**  | Runtime inspection helpers for signals, stores, components, and timelines             |
+| **Testing**   | Component mounting, mock signals/router helpers, and async test utilities             |
+| **SSR**       | Server-side rendering, hydration, and store-state serialization                       |
+
+Storybook authoring helpers are also available as a dedicated entry point via `@bquery/bquery/storybook`.
 
 ## Quick examples
 
@@ -247,45 +276,76 @@ console.log(user.pending.value, user.data.value, settings.error.value);
 
 ```ts
 import {
+  bool,
   component,
   defineComponent,
   html,
   registerDefaultComponents,
+  safeHtml,
 } from '@bquery/bquery/component';
+import { sanitizeHtml, trusted } from '@bquery/bquery/security';
+
+const badge = trusted(sanitizeHtml('<span class="badge">Active</span>'));
 
 component('user-card', {
   props: {
     username: { type: String, required: true },
     age: { type: Number, validator: (v) => v >= 0 && v <= 150 },
   },
+  state: { count: 0 },
   beforeMount() {
     console.log('About to mount');
   },
   connected() {
     console.log('Mounted');
   },
-  beforeUpdate(props) {
-    return props.username !== '';
+  beforeUpdate(newProps, oldProps) {
+    return newProps.username !== oldProps.username;
+  },
+  updated(change) {
+    console.log('Updated because of', change?.name ?? 'state/signal change');
   },
   onError(error) {
     console.error('Component error:', error);
   },
-  render({ props }) {
-    return html`<div>Hello ${props.username}</div>`;
+  render({ props, state }) {
+    return safeHtml`
+      <button class="user-card" ${bool('disabled', state.count > 3)}>
+        ${badge}
+        <span>Hello ${props.username}</span>
+      </button>
+    `;
   },
 });
 
-const UserCard = defineComponent('user-card', {
+const UserCard = defineComponent('user-card-manual', {
   props: { username: { type: String, required: true } },
   render: ({ props }) => html`<div>Hello ${props.username}</div>`,
 });
 
-customElements.define('user-card', UserCard);
+customElements.define('user-card-manual', UserCard);
 
 const tags = registerDefaultComponents({ prefix: 'ui' });
 console.log(tags.button); // ui-button
 ```
 
+### Storybook – authoring helpers
+
+```ts
+import { storyHtml, when } from '@bquery/bquery/storybook';
+
+export const Primary = {
+  args: { disabled: false, label: 'Save' },
+  render: ({ disabled, label }) =>
+    storyHtml`
+      <ui-card>
+        <ui-button ?disabled=${disabled}>${label}</ui-button>
+        ${when(!disabled, '<small>Ready to submit</small>')}
+      </ui-card>
+    `,
+};
+```
+
 ### Motion – animations
 
 ```ts
@@ -315,15 +375,18 @@ await x.to(100);
 ### Security – sanitizing
 
 ```ts
-import { sanitize, escapeHtml } from '@bquery/bquery/security';
+import { sanitize, escapeHtml, sanitizeHtml, trusted } from '@bquery/bquery/security';
+import { safeHtml } from '@bquery/bquery/component';
 
-const safeHtml = sanitize(userInput);
+const safeMarkup = sanitize(userInput);
 const safe = sanitize('<form id="cookie">...</form>');
 const urlSafe = sanitize('<a href="java\u200Bscript:alert(1)">click</a>');
 const secureLink = sanitize('<a href="https://external.com" target="_blank">Link</a>');
 const safeSrcset = sanitize('<img srcset="safe.jpg 1x, javascript:alert(1) 2x">');
 const safeForm = sanitize('<form action="javascript:alert(1)">...</form>');
 const escaped = escapeHtml('<script>alert(1)</script>');
+const icon = trusted(sanitizeHtml('<span class="icon">♥</span>'));
+const button = safeHtml`<button>${icon}<span>Save</span></button>`;
 ```
 
 ### Platform – config, cookies & accessibility
@@ -389,6 +452,93 @@ effect(() => {
 });
 ```
 
+### Forms – reactive validation
+
+```ts
+import { createForm, email, required } from '@bquery/bquery/forms';
+
+const form = createForm({
+  fields: {
+    name: { initialValue: '', validators: [required()] },
+    email: { initialValue: '', validators: [required(), email()] },
+  },
+  onSubmit: async (values) => {
+    await fetch('/api/signup', {
+      method: 'POST',
+      body: JSON.stringify(values),
+    });
+  },
+});
+
+await form.handleSubmit();
+console.log(form.isValid.value, form.fields.email.error.value);
+```
+
+### i18n – locale-aware content
+
+```ts
+import { createI18n } from '@bquery/bquery/i18n';
+
+const i18n = createI18n({
+  locale: 'en',
+  fallbackLocale: 'en',
+  messages: {
+    en: { greeting: 'Hello, {name}!' },
+    de: { greeting: 'Hallo, {name}!' },
+  },
+});
+
+console.log(i18n.t('greeting', { name: 'Ada' }));
+i18n.$locale.value = 'de';
+```
+
+### Accessibility, media, and drag & drop
+
+```ts
+import { trapFocus, announceToScreenReader } from '@bquery/bquery/a11y';
+import { mediaQuery, useViewport } from '@bquery/bquery/media';
+import { draggable } from '@bquery/bquery/dnd';
+
+const modalTrap = trapFocus(document.querySelector('#dialog')!);
+announceToScreenReader('Dialog opened');
+
+const isDark = mediaQuery('(prefers-color-scheme: dark)');
+const viewport = useViewport();
+const drag = draggable(document.querySelector('#card')!, { bounds: 'parent' });
+
+console.log(isDark.value, viewport.value.width);
+
+drag.destroy();
+modalTrap.release();
+```
+
+### Plugins, devtools, testing, and SSR
+
+```ts
+import { use } from '@bquery/bquery/plugin';
+import { enableDevtools, getTimeline } from '@bquery/bquery/devtools';
+import { renderComponent, fireEvent } from '@bquery/bquery/testing';
+import { renderToString } from '@bquery/bquery/ssr';
+
+use({
+  name: 'focus-plugin',
+  install(ctx) {
+    ctx.directive('focus', (el) => (el as HTMLElement).focus());
+  },
+});
+
+enableDevtools(true, { logToConsole: true });
+console.log(getTimeline());
+
+const mounted = renderComponent('ui-button', { props: { variant: 'primary' } });
+fireEvent(mounted.el, 'click');
+
+const { html } = renderToString('<p bq-text="label"></p>', { label: 'Hello SSR' });
+console.log(html);
+
+mounted.unmount();
+```
+
 ### Store – state management
 
 ```ts
@@ -475,6 +625,7 @@ mount('#app', {
 - **Core API**: [docs/guide/api-core.md](docs/guide/api-core.md)
 - **Agents**: [docs/guide/agents.md](docs/guide/agents.md)
 - **Components**: [docs/guide/components.md](docs/guide/components.md)
+- **Storybook**: [docs/guide/storybook.md](docs/guide/storybook.md)
 - **Reactivity**: [docs/guide/reactive.md](docs/guide/reactive.md)
 - **Motion**: [docs/guide/motion.md](docs/guide/motion.md)
 - **Security**: [docs/guide/security.md](docs/guide/security.md)
@@ -482,6 +633,15 @@ mount('#app', {
 - **Router**: [docs/guide/router.md](docs/guide/router.md)
 - **Store**: [docs/guide/store.md](docs/guide/store.md)
 - **View**: [docs/guide/view.md](docs/guide/view.md)
+- **Forms**: [docs/guide/forms.md](docs/guide/forms.md)
+- **i18n**: [docs/guide/i18n.md](docs/guide/i18n.md)
+- **Accessibility**: [docs/guide/a11y.md](docs/guide/a11y.md)
+- **Drag & Drop**: [docs/guide/dnd.md](docs/guide/dnd.md)
+- **Media**: [docs/guide/media.md](docs/guide/media.md)
+- **Plugin System**: [docs/guide/plugin.md](docs/guide/plugin.md)
+- **Devtools**: [docs/guide/devtools.md](docs/guide/devtools.md)
+- **Testing Utilities**: [docs/guide/testing.md](docs/guide/testing.md)
+- **SSR / Hydration**: [docs/guide/ssr.md](docs/guide/ssr.md)
 
 ## Local Development
 
@@ -516,12 +676,22 @@ bQuery.js
 │   ├── core/       # Selectors, DOM ops, events, utils
 │   ├── reactive/   # Signals, computed, effects, async data
 │   ├── component/  # Web Components helper + default library
+│   ├── storybook/  # Story template helpers
 │   ├── motion/     # View transitions, FLIP, springs
 │   ├── security/   # Sanitizer, CSP, Trusted Types
 │   ├── platform/   # Storage, cache, cookies, meta, config
 │   ├── router/     # SPA routing, navigation guards
 │   ├── store/      # State management, persistence
-│   └── view/       # Declarative DOM bindings
+│   ├── view/       # Declarative DOM bindings
+│   ├── forms/      # Reactive forms + validators
+│   ├── i18n/       # Internationalization + formatting
+│   ├── a11y/       # Accessibility utilities
+│   ├── dnd/        # Drag & drop helpers
+│   ├── media/      # Browser and device reactive signals
+│   ├── plugin/     # Global plugin system
+│   ├── devtools/   # Runtime inspection helpers
+│   ├── testing/    # Test utilities
+│   └── ssr/        # Server-side rendering + hydration
 ├── docs/           # VitePress documentation
 ├── .storybook/     # Storybook config
 ├── stories/        # Component stories

package/dist/a11y/announce.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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';
+/**
+ * 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 declare const announceToScreenReader: (message: string, priority?: AnnouncePriority) => void;
+/**
+ * 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 declare const clearAnnouncements: () => void;
+//# sourceMappingURL=announce.d.ts.map

package/dist/a11y/announce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../src/a11y/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAoDhD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EACf,WAAU,gBAA2B,KACpC,IAuBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,QAAO,IAUrC,CAAC"}

package/dist/a11y/audit.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { AuditResult } from './types';
+/**
+ * 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 declare const auditA11y: (container?: Element) => AuditResult;
+//# sourceMappingURL=audit.d.ts.map

package/dist/a11y/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/a11y/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAgB,WAAW,EAAiB,MAAM,SAAS,CAAC;AAmPxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,SAAS,GAAI,YAAY,OAAO,KAAG,WA8B/C,CAAC"}

package/dist/a11y/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/a11y/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/a11y/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7E,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dist/a11y/media-preferences.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 type { ColorScheme, ContrastPreference, MediaPreferenceSignal } from './types';
+/**
+ * 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 declare const prefersReducedMotion: () => MediaPreferenceSignal<boolean>;
+/**
+ * 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 declare const prefersColorScheme: () => MediaPreferenceSignal<ColorScheme>;
+/**
+ * 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 declare const prefersContrast: () => MediaPreferenceSignal<ContrastPreference>;
+//# sourceMappingURL=media-preferences.d.ts.map

package/dist/a11y/media-preferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-preferences.d.ts","sourceRoot":"","sources":["../../src/a11y/media-preferences.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAyFtF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,QAAO,qBAAqB,CAAC,OAAO,CAEpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,QAAO,qBAAqB,CAAC,WAAW,CA4BtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,QAAO,qBAAqB,CAAC,kBAAkB,CAyD1E,CAAC"}

package/dist/a11y/roving-tab-index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const rovingTabIndex: (container: HTMLElement, itemSelector: string, options?: RovingTabIndexOptions) => RovingTabIndexHandle;
+//# sourceMappingURL=roving-tab-index.d.ts.map

package/dist/a11y/roving-tab-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-tab-index.d.ts","sourceRoot":"","sources":["../../src/a11y/roving-tab-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,GACzB,WAAW,WAAW,EACtB,cAAc,MAAM,EACpB,UAAS,qBAA0B,KAClC,oBAyHF,CAAC"}

package/dist/a11y/skip-link.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+/**
+ * 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 declare const skipLink: (targetSelector: string, options?: SkipLinkOptions) => SkipLinkHandle;
+//# sourceMappingURL=skip-link.d.ts.map

package/dist/a11y/skip-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skip-link.d.ts","sourceRoot":"","sources":["../../src/a11y/skip-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA6C/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GAAI,gBAAgB,MAAM,EAAE,UAAS,eAAoB,KAAG,cA8KhF,CAAC"}