@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/engine.ts

@@ -1,11 +1,12 @@
 import {
   createClock,
+  registerPlayback,
   validateProgress,
   type PlaybackAnimation,
   type PlaybackClock,
   type PlaybackCommand,
 } from './playback.js'
-import type { View } from '@nativescript/core'
+import { Application, 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'
@@ -13,6 +14,7 @@ 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'
+import { BASE, identity, MixHandle, mixFor, mixOf, mixesOf } from './mixer.js'
 
 export interface Animation extends PromiseLike<boolean> {
   /**
@@ -32,10 +34,17 @@ export interface Plan {
   transition: ResolvedTransition
   relative?: boolean
   path?: PreparedPath
+  /** A track that is already sampled, like a motion value mapped onto a property. */
+  track?: () => Track
+  /** A named layer composed with the property's base instead of replacing it. */
+  layer?: string
 }
 
 interface Entry {
   readonly track: Track
+  /** The property, or the property and its layer. */
+  readonly key: string
+  readonly layer?: string
   readonly startedAt: number
   readonly owner: ViewAnimation
   handle: unknown
@@ -48,7 +57,7 @@ interface Entry {
 
 const revisions = new WeakMap<View, Map<Property, symbol>>()
 
-const running = new WeakMap<View, Map<Property, Entry>>()
+const running = new WeakMap<View, Map<string, Entry>>()
 const arrivals = new WeakMap<Animation, Promise<unknown>>()
 
 /** Internal forecast for starting a timeline step before another one arrives. */
@@ -101,7 +110,9 @@ export class ViewAnimation implements PlaybackAnimation {
   private readyListener: (() => void) | undefined
   private readonly endless: boolean
   private readonly timingListeners = new Set<() => void>()
+  private readonly playbackChanged: () => void
   private timingChanged() {
+    this.playbackChanged()
     for (const callback of [...this.timingListeners]) callback()
   }
 
@@ -134,6 +145,7 @@ export class ViewAnimation implements PlaybackAnimation {
     if (this.settled) return
     if (!this.started) {
       this.pendingProgress = value
+      this.timingChanged()
       return
     }
     this.seekTime(this.duration * value)
@@ -188,7 +200,7 @@ export class ViewAnimation implements PlaybackAnimation {
         entry.done = false
         entry.finished = false
         this.pending++
-        entriesOf(this.view).set(entry.track.property, entry)
+        entriesOf(this.view).set(entry.key, entry)
         this.playEntry(entry, position)
       }
     }
@@ -199,9 +211,9 @@ export class ViewAnimation implements PlaybackAnimation {
     this.timingChanged()
   }
   elapsed(entry: Entry, now: number) {
-    return this.controlled
-      ? this.time()
-      : (getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt)
+    if (this.controlled) return this.time()
+    if (entry.handle instanceof MixHandle) return entry.handle.elapsed()
+    return getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt
   }
   private time() {
     return this.clock?.time() ?? 0
@@ -209,8 +221,10 @@ export class ViewAnimation implements PlaybackAnimation {
   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)
+      if (entry.done) continue
+      else if (entry.handle instanceof MixHandle)
+        entry.handle.control(position, this._paused)
+      else driver.control?.(this.view, entry.handle, position, this._paused, command)
   }
   private scheduleArrival() {
     this.cancelArrival?.()
@@ -244,21 +258,38 @@ export class ViewAnimation implements PlaybackAnimation {
     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)
-      },
-    )
+    const startedAt = initial ? entry.startedAt : driver.now() - elapsed
+    const onEnd = (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)
+    }
+    const { property } = entry.track
+    const mix =
+      entry.layer !== undefined ? mixing(this.view, property) : mixOf(this.view, property)
+    entry.handle = mix
+      ? mix.adopt(entry.layer ?? BASE, entry.track, startedAt, onEnd)
+      : driver.play(this.view, entry.track, startedAt, onEnd)
+  }
+
+  /** Moves a natively playing entry into its property's mix, without restarting it. */
+  rehome(entry: Entry) {
+    if (entry.done || entry.handle instanceof MixHandle) return
+    const elapsed = this.elapsed(entry, getDriver().now())
+    const handle = entry.handle
+    entry.generation++
+    getDriver().stop(this.view, handle)
+    this.playEntry(entry, elapsed)
+  }
+  private unloaded = () => {
+    // NativeScript unloads the root view when iOS enters the background.
+    // An explicitly paused owner can resume after that temporary unload.
+    if (this._paused && Application.suspended) return
+    this.stop()
   }
-  private unloaded = () => this.stop()
 
   constructor(
     readonly view: View,
@@ -273,6 +304,18 @@ export class ViewAnimation implements PlaybackAnimation {
           !Number.isFinite(plan.transition.curve.duration)),
     )
     this.finished = new Promise((resolve) => (this.resolve = resolve))
+    this.playbackChanged = registerPlayback(this, () => ({
+      position: this.pendingProgress,
+      time:
+        this.pendingProgress === undefined
+          ? this.time()
+          : this.pendingProgress * this.duration,
+      duration: this.duration,
+      paused: this._paused,
+      ready: this.ready,
+      settled: this.settled,
+      completed: this.settled && this.complete,
+    }))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
     setArrivalTiming(this, {
       read: () => ({
@@ -322,52 +365,79 @@ export class ViewAnimation implements PlaybackAnimation {
     const now = driver.now()
     const entries = entriesOf(this.view)
 
-    const tracks = plans.map(({ property, keyframes, transition, relative, path }) => {
-      const previous = entries.get(property)
+    const made = plans.map((plan) => {
+      const { property, keyframes, transition, relative, path, layer } = plan
+      const key = layer === undefined ? property : `${property}#${layer}`
+      const mixed = layer !== undefined || mixOf(this.view, property) !== undefined
+      const previous = entries.get(key)
       let current: number
       let velocity = 0
       if (previous) {
         const elapsed = elapsedOf(previous, now)
-        current = driver.presented(this.view, property) ?? previous.track.valueAt(elapsed)
+        current =
+          (mixed ? undefined : driver.presented(this.view, property)) ??
+          previous.track.valueAt(elapsed)
         velocity = previous.owner.paused ? 0 : previous.track.velocityAt(elapsed)
-        release(previous, now, false)
+      } else if (mixed) {
+        current =
+          mixOf(this.view, property)?.rest(layer ?? BASE) ??
+          (layer === undefined ? readValue(this.view, property) : identity(property))
       } else {
         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,
+      const build = () => {
+        if (plan.track) return plan.track()
+        if (path)
+          return path.track(
+            property as PathProperty,
+            relative ? current : 0,
+            transition.delay,
+          )
+        return createTrack(
+          property,
+          keyframes.map((value) => {
+            if (value === null) return current
+            if (layer !== undefined || !relative || isColorProperty(property))
+              return value
+            return property === 'opacity' || property.startsWith('scale')
+              ? current * value
+              : current + value
+          }),
+          transition,
+          velocity,
         )
-      return createTrack(
-        property,
-        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,
-      )
+      }
+      return { track: build(), key, layer, previous }
     })
-
-    for (const track of tracks) writeValue(this.view, track.property, track.to)
+    // Validate every trajectory before interrupting any existing property owner.
+    for (const { previous } of made) if (previous) release(previous, now, false)
+    const tracks = made.map(({ track }) => track)
+
+    for (const { track, layer } of made) {
+      const mix =
+        layer !== undefined
+          ? mixing(this.view, track.property)
+          : mixOf(this.view, track.property)
+      if (!mix) writeValue(this.view, track.property, track.to)
+      else if (track.end === 0) mix.setRest(layer ?? BASE, 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()))
+    for (const { track, key, layer } of made) {
       const token = Symbol(track.property)
-      tokens.set(track.property, token)
+      if (layer === undefined) {
+        let tokens = revisions.get(this.view)
+        if (!tokens) revisions.set(this.view, (tokens = new Map()))
+        tokens.set(track.property, token)
+      }
       if (track.end === 0) continue
       const entry: Entry = {
         track,
+        key,
+        layer,
         startedAt: now,
         owner: this,
         handle: undefined,
@@ -376,7 +446,7 @@ export class ViewAnimation implements PlaybackAnimation {
         generation: 0,
         token,
       }
-      entries.set(track.property, entry)
+      entries.set(key, entry)
       this.entries.push(entry)
       this.pending++
     }
@@ -388,11 +458,17 @@ export class ViewAnimation implements PlaybackAnimation {
       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)
+    // Register discrete feedback after the visual animators. Android dispatches
+    // these callbacks in registration order within a frame: feedback should see
+    // that frame's updated pose, not the preceding frame's position.
+    // Scale-zero native playback may already have completed synchronously.
+    if (!this.settled) {
+      this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now, () =>
+        this.time(),
+      )
+      if (this._paused) this.haptics?.pause()
+    }
     if (this.pendingProgress !== undefined) {
       const progress = this.pendingProgress
       this.pendingProgress = undefined
@@ -405,8 +481,8 @@ export class ViewAnimation implements PlaybackAnimation {
   }
 
   private waitForLoad(plans: readonly Plan[]) {
-    for (const { property, keyframes, relative } of plans) {
-      if (relative && !isColorProperty(property)) continue
+    for (const { property, keyframes, relative, layer } of plans) {
+      if (layer !== undefined || (relative && !isColorProperty(property))) continue
       const first = keyframes[0]
       if (first !== null && first !== undefined) writeValue(this.view, property, first)
     }
@@ -438,6 +514,8 @@ export class ViewAnimation implements PlaybackAnimation {
 
 /** Current native presentation when available, otherwise the active curve or model. */
 export function currentValue(view: View, property: Property): number {
+  const mix = mixOf(view, property)
+  if (mix) return mix.value()
   const entry = running.get(view)?.get(property)
   if (!entry) return readValue(view, property)
   const driver = getDriver()
@@ -452,6 +530,22 @@ export function propertyRevision(view: View, property: Property) {
   return revisions.get(view)?.get(property)
 }
 
+/** Internal read-only diagnostics. No observers or frame hooks are installed. */
+export function inspectViewMotion(view: View) {
+  const now = getDriver().now()
+  return [...(running.get(view)?.values() ?? [])].map((entry) => ({
+    owner: entry.owner,
+    handle: entry.handle,
+    key: entry.key,
+    property: entry.track.property,
+    layer: entry.layer,
+    track: entry.track,
+    // A development hook may inspect while playEntry is still obtaining its handle.
+    elapsed: entry.handle === undefined ? 0 : elapsedOf(entry, now),
+    paused: entry.owner.paused,
+  }))
+}
+
 /** 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)
@@ -465,19 +559,69 @@ export function captureValue(view: View, property: Property): () => number | und
   }
 }
 
-/** Stops whatever is animating these properties of the view, or all of them. */
+/** Stops whatever is animating these properties of the view, or all of them, layers included. */
 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))
+  for (const mix of mixesOf(view))
+    if (!properties || properties.includes(mix.property)) mix.freeze()
   const entries = running.get(view)
   if (!entries) return
   const now = getDriver().now()
-  for (const [property, entry] of [...entries]) {
-    if (!properties || properties.includes(property)) release(entry, now, true)
+  for (const entry of [...entries.values()]) {
+    if (!properties || properties.includes(entry.track.property))
+      release(entry, now, true)
   }
 }
 
+/** Stops the regular animations of these properties and leaves their layers running. */
+export function stopBase(view: View, properties: readonly Property[]) {
+  const tokens = revisions.get(view)
+  for (const property of properties) tokens?.set(property, Symbol(property))
+  const now = getDriver().now()
+  for (const property of properties) {
+    const entry = running.get(view)?.get(property)
+    if (entry) release(entry, now, true)
+  }
+}
+
+/** Stops one layer and takes away what it adds, also after it finished. */
+export function stopLayer(view: View, layer: string, properties?: readonly Property[]) {
+  const now = getDriver().now()
+  for (const entry of [...(running.get(view)?.values() ?? [])])
+    if (
+      entry.layer === layer &&
+      (!properties || properties.includes(entry.track.property))
+    )
+      release(entry, now, true)
+  for (const mix of mixesOf(view))
+    if (!properties || properties.includes(mix.property))
+      mix.setRest(layer, identity(mix.property))
+}
+
+/** Writes a property's base value, under its layers when it has any. */
+export function setBase(view: View, property: Property, value: number) {
+  const mix = mixOf(view, property)
+  if (mix) mix.setRest(BASE, value)
+  else writeValue(view, property, value)
+}
+
+/** A property's base value, without what its layers add. */
+export function baseValue(view: View, property: Property): number {
+  return mixOf(view, property)?.rest(BASE) ?? readValue(view, property)
+}
+
+/** The property's mix, created on its first layer; a base playing natively moves into it. */
+function mixing(view: View, property: Property) {
+  const existing = mixOf(view, property)
+  if (existing) return existing
+  const mix = mixFor(view, property)
+  const base = running.get(view)?.get(property)
+  if (base) base.owner.rehome(base)
+  return mix
+}
+
 function entriesOf(view: View) {
   let entries = running.get(view)
   if (!entries) running.set(view, (entries = new Map()))
@@ -486,7 +630,7 @@ function entriesOf(view: View) {
 
 function forget(entry: Entry) {
   const entries = running.get(entry.owner.view)
-  if (entries?.get(entry.track.property) === entry) entries.delete(entry.track.property)
+  if (entries?.get(entry.key) === entry) entries.delete(entry.key)
 }
 
 function release(entry: Entry, now: number, commit: boolean) {
@@ -495,6 +639,11 @@ function release(entry: Entry, now: number, commit: boolean) {
   const { property } = entry.track
   entry.done = true
   forget(entry)
+  if (entry.handle instanceof MixHandle) {
+    entry.handle.mix.detach(entry.layer ?? BASE, commit)
+    entry.owner.ended(false)
+    return
+  }
   if (commit) {
     const value =
       driver.presented(view, property) ?? entry.track.valueAt(elapsedOf(entry, now))

package/src/gesture-native.ts

@@ -0,0 +1,139 @@
+import { isIOS, type View, type ScrollView } from '@nativescript/core'
+import { liveValueInput, type DerivedValue } from './motion-value.js'
+import { nativeLiveNode } from './live-spring-driver.js'
+import { retainScrollDelegate } from './driver/ios-scroll-delegate.js'
+
+export interface GestureSettings {
+  axis: number
+  threshold: number
+  failOffset: number
+  pinch: boolean
+  rotate: boolean
+  tap: boolean
+  doubleTap: boolean
+  contactEvents: boolean
+  minX: number
+  maxX: number
+  minY: number
+  maxY: number
+  minScale: number
+  maxScale: number
+}
+export interface GestureDriver {
+  readonly active: boolean
+  cancel(): void
+  enabled(value: boolean): void
+  settle(values: readonly number[], animated: boolean): void
+  bounds(settings: GestureSettings): void
+  dispose(): void
+}
+export function createGestureDriver(
+  surface: View,
+  scroll: ScrollView | undefined,
+  values: readonly DerivedValue[],
+  options: GestureSettings,
+  callback: (state: number, vx: number, vy: number) => void,
+): GestureDriver {
+  const inputs = values.map(liveValueInput)
+  const nodes = inputs.map((input) => nativeLiveNode(input.node))
+  const changed = (state: number, vx: number, vy: number) => {
+    for (const input of inputs) input.changed()
+    callback(state, vx, vy)
+  }
+  const json = JSON.stringify(options)
+  if (isIOS) {
+    if (typeof JoltGestureSession === 'undefined')
+      throw new Error('Rebuild the native app to use gestures().')
+    if (
+      options.contactEvents &&
+      typeof JoltGestureSession.supportsContactEvents !== 'function'
+    )
+      throw new Error(
+        'Rebuild the native app to use gesture contact events and bottomSheet().',
+      )
+    const [x, y, scale, rotation] = nodes as [
+      JoltLiveSpring,
+      JoltLiveSpring,
+      JoltLiveSpring,
+      JoltLiveSpring,
+    ]
+    const native = JoltGestureSession.attachScrollXYScaleRotationOptionsOnState(
+      surface.nativeViewProtected,
+      scroll?.nativeViewProtected ?? null,
+      x,
+      y,
+      scale,
+      rotation,
+      json,
+      changed,
+    )
+    const releaseDelegate = scroll
+      ? retainScrollDelegate(scroll, () => native.refreshScrollDelegate())
+      : () => {}
+    return {
+      get active() {
+        return native.active
+      },
+      cancel: () => native.cancel(),
+      enabled: (value) => native.setEnabled(value),
+      settle: (values, animated) => {
+        native.settleXYScaleRotationAnimated(
+          values[0]!,
+          values[1]!,
+          values[2]!,
+          values[3]!,
+          animated,
+        )
+        inputs.forEach((input) => input.changed())
+      },
+      bounds: (settings) =>
+        native.updateLeftRightTopBottom(
+          settings.minX,
+          settings.maxX,
+          settings.minY,
+          settings.maxY,
+        ),
+      dispose: () => {
+        releaseDelegate()
+        native.dispose()
+      },
+    }
+  }
+  if (
+    options.contactEvents &&
+    typeof org.rafaelaugusto.jolt.GestureSession.supportsContactEvents !== 'function'
+  )
+    throw new Error(
+      'Rebuild the native app to use gesture contact events and bottomSheet().',
+    )
+  const [x, y, scale, rotation] = nodes as [
+    org.rafaelaugusto.jolt.LiveSpring,
+    org.rafaelaugusto.jolt.LiveSpring,
+    org.rafaelaugusto.jolt.LiveSpring,
+    org.rafaelaugusto.jolt.LiveSpring,
+  ]
+  const native = new org.rafaelaugusto.jolt.GestureSession(
+    surface.nativeViewProtected,
+    scroll?.nativeViewProtected ?? null,
+    x,
+    y,
+    scale,
+    rotation,
+    json,
+    new org.rafaelaugusto.jolt.GestureSession.Listener({ onState: changed }),
+  )
+  return {
+    get active() {
+      return native.isActive()
+    },
+    cancel: () => native.cancel(),
+    enabled: (value) => native.setEnabled(value),
+    settle: (values, animated) => {
+      native.settle(values[0]!, values[1]!, values[2]!, values[3]!, animated)
+      inputs.forEach((input) => input.changed())
+    },
+    bounds: (settings) =>
+      native.updateBounds(settings.minX, settings.maxX, settings.minY, settings.maxY),
+    dispose: () => native.dispose(),
+  }
+}