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

package/src/engine.ts

@@ -4,6 +4,7 @@ import { playHaptics, type HapticOptions } from './haptics.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
+import { isColorProperty } from './color.js'
 
 export interface Animation extends PromiseLike<boolean> {
   /**
@@ -12,7 +13,7 @@ export interface Animation extends PromiseLike<boolean> {
    * Never rejects.
    */
   readonly finished: Promise<boolean>
-  /** Stops playback. Property animations keep their current values; symbol effects are removed. */
+  /** Stops playback. Each effect documents whether it preserves or restores its visual state. */
   stop(): void
 }
 
@@ -107,18 +108,21 @@ export class ViewAnimation implements Animation {
       let current: number
       let velocity = 0
       if (previous) {
-        const elapsed = now - previous.startedAt
+        const elapsed = elapsedOf(previous, now)
         current = driver.presented(this.view, property) ?? previous.track.valueAt(elapsed)
         velocity = previous.track.velocityAt(elapsed)
         release(previous, now, false)
       } else {
-        current = readValue(this.view, property)
+        current =
+          (isColorProperty(property)
+            ? driver.presented(this.view, property)
+            : undefined) ?? readValue(this.view, property)
       }
       return createTrack(
         property,
         keyframes.map((value) => {
           if (value === null) return current
-          if (!relative) return value
+          if (!relative || isColorProperty(property)) return value
           return property === 'opacity' || property.startsWith('scale')
             ? current * value
             : current + value
@@ -147,24 +151,24 @@ export class ViewAnimation implements Animation {
     this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now)
 
     for (const entry of this.entries) {
-      entry.handle = driver.play(this.view, entry.track, now, () => {
+      entry.handle = driver.play(this.view, entry.track, now, (finished = true) => {
         if (entry.done) return
         entry.done = true
         forget(entry)
-        this.ended(true)
+        this.ended(finished)
       })
     }
 
     const arrival = Math.max(...this.entries.map((entry) => entry.track.arrival))
     if (this.pending === 0) this.settle()
-    else if (Number.isFinite(arrival)) {
+    else if (Number.isFinite(arrival) && tracks.some((track) => track.end > arrival)) {
       this.cancelArrival = driver.after(arrival, this.arrive)
     }
   }
 
   private waitForLoad(plans: readonly Plan[]) {
     for (const { property, keyframes, relative } of plans) {
-      if (relative) continue
+      if (relative && !isColorProperty(property)) continue
       const first = keyframes[0]
       if (first !== null && first !== undefined) writeValue(this.view, property, first)
     }
@@ -220,9 +224,13 @@ function release(entry: Entry, now: number, commit: boolean) {
   forget(entry)
   if (commit) {
     const value =
-      driver.presented(view, property) ?? entry.track.valueAt(now - entry.startedAt)
+      driver.presented(view, property) ?? entry.track.valueAt(elapsedOf(entry, now))
     writeValue(view, property, value)
   }
   driver.stop(view, entry.handle)
   entry.owner.ended(false)
 }
+
+function elapsedOf(entry: Entry, now: number) {
+  return getDriver().elapsed?.(entry.handle) ?? now - entry.startedAt
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-export { animate, stop } from './animate.js'
+export { animate, decay, stop } from './animate.js'
 export { sequence } from './sequence.js'
 export type { Step } from './sequence.js'
 export { press } from './press.js'
@@ -7,6 +7,14 @@ 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 { liquid } from './liquid.js'
+export type { LiquidOptions, LiquidEffect } from './liquid.js'
+export { loader } from './loader.js'
+export type { LoaderOptions, LoaderStyle } from './loader.js'
+export { reveal, conceal } from './reveal.js'
+export type { RevealOptions, ConcealOptions } from './reveal.js'
+export { animateText } from './text.js'
+export type { TextOptions } from './text.js'
 export { symbolEffect } from './symbol-effect.js'
 export type {
   SymbolEffect,
@@ -20,4 +28,5 @@ export type { Spring, SpringName, Timing, Transition, Tween } from './transition
 export { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
 export type { Animation } from './engine.js'
+export type { ColorValue, ColorKeyframes } from './color.js'
 export type * from './types.js'

package/src/liquid-grid.ts

@@ -0,0 +1,28 @@
+/** A periodic displacement field. The fixed boundary keeps transparent edges in bounds. */
+export function liquidGrid(
+  columns: number,
+  rows: number,
+  phase: number,
+  intensity: number,
+) {
+  const positions = new Float32Array((columns + 1) * (rows + 1) * 2)
+  const t = phase * Math.PI * 2
+  let index = 0
+  for (let row = 0; row <= rows; row++) {
+    const y = row / rows
+    for (let column = 0; column <= columns; column++) {
+      const x = column / columns
+      const edge = Math.sin(Math.PI * x) ** 2 * Math.sin(Math.PI * y) ** 2
+      const amount = 0.055 * intensity * edge
+      positions[index++] =
+        x +
+        amount *
+          (Math.sin(Math.PI * 2 * y + t) + 0.4 * Math.sin(Math.PI * 2 * (x + y) - 2 * t))
+      positions[index++] =
+        y +
+        amount *
+          (Math.cos(Math.PI * 2 * x - t) + 0.4 * Math.cos(Math.PI * 2 * (x - y) + 2 * t))
+    }
+  }
+  return positions
+}

package/src/liquid.ts

@@ -0,0 +1,282 @@
+import { Application, Image, isIOS } from '@nativescript/core'
+import { tintColorProperty } from '@nativescript/core/ui/image'
+import { toView } from './animate.js'
+import { liquidGrid } from './liquid-grid.js'
+import type { Target } from './types.js'
+
+export interface LiquidOptions {
+  /** Amount of internal deformation, from 0 to 1. Defaults to 0.7. */
+  intensity?: number
+  /** Milliseconds per seamless cycle. Defaults to 8000. */
+  duration?: number
+}
+
+export interface LiquidEffect {
+  /** Freeze the current deformation. */
+  pause(): void
+  /** Continue from the paused deformation. */
+  resume(): void
+  /** Remove the effect and restore the image. Idempotent. */
+  stop(): void
+}
+
+const running = new WeakMap<Image, LiquidEffect>()
+const key = 'jolt:liquid'
+const columns = 24
+const rows = 24
+const steps = 64
+const noop = () => {}
+
+/** Deforms a raster image with native iOS texture warps. Android leaves it unchanged. */
+export function liquid(target: Target, options: LiquidOptions = {}): LiquidEffect {
+  const settings = {
+    intensity: options.intensity ?? 0.7,
+    duration: options.duration ?? 8000,
+  }
+  if (
+    !Number.isFinite(settings.intensity) ||
+    settings.intensity < 0 ||
+    settings.intensity > 1
+  )
+    throw new RangeError('Liquid intensity must be between zero and one.')
+  if (!Number.isFinite(settings.duration) || settings.duration <= 0)
+    throw new RangeError('Liquid duration must be a positive finite number.')
+  const image = toView(target)
+  if (!(image instanceof Image)) throw new TypeError('Expected a NativeScript Image.')
+  running.get(image)?.stop()
+  if (!isIOS || settings.intensity === 0) return { pause: noop, resume: noop, stop: noop }
+  return new Liquid(image, settings)
+}
+
+class Liquid implements LiquidEffect {
+  private stopped = false
+  private queued = false
+  private pausedByUser = false
+  private active = UIApplication.sharedApplication.applicationState === 0 // UIApplicationStateActive
+  private native: UIImageView | undefined
+  private original: UIImage | undefined
+  private source: Image['imageSource'] | undefined
+  private renderer: SKView | undefined
+  private scene: SKScene | undefined
+  private sprite: SKSpriteNode | undefined
+  private observers: [
+    string,
+    ReturnType<typeof Application.ios.addNotificationObserver>,
+  ][] = []
+
+  constructor(
+    private readonly image: Image,
+    private readonly settings: Required<LiquidOptions>,
+  ) {
+    running.set(image, this)
+    for (const event of ['loaded', 'layoutChanged', 'imageSourceChange', 'stretchChange'])
+      image.on(event, this.schedule)
+    image.on('unloaded', this.unloaded)
+    image.style.on('visibilityChange', this.schedule)
+    image.style.on('tintColorChange', this.schedule)
+    this.observe(UIAccessibilityReduceMotionStatusDidChangeNotification, this.schedule)
+    this.observe(UIApplicationWillResignActiveNotification, this.suspend)
+    this.observe(UIApplicationDidBecomeActiveNotification, this.activate)
+    this.schedule()
+  }
+
+  pause = () => {
+    this.pausedByUser = true
+    if (this.renderer) this.renderer.paused = true
+  }
+  resume = () => {
+    if (this.stopped) return
+    this.pausedByUser = false
+    this.schedule()
+  }
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    for (const event of ['loaded', 'layoutChanged', 'imageSourceChange', 'stretchChange'])
+      this.image.off(event, this.schedule)
+    this.image.off('unloaded', this.unloaded)
+    this.image.style.off('visibilityChange', this.schedule)
+    this.image.style.off('tintColorChange', this.schedule)
+    for (const [name, observer] of this.observers)
+      Application.ios.removeNotificationObserver(observer, name)
+    this.observers = []
+    if (running.get(this.image) === this) running.delete(this.image)
+    this.remove()
+  }
+  private observe(name: string, callback: () => void) {
+    this.observers.push([name, Application.ios.addNotificationObserver(name, callback)])
+  }
+  private suspend = () => {
+    this.active = false
+    if (this.renderer) this.renderer.paused = true
+  }
+  private activate = () => {
+    this.active = true
+    this.schedule()
+  }
+  private unloaded = () => 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.image.isLoaded ||
+      this.image.visibility !== 'visible' ||
+      this.image.tintColor ||
+      UIAccessibilityIsReduceMotionEnabled()
+    )
+      return this.remove()
+    const native = this.image.nativeViewProtected as UIImageView | undefined
+    if (!(native instanceof UIImageView) || !native.window) return this.remove()
+    if (
+      this.native &&
+      (this.native !== native ||
+        native.image !== null ||
+        this.image.imageSource !== this.source)
+    )
+      this.remove()
+    const source = this.original ?? native.image
+    if (
+      !source?.CGImage ||
+      source.images?.count ||
+      source.renderingMode === 2 /* AlwaysTemplate */
+    )
+      return this.remove()
+    if (source.size.width * source.size.height * source.scale ** 2 > 16_777_216)
+      return this.remove()
+    const bounds = native.bounds
+    if (
+      bounds.size.width <= 0 ||
+      bounds.size.height <= 0 ||
+      source.size.width <= 0 ||
+      source.size.height <= 0
+    )
+      return this.remove()
+    if (!this.renderer) {
+      // A paused SKView cannot draw its first frame. Keep the original visible
+      // until rendering can start, including source changes while paused.
+      if (this.pausedByUser || !this.active) return
+      this.create(native, source)
+    }
+    const renderer = this.renderer!
+    renderer.frame = CGRectMake(
+      bounds.origin.x,
+      bounds.origin.y,
+      bounds.size.width,
+      bounds.size.height,
+    )
+    this.scene!.size = CGSizeMake(bounds.size.width, bounds.size.height)
+    const iw = source.size.width
+    const ih = source.size.height
+    const { width, height } = bounds.size
+    const stretch = this.image.stretch
+    const scale =
+      stretch === 'aspectFill'
+        ? Math.max(width / iw, height / ih)
+        : Math.min(width / iw, height / ih)
+    this.sprite!.size = CGSizeMake(
+      stretch === 'fill' ? width : stretch === 'none' ? iw : iw * scale,
+      stretch === 'fill' ? height : stretch === 'none' ? ih : ih * scale,
+    )
+    this.sprite!.position = CGPointMake(width / 2, height / 2)
+    renderer.paused = this.pausedByUser || !this.active
+  }
+  private create(native: UIImageView, source: UIImage) {
+    const renderer = SKView.alloc().initWithFrame(native.bounds)
+    this.renderer = renderer
+    this.native = native
+    this.original = source
+    this.source = this.image.imageSource
+    renderer.opaque = false
+    renderer.backgroundColor = UIColor.clearColor
+    renderer.allowsTransparency = true
+    renderer.asynchronous = true
+    renderer.userInteractionEnabled = false
+    renderer.accessibilityElementsHidden = true
+    renderer.clipsToBounds = true
+    renderer.preferredFramesPerSecond = Math.min(
+      120,
+      native.window?.screen?.maximumFramesPerSecond ?? 60,
+    )
+    renderer.paused = true
+    const scene = SKScene.sceneWithSize(native.bounds.size)
+    this.scene = scene
+    scene.backgroundColor = UIColor.clearColor
+    scene.scaleMode = 3 // SKSceneScaleModeResizeFill
+    const texture = SKTexture.textureWithImage(source)
+    const sprite = SKSpriteNode.spriteNodeWithTexture(texture)
+    this.sprite = sprite
+    const warps: SKWarpGeometryGrid[] = []
+    const times: number[] = []
+    for (let step = 0; step <= steps; step++) {
+      const positions = liquidGrid(
+        columns,
+        rows,
+        step === steps ? 0 : step / steps,
+        this.settings.intensity,
+      )
+      warps.push(
+        SKWarpGeometryGrid.gridWithColumnsRowsSourcePositionsDestPositions(
+          columns,
+          rows,
+          null,
+          positions,
+        ),
+      )
+      times.push(((step / steps) * this.settings.duration) / 1000)
+    }
+    const loop = SKAction.animateWithWarpsTimes(warps, times)
+    if (!loop) throw new Error('Unable to create the liquid warp action.')
+    sprite.warpGeometry = SKWarpGeometryGrid.gridWithColumnsRows(columns, rows)
+    const entrance = SKAction.warpToDuration(
+      warps[0]!,
+      Math.min(0.35, this.settings.duration / 10000),
+    )
+    if (!entrance) throw new Error('Unable to create the liquid entrance.')
+    sprite.runActionWithKey(
+      SKAction.sequence([entrance, SKAction.repeatActionForever(loop)]),
+      key,
+    )
+    scene.addChild(sprite)
+    renderer.presentScene(scene)
+    native.addSubview(renderer)
+    native.image = null
+  }
+  private remove() {
+    const { renderer, sprite, native, original } = this
+    if (renderer) {
+      renderer.paused = true
+      sprite?.removeAllActions()
+      sprite?.removeFromParent()
+      renderer.presentScene(null)
+      renderer.removeFromSuperview()
+    }
+    if (
+      native &&
+      native.image === null &&
+      original &&
+      this.image.imageSource === this.source
+    ) {
+      native.image = original
+      // Core couldn't turn the suppressed UIImage into a template while it was
+      // hidden. Reapply its public native setter when a tint takes over.
+      if (this.image.tintColor)
+        (this.image as unknown as Record<symbol, (value: unknown) => void>)[
+          tintColorProperty.setNative
+        ]!(this.image.tintColor)
+    }
+    this.renderer = this.scene = this.sprite = this.native = this.original = undefined
+    this.source = undefined
+  }
+}

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

@@ -1,4 +1,5 @@
-import type { EventData, TouchGestureEventData } from '@nativescript/core'
+import { Color, type EventData, type TouchGestureEventData } from '@nativescript/core'
+import { isColorProperty } from './color.js'
 import { animate, toView } from './animate.js'
 import { isProperty, readValue, type Property } from './properties.js'
 import type { SpringName, Transition } from './transition.js'
@@ -30,7 +31,12 @@ export function press(
   const onTouch = (event: EventData) => {
     const { action } = event as TouchGestureEventData
     if (action === 'down' && !rest && view.isEnabled !== false) {
-      rest = Object.fromEntries(properties.map((p) => [p, readValue(view, p)]))
+      rest = Object.fromEntries(
+        properties.map((p) => [
+          p,
+          isColorProperty(p) ? new Color(readValue(view, p)) : readValue(view, p),
+        ]),
+      )
       animate(view, pressed, options ?? pressIn)
     } else if ((action === 'up' || action === 'cancel') && rest) {
       animate(