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

package/src/loader.ts

@@ -0,0 +1,201 @@
+import { Application, Color, isIOS, type View } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Target } from './types.js'
+
+export type LoaderStyle = 'dots' | 'bars' | 'ring'
+
+export interface LoaderOptions {
+  /** Defaults to 'dots'. */
+  style?: LoaderStyle
+  /** A NativeScript color string. Defaults to '#71717a'. */
+  color?: string
+  /** Maximum width and height in DIPs, fitted inside the target. Defaults to 48. */
+  size?: number
+  /** Milliseconds per cycle. Defaults to 1200. */
+  duration?: number
+}
+
+const running = new WeakMap<View, () => void>()
+const key = 'jolt:loader'
+
+/**
+ * Adds a centered native iOS loading indicator. Returns an idempotent cleanup.
+ * Unloading releases native resources; loading resumes until explicitly stopped.
+ * Reduce Motion keeps the indicator static. Android is a no-op.
+ */
+export function loader(target: Target, options: LoaderOptions = {}): () => void {
+  const settings: Required<LoaderOptions> = {
+    style: options.style ?? 'dots',
+    color: options.color ?? '#71717a',
+    size: options.size ?? 48,
+    duration: options.duration ?? 1200,
+  }
+  if (!['dots', 'bars', 'ring'].includes(settings.style))
+    throw new TypeError('Unknown loader style.')
+  if (typeof settings.color !== 'string' || !Color.isValid(settings.color))
+    throw new TypeError('Loader color must be a valid color string.')
+  for (const name of ['size', 'duration'] as const)
+    if (!Number.isFinite(settings[name]) || settings[name] <= 0)
+      throw new RangeError(`Loader ${name} must be a positive finite number.`)
+  const view = toView(target)
+  running.get(view)?.()
+  if (!isIOS) return () => {}
+  return new Loader(view, settings).stop
+}
+
+class Loader {
+  private stopped = false
+  private queued = false
+  private waitingForLoad: boolean
+  private native: UIView | undefined
+  private layer: CAReplicatorLayer | undefined
+  private item: CALayer | undefined
+  private animating = false
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: View,
+    private readonly settings: Required<LoaderOptions>,
+  ) {
+    this.waitingForLoad = !view.isLoaded
+    running.set(view, this.stop)
+    view.on('loaded', this.loaded)
+    view.on('layoutChanged', this.schedule)
+    view.on('unloaded', this.unloaded)
+    this.schedule()
+  }
+
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    this.view.off('loaded', this.loaded)
+    this.view.off('layoutChanged', this.schedule)
+    this.view.off('unloaded', this.unloaded)
+    if (running.get(this.view) === this.stop) running.delete(this.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
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.stopped) return
+      try {
+        this.update()
+      } catch (error) {
+        this.stop()
+        throw error
+      }
+    })
+  }
+
+  private update() {
+    if (this.waitingForLoad || !this.view.isLoaded) return
+    const native = this.view.nativeViewProtected as UIView | undefined
+    if (!native?.window) return this.remove()
+    const bounds = native.layer.bounds
+    const size = Math.min(this.settings.size, bounds.size.width, bounds.size.height)
+    if (size <= 0) return this.remove()
+    if (this.native && this.native !== native) this.remove()
+    this.observer ??= Application.ios.addNotificationObserver(
+      UIAccessibilityReduceMotionStatusDidChangeNotification,
+      this.schedule,
+    )
+
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      if (!this.layer) {
+        this.native = native
+        this.layer = CAReplicatorLayer.new()
+        this.layer.name = key
+        this.item = CALayer.new()
+        this.item.backgroundColor = new Color(this.settings.color).ios.CGColor
+        this.layer.addSublayer(this.item)
+        native.layer.addSublayer(this.layer)
+      }
+      const layer = this.layer
+      const item = this.item!
+      const { style, duration } = this.settings
+      layer.bounds = CGRectMake(0, 0, size, size)
+      layer.position = CGPointMake(
+        bounds.origin.x + bounds.size.width / 2,
+        bounds.origin.y + bounds.size.height / 2,
+      )
+      layer.instanceCount = style === 'dots' ? 3 : style === 'bars' ? 5 : 12
+      layer.instanceDelay = duration / 1000 / (style === 'ring' ? 12 : 5)
+      if (style === 'ring') {
+        const diameter = size * 0.16
+        item.bounds = CGRectMake(0, 0, diameter, diameter)
+        item.position = CGPointMake(size / 2, diameter / 2)
+        item.cornerRadius = diameter / 2
+        layer.instanceTransform = CATransform3DMakeRotation((2 * Math.PI) / 12, 0, 0, 1)
+      } else {
+        const width = size * (style === 'dots' ? 0.2 : 0.12)
+        const height = style === 'dots' ? width : size * 0.75
+        item.bounds = CGRectMake(0, 0, width, height)
+        item.position = CGPointMake(width / 2, size / 2)
+        item.cornerRadius = width / 2
+        layer.instanceTransform = CATransform3DMakeTranslation(
+          (size - width) / (layer.instanceCount - 1),
+          0,
+          0,
+        )
+      }
+      const reduced = UIAccessibilityIsReduceMotionEnabled()
+      item.opacity = style === 'ring' ? 0.35 : 1
+      if (reduced && this.animating) {
+        item.removeAnimationForKey(key)
+        this.animating = false
+      } else if (!reduced && !this.animating) {
+        const animation = CAKeyframeAnimation.animationWithKeyPath(
+          style === 'ring'
+            ? 'opacity'
+            : style === 'bars'
+              ? 'transform.scale.y'
+              : 'transform.scale',
+        )
+        animation.values = NSArray.arrayWithArray(
+          style === 'ring' ? [1, 0.2] : [0.35, 1, 0.35, 0.35],
+        )
+        animation.keyTimes = NSArray.arrayWithArray(
+          style === 'ring' ? [0, 1] : [0, 0.3, 0.6, 1],
+        )
+        animation.duration = duration / 1000
+        animation.repeatCount = Infinity
+        // Start one cycle in so every delayed copy is already participating.
+        animation.beginTime =
+          item.convertTimeFromLayer(CACurrentMediaTime(), null) - animation.duration
+        item.addAnimationForKey(animation, key)
+        this.animating = true
+      }
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private remove() {
+    this.item?.removeAnimationForKey(key)
+    this.layer?.removeFromSuperlayer()
+    this.item = this.layer = this.native = undefined
+    this.animating = false
+  }
+}

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/properties.ts

@@ -25,7 +25,7 @@ const defaults: Record<Property, number> = {
   rotateY: 0,
 }
 
-/** How close to its target a spring has to be to count as settled. */
+/** How close to its target a spring or decay has to be to count as settled. */
 export const precision: Record<Property, number> = {
   opacity: 0.002,
   x: 0.25,