@rafaelaugusto/jolt 0.1.0-beta.7 → 0.1.0-beta.9

package/src/drag.ts

@@ -0,0 +1,395 @@
+import {
+  Application,
+  type EventData,
+  type PanGestureEventData,
+  type TouchGestureEventData,
+  type View,
+} from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import { DEFAULT_FRICTION } from './decay.js'
+import { DragInput } from './drag-input.js'
+import {
+  clampDrag,
+  resistDrag,
+  resumeDrag,
+  solveDragRelease,
+  type DragCurve,
+} from './drag-physics.js'
+import { currentValue, ViewAnimation, type Plan } from './engine.js'
+import type { PlaybackAnimation } from './playback.js'
+import { readValue, writeValue } from './properties.js'
+import type { Target } from './types.js'
+
+export interface DragPoint {
+  readonly x: number
+  readonly y: number
+}
+export interface DragEvent extends DragPoint {
+  /** DIPs per second, in the same coordinates as the translation. */
+  readonly velocityX: number
+  readonly velocityY: number
+}
+export interface DragRelease extends DragEvent {
+  readonly target: DragPoint
+  /** False on interruption/cancellation. Check before applying completion effects. */
+  readonly animation: PlaybackAnimation
+}
+export interface DragOptions {
+  /** Defaults to both. One finger only. */
+  axis?: 'x' | 'y' | 'both'
+  /** Absolute translateX/translateY limits in DIPs; omitted edges are unbounded. */
+  bounds?: { left?: number; right?: number; top?: number; bottom?: number }
+  /** Closest stop to the projected landing. Arrays apply to every enabled axis. */
+  snap?: readonly number[] | { x?: readonly number[]; y?: readonly number[] }
+  /** Resist beyond bounds and spring back. Defaults to false (hard limits). */
+  rubberband?: boolean
+  /** Decay retention per millisecond. Defaults to 0.998. */
+  friction?: number
+  onStart?: (event: DragEvent) => void
+  onMove?: (event: DragEvent) => void
+  onRelease?: (event: DragRelease) => void
+  onCancel?: (event: DragEvent) => void
+  onSettle?: (position: DragPoint) => void
+}
+export interface Drag {
+  readonly dragging: boolean
+  readonly settling: boolean
+  readonly paused: boolean
+  readonly disposed: boolean
+  /** Current presentation, including a native release animation in flight. */
+  readonly position: DragPoint
+  /** Cancel contact/release at its visible position, keeping the subscription. */
+  cancel(): void
+  /** Cancel and detach input. play() accepts new gestures; cancelled work stays cancelled. */
+  pause(): void
+  play(): void
+  dispose(): void
+}
+
+type Axis = 'x' | 'y'
+interface Settings {
+  axes: Axis[]
+  curves: Record<Axis, DragCurve>
+  callbacks: Pick<
+    DragOptions,
+    'onStart' | 'onMove' | 'onRelease' | 'onCancel' | 'onSettle'
+  >
+}
+const owners = new WeakMap<View, Drag>()
+
+function settings(options: DragOptions): Settings {
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Drag options must be an object.')
+  const axis = options.axis ?? 'both'
+  if (!['x', 'y', 'both'].includes(axis))
+    throw new TypeError('Drag axis must be x, y or both.')
+  const friction = options.friction ?? DEFAULT_FRICTION
+  if (!Number.isFinite(friction) || friction <= 0 || friction >= 1)
+    throw new RangeError('Drag friction must be between 0 and 1 exclusively.')
+  if (options.rubberband !== undefined && typeof options.rubberband !== 'boolean')
+    throw new TypeError('Drag rubberband must be boolean.')
+  const bounds = options.bounds ?? {}
+  if (
+    typeof bounds !== 'object' ||
+    Array.isArray(bounds) ||
+    Object.entries(bounds).some(
+      ([key, value]) =>
+        !['left', 'right', 'top', 'bottom'].includes(key) ||
+        (value !== undefined && !Number.isFinite(value)),
+    )
+  )
+    throw new RangeError('Drag bounds must have finite left/right/top/bottom edges.')
+  const x: readonly [number, number] = [
+    bounds.left ?? -Infinity,
+    bounds.right ?? Infinity,
+  ]
+  const y: readonly [number, number] = [
+    bounds.top ?? -Infinity,
+    bounds.bottom ?? Infinity,
+  ]
+  if (x[0] > x[1] || y[0] > y[1]) throw new RangeError('Drag bounds must be ordered.')
+  const snap = options.snap
+  const shared = Array.isArray(snap)
+  if (
+    snap !== undefined &&
+    !shared &&
+    (!snap ||
+      typeof snap !== 'object' ||
+      Object.keys(snap).some((key) => key !== 'x' && key !== 'y'))
+  )
+    throw new TypeError('Drag snap must be an array or x/y arrays.')
+  const stops = (
+    value: readonly number[] | undefined,
+    range: readonly [number, number],
+  ) => {
+    if (value === undefined) return undefined
+    if (
+      !Array.isArray(value) ||
+      !value.length ||
+      ![...value].every((n) => Number.isFinite(n) && n >= range[0] && n <= range[1])
+    )
+      throw new RangeError('Drag snap needs nonempty finite positions within bounds.')
+    return [...value]
+  }
+  const perAxis = snap as { x?: readonly number[]; y?: readonly number[] } | undefined
+  const axes: Axis[] = axis === 'both' ? ['x', 'y'] : [axis]
+  const curves = Object.fromEntries(
+    (['x', 'y'] as const).map((key) => [
+      key,
+      {
+        type: 'drag',
+        velocity: 0,
+        friction,
+        bounds: key === 'x' ? x : y,
+        snap: stops(
+          shared && axes.includes(key) ? snap : perAxis?.[key],
+          key === 'x' ? x : y,
+        ),
+        rubberband: options.rubberband ?? false,
+      },
+    ]),
+  ) as Record<Axis, DragCurve>
+  const callbacks = {
+    onStart: options.onStart,
+    onMove: options.onMove,
+    onRelease: options.onRelease,
+    onCancel: options.onCancel,
+    onSettle: options.onSettle,
+  }
+  for (const callback of Object.values(callbacks))
+    if (callback !== undefined && typeof callback !== 'function')
+      throw new TypeError('Drag callbacks must be functions.')
+  return { axes, curves, callbacks }
+}
+
+/** Main-thread pan updates; release physics play through Jolt's native animation drivers. */
+export function drag(target: Target, options: DragOptions = {}): Drag {
+  const view = toView(target)
+  const config = settings(options) // Invalid replacements leave the existing owner intact.
+  const previous = owners.get(view)
+  const controller = new DragController(view, config)
+  owners.set(view, controller)
+  // onCancel may synchronously install another drag. The most recent owner wins.
+  try {
+    previous?.dispose()
+  } catch (error) {
+    controller.dispose()
+    throw error
+  }
+  return controller
+}
+
+class DragController implements Drag {
+  private active = false
+  private disabled = false
+  private destroyed = false
+  private background = false
+  private attached = false
+  private blocked = false
+  private generation = 0
+  private release: PlaybackAnimation | undefined
+  private input = new DragInput()
+  private origin = { x: 0, y: 0 }
+  private last: DragEvent = { x: 0, y: 0, velocityX: 0, velocityY: 0 }
+  private lengths = { x: 200, y: 200 }
+  constructor(
+    private view: View,
+    private config: Settings,
+  ) {
+    view.on('loaded', this.attach)
+    view.on('unloaded', this.unload)
+    Application.on(Application.suspendEvent, this.suspend)
+    Application.on(Application.resumeEvent, this.resume)
+    this.attach()
+  }
+  get dragging() {
+    return this.active
+  }
+  get settling() {
+    return !!this.release
+  }
+  get paused() {
+    return this.disabled
+  }
+  get disposed() {
+    return this.destroyed
+  }
+  get position(): DragPoint {
+    return { x: currentValue(this.view, 'x'), y: currentValue(this.view, 'y') }
+  }
+  cancel = () => {
+    const wasActive = this.active
+    this.active = false
+    this.blocked = true
+    this.generation++
+    const release = this.release
+    this.release = undefined
+    release?.stop()
+    this.input.reset()
+    if (wasActive)
+      this.config.callbacks.onCancel?.({ ...this.last, velocityX: 0, velocityY: 0 })
+  }
+  pause = () => {
+    if (this.destroyed || this.disabled) return
+    this.disabled = true
+    this.detach()
+  }
+  play = () => {
+    if (this.destroyed) return
+    this.disabled = false
+    this.attach()
+  }
+  dispose = () => {
+    if (this.destroyed) return
+    this.destroyed = true
+    this.view.off('loaded', this.attach)
+    this.view.off('unloaded', this.unload)
+    Application.off(Application.suspendEvent, this.suspend)
+    Application.off(Application.resumeEvent, this.resume)
+    if (owners.get(this.view) === this) owners.delete(this.view)
+    this.detach()
+  }
+  private attach = () => {
+    if (
+      this.attached ||
+      this.destroyed ||
+      this.disabled ||
+      this.background ||
+      !this.view.isLoaded
+    )
+      return
+    this.blocked = false
+    this.attached = true
+    this.view.on('touch', this.touch)
+    this.view.on('pan', this.pan)
+  }
+  private detach = () => {
+    this.attached = false
+    this.view.off('touch', this.touch)
+    this.view.off('pan', this.pan)
+    this.cancel()
+  }
+  private unload = () => this.detach()
+  private suspend = () => {
+    this.background = true
+    this.detach()
+  }
+  private resume = () => {
+    this.background = false
+    this.attach()
+  }
+  private touch = (data: EventData) => {
+    const event = data as TouchGestureEventData
+    if (event.action === 'down') {
+      this.cancel()
+      this.blocked = false
+    } else if (event.action === 'cancel') this.cancel()
+  }
+  private pan = (data: EventData) => {
+    const event = data as PanGestureEventData
+    if (!this.attached || this.destroyed || this.disabled || this.background) return
+    if (this.view.isEnabled === false) {
+      this.cancel()
+      return
+    }
+    if (event.state === 1) this.input.reset()
+    const input = this.input.read(event, this.view)
+    if (input.cancelled) {
+      this.cancel()
+      return
+    }
+    if (this.blocked) return
+    if (event.state === 1) {
+      this.cancel()
+      if (!this.attached || this.destroyed || this.disabled) return
+      this.blocked = false
+      // Claim just the enabled axes, preserving the native presentation on takeover.
+      stop(this.view, this.config.axes)
+      this.origin = { x: readValue(this.view, 'x'), y: readValue(this.view, 'y') }
+      const size =
+        (this.view.parent as View | undefined)?.getActualSize() ??
+        this.view.getActualSize()
+      this.lengths = {
+        x: Math.max(1, size.width || 200),
+        y: Math.max(1, size.height || 200),
+      }
+      this.active = true
+      this.last = { ...this.origin, velocityX: 0, velocityY: 0 }
+      for (const axis of this.config.axes) {
+        const curve = this.config.curves[axis]
+        if (!curve.rubberband) continue
+        const resumed = resumeDrag(this.origin[axis], curve.bounds, this.lengths[axis])
+        this.origin[axis] = resumed.origin
+        this.lengths[axis] = resumed.length
+      }
+      this.input.read(event, this.view)
+      this.emit(() => this.config.callbacks.onStart?.({ ...this.last }))
+    }
+    if (!this.active) return
+    const generation = this.generation
+    if (Number.isFinite(input.x) && Number.isFinite(input.y)) {
+      const position = { x: this.last.x, y: this.last.y }
+      let vx = 0,
+        vy = 0
+      for (const axis of this.config.axes) {
+        const curve = this.config.curves[axis]
+        const raw = this.origin[axis] + input[axis]
+        const distance = raw - clampDrag(raw, curve.bounds)
+        const resistance =
+          distance === 0
+            ? 1
+            : curve.rubberband
+              ? 0.55 / (1 + Math.abs(distance) / this.lengths[axis]) ** 2
+              : 0
+        position[axis] = curve.rubberband
+          ? resistDrag(raw, curve.bounds, this.lengths[axis])
+          : clampDrag(raw, curve.bounds)
+        if (axis === 'x') vx = input.velocityX * resistance
+        else vy = input.velocityY * resistance
+        stop(this.view, [axis])
+        writeValue(this.view, axis, position[axis])
+      }
+      this.last = { ...position, velocityX: vx, velocityY: vy }
+      if (event.state !== 3)
+        this.emit(() => this.config.callbacks.onMove?.({ ...this.last }))
+    }
+    if (!this.active || generation !== this.generation) return
+    if (event.state === 3) this.emit(() => this.finish())
+  }
+  private emit(callback: () => void) {
+    try {
+      callback()
+    } catch (error) {
+      // A failing application callback must not leave live input or an orphaned fling.
+      this.active = false
+      this.dispose()
+      throw error
+    }
+  }
+  private finish() {
+    this.active = false
+    const generation = ++this.generation
+    const event = { ...this.last }
+    const target = { x: event.x, y: event.y }
+    const plans: Plan[] = this.config.axes.map((axis) => {
+      const curve = {
+        ...this.config.curves[axis],
+        velocity: axis === 'x' ? event.velocityX : event.velocityY,
+      }
+      target[axis] = solveDragRelease(event[axis], curve).to
+      return {
+        property: axis,
+        keyframes: [null, null],
+        transition: { curve, delay: 0, repeat: 0, reverse: false },
+      }
+    })
+    const animation = new ViewAnimation(this.view, plans)
+    this.release = animation
+    void animation.finished.then((finished) => {
+      if (generation !== this.generation || this.destroyed) return
+      this.release = undefined
+      if (finished) this.config.callbacks.onSettle?.({ ...target })
+    })
+    this.emit(() => this.config.callbacks.onRelease?.({ ...event, target, animation }))
+  }
+}

package/src/driver/android.ts

@@ -178,6 +178,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.

package/src/driver/index.ts

@@ -5,6 +5,13 @@ 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
@@ -34,6 +41,10 @@ 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
 }

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.ts

@@ -5,11 +5,14 @@ import {
   presentedIOSDecoration,
   syncIOSDecoration,
 } from './ios-decoration.js'
-import type { View } from '@nativescript/core'
+import { Application, type View } from '@nativescript/core'
+import { stopView } from '../engine.js'
 import type { NumericProperty } from '../properties.js'
 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'
 
 interface Handle {
   stop(): void
@@ -65,6 +68,48 @@ export function createIOSDriver(): Driver {
       const layers = layersOf(view)
       const key = `jolt:${track.property}`
       const rotation = track.property.startsWith('rotate')
+      if (hasInteractionSurface(view)) {
+        if (typeof JoltInteractiveAnimation === 'undefined')
+          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)
+        }
+        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,
+          control: (time, paused) => native.controlPaused(time, paused),
+          stop: () => native.cancel(),
+        }
+      }
       const infinite = track.repeat === Infinity
       if (track.property === 'rotateX' || track.property === 'rotateY') {
         ensurePerspective(view, layers)
@@ -143,14 +188,61 @@ export function createIOSDriver(): Driver {
     },
     elapsed: (handle) => (handle as Handle).elapsed(),
 
-    sync: syncIOSDecoration,
+    sync(view, excluding) {
+      syncIOSDecoration(view, excluding)
+      if (view.nativeViewProtected && typeof JoltInteractiveAnimation !== 'undefined')
+        JoltInteractiveAnimation.syncViewExcluding(
+          view.nativeViewProtected,
+          excluding ? (keyPaths[excluding as NumericProperty] ?? null) : null,
+        )
+    },
+
+    presented(view, property) {
+      if (isDecorationProperty(property)) return presentedIOSDecoration(view, property)
+      if (isColorProperty(property)) return presentedIOSColor(view, property)
+      if (!view.nativeViewProtected || typeof JoltInteractiveAnimation === 'undefined')
+        return undefined
+      const value = JoltInteractiveAnimation.valueForViewKeyPath(
+        view.nativeViewProtected,
+        keyPaths[property],
+      )
+      if (value === null || value === undefined) return undefined
+      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,
+      }
+    },
 
-    presented: (view, property) =>
-      isDecorationProperty(property)
-        ? presentedIOSDecoration(view, property)
-        : isColorProperty(property)
-          ? presentedIOSColor(view, property)
-          : undefined,
+    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,
 

package/src/engine.ts

@@ -436,6 +436,35 @@ 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 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)