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

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()

package/src/svg-path.ts

@@ -0,0 +1,355 @@
+/** SVG path geometry in local DIPs. No DOM or platform path API is used. */
+export interface PathPoint {
+  x: number
+  y: number
+}
+export interface PathPose extends PathPoint {
+  rotate: number
+}
+type Segment = { point(t: number): PathPoint; tangent(t: number): PathPoint }
+type Vertex = PathPoint & {
+  segment: number
+  t: number
+  distance: number
+  heading: number
+}
+export interface MotionPath {
+  readonly length: number
+  at(progress: number): PathPose
+}
+const LIMIT = 1_000_000
+const MAX_SEGMENTS = 1024
+const MAX_VERTICES = 8192
+const TOLERANCE = 0.025
+const distance = (a: PathPoint, b: PathPoint) => Math.hypot(b.x - a.x, b.y - a.y)
+const mix = (a: PathPoint, b: PathPoint, t: number): PathPoint => ({
+  x: a.x + (b.x - a.x) * t,
+  y: a.y + (b.y - a.y) * t,
+})
+const checked = (p: PathPoint) => {
+  if (![p.x, p.y].every((n) => Number.isFinite(n) && Math.abs(n) <= LIMIT))
+    throw new RangeError('Path coordinates must stay within ±1000000 DIPs.')
+  return p
+}
+const unwrap = (angle: number, reference: number) =>
+  angle + 360 * Math.round((reference - angle) / 360)
+
+class Scanner {
+  index = 0
+  private hasNumber = false
+  constructor(readonly text: string) {}
+  peek() {
+    while (/[\t\n\r ]/.test(this.text[this.index] ?? '\0')) this.index++
+    return this.text[this.index]
+  }
+  command() {
+    const value = this.peek()!
+    this.index++
+    this.hasNumber = false
+    return value
+  }
+  number(flag = false) {
+    this.peek()
+    if (this.text[this.index] === ',') {
+      if (!this.hasNumber) this.error()
+      this.index++
+      this.peek()
+    }
+    const rest = this.text.slice(this.index)
+    const token = flag
+      ? /^[01]/.exec(rest)?.[0]
+      : /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?/i.exec(rest)?.[0]
+    if (!token) this.error()
+    const value = Number(token)
+    if (!Number.isFinite(value) || Math.abs(value) > LIMIT)
+      throw new RangeError('Path numbers must be finite and within ±1000000.')
+    this.index += token!.length
+    this.hasNumber = true
+    return value
+  }
+  error(): never {
+    throw new SyntaxError(`Invalid SVG path at character ${this.index}.`)
+  }
+}
+
+function line(a: PathPoint, b: PathPoint): Segment {
+  return { point: (t) => mix(a, b, t), tangent: () => ({ x: b.x - a.x, y: b.y - a.y }) }
+}
+function bezier(points: readonly PathPoint[]): Segment {
+  const evaluate = (values: readonly PathPoint[], t: number): PathPoint => {
+    let row = [...values]
+    while (row.length > 1) row = row.slice(1).map((p, i) => mix(row[i]!, p, t))
+    return row[0]!
+  }
+  const derivative = points.slice(1).map((p, i) => ({
+    x: (p.x - points[i]!.x) * (points.length - 1),
+    y: (p.y - points[i]!.y) * (points.length - 1),
+  }))
+  return { point: (t) => evaluate(points, t), tangent: (t) => evaluate(derivative, t) }
+}
+
+/** Endpoint-to-center conversion: https://www.w3.org/TR/SVG/implnote.html#ArcConversionEndpointToCenter */
+function arc(
+  a: PathPoint,
+  b: PathPoint,
+  rx: number,
+  ry: number,
+  degrees: number,
+  large: boolean,
+  sweep: boolean,
+): Segment {
+  rx = Math.abs(rx)
+  ry = Math.abs(ry)
+  if (!rx || !ry || distance(a, b) === 0) return line(a, b)
+  const phi = ((degrees % 360) * Math.PI) / 180,
+    cos = Math.cos(phi),
+    sin = Math.sin(phi)
+  const dx = (a.x - b.x) / 2,
+    dy = (a.y - b.y) / 2
+  const xp = cos * dx + sin * dy,
+    yp = -sin * dx + cos * dy
+  const correction = Math.max(1, Math.hypot(xp / rx, yp / ry))
+  rx *= correction
+  ry *= correction
+  const u = xp / rx,
+    v = yp / ry,
+    norm = u * u + v * v
+  const factor = (large === sweep ? -1 : 1) * Math.sqrt(Math.max(0, (1 - norm) / norm))
+  const cxp = factor * rx * v,
+    cyp = -factor * ry * u
+  const cx = cos * cxp - sin * cyp + (a.x + b.x) / 2,
+    cy = sin * cxp + cos * cyp + (a.y + b.y) / 2
+  const ux = (xp - cxp) / rx,
+    uy = (yp - cyp) / ry,
+    vx = (-xp - cxp) / rx,
+    vy = (-yp - cyp) / ry
+  const start = Math.atan2(uy, ux)
+  let delta = Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy)
+  if (!sweep && delta > 0) delta -= 2 * Math.PI
+  if (sweep && delta < 0) delta += 2 * Math.PI
+  if (![cx, cy, rx, ry, start, delta].every(Number.isFinite))
+    throw new RangeError('Path arc exceeds finite geometry limits.')
+  return {
+    point(t) {
+      if (t === 0) return a
+      if (t === 1) return b
+      const angle = start + t * delta,
+        x = rx * Math.cos(angle),
+        y = ry * Math.sin(angle)
+      return checked({ x: cx + cos * x - sin * y, y: cy + sin * x + cos * y })
+    },
+    tangent(t) {
+      const angle = start + t * delta,
+        x = -rx * Math.sin(angle) * delta,
+        y = ry * Math.cos(angle) * delta
+      return { x: cos * x - sin * y, y: sin * x + cos * y }
+    },
+  }
+}
+
+export function parsePath(data: string): MotionPath {
+  if (typeof data !== 'string' || !data.trim())
+    throw new TypeError('Path must be a nonempty SVG path string.')
+  if (data.length > 100_000)
+    throw new RangeError('SVG path is too long (100000 characters maximum).')
+  const scanner = new Scanner(data)
+  const segments: Segment[] = []
+  let current: PathPoint = { x: 0, y: 0 },
+    first: PathPoint | undefined
+  let command = '',
+    previous = '',
+    control: PathPoint = current
+  const add = (segment: Segment, end: PathPoint) => {
+    if (segments.length >= MAX_SEGMENTS)
+      throw new RangeError('SVG path has too many segments (1024 maximum).')
+    segments.push(segment)
+    current = checked(end)
+  }
+  while (scanner.peek() !== undefined) {
+    const token = scanner.peek()!
+    if (/[a-z]/i.test(token)) {
+      command = scanner.command()
+      if (!/[mlhvcsqtaz]/i.test(command)) scanner.error()
+    } else if (!command) scanner.error()
+    const upper = command.toUpperCase(),
+      relative = command !== upper,
+      origin = current
+    const point = () =>
+      checked({
+        x: scanner.number() + (relative ? origin.x : 0),
+        y: scanner.number() + (relative ? origin.y : 0),
+      })
+    if (!first && upper !== 'M') throw new SyntaxError('SVG path must start with M or m.')
+    if (upper === 'M') {
+      if (first)
+        throw new SyntaxError(
+          'Motion paths support one continuous subpath; use a single M command.',
+        )
+      first = current = point()
+      command = relative ? 'l' : 'L'
+    } else if (upper === 'Z') {
+      add(line(current, first!), first!)
+      command = ''
+    } else if (upper === 'L') {
+      const end = point()
+      add(line(current, end), end)
+    } else if (upper === 'H' || upper === 'V') {
+      const n = scanner.number(),
+        end = checked(
+          upper === 'H'
+            ? { x: n + (relative ? origin.x : 0), y: current.y }
+            : { x: current.x, y: n + (relative ? origin.y : 0) },
+        )
+      add(line(current, end), end)
+    } else if (upper === 'C' || upper === 'S') {
+      const c1 =
+        upper === 'C'
+          ? point()
+          : /[CS]/.test(previous)
+            ? { x: 2 * current.x - control.x, y: 2 * current.y - control.y }
+            : current
+      const c2 = point(),
+        end = point()
+      checked(c1)
+      add(bezier([current, c1, c2, end]), end)
+      control = c2
+    } else if (upper === 'Q' || upper === 'T') {
+      const c =
+        upper === 'Q'
+          ? point()
+          : /[QT]/.test(previous)
+            ? { x: 2 * current.x - control.x, y: 2 * current.y - control.y }
+            : current
+      const end = point()
+      checked(c)
+      add(bezier([current, c, end]), end)
+      control = c
+    } else if (upper === 'A') {
+      const rx = scanner.number(),
+        ry = scanner.number(),
+        rotation = scanner.number(),
+        large = scanner.number(true),
+        sweep = scanner.number(true),
+        end = point()
+      add(arc(current, end, rx, ry, rotation, !!large, !!sweep), end)
+    }
+    previous = upper
+  }
+  return measure(first!, segments)
+}
+
+function measure(first: PathPoint, segments: readonly Segment[]): MotionPath {
+  const vertices: Vertex[] = [{ ...first, segment: -1, t: 0, distance: 0, heading: 0 }]
+  const heading = (segment: Segment, t: number, fallback: PathPoint) => {
+    let v = segment.tangent(t)
+    if (Math.hypot(v.x, v.y) < 1e-9) {
+      const a = segment.point(Math.max(0, t - 1e-5)),
+        b = segment.point(Math.min(1, t + 1e-5))
+      v = { x: b.x - a.x, y: b.y - a.y }
+      if (Math.hypot(v.x, v.y) < 1e-9) v = fallback
+    }
+    return (Math.atan2(v.y, v.x) * 180) / Math.PI
+  }
+  const append = (p: PathPoint, index: number, t: number) => {
+    const last = vertices.at(-1)!,
+      length = distance(last, p)
+    if (!length) return
+    if (vertices.length >= MAX_VERTICES)
+      throw new RangeError('Path needs too many geometry samples (8192 maximum).')
+    const direction = { x: p.x - last.x, y: p.y - last.y }
+    const start = heading(
+      segments[index]!,
+      last.segment === index ? last.t : 0,
+      direction,
+    )
+    if (vertices.length === 1) last.heading = start
+    const angle = unwrap(
+      heading(segments[index]!, t, direction),
+      unwrap(start, last.heading),
+    )
+    vertices.push({
+      ...checked(p),
+      segment: index,
+      t,
+      distance: last.distance + length,
+      heading: angle,
+    })
+  }
+  segments.forEach((segment, index) => {
+    const flatten = (
+      t0: number,
+      t1: number,
+      a: PathPoint,
+      b: PathPoint,
+      depth: number,
+    ) => {
+      const span = t1 - t0,
+        q1 = segment.point(t0 + span * 0.25),
+        mid = segment.point(t0 + span * 0.5),
+        q3 = segment.point(t0 + span * 0.75)
+      const poly =
+          distance(a, q1) + distance(q1, mid) + distance(mid, q3) + distance(q3, b),
+        chord = distance(a, b)
+      const deviation = Math.max(
+        distance(q1, mix(a, b, 0.25)),
+        distance(mid, mix(a, b, 0.5)),
+        distance(q3, mix(a, b, 0.75)),
+      )
+      const directions = [
+        t0,
+        t0 + span * 0.25,
+        t0 + span * 0.5,
+        t0 + span * 0.75,
+        t1,
+      ].map((t) => segment.tangent(t))
+      const turn = directions.some((v, i) => {
+        const before = directions[i - 1]
+        return (
+          before &&
+          Math.hypot(v.x, v.y) > 1e-12 &&
+          Math.hypot(before.x, before.y) > 1e-12 &&
+          Math.abs(
+            Math.atan2(before.x * v.y - before.y * v.x, before.x * v.x + before.y * v.y),
+          ) >
+            Math.PI / 8
+        )
+      })
+      const flat = poly - chord <= TOLERANCE && deviation <= TOLERANCE
+      if (flat && (!turn || depth >= 18)) {
+        append(b, index, t1)
+        return
+      }
+      if (depth >= 18)
+        throw new RangeError('Path geometry exceeds the sampling precision limit.')
+      flatten(t0, (t0 + t1) / 2, a, mid, depth + 1)
+      flatten((t0 + t1) / 2, t1, mid, b, depth + 1)
+    }
+    flatten(0, 1, segment.point(0), segment.point(1), 0)
+  })
+  const length = vertices.at(-1)!.distance
+  return {
+    length,
+    at(progress) {
+      if (!length) return { ...first, rotate: 0 }
+      const target = Math.max(0, Math.min(1, progress)) * length
+      let low = 1,
+        high = vertices.length - 1
+      while (low < high) {
+        const middle = (low + high) >>> 1
+        if (vertices[middle]!.distance <= target) low = middle + 1
+        else high = middle
+      }
+      const b = vertices[low]!,
+        a = vertices[low - 1]!,
+        fraction = Math.max(
+          0,
+          Math.min(1, (target - a.distance) / (b.distance - a.distance)),
+        )
+      const point = mix(a, b, fraction),
+        t0 = a.segment === b.segment ? a.t : 0,
+        t = t0 + (b.t - t0) * fraction
+      const angle = heading(segments[b.segment]!, t, { x: b.x - a.x, y: b.y - a.y })
+      return { ...point, rotate: unwrap(angle, b.heading) }
+    },
+  }
+}

package/src/symbol-effect.ts

@@ -2,6 +2,7 @@ import { Image, ImageSource, isIOS } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Animation } from './engine.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export type SymbolEffectName = 'bounce' | 'pulse' | 'scale' | 'variableColor'
 
@@ -121,7 +122,7 @@ class SymbolAnimation implements Animation {
       return
     this.started = true
     const native = (this.native = view.nativeViewProtected as UIImageView)
-    const reducedMotion = UIAccessibilityIsReduceMotionEnabled()
+    const reduced = reducedMotion()
 
     if (typeof effect !== 'string') {
       // Resolve first so a symbol absent on this OS doesn't clear the current image.
@@ -145,7 +146,7 @@ class SymbolAnimation implements Animation {
       const image = native.image
       if (!image) return this.end(false)
       if (
-        reducedMotion ||
+        reduced ||
         !previous?.symbolImage ||
         !native.respondsToSelector(
           'setSymbolImage:withContentTransition:options:completion:',
@@ -165,7 +166,7 @@ class SymbolAnimation implements Animation {
     }
 
     if (
-      reducedMotion ||
+      reduced ||
       !native.image?.symbolImage ||
       !native.respondsToSelector('addSymbolEffect:options:animated:completion:')
     )