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

package/src/engine.ts

@@ -0,0 +1,216 @@
+import type { View } from '@nativescript/core'
+import { getDriver } from './driver/index.js'
+import { readValue, writeValue, type Property } from './properties.js'
+import { createTrack, type Track } from './track.js'
+import type { ResolvedTransition } from './transition.js'
+
+export interface Animation extends PromiseLike<boolean> {
+  /**
+   * Resolves with `true` once the animation played to the end, or with `false`
+   * if it was stopped or another animation took over one of its properties.
+   * Never rejects.
+   */
+  readonly finished: Promise<boolean>
+  /** Stops where it is. The view keeps the values it had at that moment. */
+  stop(): void
+}
+
+export interface Plan {
+  property: Property
+  /** `null` stands for the value the property has when the animation starts. */
+  keyframes: readonly (number | null)[]
+  transition: ResolvedTransition
+  relative?: boolean
+}
+
+interface Entry {
+  readonly track: Track
+  readonly startedAt: number
+  readonly owner: ViewAnimation
+  handle: unknown
+  done: boolean
+}
+
+const running = new WeakMap<View, Map<Property, Entry>>()
+const arrivals = new WeakMap<Animation, Promise<unknown>>()
+
+/**
+ * Resolves once the animation looks done, which for a spring is well before
+ * `finished`. Sequences move on to the next step then.
+ */
+export function arrivalOf(animation: Animation): Promise<unknown> {
+  return arrivals.get(animation) ?? animation.finished
+}
+
+export function setArrival(animation: Animation, arrival: Promise<unknown>) {
+  arrivals.set(animation, arrival)
+}
+
+export class ViewAnimation implements Animation {
+  readonly finished: Promise<boolean>
+  private resolve!: (finished: boolean) => void
+  private readonly entries: Entry[] = []
+  private pending = 0
+  private complete = true
+  private settled = false
+  private cancelWait: (() => void) | undefined
+  private arrive!: () => void
+  private cancelArrival: (() => void) | undefined
+
+  constructor(
+    readonly view: View,
+    plans: readonly Plan[],
+  ) {
+    this.finished = new Promise((resolve) => (this.resolve = resolve))
+    setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
+    if (view.isLoaded && view.nativeViewProtected) this.start(plans)
+    else this.waitForLoad(plans)
+  }
+
+  then<A = boolean, B = never>(
+    onfulfilled?: ((finished: boolean) => A | PromiseLike<A>) | null,
+    onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+  ): Promise<A | B> {
+    return this.finished.then(onfulfilled, onrejected)
+  }
+
+  stop() {
+    if (this.settled) return
+    this.cancelWait?.()
+    const now = getDriver().now()
+    for (const entry of this.entries) {
+      if (!entry.done) release(entry, now, true)
+    }
+    this.complete = false
+    this.settle()
+  }
+
+  ended(finished: boolean) {
+    if (!finished) this.complete = false
+    if (--this.pending === 0) this.settle()
+  }
+
+  private start(plans: readonly Plan[]) {
+    const driver = getDriver()
+    const now = driver.now()
+    const entries = entriesOf(this.view)
+
+    const tracks = plans.map(({ property, keyframes, transition, relative }) => {
+      const previous = entries.get(property)
+      let current: number
+      let velocity = 0
+      if (previous) {
+        const elapsed = now - previous.startedAt
+        current = driver.presented(this.view, property) ?? previous.track.valueAt(elapsed)
+        velocity = previous.track.velocityAt(elapsed)
+        release(previous, now, false)
+      } else {
+        current = readValue(this.view, property)
+      }
+      return createTrack(
+        property,
+        keyframes.map((value) => {
+          if (value === null) return current
+          if (!relative) return value
+          return property === 'opacity' || property.startsWith('scale')
+            ? current * value
+            : current + value
+        }),
+        transition,
+        velocity,
+      )
+    })
+
+    for (const track of tracks) writeValue(this.view, track.property, track.to)
+
+    for (const track of tracks) {
+      if (track.end === 0) continue
+      const entry: Entry = {
+        track,
+        startedAt: now,
+        owner: this,
+        handle: undefined,
+        done: false,
+      }
+      entries.set(track.property, entry)
+      this.entries.push(entry)
+      this.pending++
+    }
+
+    for (const entry of this.entries) {
+      entry.handle = driver.play(this.view, entry.track, now, () => {
+        if (entry.done) return
+        entry.done = true
+        forget(entry)
+        this.ended(true)
+      })
+    }
+
+    const arrival = Math.max(...this.entries.map((entry) => entry.track.arrival))
+    if (this.pending === 0) this.settle()
+    else if (Number.isFinite(arrival)) {
+      this.cancelArrival = driver.after(arrival, this.arrive)
+    }
+  }
+
+  private waitForLoad(plans: readonly Plan[]) {
+    for (const { property, keyframes, relative } of plans) {
+      if (relative) continue
+      const first = keyframes[0]
+      if (first !== null && first !== undefined) writeValue(this.view, property, first)
+    }
+    const onLoaded = () => {
+      this.cancelWait?.()
+      this.start(plans)
+    }
+    this.view.on('loaded', onLoaded)
+    this.cancelWait = () => {
+      this.view.off('loaded', onLoaded)
+      this.cancelWait = undefined
+    }
+  }
+
+  private settle() {
+    if (this.settled) return
+    this.settled = true
+    this.cancelArrival?.()
+    this.arrive()
+    this.resolve(this.complete)
+  }
+}
+
+/** Stops whatever is animating these properties of the view, or all of them. */
+export function stopView(view: View, properties?: readonly Property[]) {
+  const entries = running.get(view)
+  if (!entries) return
+  const now = getDriver().now()
+  for (const [property, entry] of [...entries]) {
+    if (!properties || properties.includes(property)) release(entry, now, true)
+  }
+}
+
+function entriesOf(view: View) {
+  let entries = running.get(view)
+  if (!entries) running.set(view, (entries = new Map()))
+  return entries
+}
+
+function forget(entry: Entry) {
+  const entries = running.get(entry.owner.view)
+  if (entries?.get(entry.track.property) === entry) entries.delete(entry.track.property)
+}
+
+function release(entry: Entry, now: number, commit: boolean) {
+  const driver = getDriver()
+  const { view } = entry.owner
+  const { property } = entry.track
+  entry.done = true
+  forget(entry)
+  if (commit) {
+    const value =
+      driver.presented(view, property) ?? entry.track.valueAt(now - entry.startedAt)
+    writeValue(view, property, value)
+  }
+  driver.stop(view, entry.handle)
+  entry.owner.ended(false)
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { animate, stop } from './animate.js'
+export { sequence } from './sequence.js'
+export type { Step } from './sequence.js'
+export { press } from './press.js'
+export { definePreset, presets } from './presets.js'
+export type { Preset, PresetName, Presets } from './presets.js'
+export { springs } from './transition.js'
+export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
+export { cubicBezier } from './easing.js'
+export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
+export type { Animation } from './engine.js'
+export type * from './types.js'

package/src/presets.ts

@@ -0,0 +1,158 @@
+import type { AnimateOptions, Keyframes } from './types.js'
+
+export interface Preset {
+  keyframes: Keyframes
+  transition: AnimateOptions
+}
+
+/** Add custom preset names through module augmentation, with `true` as each value. */
+export interface Presets {}
+
+const fadeIn = { duration: 300, ease: 'easeOut' } as const
+const fadeOut = { duration: 200, ease: 'easeIn' } as const
+const enter = { type: 'spring', duration: 500, bounce: 0 } as const
+
+export const presets = {
+  fadeIn: { keyframes: { opacity: [0, 1] }, transition: fadeIn },
+  fadeInUp: {
+    keyframes: { opacity: [0, 1], y: [24, 0] },
+    transition: { ...enter, opacity: fadeIn },
+  },
+  fadeInDown: {
+    keyframes: { opacity: [0, 1], y: [-24, 0] },
+    transition: { ...enter, opacity: fadeIn },
+  },
+  fadeInLeft: {
+    keyframes: { opacity: [0, 1], x: [-24, 0] },
+    transition: { ...enter, opacity: fadeIn },
+  },
+  fadeInRight: {
+    keyframes: { opacity: [0, 1], x: [24, 0] },
+    transition: { ...enter, opacity: fadeIn },
+  },
+  zoomIn: {
+    keyframes: { opacity: [0, 1], scale: [0.85, 1] },
+    transition: { ...enter, opacity: fadeIn },
+  },
+  popIn: {
+    keyframes: { opacity: [0, 1], scale: [0.5, 1] },
+    transition: {
+      type: 'spring',
+      duration: 550,
+      bounce: 0.4,
+      opacity: { duration: 150 },
+    },
+  },
+  flipInX: {
+    keyframes: { opacity: [0, 1], rotateX: [-90, 0] },
+    transition: {
+      type: 'spring',
+      duration: 600,
+      bounce: 0.25,
+      opacity: { duration: 200 },
+    },
+  },
+  flipInY: {
+    keyframes: { opacity: [0, 1], rotateY: [90, 0] },
+    transition: {
+      type: 'spring',
+      duration: 600,
+      bounce: 0.25,
+      opacity: { duration: 200 },
+    },
+  },
+
+  fadeOut: { keyframes: { opacity: 0 }, transition: fadeOut },
+  fadeOutUp: { keyframes: { opacity: 0, y: -24 }, transition: fadeOut },
+  fadeOutDown: { keyframes: { opacity: 0, y: 24 }, transition: fadeOut },
+  fadeOutLeft: { keyframes: { opacity: 0, x: -24 }, transition: fadeOut },
+  fadeOutRight: { keyframes: { opacity: 0, x: 24 }, transition: fadeOut },
+  zoomOut: { keyframes: { opacity: 0, scale: 0.85 }, transition: fadeOut },
+  popOut: {
+    keyframes: { opacity: 0, scale: [null, 1.08, 0.4] },
+    transition: {
+      duration: 250,
+      ease: ['easeOut', 'easeIn'],
+      times: [0, 0.3, 1],
+      opacity: { duration: 250, ease: 'easeIn' },
+    },
+  },
+
+  pulse: {
+    keyframes: { scale: [1, 1.06, 1] },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
+  },
+  bounce: {
+    keyframes: { y: [0, -18, 0, -8, 0] },
+    transition: {
+      duration: 650,
+      relative: true,
+      times: [0, 0.3, 0.6, 0.8, 1],
+      ease: ['easeOut', 'easeIn', 'easeOut', 'easeIn'],
+    },
+  },
+  shake: {
+    keyframes: { x: [0, -10, 10, -8, 8, -4, 4, 0] },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
+  },
+  wiggle: {
+    keyframes: { rotate: [0, -8, 8, -5, 5, 0] },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
+  },
+  heartbeat: {
+    keyframes: { scale: [1, 1.15, 1, 1.15, 1, 1] },
+    transition: {
+      duration: 1000,
+      relative: true,
+      times: [0, 0.14, 0.28, 0.42, 0.7, 1],
+      ease: 'easeInOut',
+    },
+  },
+  jelly: {
+    keyframes: {
+      scaleX: [1, 1.25, 0.75, 1.15, 0.95, 1.05, 1],
+      scaleY: [1, 0.75, 1.25, 0.85, 1.05, 0.95, 1],
+    },
+    transition: {
+      duration: 800,
+      relative: true,
+      times: [0, 0.3, 0.4, 0.5, 0.65, 0.75, 1],
+      ease: 'easeInOut',
+    },
+  },
+  flash: {
+    keyframes: { opacity: [1, 0, 1, 0, 1] },
+    transition: { duration: 800, ease: 'easeInOut', relative: true },
+  },
+  tada: {
+    keyframes: {
+      scale: [1, 0.9, 0.9, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1],
+      rotate: [0, -3, -3, 3, -3, 3, -3, 3, -3, 3, 0],
+    },
+    transition: { duration: 1000, ease: 'easeInOut', relative: true },
+  },
+  spin: {
+    keyframes: { rotate: [0, 360] },
+    transition: { duration: 1000, ease: 'linear', relative: true },
+  },
+} satisfies Record<string, Preset>
+
+export type PresetName = keyof typeof presets | Extract<keyof Presets, string>
+
+const customPresets = new Map<string, Preset>()
+
+/** Registers a custom preset. Registering it again replaces it for future animations. */
+export function definePreset(name: PresetName, preset: Preset): void {
+  if (Object.hasOwn(presets, name)) {
+    throw new Error(`Preset "${name}" is built in and cannot be replaced.`)
+  }
+  customPresets.set(name, preset)
+}
+
+export function getPreset(name: PresetName): Preset {
+  const preset =
+    customPresets.get(name) ??
+    (Object.hasOwn(presets, name) ? presets[name as keyof typeof presets] : undefined)
+  if (!preset) throw new Error(`Unknown preset "${name}".`)
+  return preset
+}

package/src/press.ts

@@ -0,0 +1,49 @@
+import type { EventData, TouchGestureEventData } from '@nativescript/core'
+import { animate, toView } from './animate.js'
+import { isProperty, readValue, type Property } from './properties.js'
+import type { SpringName, Transition } from './transition.js'
+import type { AnimateOptions, Keyframes, Target } from './types.js'
+
+const pressIn: Transition = { type: 'spring', duration: 200, bounce: 0 }
+const release: Transition = { type: 'spring', duration: 450, bounce: 0.35 }
+
+/**
+ * Animates the view to `pressed` while a finger is on it, and back once it's lifted.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * press(button)
+ * press(card, { scale: 0.97, opacity: 0.85 })
+ * ```
+ */
+export function press(
+  target: Target,
+  pressed: Keyframes = { scale: 0.96 },
+  options?: AnimateOptions | SpringName,
+): () => void {
+  const view = toView(target)
+  const properties = Object.keys(pressed).flatMap((key): Property[] =>
+    key === 'scale' ? ['scaleX', 'scaleY'] : isProperty(key) ? [key] : [],
+  )
+  let rest: Keyframes | undefined
+
+  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)]))
+      animate(view, pressed, options ?? pressIn)
+    } else if ((action === 'up' || action === 'cancel') && rest) {
+      animate(
+        view,
+        rest,
+        typeof options === 'object'
+          ? { ...options, relative: false }
+          : (options ?? release),
+      )
+      rest = undefined
+    }
+  }
+
+  view.on('touch', onTouch)
+  return () => view.off('touch', onTouch)
+}

package/src/properties.ts

@@ -0,0 +1,51 @@
+import type { View } from '@nativescript/core'
+
+export type Property =
+  'opacity' | 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY'
+
+const viewKeys = {
+  opacity: 'opacity',
+  x: 'translateX',
+  y: 'translateY',
+  scaleX: 'scaleX',
+  scaleY: 'scaleY',
+  rotate: 'rotate',
+  rotateX: 'rotateX',
+  rotateY: 'rotateY',
+} as const satisfies Record<Property, keyof View>
+
+const defaults: Record<Property, number> = {
+  opacity: 1,
+  x: 0,
+  y: 0,
+  scaleX: 1,
+  scaleY: 1,
+  rotate: 0,
+  rotateX: 0,
+  rotateY: 0,
+}
+
+/** How close to its target a spring has to be to count as settled. */
+export const precision: Record<Property, number> = {
+  opacity: 0.002,
+  x: 0.25,
+  y: 0.25,
+  scaleX: 0.001,
+  scaleY: 0.001,
+  rotate: 0.1,
+  rotateX: 0.1,
+  rotateY: 0.1,
+}
+
+export function isProperty(key: string): key is Property {
+  return key in viewKeys
+}
+
+export function readValue(view: View, property: Property): number {
+  const value = view[viewKeys[property]]
+  return typeof value === 'number' && !Number.isNaN(value) ? value : defaults[property]
+}
+
+export function writeValue(view: View, property: Property, value: number) {
+  view[viewKeys[property]] = value
+}

package/src/sequence.ts

@@ -0,0 +1,88 @@
+import type { View } from '@nativescript/core'
+import { animate, startingValues, toViews } from './animate.js'
+import { arrivalOf, setArrival, stopView, type Animation } from './engine.js'
+import type { PresetName } from './presets.js'
+import { writeValue, type Property } from './properties.js'
+import type { SpringName } from './transition.js'
+import type { AnimateOptions, Keyframes, Target } from './types.js'
+
+export type Step =
+  | readonly [
+      target: Target | readonly Target[],
+      animation: Keyframes | PresetName,
+      options?: AnimateOptions | SpringName,
+    ]
+  | (() => Animation)
+
+/**
+ * Plays steps one after the other. A step starts once the previous one looks
+ * done: a spring is close to its target, even if it hasn't fully settled.
+ * Views in later steps take their first absolute keyframe right away, so a title
+ * that fades in third doesn't show up before its turn. Relative and null keyframes
+ * read the current value when their step starts.
+ *
+ * ```ts
+ * await sequence([
+ *   [logo, 'popIn'],
+ *   [title, 'fadeInUp'],
+ *   [buttons, 'fadeInUp', { stagger: 50 }],
+ * ])
+ * ```
+ */
+export function sequence(steps: readonly Step[]): Animation {
+  applyStartingValues(steps)
+
+  const started: Animation[] = []
+  let stopped = false
+
+  const arrived = (async () => {
+    for (const step of steps) {
+      if (stopped) return
+      const animation = typeof step === 'function' ? step() : animate(...step)
+      started.push(animation)
+      await arrivalOf(animation)
+    }
+  })()
+
+  const finished = arrived.then(async () => {
+    const results = await Promise.all(started.map((animation) => animation.finished))
+    return !stopped && results.length === steps.length && results.every(Boolean)
+  })
+
+  const animation: Animation = {
+    finished,
+    stop() {
+      stopped = true
+      started.forEach((animation) => animation.stop())
+    },
+    then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
+  }
+  setArrival(animation, arrived)
+  return animation
+}
+
+function applyStartingValues(steps: readonly Step[]) {
+  const claimed = new Map<View, Set<Property>>()
+  for (const step of steps) {
+    if (typeof step === 'function') continue
+    const [target, animation, options] = step
+    const starts = startingValues(animation, options)
+
+    for (const view of toViews(target)) {
+      let properties = claimed.get(view)
+      if (!properties) claimed.set(view, (properties = new Set()))
+
+      const fresh = [...starts].filter(
+        ([property, value]) => !properties.has(property) && value !== null,
+      )
+      stopView(
+        view,
+        fresh.map(([property]) => property),
+      )
+      for (const [property, value] of fresh) {
+        if (value !== null) writeValue(view, property, value)
+      }
+      for (const property of starts.keys()) properties.add(property)
+    }
+  }
+}

package/src/spring.ts

@@ -0,0 +1,95 @@
+export interface SpringPhysics {
+  stiffness: number
+  damping: number
+  mass: number
+}
+
+export interface SpringParams {
+  stiffness?: number
+  damping?: number
+  mass?: number
+  bounce?: number
+  duration?: number
+}
+
+export interface SpringMotion {
+  /** Milliseconds until the spring settles. */
+  duration: number
+  position(time: number): number
+  /** Units per second. */
+  velocity(time: number): number
+}
+
+const MAX_DURATION = 10_000
+const STEP = 1000 / 120
+
+export function springPhysics({
+  stiffness,
+  damping,
+  mass,
+  bounce,
+  duration,
+}: SpringParams): SpringPhysics {
+  if (stiffness !== undefined || damping !== undefined || mass !== undefined) {
+    return { stiffness: stiffness ?? 170, damping: damping ?? 26, mass: mass ?? 1 }
+  }
+
+  // The same model as SwiftUI: duration is the period of the undamped spring,
+  // bounce 0 is critically damped, negative values are overdamped.
+  const omega = (2 * Math.PI) / ((duration ?? 400) / 1000)
+  const b = Math.min(Math.max(bounce ?? 0.15, -0.99), 0.99)
+  const ratio = b >= 0 ? 1 - b : 1 / (1 + b)
+  return { stiffness: omega * omega, damping: 2 * ratio * omega, mass: 1 }
+}
+
+export function solveSpring(
+  { stiffness, damping, mass }: SpringPhysics,
+  from: number,
+  to: number,
+  velocity: number,
+  precision: number,
+): SpringMotion {
+  const x0 = from - to
+  const w0 = Math.sqrt(stiffness / mass)
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass))
+
+  let displacement: (t: number) => number
+  if (Math.abs(zeta - 1) < 1e-6) {
+    const b = velocity + w0 * x0
+    displacement = (t) => Math.exp(-w0 * t) * (x0 + b * t)
+  } else if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta)
+    const b = (velocity + zeta * w0 * x0) / wd
+    displacement = (t) =>
+      Math.exp(-zeta * w0 * t) * (x0 * Math.cos(wd * t) + b * Math.sin(wd * t))
+  } else {
+    const s = w0 * Math.sqrt(zeta * zeta - 1)
+    const r1 = -zeta * w0 + s
+    const r2 = -zeta * w0 - s
+    const c1 = (velocity - r2 * x0) / (r1 - r2)
+    const c2 = x0 - c1
+    displacement = (t) => c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t)
+  }
+
+  const position = (time: number) => to + displacement(time / 1000)
+  const speed = (time: number) => {
+    const t = time / 1000
+    return (displacement(t + 0.0005) - displacement(t - 0.0005)) / 0.001
+  }
+
+  let duration = 0
+  while (
+    duration < MAX_DURATION &&
+    (Math.abs(displacement(duration / 1000)) > precision ||
+      Math.abs(speed(duration)) > precision * 10)
+  ) {
+    duration += STEP
+  }
+  duration = Math.ceil(duration)
+
+  return {
+    duration,
+    position: (time) => (time >= duration ? to : position(time)),
+    velocity: (time) => (time >= duration ? 0 : speed(time)),
+  }
+}