@bquery/bquery 1.5.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;
+};

package/src/motion/transition.ts

@@ -1,97 +1,97 @@
-/**
- * View transition helpers.
- *
- * @module bquery/motion
- */
-
-import type { TransitionOptions } from './types';
-import { prefersReducedMotion } from './reduced-motion';
-import { getBqueryConfig } from '../platform/config';
-
-/** Extended document type with View Transitions API */
-type DocumentWithTransition = Document & {
-  startViewTransition?: (callback: () => void | Promise<void>) => {
-    finished: Promise<void>;
-    ready: Promise<void>;
-    updateCallbackDone: Promise<void>;
-    skipTransition?: () => void;
-    types?: {
-      add: (type: string) => void;
-    };
-  };
-};
-
-const sanitizeTokens = (tokens?: string[]): string[] =>
-  (tokens ?? []).map((token) => token.trim()).filter((token) => token.length > 0);
-
-/**
- * Execute a DOM update with view transition animation.
- * Falls back to immediate update when View Transitions API is unavailable.
- *
- * @param updateOrOptions - Update function or options object
- * @returns Promise that resolves when transition completes
- *
- * @example
- * ```ts
- * await transition(() => {
- *   $('#content').text('Updated');
- * });
- * ```
- */
-export const transition = async (
-  updateOrOptions: (() => void | Promise<void>) | TransitionOptions
-): Promise<void> => {
-  const config = getBqueryConfig().transitions;
-  const options: TransitionOptions =
-    typeof updateOrOptions === 'function'
-      ? {
-          update: updateOrOptions,
-          classes: config?.classes,
-          types: config?.types,
-          skipOnReducedMotion: config?.skipOnReducedMotion,
-        }
-      : {
-          ...updateOrOptions,
-          classes: updateOrOptions.classes ?? config?.classes,
-          types: updateOrOptions.types ?? config?.types,
-          skipOnReducedMotion: updateOrOptions.skipOnReducedMotion ?? config?.skipOnReducedMotion,
-        };
-  const update = options.update;
-
-  // SSR/non-DOM environment fallback
-  if (typeof document === 'undefined') {
-    await update();
-    return;
-  }
-
-  const doc = document as DocumentWithTransition;
-  const root = document.documentElement;
-  const classes = sanitizeTokens(options.classes);
-  const types = sanitizeTokens(options.types);
-
-  if (!doc.startViewTransition || (options.skipOnReducedMotion && prefersReducedMotion())) {
-    await update();
-    options.onFinish?.();
-    return;
-  }
-
-  classes.forEach((className: string) => root.classList.add(className));
-
-  try {
-    const viewTransition = doc.startViewTransition(() => update());
-    const transitionTypes = viewTransition.types;
-
-    if (transitionTypes) {
-      for (const type of types) {
-        transitionTypes.add(type);
-      }
-    }
-
-    await viewTransition.ready;
-    options.onReady?.();
-    await viewTransition.finished;
-    options.onFinish?.();
-  } finally {
-    classes.forEach((className: string) => root.classList.remove(className));
-  }
-};
+/**
+ * View transition helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { TransitionOptions } from './types';
+import { prefersReducedMotion } from './reduced-motion';
+import { getBqueryConfig } from '../platform/config';
+
+/** Extended document type with View Transitions API */
+type DocumentWithTransition = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => {
+    finished: Promise<void>;
+    ready: Promise<void>;
+    updateCallbackDone: Promise<void>;
+    skipTransition?: () => void;
+    types?: {
+      add: (type: string) => void;
+    };
+  };
+};
+
+const sanitizeTokens = (tokens?: string[]): string[] =>
+  (tokens ?? []).map((token) => token.trim()).filter((token) => token.length > 0);
+
+/**
+ * Execute a DOM update with view transition animation.
+ * Falls back to immediate update when View Transitions API is unavailable.
+ *
+ * @param updateOrOptions - Update function or options object
+ * @returns Promise that resolves when transition completes
+ *
+ * @example
+ * ```ts
+ * await transition(() => {
+ *   $('#content').text('Updated');
+ * });
+ * ```
+ */
+export const transition = async (
+  updateOrOptions: (() => void | Promise<void>) | TransitionOptions
+): Promise<void> => {
+  const config = getBqueryConfig().transitions;
+  const options: TransitionOptions =
+    typeof updateOrOptions === 'function'
+      ? {
+          update: updateOrOptions,
+          classes: config?.classes,
+          types: config?.types,
+          skipOnReducedMotion: config?.skipOnReducedMotion,
+        }
+      : {
+          ...updateOrOptions,
+          classes: updateOrOptions.classes ?? config?.classes,
+          types: updateOrOptions.types ?? config?.types,
+          skipOnReducedMotion: updateOrOptions.skipOnReducedMotion ?? config?.skipOnReducedMotion,
+        };
+  const update = options.update;
+
+  // SSR/non-DOM environment fallback
+  if (typeof document === 'undefined') {
+    await update();
+    return;
+  }
+
+  const doc = document as DocumentWithTransition;
+  const root = document.documentElement;
+  const classes = sanitizeTokens(options.classes);
+  const types = sanitizeTokens(options.types);
+
+  if (!doc.startViewTransition || (options.skipOnReducedMotion && prefersReducedMotion())) {
+    await update();
+    options.onFinish?.();
+    return;
+  }
+
+  classes.forEach((className: string) => root.classList.add(className));
+
+  try {
+    const viewTransition = doc.startViewTransition(() => update());
+    const transitionTypes = viewTransition.types;
+
+    if (transitionTypes) {
+      for (const type of types) {
+        transitionTypes.add(type);
+      }
+    }
+
+    await viewTransition.ready;
+    options.onReady?.();
+    await viewTransition.finished;
+    options.onFinish?.();
+  } finally {
+    classes.forEach((className: string) => root.classList.remove(className));
+  }
+};