@rafaelaugusto/jolt 0.1.0-beta.1 → 0.1.0-beta.3

package/src/animate.ts

@@ -1,4 +1,5 @@
 import { View } from '@nativescript/core'
+import { DEFAULT_FRICTION, solveDecay } from './decay.js'
 import {
   arrivalOf,
   setArrival,
@@ -8,7 +9,8 @@ import {
   type Plan,
 } from './engine.js'
 import { getPreset, type PresetName } from './presets.js'
-import { isProperty, type Property } from './properties.js'
+import { resolveHaptic, type Haptic } from './haptics.js'
+import { isProperty, precision, type Property } from './properties.js'
 import {
   hasCurve,
   mergeTransitions,
@@ -19,6 +21,8 @@ import {
 } from './transition.js'
 import type {
   AnimateOptions,
+  DecayOptions,
+  DecayVelocity,
   Keyframes,
   KeyframeValue,
   Stagger,
@@ -30,6 +34,7 @@ interface Options {
   overrides: Partial<Record<keyof Keyframes, Transition>>
   stagger: number | Stagger | undefined
   relative: boolean | undefined
+  haptic: Haptic | undefined
 }
 
 /**
@@ -47,12 +52,17 @@ export function animate(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): Animation {
-  const { keyframes, base, overrides, stagger, relative } = prepare(animation, options)
+  const { keyframes, base, overrides, stagger, relative, haptic } = prepare(
+    animation,
+    options,
+  )
+  const feedback = resolveHaptic(haptic)
 
   if (!isList(target)) {
     return new ViewAnimation(
       toView(target),
       plan(keyframes, base, overrides, 0, relative),
+      feedback,
     )
   }
 
@@ -69,11 +79,83 @@ export function animate(
             staggerDelay(stagger, index, views.length),
             relative,
           ),
+          feedback,
         ),
     ),
   )
 }
 
+/** Starts at the current translation and slows down from a velocity in DIPs per second. */
+export function decay(
+  target: Target | readonly Target[],
+  velocity: DecayVelocity,
+  options: DecayOptions = {},
+): Animation {
+  const friction = options.friction ?? DEFAULT_FRICTION
+  if (!Number.isFinite(friction) || friction <= 0 || friction >= 1) {
+    throw new RangeError('Decay friction must be between 0 and 1 exclusively.')
+  }
+
+  const stops = (values: readonly number[] | undefined) => {
+    if (values === undefined) return undefined
+    if (
+      !Array.isArray(values) ||
+      values.length === 0 ||
+      ![...values].every(Number.isFinite)
+    ) {
+      throw new RangeError('Decay snap needs a nonempty array of finite positions.')
+    }
+    return [...values]
+  }
+  const snap = options.snap
+  if (
+    snap !== undefined &&
+    !Array.isArray(snap) &&
+    (snap === null ||
+      typeof snap !== 'object' ||
+      Object.keys(snap).some((key) => key !== 'x' && key !== 'y'))
+  ) {
+    throw new TypeError('Decay snap must be an array or an object with x and y stops.')
+  }
+  const shared = Array.isArray(snap)
+  const perAxis = snap as { x?: readonly number[]; y?: readonly number[] } | undefined
+  const snapped = shared ? stops(snap) : undefined
+  const snapX = shared ? snapped : stops(perAxis?.x)
+  const snapY = shared ? snapped : stops(perAxis?.y)
+
+  const plans = Object.entries(velocity).flatMap<Plan>(([property, value]) => {
+    if (property !== 'x' && property !== 'y') {
+      throw new Error(`Can't decay "${property}". Use x or y.`)
+    }
+    if (value === undefined) return []
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`Invalid decay velocity for "${property}".`)
+    }
+    // Validate every axis before handing any plans to the engine.
+    solveDecay(0, value, friction, precision[property])
+    return [
+      {
+        property,
+        keyframes: [null, null],
+        transition: {
+          curve: {
+            type: 'decay',
+            friction,
+            velocity: value,
+            snap: property === 'x' ? snapX : snapY,
+          },
+          delay: 0,
+          repeat: 0,
+          reverse: false,
+        },
+      },
+    ]
+  })
+  const views = toViews(target)
+  if (plans.length === 0) return group([])
+  return group(views.map((view) => new ViewAnimation(view, plans)))
+}
+
 /** Stops all or selected properties at their current values. `scale` stops both axes. */
 export function stop(
   target: Target | readonly Target[],
@@ -133,33 +215,43 @@ function prepare(
       : { ...own.overrides, ...user.overrides },
     stagger: user.stagger ?? own.stagger,
     relative: user.relative ?? own.relative,
+    haptic: user.haptic ?? own.haptic,
   }
 }
 
 function normalize(options: AnimateOptions | SpringName | undefined): Options {
   if (options === undefined)
-    return { base: {}, overrides: {}, stagger: undefined, relative: undefined }
+    return {
+      base: {},
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
   if (typeof options === 'string')
     return {
       base: spring(options),
       overrides: {},
       stagger: undefined,
       relative: undefined,
+      haptic: undefined,
     }
 
   const base: Record<string, unknown> = {}
   const overrides: Options['overrides'] = {}
   let stagger: Options['stagger']
   let relative: Options['relative']
+  let haptic: Options['haptic']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
     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 === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger, relative }
+  return { base, overrides, stagger, relative, haptic }
 }
 
 function plan(

package/src/decay.ts

@@ -0,0 +1,45 @@
+export interface DecayMotion {
+  duration: number
+  to: number
+  position(time: number): number
+  velocity(time: number): number
+}
+
+/** Velocity retains this fraction every millisecond, independently of the display's refresh rate. */
+export const DEFAULT_FRICTION = 0.998
+
+/** Exponential motion, with velocity in units per second and time in milliseconds. */
+export function solveDecay(
+  from: number,
+  velocity: number,
+  friction: number,
+  precision: number,
+): DecayMotion {
+  const rate = -Math.log(friction)
+  const distance = velocity / (1000 * rate)
+  const to = from + distance
+  // Stop only when both the remaining distance and speed are imperceptible.
+  const duration =
+    velocity === 0
+      ? 0
+      : Math.ceil(
+          Math.max(
+            0,
+            Math.log(Math.abs(distance) / precision) / rate,
+            Math.log(Math.abs(velocity) / (precision * 10)) / rate,
+          ),
+        )
+
+  if (!Number.isFinite(to) || !Number.isFinite(duration) || duration > 2_147_483_647) {
+    throw new RangeError('Decay velocity and friction produce an unplayable motion.')
+  }
+
+  return {
+    duration,
+    to,
+    position: (time) =>
+      time >= duration ? to : from - distance * Math.expm1(-rate * Math.max(0, time)),
+    velocity: (time) =>
+      time >= duration ? 0 : velocity * Math.exp(-rate * Math.max(0, time)),
+  }
+}

package/src/driver/android.ts

@@ -1,9 +1,48 @@
 import { Utils, type View } from '@nativescript/core'
 import type { Property } from '../properties.js'
-import { after, type Driver } from './index.js'
+import type { Driver } from './index.js'
 
 type NativeView = android.view.View
 
+interface Handle {
+  cancel(): void
+  elapsed(): number
+}
+
+/** Own only layers we create; keep app-configured hardware/software layers and paints intact. */
+function fadeLayer(view: View, nativeView: NativeView): (() => void) | undefined {
+  const { View, ViewGroup } = android.view
+  if (
+    !view.isLoaded ||
+    view.nativeViewProtected !== nativeView ||
+    !(nativeView instanceof ViewGroup) ||
+    nativeView.getChildCount() === 0 ||
+    !nativeView.isHardwareAccelerated() ||
+    nativeView.getLayerType() !== View.LAYER_TYPE_NONE
+  )
+    return undefined
+
+  // Do not cache an entire oversized scrolling/content tree into a GPU texture.
+  const { widthPixels, heightPixels } = nativeView.getResources().getDisplayMetrics()
+  const width = nativeView.getWidth()
+  const height = nativeView.getHeight()
+  if (width <= 0 || height <= 0 || width > widthPixels || height > heightPixels)
+    return undefined
+
+  nativeView.setLayerType(View.LAYER_TYPE_HARDWARE, null)
+  let active = true
+  const restore = () => {
+    if (!active) return
+    active = false
+    view.off('unloaded', restore)
+    if (nativeView.getLayerType() === View.LAYER_TYPE_HARDWARE) {
+      nativeView.setLayerType(View.LAYER_TYPE_NONE, null)
+    }
+  }
+  view.on('unloaded', restore)
+  return restore
+}
+
 const accessors: Record<
   Property,
   { get(view: NativeView): number; set(view: NativeView, value: number): void }
@@ -42,6 +81,12 @@ export function createAndroidDriver(): Driver {
       const nativeView = view.nativeViewProtected as NativeView
       const scale = unit(track.property)
 
+      if (track.property === 'rotateX' || track.property === 'rotateY') {
+        nativeView.setCameraDistance(
+          (view.perspective || 300) * Utils.layout.getDisplayDensity(),
+        )
+      }
+
       const keyframes = Array.create(android.animation.Keyframe, track.values.length)
       track.values.forEach((value, i) => {
         keyframes[i] = android.animation.Keyframe.ofFloat(track.times[i]!, value * scale)
@@ -56,6 +101,14 @@ export function createAndroidDriver(): Driver {
         nativeView,
         holders,
       )
+      let cancelled = false
+      let ended = false
+      let started = false
+      let restoreLayer: (() => void) | undefined
+      const releaseLayer = () => {
+        restoreLayer?.()
+        restoreLayer = undefined
+      }
       animator.setDuration(Math.max(track.duration, 1))
       animator.setStartDelay(track.delay)
       animator.setInterpolator(interpolator)
@@ -73,10 +126,25 @@ export function createAndroidDriver(): Driver {
       }
       animator.addListener(
         new android.animation.Animator.AnimatorListener({
-          onAnimationStart() {},
+          onAnimationStart() {
+            started = true
+            if (
+              !cancelled &&
+              !ended &&
+              track.property === 'opacity' &&
+              track.values.some((value) => value !== track.values[0])
+            )
+              restoreLayer = fadeLayer(view, nativeView)
+          },
           onAnimationRepeat() {},
-          onAnimationCancel() {},
+          onAnimationCancel() {
+            cancelled = true
+            releaseLayer()
+          },
           onAnimationEnd() {
+            if (ended) return
+            ended = true
+            releaseLayer()
             onEnd()
           },
         }),
@@ -84,18 +152,56 @@ export function createAndroidDriver(): Driver {
 
       accessors[track.property].set(nativeView, track.values[0]! * scale)
       animator.start()
-      return animator
+      return {
+        elapsed: () => (started ? track.delay + animator.getCurrentPlayTime() : 0),
+        cancel() {
+          // Cancel before native callbacks: Android can send onStart while cancelling a delay.
+          cancelled = true
+          releaseLayer()
+          animator.cancel()
+        },
+      } satisfies Handle
     },
 
     stop(_view, handle) {
-      ;(handle as android.animation.ObjectAnimator).cancel()
+      ;(handle as Handle).cancel()
     },
 
+    elapsed: (handle) => (handle as Handle).elapsed(),
+
     presented(view, property) {
       const nativeView = view.nativeViewProtected as NativeView | undefined
       return nativeView ? accessors[property].get(nativeView) / unit(property) : undefined
     },
 
-    after,
+    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.
+      const values = Array.create('float', 2)
+      values[0] = 0
+      values[1] = 1
+      const marker = android.animation.ValueAnimator.ofFloat(values)
+      marker.setDuration(ms)
+      let active = true
+      marker.addListener(
+        new android.animation.Animator.AnimatorListener({
+          onAnimationStart() {},
+          onAnimationRepeat() {},
+          onAnimationCancel() {
+            active = false
+          },
+          onAnimationEnd() {
+            if (!active) return
+            active = false
+            callback()
+          },
+        }),
+      )
+      marker.start()
+      return () => {
+        active = false
+        marker.cancel()
+      }
+    },
   }
 }

package/src/driver/index.ts

@@ -10,9 +10,11 @@ export interface Driver {
   /** Starts the track at `startedAt + track.delay` and calls `onEnd` once, however it ends. */
   play(view: View, track: Track, startedAt: number, onEnd: () => void): unknown
   stop(view: View, handle: unknown): void
+  /** Track time, including its delay, when the native clock differs from `now()`. */
+  elapsed?(handle: unknown): number
   /** The value on screen, when the platform knows it better than the track does. */
   presented(view: View, property: Property): number | undefined
-  /** Calls back after `ms` on the same clock, and returns a function that cancels it. */
+  /** Calls back after `ms` of animation time, respecting platform speed settings. */
   after(ms: number, callback: () => void): () => void
 }
 

package/src/driver/ios.ts

@@ -58,6 +58,17 @@ export function createIOSDriver(): Driver {
       }
 
       const animation = CAKeyframeAnimation.animationWithKeyPath(keyPaths[track.property])
+      // iOS 15+. The app must opt in through CADisableMinimumFrameDurationOnPhone.
+      if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
+        const nativeView = view.nativeViewProtected as UIView
+        const screen = nativeView.window?.screen ?? UIScreen.mainScreen
+        const maximum = Math.min(120, screen.maximumFramesPerSecond)
+        animation.preferredFrameRateRange = CAFrameRateRangeMake(
+          Math.min(80, maximum),
+          maximum,
+          maximum,
+        )
+      }
       animation.values = NSArray.arrayWithArray(
         track.values.map((value) => (rotation ? radians(value) : value)),
       )

package/src/engine.ts

@@ -1,5 +1,6 @@
 import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
+import { playHaptics, type HapticOptions } from './haptics.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
@@ -7,11 +8,11 @@ import type { ResolvedTransition } from './transition.js'
 export interface Animation extends PromiseLike<boolean> {
   /**
    * Resolves with `true` once the animation played to the end, or with `false`
-   * if it was stopped or another animation took over one of its properties.
+   * if it was stopped, superseded or skipped.
    * Never rejects.
    */
   readonly finished: Promise<boolean>
-  /** Stops where it is. The view keeps the values it had at that moment. */
+  /** Stops playback. Each effect documents whether it preserves or restores its visual state. */
   stop(): void
 }
 
@@ -56,10 +57,12 @@ export class ViewAnimation implements Animation {
   private cancelWait: (() => void) | undefined
   private arrive!: () => void
   private cancelArrival: (() => void) | undefined
+  private haptics: ReturnType<typeof playHaptics>
 
   constructor(
     readonly view: View,
     plans: readonly Plan[],
+    private readonly haptic?: HapticOptions,
   ) {
     this.finished = new Promise((resolve) => (this.resolve = resolve))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
@@ -77,6 +80,7 @@ export class ViewAnimation implements Animation {
   stop() {
     if (this.settled) return
     this.cancelWait?.()
+    this.haptics?.cancel()
     const now = getDriver().now()
     for (const entry of this.entries) {
       if (!entry.done) release(entry, now, true)
@@ -86,7 +90,10 @@ export class ViewAnimation implements Animation {
   }
 
   ended(finished: boolean) {
-    if (!finished) this.complete = false
+    if (!finished) {
+      this.complete = false
+      this.haptics?.cancel()
+    }
     if (--this.pending === 0) this.settle()
   }
 
@@ -100,7 +107,7 @@ export class ViewAnimation implements Animation {
       let current: number
       let velocity = 0
       if (previous) {
-        const elapsed = now - previous.startedAt
+        const elapsed = elapsedOf(previous, now)
         current = driver.presented(this.view, property) ?? previous.track.valueAt(elapsed)
         velocity = previous.track.velocityAt(elapsed)
         release(previous, now, false)
@@ -137,6 +144,8 @@ export class ViewAnimation implements Animation {
       this.pending++
     }
 
+    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now)
+
     for (const entry of this.entries) {
       entry.handle = driver.play(this.view, entry.track, now, () => {
         if (entry.done) return
@@ -148,7 +157,7 @@ export class ViewAnimation implements Animation {
 
     const arrival = Math.max(...this.entries.map((entry) => entry.track.arrival))
     if (this.pending === 0) this.settle()
-    else if (Number.isFinite(arrival)) {
+    else if (Number.isFinite(arrival) && tracks.some((track) => track.end > arrival)) {
       this.cancelArrival = driver.after(arrival, this.arrive)
     }
   }
@@ -174,6 +183,9 @@ export class ViewAnimation implements Animation {
     if (this.settled) return
     this.settled = true
     this.cancelArrival?.()
+    if (this.complete) this.haptics?.finish()
+    else this.haptics?.cancel()
+    this.haptics = undefined
     this.arrive()
     this.resolve(this.complete)
   }
@@ -208,9 +220,13 @@ function release(entry: Entry, now: number, commit: boolean) {
   forget(entry)
   if (commit) {
     const value =
-      driver.presented(view, property) ?? entry.track.valueAt(now - entry.startedAt)
+      driver.presented(view, property) ?? entry.track.valueAt(elapsedOf(entry, now))
     writeValue(view, property, value)
   }
   driver.stop(view, entry.handle)
   entry.owner.ended(false)
 }
+
+function elapsedOf(entry: Entry, now: number) {
+  return getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt
+}

package/src/haptics.ts

@@ -0,0 +1,125 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { Driver } from './driver/index.js'
+import type { Track } from './track.js'
+
+export type HapticStyle = 'light' | 'medium' | 'heavy'
+
+export interface HapticOptions {
+  style: HapticStyle
+  /** Points from 0 to 1 over the finite animation, excluding its initial delay. Defaults to arrival. */
+  times?: readonly number[]
+}
+
+export type Haptic = HapticStyle | HapticOptions | false
+
+/** Validate before any running animation is interrupted. */
+export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undefined {
+  if (haptic === undefined || haptic === false) return undefined
+  const options = typeof haptic === 'string' ? { style: haptic } : haptic
+  if (!options || !['light', 'medium', 'heavy'].includes(options.style))
+    throw new TypeError('Haptic style must be light, medium or heavy.')
+  const times = options.times
+  if (
+    times !== undefined &&
+    (!Array.isArray(times) ||
+      times.length === 0 ||
+      Array.from(times).some(
+        (time, i) =>
+          !Number.isFinite(time) ||
+          time <= 0 ||
+          time > 1 ||
+          (i > 0 && time <= times[i - 1]!),
+      ))
+  )
+    throw new RangeError(
+      'Haptic times must be increasing points greater than 0 and at most 1.',
+    )
+  return { style: options.style, times: times && [...times] }
+}
+
+const PREPARE_AHEAD = 100
+const MAX_LATENESS = 100
+const COMPLETION_TOLERANCE = 20
+
+/** Discrete feedback only: animation playback remains entirely native. */
+export function playHaptics(
+  view: View,
+  tracks: readonly Track[],
+  options: HapticOptions | undefined,
+  driver: Driver,
+  startedAt: number,
+) {
+  if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
+  const moving = tracks.filter(
+    (track) =>
+      track.duration > 0 && track.values.some((value) => value !== track.values[0]),
+  )
+  if (!moving.length) return
+  const end = Math.max(...tracks.map((track) => track.end))
+  if (!Number.isFinite(end)) return
+  const delay = Math.min(...moving.map((track) => track.delay))
+  const offsets = options.times
+    ? options.times.map((time) => delay + (end - delay) * time)
+    : [Math.max(...tracks.map((track) => track.arrival))]
+  const styles = {
+    light: 0,
+    medium: 1,
+    heavy: 2,
+  } satisfies Record<HapticStyle, UIImpactFeedbackStyle>
+  let generator: UIImpactFeedbackGenerator | undefined =
+    UIImpactFeedbackGenerator.alloc().initWithStyle(styles[options.style])
+  const native = view.nativeViewProtected as UIView
+  let next = 0
+  let cancelPrepare: (() => void) | undefined
+  let cancelImpact: (() => void) | undefined
+
+  const active = () =>
+    view.isLoaded &&
+    view.nativeViewProtected === native &&
+    !!native.window &&
+    UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
+
+  const cancel = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+    generator = undefined
+    view.off('unloaded', cancel)
+  }
+
+  const fire = (tolerance = 0) => {
+    const elapsed = driver.now() - startedAt
+    // A busy UI thread can delay timers. Drop stale impacts instead of replaying
+    // several old taps at once when it becomes responsive again.
+    while (next < offsets.length && offsets[next]! <= elapsed + tolerance) {
+      const offset = offsets[next++]!
+      if (active() && elapsed - offset <= MAX_LATENESS) generator?.impactOccurred()
+    }
+  }
+
+  const schedule = () => {
+    if (!generator || next === offsets.length) return cancel()
+    const remaining = startedAt + offsets[next]! - driver.now()
+    if (active()) generator.prepare()
+    if (remaining > PREPARE_AHEAD) {
+      cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
+        if (active()) generator?.prepare()
+      })
+    }
+    cancelImpact = driver.after(Math.max(0, remaining), () => {
+      fire()
+      schedule()
+    })
+  }
+
+  view.on('unloaded', cancel)
+  schedule()
+  return {
+    cancel,
+    finish() {
+      // Native completion may beat the timer at the final keyframe by a frame.
+      fire(COMPLETION_TOLERANCE)
+      cancel()
+    },
+  }
+}

package/src/index.ts

@@ -1,7 +1,24 @@
-export { animate, stop } from './animate.js'
+export { animate, decay, stop } from './animate.js'
 export { sequence } from './sequence.js'
 export type { Step } from './sequence.js'
 export { press } from './press.js'
+export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
+export { confetti, particles } from './particles.js'
+export type { ConfettiOptions, ParticleOptions } from './particles.js'
+export { shimmer } from './shimmer.js'
+export type { ShimmerOptions } from './shimmer.js'
+export { loader } from './loader.js'
+export type { LoaderOptions, LoaderStyle } from './loader.js'
+export { reveal, conceal } from './reveal.js'
+export type { RevealOptions, ConcealOptions } from './reveal.js'
+export { animateText } from './text.js'
+export type { TextOptions } from './text.js'
+export { symbolEffect } from './symbol-effect.js'
+export type {
+  SymbolEffect,
+  SymbolEffectName,
+  SymbolEffectOptions,
+} from './symbol-effect.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
 export { springs } from './transition.js'