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

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

@@ -5,11 +5,13 @@ 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'
 
 interface Handle {
   stop(): void
@@ -65,6 +67,40 @@ 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 suspend = () => stopView(view, [track.property])
+        const completed = (finished: boolean) => {
+          Application.off(Application.suspendEvent, suspend)
+          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,
+          )
+        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 +179,27 @@ 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) =>
-      isDecorationProperty(property)
-        ? presentedIOSDecoration(view, property)
-        : isColorProperty(property)
-          ? presentedIOSColor(view, property)
-          : undefined,
+    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)
+    },
 
     after,
 

package/src/engine.ts

@@ -436,6 +436,17 @@ 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()))
+  )
+}
+
 /** 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)

package/src/index.ts

@@ -2,6 +2,10 @@ export { animate, decay, stop } from './animate.js'
 export { sequence } from './sequence.js'
 export type { Step, SequenceOptions, SequencePosition } from './sequence.js'
 export { press } from './press.js'
+export { interactionSurface } from './interaction-surface.js'
+export type { InteractionSurface } from './interaction-surface.js'
+export { drag } from './drag.js'
+export type { Drag, DragOptions, DragPoint, DragEvent, DragRelease } from './drag.js'
 export { scrollLinked } from './scroll-linked.js'
 export type { ScrollLinkedOptions } from './scroll-linked.js'
 export { animateItems } from './items.js'
@@ -50,3 +54,13 @@ export type { PlaybackAnimation } from './playback.js'
 export type { Animation } from './engine.js'
 export type { ColorValue, ColorKeyframes } from './color.js'
 export type * from './types.js'
+export { motionScope } from './motion-scope.js'
+export type { MotionScope, MotionResource } from './motion-scope.js'
+export { motionStates } from './motion-states.js'
+export type {
+  MotionStates,
+  MotionStatesOptions,
+  MotionState,
+  MotionValues,
+  StateTransition,
+} from './motion-states.js'

package/src/interaction-surface.ts

@@ -0,0 +1,41 @@
+import type { View, ViewBase } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Target } from './types.js'
+
+const surfaces = new WeakMap<ViewBase, Set<object>>()
+export interface InteractionSurface {
+  readonly disposed: boolean
+  /** Existing animations retain their driver until they end. Disables future opt-in. */
+  dispose(): void
+}
+
+/** Opt a view/subtree into native geometry updates before starting its animations. */
+export function interactionSurface(target: Target): InteractionSurface {
+  const view = toView(target)
+  let tokens = surfaces.get(view)
+  if (!tokens) surfaces.set(view, (tokens = new Set()))
+  const token = {}
+  tokens.add(token)
+  let disposed = false
+  return {
+    get disposed() {
+      return disposed
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      tokens.delete(token)
+      if (!tokens.size) surfaces.delete(view)
+    },
+  }
+}
+
+/** Evaluated at animation start; no per-frame JS traversal. */
+export function hasInteractionSurface(view: View): boolean {
+  let current: ViewBase | undefined = view
+  while (current) {
+    if (surfaces.get(current)?.size) return true
+    current = current.parent
+  }
+  return false
+}

package/src/ios-plugin.d.ts

@@ -1,3 +1,25 @@
+declare class JoltInteractiveAnimation extends NSObject {
+  static startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
+    view: UIView,
+    layers: NSArray<CALayer>,
+    keyPath: string,
+    values: NSArray<number>,
+    times: NSArray<number>,
+    duration: number,
+    delay: number,
+    repeat: number,
+    reverse: boolean,
+    finalValue: number,
+    startedAt: number,
+    completion: (completed: boolean) => void,
+  ): JoltInteractiveAnimation
+  static syncViewExcluding(view: UIView, keyPath: string | null): void
+  static valueForViewKeyPath(view: UIView, keyPath: string): number | null
+  static activeCount(): number
+  readonly elapsed: number
+  controlPaused(elapsed: number, paused: boolean): void
+  cancel(): void
+}
 declare class JoltImageEffect extends NSObject {
   stopPreservingImage(): void
   static createWithViewDestinationModeOriginXOriginYAmplitudeRadiusDurationSeedListener(