@rafaelaugusto/jolt 0.1.0-beta.11 → 0.1.0-beta.13

package/src/android-plugin.d.ts

@@ -136,6 +136,33 @@ declare namespace org.rafaelaugusto.jolt {
       })
     }
   }
+  class KeyboardFrame {
+    constructor(root: android.view.View, listener: KeyboardFrame.Listener)
+    attach(): void
+    detach(): void
+    height(): number
+  }
+  namespace KeyboardFrame {
+    class Listener {
+      constructor(implementation: { onChange(height: number): void })
+    }
+  }
+  class KeyboardFrameFollower {
+    constructor(
+      view: android.view.View,
+      offset: number,
+      listener: KeyboardFrameFollower.Listener,
+    )
+    attach(): void
+    detach(): void
+  }
+  namespace KeyboardFrameFollower {
+    class Listener {
+      constructor(implementation: {
+        onMove(from: number, to: number, keyboard: number): void
+      })
+    }
+  }
   class TextReveal {
     constructor(
       view: android.widget.TextView,
@@ -182,3 +209,40 @@ declare namespace org.rafaelaugusto.jolt {
     }
   }
 }
+
+declare namespace org.rafaelaugusto.jolt {
+  class PropertySink extends java.lang.Object {
+    static scalar(target: any, getter: string, setter: string): PropertySink
+    getDimensions(): number
+    isAlive(): boolean
+    isCompiled(): boolean
+    read(): native.Array<number>
+    write(values: native.Array<number>): void
+    dispose(): void
+  }
+  class MapLibrePropertySink extends PropertySink {
+    constructor(target: any, camera: boolean)
+  }
+  class PropertyPlayer extends java.lang.Object {
+    constructor(
+      sink: PropertySink,
+      times: native.Array<number>,
+      values: native.Array<number>,
+      finalValue: native.Array<number>,
+      duration: number,
+      delay: number,
+      repeat: number,
+      reverse: boolean,
+      listener: PropertyPlayer.Listener,
+    )
+    static activeCount(): number
+    getFrames(): number
+    control(time: number, paused: boolean): void
+    cancel(): void
+  }
+  namespace PropertyPlayer {
+    class Listener extends java.lang.Object {
+      constructor(implementation: { onEnd(completed: boolean): void })
+    }
+  }
+}

package/src/animate.ts

@@ -17,16 +17,26 @@ import { DEFAULT_FRICTION, solveDecay } from './decay.js'
 import {
   arrivalOf,
   setArrival,
+  stopLayer,
   stopView,
   ViewAnimation,
   type Animation,
   type Plan,
 } from './engine.js'
 import { getPreset, type PresetName } from './presets.js'
+import {
+  asRoot,
+  detachBindings,
+  isMotionValue,
+  type MotionValue,
+  type ValueAnimationOptions,
+} from './motion-value.js'
 import { resolveHaptic, type Haptic } from './haptics.js'
+import { layerable } from './mixer.js'
 import { isProperty, precision, type Property } from './properties.js'
 import {
   hasCurve,
+  fitTransition,
   mergeTransitions,
   resolveTransition,
   springs,
@@ -51,24 +61,45 @@ interface Options {
   stagger: number | Stagger | undefined
   relative: boolean | undefined
   haptic: Haptic | undefined
+  layer?: string
 }
 
 /**
  * Animates one view, or several. Takes keyframes or the name of a preset,
- * and a transition or the name of a spring.
+ * and a transition or the name of a spring. A motion value animates to a number.
  *
  * ```ts
  * animate(card, 'fadeInUp')
  * animate(card, { scale: 1.1, rotate: [0, 90] }, 'bouncy')
  * animate(rows, 'fadeInUp', { stagger: 40 })
+ * animate(progress, 1, 'snappy')
  * ```
  */
+export function animate(
+  value: MotionValue,
+  to: number | readonly (number | null)[],
+  transition?: ValueAnimationOptions | SpringName,
+): PlaybackAnimation
 export function animate(
   target: Target | readonly Target[],
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
-): PlaybackAnimation {
-  return prepareAnimation(target, animation, options)()
+): PlaybackAnimation
+export function animate(
+  target: Target | readonly Target[] | MotionValue,
+  animation: Keyframes | PresetName | number | readonly (number | null)[],
+  options?: AnimateOptions | SpringName,
+): PlaybackAnimation | Animation {
+  if (isMotionValue(target))
+    return asRoot(target).animate(
+      animation as number | readonly (number | null)[],
+      options as ValueAnimationOptions | SpringName | undefined,
+    )
+  return prepareAnimation(
+    target as Target | readonly Target[],
+    animation as Keyframes | PresetName,
+    options,
+  )()
 }
 
 /** Validate and snapshot a complete animation before changing any view ownership. */
@@ -77,7 +108,7 @@ export function prepareAnimation(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): () => PlaybackAnimation {
-  const { keyframes, base, overrides, stagger, relative, haptic, path } = prepare(
+  const { keyframes, base, overrides, stagger, relative, haptic, path, layer } = prepare(
     animation,
     options,
   )
@@ -88,8 +119,15 @@ export function prepareAnimation(
     for (const property of Object.keys(keyframes))
       if (isColorProperty(property)) validateColorTarget(view, property)
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
-    const plans = plan(keyframes, base, overrides, 0, relative, path)
-    return () => new ViewAnimation(view, plans, feedback)
+    const plans = plan(keyframes, base, overrides, 0, relative, path, layer)
+    return () => {
+      if (layer === undefined)
+        detachBindings(
+          view,
+          plans.map(({ property }) => property),
+        )
+      return new ViewAnimation(view, plans, feedback)
+    }
   }
 
   const views = target.map(toView)
@@ -97,6 +135,7 @@ export function prepareAnimation(
     for (const property of Object.keys(keyframes))
       if (isColorProperty(property)) validateColorTarget(view, property)
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
+  const seed = Math.random()
   const plans = views.map((_, index) =>
     plan(
       keyframes,
@@ -105,11 +144,20 @@ export function prepareAnimation(
       staggerDelay(stagger, index, views.length),
       relative,
       path,
+      layer,
+      seed,
     ),
   )
   return () =>
     playbackGroup(
-      views.map((view, index) => new ViewAnimation(view, plans[index]!, feedback, true)),
+      views.map((view, index) => {
+        if (layer === undefined)
+          detachBindings(
+            view,
+            plans[index]!.map(({ property }) => property),
+          )
+        return new ViewAnimation(view, plans[index]!, feedback, true)
+      }),
     )
 }
 
@@ -186,15 +234,33 @@ export function decay(
   )
 }
 
-/** Stops all or selected properties at their current values. `scale` stops both axes. */
+/**
+ * Stops all or selected properties at their current values. `scale` stops both axes.
+ * A motion value stops where it is, and so do the views bound to it.
+ */
+export function stop(value: MotionValue, options?: { layer?: string }): void
 export function stop(
   target: Target | readonly Target[],
   properties?: readonly KeyframeProperty[],
+  options?: { layer?: string },
+): void
+export function stop(
+  target: Target | readonly Target[] | MotionValue,
+  properties?: readonly KeyframeProperty[] | { layer?: string },
+  options?: { layer?: string },
 ) {
-  const expanded = properties?.flatMap<Property>((property) =>
+  if (isMotionValue(target))
+    return asRoot(target).stop((properties as { layer?: string } | undefined)?.layer)
+  if (properties && !Array.isArray(properties))
+    throw new TypeError('View properties must be an array.')
+  const expanded = (
+    properties as readonly KeyframeProperty[] | undefined
+  )?.flatMap<Property>((property) =>
     property === 'scale' ? ['scaleX', 'scaleY'] : [property],
   )
-  for (const view of toViews(target)) stopView(view, expanded)
+  for (const view of toViews(target as Target | readonly Target[]))
+    if (options?.layer !== undefined) stopLayer(view, options.layer, expanded)
+    else stopView(view, expanded)
 }
 
 /**
@@ -205,7 +271,13 @@ export function stop(
  * set(logo, { opacity: 1, scale: 1, y: 0 })
  * ```
  */
-export function set(target: Target | readonly Target[], values: Values): void {
+export function set(value: MotionValue, to: number): void
+export function set(target: Target | readonly Target[], values: Values): void
+export function set(
+  target: Target | readonly Target[] | MotionValue,
+  values: Values | number,
+) {
+  if (isMotionValue(target)) return asRoot(target).set(values as number)
   if (values === null || typeof values !== 'object' || Array.isArray(values))
     throw new TypeError('set() takes an object of values.')
   const keyframes: Record<string, unknown> = {}
@@ -218,7 +290,7 @@ export function set(target: Target | readonly Target[], values: Values): void {
       )
     keyframes[key] = [value, value]
   }
-  animate(target, keyframes as Keyframes, { duration: 0 })
+  animate(target as Target | readonly Target[], keyframes as Keyframes, { duration: 0 })
 }
 
 /** Plays several animations as one: finished once they all are, and stopped together. */
@@ -281,6 +353,7 @@ function resolveAnimation(
     stagger: user.stagger ?? own.stagger,
     relative: user.relative ?? own.relative,
     haptic: user.haptic ?? own.haptic,
+    layer: user.layer,
   }
 }
 
@@ -307,16 +380,21 @@ function normalize(options: AnimateOptions | SpringName | undefined): Options {
   let stagger: Options['stagger']
   let relative: Options['relative']
   let haptic: Options['haptic']
+  let layer: Options['layer']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
-    if (key === 'stagger') stagger = value as Options['stagger']
+    if (key === 'layer') {
+      if (typeof value !== 'string' || !value)
+        throw new TypeError('A layer is named by a nonempty string.')
+      layer = value
+    } else if (key === 'stagger') stagger = value as Options['stagger']
     else if (key === 'relative') relative = value as Options['relative']
     else if (key === 'haptic') haptic = value as Options['haptic']
     else if (key === 'path' || key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger, relative, haptic }
+  return { base, overrides, stagger, relative, haptic, layer }
 }
 
 function plan(
@@ -326,8 +404,16 @@ function plan(
   offset: number,
   relative = false,
   path?: PreparedPath,
+  layer?: string,
+  seed = Math.random(),
 ): Plan[] {
+  if (layer !== undefined && path)
+    throw new Error("A path owns x and y; it can't play on a layer.")
   return expand(keyframes, path).map(([property, frames]) => {
+    if (layer !== undefined && !layerable(property))
+      throw new Error(
+        `Layers apply to x, y, scale, rotation and opacity; "${property}" has a single owner.`,
+      )
     if (path?.properties.includes(property as 'x' | 'y' | 'rotate')) {
       if (
         !Number.isFinite(path.transition.delay + offset) ||
@@ -347,12 +433,13 @@ function plan(
     const override =
       overrides[property] ?? (property.startsWith('scale') ? overrides.scale : undefined)
     const transition = resolveTransition(
-      override ? mergeTransitions(base, override) : base,
+      fitTransition(override ? mergeTransitions(base, override) : base, frames.length),
       property,
       frames.length,
     )
     transition.delay += offset
-    return { property, keyframes: frames, transition, relative }
+    if (transition.seed !== undefined) transition.seed = seed
+    return { property, keyframes: frames, transition, relative, layer }
   })
 }
 
@@ -361,8 +448,10 @@ export function startingValues(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ) {
-  const { keyframes, relative, path } = prepare(animation, options)
+  const { keyframes, relative, path, layer } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
+  if (layer !== undefined)
+    return new Map(expand(keyframes, path).map(([property]) => [property, null]))
   return new Map(
     expand(keyframes, path).map(([property, [first]]) => [
       property,

package/src/drag.ts

@@ -5,7 +5,7 @@ import {
   type TouchGestureEventData,
   type View,
 } from '@nativescript/core'
-import { stop, toView } from './animate.js'
+import { toView } from './animate.js'
 import { DEFAULT_FRICTION } from './decay.js'
 import { DragInput } from './drag-input.js'
 import {
@@ -15,9 +15,18 @@ import {
   solveDragRelease,
   type DragCurve,
 } from './drag-physics.js'
-import { currentValue, ViewAnimation, type Plan } from './engine.js'
+import {
+  baseValue,
+  currentValue,
+  setBase,
+  stopBase,
+  ViewAnimation,
+  type Animation,
+  type Plan,
+} from './engine.js'
+import { asRoot, isMotionValue, type MotionValue } from './motion-value.js'
 import type { PlaybackAnimation } from './playback.js'
-import { readValue, writeValue } from './properties.js'
+import { createTrack } from './track.js'
 import type { Target } from './types.js'
 
 export interface DragPoint {
@@ -29,10 +38,10 @@ export interface DragEvent extends DragPoint {
   readonly velocityX: number
   readonly velocityY: number
 }
-export interface DragRelease extends DragEvent {
+export interface DragRelease<A extends Animation = PlaybackAnimation> extends DragEvent {
   readonly target: DragPoint
   /** False on interruption/cancellation. Check before applying completion effects. */
-  readonly animation: PlaybackAnimation
+  readonly animation: A
 }
 export interface DragOptions {
   /** Defaults to both. One finger only. */
@@ -51,6 +60,17 @@ export interface DragOptions {
   onCancel?: (event: DragEvent) => void
   onSettle?: (position: DragPoint) => void
 }
+/** Drags a motion value instead of the view. Bounds and snap points are in the value's units. */
+export interface DragValueOptions extends Omit<
+  DragOptions,
+  'axis' | 'snap' | 'onRelease'
+> {
+  /** Takes the position on every move and plays the release; bind views to it to follow. */
+  value: MotionValue
+  axis: 'x' | 'y'
+  snap?: readonly number[]
+  onRelease?: (event: DragRelease<Animation>) => void
+}
 export interface Drag {
   readonly dragging: boolean
   readonly settling: boolean
@@ -67,22 +87,28 @@ export interface Drag {
 }
 
 type Axis = 'x' | 'y'
+type Root = ReturnType<typeof asRoot>
 interface Settings {
   axes: Axis[]
   curves: Record<Axis, DragCurve>
-  callbacks: Pick<
-    DragOptions,
-    'onStart' | 'onMove' | 'onRelease' | 'onCancel' | 'onSettle'
-  >
+  value: Root | undefined
+  callbacks: Pick<DragOptions, 'onStart' | 'onMove' | 'onCancel' | 'onSettle'> & {
+    onRelease?: (event: DragRelease<Animation>) => void
+  }
 }
 const owners = new WeakMap<View, Drag>()
 
-function settings(options: DragOptions): Settings {
+function settings(options: DragOptions | DragValueOptions): 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 value = 'value' in options ? options.value : undefined
+  if (value !== undefined && !isMotionValue(value))
+    throw new TypeError('Drag value must be a motion value.')
+  if (value !== undefined && axis === 'both')
+    throw new TypeError('Dragging a motion value needs axis "x" or "y".')
   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.')
@@ -152,18 +178,23 @@ function settings(options: DragOptions): Settings {
   const callbacks = {
     onStart: options.onStart,
     onMove: options.onMove,
-    onRelease: options.onRelease,
+    onRelease: options.onRelease as Settings['callbacks']['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 }
+  return { axes, curves, value: value && asRoot(value), callbacks }
 }
 
-/** Main-thread pan updates; release physics play through Jolt's native animation drivers. */
-export function drag(target: Target, options: DragOptions = {}): Drag {
+/**
+ * Main-thread pan updates; release physics play through Jolt's native animation drivers.
+ * With `value`, the gesture drives a motion value and the views bound to it.
+ */
+export function drag(target: Target, options: DragValueOptions): Drag
+export function drag(target: Target, options?: DragOptions): Drag
+export function drag(target: Target, options: DragOptions | DragValueOptions = {}): Drag {
   const view = toView(target)
   const config = settings(options) // Invalid replacements leave the existing owner intact.
   const previous = owners.get(view)
@@ -187,7 +218,7 @@ class DragController implements Drag {
   private attached = false
   private blocked = false
   private generation = 0
-  private release: PlaybackAnimation | undefined
+  private release: Animation | undefined
   private input = new DragInput()
   private origin = { x: 0, y: 0 }
   private last: DragEvent = { x: 0, y: 0, velocityX: 0, velocityY: 0 }
@@ -215,6 +246,8 @@ class DragController implements Drag {
     return this.destroyed
   }
   get position(): DragPoint {
+    const value = this.config.value
+    if (value) return { x: 0, y: 0, [this.config.axes[0]!]: value.base() }
     return { x: currentValue(this.view, 'x'), y: currentValue(this.view, 'y') }
   }
   cancel = () => {
@@ -303,9 +336,15 @@ class DragController implements Drag {
       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 value = this.config.value
+      if (value) {
+        value.stopBase()
+        this.origin = this.position
+      } else {
+        // Claim just the enabled axes, preserving the native presentation on takeover.
+        stopBase(this.view, this.config.axes)
+        this.origin = { x: baseValue(this.view, 'x'), y: baseValue(this.view, 'y') }
+      }
       const size =
         (this.view.parent as View | undefined)?.getActualSize() ??
         this.view.getActualSize()
@@ -346,8 +385,11 @@ class DragController implements Drag {
           : 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])
+        if (this.config.value) this.config.value.setBase(position[axis])
+        else {
+          stopBase(this.view, [axis])
+          setBase(this.view, axis, position[axis])
+        }
       }
       this.last = { ...position, velocityX: vx, velocityY: vy }
       if (event.state !== 3)
@@ -383,7 +425,11 @@ class DragController implements Drag {
         transition: { curve, delay: 0, repeat: 0, reverse: false },
       }
     })
-    const animation = new ViewAnimation(this.view, plans)
+    const [axis] = this.config.axes
+    const value = this.config.value
+    const animation = value
+      ? value.play(createTrack(axis!, [event[axis!]], plans[0]!.transition, 0))
+      : new ViewAnimation(this.view, plans)
     this.release = animation
     void animation.finished.then((finished) => {
       if (generation !== this.generation || this.destroyed) return

package/src/driver/android.ts

@@ -12,6 +12,7 @@ import {
 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,
@@ -109,6 +110,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)

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

@@ -15,6 +15,8 @@ export interface LayoutFrame {
 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,

package/src/driver/ios.ts

@@ -13,6 +13,7 @@ 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
@@ -59,6 +60,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))

package/src/easing.ts

@@ -15,6 +15,7 @@ export type EasingName =
   | 'backOut'
   | 'backInOut'
   | 'anticipate'
+  | `${'quad' | 'cubic' | 'quart' | 'quint' | 'sine' | 'expo'}${'In' | 'Out' | 'InOut'}`
 
 export type Easing = EasingName | CubicBezier | EasingFunction
 
@@ -73,6 +74,13 @@ const mirror =
   (p) =>
     p <= 0.5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2
 
+const family = <N extends string>(name: N, easeIn: EasingFunction) =>
+  ({
+    [`${name}In`]: easeIn,
+    [`${name}Out`]: reverse(easeIn),
+    [`${name}InOut`]: mirror(easeIn),
+  }) as Record<`${N}${'In' | 'Out' | 'InOut'}`, EasingFunction>
+
 const easings: Record<EasingName, EasingFunction> = {
   linear,
   ease: cubicBezier(0.25, 0.1, 0.25, 1),
@@ -87,6 +95,12 @@ const easings: Record<EasingName, EasingFunction> = {
   backInOut: mirror(backIn),
   anticipate: (p) =>
     p <= 0.5 ? backIn(2 * p) / 2 : p >= 1 ? 1 : 1 - Math.pow(2, 10 - 20 * p) / 2,
+  ...family('quad', (p) => p ** 2),
+  ...family('cubic', (p) => p ** 3),
+  ...family('quart', (p) => p ** 4),
+  ...family('quint', (p) => p ** 5),
+  ...family('sine', (p) => (p >= 1 ? 1 : 1 - Math.cos((p * Math.PI) / 2))),
+  ...family('expo', (p) => (p <= 0 ? 0 : 2 ** (10 * p - 10))),
 }
 
 export function resolveEasing(easing: Easing): EasingFunction {