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

package/platforms/android/java/org/rafaelaugusto/jolt/ColorTarget.java

@@ -0,0 +1,102 @@
+package org.rafaelaugusto.jolt;
+
+import android.graphics.PorterDuff;
+import android.graphics.drawable.ColorDrawable;
+import android.graphics.drawable.Drawable;
+import android.view.View;
+import android.widget.TextView;
+import java.lang.ref.WeakReference;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+
+/** ObjectAnimator target. All frame updates stay in native code. */
+public final class ColorTarget {
+    private static final String BORDER = "org.nativescript.widgets.BorderDrawable";
+    private static final Field[] FIELDS = fields();
+    private static final String SHADOW = "org.nativescript.widgets.BoxShadowDrawable";
+    private static final Method UNWRAP = unwrapMethod();
+    private final WeakReference<View> view;
+    private final int property;
+    private int color;
+
+    // 0 = background, 1 = uniform border, 2 = text.
+    public ColorTarget(View view, int property, int initialColor) {
+        this.view = new WeakReference<>(view);
+        this.property = property;
+        this.color = initialColor;
+    }
+
+    private static Field[] fields() {
+        try {
+            Class<?> type = Class.forName(BORDER);
+            String[] names = {"backgroundColor", "borderTopColor", "borderRightColor", "borderBottomColor", "borderLeftColor"};
+            Field[] result = new Field[names.length];
+            for (int i = 0; i < names.length; i++) {
+                result[i] = type.getDeclaredField(names[i]);
+                result[i].setAccessible(true);
+            }
+            return result;
+        } catch (ReflectiveOperationException | SecurityException exception) {
+            return null;
+        }
+    }
+
+    private static Method unwrapMethod() {
+        try {
+            return Class.forName(SHADOW).getMethod("getWrappedDrawable");
+        } catch (ReflectiveOperationException exception) {
+            return null;
+        }
+    }
+
+    private Drawable background(View nativeView) {
+        Drawable drawable = nativeView.getBackground();
+        // Avoid reflective method lookups and exceptions in the frame loop.
+        if (drawable != null && drawable.getClass().getName().equals(SHADOW) && UNWRAP != null) {
+            try {
+                return (Drawable) UNWRAP.invoke(drawable);
+            } catch (ReflectiveOperationException exception) {
+                return drawable;
+            }
+        }
+        return drawable;
+    }
+
+    public boolean isSupported() {
+        View nativeView = view.get();
+        if (nativeView == null) return false;
+        if (property == 2) return nativeView instanceof TextView;
+        Drawable drawable = background(nativeView);
+        if (drawable == null) return true;
+        if (drawable.getClass().getName().equals(SHADOW)) return false;
+        return !drawable.getClass().getName().equals(BORDER) || FIELDS != null;
+    }
+
+    public int getColor() { return color; }
+
+    public void setColor(int value) {
+        View nativeView = view.get();
+        if (nativeView == null) return;
+        color = value;
+        if (property == 2) {
+            ((TextView) nativeView).setTextColor(value);
+            return;
+        }
+        // Resolve on every frame: a Core style update may replace the drawable.
+        Drawable drawable = background(nativeView);
+        if (drawable == null || drawable.getClass().getName().equals(SHADOW)) return;
+        if (drawable.getClass().getName().equals(BORDER)) {
+            if (FIELDS == null) return;
+            try {
+                if (property == 0) FIELDS[0].setInt(drawable, value);
+                else for (int i = 1; i < FIELDS.length; i++) FIELDS[i].setInt(drawable, value);
+                drawable.invalidateSelf();
+            } catch (IllegalAccessException exception) {
+                // Unsupported Core versions keep the final model color.
+            }
+        } else if (property == 0) {
+            if (drawable instanceof ColorDrawable) ((ColorDrawable) drawable).setColor(value);
+            else drawable.setColorFilter(value, PorterDuff.Mode.SRC_IN);
+        }
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -0,0 +1,6 @@
+-keep class org.rafaelaugusto.jolt.ColorTarget { *; }
+-keep class org.nativescript.widgets.BorderDrawable { *; }
+-keepnames class org.nativescript.widgets.BoxShadowDrawable
+-keepclassmembers class org.nativescript.widgets.BoxShadowDrawable {
+    public android.graphics.drawable.Drawable getWrappedDrawable();
+}

package/src/animate.ts

@@ -1,4 +1,11 @@
 import { View } from '@nativescript/core'
+import {
+  isColorProperty,
+  parseColor,
+  validateColorTarget,
+  type ColorKeyframes,
+} from './color.js'
+import { DEFAULT_FRICTION, solveDecay } from './decay.js'
 import {
   arrivalOf,
   setArrival,
@@ -9,7 +16,7 @@ import {
 } from './engine.js'
 import { getPreset, type PresetName } from './presets.js'
 import { resolveHaptic, type Haptic } from './haptics.js'
-import { isProperty, type Property } from './properties.js'
+import { isProperty, precision, type Property } from './properties.js'
 import {
   hasCurve,
   mergeTransitions,
@@ -20,6 +27,8 @@ import {
 } from './transition.js'
 import type {
   AnimateOptions,
+  DecayOptions,
+  DecayVelocity,
   Keyframes,
   KeyframeValue,
   Stagger,
@@ -56,14 +65,20 @@ export function animate(
   const feedback = resolveHaptic(haptic)
 
   if (!isList(target)) {
+    const view = toView(target)
+    for (const property of Object.keys(keyframes))
+      if (isColorProperty(property)) validateColorTarget(view, property)
     return new ViewAnimation(
-      toView(target),
+      view,
       plan(keyframes, base, overrides, 0, relative),
       feedback,
     )
   }
 
   const views = target.map(toView)
+  for (const view of views)
+    for (const property of Object.keys(keyframes))
+      if (isColorProperty(property)) validateColorTarget(view, property)
   return group(
     views.map(
       (view, index) =>
@@ -82,6 +97,77 @@ export function animate(
   )
 }
 
+/** Starts at the current translation and slows down from a velocity in DIPs per second. */
+export function decay(
+  target: Target | readonly Target[],
+  velocity: DecayVelocity,
+  options: DecayOptions = {},
+): Animation {
+  const friction = options.friction ?? DEFAULT_FRICTION
+  if (!Number.isFinite(friction) || friction <= 0 || friction >= 1) {
+    throw new RangeError('Decay friction must be between 0 and 1 exclusively.')
+  }
+
+  const stops = (values: readonly number[] | undefined) => {
+    if (values === undefined) return undefined
+    if (
+      !Array.isArray(values) ||
+      values.length === 0 ||
+      ![...values].every(Number.isFinite)
+    ) {
+      throw new RangeError('Decay snap needs a nonempty array of finite positions.')
+    }
+    return [...values]
+  }
+  const snap = options.snap
+  if (
+    snap !== undefined &&
+    !Array.isArray(snap) &&
+    (snap === null ||
+      typeof snap !== 'object' ||
+      Object.keys(snap).some((key) => key !== 'x' && key !== 'y'))
+  ) {
+    throw new TypeError('Decay snap must be an array or an object with x and y stops.')
+  }
+  const shared = Array.isArray(snap)
+  const perAxis = snap as { x?: readonly number[]; y?: readonly number[] } | undefined
+  const snapped = shared ? stops(snap) : undefined
+  const snapX = shared ? snapped : stops(perAxis?.x)
+  const snapY = shared ? snapped : stops(perAxis?.y)
+
+  const plans = Object.entries(velocity).flatMap<Plan>(([property, value]) => {
+    if (property !== 'x' && property !== 'y') {
+      throw new Error(`Can't decay "${property}". Use x or y.`)
+    }
+    if (value === undefined) return []
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`Invalid decay velocity for "${property}".`)
+    }
+    // Validate every axis before handing any plans to the engine.
+    solveDecay(0, value, friction, precision[property])
+    return [
+      {
+        property,
+        keyframes: [null, null],
+        transition: {
+          curve: {
+            type: 'decay',
+            friction,
+            velocity: value,
+            snap: property === 'x' ? snapX : snapY,
+          },
+          delay: 0,
+          repeat: 0,
+          reverse: false,
+        },
+      },
+    ]
+  })
+  const views = toViews(target)
+  if (plans.length === 0) return group([])
+  return group(views.map((view) => new ViewAnimation(view, plans)))
+}
+
 /** Stops all or selected properties at their current values. `scale` stops both axes. */
 export function stop(
   target: Target | readonly Target[],
@@ -208,7 +294,10 @@ export function startingValues(
   const { keyframes, relative } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
   return new Map(
-    expand(keyframes).map(([property, [first]]) => [property, relative ? null : first!]),
+    expand(keyframes).map(([property, [first]]) => [
+      property,
+      relative && !isColorProperty(property) ? null : first!,
+    ]),
   )
 }
 
@@ -216,7 +305,7 @@ function expand(keyframes: Keyframes): [Property, (number | null)[]][] {
   const expanded: [Property, (number | null)[]][] = []
   for (const [key, value] of Object.entries(keyframes) as [
     keyof Keyframes,
-    KeyframeValue | undefined,
+    KeyframeValue | ColorKeyframes | undefined,
   ][]) {
     if (value === undefined) continue
     if (key !== 'scale' && !isProperty(key)) throw new Error(`Can't animate "${key}".`)
@@ -230,7 +319,18 @@ function expand(keyframes: Keyframes): [Property, (number | null)[]][] {
   return expanded
 }
 
-function toKeyframes(property: Property, value: KeyframeValue): (number | null)[] {
+function toKeyframes(
+  property: Property,
+  value: KeyframeValue | ColorKeyframes,
+): (number | null)[] {
+  if (isColorProperty(property)) {
+    const frames = Array.isArray(value) ? [...value] : [null, value]
+    if (!frames.length) throw new TypeError(`Empty color keyframes for "${property}".`)
+    if (frames.length === 1) frames.unshift(null)
+    return frames.map((frame) => (frame === null ? null : parseColor(frame)))
+  }
+  if (typeof value !== 'number' && !Array.isArray(value))
+    throw new TypeError(`Invalid numeric keyframes for "${property}".`)
   const frames = typeof value === 'number' ? [null, value] : [...value]
   if (frames.length === 1) frames.unshift(null)
   if (

package/src/color.ts

@@ -0,0 +1,101 @@
+import { Button, Color, Label, TextBase, isIOS, type View } from '@nativescript/core'
+
+export type ColorProperty = 'backgroundColor' | 'borderColor' | 'color'
+export type ColorValue = string | Color
+export type ColorKeyframes = ColorValue | readonly (ColorValue | null)[]
+export const isColorProperty = (property: string): property is ColorProperty =>
+  property === 'backgroundColor' || property === 'borderColor' || property === 'color'
+
+export function parseColor(value: unknown): number {
+  if (value instanceof Color) return value.argb >>> 0
+  if (typeof value !== 'string' || !Color.isValid(value))
+    throw new TypeError(`Invalid animation color: ${String(value)}.`)
+  return new Color(value).argb >>> 0
+}
+
+export function readColor(view: View, property: ColorProperty): number {
+  const value = property === 'borderColor' ? view.borderTopColor : view[property]
+  return value instanceof Color
+    ? value.argb >>> 0
+    : property === 'backgroundColor'
+      ? 0
+      : 0xff000000
+}
+
+export function validateColorTarget(view: View, property: ColorProperty) {
+  if (
+    property === 'color' &&
+    !(isIOS ? view instanceof Label || view instanceof Button : view instanceof TextBase)
+  )
+    throw new TypeError(
+      'Text color animation requires a Label or Button on iOS, or a TextBase on Android.',
+    )
+  if (property === 'borderColor') {
+    const colors = [
+      view.borderTopColor,
+      view.borderRightColor,
+      view.borderBottomColor,
+      view.borderLeftColor,
+    ]
+    if (
+      colors.some(
+        (color) => (color?.argb ?? 0xff000000) !== (colors[0]?.argb ?? 0xff000000),
+      )
+    )
+      throw new TypeError(
+        'borderColor animation requires the same starting color on every edge.',
+      )
+  }
+}
+
+const clamp = (value: number) => Math.max(0, Math.min(1, value))
+const linear = (channel: number) =>
+  channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+const encoded = (channel: number) =>
+  channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055
+
+function lab(value: number) {
+  const r = linear(((value >>> 16) & 255) / 255)
+  const g = linear(((value >>> 8) & 255) / 255)
+  const b = linear((value & 255) / 255)
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ] as const
+}
+
+/** Premultiplied OKLab interpolation, clipped to the sRGB output gamut. */
+export function colorMixer(from: number, to: number): (progress: number) => number {
+  const a = lab(from),
+    b = lab(to)
+  const alphaA = (from >>> 24) / 255,
+    alphaB = (to >>> 24) / 255
+  return (progress) => {
+    const p = clamp(progress)
+    if (p === 0) return from
+    if (p === 1) return to
+    const alpha = alphaA + (alphaB - alphaA) * p
+    if (alpha <= 0) return 0
+    const channel = (i: number) => (a[i]! * alphaA * (1 - p) + b[i]! * alphaB * p) / alpha
+    const L = channel(0),
+      A = channel(1),
+      B = channel(2)
+    const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3
+    const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3
+    const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3
+    const r = Math.round(
+      clamp(encoded(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s)) * 255,
+    )
+    const g = Math.round(
+      clamp(encoded(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s)) * 255,
+    )
+    const blue = Math.round(
+      clamp(encoded(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)) * 255,
+    )
+    return ((Math.round(alpha * 255) << 24) | (r << 16) | (g << 8) | blue) >>> 0
+  }
+}

package/src/decay.ts

@@ -0,0 +1,45 @@
+export interface DecayMotion {
+  duration: number
+  to: number
+  position(time: number): number
+  velocity(time: number): number
+}
+
+/** Velocity retains this fraction every millisecond, independently of the display's refresh rate. */
+export const DEFAULT_FRICTION = 0.998
+
+/** Exponential motion, with velocity in units per second and time in milliseconds. */
+export function solveDecay(
+  from: number,
+  velocity: number,
+  friction: number,
+  precision: number,
+): DecayMotion {
+  const rate = -Math.log(friction)
+  const distance = velocity / (1000 * rate)
+  const to = from + distance
+  // Stop only when both the remaining distance and speed are imperceptible.
+  const duration =
+    velocity === 0
+      ? 0
+      : Math.ceil(
+          Math.max(
+            0,
+            Math.log(Math.abs(distance) / precision) / rate,
+            Math.log(Math.abs(velocity) / (precision * 10)) / rate,
+          ),
+        )
+
+  if (!Number.isFinite(to) || !Number.isFinite(duration) || duration > 2_147_483_647) {
+    throw new RangeError('Decay velocity and friction produce an unplayable motion.')
+  }
+
+  return {
+    duration,
+    to,
+    position: (time) =>
+      time >= duration ? to : from - distance * Math.expm1(-rate * Math.max(0, time)),
+    velocity: (time) =>
+      time >= duration ? 0 : velocity * Math.exp(-rate * Math.max(0, time)),
+  }
+}

package/src/driver/android-color.ts

@@ -0,0 +1,168 @@
+import { type View } from '@nativescript/core'
+import { readColor, type ColorProperty } from '../color.js'
+import type { Track } from '../track.js'
+
+interface NativeTarget {
+  getColor(): number
+  setColor(value: number): void
+  isSupported(): boolean
+}
+interface ColorHandle {
+  cancel(): void
+  elapsed(): number
+  target: NativeTarget
+}
+const playing = new WeakMap<View, Map<ColorProperty, ColorHandle>>()
+
+export function presentedAndroidColor(view: View, property: ColorProperty): number {
+  const active = playing.get(view)?.get(property)
+  if (active) return active.target.getColor() >>> 0
+  if (property === 'color' && view.nativeViewProtected instanceof android.widget.TextView)
+    return view.nativeViewProtected.getCurrentTextColor() >>> 0
+  return readColor(view, property)
+}
+
+export function playAndroidColor(
+  view: View,
+  track: Track,
+  onEnd: (finished?: boolean) => void,
+): ColorHandle {
+  const property = track.property as ColorProperty
+  const changes =
+    property === 'borderColor'
+      ? [
+          'borderTopColorChange',
+          'borderRightColorChange',
+          'borderBottomColorChange',
+          'borderLeftColorChange',
+        ]
+      : [`${property}Change`]
+  const bridge = globalThis as unknown as {
+    org: {
+      rafaelaugusto: {
+        jolt: {
+          ColorTarget: new (
+            view: android.view.View,
+            property: number,
+            color: number,
+          ) => NativeTarget
+        }
+      }
+    }
+  }
+  let target: NativeTarget
+  try {
+    target = new bridge.org.rafaelaugusto.jolt.ColorTarget(
+      view.nativeViewProtected,
+      property === 'backgroundColor' ? 0 : property === 'borderColor' ? 1 : 2,
+      track.values[0]! | 0,
+    )
+  } catch {
+    // A JS-only update cannot install the native plugin. Keep the final model.
+    onEnd(false)
+    return {
+      cancel() {},
+      elapsed: () => 0,
+      target: {
+        getColor: () => readColor(view, property),
+        setColor() {},
+        isSupported: () => false,
+      },
+    }
+  }
+  const frames = Array.create(android.animation.Keyframe, track.values.length)
+  track.values.forEach((value, index) => {
+    frames[index] = android.animation.Keyframe.ofInt(track.times[index]!, value | 0)
+  })
+  const holder = android.animation.PropertyValuesHolder.ofKeyframe('color', frames)
+  holder.setEvaluator(new android.animation.ArgbEvaluator())
+  const holders = Array.create(android.animation.PropertyValuesHolder, 1)
+  holders[0] = holder
+  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,
+    started = false,
+    queued = false
+  const cleanup = () => {
+    if (stopped) return
+    stopped = true
+    view.off('unloaded', cancel)
+    if (property === 'color') {
+      view.off('textChange', invalidate)
+      view.off('formattedTextChange', invalidate)
+    }
+    for (const name of changes) view.style.off(name, invalidate)
+    if (playing.get(view)?.get(property) === handle) playing.get(view)?.delete(property)
+  }
+  const cancel = () => {
+    if (stopped) return
+    cleanup()
+    animator.cancel()
+    onEnd(false)
+  }
+  const invalidate = () => {
+    if (stopped || queued) return
+    queued = true
+    void Promise.resolve().then(() => {
+      queued = false
+      if (!stopped) cancel()
+    })
+  }
+  const handle: ColorHandle = {
+    target,
+    elapsed: () => (started ? track.delay + animator.getCurrentPlayTime() : 0),
+    cancel() {
+      cleanup()
+      animator.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)
+    view.on('formattedTextChange', invalidate)
+  }
+  for (const name of changes) view.style.on(name, invalidate)
+  if (target.isSupported()) {
+    target.setColor(track.values[0]! | 0)
+    animator.start()
+  } else {
+    cleanup()
+    onEnd(false)
+  }
+  return handle
+}