@rafaelaugusto/jolt 0.1.0-beta.11 → 0.1.0-beta.13

package/src/playback-group.ts

@@ -6,7 +6,7 @@ import {
   type ViewAnimation,
 } from './engine.js'
 import { getDriver } from './driver/index.js'
-import { createClock, type PlaybackClock } from './playback.js'
+import { createClock, registerPlayback, type PlaybackClock } from './playback.js'
 import { validateProgress, type PlaybackAnimation } from './playback.js'
 
 /** Staggered views share a finite time range. Shorter children remain seekable
@@ -17,6 +17,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
   let finalProgress: number | undefined
   let clock: PlaybackClock | undefined
   let pendingProgress: number | undefined
+  let changed = () => {}
   const duration = () => Math.max(0, ...children.map((child) => child.duration))
   const ensureClock = () => {
     if (clock || settled || children.some((child) => !child.ready)) return
@@ -44,6 +45,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
     clock?.seek(total * value)
     for (const child of children) child.seekTime(total * value)
     finishIfIdle()
+    changed()
   }
   for (const child of children) {
     child.onIdle(finishIfIdle)
@@ -52,6 +54,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       if (pendingProgress !== undefined && children.every((child) => child.ready))
         seek(pendingProgress)
       finishIfIdle()
+      changed()
     })
   }
   const finished = Promise.all(children.map((child) => child.finished)).then(
@@ -63,6 +66,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
           : 0
       settled = true
       clock?.cancel()
+      changed()
       return results.every(Boolean)
     },
   )
@@ -91,6 +95,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         paused = true
         clock?.pause()
         children.forEach((child) => child.pause())
+        changed()
       }
     },
     play() {
@@ -99,6 +104,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         clock?.play()
         children.forEach((child) => child.play())
         finishIfIdle()
+        changed()
       }
     },
     stop() {
@@ -106,9 +112,19 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       settled = true
       clock?.cancel()
       children.forEach((child) => child.stop())
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  changed = registerPlayback(animation, () => ({
+    position: pendingProgress,
+    time: finalProgress === undefined ? (clock?.time() ?? 0) : finalProgress * duration(),
+    duration: duration(),
+    paused,
+    ready: children.every((child) => child.ready),
+    settled,
+    completed: finalProgress === 1,
+  }))
   setArrival(animation, Promise.all(children.map(arrivalOf)))
   const listeners = new Set<() => void>()
   const timings = children.map((child) => arrivalTimingOf(child)!)

package/src/playback.ts

@@ -23,6 +23,47 @@ export interface PlaybackClock {
   cancel(): void
 }
 
+/** Boundary notifications, never frame callbacks. Consumers sample this same clock. */
+export interface PlaybackState {
+  readonly position?: number
+  readonly time: number
+  readonly duration: number
+  readonly paused: boolean
+  readonly ready: boolean
+  readonly settled: boolean
+  readonly completed: boolean
+}
+
+const sources = new WeakMap<
+  Animation,
+  {
+    read(): PlaybackState
+    listeners: Set<() => void>
+  }
+>()
+
+export function registerPlayback(animation: Animation, read: () => PlaybackState) {
+  const source = { read, listeners: new Set<() => void>() }
+  sources.set(animation, source)
+  return () => {
+    for (const listener of [...source.listeners]) listener()
+  }
+}
+
+export function playbackSource(animation: Animation) {
+  const source = sources.get(animation)
+  if (!source) throw new TypeError('This animation does not expose a playback clock.')
+  return {
+    read: source.read,
+    subscribe(listener: () => void) {
+      source.listeners.add(listener)
+      return () => {
+        source.listeners.delete(listener)
+      }
+    },
+  }
+}
+
 /** Read only on user commands; there is no frame loop in JavaScript. */
 export function createClock(now: () => number, initial = 0): PlaybackClock {
   let offset = initial

package/src/sequence.ts

@@ -10,7 +10,12 @@ import {
   stopView,
   type Animation,
 } from './engine.js'
-import { createClock } from './playback.js'
+import { createClock, registerPlayback, playbackSource } from './playback.js'
+import {
+  isMotionValue,
+  type MotionValue,
+  type ValueAnimationOptions,
+} from './motion-value.js'
 import type { PresetName } from './presets.js'
 import { writeValue, type Property } from './properties.js'
 import type { SpringName } from './transition.js'
@@ -28,6 +33,34 @@ export type Step =
     ]
   | (() => Animation)
 
+/** A participant that can genuinely freeze and continue, rather than restart. */
+export interface PlayableAnimation extends Animation {
+  pause(): void
+  play(): void
+  readonly paused: boolean
+  readonly duration?: number
+}
+
+export type TimelineStep =
+  | Exclude<Step, () => Animation>
+  | readonly [
+      MotionValue,
+      number | readonly (number | null)[],
+      ((ValueAnimationOptions & { at?: SequencePosition }) | SpringName)?,
+    ]
+  | { readonly at?: SequencePosition; readonly run: () => PlayableAnimation }
+  | (() => PlayableAnimation)
+
+export interface TimelineAnimation extends PlayableAnimation {
+  /** Unknown until every step has activated and every participant reports a duration. */
+  readonly duration: number | undefined
+}
+
+/** Overlapping steps with a shared pause/resume control, including pending launches. */
+export function timeline(steps: readonly TimelineStep[]): TimelineAnimation {
+  return compose(steps, true) as TimelineAnimation
+}
+
 /**
  * By default a step starts once the previous one looks done. `at` can overlap
  * that arrival, share the previous start, or select an absolute timeline time.
@@ -44,26 +77,54 @@ export type Step =
  * ```
  */
 export function sequence(steps: readonly Step[]): Animation {
+  return compose(steps, false)
+}
+
+function compose(
+  steps: readonly TimelineStep[] | readonly Step[],
+  controlled: boolean,
+): Animation {
   const prepared = steps.map((step) => {
     if (typeof step === 'function') return { step, position: undefined }
-    const [target, animation, options] = step
+    if (!Array.isArray(step)) {
+      const descriptor = step as { at?: SequencePosition; run: () => PlayableAnimation }
+      if (typeof descriptor.run !== 'function')
+        throw new TypeError('A timeline step needs a run() factory.')
+      return { step: descriptor.run, position: parsePosition(descriptor.at) }
+    }
+    const [target, animation, options] = step as Exclude<
+      TimelineStep,
+      Function | { run: () => PlayableAnimation }
+    >
     if (typeof options !== 'object' || options === null)
       return { step, position: undefined }
     const { at, ...transition } = options
     const position = parsePosition(at)
     return { step: [target, animation, transition] as Step, position }
   })
-  applyStartingValues(prepared.map(({ step }) => step))
+  applyStartingValues(
+    prepared
+      .map(({ step }) => step as Step)
+      .filter((step) => typeof step === 'function' || !isMotionValue(step[0])),
+  )
 
   const driver = getDriver()
   const slowdown = 1 / timeScale()
   // Absolute positions share the platform clock, including Android duration scale.
-  const clock = prepared.some(({ position }) => typeof position === 'number')
-    ? (driver.clock?.(Infinity) ?? createClock(() => driver.now()))
-    : undefined
+  const clock =
+    controlled || prepared.some(({ position }) => typeof position === 'number')
+      ? (driver.clock?.(Infinity) ?? createClock(() => driver.now()))
+      : undefined
   const started: Animation[] = []
   const cancellations = new Set<() => void>()
   let stopped = false
+  let paused = false
+  let settled = false
+  let completed = false
+  let changed = () => {}
+  const resumeChildren = new Set<PlayableAnimation>()
+  const waits = new Set<{ at: number; fire(): void; cancel(): void; schedule(): void }>()
+  const time = () => clock?.time() ?? 0
   let resolveScheduled!: () => void
   let rejectScheduled!: (reason: unknown) => void
   const scheduled = new Promise<void>((resolve, reject) => {
@@ -77,28 +138,55 @@ export function sequence(steps: readonly Step[]): Animation {
       position,
       onStart: new Set<() => void>(),
       animation: undefined as Animation | undefined,
+      start: undefined as number | undefined,
     }
   })
   const cancelSchedule = () => {
     for (const cancel of cancellations) cancel()
     cancellations.clear()
-    clock?.cancel()
+    for (const wait of waits) wait.cancel()
+    waits.clear()
+    if (!controlled || stopped || settled) clock?.cancel()
   }
   const fail = (error: unknown) => {
     if (stopped) return
     stopped = true
+    settled = true
     cancelSchedule()
     states.forEach((state) => state.onStart.clear())
     started.forEach((child) => child.stop())
+    changed()
     rejectScheduled(error)
   }
   const launch = (index: number) => {
     const state = states[index]!
     if (stopped || state.animation) return
+    if (paused) {
+      wait(0, () => launch(index))
+      return
+    }
     try {
       const step = state.step
-      const child = typeof step === 'function' ? step() : animate(...step)
+      const child =
+        typeof step === 'function'
+          ? step()
+          : (animate as (...args: any[]) => Animation)(...(step as any[]))
+      if (controlled && !isPlayable(child)) {
+        child?.stop?.()
+        throw new TypeError(
+          'A timeline participant must expose pause(), play() and paused; use sequence() for non-playable effects.',
+        )
+      }
       state.animation = child
+      state.start = time()
+      if (controlled) {
+        try {
+          const playback = playbackSource(child).read()
+          if (playback.ready) state.start = Math.max(0, time() - playback.time)
+        } catch {
+          /* A custom playable participant can omit a clock. */
+        }
+      }
       started.push(child)
       // Observe setup failures immediately, even while other steps are still
       // scheduled. Nested sequences can reject before this one reaches arrival.
@@ -110,25 +198,51 @@ export function sequence(steps: readonly Step[]): Animation {
         cancelSchedule()
         resolveScheduled()
       }
+      changed()
     } catch (error) {
       fail(error)
     }
   }
   const wait = (ms: number, callback: () => void) => {
     if (stopped) return
-    if (ms <= 0) {
-      callback()
+    if (!controlled) {
+      if (ms <= 0) {
+        callback()
+        return
+      }
+      let cancel = () => {}
+      let fired = false
+      const off = driver.after(ms, () => {
+        fired = true
+        cancellations.delete(cancel)
+        if (!stopped) callback()
+      })
+      cancel = off
+      if (!fired) cancellations.add(cancel)
       return
     }
-    let cancel = () => {}
-    let fired = false
-    const off = driver.after(ms, () => {
-      fired = true
-      cancellations.delete(cancel)
-      if (!stopped) callback()
-    })
-    cancel = off
-    if (!fired) cancellations.add(cancel)
+    let off = () => {}
+    const waiting = {
+      at: time() + Math.max(0, ms),
+      fire() {
+        off()
+        waits.delete(waiting)
+        if (!stopped) callback()
+      },
+      cancel() {
+        off()
+        off = () => {}
+      },
+      schedule() {
+        waiting.cancel()
+        if (paused || stopped) return
+        const remaining = waiting.at - time()
+        if (remaining <= 0) waiting.fire()
+        else off = driver.after(remaining, waiting.fire)
+      },
+    }
+    waits.add(waiting)
+    waiting.schedule()
   }
 
   for (let index = 0; index < states.length; index++) {
@@ -214,7 +328,11 @@ export function sequence(steps: readonly Step[]): Animation {
   const arrived = scheduled.then(() => Promise.all(started.map(arrivalOf)))
   const finished = arrived.then(async () => {
     const results = await Promise.all(started.map((animation) => animation.finished))
-    return !stopped && results.length === steps.length && results.every(Boolean)
+    completed = !stopped && results.length === steps.length && results.every(Boolean)
+    settled = true
+    clock?.cancel()
+    changed()
+    return completed
   })
 
   const animation: Animation = {
@@ -222,13 +340,69 @@ export function sequence(steps: readonly Step[]): Animation {
     stop() {
       if (stopped) return
       stopped = true
+      settled = true
       cancelSchedule()
       states.forEach((state) => state.onStart.clear())
       resolveScheduled()
       started.forEach((animation) => animation.stop())
+      resumeChildren.clear()
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  if (controlled) {
+    const duration = () => {
+      if (pending) return undefined
+      let total = 0
+      for (const state of states) {
+        const child = state.animation as PlayableAnimation | undefined
+        if (!child || child.duration === undefined) return undefined
+        try {
+          if (!playbackSource(child).read().ready) return undefined
+        } catch {
+          /* custom playable */
+        }
+        total = Math.max(total, (state.start ?? 0) + child.duration)
+      }
+      return total
+    }
+    Object.defineProperties(animation, {
+      paused: { get: () => paused },
+      duration: { get: duration },
+    })
+    Object.assign(animation, {
+      pause() {
+        if (paused || settled) return
+        paused = true
+        clock?.pause()
+        for (const wait of waits) wait.cancel()
+        for (const child of started as PlayableAnimation[]) {
+          if (!child.paused) {
+            resumeChildren.add(child)
+            child.pause()
+          }
+        }
+        changed()
+      },
+      play() {
+        if (!paused || settled) return
+        paused = false
+        clock?.play()
+        for (const child of resumeChildren) child.play()
+        resumeChildren.clear()
+        for (const wait of [...waits]) wait.schedule()
+        changed()
+      },
+    })
+    changed = registerPlayback(animation, () => ({
+      time: time(),
+      duration: duration() ?? Infinity,
+      paused,
+      ready: duration() !== undefined,
+      settled,
+      completed,
+    }))
+  }
   setArrival(animation, arrived)
   return animation
 }
@@ -276,3 +450,18 @@ function applyStartingValues(steps: readonly Step[]) {
     }
   }
 }
+
+function isPlayable(animation: Animation): animation is PlayableAnimation {
+  const handle = animation as PlayableAnimation | undefined
+  return (
+    !!handle &&
+    typeof handle.pause === 'function' &&
+    typeof handle.play === 'function' &&
+    typeof handle.paused === 'boolean' &&
+    typeof handle.stop === 'function' &&
+    typeof handle.finished?.then === 'function' &&
+    typeof handle.finished?.catch === 'function' &&
+    (handle.duration === undefined ||
+      (typeof handle.duration === 'number' && handle.duration >= 0))
+  )
+}

package/src/timed-animation.ts

@@ -0,0 +1,192 @@
+import { getDriver } from './driver/index.js'
+import { Trace } from '@nativescript/core'
+import { setArrival, setArrivalTiming } from './engine.js'
+import {
+  createClock,
+  registerPlayback,
+  validateProgress,
+  type PlaybackAnimation,
+  type PlaybackCommand,
+} from './playback.js'
+
+/** A sampled resource's control clock. Native sinks play frames; JS runs only at boundaries. */
+export class TimedAnimation implements PlaybackAnimation {
+  readonly finished: Promise<boolean>
+  private resolve!: (value: boolean) => void
+  private arrive!: () => void
+  private readonly clock
+  private readonly notifyPlayback: () => void
+  private readonly listeners = new Set<() => void>()
+  private cancelEnd?: () => void
+  private cancelArrival?: () => void
+  private _paused = false
+  private settled = false
+  private completed = false
+  private arrived = false
+  private active = false
+
+  constructor(
+    readonly duration: number,
+    private readonly arrival: number,
+    private readonly update: (
+      time: number,
+      paused: boolean,
+      command: PlaybackCommand,
+    ) => void,
+    private readonly finish: (completed: boolean) => void,
+  ) {
+    const driver = getDriver()
+    this.clock = driver.clock?.(duration) ?? createClock(() => driver.now())
+    this.finished = new Promise((resolve) => {
+      this.resolve = resolve
+    })
+    setArrival(
+      this,
+      new Promise<void>((resolve) => {
+        this.arrive = resolve
+      }),
+    )
+    this.notifyPlayback = registerPlayback(this, () => ({
+      time: this.time,
+      duration,
+      paused: this._paused,
+      ready: this.active,
+      settled: this.settled,
+      completed: this.completed,
+    }))
+    setArrivalTiming(this, {
+      read: () => ({
+        remaining: Math.max(0, arrival - this.time),
+        paused: this.paused,
+        arrived: this.arrived,
+      }),
+      subscribe: (callback) => {
+        this.listeners.add(callback)
+        return () => {
+          this.listeners.delete(callback)
+        }
+      },
+    })
+  }
+
+  get time() {
+    return Math.max(0, Math.min(this.duration, this.clock.time()))
+  }
+  get paused() {
+    return this._paused
+  }
+  get done() {
+    return this.settled
+  }
+  get progress() {
+    if (!Number.isFinite(this.duration))
+      throw new RangeError('Progress requires a finite animation.')
+    return this.completed ? 1 : this.duration ? this.time / this.duration : 0
+  }
+  set progress(value: number) {
+    validateProgress(value, this.duration)
+    this.seekTime(value * this.duration)
+  }
+
+  start() {
+    if (this.active || this.settled) return
+    this.active = true
+    this.schedule()
+    this.notify()
+  }
+
+  pause() {
+    if (this._paused || this.settled) return
+    this.clock.pause()
+    this._paused = true
+    this.cancelTimers()
+    this.update(this.time, true, 'pause')
+    this.notify()
+  }
+
+  play() {
+    if (!this._paused || this.settled) return
+    this._paused = false
+    this.clock.play()
+    this.update(this.time, false, 'play')
+    this.schedule()
+    this.notify()
+  }
+
+  seekTime(time: number) {
+    if (!Number.isFinite(time) || time < 0)
+      throw new RangeError('Seek time must be finite and nonnegative.')
+    if (this.settled) return
+    this.clock.seek(Math.min(this.duration, time))
+    this.update(this.time, this._paused, 'seek')
+    this.schedule()
+    this.notify()
+  }
+
+  stop() {
+    this.settle(false)
+  }
+
+  then<A = boolean, B = never>(
+    onfulfilled?: ((value: boolean) => A | PromiseLike<A>) | null,
+    onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+  ): Promise<A | B> {
+    return this.finished.then(onfulfilled, onrejected)
+  }
+
+  private notify() {
+    this.notifyPlayback()
+    for (const callback of [...this.listeners]) callback()
+  }
+  private cancelTimers() {
+    this.cancelEnd?.()
+    this.cancelArrival?.()
+    this.cancelEnd = this.cancelArrival = undefined
+  }
+  private schedule() {
+    this.cancelTimers()
+    if (!this.active || this._paused || this.settled) return
+    const driver = getDriver()
+    if (Number.isFinite(this.duration)) {
+      const remaining = this.duration - this.time
+      if (remaining <= 0) {
+        this.settle(true)
+        return
+      }
+      this.cancelEnd = driver.after(remaining, () => this.settle(true))
+    }
+    if (!this.arrived && Number.isFinite(this.arrival)) {
+      const remaining = this.arrival - this.time
+      const arrive = () => {
+        this.arrived = true
+        this.arrive()
+        this.notify()
+      }
+      if (remaining <= 0) arrive()
+      else this.cancelArrival = driver.after(remaining, arrive)
+    }
+  }
+  private settle(completed: boolean) {
+    if (this.settled) return
+    this.settled = true
+    this.completed = completed
+    this.cancelTimers()
+    if (completed) this.clock.seek(this.duration)
+    this.clock.cancel()
+    try {
+      this.finish(completed)
+    } catch (error) {
+      this.completed = false
+      Trace.write(
+        `Jolt sampled playback failed: ${String(error)}`,
+        Trace.categories.Error,
+        Trace.messageType.error,
+      )
+    }
+    this.arrived = true
+    this.arrive()
+    this.notify()
+    this.resolve(this.completed)
+    this.listeners.clear()
+  }
+}