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

package/src/scroll-linked.ts

@@ -0,0 +1,73 @@
+import { ScrollView, type EventData, type ScrollEventData } from '@nativescript/core'
+import { animate, toView } from './animate.js'
+import type { Keyframes, Target } from './types.js'
+
+export interface ScrollLinkedOptions {
+  /** Scroll offsets in DIPs, mapped to progress 0 and 1. Either order is allowed. */
+  range: readonly [number, number]
+  /** Offset to read. Defaults to the vertical axis. */
+  axis?: 'x' | 'y'
+}
+
+/** Builds one paused animation and scrubs it synchronously on scroll. */
+export function scrollLinked(
+  scrollView: Target,
+  target: Target,
+  keyframes: Keyframes,
+  options: ScrollLinkedOptions,
+): () => void {
+  const source = toView(scrollView)
+  if (!(source instanceof ScrollView))
+    throw new TypeError('scrollLinked requires a NativeScript ScrollView.')
+  const view = toView(target)
+  const range = options?.range
+  if (
+    !Array.isArray(range) ||
+    range.length !== 2 ||
+    !range.every(Number.isFinite) ||
+    !Number.isFinite(range[1]! - range[0]!) ||
+    range[0] === range[1]
+  )
+    throw new RangeError('Scroll range requires two distinct finite offsets in DIPs.')
+  const [start, end] = range as [number, number]
+  const axis = options.axis ?? 'y'
+  if (axis !== 'x' && axis !== 'y') throw new TypeError('Scroll axis must be "x" or "y".')
+
+  const animation = animate(view, keyframes, { duration: 1000, ease: 'linear' })
+  animation.pause()
+  let disposed = false
+  let previous: number | undefined
+
+  const update = (offset: number) => {
+    if (disposed || !Number.isFinite(offset)) return
+    const progress = Math.max(0, Math.min(1, (offset - start) / (end - start)))
+    if (progress === previous) return
+    animation.progress = progress
+    previous = progress
+  }
+  const current = () =>
+    update(axis === 'x' ? source.horizontalOffset : source.verticalOffset)
+  const onScroll = (event: EventData) => {
+    const scroll = event as ScrollEventData
+    update(axis === 'x' ? scroll.scrollX : scroll.scrollY)
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    source.off(ScrollView.scrollEvent, onScroll)
+    source.off('loaded', current)
+    source.off('unloaded', cleanup)
+    view.off('loaded', current)
+    view.off('unloaded', cleanup)
+    animation.stop()
+  }
+
+  source.on(ScrollView.scrollEvent, onScroll)
+  source.on('loaded', current)
+  source.on('unloaded', cleanup)
+  view.on('loaded', current)
+  view.on('unloaded', cleanup)
+  void animation.finished.then(cleanup)
+  current()
+  return cleanup
+}

package/src/sequence.ts

@@ -1,24 +1,36 @@
+import { timeScale } from './config.js'
 import { getDriver } from './driver/index.js'
 import { isDecorationProperty, validateDecorationTarget } from './decoration.js'
 import type { View } from '@nativescript/core'
 import { animate, startingValues, toViews } from './animate.js'
-import { arrivalOf, setArrival, stopView, type Animation } from './engine.js'
+import {
+  arrivalOf,
+  arrivalTimingOf,
+  setArrival,
+  stopView,
+  type Animation,
+} from './engine.js'
+import { createClock } from './playback.js'
 import type { PresetName } from './presets.js'
 import { writeValue, type Property } from './properties.js'
 import type { SpringName } from './transition.js'
 import type { AnimateOptions, Keyframes, Target } from './types.js'
 
+/** Absolute milliseconds, a signed offset from the previous arrival, or its start. */
+export type SequencePosition = number | '<' | `${'+' | '-'}${number}`
+export type SequenceOptions = AnimateOptions & { at?: SequencePosition }
+
 export type Step =
   | readonly [
       target: Target | readonly Target[],
       animation: Keyframes | PresetName,
-      options?: AnimateOptions | SpringName,
+      options?: SequenceOptions | SpringName,
     ]
   | (() => Animation)
 
 /**
- * Plays steps one after the other. A step starts once the previous one looks
- * done: a spring is close to its target, even if it hasn't fully settled.
+ * By default a step starts once the previous one looks done. `at` can overlap
+ * that arrival, share the previous start, or select an absolute timeline time.
  * Views in later steps take their first absolute keyframe right away, so a title
  * that fades in third doesn't show up before its turn. Relative and null keyframes
  * read the current value when their step starts.
@@ -26,26 +38,180 @@ export type Step =
  * ```ts
  * await sequence([
  *   [logo, 'popIn'],
- *   [title, 'fadeInUp'],
- *   [buttons, 'fadeInUp', { stagger: 50 }],
+ *   [title, 'fadeInUp', { at: '-150' }],
+ *   [buttons, 'fadeInUp', { stagger: 50, at: '<' }],
  * ])
  * ```
  */
 export function sequence(steps: readonly Step[]): Animation {
-  applyStartingValues(steps)
+  const prepared = steps.map((step) => {
+    if (typeof step === 'function') return { step, position: undefined }
+    const [target, animation, options] = step
+    if (typeof options !== 'object' || options === null)
+      return { step, position: undefined }
+    const { at, ...transition } = options
+    const position = parsePosition(at)
+    return { step: [target, animation, transition] as Step, position }
+  })
+  applyStartingValues(prepared.map(({ step }) => step))
 
+  const driver = getDriver()
+  const slowdown = 1 / timeScale()
+  // Absolute positions share the platform clock, including Android duration scale.
+  const clock = prepared.some(({ position }) => typeof position === 'number')
+    ? (driver.clock?.(Infinity) ?? createClock(() => driver.now()))
+    : undefined
   const started: Animation[] = []
+  const cancellations = new Set<() => void>()
   let stopped = false
+  let resolveScheduled!: () => void
+  let rejectScheduled!: (reason: unknown) => void
+  const scheduled = new Promise<void>((resolve, reject) => {
+    resolveScheduled = resolve
+    rejectScheduled = reject
+  })
+  let pending = prepared.length
+  const states = prepared.map(({ step, position }) => {
+    return {
+      step,
+      position,
+      onStart: new Set<() => void>(),
+      animation: undefined as Animation | undefined,
+    }
+  })
+  const cancelSchedule = () => {
+    for (const cancel of cancellations) cancel()
+    cancellations.clear()
+    clock?.cancel()
+  }
+  const fail = (error: unknown) => {
+    if (stopped) return
+    stopped = true
+    cancelSchedule()
+    states.forEach((state) => state.onStart.clear())
+    started.forEach((child) => child.stop())
+    rejectScheduled(error)
+  }
+  const launch = (index: number) => {
+    const state = states[index]!
+    if (stopped || state.animation) return
+    try {
+      const step = state.step
+      const child = typeof step === 'function' ? step() : animate(...step)
+      state.animation = child
+      started.push(child)
+      // Observe setup failures immediately, even while other steps are still
+      // scheduled. Nested sequences can reject before this one reaches arrival.
+      void child.finished.catch(fail)
+      pending--
+      for (const callback of [...state.onStart]) callback()
+      state.onStart.clear()
+      if (pending === 0) {
+        cancelSchedule()
+        resolveScheduled()
+      }
+    } catch (error) {
+      fail(error)
+    }
+  }
+  const wait = (ms: number, callback: () => void) => {
+    if (stopped) return
+    if (ms <= 0) {
+      callback()
+      return
+    }
+    let cancel = () => {}
+    let fired = false
+    const off = driver.after(ms, () => {
+      fired = true
+      cancellations.delete(cancel)
+      if (!stopped) callback()
+    })
+    cancel = off
+    if (!fired) cancellations.add(cancel)
+  }
 
-  const arrived = (async () => {
-    for (const step of steps) {
-      if (stopped) return
-      const animation = typeof step === 'function' ? step() : animate(...step)
-      started.push(animation)
-      await arrivalOf(animation)
+  for (let index = 0; index < states.length; index++) {
+    const { position } = states[index]!
+    const begin = () => launch(index)
+    if (typeof position === 'number') wait(position * slowdown - clock!.time(), begin)
+    else if (index === 0)
+      wait(
+        typeof position === 'object' ? Math.max(0, position.offset) * slowdown : 0,
+        begin,
+      )
+    else {
+      const previous = states[index - 1]!
+      const follow = () => {
+        if (stopped || !previous.animation) return
+        if (position === '<') {
+          begin()
+          return
+        }
+        const offset = (position?.offset ?? 0) * slowdown
+        if (offset < 0) {
+          const timing = arrivalTimingOf(previous.animation)
+          if (!timing) {
+            fail(
+              new TypeError(
+                'A negative at offset needs an animate() or decay() arrival forecast.',
+              ),
+            )
+            return
+          }
+          let off = () => {}
+          let cancelTimer = () => {}
+          let fired = false
+          let disposed = false
+          let queued = false
+          const dispose = () => {
+            disposed = true
+            off()
+            cancelTimer()
+            cancellations.delete(dispose)
+          }
+          const update = () => {
+            cancelTimer()
+            if (stopped || fired || disposed) return
+            const state = timing.read()
+            if (!state.arrived && (state.paused || state.remaining === undefined)) return
+            const remaining = state.arrived ? 0 : state.remaining! + offset
+            if (!Number.isFinite(remaining)) return
+            const fire = () => {
+              if (stopped || fired || disposed) return
+              fired = true
+              dispose()
+              begin()
+            }
+            if (remaining <= 0) fire()
+            else {
+              const cancel = driver.after(remaining, fire)
+              if (disposed) cancel()
+              else cancelTimer = cancel
+            }
+          }
+          off = timing.subscribe(() => {
+            cancelTimer()
+            // An interruption can notify from inside another animation's
+            // constructor. Start followers after its ownership changes finish.
+            if (queued || disposed) return
+            queued = true
+            void Promise.resolve().then(() => {
+              queued = false
+              update()
+            })
+          })
+          cancellations.add(dispose)
+          update()
+        } else void arrivalOf(previous.animation).then(() => wait(offset, begin), fail)
+      }
+      if (previous.animation) follow()
+      else previous.onStart.add(follow)
     }
-  })()
+  }
+  if (pending === 0) resolveScheduled()
 
+  const arrived = scheduled.then(() => Promise.all(started.map(arrivalOf)))
   const finished = arrived.then(async () => {
     const results = await Promise.all(started.map((animation) => animation.finished))
     return !stopped && results.length === steps.length && results.every(Boolean)
@@ -54,7 +220,11 @@ export function sequence(steps: readonly Step[]): Animation {
   const animation: Animation = {
     finished,
     stop() {
+      if (stopped) return
       stopped = true
+      cancelSchedule()
+      states.forEach((state) => state.onStart.clear())
+      resolveScheduled()
       started.forEach((animation) => animation.stop())
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
@@ -63,6 +233,21 @@ export function sequence(steps: readonly Step[]): Animation {
   return animation
 }
 
+type Position = number | '<' | { offset: number } | undefined
+function parsePosition(at: SequencePosition | undefined): Position {
+  if (at === undefined || at === '<') return at
+  if (typeof at === 'number' && Number.isFinite(at) && at >= 0) return at
+  if (
+    typeof at === 'string' &&
+    /^[+-](?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(at) &&
+    Number.isFinite(Number(at))
+  )
+    return { offset: Number(at) }
+  throw new RangeError(
+    'Sequence at must be a nonnegative finite time, "<", or a signed finite offset.',
+  )
+}
+
 function applyStartingValues(steps: readonly Step[]) {
   const claimed = new Map<View, Set<Property>>()
   for (const step of steps) {

package/src/shimmer.ts

@@ -1,6 +1,7 @@
 import { Application, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export interface ShimmerOptions {
   /** Milliseconds per sweep. Defaults to 1500. */
@@ -98,7 +99,7 @@ class Shimmer {
       UIAccessibilityReduceMotionStatusDidChangeNotification,
       this.update,
     )
-    if (UIAccessibilityIsReduceMotionEnabled()) return this.remove()
+    if (reducedMotion()) return this.remove()
     const bounds = native.layer.bounds
     if (bounds.size.width <= 0 || bounds.size.height <= 0) return this.remove()
     if (this.native && this.native !== native) this.remove()