@rafaelaugusto/jolt 0.1.0-beta.12 → 0.1.0-beta.14

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()
+  }
+}

package/src/types.ts

@@ -84,7 +84,7 @@ export type AnimateOptions = Transition & {
   relative?: boolean
   /** With several targets, delays each one by this much more than the previous. */
   stagger?: number | Stagger
-  /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
+  /** Native haptic feedback at arrival, or at explicit points in a finite animation. */
   haptic?: Haptic
   /**
    * Plays on a named layer, on top of the property's other animations instead of replacing

package/src/value-observers.ts

@@ -0,0 +1,133 @@
+import { Application, Color, Trace } from '@nativescript/core'
+import { getDriver } from './driver/index.js'
+
+export interface SubscribeOptions {
+  /** Deliver the current value synchronously when subscribing. Defaults to true. */
+  immediate?: boolean
+}
+
+/** `time` is milliseconds on the native animation clock, shared by a notification batch. */
+export type ValueListener<T> = (value: T, time: number) => void
+
+interface Observer {
+  read(value: number): number
+  color: boolean
+  listener: ValueListener<number | Color>
+  previous: number
+}
+
+// Only sources that need a frame live here. Idle subscriptions retain no global root reference.
+const pending = new Set<ValueObservers>()
+let cancelFrame: (() => void) | undefined
+let listening = false
+let suspended = false
+
+function suspend() {
+  suspended = true
+  cancelFrame?.()
+  cancelFrame = undefined
+}
+
+function resume() {
+  suspended = false
+  schedule()
+}
+
+function schedule() {
+  if (!pending.size) {
+    cancelFrame?.()
+    cancelFrame = undefined
+    if (listening && !suspended) {
+      Application.off(Application.suspendEvent, suspend)
+      Application.off(Application.resumeEvent, resume)
+      listening = false
+    }
+    return
+  }
+  if (!listening) {
+    Application.on(Application.suspendEvent, suspend)
+    Application.on(Application.resumeEvent, resume)
+    listening = true
+  }
+  if (cancelFrame || suspended) return
+  cancelFrame = getDriver().frame(() => {
+    cancelFrame = undefined
+    const time = getDriver().now()
+    const sources = [...pending]
+    pending.clear()
+    // Capture every source before calling any listener: reentrant writes belong to the next batch.
+    const deliveries = sources.map((source) => source.snapshot(time))
+    for (const source of sources) if (source.active) pending.add(source)
+    for (const deliver of deliveries) deliver()
+    schedule()
+  })
+}
+
+function deliver(observer: Observer, value: number, time: number) {
+  try {
+    observer.listener(observer.color ? new Color(value) : value, time)
+  } catch (error) {
+    // A consumer failure must not interrupt other consumers or strand the shared frame source.
+    Trace.write(
+      `Jolt motion value subscriber failed: ${error instanceof Error ? error.stack : String(error)}`,
+      Trace.categories.Error,
+      Trace.messageType.error,
+    )
+  }
+}
+
+/** Root-owned subscriptions; mappings are evaluated only for consumers that opted in. */
+export class ValueObservers {
+  private readonly observers = new Set<Observer>()
+  private running = false
+
+  constructor(private readonly read: (time: number) => number) {}
+
+  get active() {
+    return this.running && this.observers.size > 0
+  }
+
+  subscribe(
+    read: (value: number) => number,
+    color: boolean,
+    listener: ValueListener<number | Color>,
+    options: SubscribeOptions = {},
+  ): () => void {
+    if (typeof listener !== 'function')
+      throw new TypeError('subscribe() needs a listener function.')
+    const time = getDriver().now()
+    const observer = { read, color, listener, previous: read(this.read(time)) }
+    this.observers.add(observer)
+    if (options.immediate !== false) deliver(observer, observer.previous, time)
+    if (this.active) this.changed(true)
+    return () => {
+      this.observers.delete(observer)
+      if (!this.observers.size) {
+        pending.delete(this)
+        schedule()
+      }
+    }
+  }
+
+  changed(running: boolean) {
+    this.running = running
+    if (this.observers.size) {
+      pending.add(this)
+      schedule()
+    }
+  }
+
+  snapshot(time: number): () => void {
+    const value = this.read(time)
+    const deliveries = [...this.observers].flatMap((observer) => {
+      const next = observer.read(value)
+      if (Object.is(next, observer.previous)) return []
+      observer.previous = next
+      return [{ observer, next }]
+    })
+    return () => {
+      for (const { observer, next } of deliveries)
+        if (this.observers.has(observer)) deliver(observer, next, time)
+    }
+  }
+}

package/src/value-track.ts

@@ -0,0 +1,71 @@
+import { instantTrack, type Track } from './track.js'
+
+export interface ValuePart {
+  readonly track: Track
+  readonly elapsed: number
+  readonly base: number
+  readonly span: number
+}
+
+/** Compile scalar addition before any binding's mapping. The snapshot is independent of later edits. */
+export function valueTrack(parts: readonly ValuePart[], rest: number) {
+  const value = (time: number) =>
+    parts.reduce(
+      (sum, part) =>
+        sum + part.base + part.span * part.track.valueAt(part.elapsed + time),
+      rest,
+    )
+  let finite = 0
+  const periods: number[] = []
+  for (const { track, elapsed } of parts) {
+    if (Number.isFinite(track.end)) finite = Math.max(finite, track.end - elapsed)
+    else if (elapsed < track.delay) finite = Math.max(finite, track.delay - elapsed)
+    else periods.push(Math.max(1, track.duration * (track.reverse ? 2 : 1)))
+  }
+  if (finite <= 0 && !periods.length)
+    return { track: instantTrack('x', value(0)), windowed: false }
+  const loop = finite <= 0 && periods.length ? commonPeriod(periods) : undefined
+  // Bound finite compositions too: a minutes-long base must not undersample a short pulse.
+  const duration = finite > 0 ? Math.min(finite, 4000) : (loop ?? 4000)
+  const steps = Math.max(1, Math.min(6000, Math.ceil((duration * 60) / 1000)))
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  const values = times.map((time) => value(time * duration))
+  const endless = loop !== undefined
+  const at = (time: number) =>
+    value(
+      endless
+        ? ((time % duration) + duration) % duration
+        : Math.min(duration, Math.max(0, time)),
+    )
+  const track: Track = {
+    property: 'x',
+    delay: 0,
+    duration,
+    repeat: endless ? Infinity : 0,
+    reverse: false,
+    times,
+    values,
+    to: endless ? values[0]! : values[steps]!,
+    end: endless ? Infinity : duration,
+    arrival: endless ? Infinity : duration,
+    valueAt: at,
+    velocityAt: (time) => (at(time + 0.5) - at(time - 0.5)) * 1000,
+  }
+  return {
+    track,
+    windowed:
+      finite > duration ||
+      (!endless && parts.some(({ track }) => !Number.isFinite(track.end))),
+  }
+}
+
+function commonPeriod(periods: readonly number[]) {
+  const gcd = (a: number, b: number): number => (b ? gcd(b, a % b) : a)
+  let total = 1
+  for (const period of periods) {
+    if (!Number.isInteger(period)) return undefined
+    total = (total / gcd(total, period)) * period
+    if (total > 30000) return undefined
+  }
+  return total
+}

package/src/vue/index.ts

@@ -40,6 +40,8 @@ import {
   type GradientOptions,
   type Transition,
 } from '../index.js'
+import { isDerived } from '../motion-value.js'
+import { prepareGradient, type GradientValues } from '../gradient.js'
 import { currentKeyboard } from '../keyboard.js'
 
 type Host = NSVElement
@@ -70,7 +72,10 @@ export interface TransitionProps {
 const animations = new WeakMap<object, PlaybackAnimation>()
 const scopes = new WeakMap<object, MotionScope>()
 const removers = new WeakMap<object, () => void>()
-const gradients = new WeakMap<object, { gradient: Gradient; colors: number }>()
+const gradients = new WeakMap<
+  object,
+  { gradient: Gradient; colors: number; release?: () => void }
+>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -82,6 +87,7 @@ function split<T>(
 
 function same(a: unknown, b: unknown): boolean {
   if (Object.is(a, b)) return true
+  if (isDerived(a) || isDerived(b)) return false
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
     return false
   if (Array.isArray(a) !== Array.isArray(b)) return false
@@ -161,17 +167,35 @@ function paint(el: Host, value: GradientValue, animated: boolean) {
     (Transition | SpringName)?,
   ]
   const current = gradients.get(el)
+  prepareGradient(options)
   const colors = options.colors.length
+  const hasBindings = [
+    options.angle,
+    options.radius,
+    options.center?.x,
+    options.center?.y,
+    ...options.colors,
+    ...(options.stops ?? []),
+  ].some(isDerived)
   if (current && current.gradient.type === options.type) {
     const { type, ...values } = options
-    if (animated && current.colors === colors)
-      current.gradient.animate(values, transition)
-    else current.gradient.set(values)
+    const previous = current.release
+    if (hasBindings) current.release = current.gradient.bind(values)
+    else {
+      if (animated && current.colors === colors)
+        current.gradient.animate(values as GradientValues, transition)
+      else current.gradient.set(values as GradientValues)
+      current.release = undefined
+    }
+    previous?.()
     current.colors = colors
     return
   }
   current?.gradient.remove()
-  gradients.set(el, { gradient: gradient(el, options), colors })
+  // Track directive ownership explicitly, including bindings omitted on a later update.
+  const made = gradient(el, options)
+  const release = hasBindings ? made.bind(options) : undefined
+  gradients.set(el, { gradient: made, colors, release })
 }
 
 /**