@rafaelaugusto/jolt 0.1.0-beta.5 → 0.1.0-beta.6

package/src/driver/android.ts

@@ -207,5 +207,19 @@ export function createAndroidDriver(): Driver {
         marker.cancel()
       }
     },
+
+    reducedMotion() {
+      // Remove animations sets the animator duration scale to zero.
+      if (android.os.Build.VERSION.SDK_INT >= 26)
+        return !android.animation.ValueAnimator.areAnimatorsEnabled()
+      const { Global } = android.provider.Settings
+      return (
+        Global.getFloat(
+          Utils.android.getApplicationContext().getContentResolver(),
+          Global.ANIMATOR_DURATION_SCALE,
+          1,
+        ) === 0
+      )
+    },
   }
 }

package/src/driver/index.ts

@@ -34,6 +34,8 @@ 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
+  /** The platform's accessibility setting: Reduce Motion on iOS, Remove animations on Android. */
+  reducedMotion?(): boolean
 }
 
 export function after(ms: number, callback: () => void) {

package/src/driver/ios-color.ts

@@ -203,7 +203,6 @@ export function playIOSColor(
     )
     animation.keyTimes = NSArray.arrayWithArray(track.times as number[])
     animation.duration = Math.max(track.duration, 1) / 1000
-    timing.configure(animation, layer)
     if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
       const maximum = Math.min(
         120,
@@ -220,6 +219,7 @@ export function playIOSColor(
       animation.autoreverses = track.reverse
       animation.repeatCount = track.reverse ? (track.repeat + 1) / 2 : track.repeat + 1
     }
+    timing.configure(animation, layer)
     CATransaction.begin()
     if (!timing.paused && track.repeat !== Infinity)
       CATransaction.setCompletionBlock(() => {

package/src/driver/ios-decoration.ts

@@ -234,13 +234,13 @@ export function playIOSDecoration(
         animation.values = NSArray.arrayWithArray(values)
         animation.keyTimes = NSArray.arrayWithArray(times)
         animation.duration = Math.max(1, track.duration) / 1000
-        timing.configure(animation, layer)
         if (track.repeat > 0) {
           animation.autoreverses = track.reverse
           animation.repeatCount = track.reverse
             ? (track.repeat + 1) / 2
             : track.repeat + 1
         }
+        timing.configure(animation, layer)
         if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
           const max = Math.min(
             120,

package/src/driver/ios-playback.ts

@@ -21,7 +21,7 @@ export function iosPlayback(track: Track, startedAt: number) {
       anchor = CACurrentMediaTime() * 1000
       paused = hold
     },
-    configure(animation: CAAnimation, layer: CALayer) {
+    configure(animation: CAKeyframeAnimation, layer: CALayer) {
       const now = CACurrentMediaTime()
       const position = elapsed()
       animation.speed = paused ? 0 : 1
@@ -32,6 +32,20 @@ export function iosPlayback(track: Track, startedAt: number) {
       )
       animation.fillMode = paused ? 'both' : kCAFillModeBackwards
       animation.removedOnCompletion = !paused && track.repeat !== Infinity
+      // With speed 0, CA folds an exact duration boundary back to the first
+      // frame. Hold the actual endpoint with a constant copy, also when a
+      // shorter property waits at its end while another one is being scrubbed.
+      if (paused && Number.isFinite(track.end) && position >= track.end) {
+        const values = animation.values!
+        const index = track.reverse && track.repeat % 2 === 1 ? 0 : values.count - 1
+        const value = values.objectAtIndex(index)
+        animation.values = NSArray.arrayWithArray([value, value])
+        animation.keyTimes = NSArray.arrayWithArray([0, 1])
+        animation.duration = 1
+        animation.repeatCount = 0
+        animation.autoreverses = false
+        animation.timeOffset = 0
+      }
     },
   }
 }

package/src/driver/ios.ts

@@ -153,5 +153,7 @@ export function createIOSDriver(): Driver {
           : undefined,
 
     after,
+
+    reducedMotion: () => UIAccessibilityIsReduceMotionEnabled(),
   }
 }

package/src/engine.ts

@@ -12,12 +12,13 @@ import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
 import { isColorProperty } from './color.js'
+import type { PreparedPath, PathProperty } from './path.js'
 
 export interface Animation extends PromiseLike<boolean> {
   /**
    * Resolves with `true` once the animation played to the end, or with `false`
    * if it was stopped, superseded or skipped.
-   * Never rejects.
+   * Playback cancellation never rejects; sequences can reject setup/callback errors.
    */
   readonly finished: Promise<boolean>
   /** Stops playback. Each effect documents whether it preserves or restores its visual state. */
@@ -30,6 +31,7 @@ export interface Plan {
   keyframes: readonly (number | null)[]
   transition: ResolvedTransition
   relative?: boolean
+  path?: PreparedPath
 }
 
 interface Entry {
@@ -49,6 +51,21 @@ const revisions = new WeakMap<View, Map<Property, symbol>>()
 const running = new WeakMap<View, Map<Property, Entry>>()
 const arrivals = new WeakMap<Animation, Promise<unknown>>()
 
+/** Internal forecast for starting a timeline step before another one arrives. */
+export interface ArrivalTiming {
+  read(): { remaining: number | undefined; paused: boolean; arrived: boolean }
+  subscribe(callback: () => void): () => void
+}
+const arrivalTimings = new WeakMap<Animation, ArrivalTiming>()
+
+export function arrivalTimingOf(animation: Animation) {
+  return arrivalTimings.get(animation)
+}
+
+export function setArrivalTiming(animation: Animation, timing: ArrivalTiming) {
+  arrivalTimings.set(animation, timing)
+}
+
 /**
  * Resolves once the animation looks done, which for a spring is well before
  * `finished`. Sequences move on to the next step then.
@@ -83,6 +100,10 @@ export class ViewAnimation implements PlaybackAnimation {
   private idleListener: (() => void) | undefined
   private readyListener: (() => void) | undefined
   private readonly endless: boolean
+  private readonly timingListeners = new Set<() => void>()
+  private timingChanged() {
+    for (const callback of [...this.timingListeners]) callback()
+  }
 
   get paused() {
     return this._paused
@@ -136,6 +157,7 @@ export class ViewAnimation implements PlaybackAnimation {
     this.cancelArrival?.()
     this.haptics?.pause()
     if (this.started) this.controlTracks(this.time(), 'pause')
+    this.timingChanged()
   }
   play() {
     if (this.settled || !this._paused) return
@@ -148,6 +170,7 @@ export class ViewAnimation implements PlaybackAnimation {
       this.haptics?.play()
       if (this.pending === 0) this.becameIdle()
     }
+    this.timingChanged()
   }
   seekTime(time: number) {
     if (this.settled) return
@@ -173,6 +196,7 @@ export class ViewAnimation implements PlaybackAnimation {
     this.scheduleArrival()
     this.haptics?.seek()
     if (this.pending === 0) this.becameIdle()
+    this.timingChanged()
   }
   elapsed(entry: Entry, now: number) {
     return this.controlled
@@ -203,10 +227,12 @@ export class ViewAnimation implements PlaybackAnimation {
     if (remaining <= 0) {
       this.arrived = true
       this.arrive()
+      this.timingChanged()
     } else
       this.cancelArrival = getDriver().after(remaining, () => {
         this.arrived = true
         this.arrive()
+        this.timingChanged()
       })
   }
   private becameIdle() {
@@ -248,6 +274,17 @@ export class ViewAnimation implements PlaybackAnimation {
     )
     this.finished = new Promise((resolve) => (this.resolve = resolve))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
+    setArrivalTiming(this, {
+      read: () => ({
+        remaining: this.started ? Math.max(0, this.arrival - this.time()) : undefined,
+        paused: this._paused,
+        arrived: this.arrived || this.settled,
+      }),
+      subscribe: (callback) => {
+        this.timingListeners.add(callback)
+        return () => this.timingListeners.delete(callback)
+      },
+    })
     if (view.isLoaded && view.nativeViewProtected) this.start(plans)
     else this.waitForLoad(plans)
   }
@@ -285,7 +322,7 @@ export class ViewAnimation implements PlaybackAnimation {
     const now = driver.now()
     const entries = entriesOf(this.view)
 
-    const tracks = plans.map(({ property, keyframes, transition, relative }) => {
+    const tracks = plans.map(({ property, keyframes, transition, relative, path }) => {
       const previous = entries.get(property)
       let current: number
       let velocity = 0
@@ -300,6 +337,12 @@ export class ViewAnimation implements PlaybackAnimation {
             ? driver.presented(this.view, property)
             : undefined) ?? readValue(this.view, property)
       }
+      if (path)
+        return path.track(
+          property as PathProperty,
+          relative ? current : 0,
+          transition.delay,
+        )
       return createTrack(
         property,
         keyframes.map((value) => {
@@ -357,6 +400,7 @@ export class ViewAnimation implements PlaybackAnimation {
     } else if (this._paused) this.controlTracks(0, 'pause')
     this.scheduleArrival()
     this.readyListener?.()
+    this.timingChanged()
     if (this.pending === 0) this.becameIdle()
   }
 
@@ -388,6 +432,7 @@ export class ViewAnimation implements PlaybackAnimation {
     this.haptics = undefined
     this.arrive()
     this.resolve(this.complete)
+    this.timingChanged()
   }
 }
 

package/src/index.ts

@@ -1,7 +1,13 @@
 export { animate, decay, stop } from './animate.js'
 export { sequence } from './sequence.js'
-export type { Step } from './sequence.js'
+export type { Step, SequenceOptions, SequencePosition } from './sequence.js'
 export { press } from './press.js'
+export { scrollLinked } from './scroll-linked.js'
+export type { ScrollLinkedOptions } from './scroll-linked.js'
+export { animateItems } from './items.js'
+export type { ItemsOptions } from './items.js'
+export { followKeyboard } from './keyboard.js'
+export type { KeyboardOptions } from './keyboard.js'
 export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
 export { confetti, particles } from './particles.js'
 export type { ConfettiOptions, ParticleOptions } from './particles.js'
@@ -15,12 +21,16 @@ 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 { rollTo } from './roll.js'
+export type { RollOptions } from './roll.js'
 export { symbolEffect } from './symbol-effect.js'
 export type {
   SymbolEffect,
   SymbolEffectName,
   SymbolEffectOptions,
 } from './symbol-effect.js'
+export { configure } from './config.js'
+export type { JoltConfig } from './config.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
 export { springs } from './transition.js'

package/src/items.ts

@@ -0,0 +1,140 @@
+import { ListView, View, type EventData, type ItemEventData } from '@nativescript/core'
+import { animate, endingValues, startingValues, toView } from './animate.js'
+import { getDriver } from './driver/index.js'
+import { stopView } from './engine.js'
+import type { PresetName } from './presets.js'
+import { writeValue } from './properties.js'
+import type { SpringName } from './transition.js'
+import type { AnimateOptions, Keyframes, Target } from './types.js'
+
+export type ItemsOptions = AnimateOptions & {
+  /** Animate each data item only the first time it shows up. Defaults to false. */
+  once?: boolean
+}
+
+interface Pending {
+  index: number
+  section: number | undefined
+  item: unknown
+  key: string
+}
+
+type Row = View & {
+  bindingContext?: unknown
+  _listViewItemIndex?: number
+  _listViewSectionIndex?: number
+}
+
+interface Source extends View {
+  items?: unknown
+  _getDataItem?(index: number): unknown
+  _getDataItemInSection?(section: number, index: number): unknown
+}
+
+/**
+ * Plays an animation on each row of a list as it comes on screen. Rows are
+ * recycled, so a row that is reused for another item starts over, or settles
+ * at the end values when that item was already shown and `once` is set.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * animateItems(listView, 'fadeInUp')
+ * animateItems(listView, 'fadeInUp', { once: true })
+ * ```
+ */
+export function animateItems(
+  list: Target,
+  animation: Keyframes | PresetName,
+  options?: ItemsOptions | SpringName,
+): () => void {
+  const source = toView(list) as Source
+  const { once = false, ...rest } = typeof options === 'object' ? options : {}
+  if (rest.stagger !== undefined)
+    throw new TypeError('animateItems animates one row at a time; stagger has no effect.')
+  const transition: AnimateOptions | SpringName | undefined =
+    typeof options === 'string' ? options : rest
+  const properties = [...startingValues(animation, transition).keys()]
+  const ends = endingValues(animation, transition)
+
+  const rows = new Set<Row>()
+  const seenItems = new WeakSet<object>()
+  const seenKeys = new Set<string>()
+  const pending: Pending[] = []
+  let queued = false
+  let disposed = false
+
+  const settle = (row: Row) => {
+    stopView(row, properties)
+    for (const [property, value] of ends)
+      if (value !== null) writeValue(row, property, value)
+    getDriver().sync?.(row)
+  }
+  const show = (row: Row, { item, key }: Pending) => {
+    rows.add(row)
+    const tracked = typeof item === 'object' && item !== null
+    const seen = tracked ? seenItems.has(item) : seenKeys.has(key)
+    if (tracked) seenItems.add(item)
+    else seenKeys.add(key)
+    if (once && seen) settle(row)
+    else {
+      stopView(row, properties)
+      animate(row, animation, transition)
+    }
+  }
+  const flush = () => {
+    queued = false
+    if (disposed) return
+    const current = new Set<Row>()
+    const fresh: Row[] = []
+    source.eachChildView((child: Row) => {
+      current.add(child)
+      if (!rows.has(child)) fresh.push(child)
+      return true
+    })
+    for (const row of rows) if (!current.has(row)) rows.delete(row)
+    for (const entry of pending.splice(0)) {
+      const row =
+        fresh.find(
+          (candidate) =>
+            candidate._listViewItemIndex === entry.index &&
+            candidate._listViewSectionIndex === entry.section,
+        ) ??
+        fresh.find(
+          (candidate) =>
+            entry.item !== undefined && candidate.bindingContext === entry.item,
+        )
+      if (!row) continue
+      fresh.splice(fresh.indexOf(row), 1)
+      show(row, entry)
+    }
+  }
+  const onItemLoading = (event: EventData) => {
+    const { index, section, view } = event as ItemEventData
+    const item =
+      section === undefined
+        ? source._getDataItem?.(index)
+        : source._getDataItemInSection?.(section, index)
+    const entry: Pending = { index, section, item, key: `${section ?? ''}:${index}` }
+    if (view instanceof View) {
+      show(view, entry)
+      return
+    }
+    pending.push(entry)
+    if (queued) return
+    queued = true
+    void Promise.resolve().then(flush)
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    source.off(ListView.itemLoadingEvent, onItemLoading)
+    source.off('unloaded', cleanup)
+    pending.length = 0
+    for (const row of rows) settle(row)
+    rows.clear()
+  }
+
+  source.on(ListView.itemLoadingEvent, onItemLoading)
+  source.on('unloaded', cleanup)
+  return cleanup
+}

package/src/keyboard.ts

@@ -0,0 +1,132 @@
+import { Application, Utils, isAndroid, isIOS, type View } from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import type { Target } from './types.js'
+
+export interface KeyboardOptions {
+  /** DIPs kept between the view's bottom edge and the keyboard. Defaults to zero. */
+  offset?: number
+}
+
+const BEGIN_FROM_CURRENT_STATE = 4
+
+/**
+ * Lifts the view by its overlap with the software keyboard, at the keyboard's
+ * own speed and curve, and lets it back down when the keyboard hides.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * const release = followKeyboard(composer)
+ * followKeyboard(sendButton, { offset: 12 })
+ * ```
+ */
+export function followKeyboard(
+  target: Target,
+  options: KeyboardOptions = {},
+): () => void {
+  const view = toView(target)
+  const offset = options.offset ?? 0
+  if (!Number.isFinite(offset)) throw new RangeError('Keyboard offset must be finite.')
+  if (isIOS) return followIOS(view, offset)
+  if (isAndroid) return followAndroid(view, offset)
+  return () => {}
+}
+
+function followIOS(view: View, offset: number) {
+  let disposed = false
+  let current = 0
+  const onKeyboard = (notification: NSNotification) => {
+    if (disposed || !view.isLoaded) return
+    const native = view.nativeViewProtected as UIView | undefined
+    const window = native?.window
+    const info = notification.userInfo
+    if (!native || !window || !info) return
+    const end = info.objectForKey(UIKeyboardFrameEndUserInfoKey)?.CGRectValue as
+      CGRect | undefined
+    if (!end) return
+    const keyboard = window.convertRectFromWindow(end, null)
+    const hidden =
+      keyboard.size.height <= 0 || keyboard.origin.y >= window.bounds.size.height
+    const frame = native.convertRectToView(native.bounds, null)
+    const bottom = frame.origin.y + frame.size.height - view.translateY
+    const overlap = hidden ? 0 : Math.max(0, bottom + offset - keyboard.origin.y)
+    if (overlap === current) return
+    current = overlap
+    stop(view, ['y'])
+    const apply = () => {
+      view.translateY = overlap ? -overlap : 0
+    }
+    const duration = info.objectForKey(UIKeyboardAnimationDurationUserInfoKey)
+      ?.doubleValue as number | undefined
+    if (!duration) return apply()
+    const curve =
+      (info.objectForKey(UIKeyboardAnimationCurveUserInfoKey)?.integerValue as
+        number | undefined) ?? 0
+    // The keyboard's curve is private; shifted into the options it still applies.
+    UIView.animateWithDurationDelayOptionsAnimationsCompletion(
+      duration,
+      0,
+      ((curve << 16) | BEGIN_FROM_CURRENT_STATE) as UIViewAnimationOptions,
+      apply,
+      () => {},
+    )
+  }
+  const observer = Application.ios.addNotificationObserver(
+    UIKeyboardWillChangeFrameNotification,
+    onKeyboard,
+  )
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    Application.ios.removeNotificationObserver(
+      observer,
+      UIKeyboardWillChangeFrameNotification,
+    )
+    view.off('unloaded', cleanup)
+    if (current) view.translateY = 0
+  }
+  view.on('unloaded', cleanup)
+  return cleanup
+}
+
+function followAndroid(view: View, offset: number) {
+  if (android.os.Build.VERSION.SDK_INT < 30) return () => {}
+  const density = Utils.layout.getDisplayDensity()
+  let disposed = false
+  let follower: org.rafaelaugusto.jolt.KeyboardFollower | undefined
+  const attach = () => {
+    if (disposed || follower) return
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (!native) return
+    try {
+      follower = new org.rafaelaugusto.jolt.KeyboardFollower(
+        native,
+        offset * density,
+        new org.rafaelaugusto.jolt.KeyboardFollower.Listener({
+          onStart: () => stop(view, ['y']),
+          onSettled: (translation) => {
+            view.translateY = translation / density
+          },
+        }),
+      )
+    } catch {
+      // A JS-only update cannot install the native plugin. Leave the platform's resize in place.
+      return
+    }
+    follower.attach()
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    view.off('loaded', attach)
+    view.off('unloaded', cleanup)
+    if (follower) {
+      follower.detach()
+      follower = undefined
+      view.translateY = 0
+    }
+  }
+  view.on('loaded', attach)
+  view.on('unloaded', cleanup)
+  if (view.isLoaded) attach()
+  return cleanup
+}

package/src/label.ts

@@ -0,0 +1,76 @@
+import type { Label } from '@nativescript/core'
+
+const callbacks = new WeakMap<NSObject, (finished: boolean) => void>()
+let Delegate: typeof NSObject | undefined
+const styleEvents = [
+  'fontInternalChange',
+  'colorChange',
+  'textAlignmentChange',
+  'textDecorationChange',
+  'textTransformChange',
+  'letterSpacingChange',
+  'lineHeightChange',
+  'textShadowChange',
+  'textStrokeChange',
+  'whiteSpaceChange',
+  'textOverflowChange',
+  'maxLinesChange',
+  'paddingLeftChange',
+  'paddingRightChange',
+  'paddingTopChange',
+  'paddingBottomChange',
+  'visibilityChange',
+  'directionChange',
+  'borderLeftWidthChange',
+  'borderRightWidthChange',
+  'borderTopWidthChange',
+  'borderBottomWidthChange',
+]
+
+/** Reports text, formatted text and style changes of a Label until the returned function is called. */
+export function watchLabel(view: Label, onChange: () => void): () => void {
+  const formatted = view.formattedText
+  view.on('textChange', onChange)
+  view.on('formattedTextChange', onChange)
+  formatted?.on('propertyChange', onChange)
+  for (const event of styleEvents) view.style.on(event, onChange)
+  return () => {
+    view.off('textChange', onChange)
+    view.off('formattedTextChange', onChange)
+    formatted?.off('propertyChange', onChange)
+    for (const event of styleEvents) view.style.off(event, onChange)
+  }
+}
+
+/** A CAAnimationDelegate that reports when its animation stops. Release it with `forgetCompletion`. */
+export function completion(
+  callback: (finished: boolean) => void,
+): NSObject & CAAnimationDelegate {
+  if (!Delegate) {
+    const base = NSObject as typeof NSObject & {
+      extend(
+        methods: object,
+        options: { protocols: unknown[]; name: string },
+      ): typeof NSObject
+    }
+    Delegate = base.extend(
+      {
+        animationDidStopFinished(
+          this: NSObject,
+          _animation: CAAnimation,
+          finished: boolean,
+        ) {
+          callbacks.get(this)?.(finished)
+        },
+      },
+      { protocols: [CAAnimationDelegate], name: 'JoltLabelAnimationDelegate' },
+    )
+  }
+  const delegate = Delegate.new()
+  callbacks.set(delegate, callback)
+  return delegate
+}
+
+export function forgetCompletion(delegate: NSObject) {
+  callbacks.delete(delegate)
+}

package/src/liquid.ts

@@ -3,6 +3,7 @@ import { tintColorProperty } from '@nativescript/core/ui/image'
 import { toView } from './animate.js'
 import { liquidGrid } from './liquid-grid.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export interface LiquidOptions {
   /** Amount of internal deformation, from 0 to 1. Defaults to 0.7. */
@@ -134,7 +135,7 @@ class Liquid implements LiquidEffect {
       !this.image.isLoaded ||
       this.image.visibility !== 'visible' ||
       this.image.tintColor ||
-      UIAccessibilityIsReduceMotionEnabled()
+      reducedMotion()
     )
       return this.remove()
     const native = this.image.nativeViewProtected as UIImageView | undefined

package/src/loader.ts

@@ -1,6 +1,7 @@
 import { Application, Color, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export type LoaderStyle = 'dots' | 'bars' | 'ring'
 
@@ -160,7 +161,7 @@ class Loader {
           0,
         )
       }
-      const reduced = UIAccessibilityIsReduceMotionEnabled()
+      const reduced = reducedMotion()
       item.opacity = style === 'ring' ? 0.35 : 1
       if (reduced && this.animating) {
         item.removeAnimationForKey(key)