@effect-tui/react 0.1.0-alpha.1

package/src/motion/hooks.ts

@@ -0,0 +1,237 @@
+/**
+ * React hooks for spring animations.
+ */
+
+import { useCallback, useEffect, useRef } from "react"
+import { useRenderer } from "../renderer.js"
+import { MotionValue } from "./motion-value.js"
+import { ColorMotionValue } from "./color-motion-value.js"
+import type { SpringOptions } from "./types.js"
+import type { EventName } from "./event-emitter.js"
+import type { ColorInput } from "./color.js"
+
+// Global requestRender callback - set by useSpringRenderer hook
+let globalRequestRender: (() => void) | null = null
+
+/**
+ * Create a MotionValue. Similar to Motion's useMotionValue.
+ */
+export function useMotionValue<T>(initial: T): MotionValue<T> {
+  const ref = useRef<MotionValue<T> | null>(null)
+  if (!ref.current) {
+    ref.current = new MotionValue(initial)
+  }
+
+  useEffect(() => {
+    return () => ref.current?.destroy()
+  }, [])
+
+  return ref.current
+}
+
+/**
+ * Call this once in your app to connect springs to the renderer.
+ * If no renderer is passed, it will use the nearest RendererContext (useRenderer()).
+ */
+export function useSpringRenderer(renderer?: { requestRender: () => void }) {
+  // Prefer explicit renderer; otherwise pull from context
+  const inferred = renderer ?? useRenderer()
+  useEffect(() => {
+    if (!inferred) return
+    globalRequestRender = inferred.requestRender.bind(inferred)
+    return () => {
+      if (globalRequestRender === inferred.requestRender) {
+        globalRequestRender = null
+      }
+    }
+  }, [inferred])
+}
+
+/**
+ * Create a spring-animated value. When you call set(), it springs to the new value.
+ * Similar to Motion's useSpring.
+ *
+ * OPTIMIZED: Does NOT use React state during animation. Instead:
+ * - Returns MotionValue which you read via mv.get() in draw functions
+ * - Calls renderer.requestRender() directly on each frame
+ * - Bypasses React reconciliation entirely during animation
+ *
+ * @example
+ * const [xMv, setX] = useSpring(0, { visualDuration: 0.5 })
+ * // In canvas draw: const x = xMv.get()
+ * // To animate: setX(100)
+ */
+export function useSpring(initial: number, options?: SpringOptions): [MotionValue<number>, (value: number) => void] {
+  const mv = useMotionValue(initial)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  // Subscribe to changes and request render directly (no setState!)
+  useEffect(() => {
+    return mv.on("change", () => {
+      globalRequestRender?.()
+    })
+  }, [mv])
+
+  const set = useCallback(
+    (target: number) => {
+      mv.set(target, optionsRef.current)
+    },
+    [mv],
+  )
+
+  return [mv, set]
+}
+
+/**
+ * Create multiple spring-animated values. Similar to framer-motion's useSprings.
+ *
+ * @param count - Number of springs to create
+ * @param options - Spring configuration (shared by all springs)
+ * @returns [mvs, setAll] - Array of MotionValues and a setter function
+ *
+ * @example
+ * const [dotMvs, setDots] = useSprings(9, { visualDuration: 0.3, bounce: 0 })
+ *
+ * // Update all with a mapper function
+ * setDots((i) => i === focusedIndex ? 1 : 0)
+ *
+ * // Or update with an array
+ * setDots([0, 0, 1, 0, 0, 0, 0, 0, 0])
+ *
+ * // In draw callback
+ * const brightness = dotMvs[idx].get()
+ */
+export function useSprings(
+  count: number,
+  options?: SpringOptions,
+): [MotionValue<number>[], (values: number[] | ((index: number) => number)) => void] {
+  const mvsRef = useRef<MotionValue<number>[] | null>(null)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  // Create MotionValues on first render
+  if (!mvsRef.current) {
+    mvsRef.current = Array.from({ length: count }, () => new MotionValue(0))
+  }
+
+  // Handle count changes (recreate if count changes)
+  if (mvsRef.current.length !== count) {
+    // Destroy old ones
+    for (const mv of mvsRef.current) {
+      mv.destroy()
+    }
+    mvsRef.current = Array.from({ length: count }, () => new MotionValue(0))
+  }
+
+  const mvs = mvsRef.current
+
+  // Subscribe all to requestRender
+  useEffect(() => {
+    const unsubs = mvs.map((mv) =>
+      mv.on("change", () => {
+        globalRequestRender?.()
+      }),
+    )
+    return () => {
+      for (const unsub of unsubs) unsub()
+    }
+  }, [mvs])
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (mvsRef.current) {
+        for (const mv of mvsRef.current) {
+          mv.destroy()
+        }
+      }
+    }
+  }, [])
+
+  const setAll = useCallback(
+    (values: number[] | ((index: number) => number)) => {
+      const opts = optionsRef.current
+      if (typeof values === "function") {
+        for (let i = 0; i < mvs.length; i++) {
+          mvs[i].set(values(i), opts)
+        }
+      } else {
+        for (let i = 0; i < Math.min(mvs.length, values.length); i++) {
+          mvs[i].set(values[i], opts)
+        }
+      }
+    },
+    [mvs],
+  )
+
+  return [mvs, setAll]
+}
+
+/**
+ * Subscribe to MotionValue events. Similar to Motion's useMotionValueEvent.
+ */
+export function useMotionValueEvent<T, E extends EventName>(
+  mv: MotionValue<T>,
+  event: E,
+  callback: E extends "change" ? (value: T) => void : () => void,
+) {
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  useEffect(() => {
+    return mv.on(event, (v: any) => (callbackRef.current as any)(v))
+  }, [mv, event])
+}
+
+/**
+ * Create a ColorMotionValue hook.
+ */
+export function useColorMotionValue(initial: ColorInput): ColorMotionValue {
+  const ref = useRef<ColorMotionValue | null>(null)
+  if (!ref.current) {
+    ref.current = new ColorMotionValue(initial)
+  }
+
+  useEffect(() => {
+    return () => ref.current?.destroy()
+  }, [])
+
+  return ref.current
+}
+
+/**
+ * Create a spring-animated color. Accepts hex, rgb(), hsl(), or {r,g,b} object.
+ *
+ * @example
+ * const [colorMv, setColor] = useColorSpring("#ff0000", { visualDuration: 0.5 })
+ * setColor("#00ff00")  // Spring to green
+ * setColor("hsl(240, 100%, 50%)")  // Spring to blue
+ *
+ * // In draw callback
+ * const { r, g, b } = colorMv.get()
+ */
+export function useColorSpring(
+  initial: ColorInput,
+  options?: SpringOptions,
+): [ColorMotionValue, (color: ColorInput) => void] {
+  const mv = useColorMotionValue(initial)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+
+  // Subscribe to changes and request render
+  useEffect(() => {
+    return mv._subscribeChannels(() => {
+      globalRequestRender?.()
+    })
+  }, [mv])
+
+  const set = useCallback(
+    (color: ColorInput) => {
+      mv.set(color, optionsRef.current)
+    },
+    [mv],
+  )
+
+  return [mv, set]
+}

package/src/motion/index.ts

@@ -0,0 +1,17 @@
+// Motion-inspired animation system for TUI
+// Analytical spring physics (not Euler integration) + setTimeout-based frame loop
+
+export type { SpringOptions, MotionValue, RGBA, ColorInput } from "./motion-value.js"
+export {
+  motionValue,
+  useMotionValue,
+  useSpring,
+  useSprings,
+  useSpringRenderer,
+  useMotionValueEvent,
+  // Color springs
+  ColorMotionValue,
+  useColorMotionValue,
+  useColorSpring,
+} from "./motion-value.js"
+export { useAnimationFrame } from "./frame.js"

package/src/motion/motion-value.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect } from "vitest"
+import { motionValue } from "./motion-value.js"
+
+describe("MotionValue", () => {
+  describe("basic operations", () => {
+    it("initializes with correct value", () => {
+      const mv = motionValue(100)
+      expect(mv.get()).toBe(100)
+    })
+
+    it("jump() sets value immediately", () => {
+      const mv = motionValue(0)
+      mv.jump(50)
+      expect(mv.get()).toBe(50)
+      expect(mv.getVelocity()).toBe(0)
+    })
+
+    it("jump() stops any active animation", () => {
+      const mv = motionValue(0)
+      mv.set(100) // Start animation
+      expect(mv.isAnimating()).toBe(true)
+      mv.jump(50)
+      expect(mv.isAnimating()).toBe(false)
+      expect(mv.get()).toBe(50)
+    })
+  })
+
+  describe("spring animation", () => {
+    it("set() starts animation toward target", () => {
+      const mv = motionValue(0)
+      mv.set(100)
+      expect(mv.isAnimating()).toBe(true)
+    })
+
+    it("notifies on change", () => {
+      const mv = motionValue(0)
+      const values: number[] = []
+      mv.on("change", (v) => values.push(v))
+      mv.jump(50)
+      expect(values).toContain(50)
+    })
+
+    it("notifies animationStart and animationComplete", async () => {
+      const mv = motionValue(0)
+      let started = false
+      let completed = false
+      mv.on("animationStart", () => {
+        started = true
+      })
+      mv.on("animationComplete", () => {
+        completed = true
+      })
+
+      mv.set(100, { stiffness: 1000, damping: 50 }) // Fast spring
+      expect(started).toBe(true)
+
+      // Wait for animation to complete
+      await new Promise((r) => setTimeout(r, 500))
+      expect(completed).toBe(true)
+    })
+
+    it("stop() halts animation", () => {
+      const mv = motionValue(0)
+      mv.set(100)
+      expect(mv.isAnimating()).toBe(true)
+      mv.stop()
+      expect(mv.isAnimating()).toBe(false)
+    })
+  })
+
+  describe("spring physics correctness", () => {
+    it("reaches target value when settled", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { stiffness: 500, damping: 30 })
+
+      await new Promise((r) => setTimeout(r, 1000))
+      expect(mv.get()).toBeCloseTo(100, 1)
+    })
+
+    it("velocity is zero when settled", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { stiffness: 500, damping: 30 })
+
+      await new Promise((r) => setTimeout(r, 1000))
+      expect(Math.abs(mv.getVelocity())).toBeLessThan(0.1)
+    })
+  })
+
+  describe("retargeting", () => {
+    it("preserves velocity when retargeting mid-animation", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { stiffness: 100, damping: 10 })
+
+      // Wait a bit for velocity to build up
+      await new Promise((r) => setTimeout(r, 50))
+
+      const velocityBefore = mv.getVelocity()
+      const positionBefore = mv.get()
+
+      // Retarget to opposite direction
+      mv.set(0, { stiffness: 100, damping: 10 })
+
+      // Velocity should be preserved (same value, continuing momentum)
+      expect(mv.getVelocity()).toBeCloseTo(velocityBefore, 1)
+      expect(mv.get()).toBeCloseTo(positionBefore, 1)
+    })
+
+    it("curves smoothly when reversing direction", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { stiffness: 100, damping: 15 })
+
+      // Wait for positive velocity
+      await new Promise((r) => setTimeout(r, 30))
+      const velBefore = mv.getVelocity()
+      expect(velBefore).toBeGreaterThan(0)
+
+      // Retarget back to 0
+      mv.set(0, { stiffness: 100, damping: 15 })
+
+      // Should still have positive velocity immediately after retarget
+      expect(mv.getVelocity()).toBeGreaterThan(0)
+
+      // Wait a bit - velocity should decrease and eventually reverse
+      await new Promise((r) => setTimeout(r, 100))
+      // Position should have moved past where it was (momentum carried it)
+      // or started moving back toward 0
+    })
+  })
+
+  describe("visualDuration/bounce API", () => {
+    it("visualDuration controls animation speed", async () => {
+      const fast = motionValue(0)
+      const slow = motionValue(0)
+
+      fast.set(100, { visualDuration: 0.1, bounce: 0 })
+      slow.set(100, { visualDuration: 0.5, bounce: 0 })
+
+      await new Promise((r) => setTimeout(r, 150))
+
+      // Fast should be closer to target
+      expect(Math.abs(100 - fast.get())).toBeLessThan(Math.abs(100 - slow.get()))
+    })
+
+    it("bounce: 0 means no overshoot (critically damped)", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { visualDuration: 0.3, bounce: 0 })
+
+      const values: number[] = []
+      mv.on("change", (v) => values.push(v))
+
+      await new Promise((r) => setTimeout(r, 500))
+
+      // Should never exceed target
+      const max = Math.max(...values)
+      expect(max).toBeLessThanOrEqual(100.5) // Small tolerance for numerical precision
+    })
+
+    it("bounce > 0 allows overshoot", async () => {
+      const mv = motionValue(0)
+      mv.set(100, { visualDuration: 0.3, bounce: 0.3 })
+
+      const values: number[] = []
+      mv.on("change", (v) => values.push(v))
+
+      await new Promise((r) => setTimeout(r, 500))
+
+      // Should overshoot target
+      const max = Math.max(...values)
+      expect(max).toBeGreaterThan(100)
+    })
+  })
+
+  describe("cleanup", () => {
+    it("destroy() stops animation and clears subscribers", () => {
+      const mv = motionValue(0)
+      mv.on("change", () => {
+        // subscriber added
+      })
+
+      mv.set(100)
+      mv.destroy()
+
+      expect(mv.isAnimating()).toBe(false)
+
+      // After destroy, just verify it doesn't throw
+      mv.jump(50)
+    })
+
+    it("unsubscribe function works", () => {
+      const mv = motionValue(0)
+      const values: number[] = []
+      const unsub = mv.on("change", (v) => values.push(v))
+
+      mv.jump(10)
+      expect(values).toContain(10)
+
+      unsub()
+      mv.jump(20)
+      expect(values).not.toContain(20)
+    })
+  })
+})
+
+describe("createSpringResolver", () => {
+  // Test the analytical spring formulas directly
+  // These are internal but critical for correctness
+
+  it("initial position equals from", () => {
+    const mv = motionValue(50)
+    mv.set(100, { stiffness: 100, damping: 10 })
+    // At t=0, should still be at initial position
+    expect(mv.get()).toBe(50)
+  })
+
+  it("initial velocity is preserved", () => {
+    const mv = motionValue(0)
+    mv.set(100, { stiffness: 100, damping: 10 })
+
+    // Initial velocity should be 0 (starting from rest)
+    expect(mv.getVelocity()).toBe(0)
+  })
+})

package/src/motion/motion-value.ts

@@ -0,0 +1,140 @@
+/**
+ * MotionValue - tracks animated values with spring physics.
+ * Inspired by framer-motion's MotionValue.
+ */
+
+import { subscribeFrame } from "./frame.js"
+import { EventEmitter } from "./event-emitter.js"
+import { createSpringResolver, springFromVisualDuration } from "./spring-math.js"
+import { type SpringOptions, DEFAULT_SPRING_OPTIONS } from "./types.js"
+
+/** Create a MotionValue. Factory function like Motion's motionValue(). */
+export function motionValue<T>(initial: T): MotionValue<T> {
+  return new MotionValue(initial)
+}
+
+/**
+ * MotionValue tracks a value and its velocity, supporting spring animations.
+ */
+export class MotionValue<T = number> extends EventEmitter<T> {
+  private current: T
+  private target: T
+  private velocity = 0
+  private animation: { stop: () => void } | null = null
+
+  constructor(initial: T) {
+    super()
+    this.current = initial
+    this.target = initial
+  }
+
+  /** Get the current value */
+  get(): T {
+    return this.current
+  }
+
+  /** Set value immediately (no animation) */
+  jump(value: T) {
+    this.stop()
+    this.current = value
+    this.target = value
+    this.velocity = 0
+    this.notify("change", value)
+  }
+
+  /** Set target and animate with spring */
+  set(value: T, options?: SpringOptions) {
+    if (typeof value !== "number" || typeof this.current !== "number") {
+      // Non-numeric: jump immediately
+      this.jump(value)
+      return
+    }
+    this.target = value
+    this.animateSpring(options)
+  }
+
+  /** Get current velocity */
+  getVelocity(): number {
+    return this.velocity
+  }
+
+  /** Check if currently animating */
+  isAnimating(): boolean {
+    return this.animation !== null
+  }
+
+  /** Stop any active animation */
+  stop() {
+    if (this.animation) {
+      this.animation.stop()
+      this.animation = null
+    }
+  }
+
+  /** Destroy and clean up */
+  destroy() {
+    this.stop()
+    this.clearSubscribers()
+  }
+
+  private animateSpring(options?: SpringOptions) {
+    this.stop()
+
+    const opts = { ...DEFAULT_SPRING_OPTIONS, ...options }
+    const from = this.current as number
+    const to = this.target as number
+
+    if (from === to) return
+
+    // Derive stiffness/damping from visualDuration/bounce if provided
+    let { stiffness, damping, mass } = opts
+    if (opts.visualDuration && opts.visualDuration > 0) {
+      const derived = springFromVisualDuration(opts.visualDuration, opts.bounce)
+      stiffness = derived.stiffness
+      damping = derived.damping
+    }
+
+    // Create spring resolver (analytical solution)
+    const resolver = createSpringResolver(from, to, this.velocity, stiffness, damping, mass)
+
+    this.notify("animationStart", undefined)
+    const startTime = Date.now()
+
+    const unsubscribe = subscribeFrame(() => {
+      const elapsed = (Date.now() - startTime) / 1000 // seconds
+
+      const state = resolver(elapsed)
+      this.current = state.value as T
+      this.velocity = state.velocity
+
+      this.notify("change", this.current)
+
+      if (state.done) {
+        this.current = to as T
+        this.velocity = 0
+        this.animation = null
+        this.notify("change", this.current)
+        this.notify("animationComplete", undefined)
+        unsubscribe()
+      }
+    })
+
+    this.animation = { stop: unsubscribe }
+  }
+}
+
+// Re-export everything for backwards compatibility
+export { type SpringOptions, DEFAULT_SPRING_OPTIONS } from "./types.js"
+export type { EventName, Subscriber } from "./event-emitter.js"
+export { createSpringResolver, springFromVisualDuration, isSpringSettled } from "./spring-math.js"
+export { ColorMotionValue } from "./color-motion-value.js"
+export {
+  useMotionValue,
+  useSpring,
+  useSprings,
+  useSpringRenderer,
+  useMotionValueEvent,
+  useColorMotionValue,
+  useColorSpring,
+} from "./hooks.js"
+export type { RGBA, ColorInput } from "./color.js"