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

package/src/particles.ts

@@ -0,0 +1,323 @@
+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 interface ConfettiOptions {
+  /** Approximate number of particles in the burst. Defaults to 80. */
+  count?: number
+  colors?: readonly string[]
+}
+
+export interface ParticleOptions {
+  colors?: readonly string[]
+  shape?: 'circle' | 'rectangle' | 'ring'
+  /** Center point, or a line across the top/bottom of the target. */
+  source?: 'center' | 'top' | 'bottom'
+  /** Total particles per second, shared across all colors. Defaults to 20. */
+  rate?: number
+  /** Particle lifetime in milliseconds. Defaults to 3000. */
+  lifetime?: number
+  /** Longest side in DIPs. Defaults to 6. */
+  size?: number
+  /** DIPs per second. Defaults to 60. */
+  velocity?: number
+  velocityRange?: number
+  /** Degrees clockwise from right: -90 is up, 90 is down. Defaults to -90. */
+  angle?: number
+  /** Emission cone in degrees, from 0 to 360. Defaults to 30. */
+  spread?: number
+  /** Downward acceleration in DIPs per second squared. Defaults to 0. */
+  gravity?: number
+  /** Degrees per second. Defaults to 0. */
+  spin?: number
+  spinRange?: number
+  /** Fade each particle over its lifetime. Defaults to true. */
+  fadeOut?: boolean
+  /** Emit for this many milliseconds, then let particles expire. Omit to keep emitting. */
+  duration?: number
+}
+
+type Settings = Required<Omit<ParticleOptions, 'duration'>> & { duration?: number }
+const bursts = new WeakMap<View, () => void>()
+const emitters = new WeakMap<View, () => void>()
+const palette = ['#facc15', '#ef4444', '#3b82f6', '#22c55e', '#a855f7']
+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. */
+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.')
+  const settings = resolve(
+    {
+      colors: options.colors ?? palette,
+      shape: 'rectangle',
+      rate: count / (BURST_DURATION / 1000),
+      duration: BURST_DURATION,
+      lifetime: 2200,
+      size: 8,
+      velocity: 260,
+      velocityRange: 100,
+      angle: -90,
+      spread: 100,
+      gravity: 420,
+      spinRange: 360,
+    },
+    true,
+  )
+  return start(target, settings, true)
+}
+
+/** Adds a native particle emitter to the target. iOS only; returns immediate cleanup. */
+export function particles(target: Target, options: ParticleOptions = {}): () => void {
+  return start(target, resolve(options), false)
+}
+
+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 () => {}
+  return new Emitter(view, settings, overlay, running).stop
+}
+
+function resolve(options: ParticleOptions, burst = false): Settings {
+  const colors = options.colors ?? ['#ffffff']
+  if (
+    !Array.isArray(colors) ||
+    colors.length === 0 ||
+    colors.length > 32 ||
+    Array.from(colors).some((color) => typeof color !== 'string' || !Color.isValid(color))
+  )
+    throw new TypeError('Particles need 1 to 32 valid color strings.')
+  const shape = options.shape ?? 'circle'
+  const source = options.source ?? 'center'
+  if (!['circle', 'rectangle', 'ring'].includes(shape))
+    throw new TypeError('Unknown particle shape.')
+  if (!['center', 'top', 'bottom'].includes(source))
+    throw new TypeError('Unknown particle source.')
+  const lifetime = number('lifetime', options.lifetime ?? 3000, 1, 60000)
+  const rate = number('rate', options.rate ?? 20, 0, burst ? 50000 : 10000)
+  if (!burst && (rate * lifetime) / 1000 > 10000)
+    throw new RangeError('Particle rate × lifetime must not exceed 10000 live particles.')
+  const duration =
+    options.duration === undefined
+      ? undefined
+      : number('duration', options.duration, 1, 2147483647 - lifetime - 50)
+  const fadeOut = options.fadeOut ?? true
+  if (typeof fadeOut !== 'boolean')
+    throw new TypeError('Particle fadeOut must be a boolean.')
+  return {
+    colors: [...colors],
+    shape,
+    source,
+    lifetime,
+    rate,
+    duration,
+    fadeOut,
+    size: number('size', options.size ?? 6, 1, 128),
+    velocity: number('velocity', options.velocity ?? 60, 0, 10000),
+    velocityRange: number('velocityRange', options.velocityRange ?? 0, 0, 10000),
+    angle: number('angle', options.angle ?? -90, -360, 360),
+    spread: number('spread', options.spread ?? 30, 0, 360),
+    gravity: number('gravity', options.gravity ?? 0, -10000, 10000),
+    spin: number('spin', options.spin ?? 0, -3600, 3600),
+    spinRange: number('spinRange', options.spinRange ?? 0, 0, 3600),
+  }
+}
+
+function number(name: string, value: number, min: number, max: number): number {
+  if (!Number.isFinite(value) || value < min || value > max)
+    throw new RangeError(`Particle ${name} must be between ${min} and ${max}.`)
+  return value
+}
+
+class Emitter {
+  private stopped = false
+  private queued = false
+  private layer: CAEmitterLayer | undefined
+  private native: UIView | undefined
+  private window: UIWindow | undefined
+  private timer: ReturnType<typeof setTimeout> | undefined
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: View,
+    private readonly settings: Settings,
+    private readonly overlay: boolean,
+    private readonly running: WeakMap<View, () => void>,
+  ) {
+    running.set(view, this.stop)
+    view.on('loaded', this.schedule)
+    view.on('layoutChanged', this.schedule)
+    view.on('unloaded', this.stop)
+    this.schedule()
+  }
+
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    this.view.off('loaded', this.schedule)
+    this.view.off('layoutChanged', this.schedule)
+    this.view.off('unloaded', 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.layer?.removeAllAnimations()
+    this.layer?.removeFromSuperlayer()
+    this.layer = this.native = this.window = undefined
+    this.timer = this.observer = undefined
+  }
+
+  private schedule = () => {
+    if (this.stopped || this.queued) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.stopped) return
+      try {
+        this.update()
+      } catch (error) {
+        this.stop()
+        throw error
+      }
+    })
+  }
+
+  private motionChanged = () => {
+    if (reducedMotion()) this.stop()
+  }
+
+  private update() {
+    if (!this.view.isLoaded) return
+    if (reducedMotion()) return this.stop()
+    const native = this.view.nativeViewProtected as UIView | undefined
+    const window = native?.window
+    if (this.layer && (!native || !window)) return this.stop()
+    if (!native || !window) return
+    if (this.native && (this.native !== native || this.window !== window))
+      return this.stop()
+    const bounds = native.layer.bounds
+    if (bounds.size.width <= 0 || bounds.size.height <= 0) {
+      if (this.layer) this.stop()
+      return
+    }
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      if (!this.layer) {
+        this.native = native
+        this.window = window
+        const host = this.overlay ? window.layer : native.layer
+        const layer = (this.layer = CAEmitterLayer.new())
+        layer.name = this.overlay ? 'jolt:confetti' : 'jolt:particles'
+        layer.frame = host.bounds
+        layer.emitterShape =
+          this.settings.source === 'center' ? kCAEmitterLayerPoint : kCAEmitterLayerLine
+        layer.emitterCells = NSArray.arrayWithArray(this.cells())
+        host.addSublayer(layer)
+        // Start from an empty emitter, even if its parent has been alive for hours.
+        layer.beginTime = host.convertTimeFromLayer(CACurrentMediaTime(), null)
+        if (this.overlay)
+          layer.emitterPosition = native.convertPointToView(
+            CGPointMake(
+              bounds.origin.x + bounds.size.width / 2,
+              bounds.origin.y + bounds.size.height / 2,
+            ),
+            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.
+          layer.birthRate = 0
+          const emission = CABasicAnimation.animationWithKeyPath('birthRate')
+          emission.fromValue = 1
+          emission.toValue = 1
+          emission.duration = this.settings.duration / 1000
+          layer.addAnimationForKey(emission, 'jolt:emission')
+          this.timer = setTimeout(
+            this.stop,
+            this.settings.duration + this.settings.lifetime + 50,
+          )
+        }
+      }
+      if (!this.overlay) {
+        const layer = this.layer
+        layer.frame = bounds
+        layer.emitterSize = CGSizeMake(bounds.size.width, 0)
+        layer.emitterPosition = CGPointMake(
+          bounds.size.width / 2,
+          this.settings.source === 'top'
+            ? 0
+            : this.settings.source === 'bottom'
+              ? bounds.size.height
+              : bounds.size.height / 2,
+        )
+      }
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private cells(): CAEmitterCell[] {
+    const options = this.settings
+    const image = texture(options.shape)
+    return options.colors.map((color) => {
+      const cell = CAEmitterCell.emitterCell()
+      cell.contents = image.CGImage
+      cell.color = new Color(color).ios.CGColor
+      cell.birthRate = options.rate / options.colors.length
+      cell.lifetime = options.lifetime / 1000
+      cell.scale = options.size / 32
+      cell.velocity = options.velocity
+      cell.velocityRange = options.velocityRange
+      // Horizontal line emitters point upward at longitude zero; point
+      // emitters point right. Keep the public angle in view coordinates.
+      cell.emissionLongitude = radians(
+        options.angle + (options.source === 'center' ? 0 : 90),
+      )
+      cell.emissionRange = radians(options.spread)
+      cell.yAcceleration = options.gravity
+      cell.spin = radians(options.spin)
+      cell.spinRange = radians(options.spinRange)
+      cell.alphaSpeed = options.fadeOut ? -1 / cell.lifetime : 0
+      return cell
+    })
+  }
+}
+
+function texture(shape: Settings['shape']): UIImage {
+  const cached = textures.get(shape)
+  if (cached) return cached
+  const format = UIGraphicsImageRendererFormat.defaultFormat()
+  format.scale = 1
+  format.opaque = false
+  const height = shape === 'rectangle' ? 18 : 32
+  const renderer = UIGraphicsImageRenderer.alloc().initWithSizeFormat(
+    CGSizeMake(32, height),
+    format,
+  )
+  const image = renderer.imageWithActions((context) => {
+    const cg = context.CGContext
+    CGContextSetFillColorWithColor(cg, UIColor.whiteColor.CGColor)
+    if (shape === 'rectangle') CGContextFillRect(cg, CGRectMake(0, 0, 32, height))
+    else if (shape === 'circle') CGContextFillEllipseInRect(cg, CGRectMake(0, 0, 32, 32))
+    else {
+      CGContextSetStrokeColorWithColor(cg, UIColor.whiteColor.CGColor)
+      CGContextSetLineWidth(cg, 3)
+      CGContextStrokeEllipseInRect(cg, CGRectMake(2, 2, 28, 28))
+    }
+  })
+  textures.set(shape, image)
+  return image
+}

package/src/path.ts

@@ -0,0 +1,124 @@
+import { parsePath, type MotionPath } from './svg-path.js'
+import { reducedMotion, timeScale } from './config.js'
+import { createTrack, instantTrack, type Track } from './track.js'
+import {
+  mergeTransitions,
+  resolveTransition,
+  type Transition,
+  type ResolvedTransition,
+} from './transition.js'
+import type { Keyframes, KeyframeProperty } from './types.js'
+
+export type PathProperty = 'x' | 'y' | 'rotate'
+export interface PreparedPath {
+  readonly properties: readonly PathProperty[]
+  readonly starts: ReadonlyMap<PathProperty, number>
+  readonly transition: ResolvedTransition
+  track(property: PathProperty, offset: number, delay: number): Track
+}
+
+export function preparePath(
+  keyframes: Keyframes,
+  base: Transition,
+  overrides: Partial<Record<KeyframeProperty | 'path', Transition>>,
+): PreparedPath | undefined {
+  if (keyframes.orient !== undefined && typeof keyframes.orient !== 'boolean')
+    throw new TypeError('Path orient must be a boolean.')
+  if (keyframes.path === undefined) {
+    if (keyframes.orient !== undefined) throw new TypeError('orient requires a path.')
+    return undefined
+  }
+  if (keyframes.x !== undefined || keyframes.y !== undefined)
+    throw new TypeError('A path owns x and y; omit explicit x/y keyframes.')
+  if (keyframes.orient && keyframes.rotate !== undefined)
+    throw new TypeError('An oriented path owns rotate; omit explicit rotate keyframes.')
+  if (overrides.x || overrides.y || (keyframes.orient && overrides.rotate))
+    throw new TypeError('Use the path transition to time its coordinates together.')
+  const geometry = parsePath(keyframes.path)
+  const orient = keyframes.orient === true
+  const transition = resolveTransition(
+    overrides.path ? mergeTransitions(base, overrides.path) : base,
+    'opacity',
+    2,
+  )
+  if (
+    !Number.isFinite(transition.curve.type === 'tween' ? transition.curve.duration : 0) ||
+    !Number.isFinite(transition.delay)
+  )
+    throw new RangeError('Path duration and delay must be finite.')
+  const properties: readonly PathProperty[] = orient ? ['x', 'y', 'rotate'] : ['x', 'y']
+  const first = geometry.at(0)
+  let motion: ReturnType<typeof sample> | undefined
+  return {
+    properties,
+    starts: new Map(properties.map((property) => [property, first[property]])),
+    transition,
+    track(property, offset, requested) {
+      motion ??= sample(geometry, transition, orient)
+      const { progress, times, frames } = motion
+      const to = geometry.at(progress.to)[property] + offset
+      if (reducedMotion()) return instantTrack(property, to)
+      const delay = requested / timeScale()
+      const shift = delay - progress.delay
+      const pose = (time: number) =>
+        geometry.at(progress.valueAt(time - shift))[property] + offset
+      return {
+        ...progress,
+        property,
+        delay,
+        end: progress.end + shift,
+        arrival: progress.arrival + shift,
+        times,
+        values: offset
+          ? frames[property].map((value) => value + offset)
+          : frames[property],
+        to,
+        valueAt: pose,
+        velocityAt(time) {
+          if (time <= delay || time >= progress.end + shift) return 0
+          const position = progress.valueAt(time - shift)
+          if (position < 0 || position > 1) return 0
+          const epsilon = Math.min(1e-5, 0.01 / Math.max(1, geometry.length))
+          const a = Math.max(0, position - epsilon),
+            b = Math.min(1, position + epsilon)
+          return (
+            ((geometry.at(b)[property] - geometry.at(a)[property]) / (b - a)) *
+            progress.velocityAt(time - shift)
+          )
+        },
+      }
+    },
+  }
+}
+
+/** Sample scalar timing once, then project all coordinates through the same path. */
+function sample(geometry: MotionPath, transition: ResolvedTransition, orient: boolean) {
+  const progress = createTrack('opacity', [0, 1], transition, 0)
+  const count = Math.max(
+    1,
+    Math.min(
+      6000,
+      Math.max(
+        Math.ceil((progress.duration / 1000) * 60),
+        Math.ceil(geometry.length / 2),
+      ),
+    ),
+  )
+  const times = Array.from({ length: count + 1 }, (_, i) => i / count)
+  const frames: Record<PathProperty, number[]> = { x: [], y: [], rotate: [] }
+  for (const time of times) {
+    const position =
+      time === 0
+        ? 0
+        : time === 1
+          ? 1
+          : progress.valueAt(progress.delay + time * progress.duration)
+    if (!Number.isFinite(position))
+      throw new RangeError('Path easing must return finite progress.')
+    const pose = geometry.at(position)
+    frames.x.push(pose.x)
+    frames.y.push(pose.y)
+    if (orient) frames.rotate.push(pose.rotate)
+  }
+  return { progress, times, frames }
+}

package/src/playback-group.ts

@@ -0,0 +1,143 @@
+import {
+  arrivalOf,
+  arrivalTimingOf,
+  setArrival,
+  setArrivalTiming,
+  type ViewAnimation,
+} from './engine.js'
+import { getDriver } from './driver/index.js'
+import { createClock, type PlaybackClock } from './playback.js'
+import { validateProgress, type PlaybackAnimation } from './playback.js'
+
+/** Staggered views share a finite time range. Shorter children remain seekable
+ * until the whole group settles, unless another animation has taken ownership. */
+export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnimation {
+  let paused = false
+  let settled = false
+  let finalProgress: number | undefined
+  let clock: PlaybackClock | undefined
+  let pendingProgress: number | undefined
+  const duration = () => Math.max(0, ...children.map((child) => child.duration))
+  const ensureClock = () => {
+    if (clock || settled || children.some((child) => !child.ready)) return
+    const driver = getDriver()
+    clock = driver.clock?.(duration()) ?? createClock(() => driver.now())
+    clock.seek(Math.max(0, ...children.map((child) => child.currentTime)))
+    if (paused) clock.pause()
+  }
+  const finishIfIdle = () => {
+    if (settled || paused || children.some((child) => !child.idle || child.paused)) return
+    settled = true
+    clock?.cancel()
+    for (const child of children) child.releaseGroup()
+  }
+  const seek = (value: number) => {
+    const total = duration()
+    validateProgress(value, total)
+    if (settled) return
+    if (children.some((child) => !child.ready)) {
+      pendingProgress = value
+      return
+    }
+    pendingProgress = undefined
+    ensureClock()
+    clock?.seek(total * value)
+    for (const child of children) child.seekTime(total * value)
+    finishIfIdle()
+  }
+  for (const child of children) {
+    child.onIdle(finishIfIdle)
+    child.onReady(() => {
+      ensureClock()
+      if (pendingProgress !== undefined && children.every((child) => child.ready))
+        seek(pendingProgress)
+      finishIfIdle()
+    })
+  }
+  const finished = Promise.all(children.map((child) => child.finished)).then(
+    (results) => {
+      finalProgress ??= results.every(Boolean)
+        ? 1
+        : duration()
+          ? Math.min(1, (clock?.time() ?? 0) / duration())
+          : 0
+      settled = true
+      clock?.cancel()
+      return results.every(Boolean)
+    },
+  )
+  const animation: PlaybackAnimation = {
+    finished,
+    get duration() {
+      return duration()
+    },
+    get paused() {
+      return paused
+    },
+    get progress() {
+      if (!Number.isFinite(duration()))
+        throw new RangeError('Progress requires a finite animation.')
+      if (pendingProgress !== undefined) return pendingProgress
+      return (
+        finalProgress ??
+        (settled ? 1 : duration() ? Math.min(1, (clock?.time() ?? 0) / duration()) : 0)
+      )
+    },
+    set progress(value) {
+      seek(value)
+    },
+    pause() {
+      if (!settled && !paused) {
+        paused = true
+        clock?.pause()
+        children.forEach((child) => child.pause())
+      }
+    },
+    play() {
+      if (!settled && paused) {
+        paused = false
+        clock?.play()
+        children.forEach((child) => child.play())
+        finishIfIdle()
+      }
+    },
+    stop() {
+      finalProgress = duration() ? Math.min(1, (clock?.time() ?? 0) / duration()) : 0
+      settled = true
+      clock?.cancel()
+      children.forEach((child) => child.stop())
+    },
+    then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
+  }
+  setArrival(animation, Promise.all(children.map(arrivalOf)))
+  const listeners = new Set<() => void>()
+  const timings = children.map((child) => arrivalTimingOf(child)!)
+  const notify = () => {
+    for (const callback of [...listeners]) callback()
+  }
+  const unsubscribe = timings.map((timing) => timing.subscribe(notify))
+  setArrivalTiming(animation, {
+    read() {
+      const states = timings.map((timing) => timing.read())
+      return {
+        arrived: settled || states.every((state) => state.arrived),
+        paused: paused || states.some((state) => state.paused && !state.arrived),
+        remaining: states.some((state) => !state.arrived && state.remaining === undefined)
+          ? undefined
+          : Math.max(0, ...states.map((state) => (state.arrived ? 0 : state.remaining!))),
+      }
+    },
+    subscribe(callback) {
+      listeners.add(callback)
+      return () => listeners.delete(callback)
+    },
+  })
+  void finished.then(() => {
+    unsubscribe.forEach((off) => off())
+    notify()
+    listeners.clear()
+  })
+  ensureClock()
+  finishIfIdle()
+  return animation
+}

package/src/playback.ts

@@ -0,0 +1,62 @@
+import type { Animation } from './engine.js'
+
+/** Controls returned by animate() and decay(). Effects expose the base Animation. */
+export interface PlaybackAnimation extends Animation {
+  /** Pauses only the properties owned by this animation. */
+  pause(): void
+  /** Continues from the current position. Completed/stopped animations remain terminal. */
+  play(): void
+  readonly paused: boolean
+  /** Total milliseconds, including delays and repeats. Infinity for endless loops. */
+  readonly duration: number
+  /** Finite timeline position, from 0 to 1. Seeking preserves the playing/paused state. */
+  progress: number
+}
+
+export type PlaybackCommand = 'pause' | 'play' | 'seek'
+
+export interface PlaybackClock {
+  time(): number
+  pause(): void
+  play(): void
+  seek(ms: number): void
+  cancel(): void
+}
+
+/** Read only on user commands; there is no frame loop in JavaScript. */
+export function createClock(now: () => number, initial = 0): PlaybackClock {
+  let offset = initial
+  let anchor = now()
+  let paused = false
+  const time = () => offset + (paused ? 0 : now() - anchor)
+  return {
+    time,
+    pause() {
+      offset = time()
+      paused = true
+    },
+    play() {
+      if (paused) {
+        anchor = now()
+        paused = false
+      }
+    },
+    seek(ms) {
+      offset = ms
+      anchor = now()
+    },
+    cancel() {
+      offset = time()
+      paused = true
+    },
+  }
+}
+
+export function validateProgress(value: number, duration: number) {
+  if (!Number.isFinite(value) || value < 0 || value > 1)
+    throw new RangeError('Animation progress must be between 0 and 1.')
+  if (!Number.isFinite(duration))
+    throw new RangeError(
+      'Progress requires a finite animation; endless loops can pause and play.',
+    )
+}