@rafaelaugusto/jolt 0.1.0-beta.0 → 0.1.0-beta.10

package/src/engine.ts

@@ -1,17 +1,27 @@
+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'
 import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
+import { isColorProperty } from './color.js'
+import type { PreparedPath, PathProperty } from './path.js'
 
 export interface Animation extends PromiseLike<boolean> {
   /**
    * Resolves with `true` once the animation played to the end, or with `false`
-   * if it was stopped or another animation took over one of its properties.
-   * Never rejects.
+   * if it was stopped, superseded or skipped.
+   * Playback cancellation never rejects; sequences can reject setup/callback errors.
    */
   readonly finished: Promise<boolean>
-  /** Stops where it is. The view keeps the values it had at that moment. */
+  /** Stops playback. Each effect documents whether it preserves or restores its visual state. */
   stop(): void
 }
 
@@ -20,6 +30,8 @@ export interface Plan {
   /** `null` stands for the value the property has when the animation starts. */
   keyframes: readonly (number | null)[]
   transition: ResolvedTransition
+  relative?: boolean
+  path?: PreparedPath
 }
 
 interface Entry {
@@ -28,11 +40,32 @@ 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>>()
 
+/** Internal forecast for starting a timeline step before another one arrives. */
+export interface ArrivalTiming {
+  read(): { remaining: number | undefined; paused: boolean; arrived: boolean }
+  subscribe(callback: () => void): () => void
+}
+const arrivalTimings = new WeakMap<Animation, ArrivalTiming>()
+
+export function arrivalTimingOf(animation: Animation) {
+  return arrivalTimings.get(animation)
+}
+
+export function setArrivalTiming(animation: Animation, timing: ArrivalTiming) {
+  arrivalTimings.set(animation, timing)
+}
+
 /**
  * Resolves once the animation looks done, which for a spring is well before
  * `finished`. Sequences move on to the next step then.
@@ -45,7 +78,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[] = []
@@ -55,13 +88,203 @@ export class ViewAnimation implements Animation {
   private cancelWait: (() => void) | undefined
   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
+  private readonly timingListeners = new Set<() => void>()
+  private timingChanged() {
+    for (const callback of [...this.timingListeners]) callback()
+  }
+
+  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')
+    this.timingChanged()
+  }
+  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()
+    }
+    this.timingChanged()
+  }
+  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()
+    this.timingChanged()
+  }
+  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()
+      this.timingChanged()
+    } else
+      this.cancelArrival = getDriver().after(remaining, () => {
+        this.arrived = true
+        this.arrive()
+        this.timingChanged()
+      })
+  }
+  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)))
+    setArrivalTiming(this, {
+      read: () => ({
+        remaining: this.started ? Math.max(0, this.arrival - this.time()) : undefined,
+        paused: this._paused,
+        arrived: this.arrived || this.settled,
+      }),
+      subscribe: (callback) => {
+        this.timingListeners.add(callback)
+        return () => this.timingListeners.delete(callback)
+      },
+    })
     if (view.isLoaded && view.nativeViewProtected) this.start(plans)
     else this.waitForLoad(plans)
   }
@@ -76,6 +299,7 @@ export class ViewAnimation implements Animation {
   stop() {
     if (this.settled) return
     this.cancelWait?.()
+    this.haptics?.cancel()
     const now = getDriver().now()
     for (const entry of this.entries) {
       if (!entry.done) release(entry, now, true)
@@ -85,38 +309,62 @@ export class ViewAnimation implements Animation {
   }
 
   ended(finished: boolean) {
-    if (!finished) this.complete = false
-    if (--this.pending === 0) this.settle()
+    if (!finished) {
+      this.complete = false
+      this.haptics?.cancel()
+    }
+    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)
 
-    const tracks = plans.map(({ property, keyframes, transition }) => {
+    const tracks = plans.map(({ property, keyframes, transition, relative, path }) => {
       const previous = entries.get(property)
       let current: number
       let velocity = 0
       if (previous) {
-        const elapsed = now - previous.startedAt
+        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 = readValue(this.view, property)
+        current =
+          (isColorProperty(property)
+            ? driver.presented(this.view, property)
+            : undefined) ?? readValue(this.view, property)
       }
+      if (path)
+        return path.track(
+          property as PathProperty,
+          relative ? current : 0,
+          transition.delay,
+        )
       return createTrack(
         property,
-        keyframes.map((value) => value ?? current),
+        keyframes.map((value) => {
+          if (value === null) return current
+          if (!relative || isColorProperty(property)) return value
+          return property === 'opacity' || property.startsWith('scale')
+            ? current * value
+            : current + value
+        }),
         transition,
         velocity,
       )
     })
 
     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,
@@ -124,30 +372,41 @@ 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++
     }
 
-    for (const entry of this.entries) {
-      entry.handle = driver.play(this.view, entry.track, now, () => {
-        if (entry.done) return
-        entry.done = true
-        forget(entry)
-        this.ended(true)
-      })
-    }
-
-    const arrival = Math.max(...this.entries.map((entry) => entry.track.arrival))
-    if (this.pending === 0) this.settle()
-    else if (Number.isFinite(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?.()
+    this.timingChanged()
+    if (this.pending === 0) this.becameIdle()
   }
 
   private waitForLoad(plans: readonly Plan[]) {
-    for (const { property, keyframes } of plans) {
+    for (const { property, keyframes, relative } of plans) {
+      if (relative && !isColorProperty(property)) continue
       const first = keyframes[0]
       if (first !== null && first !== undefined) writeValue(this.view, property, first)
     }
@@ -166,13 +425,51 @@ 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
     this.arrive()
     this.resolve(this.complete)
+    this.timingChanged()
+  }
+}
+
+/** Current native presentation when available, otherwise the active curve or model. */
+export function currentValue(view: View, property: Property): number {
+  const entry = running.get(view)?.get(property)
+  if (!entry) return readValue(view, property)
+  const driver = getDriver()
+  return (
+    driver.presented(view, property) ??
+    entry.track.valueAt(elapsedOf(entry, driver.now()))
+  )
+}
+
+/** Internal property ownership marker; layout cleanup must preserve newer animations. */
+export function propertyRevision(view: View, property: Property) {
+  return revisions.get(view)?.get(property)
+}
+
+/** Sample an existing owner at layout time, without stealing an animation started meanwhile. */
+export function captureValue(view: View, property: Property): () => number | undefined {
+  const token = propertyRevision(view, property)
+  const entry = running.get(view)?.get(property)
+  const initial = currentValue(view, property)
+  return () => {
+    if (propertyRevision(view, property) !== token) return undefined
+    if (entry && running.get(view)?.get(property) === entry)
+      return currentValue(view, property)
+    return entry?.finished ? entry.track.to : initial
   }
 }
 
 /** 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()
@@ -200,9 +497,14 @@ function release(entry: Entry, now: number, commit: boolean) {
   forget(entry)
   if (commit) {
     const value =
-      driver.presented(view, property) ?? entry.track.valueAt(now - entry.startedAt)
+      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 entry.owner.elapsed(entry, now)
+}

package/src/haptics.ts

@@ -0,0 +1,148 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { Driver } from './driver/index.js'
+import type { Track } from './track.js'
+
+export type HapticStyle = 'light' | 'medium' | 'heavy'
+
+export interface HapticOptions {
+  style: HapticStyle
+  /** Points from 0 to 1 over the finite animation, excluding its initial delay. Defaults to arrival. */
+  times?: readonly number[]
+}
+
+export type Haptic = HapticStyle | HapticOptions | false
+
+/** Validate before any running animation is interrupted. */
+export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undefined {
+  if (haptic === undefined || haptic === false) return undefined
+  const options = typeof haptic === 'string' ? { style: haptic } : haptic
+  if (!options || !['light', 'medium', 'heavy'].includes(options.style))
+    throw new TypeError('Haptic style must be light, medium or heavy.')
+  const times = options.times
+  if (
+    times !== undefined &&
+    (!Array.isArray(times) ||
+      times.length === 0 ||
+      Array.from(times).some(
+        (time, i) =>
+          !Number.isFinite(time) ||
+          time <= 0 ||
+          time > 1 ||
+          (i > 0 && time <= times[i - 1]!),
+      ))
+  )
+    throw new RangeError(
+      'Haptic times must be increasing points greater than 0 and at most 1.',
+    )
+  return { style: options.style, times: times && [...times] }
+}
+
+const PREPARE_AHEAD = 100
+const MAX_LATENESS = 100
+const COMPLETION_TOLERANCE = 20
+
+/** Discrete feedback only: animation playback remains entirely native. */
+export function playHaptics(
+  view: View,
+  tracks: readonly Track[],
+  options: HapticOptions | undefined,
+  driver: Driver,
+  startedAt: number,
+  elapsedTime = () => driver.now() - startedAt,
+) {
+  if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
+  const moving = tracks.filter(
+    (track) =>
+      track.duration > 0 && track.values.some((value) => value !== track.values[0]),
+  )
+  if (!moving.length) return
+  const end = Math.max(...tracks.map((track) => track.end))
+  if (!Number.isFinite(end)) return
+  const delay = Math.min(...moving.map((track) => track.delay))
+  const offsets = options.times
+    ? options.times.map((time) => delay + (end - delay) * time)
+    : [Math.max(...tracks.map((track) => track.arrival))]
+  const styles = {
+    light: 0,
+    medium: 1,
+    heavy: 2,
+  } satisfies Record<HapticStyle, UIImpactFeedbackStyle>
+  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
+
+  const active = () =>
+    view.isLoaded &&
+    view.nativeViewProtected === native &&
+    !!native.window &&
+    UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
+
+  const cancelTimers = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+  }
+  const cancel = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+    generator = undefined
+    view.off('unloaded', cancel)
+  }
+
+  const fire = (tolerance = 0) => {
+    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) {
+      const offset = offsets[next++]!
+      if (active() && elapsed - offset <= MAX_LATENESS) generator?.impactOccurred()
+    }
+  }
+
+  const schedule = () => {
+    if (paused) return
+    if (!generator || next === offsets.length) return cancel()
+    const remaining = offsets[next]! - elapsedTime()
+    if (active()) generator.prepare()
+    if (remaining > PREPARE_AHEAD) {
+      cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
+        if (active()) generator?.prepare()
+      })
+    }
+    cancelImpact = driver.after(Math.max(0, remaining), () => {
+      fire()
+      schedule()
+    })
+  }
+
+  view.on('unloaded', cancel)
+  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)
+      cancel()
+    },
+  }
+}