@bquery/bquery 1.5.0 → 1.7.0

package/src/motion/types.ts

@@ -206,3 +206,66 @@ export interface ScrollAnimateOptions extends AnimateOptions {
  * Cleanup function for scroll animations.
  */
 export type ScrollAnimateCleanup = () => void;
+
+/**
+ * Options for the `morphElement` FLIP-based morph animation.
+ */
+export interface MorphOptions {
+  /** Animation duration in milliseconds (default: 300) */
+  duration?: number;
+  /** CSS easing function (default: 'ease') */
+  easing?: string;
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when morph completes */
+  onComplete?: () => void;
+}
+
+/**
+ * Options for the `parallax` scroll-linked effect.
+ */
+export interface ParallaxOptions {
+  /** Parallax speed multiplier (default: 0.5). Values < 1 are slower, > 1 are faster. */
+  speed?: number;
+  /** Direction of the parallax effect (default: 'vertical') */
+  direction?: 'vertical' | 'horizontal' | 'both';
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+}
+
+/**
+ * Cleanup function for the parallax effect.
+ */
+export type ParallaxCleanup = () => void;
+
+/**
+ * Options for the `typewriter` text animation.
+ */
+export interface TypewriterOptions {
+  /** Time in milliseconds between each character (default: 50) */
+  speed?: number;
+  /** Initial delay before starting, in milliseconds (default: 0) */
+  delay?: number;
+  /** Whether to show a blinking cursor (default: false) */
+  cursor?: boolean;
+  /** Cursor character (default: '|') */
+  cursorChar?: string;
+  /** Whether to loop the animation (default: false) */
+  loop?: boolean;
+  /** Pause duration at end before looping, in ms (default: 1000) */
+  loopDelay?: number;
+  /** Whether to respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when typing completes (per-loop) */
+  onComplete?: () => void;
+}
+
+/**
+ * Controls for an active typewriter animation.
+ */
+export interface TypewriterControls {
+  /** Stop the animation and clean up */
+  stop(): void;
+  /** Promise that resolves when the animation finishes, or when a looping animation is stopped */
+  done: Promise<void>;
+}

package/src/motion/typewriter.ts

@@ -0,0 +1,164 @@
+/**
+ * Character-by-character typewriter text animation.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { TypewriterControls, TypewriterOptions } from './types';
+
+/**
+ * Animate text appearing character by character in an element.
+ *
+ * @param element - The element to type text into
+ * @param text - The text to display
+ * @param options - Typewriter configuration
+ * @returns Controls with `.stop()` to cancel and `.done` promise
+ *
+ * @example
+ * ```ts
+ * const tw = typewriter(
+ *   document.querySelector('#output')!,
+ *   'Hello, world!',
+ *   { speed: 80, cursor: true },
+ * );
+ *
+ * // Wait for it to finish:
+ * await tw.done;
+ *
+ * // Or cancel early:
+ * tw.stop();
+ * ```
+ */
+export const typewriter = (
+  element: HTMLElement,
+  text: string,
+  options: TypewriterOptions = {}
+): TypewriterControls => {
+  const {
+    speed = 50,
+    delay = 0,
+    cursor = false,
+    cursorChar = '|',
+    loop = false,
+    loopDelay = 1000,
+    respectReducedMotion = true,
+    onComplete,
+  } = options;
+
+  if (typeof document === 'undefined') {
+    return {
+      stop: () => {},
+      done: Promise.resolve(),
+    };
+  }
+
+  const el = element;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let cursorEl: HTMLSpanElement | null = null;
+  let cursorTimer: ReturnType<typeof setInterval> | null = null;
+  let resolvePromise: (() => void) | null = null;
+
+  // Add cursor element if enabled
+  const setupCursor = () => {
+    if (!cursor) return;
+    cursorEl = document.createElement('span');
+    cursorEl.setAttribute('aria-hidden', 'true');
+    cursorEl.textContent = cursorChar;
+    el.appendChild(cursorEl);
+
+    // Blink the cursor
+    let visible = true;
+    cursorTimer = setInterval(() => {
+      if (cursorEl) {
+        visible = !visible;
+        cursorEl.style.opacity = visible ? '1' : '0';
+      }
+    }, 530);
+  };
+
+  const removeCursor = () => {
+    if (cursorTimer !== null) {
+      clearInterval(cursorTimer);
+      cursorTimer = null;
+    }
+    if (cursorEl && cursorEl.parentNode) {
+      cursorEl.parentNode.removeChild(cursorEl);
+      cursorEl = null;
+    }
+  };
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    removeCursor();
+    // Resolve the done promise so callers awaiting it are unblocked
+    resolvePromise?.();
+    resolvePromise = null;
+  };
+
+  // If reduced motion, show text instantly
+  if (respectReducedMotion && prefersReducedMotion()) {
+    el.textContent = text;
+    onComplete?.();
+    return {
+      stop: () => {},
+      done: Promise.resolve(),
+    };
+  }
+
+  const done = new Promise<void>((resolve) => {
+    resolvePromise = resolve;
+
+    const typeLoop = () => {
+      let charIndex = 0;
+      el.textContent = '';
+      setupCursor();
+      const textNode = document.createTextNode('');
+
+      if (cursorEl) {
+        el.insertBefore(textNode, cursorEl);
+      } else {
+        el.appendChild(textNode);
+      }
+
+      const typeNextChar = () => {
+        if (stopped) {
+          return;
+        }
+        if (charIndex < text.length) {
+          textNode.data = text.slice(0, charIndex + 1);
+          charIndex++;
+          timer = setTimeout(typeNextChar, speed);
+        } else {
+          // Typing complete for this iteration
+          onComplete?.();
+
+          if (loop && !stopped) {
+            timer = setTimeout(() => {
+              if (!stopped) {
+                removeCursor();
+                typeLoop();
+              }
+            }, loopDelay);
+          } else {
+            removeCursor();
+            resolve();
+            resolvePromise = null;
+          }
+        }
+      };
+
+      timer = setTimeout(typeNextChar, delay);
+    };
+
+    typeLoop();
+  });
+
+  return { stop, done };
+};

package/src/platform/announcer.ts

@@ -1,208 +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 };
-};
+/**
+ * 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 };
+};