@bquery/bquery 1.2.0 → 1.3.0

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;

package/src/reactive/batch.ts

@@ -0,0 +1,22 @@
+/**
+ * Batched reactive updates.
+ */
+
+import { beginBatch, endBatch } from './internals';
+
+/**
+ * Batches multiple signal updates into a single notification cycle.
+ *
+ * Updates made inside the batch function are deferred until the batch
+ * completes, preventing intermediate re-renders and improving performance.
+ *
+ * @param fn - Function containing multiple signal updates
+ */
+export const batch = (fn: () => void): void => {
+  beginBatch();
+  try {
+    fn();
+  } finally {
+    endBatch();
+  }
+};

package/src/reactive/computed.ts

@@ -0,0 +1,92 @@
+/**
+ * Computed reactive values.
+ */
+
+import {
+  clearDependencies,
+  getCurrentObserver,
+  registerDependency,
+  scheduleObserver,
+  track,
+  type ReactiveSource,
+} from './internals';
+
+/**
+ * A computed value that derives from other reactive sources.
+ *
+ * Computed values are lazily evaluated and cached. They only
+ * recompute when their dependencies change.
+ *
+ * @template T - The type of the computed value
+ */
+export class Computed<T> implements ReactiveSource {
+  private cachedValue!: T;
+  private dirty = true;
+  private subscribers = new Set<() => void>();
+  private readonly markDirty = () => {
+    this.dirty = true;
+    // Create snapshot to avoid issues with subscribers modifying the set during iteration
+    const subscribersSnapshot = Array.from(this.subscribers);
+    for (const subscriber of subscribersSnapshot) {
+      scheduleObserver(subscriber);
+    }
+  };
+
+  /**
+   * Creates a new computed value.
+   * @param compute - Function that computes the value
+   */
+  constructor(private readonly compute: () => T) {}
+
+  /**
+   * Gets the computed value, recomputing if dependencies changed.
+   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
+   */
+  get value(): T {
+    const current = getCurrentObserver();
+    if (current) {
+      this.subscribers.add(current);
+      registerDependency(current, this);
+    }
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Reads the current computed value without tracking.
+   * Useful when you need the value but don't want to create a dependency.
+   *
+   * @returns The current cached value (recomputes if dirty)
+   */
+  peek(): T {
+    if (this.dirty) {
+      this.dirty = false;
+      // Clear old dependencies before recomputing
+      clearDependencies(this.markDirty);
+      this.cachedValue = track(this.markDirty, this.compute);
+    }
+    return this.cachedValue;
+  }
+
+  /**
+   * Removes an observer from this computed's subscriber set.
+   * @internal
+   */
+  unsubscribe(observer: () => void): void {
+    this.subscribers.delete(observer);
+  }
+}
+
+/**
+ * Creates a new computed value.
+ *
+ * @template T - The type of the computed value
+ * @param fn - Function that computes the value from reactive sources
+ * @returns A new Computed instance
+ */
+export const computed = <T>(fn: () => T): Computed<T> => new Computed(fn);