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

package/src/sequence.ts

@@ -1,22 +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.
@@ -24,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)
@@ -52,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),
@@ -61,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) {
@@ -69,6 +256,8 @@ function applyStartingValues(steps: readonly Step[]) {
     const starts = startingValues(animation, options)
 
     for (const view of toViews(target)) {
+      for (const property of starts.keys())
+        if (isDecorationProperty(property)) validateDecorationTarget(view, property)
       let properties = claimed.get(view)
       if (!properties) claimed.set(view, (properties = new Set()))
 
@@ -82,6 +271,7 @@ function applyStartingValues(steps: readonly Step[]) {
       for (const [property, value] of fresh) {
         if (value !== null) writeValue(view, property, value)
       }
+      getDriver().sync?.(view)
       for (const property of starts.keys()) properties.add(property)
     }
   }

package/src/shimmer.ts

@@ -0,0 +1,180 @@
+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. */
+  duration?: number
+}
+
+const running = new WeakMap<View, () => void>()
+const key = 'jolt:shimmer'
+
+// NativeScript saves a mask here while applying clip-path or non-uniform borders.
+type MaskedView = UIView & { originalMask?: CALayer | null }
+
+/**
+ * Sweeps a native gradient mask across an iOS placeholder until stopped.
+ * Waits for layout, respects Reduce Motion and pauses while the view is unloaded.
+ * Android is a no-op. Returns an idempotent cleanup function.
+ */
+export function shimmer(target: Target, options: ShimmerOptions = {}): () => void {
+  const view = toView(target)
+  const duration = options.duration ?? 1500
+  if (!Number.isFinite(duration) || duration <= 0)
+    throw new RangeError('Shimmer duration must be a positive finite number.')
+  running.get(view)?.()
+  if (!isIOS) return () => {}
+  return new Shimmer(view, duration).stop
+}
+
+class Shimmer {
+  private stopped = false
+  private queued = false
+  private waitingForLoad: boolean
+  private native: MaskedView | undefined
+  private owner: CALayer | undefined
+  private gradient: CAGradientLayer | undefined
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: View,
+    private readonly duration: number,
+  ) {
+    this.waitingForLoad = !view.isLoaded
+    running.set(view, this.stop)
+    view.on('loaded', this.loaded)
+    view.on('layoutChanged', this.schedule)
+    view.on('unloaded', this.unloaded)
+    view.style.on('backgroundInternalChange', this.schedule)
+    this.update()
+  }
+
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    const { view } = this
+    view.off('loaded', this.loaded)
+    view.off('layoutChanged', this.schedule)
+    view.off('unloaded', this.unloaded)
+    view.style.off('backgroundInternalChange', this.schedule)
+    if (running.get(view) === this.stop) running.delete(view)
+    this.unloaded()
+  }
+
+  private loaded = () => {
+    this.waitingForLoad = false
+    this.schedule()
+  }
+
+  private unloaded = () => {
+    this.waitingForLoad = true
+    if (this.observer) {
+      Application.ios.removeNotificationObserver(
+        this.observer,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+      this.observer = undefined
+    }
+    this.remove()
+  }
+
+  private schedule = () => {
+    if (this.stopped || this.queued) return
+    this.queued = true
+    // Core raises layoutChanged before redrawing the background and its mask.
+    // Attach after that pass, coalescing events from the same layout.
+    void Promise.resolve().then(() => {
+      this.queued = false
+      this.update()
+    })
+  }
+
+  private update = () => {
+    if (this.stopped || this.waitingForLoad || !this.view.isLoaded) return
+    const native = this.view.nativeViewProtected as MaskedView | undefined
+    if (!native) return
+    this.observer ??= Application.ios.addNotificationObserver(
+      UIAccessibilityReduceMotionStatusDidChangeNotification,
+      this.update,
+    )
+    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()
+
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      this.native = native
+      const gradient = (this.gradient ??= this.createGradient())
+      // Leave Core's mask at the root so it can keep updating its path on resize.
+      let owner = native.layer
+      while (owner.mask && owner.mask !== gradient) owner = owner.mask
+      if (this.owner && this.owner !== owner && this.owner.mask === gradient)
+        this.owner.mask = null
+      this.owner = owner
+      owner.mask = gradient
+      // Don't let a later background redraw resurrect our mask after cleanup.
+      if (native.originalMask === gradient) native.originalMask = null
+
+      // Core's CAShapeLayer masks draw a path with zero bounds. In that case the
+      // path uses the view's coordinates; other masks have their own bounds.
+      const area =
+        owner.bounds.size.width > 0 && owner.bounds.size.height > 0
+          ? owner.bounds
+          : bounds
+      gradient.frame = CGRectMake(
+        area.origin.x - area.size.width,
+        area.origin.y,
+        area.size.width * 3,
+        area.size.height,
+      )
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private createGradient(): CAGradientLayer {
+    const gradient = CAGradientLayer.new()
+    const dim = UIColor.colorWithWhiteAlpha(1, 0.35).CGColor
+    gradient.colors = NSArray.arrayWithArray([dim, UIColor.whiteColor.CGColor, dim])
+    gradient.startPoint = CGPointMake(0, 0.5)
+    gradient.endPoint = CGPointMake(1, 0.5)
+
+    // A three-width mask lets the band enter and leave while every stop stays
+    // within the documented 0...1 range for CAGradientLayer.locations.
+    const from = NSArray.arrayWithArray([0, 0.125, 0.25])
+    const to = NSArray.arrayWithArray([0.75, 0.875, 1])
+    gradient.locations = from
+    const animation = CABasicAnimation.animationWithKeyPath('locations')
+    animation.fromValue = from
+    animation.toValue = to
+    animation.duration = this.duration / 1000
+    animation.repeatCount = Infinity
+    animation.removedOnCompletion = false
+    animation.timingFunction = CAMediaTimingFunction.functionWithName(
+      kCAMediaTimingFunctionLinear,
+    )
+    gradient.addAnimationForKey(animation, key)
+    return gradient
+  }
+
+  private remove() {
+    const { gradient, owner, native } = this
+    if (!gradient) return
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      gradient.removeAnimationForKey(key)
+      if (owner?.mask === gradient) owner.mask = null
+      if (native?.originalMask === gradient) native.originalMask = null
+    } finally {
+      CATransaction.commit()
+    }
+    this.owner = undefined
+    this.gradient = undefined
+    this.native = undefined
+  }
+}