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

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/playback-group.ts

@@ -0,0 +1,110 @@
+import { arrivalOf, setArrival, 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)))
+  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.',
+    )
+}

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(

package/src/properties.ts

@@ -1,7 +1,15 @@
-import type { View } from '@nativescript/core'
+import { Color, type View } from '@nativescript/core'
+import {
+  isDecorationProperty,
+  readDecoration,
+  writeDecoration,
+  type DecorationProperty,
+} from './decoration.js'
+import { isColorProperty, readColor, type ColorProperty } from './color.js'
 
-export type Property =
+export type NumericProperty =
   'opacity' | 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY'
+export type Property = NumericProperty | ColorProperty | DecorationProperty
 
 const viewKeys = {
   opacity: 'opacity',
@@ -12,9 +20,9 @@ const viewKeys = {
   rotate: 'rotate',
   rotateX: 'rotateX',
   rotateY: 'rotateY',
-} as const satisfies Record<Property, keyof View>
+} as const satisfies Record<NumericProperty, keyof View>
 
-const defaults: Record<Property, number> = {
+const defaults: Record<NumericProperty, number> = {
   opacity: 1,
   x: 0,
   y: 0,
@@ -27,6 +35,17 @@ const defaults: Record<Property, number> = {
 
 /** How close to its target a spring or decay has to be to count as settled. */
 export const precision: Record<Property, number> = {
+  borderRadius: 0.1,
+  borderWidth: 0.1,
+  shadowOpacity: 0.002,
+  shadowRadius: 0.1,
+  shadowOffsetX: 0.1,
+  shadowOffsetY: 0.1,
+  elevation: 0.1,
+  translationZ: 0.1,
+  backgroundColor: 0.002,
+  borderColor: 0.002,
+  color: 0.002,
   opacity: 0.002,
   x: 0.25,
   y: 0.25,
@@ -38,14 +57,21 @@ export const precision: Record<Property, number> = {
 }
 
 export function isProperty(key: string): key is Property {
-  return key in viewKeys
+  return Object.hasOwn(viewKeys, key) || isColorProperty(key) || isDecorationProperty(key)
 }
 
 export function readValue(view: View, property: Property): number {
+  if (isColorProperty(property)) return readColor(view, property)
+  if (isDecorationProperty(property)) return readDecoration(view, property)
   const value = view[viewKeys[property]]
   return typeof value === 'number' && !Number.isNaN(value) ? value : defaults[property]
 }
 
 export function writeValue(view: View, property: Property, value: number) {
+  if (isColorProperty(property)) {
+    view[property] = new Color(value)
+    return
+  }
+  if (isDecorationProperty(property)) return writeDecoration(view, property, value)
   view[viewKeys[property]] = value
 }

package/src/sequence.ts

@@ -1,3 +1,5 @@
+import { getDriver } from './driver/index.js'
+import { isDecorationProperty, validateDecorationTarget } from './decoration.js'
 import type { View } from '@nativescript/core'
 import { animate, startingValues, toViews } from './animate.js'
 import { arrivalOf, setArrival, stopView, type Animation } from './engine.js'
@@ -69,6 +71,8 @@ function applyStartingValues(steps: readonly Step[]) {
     const starts = startingValues(animation, options)
 
     for (const view of toViews(target)) {
+      for (const property of starts.keys())
+        if (isDecorationProperty(property)) validateDecorationTarget(view, property)
       let properties = claimed.get(view)
       if (!properties) claimed.set(view, (properties = new Set()))
 
@@ -82,6 +86,7 @@ function applyStartingValues(steps: readonly Step[]) {
       for (const [property, value] of fresh) {
         if (value !== null) writeValue(view, property, value)
       }
+      getDriver().sync?.(view)
       for (const property of starts.keys()) properties.add(property)
     }
   }

package/src/text.ts

@@ -1,3 +1,4 @@
+import { stopIOSColorText } from './driver/ios-color.js'
 import { Application, Label, isIOS } from '@nativescript/core'
 import { textProperty, formattedTextProperty } from '@nativescript/core/ui/text-base'
 import { toView } from './animate.js'
@@ -119,6 +120,7 @@ class TextAnimation implements Animation {
     this.finished = new Promise((resolve) => {
       this.resolve = resolve
     })
+    if (isIOS) stopIOSColorText(view)
     this.formatted = view.formattedText
     running.set(view, this)
     if (!isIOS) {

package/src/track.ts

@@ -1,8 +1,10 @@
+import { clampDecoration, isDecorationProperty } from './decoration.js'
 import { linear } from './easing.js'
 import { solveDecay } from './decay.js'
 import { precision, type Property } from './properties.js'
 import { solveSpring, springPhysics } from './spring.js'
 import type { Curve, ResolvedTransition } from './transition.js'
+import { colorMixer, isColorProperty, type ColorProperty } from './color.js'
 
 /**
  * One property animated over time. The curve is computed here and sampled,
@@ -44,9 +46,11 @@ const ARRIVAL_TOLERANCE = 0.05
 export function createTrack(
   property: Property,
   keyframes: readonly number[],
-  { curve, delay, repeat, reverse }: ResolvedTransition,
+  transition: ResolvedTransition,
   velocity: number,
 ): Track {
+  if (isColorProperty(property)) return colorTrack(property, keyframes, transition)
+  const { curve, delay, repeat, reverse } = transition
   const motion =
     curve.type === 'spring'
       ? spring(property, keyframes, curve, velocity)
@@ -69,7 +73,7 @@ export function createTrack(
     return reverse && iteration % 2 === 1 ? [duration - local, -1] : [local, 1]
   }
 
-  return {
+  const track: Track = {
     property,
     delay,
     duration,
@@ -91,6 +95,65 @@ export function createTrack(
       return motion.velocity(time) * direction
     },
   }
+  if (!isDecorationProperty(property)) return track
+  return {
+    ...track,
+    values: track.values.map((value) => clampDecoration(property, value)),
+    to: clampDecoration(property, track.to),
+    valueAt: (elapsed) => clampDecoration(property, track.valueAt(elapsed)),
+  }
+}
+
+function colorTrack(
+  property: ColorProperty,
+  colors: readonly number[],
+  transition: ResolvedTransition,
+): Track {
+  const progress = createTrack(
+    'opacity',
+    colors.map((_, i) => i),
+    transition,
+    0,
+  )
+  const mixes = colors.slice(1).map((color, i) => colorMixer(colors[i]!, color))
+  const colorAt = (position: number) => {
+    const p = Math.max(0, Math.min(colors.length - 1, position))
+    const segment = Math.min(mixes.length - 1, Math.floor(p))
+    return mixes[segment]!(p - segment)
+  }
+  // Linear timing still needs intermediate colors: native RGB interpolation is
+  // only the short bridge between these perceptually spaced samples.
+  const steps = Math.max(
+    1,
+    Math.min(
+      MAX_DECAY_SAMPLES,
+      Math.ceil((progress.duration / 1000) * SAMPLES_PER_SECOND),
+    ),
+  )
+  const times = [
+    ...new Set([
+      ...progress.times,
+      ...Array.from({ length: steps + 1 }, (_, i) => i / steps),
+    ]),
+  ].sort((a, b) => a - b)
+  return {
+    ...progress,
+    property,
+    times,
+    values: times.map((time) =>
+      colorAt(
+        time === 0
+          ? progress.values[0]!
+          : time === 1
+            ? progress.values.at(-1)!
+            : progress.valueAt(progress.delay + time * progress.duration),
+      ),
+    ),
+    to: colorAt(progress.to),
+    valueAt: (elapsed) => colorAt(progress.valueAt(elapsed)),
+    // Packed colors have no scalar velocity to carry into another spring.
+    velocityAt: () => 0,
+  }
 }
 
 function decay(
@@ -185,7 +248,13 @@ function tween(
     const steps =
       easing === linear || from === to
         ? 1
-        : Math.max(1, Math.ceil(((span * duration) / 1000) * SAMPLES_PER_SECOND))
+        : Math.max(
+            1,
+            Math.min(
+              MAX_DECAY_SAMPLES,
+              Math.ceil(((span * duration) / 1000) * SAMPLES_PER_SECOND),
+            ),
+          )
     for (let step = 1; step <= steps; step++) {
       times.push(start + (span * step) / steps)
       values.push(step === steps ? to : from + (to - from) * easing(step / steps))