@rafaelaugusto/jolt 0.0.0-stage → 0.1.0-beta.1

package/src/animate.ts

@@ -0,0 +1,246 @@
+import { View } from '@nativescript/core'
+import {
+  arrivalOf,
+  setArrival,
+  stopView,
+  ViewAnimation,
+  type Animation,
+  type Plan,
+} from './engine.js'
+import { getPreset, type PresetName } from './presets.js'
+import { isProperty, type Property } from './properties.js'
+import {
+  hasCurve,
+  mergeTransitions,
+  resolveTransition,
+  springs,
+  type SpringName,
+  type Transition,
+} from './transition.js'
+import type {
+  AnimateOptions,
+  Keyframes,
+  KeyframeValue,
+  Stagger,
+  Target,
+} from './types.js'
+
+interface Options {
+  base: Transition
+  overrides: Partial<Record<keyof Keyframes, Transition>>
+  stagger: number | Stagger | undefined
+  relative: boolean | undefined
+}
+
+/**
+ * Animates one view, or several. Takes keyframes or the name of a preset,
+ * and a transition or the name of a spring.
+ *
+ * ```ts
+ * animate(card, 'fadeInUp')
+ * animate(card, { scale: 1.1, rotate: [0, 90] }, 'bouncy')
+ * animate(rows, 'fadeInUp', { stagger: 40 })
+ * ```
+ */
+export function animate(
+  target: Target | readonly Target[],
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+): Animation {
+  const { keyframes, base, overrides, stagger, relative } = prepare(animation, options)
+
+  if (!isList(target)) {
+    return new ViewAnimation(
+      toView(target),
+      plan(keyframes, base, overrides, 0, relative),
+    )
+  }
+
+  const views = target.map(toView)
+  return group(
+    views.map(
+      (view, index) =>
+        new ViewAnimation(
+          view,
+          plan(
+            keyframes,
+            base,
+            overrides,
+            staggerDelay(stagger, index, views.length),
+            relative,
+          ),
+        ),
+    ),
+  )
+}
+
+/** Stops all or selected properties at their current values. `scale` stops both axes. */
+export function stop(
+  target: Target | readonly Target[],
+  properties?: readonly (keyof Keyframes)[],
+) {
+  const expanded = properties?.flatMap<Property>((property) =>
+    property === 'scale' ? ['scaleX', 'scaleY'] : [property],
+  )
+  for (const view of toViews(target)) stopView(view, expanded)
+}
+
+/** Plays several animations as one: finished once they all are, and stopped together. */
+export function group(animations: readonly Animation[]): Animation {
+  const finished = Promise.all(animations.map((animation) => animation.finished)).then(
+    (results) => results.every(Boolean),
+  )
+  const animation: Animation = {
+    finished,
+    stop: () => animations.forEach((animation) => animation.stop()),
+    then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
+  }
+  setArrival(animation, Promise.all(animations.map(arrivalOf)))
+  return animation
+}
+
+export function toView(target: Target): View {
+  if (target instanceof View) return target
+  const view =
+    (target as { nativeView?: unknown } | null)?.nativeView ??
+    (target as { nativeElement?: unknown } | null)?.nativeElement
+  if (view instanceof View) return view
+  throw new TypeError(`Expected a NativeScript view, got ${String(target)}.`)
+}
+
+export function toViews(target: Target | readonly Target[]): View[] {
+  return isList(target) ? target.map(toView) : [toView(target)]
+}
+
+function isList<T>(target: T | readonly T[]): target is readonly T[] {
+  return Array.isArray(target)
+}
+
+function prepare(
+  animation: Keyframes | PresetName,
+  options?: AnimateOptions | SpringName,
+) {
+  const user = normalize(options)
+  if (typeof animation !== 'string') return { keyframes: animation, ...user }
+
+  const preset = getPreset(animation)
+  const own = normalize(preset.transition)
+  return {
+    keyframes: preset.keyframes,
+    base: mergeTransitions(own.base, user.base),
+    overrides: hasCurve(user.base)
+      ? user.overrides
+      : { ...own.overrides, ...user.overrides },
+    stagger: user.stagger ?? own.stagger,
+    relative: user.relative ?? own.relative,
+  }
+}
+
+function normalize(options: AnimateOptions | SpringName | undefined): Options {
+  if (options === undefined)
+    return { base: {}, overrides: {}, stagger: undefined, relative: undefined }
+  if (typeof options === 'string')
+    return {
+      base: spring(options),
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+    }
+
+  const base: Record<string, unknown> = {}
+  const overrides: Options['overrides'] = {}
+  let stagger: Options['stagger']
+  let relative: Options['relative']
+  for (const [key, value] of Object.entries(options)) {
+    if (value === undefined) continue
+    if (key === 'stagger') stagger = value as Options['stagger']
+    else if (key === 'relative') relative = value as Options['relative']
+    else if (key === 'scale' || isProperty(key)) {
+      overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
+    } else base[key] = value
+  }
+  return { base, overrides, stagger, relative }
+}
+
+function plan(
+  keyframes: Keyframes,
+  base: Transition,
+  overrides: Options['overrides'],
+  offset: number,
+  relative = false,
+): Plan[] {
+  return expand(keyframes).map(([property, frames]) => {
+    const override =
+      overrides[property] ?? (property.startsWith('scale') ? overrides.scale : undefined)
+    const transition = resolveTransition(
+      override ? mergeTransitions(base, override) : base,
+      property,
+      frames.length,
+    )
+    transition.delay += offset
+    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,
+  options?: AnimateOptions | SpringName,
+) {
+  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!]),
+  )
+}
+
+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,
+  ][]) {
+    if (value === undefined) 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)])
+    }
+  }
+  return expanded
+}
+
+function toKeyframes(property: Property, value: KeyframeValue): (number | null)[] {
+  const frames = typeof value === 'number' ? [null, value] : [...value]
+  if (frames.length === 1) frames.unshift(null)
+  if (
+    frames.length === 0 ||
+    frames.some((frame) => frame !== null && !Number.isFinite(frame))
+  ) {
+    throw new Error(`Invalid keyframes for "${property}": ${JSON.stringify(value)}.`)
+  }
+  return frames
+}
+
+function staggerDelay(stagger: Options['stagger'], index: number, count: number) {
+  if (stagger === undefined) return 0
+  const { each, from = 'first' } =
+    typeof stagger === 'number' ? { each: stagger } : stagger
+  const origin =
+    from === 'first'
+      ? 0
+      : from === 'last'
+        ? count - 1
+        : from === 'center'
+          ? (count - 1) / 2
+          : from
+  return each * Math.abs(index - origin)
+}
+
+function spring(name: SpringName): Transition {
+  const transition = springs[name]
+  if (!transition) throw new Error(`Unknown spring "${name}".`)
+  return transition
+}

package/src/driver/android.ts

@@ -0,0 +1,101 @@
+import { Utils, type View } from '@nativescript/core'
+import type { Property } from '../properties.js'
+import { after, type Driver } from './index.js'
+
+type NativeView = android.view.View
+
+const accessors: Record<
+  Property,
+  { get(view: NativeView): number; set(view: NativeView, value: number): void }
+> = {
+  opacity: { get: (v) => v.getAlpha(), set: (v, value) => v.setAlpha(value) },
+  x: { get: (v) => v.getTranslationX(), set: (v, value) => v.setTranslationX(value) },
+  y: { get: (v) => v.getTranslationY(), set: (v, value) => v.setTranslationY(value) },
+  scaleX: { get: (v) => v.getScaleX(), set: (v, value) => v.setScaleX(value) },
+  scaleY: { get: (v) => v.getScaleY(), set: (v, value) => v.setScaleY(value) },
+  rotate: { get: (v) => v.getRotation(), set: (v, value) => v.setRotation(value) },
+  rotateX: { get: (v) => v.getRotationX(), set: (v, value) => v.setRotationX(value) },
+  rotateY: { get: (v) => v.getRotationY(), set: (v, value) => v.setRotationY(value) },
+}
+
+const unit = (property: Property) =>
+  property === 'x' || property === 'y' ? Utils.layout.getDisplayDensity() : 1
+
+export function createAndroidDriver(): Driver {
+  const { View } = android.view
+  const nativeProperties = {
+    opacity: View.ALPHA,
+    x: View.TRANSLATION_X,
+    y: View.TRANSLATION_Y,
+    scaleX: View.SCALE_X,
+    scaleY: View.SCALE_Y,
+    rotate: View.ROTATION,
+    rotateX: View.ROTATION_X,
+    rotateY: View.ROTATION_Y,
+  } satisfies Record<Property, unknown>
+  const interpolator = new android.view.animation.LinearInterpolator()
+
+  return {
+    now: () => android.os.SystemClock.uptimeMillis(),
+
+    play(view, track, _startedAt, onEnd) {
+      const nativeView = view.nativeViewProtected as NativeView
+      const scale = unit(track.property)
+
+      const keyframes = Array.create(android.animation.Keyframe, track.values.length)
+      track.values.forEach((value, i) => {
+        keyframes[i] = android.animation.Keyframe.ofFloat(track.times[i]!, value * scale)
+      })
+      const holders = Array.create(android.animation.PropertyValuesHolder, 1)
+      holders[0] = android.animation.PropertyValuesHolder.ofKeyframe(
+        nativeProperties[track.property],
+        keyframes,
+      )
+
+      const animator = android.animation.ObjectAnimator.ofPropertyValuesHolder(
+        nativeView,
+        holders,
+      )
+      animator.setDuration(Math.max(track.duration, 1))
+      animator.setStartDelay(track.delay)
+      animator.setInterpolator(interpolator)
+      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,
+        )
+      }
+      animator.addListener(
+        new android.animation.Animator.AnimatorListener({
+          onAnimationStart() {},
+          onAnimationRepeat() {},
+          onAnimationCancel() {},
+          onAnimationEnd() {
+            onEnd()
+          },
+        }),
+      )
+
+      accessors[track.property].set(nativeView, track.values[0]! * scale)
+      animator.start()
+      return animator
+    },
+
+    stop(_view, handle) {
+      ;(handle as android.animation.ObjectAnimator).cancel()
+    },
+
+    presented(view, property) {
+      const nativeView = view.nativeViewProtected as NativeView | undefined
+      return nativeView ? accessors[property].get(nativeView) / unit(property) : undefined
+    },
+
+    after,
+  }
+}

package/src/driver/index.ts

@@ -0,0 +1,32 @@
+import { isAndroid, type View } from '@nativescript/core'
+import type { Property } from '../properties.js'
+import type { Track } from '../track.js'
+import { createAndroidDriver } from './android.js'
+import { createIOSDriver } from './ios.js'
+
+export interface Driver {
+  /** Milliseconds, on the clock the platform's animations run on. */
+  now(): number
+  /** Starts the track at `startedAt + track.delay` and calls `onEnd` once, however it ends. */
+  play(view: View, track: Track, startedAt: number, onEnd: () => void): unknown
+  stop(view: View, handle: unknown): void
+  /** The value on screen, when the platform knows it better than the track does. */
+  presented(view: View, property: Property): number | undefined
+  /** Calls back after `ms` on the same clock, and returns a function that cancels it. */
+  after(ms: number, callback: () => void): () => void
+}
+
+export function after(ms: number, callback: () => void) {
+  const timer = setTimeout(callback, ms)
+  return () => clearTimeout(timer)
+}
+
+let driver: Driver | undefined
+
+export function getDriver(): Driver {
+  return (driver ??= isAndroid ? createAndroidDriver() : createIOSDriver())
+}
+
+export function setDriver(next: Driver | undefined) {
+  driver = next
+}

package/src/driver/ios.ts

@@ -0,0 +1,97 @@
+import type { View } from '@nativescript/core'
+import type { Property } from '../properties.js'
+import { after, type Driver } from './index.js'
+
+interface Handle {
+  layers: CALayer[]
+  key: string
+  onStop?: () => void
+}
+
+const keyPaths: Record<Property, string> = {
+  opacity: 'opacity',
+  x: 'transform.translation.x',
+  y: 'transform.translation.y',
+  scaleX: 'transform.scale.x',
+  scaleY: 'transform.scale.y',
+  rotate: 'transform.rotation.z',
+  rotateX: 'transform.rotation.x',
+  rotateY: 'transform.rotation.y',
+}
+
+const radians = (degrees: number) => (degrees * Math.PI) / 180
+
+function layersOf(view: View): CALayer[] {
+  const nativeView = view.nativeViewProtected as UIView & {
+    outerShadowContainerLayer?: CALayer
+  }
+  return nativeView.outerShadowContainerLayer
+    ? [nativeView.layer, nativeView.outerShadowContainerLayer]
+    : [nativeView.layer]
+}
+
+/** A 3D rotation only looks 3D with perspective, which core leaves out once the rotation ends at 0. */
+function ensurePerspective(view: View, layers: CALayer[]) {
+  CATransaction.begin()
+  CATransaction.setDisableActions(true)
+  for (const layer of layers) {
+    const transform = layer.transform
+    if (transform.m34 === 0) {
+      transform.m34 = -1 / (view.perspective || 300)
+      layer.transform = transform
+    }
+  }
+  CATransaction.commit()
+}
+
+export function createIOSDriver(): Driver {
+  return {
+    now: () => CACurrentMediaTime() * 1000,
+
+    play(view, track, startedAt, onEnd): Handle {
+      const layers = layersOf(view)
+      const key = `jolt:${track.property}`
+      const rotation = track.property.startsWith('rotate')
+      const infinite = track.repeat === Infinity
+      if (track.property === 'rotateX' || track.property === 'rotateY') {
+        ensurePerspective(view, layers)
+      }
+
+      const animation = CAKeyframeAnimation.animationWithKeyPath(keyPaths[track.property])
+      animation.values = NSArray.arrayWithArray(
+        track.values.map((value) => (rotation ? radians(value) : value)),
+      )
+      animation.keyTimes = NSArray.arrayWithArray(track.times as number[])
+      animation.duration = Math.max(track.duration, 1) / 1000
+      animation.beginTime = (startedAt + track.delay) / 1000
+      animation.fillMode = kCAFillModeBackwards
+      // Keep infinite loops when iOS removes animations on backgrounding.
+      // They are removed explicitly when stopped or replaced.
+      animation.removedOnCompletion = !infinite
+      if (track.repeat > 0) {
+        animation.autoreverses = track.reverse
+        animation.repeatCount = track.reverse ? (track.repeat + 1) / 2 : track.repeat + 1
+      }
+
+      CATransaction.begin()
+      // iOS completes the transaction on backgrounding even if the loop is retained.
+      if (!infinite) CATransaction.setCompletionBlock(onEnd)
+      for (const layer of layers) layer.addAnimationForKey(animation, key)
+      CATransaction.commit()
+
+      return { layers, key, onStop: infinite ? onEnd : undefined }
+    },
+
+    stop(_view, handle) {
+      const playing = handle as Handle
+      const { layers, key, onStop } = playing
+      playing.onStop = undefined
+      for (const layer of layers) layer.removeAnimationForKey(key)
+      onStop?.()
+    },
+
+    presented: () => undefined,
+
+    after,
+  }
+}

package/src/easing.ts

@@ -0,0 +1,100 @@
+export type EasingFunction = (progress: number) => number
+
+export type CubicBezier = readonly [x1: number, y1: number, x2: number, y2: number]
+
+export type EasingName =
+  | 'linear'
+  | 'ease'
+  | 'easeIn'
+  | 'easeOut'
+  | 'easeInOut'
+  | 'circIn'
+  | 'circOut'
+  | 'circInOut'
+  | 'backIn'
+  | 'backOut'
+  | 'backInOut'
+  | 'anticipate'
+
+export type Easing = EasingName | CubicBezier | EasingFunction
+
+export const linear: EasingFunction = (p) => p
+
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number) {
+  if (x1 === y1 && x2 === y2) return linear
+
+  const cx = 3 * x1
+  const bx = 3 * (x2 - x1) - cx
+  const ax = 1 - cx - bx
+  const cy = 3 * y1
+  const by = 3 * (y2 - y1) - cy
+  const ay = 1 - cy - by
+
+  const sampleX = (t: number) => ((ax * t + bx) * t + cx) * t
+  const sampleY = (t: number) => ((ay * t + by) * t + cy) * t
+  const slopeX = (t: number) => (3 * ax * t + 2 * bx) * t + cx
+
+  const solveX = (x: number) => {
+    let t = x
+    for (let i = 0; i < 8; i++) {
+      const error = sampleX(t) - x
+      if (Math.abs(error) < 1e-7) return t
+      const slope = slopeX(t)
+      if (Math.abs(slope) < 1e-6) break
+      t -= error / slope
+    }
+
+    let low = 0
+    let high = 1
+    t = x
+    for (let i = 0; i < 40; i++) {
+      const value = sampleX(t)
+      if (Math.abs(value - x) < 1e-7) break
+      if (value < x) low = t
+      else high = t
+      t = (low + high) / 2
+    }
+    return t
+  }
+
+  return (p: number) => (p <= 0 ? 0 : p >= 1 ? 1 : sampleY(solveX(p)))
+}
+
+const backIn = cubicBezier(0.36, 0, 0.66, -0.56)
+const circIn: EasingFunction = (p) => 1 - Math.sqrt(1 - Math.min(p * p, 1))
+
+const reverse =
+  (easing: EasingFunction): EasingFunction =>
+  (p) =>
+    1 - easing(1 - p)
+
+const mirror =
+  (easing: EasingFunction): EasingFunction =>
+  (p) =>
+    p <= 0.5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2
+
+const easings: Record<EasingName, EasingFunction> = {
+  linear,
+  ease: cubicBezier(0.25, 0.1, 0.25, 1),
+  easeIn: cubicBezier(0.42, 0, 1, 1),
+  easeOut: cubicBezier(0, 0, 0.58, 1),
+  easeInOut: cubicBezier(0.42, 0, 0.58, 1),
+  circIn,
+  circOut: reverse(circIn),
+  circInOut: mirror(circIn),
+  backIn,
+  backOut: reverse(backIn),
+  backInOut: mirror(backIn),
+  anticipate: (p) =>
+    p <= 0.5 ? backIn(2 * p) / 2 : p >= 1 ? 1 : 1 - Math.pow(2, 10 - 20 * p) / 2,
+}
+
+export function resolveEasing(easing: Easing): EasingFunction {
+  if (typeof easing === 'function') return easing
+  if (typeof easing === 'string') {
+    const resolved = easings[easing]
+    if (!resolved) throw new Error(`Unknown easing "${easing}".`)
+    return resolved
+  }
+  return cubicBezier(...easing)
+}