@rafaelaugusto/jolt 0.1.0-beta.8 → 0.1.0-rc.1

package/src/driver/android-particles.ts

@@ -0,0 +1,118 @@
+import { Application, Color, Utils, type View } from '@nativescript/core'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import type { ParticleSettings } from '../particles.js'
+
+type NativeEmitter = org.rafaelaugusto.jolt.ParticleEmitter
+const live = new WeakMap<View, { emitter?: NativeEmitter; burst?: NativeEmitter }>()
+
+/** Internal diagnostic seam for native conformance, not a public animation API. */
+export function currentAndroidParticles(view: View, overlay = false) {
+  return live.get(view)?.[overlay ? 'burst' : 'emitter']
+}
+
+export function androidParticles(
+  view: View,
+  settings: ParticleSettings,
+  overlay: boolean,
+  owners: WeakMap<View, () => void>,
+): () => void {
+  let stopped = false,
+    queued = false
+  let emitter: NativeEmitter | undefined,
+    target: android.view.View | undefined,
+    unwatch: (() => void) | undefined
+  const key = overlay ? 'burst' : 'emitter'
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    view.off('loaded', schedule)
+    view.off('layoutChanged', schedule)
+    view.off('unloaded', stop)
+    view.style.off('borderTopLeftRadiusChange', schedule)
+    Application.off(Application.suspendEvent, stop)
+    unwatch?.()
+    unwatch = undefined
+    if (owners.get(view) === stop) owners.delete(view)
+    const active = live.get(view)
+    if (active && active[key] === emitter) {
+      delete active[key]
+      if (!active.emitter && !active.burst) live.delete(view)
+    }
+    const native = emitter
+    emitter = target = undefined
+    native?.stop()
+  }
+  const update = () => {
+    if (!view.isLoaded) return
+    if (reducedMotion()) return stop()
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (target && target !== native) return stop()
+    if (emitter) {
+      emitter.refresh(
+        (typeof view.borderRadius === 'number' ? view.borderRadius : 0) *
+          Utils.layout.getDisplayDensity(),
+      )
+      return
+    }
+    if (!native?.getWindowToken() || native.getWidth() <= 0 || native.getHeight() <= 0)
+      return
+    const colors = Array.create('int', settings.colors.length)
+    settings.colors.forEach((color, i) => {
+      colors[i] = new Color(color).argb | 0
+    })
+    target = native
+    emitter = new org.rafaelaugusto.jolt.ParticleEmitter(
+      native,
+      overlay,
+      colors,
+      settings.shape === 'circle' ? 0 : settings.shape === 'rectangle' ? 1 : 2,
+      settings.source === 'center' ? 0 : settings.source === 'top' ? 1 : 2,
+      settings.rate,
+      settings.lifetime,
+      settings.size,
+      settings.velocity,
+      settings.velocityRange,
+      settings.angle,
+      settings.spread,
+      settings.gravity,
+      settings.spin,
+      settings.spinRange,
+      settings.fadeOut,
+      settings.duration ?? -1,
+      new org.rafaelaugusto.jolt.ParticleEmitter.Listener({ onEnd: stop }),
+    )
+    const active = live.get(view) ?? {}
+    active[key] = emitter
+    live.set(view, active)
+    emitter.refresh(
+      (typeof view.borderRadius === 'number' ? view.borderRadius : 0) *
+        Utils.layout.getDisplayDensity(),
+    )
+    emitter.start()
+  }
+  function schedule() {
+    if (stopped || queued) return
+    queued = true
+    void Promise.resolve().then(() => {
+      queued = false
+      if (stopped) return
+      try {
+        update()
+      } catch (error) {
+        stop()
+        throw error
+      }
+    })
+  }
+  owners.set(view, stop)
+  view.on('loaded', schedule)
+  view.on('layoutChanged', schedule)
+  view.on('unloaded', stop)
+  view.style.on('borderTopLeftRadiusChange', schedule)
+  Application.on(Application.suspendEvent, stop)
+  unwatch = onReducedMotion((reduced) => {
+    if (reduced) stop()
+  })
+  schedule()
+  return stop
+}

package/src/driver/android.ts

@@ -4,14 +4,16 @@ import {
   type AndroidPlayback,
 } from './android-playback.js'
 import { isDecorationProperty } from '../decoration.js'
+import { syncLiveSprings } from '../live-spring-driver.js'
 import {
   syncAndroidDecoration,
   playAndroidDecoration,
   presentedAndroidDecoration,
 } from './android-decoration.js'
-import { Utils, type View } from '@nativescript/core'
+import { Application, Utils, type View } from '@nativescript/core'
 import type { NumericProperty } from '../properties.js'
 import type { Driver } from './index.js'
+import { frame } from './frame.js'
 import { isColorProperty } from '../color.js'
 import {
   playAndroidColor,
@@ -31,6 +33,7 @@ function fadeLayer(view: View, nativeView: NativeView): (() => void) | undefined
     view.nativeViewProtected !== nativeView ||
     !(nativeView instanceof ViewGroup) ||
     nativeView.getChildCount() === 0 ||
+    !nativeView.getClipChildren() ||
     !nativeView.isHardwareAccelerated() ||
     nativeView.getLayerType() !== View.LAYER_TYPE_NONE
   )
@@ -57,6 +60,23 @@ function fadeLayer(view: View, nativeView: NativeView): (() => void) | undefined
   return restore
 }
 
+/**
+ * A translucent view is drawn into a buffer of its own size, which cuts off children
+ * that draw outside it. Fade those children one by one instead.
+ */
+function keepOverflow(nativeView: NativeView) {
+  if (
+    android.os.Build.VERSION.SDK_INT >= 24 &&
+    nativeView instanceof android.view.ViewGroup &&
+    !nativeView.getClipChildren() &&
+    nativeView.getHasOverlappingRendering()
+  ) {
+    nativeView.forceHasOverlappingRendering(false)
+    // The render node only picks the flag up when the view draws again.
+    nativeView.invalidate()
+  }
+}
+
 const accessors: Record<
   NumericProperty,
   { get(view: NativeView): number; set(view: NativeView, value: number): void }
@@ -91,6 +111,7 @@ export function createAndroidDriver(): Driver {
 
   return {
     now: () => android.os.SystemClock.uptimeMillis(),
+    frame,
     clock,
     control(_view, handle, elapsed, paused, command) {
       ;(handle as Handle).control(elapsed, paused, command)
@@ -143,6 +164,8 @@ export function createAndroidDriver(): Driver {
             : android.animation.ValueAnimator.RESTART,
         )
       }
+      if (track.property === 'opacity' && track.values.some((value) => value < 1))
+        keepOverflow(nativeView)
       accessors[track.property].set(nativeView, track.values[0]! * scale)
       return androidPlayback(
         animator,
@@ -166,6 +189,7 @@ export function createAndroidDriver(): Driver {
     sync(view) {
       syncAndroidDecoration(view)
       syncAndroidColor(view)
+      syncLiveSprings(view)
     },
 
     elapsed: (handle) => (handle as Handle).elapsed(),
@@ -178,6 +202,44 @@ export function createAndroidDriver(): Driver {
       return nativeView ? accessors[property].get(nativeView) / unit(property) : undefined
     },
 
+    layoutFrame(view) {
+      const native = view.nativeViewProtected as android.view.View | undefined
+      if (!native) return undefined
+      const dip = Utils.layout.toDeviceIndependentPixels
+      return {
+        x: dip(native.getLeft()),
+        y: dip(native.getTop()),
+        width: dip(native.getWidth()),
+        height: dip(native.getHeight()),
+      }
+    },
+
+    afterLayout(view, callback) {
+      const native = view.nativeViewProtected as android.view.View
+      const observer = native.getViewTreeObserver()
+      let active = true
+      const detach = () => {
+        if (!active) return
+        active = false
+        if (observer.isAlive()) observer.removeOnPreDrawListener(listener)
+        else {
+          const current = native.getViewTreeObserver()
+          if (current.isAlive()) current.removeOnPreDrawListener(listener)
+        }
+      }
+      const listener = new android.view.ViewTreeObserver.OnPreDrawListener({
+        onPreDraw() {
+          if (active) {
+            detach()
+            callback()
+          }
+          return true
+        },
+      })
+      observer.addOnPreDrawListener(listener)
+      return detach
+    },
+
     after(ms, callback) {
       // A native marker follows animator duration scale, including changes during playback.
       // Only completion crosses the bridge; there is no JavaScript update listener.
@@ -221,5 +283,11 @@ export function createAndroidDriver(): Driver {
         ) === 0
       )
     },
+
+    watchReducedMotion(callback) {
+      // Android has no broadcast for the animator scale; it can only change in Settings.
+      Application.on(Application.resumeEvent, callback)
+      return () => Application.off(Application.resumeEvent, callback)
+    },
   }
 }

package/src/driver/frame.ts

@@ -0,0 +1,10 @@
+import {
+  cancelAnimationFrame,
+  requestAnimationFrame,
+} from '@nativescript/core/animation-frame'
+
+/** NativeScript schedules subsequent frames with CADisplayLink / Choreographer. */
+export function frame(callback: () => void): () => void {
+  const id = requestAnimationFrame(callback)
+  return () => cancelAnimationFrame(id)
+}

package/src/driver/index.ts

@@ -5,9 +5,18 @@ import type { Track } from '../track.js'
 import { createAndroidDriver } from './android.js'
 import { createIOSDriver } from './ios.js'
 
+export interface LayoutFrame {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
 export interface Driver {
   /** Milliseconds, on the clock the platform's animations run on. */
   now(): number
+  /** One native animation frame; returns an idempotent cancellation function. */
+  frame(callback: () => void): () => void
   /** Starts the track at `startedAt + track.delay` and calls `onEnd` once, however it ends. */
   play(
     view: View,
@@ -34,8 +43,14 @@ export interface Driver {
   presented(view: View, property: Property): number | undefined
   /** Calls back after `ms` of animation time, respecting platform speed settings. */
   after(ms: number, callback: () => void): () => void
+  /** Untransformed native layout bounds in parent DIPs. */
+  layoutFrame?(view: View): LayoutFrame | undefined
+  /** One callback after layout, before drawing; caller requests layout and owns cancellation. */
+  afterLayout?(view: View, callback: () => void): () => void
   /** The platform's accessibility setting: Reduce Motion on iOS, Remove animations on Android. */
   reducedMotion?(): boolean
+  /** Calls back when that setting may have changed; returns a cleanup function. */
+  watchReducedMotion?(callback: () => void): () => void
 }
 
 export function after(ms: number, callback: () => void) {

package/src/driver/ios-gradient.ts

@@ -0,0 +1,136 @@
+import { Color, type View } from '@nativescript/core'
+import {
+  gradientPoints,
+  type GradientFrame,
+  type GradientPainter,
+  type GradientType,
+} from '../gradient.js'
+
+const keys = ['colors', 'locations', 'startPoint', 'endPoint'] as const
+
+/** A CAGradientLayer at the back of the view's layer: above its background, below its children. */
+export function iosGradient(view: View, type: GradientType): GradientPainter {
+  const layer = CAGradientLayer.new()
+  layer.type =
+    type === 'linear'
+      ? kCAGradientLayerAxial
+      : type === 'radial'
+        ? kCAGradientLayerRadial
+        : kCAGradientLayerConic
+  let current: GradientFrame | undefined
+  let generation = 0
+
+  const native = () => view.nativeViewProtected as UIView | undefined
+  const size = () => {
+    const bounds = native()?.layer.bounds
+    return { width: bounds?.size.width ?? 0, height: bounds?.size.height ?? 0 }
+  }
+  const values = (frame: GradientFrame) => {
+    const { width, height } = size()
+    const { start, end: toward } = gradientPoints(type, frame, width, height)
+    // Core Animation starts a conic gradient on the side opposite its end point.
+    const end =
+      type === 'conic' ? { x: 2 * start.x - toward.x, y: 2 * start.y - toward.y } : toward
+    return {
+      colors: NSArray.arrayWithArray(
+        frame.colors.map((argb) => new Color(argb).ios.CGColor),
+      ),
+      locations: NSArray.arrayWithArray(frame.stops),
+      startPoint: NSValue.valueWithCGPoint(CGPointMake(start.x, start.y)),
+      endPoint: NSValue.valueWithCGPoint(CGPointMake(end.x, end.y)),
+    }
+  }
+  const attach = () => {
+    const host = native()
+    if (!host) return
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    if (layer.superlayer !== host.layer) host.layer.insertSublayerAtIndex(layer, 0)
+    layer.frame = host.layer.bounds
+    layer.cornerRadius =
+      typeof view.borderRadius === 'number' ? view.borderRadius : host.layer.cornerRadius
+    if (current) {
+      const model = values(current)
+      layer.colors = model.colors
+      layer.locations = model.locations
+      layer.startPoint = model.startPoint.CGPointValue
+      layer.endPoint = model.endPoint.CGPointValue
+    }
+    CATransaction.commit()
+  }
+  view.on('loaded', attach)
+  view.on('layoutChanged', attach)
+  view.style.on('borderTopLeftRadiusChange', attach)
+
+  return {
+    paint(frame) {
+      layer.speed = 1
+      layer.timeOffset = 0
+      layer.beginTime = 0
+      current = frame
+      generation++
+      for (const key of keys) layer.removeAnimationForKey(`jolt:gradient:${key}`)
+      attach()
+    },
+    play(frames, times, timing, onEnd) {
+      const instance = ++generation
+      current = frames[frames.length - 1]!
+      attach()
+      const sampled = frames.map(values)
+      const now = CACurrentMediaTime()
+      const parentTime = () =>
+        layer.superlayer?.convertTimeFromLayer(CACurrentMediaTime(), null) ??
+        CACurrentMediaTime()
+      CATransaction.begin()
+      CATransaction.setDisableActions(true)
+      layer.speed = 1
+      layer.timeOffset = 0
+      layer.beginTime = layer.superlayer?.convertTimeFromLayer(now, null) ?? now
+      if (timing.repeat !== Infinity)
+        CATransaction.setCompletionBlock(() => {
+          if (instance === generation) onEnd(true)
+        })
+      for (const key of keys) {
+        const animation = CAKeyframeAnimation.animationWithKeyPath(key)
+        animation.values = NSArray.arrayWithArray(sampled.map((value) => value[key]))
+        animation.keyTimes = NSArray.arrayWithArray(times as number[])
+        animation.duration = Math.max(timing.duration, 1) / 1000
+        animation.beginTime = Math.max(0.000001, timing.delay / 1000)
+        animation.fillMode = kCAFillModeBackwards
+        if (timing.repeat > 0) {
+          animation.autoreverses = timing.reverse
+          animation.repeatCount = timing.reverse
+            ? (timing.repeat + 1) / 2
+            : timing.repeat + 1
+        }
+        layer.addAnimationForKey(animation, `jolt:gradient:${key}`)
+      }
+      CATransaction.commit()
+      return {
+        control(elapsed, paused) {
+          if (instance !== generation) return
+          CATransaction.begin()
+          CATransaction.setDisableActions(true)
+          layer.speed = paused ? 0 : 1
+          layer.timeOffset = paused ? elapsed / 1000 : 0
+          layer.beginTime = paused ? 0 : parentTime() - elapsed / 1000
+          CATransaction.commit()
+        },
+        cancel() {
+          if (instance !== generation) return
+          generation++
+          for (const key of keys) layer.removeAnimationForKey(`jolt:gradient:${key}`)
+          onEnd(false)
+        },
+      }
+    },
+    remove() {
+      generation++
+      view.off('loaded', attach)
+      view.off('layoutChanged', attach)
+      view.style.off('borderTopLeftRadiusChange', attach)
+      layer.removeAllAnimations()
+      layer.removeFromSuperlayer()
+    },
+  }
+}

package/src/driver/ios-layout.ts

@@ -0,0 +1,63 @@
+import type { View } from '@nativescript/core'
+
+type LayoutView = View & {
+  _isTransformed: boolean
+  _modifyNativeViewFrame(native: UIView, frame: CGRect): void
+}
+const retained = new WeakMap<View, { count: number; restore(): void }>()
+
+/**
+ * NativeScript caches whether its JS transform is nonidentity. Interactive native
+ * playback can move the actual model while that cached destination is identity.
+ * Let Core reset/restore the real transform when it next assigns a layout frame.
+ * This hook belongs only to the opted-in instance and only while tracks own it.
+ */
+export function retainInteractiveLayout(view: View): () => void {
+  const host = view as LayoutView
+  let entry = retained.get(view)
+  if (!entry) {
+    const original = host._modifyNativeViewFrame
+    if (typeof original !== 'function') return () => {}
+    const descriptor = Object.getOwnPropertyDescriptor(host, '_modifyNativeViewFrame')
+    let active = true
+    const wrapper: LayoutView['_modifyNativeViewFrame'] = function (
+      this: LayoutView,
+      native,
+      frame,
+    ) {
+      if (active)
+        this._isTransformed = !CATransform3DEqualToTransform(
+          native.layer.transform,
+          CATransform3DIdentity,
+        )
+      original.call(this, native, frame)
+    }
+    host._modifyNativeViewFrame = wrapper
+    entry = {
+      count: 0,
+      restore() {
+        active = false
+        const native = host.nativeViewProtected as UIView | undefined
+        if (native)
+          host._isTransformed = !CATransform3DEqualToTransform(
+            native.layer.transform,
+            CATransform3DIdentity,
+          )
+        if (host._modifyNativeViewFrame !== wrapper) return
+        if (descriptor) Object.defineProperty(host, '_modifyNativeViewFrame', descriptor)
+        else delete (host as Partial<LayoutView>)._modifyNativeViewFrame
+      },
+    }
+    retained.set(view, entry)
+  }
+  entry.count++
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    if (--entry.count === 0) {
+      entry.restore()
+      retained.delete(view)
+    }
+  }
+}

package/src/driver/ios-scroll-delegate.ts

@@ -0,0 +1,23 @@
+import type { ScrollView } from '@nativescript/core'
+
+/** Preserve Core's lazy scroll listener attach/detach without adding a JS scroll observer. */
+export function retainScrollDelegate(scroll: ScrollView, refresh: () => void) {
+  const host = scroll as ScrollView & { attachNative(): void; detachNative(): void }
+  const restore: (() => void)[] = []
+  for (const key of ['attachNative', 'detachNative'] as const) {
+    const original = host[key]
+    if (typeof original !== 'function') continue
+    const descriptor = Object.getOwnPropertyDescriptor(host, key)
+    const wrapper = function (this: typeof host) {
+      original.call(this)
+      refresh()
+    }
+    host[key] = wrapper
+    restore.push(() => {
+      if (host[key] !== wrapper) return
+      if (descriptor) Object.defineProperty(host, key, descriptor)
+      else delete (host as Partial<typeof host>)[key]
+    })
+  }
+  return () => restore.forEach((action) => action())
+}

package/src/driver/ios.ts

@@ -1,4 +1,5 @@
 import { iosPlayback } from './ios-playback.js'
+import { syncLiveSprings } from '../live-spring-driver.js'
 import { isDecorationProperty } from '../decoration.js'
 import {
   playIOSDecoration,
@@ -12,6 +13,8 @@ import { isColorProperty } from '../color.js'
 import { playIOSColor, presentedIOSColor } from './ios-color.js'
 import { after, type Driver } from './index.js'
 import { hasInteractionSurface } from '../interaction-surface.js'
+import { retainInteractiveLayout } from './ios-layout.js'
+import { frame } from './frame.js'
 
 interface Handle {
   stop(): void
@@ -58,6 +61,7 @@ function ensurePerspective(view: View, layers: CALayer[]) {
 export function createIOSDriver(): Driver {
   return {
     now: () => CACurrentMediaTime() * 1000,
+    frame,
 
     play(view, track, startedAt, onEnd): Handle {
       if (isDecorationProperty(track.property))
@@ -72,28 +76,36 @@ export function createIOSDriver(): Driver {
           throw new Error('Rebuild the iOS app to enable Jolt interaction surfaces.')
         if (track.property === 'rotateX' || track.property === 'rotateY')
           ensurePerspective(view, layers)
+        const releaseLayout = retainInteractiveLayout(view)
         const suspend = () => stopView(view, [track.property])
         const completed = (finished: boolean) => {
           Application.off(Application.suspendEvent, suspend)
+          releaseLayout()
           onEnd(finished)
         }
-        const native =
-          JoltInteractiveAnimation.startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
-            view.nativeViewProtected,
-            NSArray.arrayWithArray(layers),
-            keyPaths[track.property as NumericProperty],
-            NSArray.arrayWithArray(
-              track.values.map((value) => (rotation ? radians(value) : value)),
-            ),
-            NSArray.arrayWithArray(track.times as number[]),
-            track.duration,
-            track.delay,
-            track.repeat,
-            track.reverse,
-            rotation ? radians(track.to) : track.to,
-            startedAt,
-            completed,
-          )
+        let native: JoltInteractiveAnimation
+        try {
+          native =
+            JoltInteractiveAnimation.startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
+              view.nativeViewProtected,
+              NSArray.arrayWithArray(layers),
+              keyPaths[track.property as NumericProperty],
+              NSArray.arrayWithArray(
+                track.values.map((value) => (rotation ? radians(value) : value)),
+              ),
+              NSArray.arrayWithArray(track.times as number[]),
+              track.duration,
+              track.delay,
+              track.repeat,
+              track.reverse,
+              rotation ? radians(track.to) : track.to,
+              startedAt,
+              completed,
+            )
+        } catch (error) {
+          releaseLayout()
+          throw error
+        }
         Application.on(Application.suspendEvent, suspend)
         return {
           elapsed: () => native.elapsed,
@@ -186,6 +198,7 @@ export function createIOSDriver(): Driver {
           view.nativeViewProtected,
           excluding ? (keyPaths[excluding as NumericProperty] ?? null) : null,
         )
+      syncLiveSprings(view)
     },
 
     presented(view, property) {
@@ -201,8 +214,48 @@ export function createIOSDriver(): Driver {
       return property.startsWith('rotate') ? (value * 180) / Math.PI : Number(value)
     },
 
+    layoutFrame(view) {
+      const native = view.nativeViewProtected as UIView | undefined
+      if (!native) return undefined
+      const { width, height } = native.bounds.size
+      const { position, anchorPoint } = native.layer
+      return {
+        x: position.x - width * anchorPoint.x,
+        y: position.y - height * anchorPoint.y,
+        width,
+        height,
+      }
+    },
+
+    afterLayout(view, callback) {
+      const original = view.layout
+      const descriptor = Object.getOwnPropertyDescriptor(view, 'layout')
+      let active = true
+      const detach = () => {
+        active = false
+        if (view.layout !== wrapper) return
+        if (descriptor) Object.defineProperty(view, 'layout', descriptor)
+        else delete (view as Partial<View>).layout
+      }
+      const wrapper: View['layout'] = function (this: View, ...args) {
+        original.apply(this, args)
+        if (active) {
+          detach()
+          callback()
+        }
+      }
+      view.layout = wrapper
+      return detach
+    },
+
     after,
 
     reducedMotion: () => UIAccessibilityIsReduceMotionEnabled(),
+
+    watchReducedMotion(callback) {
+      const name = UIAccessibilityReduceMotionStatusDidChangeNotification
+      const observer = Application.ios.addNotificationObserver(name, callback)
+      return () => Application.ios.removeNotificationObserver(observer, name)
+    },
   }
 }