@bquery/bquery 1.2.0 → 1.3.0

package/src/motion/index.ts

@@ -5,361 +5,44 @@
  * @module bquery/motion
  */
 
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * 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;
-}
-
-/**
- * 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;
-}
-
-// ============================================================================
-// View Transitions
-// ============================================================================
-
-/** Extended document type with View Transitions API */
-type DocumentWithTransition = Document & {
-  startViewTransition?: (callback: () => void) => {
-    finished: Promise<void>;
-    ready: Promise<void>;
-    updateCallbackDone: Promise<void>;
-  };
-};
-
-/**
- * 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) | TransitionOptions
-): Promise<void> => {
-  const update = typeof updateOrOptions === 'function' ? updateOrOptions : updateOrOptions.update;
-
-  const doc = document as DocumentWithTransition;
-
-  if (doc.startViewTransition) {
-    await doc.startViewTransition(() => update()).finished;
-    return;
-  }
-
-  update();
-};
-
-// ============================================================================
-// FLIP Animations
-// ============================================================================
-
-/**
- * Capture the current bounds of an element for FLIP animation.
- *
- * @param element - The DOM element to measure
- * @returns The element's current position and size
- */
-export const capturePosition = (element: Element): ElementBounds => {
-  const rect = element.getBoundingClientRect();
-  return {
-    top: rect.top,
-    left: rect.left,
-    width: rect.width,
-    height: rect.height,
-  };
-};
-
-/**
- * Perform a FLIP (First, Last, Invert, Play) animation.
- * Animates an element from its captured position to its current position.
- *
- * @param element - The element to animate
- * @param firstBounds - The previously captured bounds
- * @param options - Animation configuration
- * @returns Promise that resolves when animation completes
- *
- * @example
- * ```ts
- * const first = capturePosition(element);
- * // ... DOM changes that move the element ...
- * await flip(element, first, { duration: 300 });
- * ```
- */
-export const flip = (
-  element: Element,
-  firstBounds: ElementBounds,
-  options: FlipOptions = {}
-): Promise<void> => {
-  const { duration = 300, easing = 'ease-out', onComplete } = options;
-
-  // Last: Get current position
-  const lastBounds = capturePosition(element);
-
-  // Skip animation if element has zero dimensions (avoid division by zero)
-  if (lastBounds.width === 0 || lastBounds.height === 0) {
-    return Promise.resolve();
-  }
-
-  // Invert: Calculate the delta
-  const deltaX = firstBounds.left - lastBounds.left;
-  const deltaY = firstBounds.top - lastBounds.top;
-  const deltaW = firstBounds.width / lastBounds.width;
-  const deltaH = firstBounds.height / lastBounds.height;
-
-  // Skip animation if no change
-  if (deltaX === 0 && deltaY === 0 && deltaW === 1 && deltaH === 1) {
-    return Promise.resolve();
-  }
-
-  const htmlElement = element as HTMLElement;
-
-  // Apply inverted transform
-  htmlElement.style.transform = `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`;
-  htmlElement.style.transformOrigin = 'top left';
-
-  // Force reflow
-  void htmlElement.offsetHeight;
-
-  // Play: Animate back to current position
-  return new Promise((resolve) => {
-    const animation = htmlElement.animate(
-      [
-        {
-          transform: `translate(${deltaX}px, ${deltaY}px) scale(${deltaW}, ${deltaH})`,
-        },
-        { transform: 'translate(0, 0) scale(1, 1)' },
-      ],
-      { duration, easing, fill: 'forwards' }
-    );
-
-    animation.onfinish = () => {
-      htmlElement.style.transform = '';
-      htmlElement.style.transformOrigin = '';
-      onComplete?.();
-      resolve();
-    };
-  });
-};
-
-/**
- * FLIP helper for animating a list of elements.
- * Useful for reordering lists with smooth animations.
- *
- * @param elements - Array of elements to animate
- * @param performUpdate - Function that performs the DOM update
- * @param options - Animation configuration
- *
- * @example
- * ```ts
- * await flipList(listItems, () => {
- *   container.appendChild(container.firstChild); // Move first to last
- * });
- * ```
- */
-export const flipList = async (
-  elements: Element[],
-  performUpdate: () => void,
-  options: FlipOptions = {}
-): Promise<void> => {
-  // First: Capture all positions
-  const positions = new Map<Element, ElementBounds>();
-  for (const el of elements) {
-    positions.set(el, capturePosition(el));
-  }
-
-  // Perform DOM update
-  performUpdate();
-
-  // Animate each element
-  const animations = elements.map((el) => {
-    const first = positions.get(el);
-    if (!first) return Promise.resolve();
-    return flip(el, first, options);
-  });
-
-  await Promise.all(animations);
-};
-
-// ============================================================================
-// Spring Physics
-// ============================================================================
-
-/**
- * Default spring configuration values.
- */
-const DEFAULT_SPRING_CONFIG: Required<SpringConfig> = {
-  stiffness: 100,
-  damping: 10,
-  mass: 1,
-  precision: 0.01,
-};
-
-/**
- * Create a spring-based animation for smooth, physics-based motion.
- *
- * @param initialValue - Starting value for the spring
- * @param config - Spring physics configuration
- * @returns Spring instance for controlling the animation
- *
- * @example
- * ```ts
- * const x = spring(0, { stiffness: 120, damping: 14 });
- * x.onChange((value) => {
- *   element.style.transform = `translateX(${value}px)`;
- * });
- * await x.to(100);
- * ```
- */
-export const spring = (initialValue: number, config: SpringConfig = {}): Spring => {
-  const { stiffness, damping, mass, precision } = {
-    ...DEFAULT_SPRING_CONFIG,
-    ...config,
-  };
-
-  let current = initialValue;
-  let velocity = 0;
-  let target = initialValue;
-  let animationFrame: number | null = null;
-  let resolvePromise: (() => void) | null = null;
-  const listeners = new Set<(value: number) => void>();
-
-  const notifyListeners = () => {
-    for (const listener of listeners) {
-      listener(current);
-    }
-  };
-
-  const step = () => {
-    // Spring physics calculation
-    const displacement = current - target;
-    const springForce = -stiffness * displacement;
-    const dampingForce = -damping * velocity;
-    const acceleration = (springForce + dampingForce) / mass;
-
-    velocity += acceleration * (1 / 60); // Assuming 60fps
-    current += velocity * (1 / 60);
-
-    notifyListeners();
-
-    // Check if spring has settled
-    if (Math.abs(velocity) < precision && Math.abs(displacement) < precision) {
-      current = target;
-      velocity = 0;
-      animationFrame = null;
-      notifyListeners();
-      resolvePromise?.();
-      resolvePromise = null;
-      return;
-    }
-
-    animationFrame = requestAnimationFrame(step);
-  };
-
-  return {
-    to(newTarget: number): Promise<void> {
-      target = newTarget;
-
-      if (animationFrame !== null) {
-        cancelAnimationFrame(animationFrame);
-      }
-
-      return new Promise((resolve) => {
-        resolvePromise = resolve;
-        animationFrame = requestAnimationFrame(step);
-      });
-    },
-
-    current(): number {
-      return current;
-    },
-
-    stop(): void {
-      if (animationFrame !== null) {
-        cancelAnimationFrame(animationFrame);
-        animationFrame = null;
-      }
-      velocity = 0;
-      resolvePromise?.();
-      resolvePromise = null;
-    },
-
-    onChange(callback: (value: number) => void): () => void {
-      listeners.add(callback);
-      return () => listeners.delete(callback);
-    },
-  };
-};
-
-/**
- * Preset spring configurations for common use cases.
- */
-export const springPresets = {
-  /** Gentle, slow-settling spring */
-  gentle: { stiffness: 80, damping: 15 } as SpringConfig,
-  /** Responsive, snappy spring */
-  snappy: { stiffness: 200, damping: 20 } as SpringConfig,
-  /** Bouncy, playful spring */
-  bouncy: { stiffness: 300, damping: 8 } as SpringConfig,
-  /** Stiff, quick spring with minimal overshoot */
-  stiff: { stiffness: 400, damping: 30 } as SpringConfig,
-};
+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';

package/src/motion/keyframes.ts

@@ -0,0 +1,46 @@
+/**
+ * Keyframe presets.
+ *
+ * @module bquery/motion
+ */
+
+/**
+ * Common keyframe presets for quick animations.
+ */
+export const keyframePresets = {
+  fadeIn: (from = 0, to = 1): Keyframe[] => [{ opacity: from }, { opacity: to }],
+  fadeOut: (from = 1, to = 0): Keyframe[] => [{ opacity: from }, { opacity: to }],
+  slideInUp: (distance = 16): Keyframe[] => [
+    { opacity: 0, transform: `translateY(${distance}px)` },
+    { opacity: 1, transform: 'translateY(0)' },
+  ],
+  slideInDown: (distance = 16): Keyframe[] => [
+    { opacity: 0, transform: `translateY(-${distance}px)` },
+    { opacity: 1, transform: 'translateY(0)' },
+  ],
+  slideInLeft: (distance = 16): Keyframe[] => [
+    { opacity: 0, transform: `translateX(${distance}px)` },
+    { opacity: 1, transform: 'translateX(0)' },
+  ],
+  slideInRight: (distance = 16): Keyframe[] => [
+    { opacity: 0, transform: `translateX(-${distance}px)` },
+    { opacity: 1, transform: 'translateX(0)' },
+  ],
+  scaleIn: (from = 0.95, to = 1): Keyframe[] => [
+    { opacity: 0, transform: `scale(${from})` },
+    { opacity: 1, transform: `scale(${to})` },
+  ],
+  scaleOut: (from = 1, to = 0.95): Keyframe[] => [
+    { opacity: 1, transform: `scale(${from})` },
+    { opacity: 0, transform: `scale(${to})` },
+  ],
+  pop: (from = 0.9, mid = 1.02, to = 1): Keyframe[] => [
+    { opacity: 0, transform: `scale(${from})` },
+    { opacity: 1, transform: `scale(${mid})`, offset: 0.6 },
+    { opacity: 1, transform: `scale(${to})` },
+  ],
+  rotateIn: (degrees = 6): Keyframe[] => [
+    { opacity: 0, transform: `rotate(${degrees}deg) scale(0.98)` },
+    { opacity: 1, transform: 'rotate(0deg) scale(1)' },
+  ],
+};

package/src/motion/reduced-motion.ts

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

package/src/motion/scroll.ts

@@ -0,0 +1,57 @@
+/**
+ * Scroll-triggered animation helpers.
+ *
+ * @module bquery/motion
+ */
+
+import { animate } from './animate';
+import type { ScrollAnimateCleanup, ScrollAnimateOptions } from './types';
+
+const resolveElements = (elements: Element | Iterable<Element> | ArrayLike<Element>): Element[] => {
+  if (typeof Element !== 'undefined' && elements instanceof Element) return [elements];
+  return Array.from(elements as Iterable<Element>);
+};
+
+/**
+ * Animate elements when they enter the viewport.
+ *
+ * @param elements - Target element(s)
+ * @param options - Scroll animation configuration
+ * @returns Cleanup function to disconnect observers
+ */
+export const scrollAnimate = (
+  elements: Element | Iterable<Element> | ArrayLike<Element>,
+  options: ScrollAnimateOptions
+): ScrollAnimateCleanup => {
+  const targets = resolveElements(elements);
+  if (!targets.length) return () => undefined;
+
+  const { root = null, rootMargin, threshold, once = true, onEnter, ...animationConfig } = options;
+
+  if (typeof IntersectionObserver === 'undefined') {
+    targets.forEach((element) => {
+      onEnter?.(element);
+      void animate(element, animationConfig);
+    });
+    return () => undefined;
+  }
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (!entry.isIntersecting) return;
+        const element = entry.target as Element;
+        onEnter?.(element);
+        void animate(element, animationConfig);
+        if (once) {
+          observer.unobserve(element);
+        }
+      });
+    },
+    { root, rootMargin, threshold }
+  );
+
+  targets.forEach((element) => observer.observe(element));
+
+  return () => observer.disconnect();
+};

package/src/motion/spring.ts

@@ -0,0 +1,150 @@
+/**
+ * Spring physics helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { Spring, SpringConfig } from './types';
+
+/**
+ * Default spring configuration values.
+ */
+const DEFAULT_SPRING_CONFIG: Required<SpringConfig> = {
+  stiffness: 100,
+  damping: 10,
+  mass: 1,
+  precision: 0.01,
+};
+
+/**
+ * Create a spring-based animation for smooth, physics-based motion.
+ *
+ * Uses variable frame rate timing based on `requestAnimationFrame` timestamps
+ * to ensure consistent animation speed across different devices and frame rates.
+ * Large time deltas (e.g., from tab backgrounding) are clamped to maintain
+ * simulation stability.
+ *
+ * @param initialValue - Starting value for the spring
+ * @param config - Spring physics configuration
+ * @returns Spring instance for controlling the animation
+ *
+ * @example
+ * ```ts
+ * const x = spring(0, { stiffness: 120, damping: 14 });
+ * x.onChange((value) => {
+ *   element.style.transform = `translateX(${value}px)`;
+ * });
+ * await x.to(100);
+ * ```
+ */
+export const spring = (initialValue: number, config: SpringConfig = {}): Spring => {
+  const { stiffness, damping, mass, precision } = {
+    ...DEFAULT_SPRING_CONFIG,
+    ...config,
+  };
+
+  let current = initialValue;
+  let velocity = 0;
+  let target = initialValue;
+  let animationFrame: number | null = null;
+  let resolvePromise: (() => void) | null = null;
+  let lastTime: number | null = null;
+  const listeners = new Set<(value: number) => void>();
+
+  const notifyListeners = () => {
+    for (const listener of listeners) {
+      listener(current);
+    }
+  };
+
+  const step = (timestamp: number) => {
+    // Calculate time delta (in seconds) from last frame
+    // If this is the first frame, use a sensible default (1/60s)
+    // This ensures the animation speed is independent of frame rate
+    const deltaTime = lastTime !== null ? (timestamp - lastTime) / 1000 : 1 / 60;
+    // Clamp large deltas to prevent instability (e.g. tab backgrounding)
+    // Maximum delta of 1/30s (~33ms) keeps simulation stable
+    const clampedDelta = Math.min(deltaTime, 1 / 30);
+    lastTime = timestamp;
+
+    // Spring physics calculation
+    const displacement = current - target;
+    const springForce = -stiffness * displacement;
+    const dampingForce = -damping * velocity;
+    const acceleration = (springForce + dampingForce) / mass;
+
+    velocity += acceleration * clampedDelta;
+    current += velocity * clampedDelta;
+
+    notifyListeners();
+
+    // Check if spring has settled
+    if (Math.abs(velocity) < precision && Math.abs(displacement) < precision) {
+      current = target;
+      velocity = 0;
+      animationFrame = null;
+      notifyListeners();
+      resolvePromise?.();
+      resolvePromise = null;
+      return;
+    }
+
+    animationFrame = requestAnimationFrame(step);
+  };
+
+  return {
+    to(newTarget: number): Promise<void> {
+      target = newTarget;
+
+      if (animationFrame !== null) {
+        cancelAnimationFrame(animationFrame);
+      }
+
+      // Resolve any pending promise from a previous to() call
+      // This ensures all returned promises eventually settle
+      resolvePromise?.();
+
+      // Reset lastTime to ensure clean start for new animation
+      lastTime = null;
+
+      return new Promise((resolve) => {
+        resolvePromise = resolve;
+        animationFrame = requestAnimationFrame(step);
+      });
+    },
+
+    current(): number {
+      return current;
+    },
+
+    stop(): void {
+      if (animationFrame !== null) {
+        cancelAnimationFrame(animationFrame);
+        animationFrame = null;
+      }
+      velocity = 0;
+      lastTime = null;
+      resolvePromise?.();
+      resolvePromise = null;
+    },
+
+    onChange(callback: (value: number) => void): () => void {
+      listeners.add(callback);
+      return () => listeners.delete(callback);
+    },
+  };
+};
+
+/**
+ * Preset spring configurations for common use cases.
+ */
+export const springPresets = {
+  /** Gentle, slow-settling spring */
+  gentle: { stiffness: 80, damping: 15 } as SpringConfig,
+  /** Responsive, snappy spring */
+  snappy: { stiffness: 200, damping: 20 } as SpringConfig,
+  /** Bouncy, playful spring */
+  bouncy: { stiffness: 300, damping: 8 } as SpringConfig,
+  /** Stiff, quick spring with minimal overshoot */
+  stiff: { stiffness: 400, damping: 30 } as SpringConfig,
+};