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

package/src/haptics.ts

@@ -0,0 +1,125 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { Driver } from './driver/index.js'
+import type { Track } from './track.js'
+
+export type HapticStyle = 'light' | 'medium' | 'heavy'
+
+export interface HapticOptions {
+  style: HapticStyle
+  /** Points from 0 to 1 over the finite animation, excluding its initial delay. Defaults to arrival. */
+  times?: readonly number[]
+}
+
+export type Haptic = HapticStyle | HapticOptions | false
+
+/** Validate before any running animation is interrupted. */
+export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undefined {
+  if (haptic === undefined || haptic === false) return undefined
+  const options = typeof haptic === 'string' ? { style: haptic } : haptic
+  if (!options || !['light', 'medium', 'heavy'].includes(options.style))
+    throw new TypeError('Haptic style must be light, medium or heavy.')
+  const times = options.times
+  if (
+    times !== undefined &&
+    (!Array.isArray(times) ||
+      times.length === 0 ||
+      Array.from(times).some(
+        (time, i) =>
+          !Number.isFinite(time) ||
+          time <= 0 ||
+          time > 1 ||
+          (i > 0 && time <= times[i - 1]!),
+      ))
+  )
+    throw new RangeError(
+      'Haptic times must be increasing points greater than 0 and at most 1.',
+    )
+  return { style: options.style, times: times && [...times] }
+}
+
+const PREPARE_AHEAD = 100
+const MAX_LATENESS = 100
+const COMPLETION_TOLERANCE = 20
+
+/** Discrete feedback only: animation playback remains entirely native. */
+export function playHaptics(
+  view: View,
+  tracks: readonly Track[],
+  options: HapticOptions | undefined,
+  driver: Driver,
+  startedAt: number,
+) {
+  if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
+  const moving = tracks.filter(
+    (track) =>
+      track.duration > 0 && track.values.some((value) => value !== track.values[0]),
+  )
+  if (!moving.length) return
+  const end = Math.max(...tracks.map((track) => track.end))
+  if (!Number.isFinite(end)) return
+  const delay = Math.min(...moving.map((track) => track.delay))
+  const offsets = options.times
+    ? options.times.map((time) => delay + (end - delay) * time)
+    : [Math.max(...tracks.map((track) => track.arrival))]
+  const styles = {
+    light: 0,
+    medium: 1,
+    heavy: 2,
+  } satisfies Record<HapticStyle, UIImpactFeedbackStyle>
+  let generator: UIImpactFeedbackGenerator | undefined =
+    UIImpactFeedbackGenerator.alloc().initWithStyle(styles[options.style])
+  const native = view.nativeViewProtected as UIView
+  let next = 0
+  let cancelPrepare: (() => void) | undefined
+  let cancelImpact: (() => void) | undefined
+
+  const active = () =>
+    view.isLoaded &&
+    view.nativeViewProtected === native &&
+    !!native.window &&
+    UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
+
+  const cancel = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+    generator = undefined
+    view.off('unloaded', cancel)
+  }
+
+  const fire = (tolerance = 0) => {
+    const elapsed = driver.now() - startedAt
+    // A busy UI thread can delay timers. Drop stale impacts instead of replaying
+    // several old taps at once when it becomes responsive again.
+    while (next < offsets.length && offsets[next]! <= elapsed + tolerance) {
+      const offset = offsets[next++]!
+      if (active() && elapsed - offset <= MAX_LATENESS) generator?.impactOccurred()
+    }
+  }
+
+  const schedule = () => {
+    if (!generator || next === offsets.length) return cancel()
+    const remaining = startedAt + offsets[next]! - driver.now()
+    if (active()) generator.prepare()
+    if (remaining > PREPARE_AHEAD) {
+      cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
+        if (active()) generator?.prepare()
+      })
+    }
+    cancelImpact = driver.after(Math.max(0, remaining), () => {
+      fire()
+      schedule()
+    })
+  }
+
+  view.on('unloaded', cancel)
+  schedule()
+  return {
+    cancel,
+    finish() {
+      // Native completion may beat the timer at the final keyframe by a frame.
+      fire(COMPLETION_TOLERANCE)
+      cancel()
+    },
+  }
+}

package/src/index.ts

@@ -2,8 +2,19 @@ export { animate, stop } from './animate.js'
 export { sequence } from './sequence.js'
 export type { Step } from './sequence.js'
 export { press } from './press.js'
-export { presets } from './presets.js'
-export type { PresetName } from './presets.js'
+export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
+export { confetti, particles } from './particles.js'
+export type { ConfettiOptions, ParticleOptions } from './particles.js'
+export { shimmer } from './shimmer.js'
+export type { ShimmerOptions } from './shimmer.js'
+export { symbolEffect } from './symbol-effect.js'
+export type {
+  SymbolEffect,
+  SymbolEffectName,
+  SymbolEffectOptions,
+} from './symbol-effect.js'
+export { definePreset, presets } from './presets.js'
+export type { Preset, PresetName, Presets } from './presets.js'
 export { springs } from './transition.js'
 export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
 export { cubicBezier } from './easing.js'

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'
+
+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 || UIAccessibilityIsReduceMotionEnabled())
+    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 (UIAccessibilityIsReduceMotionEnabled()) this.stop()
+  }
+
+  private update() {
+    if (!this.view.isLoaded) return
+    if (UIAccessibilityIsReduceMotionEnabled()) 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/presets.ts

@@ -5,6 +5,9 @@ export interface Preset {
   transition: AnimateOptions
 }
 
+/** Add custom preset names through module augmentation, with `true` as each value. */
+export interface Presets {}
+
 const fadeIn = { duration: 300, ease: 'easeOut' } as const
 const fadeOut = { duration: 200, ease: 'easeIn' } as const
 const enter = { type: 'spring', duration: 500, bounce: 0 } as const
@@ -77,28 +80,30 @@ export const presets = {
 
   pulse: {
     keyframes: { scale: [1, 1.06, 1] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   bounce: {
     keyframes: { y: [0, -18, 0, -8, 0] },
     transition: {
       duration: 650,
+      relative: true,
       times: [0, 0.3, 0.6, 0.8, 1],
       ease: ['easeOut', 'easeIn', 'easeOut', 'easeIn'],
     },
   },
   shake: {
     keyframes: { x: [0, -10, 10, -8, 8, -4, 4, 0] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   wiggle: {
     keyframes: { rotate: [0, -8, 8, -5, 5, 0] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   heartbeat: {
     keyframes: { scale: [1, 1.15, 1, 1.15, 1, 1] },
     transition: {
       duration: 1000,
+      relative: true,
       times: [0, 0.14, 0.28, 0.42, 0.7, 1],
       ease: 'easeInOut',
     },
@@ -110,25 +115,44 @@ export const presets = {
     },
     transition: {
       duration: 800,
+      relative: true,
       times: [0, 0.3, 0.4, 0.5, 0.65, 0.75, 1],
       ease: 'easeInOut',
     },
   },
   flash: {
     keyframes: { opacity: [1, 0, 1, 0, 1] },
-    transition: { duration: 800, ease: 'easeInOut' },
+    transition: { duration: 800, ease: 'easeInOut', relative: true },
   },
   tada: {
     keyframes: {
       scale: [1, 0.9, 0.9, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1],
       rotate: [0, -3, -3, 3, -3, 3, -3, 3, -3, 3, 0],
     },
-    transition: { duration: 1000, ease: 'easeInOut' },
+    transition: { duration: 1000, ease: 'easeInOut', relative: true },
   },
   spin: {
     keyframes: { rotate: [0, 360] },
-    transition: { duration: 1000, ease: 'linear' },
+    transition: { duration: 1000, ease: 'linear', relative: true },
   },
 } satisfies Record<string, Preset>
 
-export type PresetName = keyof typeof presets
+export type PresetName = keyof typeof presets | Extract<keyof Presets, string>
+
+const customPresets = new Map<string, Preset>()
+
+/** Registers a custom preset. Registering it again replaces it for future animations. */
+export function definePreset(name: PresetName, preset: Preset): void {
+  if (Object.hasOwn(presets, name)) {
+    throw new Error(`Preset "${name}" is built in and cannot be replaced.`)
+  }
+  customPresets.set(name, preset)
+}
+
+export function getPreset(name: PresetName): Preset {
+  const preset =
+    customPresets.get(name) ??
+    (Object.hasOwn(presets, name) ? presets[name as keyof typeof presets] : undefined)
+  if (!preset) throw new Error(`Unknown preset "${name}".`)
+  return preset
+}

package/src/press.ts

@@ -33,7 +33,13 @@ export function press(
       rest = Object.fromEntries(properties.map((p) => [p, readValue(view, p)]))
       animate(view, pressed, options ?? pressIn)
     } else if ((action === 'up' || action === 'cancel') && rest) {
-      animate(view, rest, options ?? release)
+      animate(
+        view,
+        rest,
+        typeof options === 'object'
+          ? { ...options, relative: false }
+          : (options ?? release),
+      )
       rest = undefined
     }
   }

package/src/sequence.ts

@@ -17,8 +17,9 @@ export type Step =
 /**
  * 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.
- * Views in later steps take their first keyframe right away, so a title that
- * fades in third doesn't show up before its turn.
+ * 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.
  *
  * ```ts
  * await sequence([
@@ -64,14 +65,16 @@ function applyStartingValues(steps: readonly Step[]) {
   const claimed = new Map<View, Set<Property>>()
   for (const step of steps) {
     if (typeof step === 'function') continue
-    const [target, animation] = step
-    const starts = startingValues(animation)
+    const [target, animation, options] = step
+    const starts = startingValues(animation, options)
 
     for (const view of toViews(target)) {
       let properties = claimed.get(view)
       if (!properties) claimed.set(view, (properties = new Set()))
 
-      const fresh = [...starts].filter(([property]) => !properties.has(property))
+      const fresh = [...starts].filter(
+        ([property, value]) => !properties.has(property) && value !== null,
+      )
       stopView(
         view,
         fresh.map(([property]) => property),