@rafaelaugusto/jolt 0.1.0-beta.15 → 0.1.0-beta.16

package/src/gestures/index.ts

@@ -0,0 +1,350 @@
+import { Application, GridLayout, ScrollView, Trace, isAndroid } from '@nativescript/core'
+import {
+  createGestureDriver,
+  type GestureDriver,
+  type GestureSettings,
+} from '../gesture-native.js'
+import {
+  motionValue,
+  springValue,
+  type DerivedValue,
+  type SpringValueOptions,
+} from '../motion-value.js'
+
+/** A GridLayout that provides native gesture dispatch and nested-scroll consumption. */
+export class GestureSurface extends GridLayout {
+  override createNativeView() {
+    if (isAndroid) {
+      if (typeof org.rafaelaugusto.jolt.GestureSurface !== 'function')
+        throw new Error('Rebuild the native app to use GestureSurface.')
+      return new org.rafaelaugusto.jolt.GestureSurface(this._context)
+    }
+    return super.createNativeView()
+  }
+}
+export interface GesturePosition {
+  x: number
+  y: number
+  scale: number
+  rotate: number
+}
+export interface GestureEvent extends GesturePosition {
+  velocityX: number
+  velocityY: number
+}
+export interface GestureBounds {
+  left?: number
+  right?: number
+  top?: number
+  bottom?: number
+}
+export interface GesturesOptions {
+  pan?:
+    | boolean
+    | {
+        axis?: 'x' | 'y' | 'both'
+        threshold?: number
+        failOffset?: number
+        bounds?: GestureBounds
+      }
+  pinch?: boolean | { min?: number; max?: number }
+  rotate?: boolean
+  initial?: Partial<GesturePosition>
+  spring?: Pick<SpringValueOptions, 'stiffness' | 'damping' | 'mass'>
+  /** A descendant, vertical NativeScript ScrollView. Other list plugins are not supported. */
+  scrollView?: ScrollView
+  onStart?: (event: GestureEvent) => void
+  onEnd?: (event: GestureEvent) => void
+  onCancel?: (event: GestureEvent) => void
+  onTap?: (event: GestureEvent) => void
+  onDoubleTap?: (event: GestureEvent) => void
+}
+export interface Gestures {
+  readonly x: DerivedValue
+  readonly y: DerivedValue
+  readonly scale: DerivedValue
+  readonly rotate: DerivedValue
+  readonly position: GesturePosition
+  readonly active: boolean
+  readonly paused: boolean
+  readonly disposed: boolean
+  /** Spring toward a new position, carrying the last contact's velocity. */
+  settleTo(position: Partial<GesturePosition>): void
+  jumpTo(position: Partial<GesturePosition>): void
+  updateBounds(bounds: GestureBounds): void
+  cancel(): void
+  pause(): void
+  play(): void
+  dispose(): void
+}
+const owners = new WeakMap<GestureSurface, Gestures>()
+const LIMIT = 1e9
+function bounds(input: GestureBounds = {}) {
+  if (!input || typeof input !== 'object')
+    throw new TypeError('Gesture bounds must be an object.')
+  const result = {
+    minX: input.left ?? -LIMIT,
+    maxX: input.right ?? LIMIT,
+    minY: input.top ?? -LIMIT,
+    maxY: input.bottom ?? LIMIT,
+  }
+  if (
+    Object.values(result).some((value) => !Number.isFinite(value)) ||
+    result.minX > result.maxX ||
+    result.minY > result.maxY
+  )
+    throw new RangeError('Gesture bounds must be finite and ordered.')
+  return result
+}
+function settings(options: GesturesOptions): GestureSettings {
+  for (const key of ['pan', 'pinch'] as const)
+    if (
+      options[key] !== undefined &&
+      typeof options[key] !== 'boolean' &&
+      (!options[key] || typeof options[key] !== 'object')
+    )
+      throw new TypeError(`Gesture ${key} must be boolean or an options object.`)
+  if (options.rotate !== undefined && typeof options.rotate !== 'boolean')
+    throw new TypeError('Gesture rotate must be boolean.')
+  for (const key of ['onStart', 'onEnd', 'onCancel', 'onTap', 'onDoubleTap'] as const)
+    if (options[key] !== undefined && typeof options[key] !== 'function')
+      throw new TypeError(`Gesture ${key} must be a function.`)
+  const pan = typeof options.pan === 'object' ? options.pan : {}
+  const pinch = typeof options.pinch === 'object' ? options.pinch : {}
+  const axis = pan.axis ?? 'both'
+  if (!['x', 'y', 'both'].includes(axis))
+    throw new TypeError('Gesture pan axis must be x, y or both.')
+  const result = {
+    ...bounds(pan.bounds),
+    axis: options.pan ? (axis === 'x' ? 1 : axis === 'y' ? 2 : 3) : 0,
+    threshold: pan.threshold ?? 8,
+    failOffset: pan.failOffset ?? 12,
+    pinch: !!options.pinch,
+    rotate: !!options.rotate,
+    tap: !!options.onTap,
+    doubleTap: !!options.onDoubleTap,
+    minScale: pinch.min ?? 0.25,
+    maxScale: pinch.max ?? 4,
+  }
+  if (
+    ![result.threshold, result.failOffset, result.minScale, result.maxScale].every(
+      (value) => Number.isFinite(value) && value > 0,
+    ) ||
+    result.minScale > result.maxScale
+  )
+    throw new RangeError(
+      'Gesture thresholds and scale limits must be positive and ordered.',
+    )
+  if (
+    options.scrollView &&
+    (!(options.scrollView instanceof ScrollView) ||
+      options.scrollView.orientation !== 'vertical' ||
+      result.axis !== 2)
+  )
+    throw new TypeError('Scroll handoff needs a vertical ScrollView and a y-axis pan.')
+  if (
+    options.scrollView &&
+    (pan.bounds?.top === undefined || pan.bounds?.bottom === undefined)
+  )
+    throw new TypeError('Scroll handoff needs explicit top and bottom pan bounds.')
+  return result
+}
+
+/** Compose native pan/pinch/rotation and exclusive single/double taps on one surface. */
+export function gestures(
+  surface: GestureSurface,
+  options: GesturesOptions = {},
+): Gestures {
+  if (!(surface instanceof GestureSurface))
+    throw new TypeError('gestures() requires a GestureSurface.')
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Gesture options must be an object.')
+  let config = settings(options)
+  if (options.scrollView) {
+    let ancestor = options.scrollView.parent
+    while (ancestor && ancestor !== surface) ancestor = ancestor.parent
+    if (ancestor !== surface)
+      throw new TypeError('The ScrollView must be inside the GestureSurface.')
+  }
+  const initial = { x: 0, y: 0, scale: 1, rotate: 0, ...options.initial }
+  if (Object.values(initial).some((value) => !Number.isFinite(value)))
+    throw new RangeError('Initial gesture values must be finite.')
+  if (
+    initial.x < config.minX ||
+    initial.x > config.maxX ||
+    initial.y < config.minY ||
+    initial.y > config.maxY ||
+    initial.scale < config.minScale ||
+    initial.scale > config.maxScale
+  )
+    throw new RangeError('Initial gesture values must be within their bounds.')
+  const keys = ['x', 'y', 'scale', 'rotate'] as const
+  const values = keys.map((key) => springValue(motionValue(initial[key]), options.spring))
+  let driver: GestureDriver | undefined,
+    ended = false,
+    held = false,
+    suspended = false,
+    disposing = false
+  const position = (): GesturePosition => ({
+    x: values[0]!.get(),
+    y: values[1]!.get(),
+    scale: values[2]!.get(),
+    rotate: values[3]!.get(),
+  })
+  const callback = (state: number, velocityX: number, velocityY: number) => {
+    if (ended) return
+    const event = { ...position(), velocityX, velocityY }
+    const handler = [
+      undefined,
+      options.onStart,
+      options.onEnd,
+      options.onCancel,
+      options.onTap,
+      options.onDoubleTap,
+    ][state]
+    try {
+      handler?.(event)
+    } catch (error) {
+      Trace.write(
+        `Jolt gesture callback failed: ${String(error)}`,
+        Trace.categories.Error,
+        Trace.messageType.error,
+      )
+    }
+  }
+  const detach = () => {
+    const previous = driver
+    driver = undefined
+    previous?.dispose()
+  }
+  const refreshEnabled = () =>
+    driver?.enabled(
+      !held &&
+        !suspended &&
+        surface.isEnabled !== false &&
+        surface.isUserInteractionEnabled !== false,
+    )
+  const attach = () => {
+    if (
+      ended ||
+      driver ||
+      !surface.isLoaded ||
+      !surface.nativeViewProtected ||
+      (options.scrollView && !options.scrollView.nativeViewProtected)
+    )
+      return
+    try {
+      driver = createGestureDriver(surface, options.scrollView, values, config, callback)
+      refreshEnabled()
+    } catch (error) {
+      control.dispose()
+      throw error
+    }
+  }
+  const suspend = () => {
+    suspended = true
+    driver?.enabled(false)
+  }
+  const resume = () => {
+    suspended = false
+    refreshEnabled()
+  }
+  const move = (next: Partial<GesturePosition>, animated: boolean) => {
+    if (ended) return
+    if (
+      !next ||
+      typeof next !== 'object' ||
+      Object.entries(next).some(
+        ([key, value]) =>
+          !keys.includes(key as (typeof keys)[number]) || !Number.isFinite(value),
+      )
+    )
+      throw new TypeError(
+        'Gesture positions must contain finite x, y, scale or rotate values.',
+      )
+    if (!driver)
+      throw new Error('Load the GestureSurface before moving its gesture values.')
+    const target = { ...position(), ...next }
+    driver.settle(
+      keys.map((key) => target[key]),
+      animated,
+    )
+  }
+  const control: Gestures = {
+    x: values[0]!,
+    y: values[1]!,
+    scale: values[2]!,
+    rotate: values[3]!,
+    get position() {
+      return position()
+    },
+    get active() {
+      return driver?.active ?? false
+    },
+    get paused() {
+      return held
+    },
+    get disposed() {
+      return ended
+    },
+    settleTo: (next) => move(next, true),
+    jumpTo: (next) => move(next, false),
+    updateBounds(next) {
+      config = {
+        ...config,
+        ...bounds({
+          left: config.minX,
+          right: config.maxX,
+          top: config.minY,
+          bottom: config.maxY,
+          ...next,
+        }),
+      }
+      driver?.bounds(config)
+    },
+    cancel() {
+      driver?.cancel()
+    },
+    pause() {
+      held = true
+      driver?.enabled(false)
+    },
+    play() {
+      held = false
+      refreshEnabled()
+    },
+    dispose() {
+      if (ended || disposing) return
+      disposing = true
+      detach()
+      ended = true
+      surface.off('loaded', attach)
+      surface.off('unloaded', detach)
+      surface.off('isEnabledChange', refreshEnabled)
+      surface.off('isUserInteractionEnabledChange', refreshEnabled)
+      options.scrollView?.off('loaded', attach)
+      options.scrollView?.off('unloaded', detach)
+      Application.off(Application.suspendEvent, suspend)
+      Application.off(Application.resumeEvent, resume)
+      values.forEach((value) => value.dispose())
+      if (owners.get(surface) === control) owners.delete(surface)
+    },
+  }
+  owners.get(surface)?.dispose()
+  owners.set(surface, control)
+  surface.on('loaded', attach)
+  surface.on('unloaded', detach)
+  surface.on('isEnabledChange', refreshEnabled)
+  surface.on('isUserInteractionEnabledChange', refreshEnabled)
+  options.scrollView?.on('loaded', attach)
+  options.scrollView?.on('unloaded', detach)
+  Application.on(Application.suspendEvent, suspend)
+  Application.on(Application.resumeEvent, resume)
+  try {
+    attach()
+  } catch (error) {
+    control.dispose()
+    throw error
+  }
+  return control
+}

package/src/index.ts

@@ -2,7 +2,7 @@ export { timeline } from './sequence.js'
 export type { TimelineAnimation, TimelineStep, PlayableAnimation } from './sequence.js'
 export { playbackProgress } from './motion-value.js'
 export { animate, decay, set, stop } from './animate.js'
-export { bind, motionValue, scrollValue } from './motion-value.js'
+export { bind, motionValue, scrollValue, springValue } from './motion-value.js'
 export type {
   Bindings,
   DerivedColor,
@@ -10,6 +10,8 @@ export type {
   MapOptions,
   MotionValue,
   ScrollValue,
+  SpringValue,
+  SpringValueOptions,
   ValueAnimationOptions,
 } from './motion-value.js'
 export type { SubscribeOptions, ValueListener } from './value-observers.js'

package/src/ios-plugin.d.ts

@@ -1,3 +1,61 @@
+declare class JoltGestureSession extends NSObject {
+  static attachScrollXYScaleRotationOptionsOnState(
+    surface: UIView,
+    scroll: UIScrollView | null,
+    x: JoltLiveSpring,
+    y: JoltLiveSpring,
+    scale: JoltLiveSpring,
+    rotation: JoltLiveSpring,
+    options: string,
+    onState: (state: number, velocityX: number, velocityY: number) => void,
+  ): JoltGestureSession
+  readonly active: boolean
+  cancel(): void
+  refreshScrollDelegate(): void
+  setEnabled(value: boolean): void
+  settleXYScaleRotationAnimated(
+    x: number,
+    y: number,
+    scale: number,
+    rotation: number,
+    animated: boolean,
+  ): void
+  updateLeftRightTopBottom(left: number, right: number, top: number, bottom: number): void
+  dispose(): void
+}
+declare class JoltLiveSpring extends NSObject {
+  static createStiffnessDampingMassRestDeltaRestSpeedReduced(
+    initial: number,
+    stiffness: number,
+    damping: number,
+    mass: number,
+    restDelta: number,
+    restSpeed: number,
+    reduced: boolean,
+  ): JoltLiveSpring
+  static activeCount(): number
+  static nodeCount(): number
+  static sync(view: UIView): void
+  readonly position: number
+  readonly velocity: number
+  readonly moving: boolean
+  followMappings(source: JoltLiveSpring, mappings: string): void
+  updateInput(snapshot: string): void
+  setTarget(value: number): void
+  setReduced(value: boolean): void
+  setPaused(value: boolean): void
+  bindPropertyMappings(
+    view: UIView,
+    property: string,
+    mappings: string,
+  ): JoltLiveSpringBinding
+  dispose(): void
+}
+declare class JoltLiveSpringBinding extends NSObject {
+  readonly value: number
+  setLayers(inputs: string): void
+  cancel(): void
+}
 declare class JoltInteractiveAnimation extends NSObject {
   static startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
     view: UIView,

package/src/live-spring-driver.ts

@@ -0,0 +1,181 @@
+import { isAndroid, type View } from '@nativescript/core'
+import type { NumericProperty } from './properties.js'
+import { retainInteractiveLayout } from './driver/ios-layout.js'
+
+export interface LiveMapping {
+  input: readonly number[]
+  output: readonly number[]
+  clamp: boolean
+}
+export interface LiveSpringPhysics {
+  stiffness: number
+  damping: number
+  mass: number
+  restDelta: number
+  restSpeed: number
+}
+export interface LiveInput {
+  value: number
+  running: boolean
+  elapsed: number
+  duration: number
+  delay: number
+  repeat: number
+  reverse: boolean
+  to: number
+  times: readonly number[]
+  values: readonly number[]
+}
+export interface LiveBinding {
+  value(): number
+  layers(inputs: readonly LiveInput[]): void
+  cancel(): void
+}
+export interface LiveNode {
+  position(): number
+  velocity(): number
+  moving(): boolean
+  follow(source: LiveNode, maps: readonly LiveMapping[]): void
+  update(input: LiveInput): void
+  reduced(value: boolean): void
+  paused(value: boolean): void
+  bind(view: View, property: NumericProperty, maps: readonly LiveMapping[]): LiveBinding
+  dispose(): void
+}
+export interface LiveSpringDriver {
+  create(initial: number, physics: LiveSpringPhysics, reduced: boolean): LiveNode
+  sync(view: View): void
+}
+let override: LiveSpringDriver | undefined
+export function setLiveSpringDriver(driver: LiveSpringDriver | undefined) {
+  override = driver
+}
+export function liveSpringDriver(): LiveSpringDriver {
+  if (override) return override
+  if (!available())
+    throw new Error(
+      'springValue() needs the Jolt native classes. Rebuild the native app after upgrading Jolt.',
+    )
+  return nativeDriver
+}
+function available() {
+  return isAndroid
+    ? typeof org !== 'undefined' &&
+        typeof org.rafaelaugusto.jolt.LiveSpring === 'function'
+    : typeof JoltLiveSpring !== 'undefined'
+}
+export function syncLiveSprings(view: View) {
+  if (override) override.sync(view)
+  else if (available() && view.nativeViewProtected) nativeDriver.sync(view)
+}
+const handles = new WeakMap<
+  LiveNode,
+  org.rafaelaugusto.jolt.LiveSpring | JoltLiveSpring
+>()
+/** Internal native input connection; never exposes handles through the public value API. */
+export function nativeLiveNode(node: LiveNode) {
+  const handle = handles.get(node)
+  if (!handle) throw new Error('A gesture needs a native live value node.')
+  return handle
+}
+const nativeDriver: LiveSpringDriver = {
+  create(initial, physics, reduced) {
+    const { stiffness, damping, mass, restDelta, restSpeed } = physics
+    if (isAndroid) {
+      const native = new org.rafaelaugusto.jolt.LiveSpring(
+        initial,
+        stiffness,
+        damping,
+        mass,
+        restDelta,
+        restSpeed,
+        reduced,
+      )
+      const node: LiveNode = {
+        position: () => native.getPosition(),
+        velocity: () => native.getVelocity(),
+        moving: () => native.isMoving(),
+        follow: (source, maps) =>
+          native.follow(
+            handles.get(source) as org.rafaelaugusto.jolt.LiveSpring,
+            JSON.stringify(maps),
+          ),
+        update: (input) =>
+          input.running
+            ? native.updateInput(JSON.stringify(input))
+            : native.setTarget(input.value),
+        reduced: (value) => native.setReduced(value),
+        paused: (value) => native.setPaused(value),
+        bind(view, property, maps) {
+          const binding = native.bind(
+            view.nativeViewProtected,
+            property,
+            JSON.stringify(maps),
+          )
+          return {
+            value: () => binding.getValue(),
+            layers: (inputs) => binding.setLayers(JSON.stringify(inputs)),
+            cancel: () => binding.cancel(),
+          }
+        },
+        dispose: () => native.dispose(),
+      }
+      handles.set(node, native)
+      return node
+    }
+    const native = JoltLiveSpring.createStiffnessDampingMassRestDeltaRestSpeedReduced(
+      initial,
+      stiffness,
+      damping,
+      mass,
+      restDelta,
+      restSpeed,
+      reduced,
+    )
+    const node: LiveNode = {
+      position: () => native.position,
+      velocity: () => native.velocity,
+      moving: () => native.moving,
+      follow: (source, maps) =>
+        native.followMappings(
+          handles.get(source) as JoltLiveSpring,
+          JSON.stringify(maps),
+        ),
+      update: (input) =>
+        input.running
+          ? native.updateInput(JSON.stringify(input))
+          : native.setTarget(input.value),
+      reduced: (value) => native.setReduced(value),
+      paused: (value) => native.setPaused(value),
+      bind(view, property, maps) {
+        const releaseLayout = retainInteractiveLayout(view)
+        let binding: JoltLiveSpringBinding
+        try {
+          binding = native.bindPropertyMappings(
+            view.nativeViewProtected,
+            property,
+            JSON.stringify(maps),
+          )
+        } catch (error) {
+          releaseLayout()
+          throw error
+        }
+        return {
+          value: () => binding.value,
+          layers: (inputs) => binding.setLayers(JSON.stringify(inputs)),
+          cancel: () => {
+            binding.cancel()
+            releaseLayout()
+          },
+        }
+      },
+      dispose: () => native.dispose(),
+    }
+    handles.set(node, native)
+    return node
+  },
+  sync(view) {
+    if (isAndroid) org.rafaelaugusto.jolt.LiveSpring.sync(view.nativeViewProtected)
+    else JoltLiveSpring.sync(view.nativeViewProtected)
+  },
+}

package/src/mixer.ts

@@ -2,6 +2,7 @@ import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import type { Track } from './track.js'
+import type { LiveInput } from './live-spring-driver.js'
 
 /** The channel of regular animations; layers are named next to it. */
 export const BASE = ''
@@ -67,6 +68,7 @@ export function mixFor(view: View, property: Property): Mix {
 
 /** One property of one view: a base and named layers, played natively as one composite track. */
 export class Mix {
+  private live: { read(): number; layers(inputs: readonly LiveInput[]): void } | undefined
   private readonly rests = new Map<string, number>()
   private readonly channels = new Map<string, Channel>()
   private native: unknown
@@ -80,12 +82,27 @@ export class Mix {
   }
 
   rest(key: string): number {
+    if (key === BASE && this.live) return this.live.read()
     return (
       this.rests.get(key) ??
       (key === BASE ? readValue(this.view, this.property) : identity(this.property))
     )
   }
 
+  attachLive(base: {
+    read(): number
+    layers(inputs: readonly LiveInput[]): void
+  }): () => void {
+    this.live = base
+    this.compose()
+    return () => {
+      if (this.live !== base) return
+      this.rests.set(BASE, base.read())
+      this.live = undefined
+      this.compose()
+    }
+  }
+
   setRest(key: string, value: number) {
     this.rests.set(key, value)
     this.compose()
@@ -192,6 +209,31 @@ export class Mix {
     const previous = this.native
     this.native = undefined
 
+    if (this.live) {
+      if (previous !== undefined) driver.stop(this.view, previous)
+      const layers: LiveInput[] = []
+      for (const key of new Set([...this.rests.keys(), ...this.channels.keys()])) {
+        if (key === BASE) continue
+        const channel = this.channels.get(key)
+        const value = this.part(key, now, now)
+        const track = channel?.track
+        layers.push({
+          value,
+          running: !!channel && !channel.paused,
+          elapsed: this.elapsed(key, now),
+          duration: track?.duration ?? 0,
+          delay: track?.delay ?? 0,
+          repeat: track ? (Number.isFinite(track.repeat) ? track.repeat : -1) : 0,
+          reverse: track?.reverse ?? false,
+          to: track?.to ?? value,
+          times: track?.times ?? [],
+          values: track?.values ?? [],
+        })
+      }
+      this.live.layers(layers)
+      return
+    }
+
     let finite = 0
     const periods: number[] = []
     for (const [key, channel] of this.channels) {
@@ -245,7 +287,7 @@ export class Mix {
   }
 
   private dissolve() {
-    if (this.channels.size) return
+    if (this.live || this.channels.size) return
     for (const [key, value] of this.rests)
       if (key !== BASE && value !== identity(this.property)) return
     const properties = mixes.get(this.view)