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

package/src/driver/ios-shadow.ts

@@ -0,0 +1,50 @@
+import type { View } from '@nativescript/core'
+
+type BackgroundView = { _redrawNativeBackground?: (...args: unknown[]) => void }
+const repairs = new WeakSet<View>()
+
+/** Core treats alpha 0 as 1. Repair its model layer after background redraws,
+ * not on animation frames. The wrapper belongs only to this view and is
+ * removed when the shadow color changes. */
+export function preserveZeroShadow(view: View) {
+  const target = view as unknown as BackgroundView
+  const hasZero = () =>
+    Array.isArray(view.boxShadow) &&
+    view.boxShadow.some((shadow) => shadow.color.argb >>> 24 === 0)
+  if (!hasZero() || repairs.has(view)) return
+  const descriptor = Object.getOwnPropertyDescriptor(view, '_redrawNativeBackground')
+  const original = target._redrawNativeBackground
+  const apply = () => {
+    if (!hasZero()) return dispose()
+    if (!view.isLoaded) return
+    const layers = view.nativeViewProtected?.outerShadowContainerLayer?.sublayers as
+      NSArray<CALayer> | undefined
+    if (!layers || !Array.isArray(view.boxShadow)) return
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    for (let i = 0; i < Math.min(layers.count, view.boxShadow.length); i++)
+      if (view.boxShadow[i]!.color.argb >>> 24 === 0)
+        layers.objectAtIndex(i).shadowOpacity = 0
+    CATransaction.commit()
+  }
+  const redraw = function (this: BackgroundView, ...args: unknown[]) {
+    original!.apply(this, args)
+    apply()
+  }
+  const dispose = () => {
+    view.style.off('boxShadowChange', apply)
+    view.off('loaded', apply)
+    view.off('layoutChanged', apply)
+    if (original && target._redrawNativeBackground === redraw) {
+      if (descriptor) Object.defineProperty(view, '_redrawNativeBackground', descriptor)
+      else delete target._redrawNativeBackground
+    }
+    repairs.delete(view)
+  }
+  repairs.add(view)
+  if (original) target._redrawNativeBackground = redraw
+  view.style.on('boxShadowChange', apply)
+  view.on('loaded', apply)
+  view.on('layoutChanged', apply)
+  apply()
+}

package/src/driver/ios.ts

@@ -1,3 +1,10 @@
+import { iosPlayback } from './ios-playback.js'
+import { isDecorationProperty } from '../decoration.js'
+import {
+  playIOSDecoration,
+  presentedIOSDecoration,
+  syncIOSDecoration,
+} from './ios-decoration.js'
 import type { View } from '@nativescript/core'
 import type { NumericProperty } from '../properties.js'
 import { isColorProperty } from '../color.js'
@@ -5,10 +12,9 @@ import { playIOSColor, presentedIOSColor } from './ios-color.js'
 import { after, type Driver } from './index.js'
 
 interface Handle {
-  layers: CALayer[]
-  key: string
-  onStop?: () => void
-  color?: ReturnType<typeof playIOSColor>
+  stop(): void
+  elapsed(): number
+  control(elapsed: number, paused: boolean): void
 }
 
 const keyPaths: Record<NumericProperty, string> = {
@@ -52,8 +58,10 @@ export function createIOSDriver(): Driver {
     now: () => CACurrentMediaTime() * 1000,
 
     play(view, track, startedAt, onEnd): Handle {
+      if (isDecorationProperty(track.property))
+        return playIOSDecoration(view, track, startedAt, onEnd)
       if (isColorProperty(track.property))
-        return { layers: [], key: '', color: playIOSColor(view, track, startedAt, onEnd) }
+        return playIOSColor(view, track, startedAt, onEnd)
       const layers = layersOf(view)
       const key = `jolt:${track.property}`
       const rotation = track.property.startsWith('rotate')
@@ -62,57 +70,90 @@ export function createIOSDriver(): Driver {
         ensurePerspective(view, layers)
       }
 
-      const animation = CAKeyframeAnimation.animationWithKeyPath(keyPaths[track.property])
-      // iOS 15+. The app must opt in through CADisableMinimumFrameDurationOnPhone.
-      if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
-        const nativeView = view.nativeViewProtected as UIView
-        const screen = nativeView.window?.screen ?? UIScreen.mainScreen
-        const maximum = Math.min(120, screen.maximumFramesPerSecond)
-        animation.preferredFrameRateRange = CAFrameRateRangeMake(
-          Math.min(80, maximum),
-          maximum,
-          maximum,
+      const timing = iosPlayback(track, startedAt)
+      let stopped = false,
+        generation = 0
+      const attach = () => {
+        const instance = ++generation
+        const animation = CAKeyframeAnimation.animationWithKeyPath(
+          keyPaths[track.property as NumericProperty],
         )
+        // iOS 15+. The app must opt in through CADisableMinimumFrameDurationOnPhone.
+        if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
+          const nativeView = view.nativeViewProtected as UIView
+          const screen = nativeView.window?.screen ?? UIScreen.mainScreen
+          const maximum = Math.min(120, screen.maximumFramesPerSecond)
+          animation.preferredFrameRateRange = CAFrameRateRangeMake(
+            Math.min(80, maximum),
+            maximum,
+            maximum,
+          )
+        }
+        animation.values = NSArray.arrayWithArray(
+          track.values.map((value) => (rotation ? radians(value) : value)),
+        )
+        animation.keyTimes = NSArray.arrayWithArray(track.times as number[])
+        animation.duration = Math.max(track.duration, 1) / 1000
+        // Keep infinite loops when iOS removes animations on backgrounding.
+        // They are removed explicitly when stopped or replaced.
+        if (track.repeat > 0) {
+          animation.autoreverses = track.reverse
+          animation.repeatCount = track.reverse
+            ? (track.repeat + 1) / 2
+            : track.repeat + 1
+        }
+
+        CATransaction.begin()
+        if (!timing.paused && !infinite)
+          CATransaction.setCompletionBlock(() => {
+            if (stopped || instance !== generation) return
+            stopped = true
+            onEnd()
+          })
+        for (const layer of layers) {
+          timing.configure(animation, layer)
+          layer.addAnimationForKey(animation, key)
+        }
+        CATransaction.commit()
       }
-      animation.values = NSArray.arrayWithArray(
-        track.values.map((value) => (rotation ? radians(value) : value)),
-      )
-      animation.keyTimes = NSArray.arrayWithArray(track.times as number[])
-      animation.duration = Math.max(track.duration, 1) / 1000
-      animation.beginTime = (startedAt + track.delay) / 1000
-      animation.fillMode = kCAFillModeBackwards
-      // Keep infinite loops when iOS removes animations on backgrounding.
-      // They are removed explicitly when stopped or replaced.
-      animation.removedOnCompletion = !infinite
-      if (track.repeat > 0) {
-        animation.autoreverses = track.reverse
-        animation.repeatCount = track.reverse ? (track.repeat + 1) / 2 : track.repeat + 1
+      attach()
+      return {
+        elapsed: timing.elapsed,
+        control(time, paused) {
+          if (!stopped) {
+            timing.control(time, paused)
+            attach()
+          }
+        },
+        stop() {
+          if (stopped) return
+          stopped = true
+          generation++
+          for (const layer of layers) layer.removeAnimationForKey(key)
+          onEnd(false)
+        },
       }
-
-      CATransaction.begin()
-      // iOS completes the transaction on backgrounding even if the loop is retained.
-      if (!infinite) CATransaction.setCompletionBlock(onEnd)
-      for (const layer of layers) layer.addAnimationForKey(animation, key)
-      CATransaction.commit()
-
-      return { layers, key, onStop: infinite ? onEnd : undefined }
     },
 
     stop(_view, handle) {
-      const playing = handle as Handle
-      const { layers, key, onStop } = playing
-      if (playing.color) {
-        playing.color.stop()
-        return
-      }
-      playing.onStop = undefined
-      for (const layer of layers) layer.removeAnimationForKey(key)
-      onStop?.()
+      ;(handle as Handle).stop()
+    },
+    control(_view, handle, elapsed, paused) {
+      ;(handle as Handle).control(elapsed, paused)
     },
+    elapsed: (handle) => (handle as Handle).elapsed(),
+
+    sync: syncIOSDecoration,
 
     presented: (view, property) =>
-      isColorProperty(property) ? presentedIOSColor(view, property) : undefined,
+      isDecorationProperty(property)
+        ? presentedIOSDecoration(view, property)
+        : isColorProperty(property)
+          ? presentedIOSColor(view, property)
+          : undefined,
 
     after,
+
+    reducedMotion: () => UIAccessibilityIsReduceMotionEnabled(),
   }
 }

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'
@@ -5,12 +12,13 @@ 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, superseded or skipped.
-   * Never rejects.
+   * Playback cancellation never rejects; sequences can reject setup/callback errors.
    */
   readonly finished: Promise<boolean>
   /** Stops playback. Each effect documents whether it preserves or restores its visual state. */
@@ -23,6 +31,7 @@ export interface Plan {
   keyframes: readonly (number | null)[]
   transition: ResolvedTransition
   relative?: boolean
+  path?: PreparedPath
 }
 
 interface Entry {
@@ -31,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.
@@ -48,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[] = []
@@ -59,14 +89,202 @@ 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
+  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)
   }
@@ -95,22 +313,23 @@ 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)
 
-    const tracks = plans.map(({ property, keyframes, transition, relative }) => {
+    const tracks = plans.map(({ property, keyframes, transition, relative, path }) => {
       const previous = entries.get(property)
       let current: number
       let velocity = 0
       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 =
@@ -118,6 +337,12 @@ export class ViewAnimation implements Animation {
             ? 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) => {
@@ -133,8 +358,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 +372,36 @@ 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?.()
+    this.timingChanged()
+    if (this.pending === 0) this.becameIdle()
   }
 
   private waitForLoad(plans: readonly Plan[]) {
@@ -187,16 +425,22 @@ 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()
   }
 }
 
 /** 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 +470,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)
 }