@bquery/bquery 1.3.0 → 1.5.0

package/src/motion/types.ts

@@ -1,198 +1,208 @@
-/**
- * Shared Motion module types.
- *
- * @module bquery/motion
- */
-
-/**
- * Options for view transitions.
- */
-export interface TransitionOptions {
-  /** The DOM update function to execute during transition */
-  update: () => void;
-}
-
-/**
- * Captured element bounds for FLIP animations.
- */
-export interface ElementBounds {
-  top: number;
-  left: number;
-  width: number;
-  height: number;
-}
-
-/**
- * FLIP animation configuration options.
- */
-export interface FlipOptions {
-  /** Animation duration in milliseconds */
-  duration?: number;
-  /** CSS easing function */
-  easing?: string;
-  /** Callback when animation completes */
-  onComplete?: () => void;
-}
-
-/**
- * Stagger delay function signature.
- */
-export type StaggerFunction = (index: number, total: number) => number;
-
-/**
- * Extended options for group FLIP animations.
- */
-export interface FlipGroupOptions extends FlipOptions {
-  /** Optional stagger delay function */
-  stagger?: StaggerFunction;
-}
-
-/**
- * Spring physics configuration.
- */
-export interface SpringConfig {
-  /** Spring stiffness (default: 100) */
-  stiffness?: number;
-  /** Damping coefficient (default: 10) */
-  damping?: number;
-  /** Mass of the object (default: 1) */
-  mass?: number;
-  /** Velocity threshold for completion (default: 0.01) */
-  precision?: number;
-}
-
-/**
- * Spring instance for animating values.
- */
-export interface Spring {
-  /** Start animating to target value */
-  to(target: number): Promise<void>;
-  /** Get current animated value */
-  current(): number;
-  /** Stop the animation */
-  stop(): void;
-  /** Subscribe to value changes */
-  onChange(callback: (value: number) => void): () => void;
-}
-
-/**
- * Web Animations helper configuration.
- */
-export interface AnimateOptions {
-  /** Keyframes to animate */
-  keyframes: Keyframe[] | PropertyIndexedKeyframes;
-  /** Animation options (duration, easing, etc.) */
-  options?: KeyframeAnimationOptions;
-  /** Commit final styles to the element (default: true) */
-  commitStyles?: boolean;
-  /** Respect prefers-reduced-motion (default: true) */
-  respectReducedMotion?: boolean;
-  /** Callback when animation completes */
-  onFinish?: () => void;
-}
-
-/**
- * Stagger helper configuration.
- */
-export interface StaggerOptions {
-  /** Start delay in milliseconds (default: 0) */
-  start?: number;
-  /** Origin index or keyword (default: 'start') */
-  from?: 'start' | 'center' | 'end' | number;
-  /** Optional easing function for normalized distance */
-  easing?: EasingFunction;
-}
-
-/**
- * Easing function signature.
- */
-export type EasingFunction = (t: number) => number;
-
-/**
- * Sequence step configuration.
- */
-export interface SequenceStep extends AnimateOptions {
-  /** Target element to animate */
-  target: Element;
-}
-
-/**
- * Sequence run configuration.
- */
-export interface SequenceOptions {
-  /** Optional stagger delay between steps */
-  stagger?: StaggerFunction;
-  /** Callback when sequence completes */
-  onFinish?: () => void;
-}
-
-/**
- * Timeline step configuration.
- */
-export interface TimelineStep {
-  /** Target element to animate */
-  target: Element;
-  /** Keyframes to animate */
-  keyframes: Keyframe[] | PropertyIndexedKeyframes;
-  /** Animation options for this step */
-  options?: KeyframeAnimationOptions;
-  /** Absolute or relative start time in milliseconds */
-  at?: number | `+=${number}` | `-=${number}`;
-  /** Optional label for debugging */
-  label?: string;
-}
-
-/**
- * Timeline configuration.
- */
-export interface TimelineConfig {
-  /** Commit final styles when timeline completes (default: true) */
-  commitStyles?: boolean;
-  /** Respect prefers-reduced-motion (default: true) */
-  respectReducedMotion?: boolean;
-  /** Callback when timeline completes */
-  onFinish?: () => void;
-}
-
-/**
- * Timeline controls.
- */
-export interface TimelineControls {
-  /** Play all steps */
-  play(): Promise<void>;
-  /** Pause animations */
-  pause(): void;
-  /** Resume animations */
-  resume(): void;
-  /** Stop and cancel animations */
-  stop(): void;
-  /** Seek to a specific time in milliseconds */
-  seek(time: number): void;
-  /** Add a step to the timeline */
-  add(step: TimelineStep): void;
-  /** Total timeline duration in milliseconds */
-  duration(): number;
-  /** Subscribe to finish events */
-  onFinish(callback: () => void): () => void;
-}
-
-/**
- * Scroll animation configuration.
- */
-export interface ScrollAnimateOptions extends AnimateOptions {
-  /** IntersectionObserver root */
-  root?: Element | Document | null;
-  /** Root margin for observer */
-  rootMargin?: string;
-  /** Intersection thresholds */
-  threshold?: number | number[];
-  /** Trigger only once (default: true) */
-  once?: boolean;
-  /** Callback when element enters the viewport */
-  onEnter?: (element: Element) => void;
-}
-
-/**
- * Cleanup function for scroll animations.
- */
-export type ScrollAnimateCleanup = () => void;
+/**
+ * Shared Motion module types.
+ *
+ * @module bquery/motion
+ */
+
+/**
+ * Options for view transitions.
+ */
+export interface TransitionOptions {
+  /** The DOM update function to execute during transition */
+  update: () => void | Promise<void>;
+  /** Skip the transition when reduced motion is preferred. */
+  skipOnReducedMotion?: boolean;
+  /** Classes applied to the root element while the transition is active. */
+  classes?: string[];
+  /** Transition types added when supported by the browser. */
+  types?: string[];
+  /** Called after the transition becomes ready. */
+  onReady?: () => void;
+  /** Called after the transition finishes. */
+  onFinish?: () => void;
+}
+
+/**
+ * Captured element bounds for FLIP animations.
+ */
+export interface ElementBounds {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * FLIP animation configuration options.
+ */
+export interface FlipOptions {
+  /** Animation duration in milliseconds */
+  duration?: number;
+  /** CSS easing function */
+  easing?: string;
+  /** Callback when animation completes */
+  onComplete?: () => void;
+}
+
+/**
+ * Stagger delay function signature.
+ */
+export type StaggerFunction = (index: number, total: number) => number;
+
+/**
+ * Extended options for group FLIP animations.
+ */
+export interface FlipGroupOptions extends FlipOptions {
+  /** Optional stagger delay function */
+  stagger?: StaggerFunction;
+}
+
+/**
+ * Spring physics configuration.
+ */
+export interface SpringConfig {
+  /** Spring stiffness (default: 100) */
+  stiffness?: number;
+  /** Damping coefficient (default: 10) */
+  damping?: number;
+  /** Mass of the object (default: 1) */
+  mass?: number;
+  /** Velocity threshold for completion (default: 0.01) */
+  precision?: number;
+}
+
+/**
+ * Spring instance for animating values.
+ */
+export interface Spring {
+  /** Start animating to target value */
+  to(target: number): Promise<void>;
+  /** Get current animated value */
+  current(): number;
+  /** Stop the animation */
+  stop(): void;
+  /** Subscribe to value changes */
+  onChange(callback: (value: number) => void): () => void;
+}
+
+/**
+ * Web Animations helper configuration.
+ */
+export interface AnimateOptions {
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options (duration, easing, etc.) */
+  options?: KeyframeAnimationOptions;
+  /** Commit final styles to the element (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when animation completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Stagger helper configuration.
+ */
+export interface StaggerOptions {
+  /** Start delay in milliseconds (default: 0) */
+  start?: number;
+  /** Origin index or keyword (default: 'start') */
+  from?: 'start' | 'center' | 'end' | number;
+  /** Optional easing function for normalized distance */
+  easing?: EasingFunction;
+}
+
+/**
+ * Easing function signature.
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Sequence step configuration.
+ */
+export interface SequenceStep extends AnimateOptions {
+  /** Target element to animate */
+  target: Element;
+}
+
+/**
+ * Sequence run configuration.
+ */
+export interface SequenceOptions {
+  /** Optional stagger delay between steps */
+  stagger?: StaggerFunction;
+  /** Callback when sequence completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline step configuration.
+ */
+export interface TimelineStep {
+  /** Target element to animate */
+  target: Element;
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options for this step */
+  options?: KeyframeAnimationOptions;
+  /** Absolute or relative start time in milliseconds */
+  at?: number | `+=${number}` | `-=${number}`;
+  /** Optional label for debugging */
+  label?: string;
+}
+
+/**
+ * Timeline configuration.
+ */
+export interface TimelineConfig {
+  /** Commit final styles when timeline completes (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when timeline completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline controls.
+ */
+export interface TimelineControls {
+  /** Play all steps */
+  play(): Promise<void>;
+  /** Pause animations */
+  pause(): void;
+  /** Resume animations */
+  resume(): void;
+  /** Stop and cancel animations */
+  stop(): void;
+  /** Seek to a specific time in milliseconds */
+  seek(time: number): void;
+  /** Add a step to the timeline */
+  add(step: TimelineStep): void;
+  /** Total timeline duration in milliseconds */
+  duration(): number;
+  /** Subscribe to finish events */
+  onFinish(callback: () => void): () => void;
+}
+
+/**
+ * Scroll animation configuration.
+ */
+export interface ScrollAnimateOptions extends AnimateOptions {
+  /** IntersectionObserver root */
+  root?: Element | Document | null;
+  /** Root margin for observer */
+  rootMargin?: string;
+  /** Intersection thresholds */
+  threshold?: number | number[];
+  /** Trigger only once (default: true) */
+  once?: boolean;
+  /** Callback when element enters the viewport */
+  onEnter?: (element: Element) => void;
+}
+
+/**
+ * Cleanup function for scroll animations.
+ */
+export type ScrollAnimateCleanup = () => void;

package/src/platform/announcer.ts

@@ -0,0 +1,208 @@
+/**
+ * Accessibility live-region announcer helpers.
+ *
+ * @module bquery/platform
+ */
+
+import { effect, signal, type Signal } from '../reactive/signal';
+import { getBqueryConfig } from './config';
+
+/** Options for creating an announcer. */
+export interface UseAnnouncerOptions {
+  /** Live region politeness. */
+  politeness?: 'polite' | 'assertive';
+  /** Whether the live region should be atomic. */
+  atomic?: boolean;
+  /** Delay before applying the message. */
+  delay?: number;
+  /** Delay after which the message is cleared automatically. */
+  clearDelay?: number;
+  /** Optional element id for the live region. */
+  id?: string;
+  /** Optional CSS class name. */
+  className?: string;
+  /** Optional container used to append the live region. */
+  container?: HTMLElement;
+}
+
+/** Runtime options for a single announcement. */
+export interface AnnounceOptions {
+  /** Override politeness for this specific announcement. */
+  politeness?: 'polite' | 'assertive';
+  /** Override the message delay for this specific announcement. */
+  delay?: number;
+  /** Override the auto-clear delay for this specific announcement. */
+  clearDelay?: number;
+}
+
+/** Returned announcer API. */
+export interface AnnouncerHandle {
+  /** The live region element or null outside the DOM. */
+  element: HTMLElement | null;
+  /** Reactive message signal. */
+  message: Signal<string>;
+  /** Announce a message to assistive technologies. */
+  announce: (value: string, options?: AnnounceOptions) => void;
+  /** Clear the current announcement. */
+  clear: () => void;
+  /** Remove the live region if it was created by this announcer. */
+  destroy: () => void;
+}
+
+const visuallyHiddenStyle = [
+  'position:absolute',
+  'width:1px',
+  'height:1px',
+  'padding:0',
+  'margin:-1px',
+  'overflow:hidden',
+  'clip:rect(0, 0, 0, 0)',
+  'white-space:nowrap',
+  'border:0',
+].join(';');
+
+/**
+ * Create or reuse an accessible live region.
+ *
+ * @param options - Live region configuration
+ * @returns An announcer handle with announce(), clear(), and destroy()
+ *
+ * @example
+ * ```ts
+ * const announcer = useAnnouncer();
+ * announcer.announce('Saved successfully');
+ * ```
+ */
+export const useAnnouncer = (options: UseAnnouncerOptions = {}): AnnouncerHandle => {
+  const defaults = getBqueryConfig().announcer;
+  const resolvedOptions: Required<
+    Pick<UseAnnouncerOptions, 'politeness' | 'atomic' | 'delay' | 'clearDelay'>
+  > &
+    UseAnnouncerOptions = {
+    politeness: defaults?.politeness ?? 'polite',
+    atomic: defaults?.atomic ?? true,
+    delay: defaults?.delay ?? 16,
+    clearDelay: defaults?.clearDelay ?? 1000,
+    ...options,
+  };
+
+  const message = signal('');
+
+  if (typeof document === 'undefined') {
+    return {
+      element: null,
+      message,
+      announce(value: string) {
+        message.value = value;
+      },
+      clear() {
+        message.value = '';
+      },
+      destroy() {
+        message.value = '';
+      },
+    };
+  }
+
+  const existing = resolvedOptions.id ? document.getElementById(resolvedOptions.id) : null;
+  const element = (existing ?? document.createElement('div')) as HTMLElement;
+  const created = !existing;
+
+  if (resolvedOptions.id) {
+    element.id = resolvedOptions.id;
+  }
+
+  if (resolvedOptions.className) {
+    element.className = resolvedOptions.className;
+  }
+
+  element.setAttribute('aria-live', resolvedOptions.politeness);
+  element.setAttribute('aria-atomic', String(resolvedOptions.atomic));
+  element.setAttribute('role', resolvedOptions.politeness === 'assertive' ? 'alert' : 'status');
+  element.setAttribute('data-bquery-announcer', 'true');
+  if (!element.getAttribute('style')) {
+    element.setAttribute('style', visuallyHiddenStyle);
+  }
+
+  if (created) {
+    const parent = resolvedOptions.container ?? document.body ?? document.documentElement;
+    if (!parent) {
+      return {
+        element: null,
+        message,
+        announce(value: string) {
+          message.value = value;
+        },
+        clear() {
+          message.value = '';
+        },
+        destroy() {
+          message.value = '';
+        },
+      };
+    }
+    parent.appendChild(element);
+  }
+
+  const disposeMessageEffect = effect(() => {
+    element.textContent = message.value;
+  });
+
+  let messageTimer: ReturnType<typeof setTimeout> | undefined;
+  let clearTimer: ReturnType<typeof setTimeout> | undefined;
+  let destroyed = false;
+
+  const clearTimers = (): void => {
+    if (messageTimer) {
+      clearTimeout(messageTimer);
+      messageTimer = undefined;
+    }
+    if (clearTimer) {
+      clearTimeout(clearTimer);
+      clearTimer = undefined;
+    }
+  };
+
+  const clear = (): void => {
+    if (destroyed) return;
+    clearTimers();
+    message.value = '';
+  };
+
+  const announce = (value: string, announceOptions: AnnounceOptions = {}): void => {
+    if (destroyed) return;
+    const politeness = announceOptions.politeness ?? resolvedOptions.politeness;
+    const delay = announceOptions.delay ?? resolvedOptions.delay;
+    const clearDelay = announceOptions.clearDelay ?? resolvedOptions.clearDelay;
+
+    clearTimers();
+
+    element.setAttribute('aria-live', politeness);
+    element.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+    message.value = '';
+
+    messageTimer = setTimeout(() => {
+      if (destroyed) return;
+      message.value = value;
+      if (clearDelay > 0) {
+        clearTimer = setTimeout(() => {
+          if (destroyed) return;
+          message.value = '';
+        }, clearDelay);
+      }
+    }, delay);
+  };
+
+  const destroy = (): void => {
+    if (destroyed) return;
+    destroyed = true;
+    clearTimers();
+    message.value = '';
+    disposeMessageEffect();
+    if (created) {
+      element.remove();
+    }
+  };
+
+  return { element, message, announce, clear, destroy };
+};