@rafaelaugusto/jolt 0.1.0-beta.4 → 0.1.0-beta.5

package/src/engine.ts

@@ -1,3 +1,10 @@
+import {
+  createClock,
+  validateProgress,
+  type PlaybackAnimation,
+  type PlaybackClock,
+  type PlaybackCommand,
+} from './playback.js'
 import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
 import { playHaptics, type HapticOptions } from './haptics.js'
@@ -31,8 +38,14 @@ interface Entry {
   readonly owner: ViewAnimation
   handle: unknown
   done: boolean
+  finished: boolean
+  generation: number
+  token: symbol
+  completedValue?: number
 }
 
+const revisions = new WeakMap<View, Map<Property, symbol>>()
+
 const running = new WeakMap<View, Map<Property, Entry>>()
 const arrivals = new WeakMap<Animation, Promise<unknown>>()
 
@@ -48,7 +61,7 @@ export function setArrival(animation: Animation, arrival: Promise<unknown>) {
   arrivals.set(animation, arrival)
 }
 
-export class ViewAnimation implements Animation {
+export class ViewAnimation implements PlaybackAnimation {
   readonly finished: Promise<boolean>
   private resolve!: (finished: boolean) => void
   private readonly entries: Entry[] = []
@@ -59,12 +72,180 @@ export class ViewAnimation implements Animation {
   private arrive!: () => void
   private cancelArrival: (() => void) | undefined
   private haptics: ReturnType<typeof playHaptics>
+  private clock: PlaybackClock | undefined
+  private _paused = false
+  private controlled = false
+  private pendingProgress: number | undefined
+  private total = 0
+  private started = false
+  private arrival = 0
+  private arrived = false
+  private idleListener: (() => void) | undefined
+  private readyListener: (() => void) | undefined
+  private readonly endless: boolean
+
+  get paused() {
+    return this._paused
+  }
+  get duration() {
+    return this.started ? this.total : this.endless ? Infinity : 0
+  }
+  get currentTime() {
+    return this.time()
+  }
+  get ready() {
+    return this.started || this.settled
+  }
+  get idle() {
+    return this.settled || (this.started && this.pending === 0)
+  }
+  get progress() {
+    if (!Number.isFinite(this.duration))
+      throw new RangeError('Progress requires a finite animation.')
+    if (this.settled && this.complete) return 1
+    return (
+      this.pendingProgress ??
+      (this.duration ? Math.min(1, this.time() / this.duration) : this.settled ? 1 : 0)
+    )
+  }
+  set progress(value: number) {
+    validateProgress(value, this.duration)
+    if (this.settled) return
+    if (!this.started) {
+      this.pendingProgress = value
+      return
+    }
+    this.seekTime(this.duration * value)
+  }
+  onIdle(callback: () => void) {
+    this.idleListener = callback
+  }
+  onReady(callback: () => void) {
+    this.readyListener = callback
+  }
+  releaseGroup() {
+    this.held = false
+    if (this.idle && !this._paused) this.settle()
+  }
+
+  pause() {
+    if (this.settled || this._paused) return
+    this.controlled = true
+    this._paused = true
+    this.clock?.pause()
+    this.cancelArrival?.()
+    this.haptics?.pause()
+    if (this.started) this.controlTracks(this.time(), 'pause')
+  }
+  play() {
+    if (this.settled || !this._paused) return
+    this.controlled = true
+    this._paused = false
+    this.clock?.play()
+    if (this.started) {
+      this.controlTracks(this.time(), 'play')
+      this.scheduleArrival()
+      this.haptics?.play()
+      if (this.pending === 0) this.becameIdle()
+    }
+  }
+  seekTime(time: number) {
+    if (this.settled) return
+    this.controlled = true
+    const position = Math.max(0, Math.min(this.total, time))
+    this.clock?.seek(position)
+    if (!this._paused) this.clock?.play()
+    for (const entry of this.entries) {
+      if (
+        entry.done &&
+        entry.finished &&
+        revisions.get(this.view)?.get(entry.track.property) === entry.token &&
+        readValue(this.view, entry.track.property) === entry.completedValue
+      ) {
+        entry.done = false
+        entry.finished = false
+        this.pending++
+        entriesOf(this.view).set(entry.track.property, entry)
+        this.playEntry(entry, position)
+      }
+    }
+    this.controlTracks(position)
+    this.scheduleArrival()
+    this.haptics?.seek()
+    if (this.pending === 0) this.becameIdle()
+  }
+  elapsed(entry: Entry, now: number) {
+    return this.controlled
+      ? this.time()
+      : (getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt)
+  }
+  private time() {
+    return this.clock?.time() ?? 0
+  }
+  private controlTracks(position: number, command: PlaybackCommand = 'seek') {
+    const driver = getDriver()
+    for (const entry of this.entries)
+      if (!entry.done)
+        driver.control?.(this.view, entry.handle, position, this._paused, command)
+  }
+  private scheduleArrival() {
+    this.cancelArrival?.()
+    this.cancelArrival = undefined
+    if (
+      this.pending === 0 ||
+      this.arrived ||
+      this._paused ||
+      !Number.isFinite(this.arrival) ||
+      this.total <= this.arrival
+    )
+      return
+    const remaining = this.arrival - this.time()
+    if (remaining <= 0) {
+      this.arrived = true
+      this.arrive()
+    } else
+      this.cancelArrival = getDriver().after(remaining, () => {
+        this.arrived = true
+        this.arrive()
+      })
+  }
+  private becameIdle() {
+    this.clock?.pause()
+    this.idleListener?.()
+    if (!this.complete || (!this.held && !this._paused)) this.settle()
+  }
+  private playEntry(entry: Entry, elapsed = 0) {
+    const initial = entry.generation === 0
+    const instance = ++entry.generation
+    const driver = getDriver()
+    entry.handle = driver.play(
+      this.view,
+      entry.track,
+      initial ? entry.startedAt : driver.now() - elapsed,
+      (finished = true) => {
+        if (entry.done || instance !== entry.generation) return
+        entry.done = true
+        entry.finished = finished
+        entry.completedValue = readValue(this.view, entry.track.property)
+        forget(entry)
+        this.ended(finished)
+      },
+    )
+  }
+  private unloaded = () => this.stop()
 
   constructor(
     readonly view: View,
     plans: readonly Plan[],
     private readonly haptic?: HapticOptions,
+    private held = false,
   ) {
+    this.endless = plans.some(
+      (plan) =>
+        !Number.isFinite(plan.transition.repeat) ||
+        (plan.transition.curve.type === 'tween' &&
+          !Number.isFinite(plan.transition.curve.duration)),
+    )
     this.finished = new Promise((resolve) => (this.resolve = resolve))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
     if (view.isLoaded && view.nativeViewProtected) this.start(plans)
@@ -95,10 +276,11 @@ export class ViewAnimation implements Animation {
       this.complete = false
       this.haptics?.cancel()
     }
-    if (--this.pending === 0) this.settle()
+    if (--this.pending === 0) this.becameIdle()
   }
 
   private start(plans: readonly Plan[]) {
+    this.started = true
     const driver = getDriver()
     const now = driver.now()
     const entries = entriesOf(this.view)
@@ -110,7 +292,7 @@ export class ViewAnimation implements Animation {
       if (previous) {
         const elapsed = elapsedOf(previous, now)
         current = driver.presented(this.view, property) ?? previous.track.valueAt(elapsed)
-        velocity = previous.track.velocityAt(elapsed)
+        velocity = previous.owner.paused ? 0 : previous.track.velocityAt(elapsed)
         release(previous, now, false)
       } else {
         current =
@@ -133,8 +315,13 @@ export class ViewAnimation implements Animation {
     })
 
     for (const track of tracks) writeValue(this.view, track.property, track.to)
+    driver.sync?.(this.view)
 
     for (const track of tracks) {
+      let tokens = revisions.get(this.view)
+      if (!tokens) revisions.set(this.view, (tokens = new Map()))
+      const token = Symbol(track.property)
+      tokens.set(track.property, token)
       if (track.end === 0) continue
       const entry: Entry = {
         track,
@@ -142,28 +329,35 @@ export class ViewAnimation implements Animation {
         owner: this,
         handle: undefined,
         done: false,
+        finished: false,
+        generation: 0,
+        token,
       }
       entries.set(track.property, entry)
       this.entries.push(entry)
       this.pending++
     }
 
-    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now)
-
-    for (const entry of this.entries) {
-      entry.handle = driver.play(this.view, entry.track, now, (finished = true) => {
-        if (entry.done) return
-        entry.done = true
-        forget(entry)
-        this.ended(finished)
-      })
-    }
-
-    const arrival = Math.max(...this.entries.map((entry) => entry.track.arrival))
-    if (this.pending === 0) this.settle()
-    else if (Number.isFinite(arrival) && tracks.some((track) => track.end > arrival)) {
-      this.cancelArrival = driver.after(arrival, this.arrive)
-    }
+    this.total = Math.max(0, ...tracks.map((track) => track.end))
+    this.arrival = Math.max(0, ...tracks.map((track) => track.arrival))
+    this.clock =
+      (this.pending ? driver.clock?.(this.total) : undefined) ??
+      createClock(() => driver.now())
+    if (this._paused) this.clock.pause()
+    this.view.on('unloaded', this.unloaded)
+    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now, () =>
+      this.time(),
+    )
+    if (this._paused) this.haptics?.pause()
+    for (const entry of this.entries) this.playEntry(entry)
+    if (this.pendingProgress !== undefined) {
+      const progress = this.pendingProgress
+      this.pendingProgress = undefined
+      this.seekTime(progress * this.total)
+    } else if (this._paused) this.controlTracks(0, 'pause')
+    this.scheduleArrival()
+    this.readyListener?.()
+    if (this.pending === 0) this.becameIdle()
   }
 
   private waitForLoad(plans: readonly Plan[]) {
@@ -187,6 +381,8 @@ export class ViewAnimation implements Animation {
     if (this.settled) return
     this.settled = true
     this.cancelArrival?.()
+    this.clock?.cancel()
+    this.view.off('unloaded', this.unloaded)
     if (this.complete) this.haptics?.finish()
     else this.haptics?.cancel()
     this.haptics = undefined
@@ -197,6 +393,9 @@ export class ViewAnimation implements Animation {
 
 /** Stops whatever is animating these properties of the view, or all of them. */
 export function stopView(view: View, properties?: readonly Property[]) {
+  const tokens = revisions.get(view)
+  for (const property of properties ?? tokens?.keys() ?? [])
+    tokens?.set(property, Symbol(property))
   const entries = running.get(view)
   if (!entries) return
   const now = getDriver().now()
@@ -226,11 +425,12 @@ function release(entry: Entry, now: number, commit: boolean) {
     const value =
       driver.presented(view, property) ?? entry.track.valueAt(elapsedOf(entry, now))
     writeValue(view, property, value)
+    driver.sync?.(view, property)
   }
   driver.stop(view, entry.handle)
   entry.owner.ended(false)
 }
 
 function elapsedOf(entry: Entry, now: number) {
-  return getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt
+  return entry.owner.elapsed(entry, now)
 }

package/src/haptics.ts

@@ -48,6 +48,7 @@ export function playHaptics(
   options: HapticOptions | undefined,
   driver: Driver,
   startedAt: number,
+  elapsedTime = () => driver.now() - startedAt,
 ) {
   if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
   const moving = tracks.filter(
@@ -69,6 +70,7 @@ export function playHaptics(
   let generator: UIImpactFeedbackGenerator | undefined =
     UIImpactFeedbackGenerator.alloc().initWithStyle(styles[options.style])
   const native = view.nativeViewProtected as UIView
+  let paused = false
   let next = 0
   let cancelPrepare: (() => void) | undefined
   let cancelImpact: (() => void) | undefined
@@ -79,6 +81,11 @@ export function playHaptics(
     !!native.window &&
     UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
 
+  const cancelTimers = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+  }
   const cancel = () => {
     cancelPrepare?.()
     cancelImpact?.()
@@ -88,7 +95,7 @@ export function playHaptics(
   }
 
   const fire = (tolerance = 0) => {
-    const elapsed = driver.now() - startedAt
+    const elapsed = elapsedTime()
     // A busy UI thread can delay timers. Drop stale impacts instead of replaying
     // several old taps at once when it becomes responsive again.
     while (next < offsets.length && offsets[next]! <= elapsed + tolerance) {
@@ -98,8 +105,9 @@ export function playHaptics(
   }
 
   const schedule = () => {
+    if (paused) return
     if (!generator || next === offsets.length) return cancel()
-    const remaining = startedAt + offsets[next]! - driver.now()
+    const remaining = offsets[next]! - elapsedTime()
     if (active()) generator.prepare()
     if (remaining > PREPARE_AHEAD) {
       cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
@@ -116,6 +124,21 @@ export function playHaptics(
   schedule()
   return {
     cancel,
+    pause() {
+      paused = true
+      cancelTimers()
+    },
+    play() {
+      if (paused) {
+        paused = false
+        schedule()
+      }
+    },
+    seek() {
+      cancelTimers()
+      while (next < offsets.length && offsets[next]! <= elapsedTime()) next++
+      schedule()
+    },
     finish() {
       // Native completion may beat the timer at the final keyframe by a frame.
       fire(COMPLETION_TOLERANCE)

package/src/index.ts

@@ -27,6 +27,7 @@ export { springs } from './transition.js'
 export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
 export { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
+export type { PlaybackAnimation } from './playback.js'
 export type { Animation } from './engine.js'
 export type { ColorValue, ColorKeyframes } from './color.js'
 export type * from './types.js'

package/src/playback-group.ts

@@ -0,0 +1,110 @@
+import { arrivalOf, setArrival, type ViewAnimation } from './engine.js'
+import { getDriver } from './driver/index.js'
+import { createClock, type PlaybackClock } from './playback.js'
+import { validateProgress, type PlaybackAnimation } from './playback.js'
+
+/** Staggered views share a finite time range. Shorter children remain seekable
+ * until the whole group settles, unless another animation has taken ownership. */
+export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnimation {
+  let paused = false
+  let settled = false
+  let finalProgress: number | undefined
+  let clock: PlaybackClock | undefined
+  let pendingProgress: number | undefined
+  const duration = () => Math.max(0, ...children.map((child) => child.duration))
+  const ensureClock = () => {
+    if (clock || settled || children.some((child) => !child.ready)) return
+    const driver = getDriver()
+    clock = driver.clock?.(duration()) ?? createClock(() => driver.now())
+    clock.seek(Math.max(0, ...children.map((child) => child.currentTime)))
+    if (paused) clock.pause()
+  }
+  const finishIfIdle = () => {
+    if (settled || paused || children.some((child) => !child.idle || child.paused)) return
+    settled = true
+    clock?.cancel()
+    for (const child of children) child.releaseGroup()
+  }
+  const seek = (value: number) => {
+    const total = duration()
+    validateProgress(value, total)
+    if (settled) return
+    if (children.some((child) => !child.ready)) {
+      pendingProgress = value
+      return
+    }
+    pendingProgress = undefined
+    ensureClock()
+    clock?.seek(total * value)
+    for (const child of children) child.seekTime(total * value)
+    finishIfIdle()
+  }
+  for (const child of children) {
+    child.onIdle(finishIfIdle)
+    child.onReady(() => {
+      ensureClock()
+      if (pendingProgress !== undefined && children.every((child) => child.ready))
+        seek(pendingProgress)
+      finishIfIdle()
+    })
+  }
+  const finished = Promise.all(children.map((child) => child.finished)).then(
+    (results) => {
+      finalProgress ??= results.every(Boolean)
+        ? 1
+        : duration()
+          ? Math.min(1, (clock?.time() ?? 0) / duration())
+          : 0
+      settled = true
+      clock?.cancel()
+      return results.every(Boolean)
+    },
+  )
+  const animation: PlaybackAnimation = {
+    finished,
+    get duration() {
+      return duration()
+    },
+    get paused() {
+      return paused
+    },
+    get progress() {
+      if (!Number.isFinite(duration()))
+        throw new RangeError('Progress requires a finite animation.')
+      if (pendingProgress !== undefined) return pendingProgress
+      return (
+        finalProgress ??
+        (settled ? 1 : duration() ? Math.min(1, (clock?.time() ?? 0) / duration()) : 0)
+      )
+    },
+    set progress(value) {
+      seek(value)
+    },
+    pause() {
+      if (!settled && !paused) {
+        paused = true
+        clock?.pause()
+        children.forEach((child) => child.pause())
+      }
+    },
+    play() {
+      if (!settled && paused) {
+        paused = false
+        clock?.play()
+        children.forEach((child) => child.play())
+        finishIfIdle()
+      }
+    },
+    stop() {
+      finalProgress = duration() ? Math.min(1, (clock?.time() ?? 0) / duration()) : 0
+      settled = true
+      clock?.cancel()
+      children.forEach((child) => child.stop())
+    },
+    then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
+  }
+  setArrival(animation, Promise.all(children.map(arrivalOf)))
+  ensureClock()
+  finishIfIdle()
+  return animation
+}

package/src/playback.ts

@@ -0,0 +1,62 @@
+import type { Animation } from './engine.js'
+
+/** Controls returned by animate() and decay(). Effects expose the base Animation. */
+export interface PlaybackAnimation extends Animation {
+  /** Pauses only the properties owned by this animation. */
+  pause(): void
+  /** Continues from the current position. Completed/stopped animations remain terminal. */
+  play(): void
+  readonly paused: boolean
+  /** Total milliseconds, including delays and repeats. Infinity for endless loops. */
+  readonly duration: number
+  /** Finite timeline position, from 0 to 1. Seeking preserves the playing/paused state. */
+  progress: number
+}
+
+export type PlaybackCommand = 'pause' | 'play' | 'seek'
+
+export interface PlaybackClock {
+  time(): number
+  pause(): void
+  play(): void
+  seek(ms: number): void
+  cancel(): void
+}
+
+/** Read only on user commands; there is no frame loop in JavaScript. */
+export function createClock(now: () => number, initial = 0): PlaybackClock {
+  let offset = initial
+  let anchor = now()
+  let paused = false
+  const time = () => offset + (paused ? 0 : now() - anchor)
+  return {
+    time,
+    pause() {
+      offset = time()
+      paused = true
+    },
+    play() {
+      if (paused) {
+        anchor = now()
+        paused = false
+      }
+    },
+    seek(ms) {
+      offset = ms
+      anchor = now()
+    },
+    cancel() {
+      offset = time()
+      paused = true
+    },
+  }
+}
+
+export function validateProgress(value: number, duration: number) {
+  if (!Number.isFinite(value) || value < 0 || value > 1)
+    throw new RangeError('Animation progress must be between 0 and 1.')
+  if (!Number.isFinite(duration))
+    throw new RangeError(
+      'Progress requires a finite animation; endless loops can pause and play.',
+    )
+}

package/src/properties.ts

@@ -1,9 +1,15 @@
 import { Color, type View } from '@nativescript/core'
+import {
+  isDecorationProperty,
+  readDecoration,
+  writeDecoration,
+  type DecorationProperty,
+} from './decoration.js'
 import { isColorProperty, readColor, type ColorProperty } from './color.js'
 
 export type NumericProperty =
   'opacity' | 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY'
-export type Property = NumericProperty | ColorProperty
+export type Property = NumericProperty | ColorProperty | DecorationProperty
 
 const viewKeys = {
   opacity: 'opacity',
@@ -29,6 +35,14 @@ const defaults: Record<NumericProperty, number> = {
 
 /** How close to its target a spring or decay has to be to count as settled. */
 export const precision: Record<Property, number> = {
+  borderRadius: 0.1,
+  borderWidth: 0.1,
+  shadowOpacity: 0.002,
+  shadowRadius: 0.1,
+  shadowOffsetX: 0.1,
+  shadowOffsetY: 0.1,
+  elevation: 0.1,
+  translationZ: 0.1,
   backgroundColor: 0.002,
   borderColor: 0.002,
   color: 0.002,
@@ -43,11 +57,12 @@ export const precision: Record<Property, number> = {
 }
 
 export function isProperty(key: string): key is Property {
-  return key in viewKeys || isColorProperty(key)
+  return Object.hasOwn(viewKeys, key) || isColorProperty(key) || isDecorationProperty(key)
 }
 
 export function readValue(view: View, property: Property): number {
   if (isColorProperty(property)) return readColor(view, property)
+  if (isDecorationProperty(property)) return readDecoration(view, property)
   const value = view[viewKeys[property]]
   return typeof value === 'number' && !Number.isNaN(value) ? value : defaults[property]
 }
@@ -57,5 +72,6 @@ export function writeValue(view: View, property: Property, value: number) {
     view[property] = new Color(value)
     return
   }
+  if (isDecorationProperty(property)) return writeDecoration(view, property, value)
   view[viewKeys[property]] = value
 }

package/src/sequence.ts

@@ -1,3 +1,5 @@
+import { getDriver } from './driver/index.js'
+import { isDecorationProperty, validateDecorationTarget } from './decoration.js'
 import type { View } from '@nativescript/core'
 import { animate, startingValues, toViews } from './animate.js'
 import { arrivalOf, setArrival, stopView, type Animation } from './engine.js'
@@ -69,6 +71,8 @@ function applyStartingValues(steps: readonly Step[]) {
     const starts = startingValues(animation, options)
 
     for (const view of toViews(target)) {
+      for (const property of starts.keys())
+        if (isDecorationProperty(property)) validateDecorationTarget(view, property)
       let properties = claimed.get(view)
       if (!properties) claimed.set(view, (properties = new Set()))
 
@@ -82,6 +86,7 @@ function applyStartingValues(steps: readonly Step[]) {
       for (const [property, value] of fresh) {
         if (value !== null) writeValue(view, property, value)
       }
+      getDriver().sync?.(view)
       for (const property of starts.keys()) properties.add(property)
     }
   }

package/src/track.ts

@@ -1,3 +1,4 @@
+import { clampDecoration, isDecorationProperty } from './decoration.js'
 import { linear } from './easing.js'
 import { solveDecay } from './decay.js'
 import { precision, type Property } from './properties.js'
@@ -72,7 +73,7 @@ export function createTrack(
     return reverse && iteration % 2 === 1 ? [duration - local, -1] : [local, 1]
   }
 
-  return {
+  const track: Track = {
     property,
     delay,
     duration,
@@ -94,6 +95,13 @@ export function createTrack(
       return motion.velocity(time) * direction
     },
   }
+  if (!isDecorationProperty(property)) return track
+  return {
+    ...track,
+    values: track.values.map((value) => clampDecoration(property, value)),
+    to: clampDecoration(property, track.to),
+    valueAt: (elapsed) => clampDecoration(property, track.valueAt(elapsed)),
+  }
 }
 
 function colorTrack(