@rafaelaugusto/jolt 0.1.0-beta.12 → 0.1.0-beta.14

package/src/particles.ts

@@ -1,7 +1,8 @@
-import { Application, Color, isIOS, type View } from '@nativescript/core'
+import { Application, Color, isAndroid, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
-import { reducedMotion } from './config.js'
+import { onReducedMotion, reducedMotion } from './config.js'
+import { androidParticles } from './driver/android-particles.js'
 
 export interface ConfettiOptions {
   /** Approximate number of particles in the burst. Defaults to 80. */
@@ -38,7 +39,10 @@ export interface ParticleOptions {
   duration?: number
 }
 
-type Settings = Required<Omit<ParticleOptions, 'duration'>> & { duration?: number }
+export type ParticleSettings = Required<Omit<ParticleOptions, 'duration'>> & {
+  duration?: number
+}
+type Settings = ParticleSettings
 const bursts = new WeakMap<View, () => void>()
 const emitters = new WeakMap<View, () => void>()
 const palette = ['#facc15', '#ef4444', '#3b82f6', '#22c55e', '#a855f7']
@@ -46,7 +50,7 @@ const textures = new Map<Settings['shape'], UIImage>()
 const radians = (degrees: number) => (degrees * Math.PI) / 180
 const BURST_DURATION = 200
 
-/** Bursts from the target's center into its window. iOS only; returns immediate cleanup. */
+/** Bursts from the target's center into its window. Returns immediate cleanup. */
 export function confetti(target: Target, options: ConfettiOptions = {}): () => void {
   const count = number('count', options.count ?? 80, 0, 10000)
   if (!Number.isInteger(count)) throw new RangeError('Particle count must be an integer.')
@@ -70,7 +74,7 @@ export function confetti(target: Target, options: ConfettiOptions = {}): () => v
   return start(target, settings, true)
 }
 
-/** Adds a native particle emitter to the target. iOS only; returns immediate cleanup. */
+/** Adds a native particle emitter to the target. Returns immediate cleanup. */
 export function particles(target: Target, options: ParticleOptions = {}): () => void {
   return start(target, resolve(options), false)
 }
@@ -79,7 +83,9 @@ function start(target: Target, settings: Settings, overlay: boolean): () => void
   const view = toView(target)
   const running = overlay ? bursts : emitters
   running.get(view)?.()
-  if (!isIOS || settings.rate === 0 || reducedMotion()) return () => {}
+  if (settings.rate === 0 || reducedMotion()) return () => {}
+  if (isAndroid) return androidParticles(view, settings, overlay, running)
+  if (!isIOS) return () => {}
   return new Emitter(view, settings, overlay, running).stop
 }
 
@@ -141,7 +147,7 @@ class Emitter {
   private native: UIView | undefined
   private window: UIWindow | undefined
   private timer: ReturnType<typeof setTimeout> | undefined
-  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+  private unwatch: (() => void) | undefined
 
   constructor(
     private readonly view: View,
@@ -153,6 +159,8 @@ class Emitter {
     view.on('loaded', this.schedule)
     view.on('layoutChanged', this.schedule)
     view.on('unloaded', this.stop)
+    Application.on(Application.suspendEvent, this.stop)
+    this.unwatch = onReducedMotion(this.motionChanged)
     this.schedule()
   }
 
@@ -162,17 +170,14 @@ class Emitter {
     this.view.off('loaded', this.schedule)
     this.view.off('layoutChanged', this.schedule)
     this.view.off('unloaded', this.stop)
+    Application.off(Application.suspendEvent, this.stop)
     if (this.running.get(this.view) === this.stop) this.running.delete(this.view)
     if (this.timer !== undefined) clearTimeout(this.timer)
-    if (this.observer)
-      Application.ios.removeNotificationObserver(
-        this.observer,
-        UIAccessibilityReduceMotionStatusDidChangeNotification,
-      )
+    this.unwatch?.()
     this.layer?.removeAllAnimations()
     this.layer?.removeFromSuperlayer()
     this.layer = this.native = this.window = undefined
-    this.timer = this.observer = undefined
+    this.timer = this.unwatch = undefined
   }
 
   private schedule = () => {
@@ -232,10 +237,6 @@ class Emitter {
             ),
             window,
           )
-        this.observer = Application.ios.addNotificationObserver(
-          UIAccessibilityReduceMotionStatusDidChangeNotification,
-          this.motionChanged,
-        )
         if (this.settings.duration !== undefined) {
           // The render server stops emission even if JS is blocked. The timer
           // only removes the empty layer after the last particles have expired.

package/src/playback-group.ts

@@ -6,7 +6,7 @@ import {
   type ViewAnimation,
 } from './engine.js'
 import { getDriver } from './driver/index.js'
-import { createClock, type PlaybackClock } from './playback.js'
+import { createClock, registerPlayback, type PlaybackClock } from './playback.js'
 import { validateProgress, type PlaybackAnimation } from './playback.js'
 
 /** Staggered views share a finite time range. Shorter children remain seekable
@@ -17,6 +17,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
   let finalProgress: number | undefined
   let clock: PlaybackClock | undefined
   let pendingProgress: number | undefined
+  let changed = () => {}
   const duration = () => Math.max(0, ...children.map((child) => child.duration))
   const ensureClock = () => {
     if (clock || settled || children.some((child) => !child.ready)) return
@@ -44,6 +45,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
     clock?.seek(total * value)
     for (const child of children) child.seekTime(total * value)
     finishIfIdle()
+    changed()
   }
   for (const child of children) {
     child.onIdle(finishIfIdle)
@@ -52,6 +54,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       if (pendingProgress !== undefined && children.every((child) => child.ready))
         seek(pendingProgress)
       finishIfIdle()
+      changed()
     })
   }
   const finished = Promise.all(children.map((child) => child.finished)).then(
@@ -63,6 +66,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
           : 0
       settled = true
       clock?.cancel()
+      changed()
       return results.every(Boolean)
     },
   )
@@ -91,6 +95,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         paused = true
         clock?.pause()
         children.forEach((child) => child.pause())
+        changed()
       }
     },
     play() {
@@ -99,6 +104,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         clock?.play()
         children.forEach((child) => child.play())
         finishIfIdle()
+        changed()
       }
     },
     stop() {
@@ -106,9 +112,19 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       settled = true
       clock?.cancel()
       children.forEach((child) => child.stop())
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  changed = registerPlayback(animation, () => ({
+    position: pendingProgress,
+    time: finalProgress === undefined ? (clock?.time() ?? 0) : finalProgress * duration(),
+    duration: duration(),
+    paused,
+    ready: children.every((child) => child.ready),
+    settled,
+    completed: finalProgress === 1,
+  }))
   setArrival(animation, Promise.all(children.map(arrivalOf)))
   const listeners = new Set<() => void>()
   const timings = children.map((child) => arrivalTimingOf(child)!)

package/src/playback.ts

@@ -23,6 +23,47 @@ export interface PlaybackClock {
   cancel(): void
 }
 
+/** Boundary notifications, never frame callbacks. Consumers sample this same clock. */
+export interface PlaybackState {
+  readonly position?: number
+  readonly time: number
+  readonly duration: number
+  readonly paused: boolean
+  readonly ready: boolean
+  readonly settled: boolean
+  readonly completed: boolean
+}
+
+const sources = new WeakMap<
+  Animation,
+  {
+    read(): PlaybackState
+    listeners: Set<() => void>
+  }
+>()
+
+export function registerPlayback(animation: Animation, read: () => PlaybackState) {
+  const source = { read, listeners: new Set<() => void>() }
+  sources.set(animation, source)
+  return () => {
+    for (const listener of [...source.listeners]) listener()
+  }
+}
+
+export function playbackSource(animation: Animation) {
+  const source = sources.get(animation)
+  if (!source) throw new TypeError('This animation does not expose a playback clock.')
+  return {
+    read: source.read,
+    subscribe(listener: () => void) {
+      source.listeners.add(listener)
+      return () => {
+        source.listeners.delete(listener)
+      }
+    },
+  }
+}
+
 /** Read only on user commands; there is no frame loop in JavaScript. */
 export function createClock(now: () => number, initial = 0): PlaybackClock {
   let offset = initial

package/src/scene-appearance.ts

@@ -0,0 +1,92 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import { Color } from '@nativescript/core'
+import { colorMixer, parseColor, type ColorValue } from './color.js'
+import { registerNativeProperty, type NativeProperty } from './native-property.js'
+
+const clamp = (n: number) => Math.max(0, Math.min(1, n))
+function scalar(name: string, maximum: number, create: (target: object) => object) {
+  return registerNativeProperty<number>({
+    name: `jolt.scenekit/${name}`,
+    units: [
+      name === 'light-intensity'
+        ? 'lumens (PBR); 1000 = unit multiplier otherwise'
+        : 'opacity fraction',
+    ],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0 || value > maximum)
+        throw new RangeError(`${name} needs a finite value in 0..${maximum}.`)
+    },
+    interpolate: (a, b, t) => Math.max(0, Math.min(maximum, a + (b - a) * t)),
+    create,
+  })
+}
+function color(name: string, create: (target: object) => object) {
+  return registerNativeProperty<ColorValue>({
+    name: `jolt.scenekit/${name}`,
+    // Premultiply the sampled sRGB channels, so native linear interpolation also handles zero alpha.
+    units: [
+      'premultiplied sRGB red',
+      'premultiplied sRGB green',
+      'premultiplied sRGB blue',
+      'alpha',
+    ],
+    platforms: ['ios'],
+    encode(value) {
+      const argb = parseColor(value),
+        alpha = (argb >>> 24) / 255
+      return [
+        (((argb >>> 16) & 255) / 255) * alpha,
+        (((argb >>> 8) & 255) / 255) * alpha,
+        ((argb & 255) / 255) * alpha,
+        alpha,
+      ]
+    },
+    decode(values) {
+      const alpha = clamp(values[3]!)
+      const channel = (i: number) =>
+        Math.round(clamp(alpha ? values[i]! / alpha : 0) * 255)
+      return new Color(
+        ((Math.round(alpha * 255) << 24) |
+          (channel(0) << 16) |
+          (channel(1) << 8) |
+          channel(2)) >>>
+          0,
+      )
+    },
+    interpolate: (a, b, t) => new Color(colorMixer(parseColor(a), parseColor(b))(t)),
+    create,
+  })
+}
+
+/** SCNLight intensity, finite and nonnegative. Non-spatial: retains timing under reduced motion. */
+export const sceneKitLightIntensity: (light: SCNLight) => NativeProperty<number> = scalar(
+  'light-intensity',
+  Infinity,
+  (target) => JoltReferenceProperties.sceneLightIntensity(target as NSObject),
+)
+/** Solid UIColor/CGColor light color. Returns a normalized sRGB Color from get(). */
+export const sceneKitLightColor: (light: SCNLight) => NativeProperty<ColorValue> = color(
+  'light-color',
+  (target) => JoltReferenceProperties.sceneLightColor(target as NSObject),
+)
+/** SCNMaterial transparency in 0..1; does not change transparencyMode/transparent contents. */
+export const sceneKitMaterialTransparency: (
+  material: SCNMaterial,
+) => NativeProperty<number> = scalar('material-transparency', 1, (target) =>
+  JoltReferenceProperties.sceneMaterialTransparency(target as NSObject),
+)
+/** Solid color diffuse contents only; never converts a texture into a color. */
+export const sceneKitMaterialDiffuse: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-diffuse', (target) =>
+  JoltReferenceProperties.sceneMaterialDiffuse(target as NSObject),
+)
+/** Solid color emission contents only; does not make the material illuminate nearby geometry. */
+export const sceneKitMaterialEmission: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-emission', (target) =>
+  JoltReferenceProperties.sceneMaterialEmission(target as NSObject),
+)

package/src/sequence.ts

@@ -10,7 +10,12 @@ import {
   stopView,
   type Animation,
 } from './engine.js'
-import { createClock } from './playback.js'
+import { createClock, registerPlayback, playbackSource } from './playback.js'
+import {
+  isMotionValue,
+  type MotionValue,
+  type ValueAnimationOptions,
+} from './motion-value.js'
 import type { PresetName } from './presets.js'
 import { writeValue, type Property } from './properties.js'
 import type { SpringName } from './transition.js'
@@ -28,6 +33,34 @@ export type Step =
     ]
   | (() => Animation)
 
+/** A participant that can genuinely freeze and continue, rather than restart. */
+export interface PlayableAnimation extends Animation {
+  pause(): void
+  play(): void
+  readonly paused: boolean
+  readonly duration?: number
+}
+
+export type TimelineStep =
+  | Exclude<Step, () => Animation>
+  | readonly [
+      MotionValue,
+      number | readonly (number | null)[],
+      ((ValueAnimationOptions & { at?: SequencePosition }) | SpringName)?,
+    ]
+  | { readonly at?: SequencePosition; readonly run: () => PlayableAnimation }
+  | (() => PlayableAnimation)
+
+export interface TimelineAnimation extends PlayableAnimation {
+  /** Unknown until every step has activated and every participant reports a duration. */
+  readonly duration: number | undefined
+}
+
+/** Overlapping steps with a shared pause/resume control, including pending launches. */
+export function timeline(steps: readonly TimelineStep[]): TimelineAnimation {
+  return compose(steps, true) as TimelineAnimation
+}
+
 /**
  * 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.
@@ -44,26 +77,54 @@ export type Step =
  * ```
  */
 export function sequence(steps: readonly Step[]): Animation {
+  return compose(steps, false)
+}
+
+function compose(
+  steps: readonly TimelineStep[] | readonly Step[],
+  controlled: boolean,
+): Animation {
   const prepared = steps.map((step) => {
     if (typeof step === 'function') return { step, position: undefined }
-    const [target, animation, options] = step
+    if (!Array.isArray(step)) {
+      const descriptor = step as { at?: SequencePosition; run: () => PlayableAnimation }
+      if (typeof descriptor.run !== 'function')
+        throw new TypeError('A timeline step needs a run() factory.')
+      return { step: descriptor.run, position: parsePosition(descriptor.at) }
+    }
+    const [target, animation, options] = step as Exclude<
+      TimelineStep,
+      Function | { run: () => PlayableAnimation }
+    >
     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))
+  applyStartingValues(
+    prepared
+      .map(({ step }) => step as Step)
+      .filter((step) => typeof step === 'function' || !isMotionValue(step[0])),
+  )
 
   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 clock =
+    controlled || 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 paused = false
+  let settled = false
+  let completed = false
+  let changed = () => {}
+  const resumeChildren = new Set<PlayableAnimation>()
+  const waits = new Set<{ at: number; fire(): void; cancel(): void; schedule(): void }>()
+  const time = () => clock?.time() ?? 0
   let resolveScheduled!: () => void
   let rejectScheduled!: (reason: unknown) => void
   const scheduled = new Promise<void>((resolve, reject) => {
@@ -77,28 +138,55 @@ export function sequence(steps: readonly Step[]): Animation {
       position,
       onStart: new Set<() => void>(),
       animation: undefined as Animation | undefined,
+      start: undefined as number | undefined,
     }
   })
   const cancelSchedule = () => {
     for (const cancel of cancellations) cancel()
     cancellations.clear()
-    clock?.cancel()
+    for (const wait of waits) wait.cancel()
+    waits.clear()
+    if (!controlled || stopped || settled) clock?.cancel()
   }
   const fail = (error: unknown) => {
     if (stopped) return
     stopped = true
+    settled = true
     cancelSchedule()
     states.forEach((state) => state.onStart.clear())
     started.forEach((child) => child.stop())
+    changed()
     rejectScheduled(error)
   }
   const launch = (index: number) => {
     const state = states[index]!
     if (stopped || state.animation) return
+    if (paused) {
+      wait(0, () => launch(index))
+      return
+    }
     try {
       const step = state.step
-      const child = typeof step === 'function' ? step() : animate(...step)
+      const child =
+        typeof step === 'function'
+          ? step()
+          : (animate as (...args: any[]) => Animation)(...(step as any[]))
+      if (controlled && !isPlayable(child)) {
+        child?.stop?.()
+        throw new TypeError(
+          'A timeline participant must expose pause(), play() and paused; use sequence() for non-playable effects.',
+        )
+      }
       state.animation = child
+      state.start = time()
+      if (controlled) {
+        try {
+          const playback = playbackSource(child).read()
+          if (playback.ready) state.start = Math.max(0, time() - playback.time)
+        } catch {
+          /* A custom playable participant can omit a clock. */
+        }
+      }
       started.push(child)
       // Observe setup failures immediately, even while other steps are still
       // scheduled. Nested sequences can reject before this one reaches arrival.
@@ -110,25 +198,51 @@ export function sequence(steps: readonly Step[]): Animation {
         cancelSchedule()
         resolveScheduled()
       }
+      changed()
     } catch (error) {
       fail(error)
     }
   }
   const wait = (ms: number, callback: () => void) => {
     if (stopped) return
-    if (ms <= 0) {
-      callback()
+    if (!controlled) {
+      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)
       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)
+    let off = () => {}
+    const waiting = {
+      at: time() + Math.max(0, ms),
+      fire() {
+        off()
+        waits.delete(waiting)
+        if (!stopped) callback()
+      },
+      cancel() {
+        off()
+        off = () => {}
+      },
+      schedule() {
+        waiting.cancel()
+        if (paused || stopped) return
+        const remaining = waiting.at - time()
+        if (remaining <= 0) waiting.fire()
+        else off = driver.after(remaining, waiting.fire)
+      },
+    }
+    waits.add(waiting)
+    waiting.schedule()
   }
 
   for (let index = 0; index < states.length; index++) {
@@ -214,7 +328,11 @@ export function sequence(steps: readonly Step[]): Animation {
   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)
+    completed = !stopped && results.length === steps.length && results.every(Boolean)
+    settled = true
+    clock?.cancel()
+    changed()
+    return completed
   })
 
   const animation: Animation = {
@@ -222,13 +340,69 @@ export function sequence(steps: readonly Step[]): Animation {
     stop() {
       if (stopped) return
       stopped = true
+      settled = true
       cancelSchedule()
       states.forEach((state) => state.onStart.clear())
       resolveScheduled()
       started.forEach((animation) => animation.stop())
+      resumeChildren.clear()
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  if (controlled) {
+    const duration = () => {
+      if (pending) return undefined
+      let total = 0
+      for (const state of states) {
+        const child = state.animation as PlayableAnimation | undefined
+        if (!child || child.duration === undefined) return undefined
+        try {
+          if (!playbackSource(child).read().ready) return undefined
+        } catch {
+          /* custom playable */
+        }
+        total = Math.max(total, (state.start ?? 0) + child.duration)
+      }
+      return total
+    }
+    Object.defineProperties(animation, {
+      paused: { get: () => paused },
+      duration: { get: duration },
+    })
+    Object.assign(animation, {
+      pause() {
+        if (paused || settled) return
+        paused = true
+        clock?.pause()
+        for (const wait of waits) wait.cancel()
+        for (const child of started as PlayableAnimation[]) {
+          if (!child.paused) {
+            resumeChildren.add(child)
+            child.pause()
+          }
+        }
+        changed()
+      },
+      play() {
+        if (!paused || settled) return
+        paused = false
+        clock?.play()
+        for (const child of resumeChildren) child.play()
+        resumeChildren.clear()
+        for (const wait of [...waits]) wait.schedule()
+        changed()
+      },
+    })
+    changed = registerPlayback(animation, () => ({
+      time: time(),
+      duration: duration() ?? Infinity,
+      paused,
+      ready: duration() !== undefined,
+      settled,
+      completed,
+    }))
+  }
   setArrival(animation, arrived)
   return animation
 }
@@ -276,3 +450,18 @@ function applyStartingValues(steps: readonly Step[]) {
     }
   }
 }
+
+function isPlayable(animation: Animation): animation is PlayableAnimation {
+  const handle = animation as PlayableAnimation | undefined
+  return (
+    !!handle &&
+    typeof handle.pause === 'function' &&
+    typeof handle.play === 'function' &&
+    typeof handle.paused === 'boolean' &&
+    typeof handle.stop === 'function' &&
+    typeof handle.finished?.then === 'function' &&
+    typeof handle.finished?.catch === 'function' &&
+    (handle.duration === undefined ||
+      (typeof handle.duration === 'number' && handle.duration >= 0))
+  )
+}