@bquery/bquery 1.1.2 → 1.3.0

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);

package/src/reactive/core.ts

@@ -0,0 +1,93 @@
+/**
+ * Core reactive signals.
+ */
+
+import {
+  getCurrentObserver,
+  registerDependency,
+  scheduleObserver,
+  type ReactiveSource,
+} from './internals';
+
+/**
+ * A reactive value container that notifies subscribers on change.
+ *
+ * Signals are the foundational primitive of the reactive system.
+ * Reading a signal's value inside an effect or computed automatically
+ * establishes a reactive dependency.
+ *
+ * @template T - The type of the stored value
+ */
+export class Signal<T> implements ReactiveSource {
+  private subscribers = new Set<() => void>();
+
+  /**
+   * Creates a new signal with an initial value.
+   * @param _value - The initial value
+   */
+  constructor(private _value: T) {}
+
+  /**
+   * Gets the current value and tracks the read if inside an observer.
+   * During untrack calls, getCurrentObserver returns undefined, preventing dependency tracking.
+   */
+  get value(): T {
+    const current = getCurrentObserver();
+    if (current) {
+      this.subscribers.add(current);
+      registerDependency(current, this);
+    }
+    return this._value;
+  }
+
+  /**
+   * Sets a new value and notifies all subscribers if the value changed.
+   * Uses Object.is for equality comparison.
+   */
+  set value(next: T) {
+    if (Object.is(this._value, next)) return;
+    this._value = next;
+    // 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);
+    }
+  }
+
+  /**
+   * Reads the current value without tracking.
+   * Useful when you need the value but don't want to create a dependency.
+   *
+   * @returns The current value
+   */
+  peek(): T {
+    return this._value;
+  }
+
+  /**
+   * Updates the value using a function.
+   * Useful for updates based on the current value.
+   *
+   * @param updater - Function that receives current value and returns new value
+   */
+  update(updater: (current: T) => T): void {
+    this.value = updater(this._value);
+  }
+
+  /**
+   * Removes an observer from this signal's subscriber set.
+   * @internal
+   */
+  unsubscribe(observer: () => void): void {
+    this.subscribers.delete(observer);
+  }
+}
+
+/**
+ * Creates a new reactive signal.
+ *
+ * @template T - The type of the signal value
+ * @param value - The initial value
+ * @returns A new Signal instance
+ */
+export const signal = <T>(value: T): Signal<T> => new Signal(value);

package/src/reactive/effect.ts

@@ -0,0 +1,43 @@
+/**
+ * Reactive effects.
+ */
+
+import { CleanupFn, Observer, track, clearDependencies } from './internals';
+
+/**
+ * Creates a side effect that automatically re-runs when dependencies change.
+ *
+ * The effect runs immediately upon creation and then re-runs whenever
+ * any signal or computed value read inside it changes.
+ *
+ * @param fn - The effect function to run
+ * @returns A cleanup function to stop the effect
+ */
+export const effect = (fn: () => void | CleanupFn): CleanupFn => {
+  let cleanupFn: CleanupFn | void;
+  let isDisposed = false;
+
+  const observer: Observer = () => {
+    if (isDisposed) return;
+
+    if (cleanupFn) {
+      cleanupFn();
+    }
+
+    // Clear old dependencies before running to avoid stale subscriptions
+    clearDependencies(observer);
+
+    cleanupFn = track(observer, fn);
+  };
+
+  observer();
+
+  return () => {
+    isDisposed = true;
+    if (cleanupFn) {
+      cleanupFn();
+    }
+    // Clean up all dependencies when effect is disposed
+    clearDependencies(observer);
+  };
+};

package/src/reactive/index.ts

@@ -1,22 +1,23 @@
-/**
- * Reactive module providing fine-grained reactivity primitives.
- *
- * @module bquery/reactive
- */
-
-export {
-  Computed,
-  Signal,
-  batch,
-  computed,
-  effect,
-  isComputed,
-  isSignal,
-  persistedSignal,
-  readonly,
-  signal,
-  untrack,
-  watch,
-} from './signal';
-
-export type { CleanupFn, Observer, ReadonlySignal } from './signal';
+/**
+ * Reactive module providing fine-grained reactivity primitives.
+ *
+ * @module bquery/reactive
+ */
+
+export {
+  Computed,
+  Signal,
+  batch,
+  computed,
+  effect,
+  isComputed,
+  isSignal,
+  linkedSignal,
+  persistedSignal,
+  readonly,
+  signal,
+  untrack,
+  watch,
+} from './signal';
+
+export type { CleanupFn, LinkedSignal, Observer, ReadonlySignal } from './signal';

package/src/reactive/internals.ts

@@ -0,0 +1,105 @@
+/**
+ * Internal reactive plumbing shared across primitives.
+ * @internal
+ */
+
+export type Observer = () => void;
+export type CleanupFn = () => void;
+
+/**
+ * Interface for reactive sources (Signals, Computed) that can unsubscribe observers.
+ * @internal
+ */
+export interface ReactiveSource {
+  unsubscribe(observer: Observer): void;
+}
+
+const observerStack: Observer[] = [];
+let batchDepth = 0;
+const pendingObservers = new Set<Observer>();
+
+// Track dependencies for each observer to enable cleanup
+const observerDependencies = new WeakMap<Observer, Set<ReactiveSource>>();
+
+export const track = <T>(observer: Observer, fn: () => T): T => {
+  observerStack.push(observer);
+  try {
+    return fn();
+  } finally {
+    observerStack.pop();
+  }
+};
+
+export const getCurrentObserver = (): Observer | undefined =>
+  observerStack[observerStack.length - 1];
+
+/**
+ * Executes a function without exposing the current observer to dependencies.
+ * Unlike disabling tracking globally, this still allows nested reactive internals
+ * (e.g., computed recomputation) to track their own dependencies.
+ * @internal
+ */
+export const withoutCurrentObserver = <T>(fn: () => T): T => {
+  // Push undefined to temporarily "hide" the current observer
+  // This way, Signal.value reads won't link to the previous observer,
+  // but nested track() calls (e.g., computed recompute) still work normally.
+  observerStack.push(undefined as unknown as Observer);
+  try {
+    return fn();
+  } finally {
+    observerStack.pop();
+  }
+};
+
+export const scheduleObserver = (observer: Observer): void => {
+  if (batchDepth > 0) {
+    pendingObservers.add(observer);
+    return;
+  }
+  observer();
+};
+
+const flushObservers = (): void => {
+  for (const observer of Array.from(pendingObservers)) {
+    pendingObservers.delete(observer);
+    observer();
+  }
+};
+
+export const beginBatch = (): void => {
+  batchDepth += 1;
+};
+
+export const endBatch = (): void => {
+  batchDepth -= 1;
+  if (batchDepth === 0) {
+    flushObservers();
+  }
+};
+
+/**
+ * Registers a dependency between an observer and a reactive source.
+ * @internal
+ */
+export const registerDependency = (observer: Observer, source: ReactiveSource): void => {
+  let deps = observerDependencies.get(observer);
+  if (!deps) {
+    deps = new Set();
+    observerDependencies.set(observer, deps);
+  }
+  deps.add(source);
+};
+
+/**
+ * Clears all dependencies for an observer, unsubscribing from all sources.
+ * @internal
+ */
+export const clearDependencies = (observer: Observer): void => {
+  const deps = observerDependencies.get(observer);
+  if (deps) {
+    for (const source of deps) {
+      source.unsubscribe(observer);
+    }
+    deps.clear();
+  }
+};

package/src/reactive/linked.ts

@@ -0,0 +1,56 @@
+/**
+ * Linked (writable) computed helpers.
+ */
+
+import { computed, Computed } from './computed';
+
+/**
+ * A writable computed-like signal.
+ */
+export interface LinkedSignal<T> {
+  /** Gets or sets the current value with dependency tracking. */
+  value: T;
+  /** Gets the current value without dependency tracking. */
+  peek(): T;
+}
+
+/**
+ * Creates a writable computed signal by linking a getter and setter.
+ *
+ * @template T - The derived value type
+ * @param getValue - Getter that derives the current value
+ * @param setValue - Setter that writes back to underlying signals
+ * @returns A writable computed-like signal
+ *
+ * @example
+ * ```ts
+ * const first = signal('Ada');
+ * const last = signal('Lovelace');
+ * const fullName = linkedSignal(
+ *   () => `${first.value} ${last.value}`,
+ *   (next) => {
+ *     const [a, b] = next.split(' ');
+ *     first.value = a ?? '';
+ *     last.value = b ?? '';
+ *   }
+ * );
+ * ```
+ */
+export const linkedSignal = <T>(
+  getValue: () => T,
+  setValue: (value: T) => void
+): LinkedSignal<T> => {
+  const derived: Computed<T> = computed(getValue);
+
+  return {
+    get value(): T {
+      return derived.value;
+    },
+    set value(next: T) {
+      setValue(next);
+    },
+    peek(): T {
+      return derived.peek();
+    },
+  };
+};