@rafaelaugusto/jolt 0.1.0-beta.0 → 0.1.0-beta.10

package/src/android-plugin.d.ts

@@ -0,0 +1,155 @@
+declare namespace org.rafaelaugusto.jolt {
+  class PhotoZoom {
+    constructor(
+      image: android.widget.ImageView,
+      viewport: android.view.View,
+      bitmapWidth: number,
+      bitmapHeight: number,
+      minimum: number,
+      maximum: number,
+      doubleTap: number,
+      dismiss: boolean,
+      reduced: boolean,
+      backdrop: android.view.View | null,
+      chrome: android.view.View | null,
+      previousTouch: android.view.View.OnTouchListener | null,
+      previousImageTouch: android.view.View.OnTouchListener | null,
+      listener: PhotoZoom.Listener,
+    )
+    getX(): number
+    getY(): number
+    getScale(): number
+    getDismissProgress(): number
+    isDismissPending(): boolean
+    zoom(scale: number, x: number, y: number, animated: boolean): void
+    reset(animated: boolean): void
+    requestDismiss(): void
+    setReduced(value: boolean): void
+    setActive(value: boolean): void
+    stop(): void
+  }
+  namespace PhotoZoom {
+    class Listener {
+      constructor(implementation: {
+        onDismiss(
+          x: number,
+          y: number,
+          scale: number,
+          velocity: number,
+          progress: number,
+        ): void
+        onSettled(x: number, y: number, scale: number): void
+      })
+    }
+  }
+  class ImageEffect {
+    constructor(
+      image: android.widget.ImageView,
+      source: android.graphics.Bitmap | null,
+      destination: android.graphics.Bitmap | null,
+      geometry: androidNative.Array<number>,
+      mode: number,
+      x: number,
+      y: number,
+      amplitude: number,
+      radius: number,
+      duration: number,
+      seed: number,
+      previousTouch: android.view.View.OnTouchListener | null,
+      listener: ImageEffect.Listener,
+    )
+    isSupported(): boolean
+    getFailureReason(): string
+    getProgress(): number
+    getFrames(): number
+    getTextureBytes(): number
+    getLongestFrameNanos(): number
+    play(endpoint: number): void
+    pause(): void
+    resume(): void
+    seek(progress: number): void
+    finish(endpoint: number): void
+    stop(): void
+    stopPreservingImage(): void
+  }
+  namespace ImageEffect {
+    class Listener {
+      constructor(implementation: { onEnd(completed: boolean, progress: number): void })
+    }
+  }
+  class KeyboardFollower {
+    constructor(
+      view: android.view.View,
+      offset: number,
+      listener: KeyboardFollower.Listener,
+    )
+    attach(): void
+    detach(): void
+  }
+  namespace KeyboardFollower {
+    class Listener {
+      constructor(implementation: {
+        onStart(): void
+        onSettled(translation: number): void
+      })
+    }
+  }
+  class KeyboardObserver {
+    constructor(root: android.view.View, listener: KeyboardObserver.Listener)
+    attach(): void
+    detach(): void
+    height(): number
+  }
+  namespace KeyboardObserver {
+    class Listener {
+      constructor(implementation: {
+        onChange(height: number, duration: number, curve: ArrayLike<number> | null): void
+      })
+    }
+  }
+  class TextReveal {
+    constructor(
+      view: android.widget.TextView,
+      byWord: boolean,
+      duration: number,
+      stagger: number,
+      delay: number,
+      offset: number,
+      callback: TextReveal.Callback,
+    )
+    isSupported(): boolean
+    start(): void
+    cancel(): void
+  }
+  namespace TextReveal {
+    class Callback {
+      constructor(implementation: { onEnd(finished: boolean): void })
+    }
+  }
+  class NumberRoll {
+    constructor(
+      view: android.widget.TextView,
+      starts: androidNative.Array<number>,
+      ends: androidNative.Array<number>,
+      previous: androidNative.Array<string>,
+      direction: number,
+      times: androidNative.Array<number>,
+      values: androidNative.Array<number>,
+      duration: number,
+      delay: number,
+      stagger: number,
+      shift: number,
+      fade: number,
+      tabular: boolean,
+      callback: NumberRoll.Callback,
+    )
+    isSupported(): boolean
+    start(): void
+    cancel(): void
+  }
+  namespace NumberRoll {
+    class Callback {
+      constructor(implementation: { onEnd(finished: boolean): void })
+    }
+  }
+}

package/src/animate.ts

@@ -1,4 +1,19 @@
+import {
+  isDecorationProperty,
+  validateDecorationTarget,
+  validateDecorationFrames,
+} from './decoration.js'
+import { playbackGroup } from './playback-group.js'
+import type { PlaybackAnimation } from './playback.js'
+import { preparePath, type PreparedPath } from './path.js'
 import { View } from '@nativescript/core'
+import {
+  isColorProperty,
+  parseColor,
+  validateColorTarget,
+  type ColorKeyframes,
+} from './color.js'
+import { DEFAULT_FRICTION, solveDecay } from './decay.js'
 import {
   arrivalOf,
   setArrival,
@@ -7,8 +22,9 @@ import {
   type Animation,
   type Plan,
 } from './engine.js'
-import { presets, type PresetName } from './presets.js'
-import { isProperty, type Property } from './properties.js'
+import { getPreset, type PresetName } from './presets.js'
+import { resolveHaptic, type Haptic } from './haptics.js'
+import { isProperty, precision, type Property } from './properties.js'
 import {
   hasCurve,
   mergeTransitions,
@@ -19,16 +35,22 @@ import {
 } from './transition.js'
 import type {
   AnimateOptions,
+  DecayOptions,
+  DecayVelocity,
   Keyframes,
   KeyframeValue,
+  KeyframeProperty,
   Stagger,
   Target,
+  Values,
 } from './types.js'
 
 interface Options {
   base: Transition
-  overrides: Partial<Record<keyof Keyframes, Transition>>
+  overrides: Partial<Record<KeyframeProperty | 'path', Transition>>
   stagger: number | Stagger | undefined
+  relative: boolean | undefined
+  haptic: Haptic | undefined
 }
 
 /**
@@ -45,28 +67,158 @@ export function animate(
   target: Target | readonly Target[],
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
-): Animation {
-  const { keyframes, base, overrides, stagger } = prepare(animation, options)
+): PlaybackAnimation {
+  return prepareAnimation(target, animation, options)()
+}
+
+/** Validate and snapshot a complete animation before changing any view ownership. */
+export function prepareAnimation(
+  target: Target | readonly Target[],
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+): () => PlaybackAnimation {
+  const { keyframes, base, overrides, stagger, relative, haptic, path } = prepare(
+    animation,
+    options,
+  )
+  const feedback = resolveHaptic(haptic)
 
   if (!isList(target)) {
-    return new ViewAnimation(toView(target), plan(keyframes, base, overrides, 0))
+    const view = toView(target)
+    for (const property of Object.keys(keyframes))
+      if (isColorProperty(property)) validateColorTarget(view, property)
+      else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
+    const plans = plan(keyframes, base, overrides, 0, relative, path)
+    return () => new ViewAnimation(view, plans, feedback)
   }
 
   const views = target.map(toView)
-  return group(
-    views.map(
-      (view, index) =>
-        new ViewAnimation(
-          view,
-          plan(keyframes, base, overrides, staggerDelay(stagger, index, views.length)),
-        ),
+  for (const view of views)
+    for (const property of Object.keys(keyframes))
+      if (isColorProperty(property)) validateColorTarget(view, property)
+      else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
+  const plans = views.map((_, index) =>
+    plan(
+      keyframes,
+      base,
+      overrides,
+      staggerDelay(stagger, index, views.length),
+      relative,
+      path,
     ),
   )
+  return () =>
+    playbackGroup(
+      views.map((view, index) => new ViewAnimation(view, plans[index]!, feedback, true)),
+    )
 }
 
-/** Stops every animation running on the view, leaving it where it is. */
-export function stop(target: Target | readonly Target[]) {
-  for (const view of toViews(target)) stopView(view)
+/** 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 = {},
+): PlaybackAnimation {
+  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 playbackGroup([])
+  return playbackGroup(
+    views.map((view) => new ViewAnimation(view, plans, undefined, true)),
+  )
+}
+
+/** Stops all or selected properties at their current values. `scale` stops both axes. */
+export function stop(
+  target: Target | readonly Target[],
+  properties?: readonly KeyframeProperty[],
+) {
+  const expanded = properties?.flatMap<Property>((property) =>
+    property === 'scale' ? ['scaleX', 'scaleY'] : [property],
+  )
+  for (const view of toViews(target)) stopView(view, expanded)
+}
+
+/**
+ * Applies values at once, stopping whatever animates those properties.
+ * `scale` sets both axes. A view that isn't loaded yet gets them right away.
+ *
+ * ```ts
+ * set(logo, { opacity: 1, scale: 1, y: 0 })
+ * ```
+ */
+export function set(target: Target | readonly Target[], values: Values): void {
+  if (values === null || typeof values !== 'object' || Array.isArray(values))
+    throw new TypeError('set() takes an object of values.')
+  const keyframes: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) continue
+    if (key !== 'scale' && !isProperty(key)) throw new Error(`Can't set "${key}".`)
+    if (value === null || Array.isArray(value))
+      throw new TypeError(
+        `set() takes one value per property, got ${String(value)} for "${key}".`,
+      )
+    keyframes[key] = [value, value]
+  }
+  animate(target, keyframes as Keyframes, { duration: 0 })
 }
 
 /** Plays several animations as one: finished once they all are, and stopped together. */
@@ -103,39 +255,68 @@ function isList<T>(target: T | readonly T[]): target is readonly T[] {
 function prepare(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
+) {
+  const prepared = resolveAnimation(animation, options)
+  return {
+    ...prepared,
+    path: preparePath(prepared.keyframes, prepared.base, prepared.overrides),
+  }
+}
+
+function resolveAnimation(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
 ) {
   const user = normalize(options)
   if (typeof animation !== 'string') return { keyframes: animation, ...user }
 
-  const preset = presets[animation]
-  if (!preset) throw new Error(`Unknown preset "${animation}".`)
+  const preset = getPreset(animation)
   const own = normalize(preset.transition)
   return {
-    keyframes: preset.keyframes as Keyframes,
+    keyframes: preset.keyframes,
     base: mergeTransitions(own.base, user.base),
     overrides: hasCurve(user.base)
       ? user.overrides
       : { ...own.overrides, ...user.overrides },
-    stagger: user.stagger,
+    stagger: user.stagger ?? own.stagger,
+    relative: user.relative ?? own.relative,
+    haptic: user.haptic ?? own.haptic,
   }
 }
 
 function normalize(options: AnimateOptions | SpringName | undefined): Options {
-  if (options === undefined) return { base: {}, overrides: {}, stagger: undefined }
+  if (options === undefined)
+    return {
+      base: {},
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
   if (typeof options === 'string')
-    return { base: spring(options), overrides: {}, stagger: undefined }
+    return {
+      base: spring(options),
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
 
   const base: Record<string, unknown> = {}
   const overrides: Options['overrides'] = {}
   let stagger: Options['stagger']
+  let relative: Options['relative']
+  let haptic: Options['haptic']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
     if (key === 'stagger') stagger = value as Options['stagger']
-    else if (key === 'scale' || isProperty(key)) {
+    else if (key === 'relative') relative = value as Options['relative']
+    else if (key === 'haptic') haptic = value as Options['haptic']
+    else if (key === 'path' || key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger }
+  return { base, overrides, stagger, relative, haptic }
 }
 
 function plan(
@@ -143,8 +324,26 @@ function plan(
   base: Transition,
   overrides: Options['overrides'],
   offset: number,
+  relative = false,
+  path?: PreparedPath,
 ): Plan[] {
-  return expand(keyframes).map(([property, frames]) => {
+  return expand(keyframes, path).map(([property, frames]) => {
+    if (path?.properties.includes(property as 'x' | 'y' | 'rotate')) {
+      if (
+        !Number.isFinite(path.transition.delay + offset) ||
+        path.transition.delay + offset < 0
+      )
+        throw new RangeError(
+          'Path delays, including stagger, must be finite and nonnegative.',
+        )
+      return {
+        property,
+        keyframes: frames,
+        transition: { ...path.transition, delay: path.transition.delay + offset },
+        relative,
+        path,
+      }
+    }
     const override =
       overrides[property] ?? (property.startsWith('scale') ? overrides.scale : undefined)
     const transition = resolveTransition(
@@ -153,39 +352,79 @@ function plan(
       frames.length,
     )
     transition.delay += offset
-    return { property, keyframes: frames, transition }
+    return { property, keyframes: frames, transition, relative }
   })
 }
 
 /** Each property the animation touches, with the value it starts from when it sets one. */
-export function startingValues(animation: Keyframes | PresetName) {
-  const keyframes =
-    typeof animation === 'string' ? presets[animation]?.keyframes : animation
+export function startingValues(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+) {
+  const { keyframes, relative, path } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
   return new Map(
-    expand(keyframes as Keyframes).map(([property, [first]]) => [property, first!]),
+    expand(keyframes, path).map(([property, [first]]) => [
+      property,
+      relative && !isColorProperty(property) ? null : first!,
+    ]),
   )
 }
 
-function expand(keyframes: Keyframes): [Property, (number | null)[]][] {
+/** Each property the animation touches, with the value it leaves behind when that is known up front. */
+export function endingValues(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+) {
+  const { keyframes, base, overrides, relative, path } = prepare(animation, options)
+  return new Map(
+    plan(keyframes, base, overrides, 0, relative, path).map(
+      ({ property, keyframes: frames, transition, path: owned }) => {
+        const finite = Number.isFinite(transition.repeat)
+        const backwards = transition.reverse && finite && transition.repeat % 2 === 1
+        const unknown = owned !== undefined || (relative && !isColorProperty(property))
+        const frame = !finite || backwards ? frames[0] : frames.at(-1)
+        return [property, unknown ? null : frame!]
+      },
+    ),
+  )
+}
+
+function expand(
+  keyframes: Keyframes,
+  path?: PreparedPath,
+): [Property, (number | null)[]][] {
   const expanded: [Property, (number | null)[]][] = []
-  for (const [key, value] of Object.entries(keyframes) as [
-    keyof Keyframes,
-    KeyframeValue | undefined,
-  ][]) {
-    if (value === undefined) continue
+  for (const [key, value] of Object.entries(keyframes)) {
+    if (value === undefined || key === 'path' || key === 'orient') continue
     if (key !== 'scale' && !isProperty(key)) throw new Error(`Can't animate "${key}".`)
 
     const properties: Property[] = key === 'scale' ? ['scaleX', 'scaleY'] : [key]
     for (const property of properties) {
       if (key === 'scale' && keyframes[property] !== undefined) continue
-      expanded.push([property, toKeyframes(property, value)])
+      expanded.push([
+        property,
+        toKeyframes(property, value as KeyframeValue | ColorKeyframes),
+      ])
     }
   }
+  for (const [property, value] of path?.starts ?? [])
+    expanded.push([property, [value, value]])
   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 (
@@ -194,6 +433,7 @@ function toKeyframes(property: Property, value: KeyframeValue): (number | null)[
   ) {
     throw new Error(`Invalid keyframes for "${property}": ${JSON.stringify(value)}.`)
   }
+  if (isDecorationProperty(property)) validateDecorationFrames(property, frames)
   return frames
 }
 

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
+  }
+}