@bquery/bquery 1.6.0 → 1.7.0

package/src/a11y/types.ts

@@ -0,0 +1,183 @@
+/**
+ * Type definitions for the bQuery accessibility (a11y) module.
+ *
+ * @module bquery/a11y
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+// ─── Focus Trap ──────────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring focus trapping behavior.
+ */
+export interface TrapFocusOptions {
+  /**
+   * Element to receive initial focus when the trap activates.
+   * If not provided, the first focusable element is focused.
+   */
+  initialFocus?: HTMLElement | string;
+
+  /**
+   * Element to receive focus when the trap is released.
+   * If not provided, focus returns to the element that was focused
+   * before the trap was activated.
+   */
+  returnFocus?: HTMLElement | string;
+
+  /**
+   * Whether pressing Escape releases the focus trap.
+   * @default true
+   */
+  escapeDeactivates?: boolean;
+
+  /**
+   * Callback invoked when the trap is deactivated via Escape.
+   */
+  onEscape?: () => void;
+}
+
+/**
+ * Handle returned by `trapFocus()` for managing the focus trap lifecycle.
+ */
+export interface FocusTrapHandle {
+  /** Release the focus trap, restoring focus to the previous element. */
+  release: () => void;
+  /** Whether the trap is currently active. */
+  active: boolean;
+}
+
+// ─── Screen Reader Announcements ─────────────────────────────────────────────
+
+/**
+ * Priority level for screen reader announcements.
+ * - `'polite'` — announced when the user is idle (default)
+ * - `'assertive'` — announced immediately, interrupting current speech
+ */
+export type AnnouncePriority = 'polite' | 'assertive';
+
+// ─── Roving Tab Index ────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring roving tab index behavior.
+ */
+export interface RovingTabIndexOptions {
+  /**
+   * Whether navigation wraps around from last to first (and vice versa).
+   * @default true
+   */
+  wrap?: boolean;
+
+  /**
+   * Orientation of the group — determines which arrow keys are used.
+   * - `'horizontal'` — Left/Right arrows
+   * - `'vertical'` — Up/Down arrows
+   * - `'both'` — All arrow keys
+   * @default 'vertical'
+   */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+
+  /**
+   * Callback fired when the active item changes.
+   */
+  onActivate?: (element: Element, index: number) => void;
+}
+
+/**
+ * Handle returned by `rovingTabIndex()` for cleanup.
+ */
+export interface RovingTabIndexHandle {
+  /** Remove event listeners and restore original tabindex values. */
+  destroy: () => void;
+  /** Programmatically focus a specific item by index. */
+  focusItem: (index: number) => void;
+  /** Get the currently active index. */
+  activeIndex: () => number;
+}
+
+// ─── Skip Link ───────────────────────────────────────────────────────────────
+
+/**
+ * Options for configuring auto-generated skip navigation.
+ */
+export interface SkipLinkOptions {
+  /**
+   * Text content of the skip link.
+   * @default 'Skip to main content'
+   */
+  text?: string;
+
+  /**
+   * CSS class applied to the skip link element.
+   * @default 'bq-skip-link'
+   */
+  className?: string;
+}
+
+/**
+ * Handle returned by `skipLink()` for cleanup.
+ */
+export interface SkipLinkHandle {
+  /** Remove the skip link from the DOM. */
+  destroy: () => void;
+  /**
+   * The created skip link element, or `null` when `skipLink()` is called in a
+   * non-DOM environment and returns a no-op handle.
+   */
+  element: HTMLAnchorElement | null;
+}
+
+// ─── Media Preferences ───────────────────────────────────────────────────────
+
+/**
+ * Color scheme preference value.
+ */
+export type ColorScheme = 'light' | 'dark';
+
+/**
+ * Contrast preference value.
+ */
+export type ContrastPreference = 'no-preference' | 'more' | 'less' | 'custom';
+
+/**
+ * Readonly media preference signal with an explicit cleanup hook.
+ */
+export interface MediaPreferenceSignal<T> extends ReadonlySignal<T> {
+  /** Releases underlying media-query listeners. Safe to call multiple times. */
+  destroy(): void;
+}
+
+// ─── Accessibility Audit ─────────────────────────────────────────────────────
+
+/**
+ * Severity level for audit findings.
+ */
+export type AuditSeverity = 'error' | 'warning' | 'info';
+
+/**
+ * A single accessibility audit finding.
+ */
+export interface AuditFinding {
+  /** Severity level of the finding. */
+  severity: AuditSeverity;
+  /** Human-readable description of the issue. */
+  message: string;
+  /** The DOM element with the issue. */
+  element: Element;
+  /** The audit rule that triggered this finding. */
+  rule: string;
+}
+
+/**
+ * Result of an accessibility audit.
+ */
+export interface AuditResult {
+  /** All findings from the audit. */
+  findings: AuditFinding[];
+  /** Number of errors found. */
+  errors: number;
+  /** Number of warnings found. */
+  warnings: number;
+  /** Whether the audit passed (no errors). */
+  passed: boolean;
+}

package/src/component/component.ts

@@ -4,10 +4,11 @@
  * @module bquery/component
  */
 
-import { sanitizeHtml } from '../security/sanitize';
-import { effect, untrack } from '../reactive/signal';
 import type { CleanupFn } from '../reactive/signal';
+import { effect, untrack } from '../reactive/signal';
+import { sanitizeHtml } from '../security/sanitize';
 import { coercePropValue } from './props';
+import { createComponentScope, setCurrentScope, type ComponentScope } from './scope';
 import type {
   AttributeChange,
   ComponentClass,
@@ -16,6 +17,7 @@ import type {
   ComponentSignals,
   ComponentStateShape,
   PropDefinition,
+  ShadowMode,
 } from './types';
 
 /**
@@ -73,13 +75,33 @@ const createComponentClass = <
   tagName: string,
   definition: ComponentDefinition<TProps, TState, TSignals>
 ): ComponentClass<TState> => {
-  const componentAllowedTags = [...COMPONENT_ALLOWED_TAGS, ...(definition.sanitize?.allowTags ?? [])];
+  const componentAllowedTags = [
+    ...COMPONENT_ALLOWED_TAGS,
+    ...(definition.sanitize?.allowTags ?? []),
+  ];
   const componentAllowedAttributes = [
     ...COMPONENT_ALLOWED_ATTRIBUTES,
     ...(definition.sanitize?.allowAttributes ?? []),
   ];
   const signalSources = Object.values(definition.signals ?? {}) as ComponentSignalLike<unknown>[];
 
+  /** Resolve the Shadow DOM mode from the `shadow` option. */
+  const resolveShadowMode = (option: ShadowMode | undefined): 'open' | 'closed' | false => {
+    if (option === false) return false;
+    if (option === 'closed') return 'closed';
+    // true, 'open', or undefined all resolve to 'open'
+    return 'open';
+  };
+  const shadowMode = resolveShadowMode(definition.shadow);
+
+  /**
+   * Merges prop-derived observed attributes with any extra attributes from
+   * `observeAttributes`, deduplicating to avoid redundant callbacks.
+   */
+  const observedAttrs = Array.from(
+    new Set([...Object.keys(definition.props ?? {}), ...(definition.observeAttributes ?? [])])
+  );
+
   class BQueryComponent extends HTMLElement {
     /** Internal state object for the component */
     private readonly state: ComponentStateShape<TState> = {
@@ -93,10 +115,18 @@ const createComponentClass = <
     private hasMounted = false;
     /** Cleanup for external signal subscriptions */
     private signalEffectCleanup?: CleanupFn;
+    /** Component-scoped reactive resource tracker */
+    private scope?: ComponentScope;
+    /** Render target for open/closed shadow roots or the host element when shadow DOM is disabled */
+    private readonly renderRootNode: HTMLElement | ShadowRoot;
 
     constructor() {
       super();
-      this.attachShadow({ mode: 'open' });
+      if (shadowMode !== false) {
+        this.renderRootNode = this.attachShadow({ mode: shadowMode });
+      } else {
+        this.renderRootNode = this;
+      }
       this.syncProps();
     }
 
@@ -104,7 +134,7 @@ const createComponentClass = <
      * Returns the list of attributes to observe for changes.
      */
     static get observedAttributes(): string[] {
-      return Object.keys(definition.props ?? {});
+      return observedAttrs;
     }
 
     /**
@@ -121,10 +151,15 @@ const createComponentClass = <
           return;
         }
         if (this.hasMounted) {
+          // Recreate scope for reconnected component
+          this.scope = createComponentScope();
+          const previousScope = setCurrentScope(this.scope);
           try {
             definition.connected?.call(this);
           } catch (error) {
             this.handleError(error as Error);
+          } finally {
+            setCurrentScope(previousScope);
           }
           this.setupSignalSubscriptions(true);
           return;
@@ -142,8 +177,22 @@ const createComponentClass = <
      */
     private mount(): void {
       if (this.hasMounted) return;
-      definition.beforeMount?.call(this);
-      definition.connected?.call(this);
+      const previousScope = setCurrentScope(this.ensureScope());
+      let hookError = false;
+      try {
+        definition.beforeMount?.call(this);
+        definition.connected?.call(this);
+      } catch (error) {
+        hookError = true;
+        this.handleError(error as Error);
+      } finally {
+        setCurrentScope(previousScope);
+      }
+      if (hookError) {
+        this.scope?.dispose();
+        this.scope = undefined;
+        return;
+      }
       this.render();
       this.setupSignalSubscriptions();
       this.hasMounted = true;
@@ -156,6 +205,9 @@ const createComponentClass = <
       try {
         this.signalEffectCleanup?.();
         this.signalEffectCleanup = undefined;
+        // Dispose all scoped reactive resources (useSignal, useComputed, useEffect)
+        this.scope?.dispose();
+        this.scope = undefined;
         definition.disconnected?.call(this);
       } catch (error) {
         this.handleError(error as Error);
@@ -165,15 +217,21 @@ const createComponentClass = <
     /**
      * Called when an observed attribute changes.
      */
-    attributeChangedCallback(
-      name: string,
-      oldValue: string | null,
-      newValue: string | null
-    ): void {
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
       try {
         const previousProps = this.cloneProps();
         this.syncProps();
 
+        // Fire the user-facing onAttributeChanged hook for every observed attribute change
+        if (definition.onAttributeChanged) {
+          const previousScope = setCurrentScope(this.ensureScope());
+          try {
+            definition.onAttributeChanged.call(this, name, oldValue, newValue);
+          } finally {
+            setCurrentScope(previousScope);
+          }
+        }
+
         if (this.hasMounted) {
           // Component already mounted - trigger update render
           this.render(true, previousProps, { name, oldValue, newValue });
@@ -187,6 +245,24 @@ const createComponentClass = <
       }
     }
 
+    /**
+     * Called when the element is moved to a new document (e.g. via `document.adoptNode`).
+     */
+    adoptedCallback(): void {
+      if (!definition.onAdopted) {
+        return;
+      }
+
+      const previousScope = setCurrentScope(this.ensureScope());
+      try {
+        definition.onAdopted.call(this);
+      } catch (error) {
+        this.handleError(error as Error);
+      } finally {
+        setCurrentScope(previousScope);
+      }
+    }
+
     /**
      * Handles errors during component lifecycle.
      * @internal
@@ -199,6 +275,14 @@ const createComponentClass = <
       }
     }
 
+    /**
+     * Ensures the component has an active scope for scoped reactive primitives.
+     * @internal
+     */
+    private ensureScope(): ComponentScope {
+      return (this.scope ??= createComponentScope());
+    }
+
     /**
      * Updates a state property and triggers a re-render.
      *
@@ -324,7 +408,7 @@ const createComponentClass = <
     }
 
     /**
-     * Renders the component to its shadow root.
+     * Renders the component to its shadow root or host element.
      * @internal
      */
     private render(): void;
@@ -354,7 +438,7 @@ const createComponentClass = <
           this.dispatchEvent(new CustomEvent(event, { detail, bubbles: true, composed: true }));
         };
 
-        if (!this.shadowRoot) return;
+        const renderRoot = this.renderRootNode;
 
         const markup = definition.render({
           props: this.props,
@@ -373,12 +457,12 @@ const createComponentClass = <
         });
         let existingStyleElement: HTMLStyleElement | null = null;
         if (definition.styles) {
-          existingStyleElement = this.shadowRoot.querySelector<HTMLStyleElement>(
+          existingStyleElement = renderRoot.querySelector<HTMLStyleElement>(
             'style[data-bquery-component-style]'
           );
         }
 
-        this.shadowRoot.innerHTML = sanitizedMarkup;
+        renderRoot.innerHTML = sanitizedMarkup;
 
         if (definition.styles) {
           const styleElement = existingStyleElement ?? document.createElement('style');
@@ -386,7 +470,7 @@ const createComponentClass = <
             styleElement.setAttribute('data-bquery-component-style', '');
           }
           styleElement.textContent = definition.styles;
-          this.shadowRoot.prepend(styleElement);
+          renderRoot.prepend(styleElement);
         }
 
         if (triggerUpdated) {
@@ -496,26 +580,17 @@ export function defineComponent<
 export function component<
   TProps extends Record<string, unknown>,
   TSignals extends ComponentSignals = Record<string, never>,
->(
-  tagName: string,
-  definition: ComponentDefinition<TProps, undefined, TSignals>
-): void;
+>(tagName: string, definition: ComponentDefinition<TProps, undefined, TSignals>): void;
 export function component<
   TProps extends Record<string, unknown>,
   TState extends Record<string, unknown>,
   TSignals extends ComponentSignals = Record<string, never>,
->(
-  tagName: string,
-  definition: ComponentDefinition<TProps, TState, TSignals>
-): void;
+>(tagName: string, definition: ComponentDefinition<TProps, TState, TSignals>): void;
 export function component<
   TProps extends Record<string, unknown>,
   TState extends Record<string, unknown> | undefined = undefined,
   TSignals extends ComponentSignals = Record<string, never>,
->(
-  tagName: string,
-  definition: ComponentDefinition<TProps, TState, TSignals>
-): void {
+>(tagName: string, definition: ComponentDefinition<TProps, TState, TSignals>): void {
   const elementClass = createComponentClass(tagName, definition);
 
   if (!customElements.get(tagName)) {

package/src/component/html.ts

@@ -117,7 +117,10 @@ export const bool = (name: string, enabled: unknown): BooleanAttribute => {
  * ```
  */
 export const html = (strings: TemplateStringsArray, ...values: unknown[]): string => {
-  return strings.reduce((acc, part, index) => `${acc}${part}${stringifyTemplateValue(values[index])}`, '');
+  return strings.reduce(
+    (acc, part, index) => `${acc}${part}${stringifyTemplateValue(values[index])}`,
+    ''
+  );
 };
 
 /**
@@ -135,10 +138,7 @@ export const html = (strings: TemplateStringsArray, ...values: unknown[]): strin
  * // Result: '<div>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</div>'
  * ```
  */
-export const safeHtml = (
-  strings: TemplateStringsArray,
-  ...values: unknown[]
-): SanitizedHtml => {
+export const safeHtml = (strings: TemplateStringsArray, ...values: unknown[]): SanitizedHtml => {
   const escape = (value: unknown): string => {
     if (isTrustedHtml(value)) return unwrapTrustedHtml(value);
     return escapeTemplateValue(value);

package/src/component/index.ts

@@ -38,6 +38,7 @@
 export { component, defineComponent } from './component';
 export { bool, html, safeHtml } from './html';
 export { registerDefaultComponents } from './library';
+export { useComputed, useEffect, useSignal } from './scope';
 export type { DefaultComponentLibraryOptions, RegisteredDefaultComponents } from './library';
 export type {
   AttributeChange,
@@ -47,4 +48,5 @@ export type {
   ComponentSignalLike,
   ComponentSignals,
   PropDefinition,
+  ShadowMode,
 } from './types';

package/src/component/library.ts

@@ -120,9 +120,21 @@ const canSkipInputRender = (
   if (oldProps.name !== newProps.name) return false;
   if (oldProps.disabled !== newProps.disabled) return false;
 
-  const control = element.shadowRoot?.querySelector('input.control') as HTMLInputElement | null;
+  // Verify shadow DOM still matches expected non-value props before skipping re-render
+  const shadowRoot = element.shadowRoot;
+  if (!shadowRoot) return false;
+
+  const labelEl = shadowRoot.querySelector('.label');
+  if ((labelEl?.textContent ?? '') !== newProps.label) return false;
+
+  const control = shadowRoot.querySelector('input.control') as HTMLInputElement | null;
   if (!control) return false;
 
+  if (control.type !== newProps.type) return false;
+  if (control.placeholder !== newProps.placeholder) return false;
+  if (control.name !== newProps.name) return false;
+  if (control.disabled !== newProps.disabled) return false;
+
   if (control.value !== newProps.value) {
     control.value = newProps.value;
   }
@@ -163,11 +175,23 @@ const canSkipTextareaRender = (
   if (oldProps.rows !== newProps.rows) return false;
   if (oldProps.disabled !== newProps.disabled) return false;
 
-  const control = element.shadowRoot?.querySelector(
+  // Verify shadow DOM still matches expected non-value props before skipping re-render
+  const shadowRoot = element.shadowRoot;
+  if (!shadowRoot) return false;
+
+  const labelEl = shadowRoot.querySelector('.label');
+  if ((labelEl?.textContent ?? '') !== newProps.label) return false;
+
+  const control = shadowRoot.querySelector(
     'textarea.control'
   ) as HTMLTextAreaElement | null;
   if (!control) return false;
 
+  if (control.placeholder !== newProps.placeholder) return false;
+  if (control.name !== newProps.name) return false;
+  if (Number(control.rows) !== newProps.rows) return false;
+  if (control.disabled !== newProps.disabled) return false;
+
   if (control.value !== newProps.value) {
     control.value = newProps.value;
   }