Animate.js

// ============================================================================
// Animate.js - the animation clock: Animate.Real + its shared-frame driver
// ============================================================================
//
// The shared-resource driver shape (the third pattern alongside Network's independent
// fetch and Dom's tree reconcile). Animate.Real(from, to, durationMs) returns a reactive
// Real that starts at `from` and is READABLE immediately (unlike a Network response it is
// not locked - an animation shows its current value while it runs), and emits an animation
// request into the module-scoped 'real' channel. The driver keeps ONE frame loop and a
// per-state table of active animations; on each frame it advances them all and sets their
// states via addUpdates (which re-renders), removing each when it reaches `to`.
//
// Like the request, the emission carries the STATE itself as a field (case B), never a
// settable id: the native driver derives the settable it sets with Reactive.Reference. An
// animation is keyed by that state id, and by a signature (from|to|durationMs) so changing
// the target restarts it while an unchanged one keeps its start time.
//
// The clock and the frame scheduler are injected via the driver's Mount params (`now`,
// `requestFrame`) so the loop is deterministic under test; they default to the browser's
// performance clock and requestAnimationFrame (with a setTimeout fallback).
// ----------------------------------------------------------------------------

Reactive.Module('Animate', () => {

  // Real(from, to, durationMs) -> a Maths.Real that animates from `from` to `to` over
  // durationMs, updating each frame. Readable immediately (starts at `from`).
  Reactive.Function('Real', () => {
    const from = Reactive.Argument(Maths.Real)
    const to = Reactive.Argument(Maths.Real)
    const durationMs = Reactive.Argument(Maths.Real)
    const fromValue = Reactive.Value(from)
    const value = Reactive.State(Maths.Real)(fromValue)
    Reactive.Emit('real', { value: value, from: fromValue, to: Reactive.Value(to), durationMs: Reactive.Value(durationMs) })
    return value
  })

  // The animation driver: one frame loop, a per-state active table, ticks -> addUpdates.
  Reactive.Driver('real', (params, addUpdates) => {
    const RV = Reactive._internal.ReactiveValue
    const RG = Reactive._internal.ReactiveGettable
    const RS = Reactive._internal.ReactiveSettable

    const now = (params != null && params.now != null)
      ? params.now
      : (typeof performance !== 'undefined' && performance.now ? () => performance.now() : () => Date.now())
    const requestFrame = (params != null && params.requestFrame != null)
      ? params.requestFrame
      : (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => setTimeout(cb, 16))

    const active = {}   // settableId -> { from, to, durationMs, startTime, signature }
    const done = {}     // settableId -> signature that has already reached its target
    let running = false

    function ensureRunning() {
      if (running) {
        return
      }
      running = true
      requestFrame(frame)
    }

    function frame() {
      running = false
      const t = now()
      const updates = {}
      let anyActive = false
      for (const id of Object.keys(active)) {
        const a = active[id]
        const elapsed = t - a.startTime
        const progress = a.durationMs <= 0 ? 1 : Math.min(1, elapsed / a.durationMs)
        const value = a.from + (a.to - a.from) * progress
        updates[id] = new RV(new RG(undefined, value), new RS(id, undefined))
        if (progress >= 1) {
          // Reached the target: record the completed signature so the program re-declaring
          // this same animation next render does not restart it.
          done[id] = a.signature
          delete active[id]
        } else {
          anyActive = true
        }
      }
      addUpdates(updates)
      if (anyActive) {
        ensureRunning()
      }
    }

    return (emissions) => {
      const present = {}
      for (const anim of emissions) {
        const id = Reactive.Reference(anim.value)
        present[id] = true
        const signature = anim.from + '|' + anim.to + '|' + anim.durationMs
        // An already-completed target is not restarted just because it is re-declared.
        if (done[id] === signature) {
          continue
        }
        // A new or changed target: (re)start it, and clear any stale completion.
        if (active[id] == null || active[id].signature !== signature) {
          active[id] = { from: anim.from, to: anim.to, durationMs: anim.durationMs, startTime: now(), signature: signature }
          delete done[id]
        }
      }
      for (const id of Object.keys(active)) {
        if (present[id] !== true) {
          delete active[id]
        }
      }
      for (const id of Object.keys(done)) {
        if (present[id] !== true) {
          delete done[id]
        }
      }
      if (Object.keys(active).length > 0) {
        ensureRunning()
      }
    }
  })

})