@bquery/bquery 1.2.0 → 1.4.0

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,
+};

package/src/motion/stagger.ts

@@ -0,0 +1,43 @@
+/**
+ * Stagger helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { StaggerFunction, StaggerOptions } from './types';
+
+/**
+ * Create a staggered delay function for list animations.
+ *
+ * @param step - Delay between items in milliseconds
+ * @param options - Stagger configuration
+ * @returns Function that returns delay for a given index
+ *
+ * @example
+ * ```ts
+ * const delay = stagger(50, { from: 'center' });
+ * delay(0, 3); // 50
+ * delay(1, 3); // 0
+ * ```
+ */
+export const stagger = (step: number, options: StaggerOptions = {}): StaggerFunction => {
+  const { start = 0, from = 'start', easing } = options;
+
+  return (index: number, total = 0): number => {
+    const origin =
+      typeof from === 'number'
+        ? from
+        : from === 'center'
+          ? (total - 1) / 2
+          : from === 'end'
+            ? total - 1
+            : 0;
+
+    const distance = Math.abs(index - origin);
+    const maxDistance = total > 1 ? Math.max(origin, total - 1 - origin) : 1;
+    const normalized = maxDistance === 0 ? 0 : distance / maxDistance;
+    const eased = easing ? easing(normalized) * maxDistance : distance;
+
+    return start + eased * step;
+  };
+};

package/src/motion/timeline.ts

@@ -0,0 +1,246 @@
+/**
+ * Timeline and sequence helpers.
+ *
+ * @module bquery/motion
+ */
+
+import { animate, applyFinalKeyframeStyles } from './animate';
+import { prefersReducedMotion } from './reduced-motion';
+import type {
+  SequenceOptions,
+  SequenceStep,
+  TimelineConfig,
+  TimelineControls,
+  TimelineStep,
+} from './types';
+
+const resolveTimeValue = (value?: number | string): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.endsWith('ms')) {
+      const parsed = Number.parseFloat(trimmed.slice(0, -2));
+      return Number.isFinite(parsed) ? parsed : 0;
+    }
+    if (trimmed.endsWith('s')) {
+      const parsed = Number.parseFloat(trimmed.slice(0, -1));
+      return Number.isFinite(parsed) ? parsed * 1000 : 0;
+    }
+    const parsed = Number.parseFloat(trimmed);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+};
+
+const resolveAt = (at: TimelineStep['at'], previousEnd: number): number => {
+  if (typeof at === 'number') return at;
+  if (typeof at === 'string') {
+    const match = /^([+-])=(\d+(?:\.\d+)?)$/.exec(at);
+    if (match) {
+      const delta = Number.parseFloat(match[2]);
+      if (!Number.isFinite(delta)) return previousEnd;
+      return match[1] === '+' ? previousEnd + delta : previousEnd - delta;
+    }
+  }
+  return previousEnd;
+};
+
+const normalizeDuration = (options?: KeyframeAnimationOptions): number => {
+  const baseDuration = resolveTimeValue(options?.duration as number | string | undefined);
+  const endDelay = resolveTimeValue(options?.endDelay as number | string | undefined);
+  const rawIterations = options?.iterations ?? 1;
+
+  // Handle infinite iterations - treat as a special case with a very large duration
+  // In practice, infinite iterations shouldn't be used in timelines as they never end
+  if (rawIterations === Infinity) {
+    // Return a large sentinel value - timeline calculations will be incorrect,
+    // but this at least prevents NaN/Infinity from breaking scheduling
+    return Number.MAX_SAFE_INTEGER;
+  }
+
+  // Per Web Animations spec, iterations must be a non-negative number
+  // Treat negative as 0 (only endDelay duration)
+  const iterations = Math.max(0, rawIterations);
+
+  // Total duration = (baseDuration * iterations) + endDelay
+  // Note: endDelay is applied once at the end, after all iterations
+  return baseDuration * iterations + endDelay;
+};
+
+const scheduleSteps = (steps: TimelineStep[]) => {
+  let previousEnd = 0;
+  return steps.map((step) => {
+    const baseStart = resolveAt(step.at, previousEnd);
+    const stepDelay = resolveTimeValue(step.options?.delay as number | string | undefined);
+    const start = Math.max(0, baseStart + stepDelay);
+    const duration = normalizeDuration(step.options);
+    const end = start + duration;
+    previousEnd = Math.max(previousEnd, end);
+    return { step, start, end, duration };
+  });
+};
+
+/**
+ * Run a list of animations sequentially.
+ *
+ * @param steps - Steps to run in order
+ * @param options - Sequence configuration
+ */
+export const sequence = async (
+  steps: SequenceStep[],
+  options: SequenceOptions = {}
+): Promise<void> => {
+  const { stagger, onFinish } = options;
+  const total = steps.length;
+
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index];
+    const delay = stagger ? stagger(index, total) : 0;
+    if (delay > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+    await animate(step.target, step);
+  }
+
+  onFinish?.();
+};
+
+/**
+ * Create a timeline controller for multiple animations.
+ *
+ * @param initialSteps - Steps for the timeline
+ * @param config - Timeline configuration
+ */
+export const timeline = (
+  initialSteps: TimelineStep[] = [],
+  config: TimelineConfig = {}
+): TimelineControls => {
+  const steps = [...initialSteps];
+  const listeners = new Set<() => void>();
+  let animations: Array<{ animation: Animation; step: TimelineStep; start: number }> = [];
+  let totalDuration = 0;
+  let reducedMotionApplied = false;
+  let finalized = false;
+
+  const { commitStyles = true, respectReducedMotion = true, onFinish } = config;
+
+  const finalize = () => {
+    if (finalized) return;
+    finalized = true;
+
+    if (commitStyles) {
+      for (const item of animations) {
+        const { animation, step } = item;
+        if (typeof animation.commitStyles === 'function') {
+          animation.commitStyles();
+        } else {
+          applyFinalKeyframeStyles(step.target, step.keyframes);
+        }
+        animation.cancel();
+      }
+    }
+
+    listeners.forEach((listener) => listener());
+    onFinish?.();
+  };
+
+  const buildAnimations = () => {
+    animations.forEach(({ animation }) => animation.cancel());
+    animations = [];
+    finalized = false;
+
+    const schedule = scheduleSteps(steps);
+    totalDuration = schedule.length ? Math.max(...schedule.map((item) => item.end)) : 0;
+
+    if (respectReducedMotion && prefersReducedMotion()) {
+      if (commitStyles) {
+        schedule.forEach(({ step }) => applyFinalKeyframeStyles(step.target, step.keyframes));
+      }
+      reducedMotionApplied = true;
+      return;
+    }
+
+    // Check if Web Animations API is available on all targets
+    const animateUnavailable = schedule.some(
+      ({ step }) => typeof (step.target as HTMLElement).animate !== 'function'
+    );
+    if (animateUnavailable) {
+      if (commitStyles) {
+        schedule.forEach(({ step }) => applyFinalKeyframeStyles(step.target, step.keyframes));
+      }
+      reducedMotionApplied = true;
+      return;
+    }
+
+    reducedMotionApplied = false;
+    animations = schedule.map(({ step, start }) => {
+      const { delay: _delay, ...options } = step.options ?? {};
+      const animation = step.target.animate(step.keyframes, {
+        ...options,
+        delay: start,
+        fill: options.fill ?? 'both',
+      });
+      return { animation, step, start };
+    });
+  };
+
+  return {
+    add(step: TimelineStep): void {
+      steps.push(step);
+    },
+
+    duration(): number {
+      if (!steps.length) return 0;
+      if (!animations.length) {
+        const schedule = scheduleSteps(steps);
+        return Math.max(...schedule.map((item) => item.end));
+      }
+      return totalDuration;
+    },
+
+    async play(): Promise<void> {
+      buildAnimations();
+
+      if (reducedMotionApplied || animations.length === 0) {
+        finalize();
+        return;
+      }
+
+      const finishPromises = animations.map((item) =>
+        item.animation.finished.catch(() => undefined)
+      );
+      await Promise.all(finishPromises);
+      finalize();
+    },
+
+    pause(): void {
+      if (reducedMotionApplied) return;
+      animations.forEach(({ animation }) => animation.pause());
+    },
+
+    resume(): void {
+      if (reducedMotionApplied) return;
+      animations.forEach(({ animation }) => animation.play());
+    },
+
+    stop(): void {
+      animations.forEach(({ animation }) => animation.cancel());
+      animations = [];
+      reducedMotionApplied = false;
+    },
+
+    seek(time: number): void {
+      if (reducedMotionApplied) return;
+      animations.forEach(({ animation }) => {
+        // currentTime is measured from the beginning of the animation including delay,
+        // so we set it directly to the requested timeline time
+        animation.currentTime = time;
+      });
+    },
+
+    onFinish(callback: () => void): () => void {
+      listeners.add(callback);
+      return () => listeners.delete(callback);
+    },
+  };
+};

package/src/motion/transition.ts

@@ -0,0 +1,51 @@
+/**
+ * View transition helpers.
+ *
+ * @module bquery/motion
+ */
+
+import type { TransitionOptions } from './types';
+
+/** 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;
+
+  // SSR/non-DOM environment fallback
+  if (typeof document === 'undefined') {
+    update();
+    return;
+  }
+
+  const doc = document as DocumentWithTransition;
+
+  if (doc.startViewTransition) {
+    await doc.startViewTransition(() => update()).finished;
+    return;
+  }
+
+  update();
+};

package/src/motion/types.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared Motion module types.
+ *
+ * @module bquery/motion
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Stagger delay function signature.
+ */
+export type StaggerFunction = (index: number, total: number) => number;
+
+/**
+ * Extended options for group FLIP animations.
+ */
+export interface FlipGroupOptions extends FlipOptions {
+  /** Optional stagger delay function */
+  stagger?: StaggerFunction;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Web Animations helper configuration.
+ */
+export interface AnimateOptions {
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options (duration, easing, etc.) */
+  options?: KeyframeAnimationOptions;
+  /** Commit final styles to the element (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when animation completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Stagger helper configuration.
+ */
+export interface StaggerOptions {
+  /** Start delay in milliseconds (default: 0) */
+  start?: number;
+  /** Origin index or keyword (default: 'start') */
+  from?: 'start' | 'center' | 'end' | number;
+  /** Optional easing function for normalized distance */
+  easing?: EasingFunction;
+}
+
+/**
+ * Easing function signature.
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Sequence step configuration.
+ */
+export interface SequenceStep extends AnimateOptions {
+  /** Target element to animate */
+  target: Element;
+}
+
+/**
+ * Sequence run configuration.
+ */
+export interface SequenceOptions {
+  /** Optional stagger delay between steps */
+  stagger?: StaggerFunction;
+  /** Callback when sequence completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline step configuration.
+ */
+export interface TimelineStep {
+  /** Target element to animate */
+  target: Element;
+  /** Keyframes to animate */
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;
+  /** Animation options for this step */
+  options?: KeyframeAnimationOptions;
+  /** Absolute or relative start time in milliseconds */
+  at?: number | `+=${number}` | `-=${number}`;
+  /** Optional label for debugging */
+  label?: string;
+}
+
+/**
+ * Timeline configuration.
+ */
+export interface TimelineConfig {
+  /** Commit final styles when timeline completes (default: true) */
+  commitStyles?: boolean;
+  /** Respect prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+  /** Callback when timeline completes */
+  onFinish?: () => void;
+}
+
+/**
+ * Timeline controls.
+ */
+export interface TimelineControls {
+  /** Play all steps */
+  play(): Promise<void>;
+  /** Pause animations */
+  pause(): void;
+  /** Resume animations */
+  resume(): void;
+  /** Stop and cancel animations */
+  stop(): void;
+  /** Seek to a specific time in milliseconds */
+  seek(time: number): void;
+  /** Add a step to the timeline */
+  add(step: TimelineStep): void;
+  /** Total timeline duration in milliseconds */
+  duration(): number;
+  /** Subscribe to finish events */
+  onFinish(callback: () => void): () => void;
+}
+
+/**
+ * Scroll animation configuration.
+ */
+export interface ScrollAnimateOptions extends AnimateOptions {
+  /** IntersectionObserver root */
+  root?: Element | Document | null;
+  /** Root margin for observer */
+  rootMargin?: string;
+  /** Intersection thresholds */
+  threshold?: number | number[];
+  /** Trigger only once (default: true) */
+  once?: boolean;
+  /** Callback when element enters the viewport */
+  onEnter?: (element: Element) => void;
+}
+
+/**
+ * Cleanup function for scroll animations.
+ */
+export type ScrollAnimateCleanup = () => void;