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

package/src/config.ts

@@ -0,0 +1,46 @@
+import { getDriver } from './driver/index.js'
+
+export interface JoltConfig {
+  /** Playback speed for every engine animation. `0.2` plays everything five times slower. */
+  timeScale?: number
+  /**
+   * When transforms, paths, decorations and decay jump to their end instead of animating.
+   * `user` follows the platform setting. Opacity and colors still animate.
+   */
+  reducedMotion?: 'user' | 'always' | 'never'
+}
+
+const settings: Required<JoltConfig> = { timeScale: 1, reducedMotion: 'user' }
+const preferences: readonly JoltConfig['reducedMotion'][] = ['user', 'always', 'never']
+
+/**
+ * Global settings, applied to animations that start after the call.
+ *
+ * ```ts
+ * configure({ timeScale: 0.2 }) // tune a spring in slow motion
+ * configure({ reducedMotion: 'always' }) // check the reduced layout
+ * ```
+ */
+export function configure(options: JoltConfig): void {
+  if (options === null || typeof options !== 'object')
+    throw new TypeError('configure() takes an options object.')
+  const { timeScale, reducedMotion } = options
+  if (timeScale !== undefined && (!Number.isFinite(timeScale) || timeScale <= 0))
+    throw new RangeError(`Time scale must be a positive finite number, got ${timeScale}.`)
+  if (reducedMotion !== undefined && !preferences.includes(reducedMotion))
+    throw new TypeError(
+      `Reduced motion must be 'user', 'always' or 'never', got ${String(reducedMotion)}.`,
+    )
+  if (timeScale !== undefined) settings.timeScale = timeScale
+  if (reducedMotion !== undefined) settings.reducedMotion = reducedMotion
+}
+
+export function timeScale(): number {
+  return settings.timeScale
+}
+
+/** Whether motion is reduced right now. `user` asks the platform each time. */
+export function reducedMotion(): boolean {
+  if (settings.reducedMotion === 'user') return getDriver().reducedMotion?.() ?? false
+  return settings.reducedMotion === 'always'
+}

package/src/decoration.ts

@@ -0,0 +1,180 @@
+import { preserveZeroShadow } from './driver/ios-shadow.js'
+import { Color, Utils, isAndroid, type View } from '@nativescript/core'
+
+type Shadow = Exclude<View['boxShadow'], string>[number]
+export type DecorationProperty =
+  | 'borderRadius'
+  | 'borderWidth'
+  | 'shadowOpacity'
+  | 'shadowRadius'
+  | 'shadowOffsetX'
+  | 'shadowOffsetY'
+  | 'elevation'
+  | 'translationZ'
+
+export const decorationProperties: readonly DecorationProperty[] = [
+  'borderRadius',
+  'borderWidth',
+  'shadowOpacity',
+  'shadowRadius',
+  'shadowOffsetX',
+  'shadowOffsetY',
+  'elevation',
+  'translationZ',
+]
+export const radiusKeys = [
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomRightRadius',
+  'borderBottomLeftRadius',
+] as const
+export const widthKeys = [
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+] as const
+const writing = new WeakSet<View>()
+export const isWritingDecoration = (view: View) => writing.has(view)
+export const isDecorationProperty = (key: string): key is DecorationProperty =>
+  decorationProperties.includes(key as DecorationProperty)
+
+/** Core lengths may be numbers, px strings or parsed { value, unit } lengths. */
+export function dip(value: unknown): number {
+  if (value === undefined || value === null) return 0
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const match = /^(-?(?:\d+(?:\.\d*)?|\.\d+))(dip|px)?$/.exec(value.trim())
+    if (match)
+      return Number(match[1]) / (match[2] === 'px' ? Utils.layout.getDisplayDensity() : 1)
+  }
+  if (typeof value === 'object' && 'value' in value && 'unit' in value) {
+    const length = value as { value: number; unit: string }
+    if (Number.isFinite(length.value) && (length.unit === 'dip' || length.unit === 'px'))
+      return length.value / (length.unit === 'px' ? Utils.layout.getDisplayDensity() : 1)
+  }
+  throw new TypeError('Decoration animations require finite DIP or px lengths.')
+}
+
+export function singleShadow(view: View): Shadow {
+  const shadows = view.boxShadow
+  if (!Array.isArray(shadows) || shadows.length !== 1 || shadows[0]!.inset)
+    throw new TypeError('Shadow animation requires one existing outer boxShadow.')
+  return shadows[0]!
+}
+
+export function validateDecorationTarget(view: View, property: DecorationProperty) {
+  const shadow = property.startsWith('shadow')
+  const z = property === 'elevation' || property === 'translationZ'
+  if ((shadow && isAndroid) || (z && !isAndroid))
+    throw new TypeError(`"${property}" is only supported on ${z ? 'Android' : 'iOS'}.`)
+  if (z) return
+  if (view.style.clipPath || view.style.cornerShape === 'squircle')
+    throw new TypeError(
+      'Decoration animations require circular corners without a clipPath.',
+    )
+  for (const keys of [radiusKeys, widthKeys]) {
+    const values = keys.map((key) => dip(view[key]))
+    if (values.some((value) => value !== values[0]))
+      throw new TypeError(
+        'Decoration animations require uniform border widths and radii.',
+      )
+  }
+  const colors = [
+    view.borderTopColor,
+    view.borderRightColor,
+    view.borderBottomColor,
+    view.borderLeftColor,
+  ].map((color) => color?.argb ?? 0)
+  if (colors.some((color) => color !== colors[0]))
+    throw new TypeError('Decoration animations require uniform border colors.')
+  if (shadow) {
+    const value = singleShadow(view)
+    for (const length of [
+      value.offsetX,
+      value.offsetY,
+      value.blurRadius,
+      value.spreadRadius,
+    ])
+      dip(length)
+  }
+  if (
+    property === 'borderRadius' &&
+    isAndroid &&
+    view.boxShadow &&
+    (!Array.isArray(view.boxShadow) || view.boxShadow.length)
+  )
+    throw new TypeError(
+      'Animate Android radius with elevation shadows; CSS boxShadow caches its shape.',
+    )
+}
+
+export function validateDecorationFrames(
+  property: DecorationProperty,
+  frames: readonly (number | null)[],
+) {
+  if (
+    frames.some((value) => value !== null && clampDecoration(property, value) !== value)
+  )
+    throw new RangeError(`Invalid keyframes for "${property}".`)
+}
+export function clampDecoration(property: DecorationProperty, value: number): number {
+  if (property === 'shadowOpacity') return Math.max(0, Math.min(1, value))
+  return property === 'borderRadius' ||
+    property === 'borderWidth' ||
+    property === 'shadowRadius' ||
+    property === 'elevation'
+    ? Math.max(0, value)
+    : value
+}
+
+export function readDecoration(view: View, property: DecorationProperty): number {
+  if (property === 'borderRadius') {
+    const radius = !isAndroid ? view.nativeViewProtected?.layer?.cornerRadius : undefined
+    return typeof radius === 'number' ? radius : dip(view.borderTopLeftRadius)
+  }
+  if (property === 'borderWidth') return dip(view.borderTopWidth)
+  if (property === 'elevation')
+    return view.nativeViewProtected?.getElevation
+      ? view.nativeViewProtected.getElevation() / Utils.layout.getDisplayDensity()
+      : view.androidElevation || 0
+  if (property === 'translationZ')
+    return (
+      view.nativeViewProtected?.getTranslationZ?.() / Utils.layout.getDisplayDensity() ||
+      0
+    )
+  const shadow = singleShadow(view)
+  if (property === 'shadowOpacity')
+    return ((shadow.color?.argb ?? 0xff000000) >>> 24) / 255
+  return property === 'shadowRadius'
+    ? dip(shadow.blurRadius) / 2
+    : dip(property === 'shadowOffsetX' ? shadow.offsetX : shadow.offsetY)
+}
+
+export function writeDecoration(view: View, property: DecorationProperty, raw: number) {
+  const value = clampDecoration(property, raw)
+  writing.add(view)
+  try {
+    if (property === 'borderRadius' || property === 'borderWidth') view[property] = value
+    else if (property === 'elevation') view.androidElevation = value
+    else if (property === 'translationZ')
+      view.nativeViewProtected?.setTranslationZ?.(
+        value * Utils.layout.getDisplayDensity(),
+      )
+    else {
+      const shadow = { ...singleShadow(view) }
+      if (property === 'shadowOpacity')
+        shadow.color = new Color(
+          ((Math.round(value * 255) << 24) | ((shadow.color?.argb ?? 0) & 0xffffff)) >>>
+            0,
+        )
+      else if (property === 'shadowRadius') shadow.blurRadius = value * 2
+      else if (property === 'shadowOffsetX') shadow.offsetX = value
+      else shadow.offsetY = value
+      view.boxShadow = [shadow]
+      if (!isAndroid) preserveZeroShadow(view)
+    }
+  } finally {
+    writing.delete(view)
+  }
+}

package/src/driver/android-color.ts

@@ -1,5 +1,7 @@
 import { type View } from '@nativescript/core'
 import { readColor, type ColorProperty } from '../color.js'
+import { androidPlayback, type AndroidPlayback } from './android-playback.js'
+import type { PlaybackCommand } from '../playback.js'
 import type { Track } from '../track.js'
 
 interface NativeTarget {
@@ -8,12 +10,18 @@ interface NativeTarget {
   isSupported(): boolean
 }
 interface ColorHandle {
+  control(elapsed: number, paused: boolean, command?: PlaybackCommand): void
   cancel(): void
   elapsed(): number
   target: NativeTarget
 }
 const playing = new WeakMap<View, Map<ColorProperty, ColorHandle>>()
 
+export function syncAndroidColor(view: View) {
+  for (const handle of playing.get(view)?.values() ?? [])
+    handle.target.setColor(handle.target.getColor())
+}
+
 export function presentedAndroidColor(view: View, property: ColorProperty): number {
   const active = playing.get(view)?.get(property)
   if (active) return active.target.getColor() >>> 0
@@ -62,6 +70,7 @@ export function playAndroidColor(
     onEnd(false)
     return {
       cancel() {},
+      control() {},
       elapsed: () => 0,
       target: {
         getColor: () => readColor(view, property),
@@ -98,7 +107,6 @@ export function playAndroidColor(
     )
   }
   let stopped = false,
-    started = false,
     queued = false
   const cleanup = () => {
     if (stopped) return
@@ -111,10 +119,11 @@ export function playAndroidColor(
     for (const name of changes) view.style.off(name, invalidate)
     if (playing.get(view)?.get(property) === handle) playing.get(view)?.delete(property)
   }
+  let player: AndroidPlayback | undefined
   const cancel = () => {
     if (stopped) return
     cleanup()
-    animator.cancel()
+    player?.cancel()
     onEnd(false)
   }
   const invalidate = () => {
@@ -127,30 +136,18 @@ export function playAndroidColor(
   }
   const handle: ColorHandle = {
     target,
-    elapsed: () => (started ? track.delay + animator.getCurrentPlayTime() : 0),
+    elapsed: () => player?.elapsed() ?? 0,
+    control(time, paused, command) {
+      player?.control(time, paused, command)
+    },
     cancel() {
       cleanup()
-      animator.cancel()
+      player?.cancel()
     },
   }
   let entries = playing.get(view)
   if (!entries) playing.set(view, (entries = new Map()))
   entries.set(property, handle)
-  animator.addListener(
-    new android.animation.Animator.AnimatorListener({
-      onAnimationStart() {
-        started = true
-      },
-      onAnimationRepeat() {},
-      onAnimationCancel() {},
-      onAnimationEnd() {
-        if (!stopped) {
-          cleanup()
-          onEnd()
-        }
-      },
-    }),
-  )
   view.on('unloaded', cancel)
   if (property === 'color') {
     view.on('textChange', invalidate)
@@ -159,7 +156,12 @@ export function playAndroidColor(
   for (const name of changes) view.style.on(name, invalidate)
   if (target.isSupported()) {
     target.setColor(track.values[0]! | 0)
-    animator.start()
+    player = androidPlayback(animator, track, () => {
+      if (!stopped) {
+        cleanup()
+        onEnd()
+      }
+    })
   } else {
     cleanup()
     onEnd(false)

package/src/driver/android-decoration.ts

@@ -0,0 +1,182 @@
+import { Utils, type View } from '@nativescript/core'
+import {
+  isWritingDecoration,
+  radiusKeys,
+  widthKeys,
+  validateDecorationTarget,
+  type DecorationProperty,
+} from '../decoration.js'
+import { androidPlayback, type AndroidPlayback } from './android-playback.js'
+import type { PlaybackCommand } from '../playback.js'
+import type { Track } from '../track.js'
+interface NativeTarget {
+  getValue(): number
+  setValue(value: number): void
+  isSupported(): boolean
+  acquire(): void
+  release(): void
+}
+interface Handle {
+  control(elapsed: number, paused: boolean, command?: PlaybackCommand): void
+  cancel(): void
+  elapsed(): number
+  target: NativeTarget
+}
+const playing = new WeakMap<View, Map<DecorationProperty, Handle>>()
+const ids = { borderRadius: 0, borderWidth: 1, elevation: 2, translationZ: 3 } as const
+export function syncAndroidDecoration(view: View) {
+  for (const handle of playing.get(view)?.values() ?? [])
+    handle.target.setValue(handle.target.getValue())
+}
+export const presentedAndroidDecoration = (view: View, property: DecorationProperty) => {
+  const target = playing.get(view)?.get(property)?.target
+  return target ? target.getValue() / Utils.layout.getDisplayDensity() : undefined
+}
+export function playAndroidDecoration(
+  view: View,
+  track: Track,
+  onEnd: (finished?: boolean) => void,
+): Handle {
+  const property = track.property as keyof typeof ids
+  const density = Utils.layout.getDisplayDensity()
+  const bridge = globalThis as unknown as {
+    org: {
+      rafaelaugusto: {
+        jolt: {
+          DecorationTarget: new (
+            view: android.view.View,
+            property: number,
+            value: number,
+            borderColor: number,
+          ) => NativeTarget
+        }
+      }
+    }
+  }
+  let target: NativeTarget
+  try {
+    target = new bridge.org.rafaelaugusto.jolt.DecorationTarget(
+      view.nativeViewProtected,
+      ids[property],
+      track.values[0]! * density,
+      view.borderTopColor?.argb ?? 0,
+    )
+  } catch {
+    onEnd(false)
+    return {
+      cancel() {},
+      control() {},
+      elapsed: () => 0,
+      target: {
+        getValue: () => track.to * density,
+        setValue() {},
+        isSupported: () => false,
+        acquire() {},
+        release() {},
+      },
+    }
+  }
+  const frames = Array.create(android.animation.Keyframe, track.values.length)
+  track.values.forEach((value, index) => {
+    frames[index] = android.animation.Keyframe.ofFloat(
+      track.times[index]!,
+      value * density,
+    )
+  })
+  const holders = Array.create(android.animation.PropertyValuesHolder, 1)
+  holders[0] = android.animation.PropertyValuesHolder.ofKeyframe('value', frames)
+  const animator = android.animation.ObjectAnimator.ofPropertyValuesHolder(
+    target as unknown as java.lang.Object,
+    holders,
+  )
+  animator.setDuration(Math.max(track.duration, 1))
+  animator.setStartDelay(track.delay)
+  animator.setInterpolator(new android.view.animation.LinearInterpolator())
+  if (track.repeat > 0) {
+    animator.setRepeatCount(
+      Number.isFinite(track.repeat)
+        ? track.repeat
+        : android.animation.ValueAnimator.INFINITE,
+    )
+    animator.setRepeatMode(
+      track.reverse
+        ? android.animation.ValueAnimator.REVERSE
+        : android.animation.ValueAnimator.RESTART,
+    )
+  }
+  let stopped = false
+  const changes = [
+    ...radiusKeys,
+    ...widthKeys,
+    'clipPath',
+    'cornerShape',
+    'boxShadow',
+    'androidElevation',
+  ].map((name) => `${name}Change`)
+  const cleanup = () => {
+    if (stopped) return
+    stopped = true
+    view.off('unloaded', cancel)
+    for (const event of changes) view.style.off(event, external)
+    target.release()
+    if (playing.get(view)?.get(property) === handle) playing.get(view)?.delete(property)
+  }
+  let player: AndroidPlayback | undefined
+  const cancel = () => {
+    if (!stopped) {
+      cleanup()
+      player?.cancel()
+      onEnd(false)
+    }
+  }
+  const external = (event: { eventName: string }) => {
+    if (isWritingDecoration(view)) return
+    const own =
+      property === 'borderRadius'
+        ? radiusKeys
+        : property === 'borderWidth'
+          ? widthKeys
+          : property === 'elevation'
+            ? ['androidElevation']
+            : []
+    void Promise.resolve().then(() => {
+      if (stopped) return
+      if (own.some((name) => event.eventName === `${name}Change`)) return cancel()
+      try {
+        validateDecorationTarget(view, property)
+      } catch {
+        cancel()
+      }
+    })
+  }
+  const handle: Handle = {
+    target,
+    elapsed: () => player?.elapsed() ?? 0,
+    control(time, paused, command) {
+      player?.control(time, paused, command)
+    },
+    cancel() {
+      cleanup()
+      player?.cancel()
+    },
+  }
+  const entries = playing.get(view) ?? new Map<DecorationProperty, Handle>()
+  playing.set(view, entries)
+  entries.set(property, handle)
+  view.on('unloaded', cancel)
+  for (const event of changes) view.style.on(event, external)
+  if (target.isSupported()) {
+    target.acquire()
+    target.setValue(track.values[0]! * density)
+    player = androidPlayback(animator, track, () => {
+      if (!stopped) {
+        cleanup()
+        onEnd()
+      }
+    })
+  } else {
+    cleanup()
+    onEnd(false)
+  }
+  return handle
+}

package/src/driver/android-playback.ts

@@ -0,0 +1,157 @@
+import type { Track } from '../track.js'
+import type { PlaybackClock, PlaybackCommand } from '../playback.js'
+
+export interface AndroidPlayback {
+  cancel(): void
+  elapsed(): number
+  control(elapsed: number, paused: boolean, command?: PlaybackCommand): void
+}
+
+/** Reuse native keyframes when seeking, including rewinding into a start delay. */
+export function androidPlayback(
+  animator: android.animation.ValueAnimator,
+  track: Track,
+  onEnd: () => void,
+  onStart?: () => void,
+  onRelease?: () => void,
+): AndroidPlayback {
+  let suppressed = false
+  let stopped = false
+  let started = false
+  let acquired = false
+  let origin = 0
+  let delay = track.delay
+  let held: number | undefined
+  animator.addListener(
+    new android.animation.Animator.AnimatorListener({
+      onAnimationStart() {
+        if (!suppressed && !stopped) {
+          started = true
+          if (!acquired) {
+            acquired = true
+            onStart?.()
+          }
+        }
+      },
+      onAnimationRepeat() {},
+      onAnimationCancel() {
+        if (!suppressed && !stopped) onRelease?.()
+      },
+      onAnimationEnd() {
+        if (suppressed || stopped || held !== undefined) return
+        stopped = true
+        onRelease?.()
+        onEnd()
+      },
+    }),
+  )
+  const elapsed = () =>
+    held ?? (started ? origin + delay + animator.getCurrentPlayTime() : origin)
+  const control = (
+    position: number,
+    paused: boolean,
+    command: PlaybackCommand = 'seek',
+  ) => {
+    if (stopped) return
+    if (command === 'pause') {
+      held = position
+      animator.pause()
+      return
+    }
+    if (command === 'play') {
+      held = undefined
+      animator.resume()
+      return
+    }
+    suppressed = true
+    animator.cancel()
+    started = false
+    origin = Math.min(position, track.delay)
+    delay = Math.max(0, track.delay - position)
+    animator.setStartDelay(delay)
+    held = paused ? position : undefined
+    suppressed = false
+    animator.start()
+    if (paused) animator.pause()
+    if (position >= track.delay)
+      animator.setCurrentPlayTime(Math.max(0, position - track.delay))
+  }
+  animator.start()
+  return {
+    elapsed,
+    control,
+    cancel() {
+      if (stopped) return
+      stopped = true
+      onRelease?.()
+      animator.cancel()
+    },
+  }
+}
+
+/** Share one native clock among active animations. Pause it when every owner
+ * is paused, and dispose it when the last owner settles. No frame callbacks. */
+export function androidClockFactory() {
+  let animator: android.animation.ValueAnimator | undefined
+  let owners = 0,
+    running = 0,
+    accumulated = 0
+  const now = () => accumulated + (animator?.getCurrentPlayTime() ?? 0)
+  const start = () => {
+    if (animator) return
+    const values = Array.create('float', 2)
+    values[0] = 0
+    values[1] = 1
+    animator = android.animation.ValueAnimator.ofFloat(values)
+    animator.setDuration(60_000)
+    animator.setRepeatCount(android.animation.ValueAnimator.INFINITE)
+    animator.start()
+  }
+  const stop = () => {
+    accumulated = now()
+    animator?.cancel()
+    animator = undefined
+  }
+  return (_duration: number): PlaybackClock => {
+    start()
+    owners++
+    running++
+    let offset = 0,
+      anchor = now(),
+      paused = false,
+      stopped = false
+    const time = () => offset + (paused || stopped ? 0 : now() - anchor)
+    const pause = () => {
+      if (paused || stopped) return
+      offset = time()
+      paused = true
+      // getCurrentPlayTime keeps counting while a ValueAnimator is paused and
+      // corrects itself only on its next frame. Start a fresh marker on resume
+      // so command-time reads cannot jump forward and then backward.
+      if (--running === 0) stop()
+    }
+    return {
+      time,
+      pause,
+      play() {
+        if (!paused || stopped) return
+        if (running++ === 0) start()
+        anchor = now()
+        paused = false
+      },
+      seek(ms) {
+        offset = ms
+        anchor = now()
+      },
+      cancel() {
+        if (stopped) return
+        pause()
+        stopped = true
+        if (--owners === 0) {
+          stop()
+          accumulated = 0
+        }
+      },
+    }
+  }
+}