@bquery/bquery 1.6.0 → 1.7.0

package/src/motion/index.ts

@@ -1,48 +1,57 @@
-/**
- * Motion module providing view transitions, FLIP animations, and spring physics.
- * Designed to work with modern browser APIs while providing smooth fallbacks.
- *
- * @module bquery/motion
- */
-
-export type {
-  AnimateOptions,
-  EasingFunction,
-  ElementBounds,
-  FlipGroupOptions,
-  FlipOptions,
-  ScrollAnimateCleanup,
-  ScrollAnimateOptions,
-  SequenceOptions,
-  SequenceStep,
-  Spring,
-  SpringConfig,
-  StaggerFunction,
-  StaggerOptions,
-  TimelineConfig,
-  TimelineControls,
-  TimelineStep,
-  TransitionOptions,
-} from './types';
-
-export { animate } from './animate';
-export {
-  easeInCubic,
-  easeInOutCubic,
-  easeInOutQuad,
-  easeInQuad,
-  easeOutBack,
-  easeOutCubic,
-  easeOutExpo,
-  easeOutQuad,
-  easingPresets,
-  linear,
-} from './easing';
-export { capturePosition, flip, flipElements, flipList } from './flip';
-export { keyframePresets } from './keyframes';
-export { prefersReducedMotion } from './reduced-motion';
-export { scrollAnimate } from './scroll';
-export { spring, springPresets } from './spring';
-export { stagger } from './stagger';
-export { sequence, timeline } from './timeline';
-export { transition } from './transition';
+/**
+ * Motion module providing view transitions, FLIP animations, spring physics,
+ * parallax, typewriter effects, and more.
+ * Designed to work with modern browser APIs while providing smooth fallbacks.
+ *
+ * @module bquery/motion
+ */
+
+export type {
+  AnimateOptions,
+  EasingFunction,
+  ElementBounds,
+  FlipGroupOptions,
+  FlipOptions,
+  MorphOptions,
+  ParallaxCleanup,
+  ParallaxOptions,
+  ScrollAnimateCleanup,
+  ScrollAnimateOptions,
+  SequenceOptions,
+  SequenceStep,
+  Spring,
+  SpringConfig,
+  StaggerFunction,
+  StaggerOptions,
+  TimelineConfig,
+  TimelineControls,
+  TimelineStep,
+  TransitionOptions,
+  TypewriterControls,
+  TypewriterOptions,
+} from './types';
+
+export { animate } from './animate';
+export {
+  easeInCubic,
+  easeInOutCubic,
+  easeInOutQuad,
+  easeInQuad,
+  easeOutBack,
+  easeOutCubic,
+  easeOutExpo,
+  easeOutQuad,
+  easingPresets,
+  linear,
+} from './easing';
+export { capturePosition, flip, flipElements, flipList } from './flip';
+export { keyframePresets } from './keyframes';
+export { morphElement } from './morph';
+export { parallax } from './parallax';
+export { prefersReducedMotion, setReducedMotion } from './reduced-motion';
+export { scrollAnimate } from './scroll';
+export { spring, springPresets } from './spring';
+export { stagger } from './stagger';
+export { sequence, timeline } from './timeline';
+export { transition } from './transition';
+export { typewriter } from './typewriter';

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.
- *
- * @module bquery/motion
- */
-
-/**
- * Check whether the user prefers reduced motion.
- *
- * @returns true if the user prefers reduced motion, otherwise false
- */
-export const prefersReducedMotion = (): boolean => {
-  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
-    return false;
-  }
-  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-};
+/**
+ * Reduced motion detection and global toggle helpers.
+ *
+ * @module bquery/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.
+ *
+ * @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;
+};