@bquery/bquery 1.6.0 → 1.8.1

package/src/motion/morph.ts

@@ -0,0 +1,151 @@
+/**
+ * FLIP-based morph animation between two element states.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { MorphOptions } from './types';
+
+/**
+ * Perform a FLIP-based morph animation between two elements.
+ *
+ * Captures the bounding rect of the `from` element, hides it, shows the
+ * `to` element, then animates the `to` element from the `from` position
+ * using CSS transforms and opacity.
+ *
+ * @param from - The source element (will be hidden at the end)
+ * @param to - The destination element (will be shown and animated into place)
+ * @param options - Morph animation options
+ * @returns Promise that resolves when the morph completes
+ *
+ * @example
+ * ```ts
+ * const card = document.querySelector('.card');
+ * const detail = document.querySelector('.detail');
+ * await morphElement(card, detail, { duration: 400, easing: 'ease-out' });
+ * ```
+ */
+export const morphElement = (
+  from: Element,
+  to: Element,
+  options: MorphOptions = {}
+): Promise<void> => {
+  const { duration = 300, easing = 'ease', respectReducedMotion = true, onComplete } = options;
+
+  const fromEl = from as HTMLElement;
+  const toEl = to as HTMLElement;
+
+  if (
+    typeof window === 'undefined' ||
+    typeof document === 'undefined' ||
+    typeof fromEl.getBoundingClientRect !== 'function' ||
+    typeof toEl.getBoundingClientRect !== 'function' ||
+    typeof fromEl.style === 'undefined' ||
+    typeof toEl.style === 'undefined'
+  ) {
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  // Capture FIRST position of source element
+  const firstRect = from.getBoundingClientRect();
+
+  // Ensure destination is visible so we can measure it
+  const previousDisplay = toEl.style.display;
+  const previousVisibility = toEl.style.visibility;
+  const previousTransform = toEl.style.transform;
+  const previousOpacity = toEl.style.opacity;
+  const computedDisplay =
+    typeof getComputedStyle === 'function'
+      ? getComputedStyle(toEl).display
+      : previousDisplay || 'block';
+  // Prefer an explicit inline display, otherwise fall back to the current computed
+  // display, and finally to `block` so hidden destinations remain measurable.
+  const forcedDisplay =
+    computedDisplay === 'none' ? 'block' : previousDisplay || computedDisplay || 'block';
+  const restoreAnimatedInlineStyles = () => {
+    toEl.style.transform = previousTransform;
+    toEl.style.opacity = previousOpacity;
+  };
+
+  toEl.style.visibility = 'hidden';
+  toEl.style.display = forcedDisplay;
+
+  // Capture LAST position of destination element
+  const lastRect = to.getBoundingClientRect();
+
+  // Restore visibility (it will be animated in)
+  toEl.style.visibility = previousVisibility;
+
+  // Hide source, show destination
+  fromEl.style.display = 'none';
+  if (computedDisplay === 'none') {
+    toEl.style.display = forcedDisplay;
+  } else if (previousDisplay === 'none') {
+    toEl.style.display = '';
+  } else {
+    toEl.style.display = previousDisplay;
+  }
+
+  // If reduced motion is preferred, skip the animation
+  if (respectReducedMotion && prefersReducedMotion()) {
+    restoreAnimatedInlineStyles();
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  // Calculate the transform inversion (FLIP: Invert)
+  const dx = firstRect.left - lastRect.left;
+  const dy = firstRect.top - lastRect.top;
+  const sx = firstRect.width / (lastRect.width || 1);
+  const sy = firstRect.height / (lastRect.height || 1);
+
+  // If no visual change, skip animation
+  if (dx === 0 && dy === 0 && sx === 1 && sy === 1) {
+    restoreAnimatedInlineStyles();
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  const keyframes: Keyframe[] = [
+    {
+      transform: `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`,
+      opacity: '0.5',
+    },
+    {
+      transform: 'translate(0, 0) scale(1, 1)',
+      opacity: '1',
+    },
+  ];
+
+  // Check if animate API is available
+  if (typeof toEl.animate !== 'function') {
+    restoreAnimatedInlineStyles();
+    onComplete?.();
+    return Promise.resolve();
+  }
+
+  return new Promise<void>((resolve) => {
+    const animation = toEl.animate(keyframes, {
+      duration,
+      easing,
+      fill: 'forwards',
+    });
+
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      restoreAnimatedInlineStyles();
+      animation.cancel();
+      onComplete?.();
+      resolve();
+    };
+
+    animation.onfinish = finalize;
+    if (animation.finished) {
+      animation.finished.then(finalize).catch(finalize);
+    }
+  });
+};

package/src/motion/parallax.ts

@@ -0,0 +1,120 @@
+/**
+ * Scroll-linked parallax effect.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { ParallaxCleanup, ParallaxOptions } from './types';
+
+/**
+ * Apply a scroll-linked parallax effect to an element.
+ *
+ * The element's position is translated based on the scroll position
+ * multiplied by the speed factor. A speed of `0.5` means the element
+ * moves at half the scroll speed (classic background parallax).
+ *
+ * @param element - The element to apply the parallax effect to
+ * @param options - Parallax configuration
+ * @returns A cleanup function that removes the scroll listener
+ *
+ * @example
+ * ```ts
+ * const cleanup = parallax(document.querySelector('.hero-bg')!, {
+ *   speed: 0.3,
+ *   direction: 'vertical',
+ * });
+ *
+ * // Later, remove the effect:
+ * cleanup();
+ * ```
+ */
+export const parallax = (element: Element, options: ParallaxOptions = {}): ParallaxCleanup => {
+  if (
+    typeof window === 'undefined' ||
+    typeof window.addEventListener !== 'function' ||
+    typeof window.removeEventListener !== 'function' ||
+    typeof requestAnimationFrame !== 'function' ||
+    typeof cancelAnimationFrame !== 'function'
+  ) {
+    return () => {};
+  }
+
+  const { speed = 0.5, direction = 'vertical', respectReducedMotion = true } = options;
+
+  const el = element as HTMLElement;
+  const previousTransform = el.style.transform;
+
+  // If reduced motion is preferred, don't apply parallax
+  if (respectReducedMotion && prefersReducedMotion()) {
+    return () => {};
+  }
+
+  let ticking = false;
+  let destroyed = false;
+  let frameId: number | null = null;
+
+  const cleanup = (): void => {
+    if (destroyed) return;
+    destroyed = true;
+    window.removeEventListener('scroll', onScroll);
+    if (frameId !== null) {
+      cancelAnimationFrame(frameId);
+      frameId = null;
+    }
+    ticking = false;
+    el.style.transform = previousTransform;
+  };
+
+  const updatePosition = () => {
+    if (destroyed) return;
+
+    // Re-check reduced motion on each frame (in case toggle changed)
+    if (respectReducedMotion && prefersReducedMotion()) {
+      cleanup();
+      return;
+    }
+
+    const scrollY = window.scrollY;
+    const scrollX = window.scrollX;
+
+    let tx = 0;
+    let ty = 0;
+
+    if (direction === 'vertical' || direction === 'both') {
+      ty = scrollY * speed;
+    }
+    if (direction === 'horizontal' || direction === 'both') {
+      tx = scrollX * speed;
+    }
+
+    const parallaxTransform = `translate3d(${tx}px, ${ty}px, 0)`;
+    el.style.transform = previousTransform
+      ? `${previousTransform} ${parallaxTransform}`
+      : parallaxTransform;
+  };
+
+  const onScroll = () => {
+    if (destroyed) return;
+    if (respectReducedMotion && prefersReducedMotion()) {
+      cleanup();
+      return;
+    }
+    if (!ticking) {
+      ticking = true;
+      frameId = requestAnimationFrame(() => {
+        frameId = null;
+        updatePosition();
+        ticking = false;
+      });
+    }
+  };
+
+  // Apply initial position
+  updatePosition();
+
+  // Listen to scroll events
+  window.addEventListener('scroll', onScroll, { passive: true });
+
+  return cleanup;
+};

package/src/motion/reduced-motion.ts

@@ -1,17 +1,66 @@
 /**
- * Reduced motion detection helpers.
+ * Reduced motion detection and global toggle helpers.
  *
  * @module bquery/motion
  */
 
 /**
- * Check whether the user prefers reduced motion.
+ * Global override for reduced motion preference.
+ * When `null`, the system preference is used.
+ * When `true`, reduced motion is forced on.
+ * When `false`, reduced motion is forced off.
  *
- * @returns true if the user prefers reduced motion, otherwise false
+ * @internal
+ */
+let reducedMotionOverride: boolean | null = null;
+
+/**
+ * Check whether reduced motion should be applied.
+ *
+ * Returns the global override if set via {@link setReducedMotion},
+ * otherwise checks the user's system preference.
+ *
+ * @returns `true` if reduced motion should be applied
+ *
+ * @example
+ * ```ts
+ * if (prefersReducedMotion()) {
+ *   // skip animation
+ * }
+ * ```
  */
 export const prefersReducedMotion = (): boolean => {
+  if (reducedMotionOverride !== null) {
+    return reducedMotionOverride;
+  }
   if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
     return false;
   }
   return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
 };
+
+/**
+ * Programmatically override the reduced motion preference globally.
+ *
+ * When set to `true`, all motion functions that respect reduced motion
+ * will skip animations. When set to `false`, animations run regardless
+ * of system settings. Pass `null` to restore system-preference detection.
+ *
+ * @param override - `true` to force reduced motion, `false` to force
+ *   full motion, or `null` to use system preference
+ *
+ * @example
+ * ```ts
+ * // Force all animations to be instant
+ * setReducedMotion(true);
+ *
+ * // Re-enable animations regardless of system
+ * setReducedMotion(false);
+ *
+ * // Restore system preference
+ * setReducedMotion(null);
+ * ```
+ */
+export const setReducedMotion = (override: boolean | null): void => {
+  reducedMotionOverride = override;
+};

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/plugin/index.ts

@@ -0,0 +1,37 @@
+/**
+ * bQuery Plugin System — register plugins that extend bQuery with custom
+ * directives and components.
+ *
+ * @module bquery/plugin
+ *
+ * @example
+ * ```ts
+ * import { use, isInstalled, getInstalledPlugins } from '@bquery/bquery/plugin';
+ *
+ * use({
+ *   name: 'my-plugin',
+ *   install(ctx, options) {
+ *     ctx.directive('tooltip', (el, expr) => { ... });
+ *     ctx.component('my-widget', MyWidgetElement);
+ *   },
+ * });
+ * ```
+ */
+
+// Types
+export type {
+  BQueryPlugin,
+  CustomDirective,
+  CustomDirectiveHandler,
+  PluginInstallContext,
+} from './types';
+
+// Runtime API
+export {
+  use,
+  isInstalled,
+  getInstalledPlugins,
+  getCustomDirective,
+  getCustomDirectives,
+  resetPlugins,
+} from './registry';