@lab206/animate 0.1.0

package/src/playback.ts

@@ -0,0 +1,67 @@
+import type { AnimationPlayback, PlayState } from "./types.js";
+
+export interface PlaybackController extends AnimationPlayback {
+  /** @internal */
+  _resolveFinished(): void;
+}
+
+export function createPlayback(handlers: {
+  onCancel: () => void;
+  onComplete: () => void;
+}): PlaybackController {
+  let playState: PlayState = "running";
+  let resolveFinished!: () => void;
+  let rejectFinished!: (reason?: unknown) => void;
+  let settled = false;
+
+  const finished = new Promise<void>((resolve, reject) => {
+    resolveFinished = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    rejectFinished = (reason?: unknown) => {
+      if (settled) return;
+      settled = true;
+      reject(reason ?? abortError());
+    };
+  });
+
+  // Prevent unhandled rejection when nobody awaits cancel.
+  finished.catch(() => {});
+
+  const playback: PlaybackController = {
+    get playState() {
+      return playState;
+    },
+    finished,
+    cancel() {
+      if (playState !== "running") return;
+      playState = "cancelled";
+      handlers.onCancel();
+      rejectFinished();
+    },
+    complete() {
+      if (playState !== "running") return;
+      playState = "finished";
+      handlers.onComplete();
+      resolveFinished();
+    },
+    _resolveFinished() {
+      if (playState === "cancelled") return;
+      playState = "finished";
+      resolveFinished();
+    },
+  };
+
+  return playback;
+}
+
+function abortError(): Error {
+  if (typeof DOMException !== "undefined") {
+    return new DOMException("Animation cancelled", "AbortError");
+  }
+  const err = new Error("Animation cancelled");
+  err.name = "AbortError";
+  return err;
+}

package/src/reduced-motion.ts

@@ -0,0 +1,23 @@
+let override: boolean | null = null;
+
+/**
+ * Detect `prefers-reduced-motion: reduce`.
+ * Safe on server (returns false unless overridden).
+ */
+export function prefersReducedMotion(): boolean {
+  if (override !== null) return override;
+  if (typeof matchMedia !== "function") return false;
+  try {
+    return matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Force reduced-motion on/off (tests, user settings).
+ * Pass `null` to clear the override.
+ */
+export function setReducedMotionOverride(value: boolean | null): void {
+  override = value;
+}

package/src/registry.ts

@@ -0,0 +1,31 @@
+import type { Animatable } from "./types.js";
+import type { AnimationPlayback } from "./types.js";
+
+/** One active animation per signal — new animate() interrupts the previous. */
+const active = new WeakMap<Animatable, AnimationPlayback>();
+
+export function getActive(target: Animatable): AnimationPlayback | undefined {
+  return active.get(target);
+}
+
+export function setActive(
+  target: Animatable,
+  playback: AnimationPlayback,
+): void {
+  active.set(target, playback);
+}
+
+export function clearActive(
+  target: Animatable,
+  playback: AnimationPlayback,
+): void {
+  if (active.get(target) === playback) {
+    active.delete(target);
+  }
+}
+
+/** Cancel the in-flight animation on a signal, if any. */
+export function cancel(target: Animatable): void {
+  const current = active.get(target);
+  current?.cancel();
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+import type { Signal } from "@lab206/core";
+
+/** Easing function: progress 0..1 → eased 0..1. */
+export type EasingFn = (t: number) => number;
+
+/** Named easings shipped with the library. */
+export type EaseName =
+  | "linear"
+  | "easeIn"
+  | "easeOut"
+  | "easeInOut"
+  | "easeInCubic"
+  | "easeOutCubic"
+  | "easeInOutCubic"
+  | "easeInBack"
+  | "easeOutBack"
+  | "easeInOutBack";
+
+export type Ease = EaseName | EasingFn;
+
+/** Playback state of a single animation. */
+export type PlayState = "running" | "finished" | "cancelled";
+
+/**
+ * Handle returned by `animate()`.
+ * - `finished` resolves on natural completion (not on cancel)
+ * - `cancel()` stops mid-flight and leaves the current value
+ * - `complete()` jumps to the end value and finishes
+ */
+export interface AnimationPlayback {
+  readonly playState: PlayState;
+  readonly finished: Promise<void>;
+  cancel(): void;
+  complete(): void;
+}
+
+/** Duration-based tween options. */
+export interface TweenOptions {
+  type?: "tween";
+  /** Duration in milliseconds. Default: 300. */
+  duration?: number;
+  /** Delay before starting, in ms. Default: 0. */
+  delay?: number;
+  /** Easing curve. Default: "easeOut". */
+  ease?: Ease;
+  /** Override the starting value (defaults to `target.peek()`). */
+  from?: number;
+  /**
+   * Honor `prefers-reduced-motion` (jump to end).
+   * Default: true.
+   */
+  respectReducedMotion?: boolean;
+  onUpdate?: (value: number) => void;
+  onComplete?: () => void;
+  onCancel?: () => void;
+}
+
+/** Spring physics options. */
+export interface SpringOptions {
+  type: "spring";
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  /** Initial velocity (units per second). */
+  velocity?: number;
+  /** Settle threshold for position. */
+  restDelta?: number;
+  /** Settle threshold for velocity. */
+  restSpeed?: number;
+  delay?: number;
+  from?: number;
+  respectReducedMotion?: boolean;
+  onUpdate?: (value: number) => void;
+  onComplete?: () => void;
+  onCancel?: () => void;
+}
+
+export type AnimateOptions = TweenOptions | SpringOptions;
+
+/** Anything we can animate — a writable number signal. */
+export type Animatable = Signal<number>;
+
+/** @internal Driver for time + frames (swappable in tests). */
+export interface FrameDriver {
+  now(): number;
+  raf(cb: (time: number) => void): number;
+  caf(id: number): void;
+}