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

package/src/track.ts

@@ -0,0 +1,163 @@
+import { linear } from './easing.js'
+import { precision, type Property } from './properties.js'
+import { solveSpring } from './spring.js'
+import type { Curve, ResolvedTransition } from './transition.js'
+
+/**
+ * One property animated over time. The curve is computed here and sampled,
+ * so the platform plays plain keyframes and nothing runs in JavaScript per frame.
+ */
+export interface Track {
+  readonly property: Property
+  readonly delay: number
+  /** One iteration, in milliseconds. */
+  readonly duration: number
+  readonly repeat: number
+  readonly reverse: boolean
+  /** Offsets from 0 to 1 within one iteration, paired with `values`. */
+  readonly times: readonly number[]
+  readonly values: readonly number[]
+  /** Where the property is left once the track is over. */
+  readonly to: number
+  /** Milliseconds from the start until the end of the last iteration. */
+  readonly end: number
+  /** When it looks done: a spring is close to its target and stays there, long before it settles. */
+  readonly arrival: number
+  valueAt(elapsed: number): number
+  /** Units per second. */
+  velocityAt(elapsed: number): number
+}
+
+interface Motion {
+  duration: number
+  position(time: number): number
+  velocity(time: number): number
+  times: number[]
+  values: number[]
+}
+
+const SAMPLES_PER_SECOND = 60
+const ARRIVAL_TOLERANCE = 0.05
+
+export function createTrack(
+  property: Property,
+  keyframes: readonly number[],
+  { curve, delay, repeat, reverse }: ResolvedTransition,
+  velocity: number,
+): Track {
+  const motion =
+    curve.type === 'spring'
+      ? spring(property, keyframes, curve, velocity)
+      : tween(keyframes, curve)
+  const { duration } = motion
+  const first = motion.values[0]!
+  const last = motion.values.at(-1)!
+  const finite = Number.isFinite(repeat)
+  const endsBackwards = reverse && finite && repeat % 2 === 1
+  const end = delay + (duration === 0 ? 0 : duration * (repeat + 1))
+
+  const localTime = (elapsed: number): [time: number, direction: number] => {
+    const time = elapsed - delay
+    if (time <= 0) return [0, 1]
+    if (time >= end - delay) return [endsBackwards ? 0 : duration, 1]
+    const iteration = Math.floor(time / duration)
+    const local = time - iteration * duration
+    return reverse && iteration % 2 === 1 ? [duration - local, -1] : [local, 1]
+  }
+
+  return {
+    property,
+    delay,
+    duration,
+    repeat,
+    reverse,
+    times: motion.times,
+    values: motion.values,
+    to: !finite || endsBackwards ? first : last,
+    end,
+    arrival: curve.type === 'spring' && repeat === 0 ? delay + arrival(motion) : end,
+    valueAt: (elapsed) => motion.position(localTime(elapsed)[0]),
+    velocityAt: (elapsed) => {
+      if (elapsed <= delay || elapsed >= end) return 0
+      const [time, direction] = localTime(elapsed)
+      return motion.velocity(time) * direction
+    },
+  }
+}
+
+function arrival({ times, values, duration }: Motion) {
+  const target = values.at(-1)!
+  const tolerance =
+    Math.max(...values.map((value) => Math.abs(value - target))) * ARRIVAL_TOLERANCE
+  let i = values.length - 1
+  while (i > 0 && Math.abs(values[i - 1]! - target) <= tolerance) i--
+  return times[i]! * duration
+}
+
+function spring(
+  property: Property,
+  [from, to]: readonly number[],
+  curve: Extract<Curve, { type: 'spring' }>,
+  velocity: number,
+): Motion {
+  const motion = solveSpring(
+    curve.physics,
+    from!,
+    to!,
+    curve.velocity ?? velocity,
+    precision[property],
+  )
+  const steps = Math.max(1, Math.ceil((motion.duration / 1000) * SAMPLES_PER_SECOND))
+  const times: number[] = []
+  const values: number[] = []
+  for (let i = 0; i <= steps; i++) {
+    times.push(i / steps)
+    values.push(i === steps ? to! : motion.position((i / steps) * motion.duration))
+  }
+  return { ...motion, times, values }
+}
+
+function tween(
+  keyframes: readonly number[],
+  curve: Extract<Curve, { type: 'tween' }>,
+): Motion {
+  const { duration, ease } = curve
+  const offsets = curve.times ?? keyframes.map((_, i) => i / (keyframes.length - 1))
+
+  const position = (time: number) => {
+    const progress = duration > 0 ? Math.min(Math.max(time / duration, 0), 1) : 1
+    let i = 0
+    while (i < offsets.length - 2 && progress > offsets[i + 1]!) i++
+    const start = offsets[i]!
+    const span = offsets[i + 1]! - start
+    const local = span > 0 ? (progress - start) / span : 1
+    const from = keyframes[i]!
+    return from + (keyframes[i + 1]! - from) * ease[i]!(local)
+  }
+
+  const times = [0]
+  const values = [keyframes[0]!]
+  for (let i = 0; i < keyframes.length - 1; i++) {
+    const start = offsets[i]!
+    const span = offsets[i + 1]! - start
+    const from = keyframes[i]!
+    const to = keyframes[i + 1]!
+    const easing = ease[i]!
+    const steps =
+      easing === linear || from === to
+        ? 1
+        : Math.max(1, Math.ceil(((span * duration) / 1000) * SAMPLES_PER_SECOND))
+    for (let step = 1; step <= steps; step++) {
+      times.push(start + (span * step) / steps)
+      values.push(step === steps ? to : from + (to - from) * easing(step / steps))
+    }
+  }
+
+  return {
+    duration,
+    position,
+    velocity: (time) => (position(time + 0.5) - position(time - 0.5)) * 1000,
+    times,
+    values,
+  }
+}

package/src/transition.ts

@@ -0,0 +1,160 @@
+import { resolveEasing, type Easing, type EasingFunction } from './easing.js'
+import type { Property } from './properties.js'
+import { springPhysics, type SpringPhysics } from './spring.js'
+
+export interface Timing {
+  /** Milliseconds to wait before starting. The first keyframe is applied right away. */
+  delay?: number
+  /** How many more times to play it. `Infinity` keeps going until stopped. */
+  repeat?: number
+  /** `reverse` plays every other repeat backwards. */
+  repeatType?: 'loop' | 'reverse'
+}
+
+export interface Tween extends Timing {
+  type?: 'tween'
+  /** Milliseconds. */
+  duration?: number
+  /** One easing, or one per segment between keyframes. */
+  ease?: Easing | readonly Easing[]
+  /** Where each keyframe sits, from 0 to 1. Evenly spaced by default. */
+  times?: readonly number[]
+}
+
+export interface Spring extends Timing {
+  type?: 'spring'
+  stiffness?: number
+  damping?: number
+  mass?: number
+  /** From -1 to 1. 0 settles without overshooting, higher values bounce more. */
+  bounce?: number
+  /** How long the spring feels, in milliseconds. Goes with `bounce`, ignored with `stiffness`, `damping` or `mass`. */
+  duration?: number
+  /** Units per second. Defaults to the velocity of the animation it interrupts. */
+  velocity?: number
+}
+
+export type Transition = Tween | Spring
+
+export type SpringName = 'smooth' | 'snappy' | 'bouncy'
+
+export const springs: Record<SpringName, Spring> = {
+  smooth: { type: 'spring', duration: 500, bounce: 0 },
+  snappy: { type: 'spring', duration: 400, bounce: 0.15 },
+  bouncy: { type: 'spring', duration: 550, bounce: 0.4 },
+}
+
+export type Curve =
+  | {
+      type: 'tween'
+      duration: number
+      ease: readonly EasingFunction[]
+      times: readonly number[] | undefined
+    }
+  | { type: 'spring'; physics: SpringPhysics; velocity: number | undefined }
+
+export interface ResolvedTransition {
+  curve: Curve
+  delay: number
+  repeat: number
+  reverse: boolean
+}
+
+const springKeys = ['stiffness', 'damping', 'mass', 'bounce', 'velocity'] as const
+const curveKeys = ['type', 'duration', 'ease', 'times', ...springKeys] as const
+const timingKeys = ['delay', 'repeat', 'repeatType'] as const
+
+export const DEFAULT_DURATION = 300
+
+export function hasCurve(transition: Transition): boolean {
+  return curveKeys.some(
+    (key) => (transition as Record<string, unknown>)[key] !== undefined,
+  )
+}
+
+export function timingOf(transition: Transition): Timing {
+  const timing: Record<string, unknown> = {}
+  for (const key of timingKeys) {
+    if (transition[key] !== undefined) timing[key] = transition[key]
+  }
+  return timing
+}
+
+/** Timing merges key by key, the curve is taken whole from whichever side has one. */
+export function mergeTransitions(base: Transition, override: Transition): Transition {
+  return hasCurve(override)
+    ? { ...timingOf(base), ...override }
+    : { ...base, ...timingOf(override) }
+}
+
+export function resolveTransition(
+  transition: Transition,
+  property: Property,
+  keyframes: number,
+): ResolvedTransition {
+  const type =
+    transition.type ??
+    (springKeys.some((key) => (transition as Spring)[key] !== undefined)
+      ? 'spring'
+      : hasCurve(transition) || property === 'opacity' || keyframes > 2
+        ? 'tween'
+        : 'spring')
+
+  const delay = transition.delay ?? 0
+  const repeat = transition.repeat ?? 0
+  if (delay < 0 || Number.isNaN(delay)) throw new RangeError(`Invalid delay: ${delay}.`)
+  if (repeat < 0 || Number.isNaN(repeat))
+    throw new RangeError(`Invalid repeat: ${repeat}.`)
+  const timing = { delay, repeat, reverse: transition.repeatType === 'reverse' }
+
+  if (type === 'spring') {
+    if (keyframes > 2) {
+      throw new Error(
+        `A spring goes from one value to another, but "${property}" has ${keyframes} keyframes. Use a tween for keyframes.`,
+      )
+    }
+    const spring = transition as Spring
+    return {
+      ...timing,
+      curve: { type, physics: springPhysics(spring), velocity: spring.velocity },
+    }
+  }
+
+  const tween = transition as Tween
+  const duration = tween.duration ?? DEFAULT_DURATION
+  if (duration < 0 || Number.isNaN(duration)) {
+    throw new RangeError(`Invalid duration: ${duration}.`)
+  }
+
+  const segments = keyframes - 1
+  const ease = tween.ease ?? 'easeOut'
+  const eases = isEasingList(ease) ? ease : Array.from({ length: segments }, () => ease)
+  if (eases.length !== segments) {
+    throw new Error(
+      `"${property}" has ${segments} segments between keyframes but ${eases.length} easings.`,
+    )
+  }
+
+  const times = tween.times
+  if (times) {
+    const valid =
+      times.length === keyframes &&
+      times[0] === 0 &&
+      times.at(-1) === 1 &&
+      times.every((time, i) => i === 0 || time >= times[i - 1]!)
+    if (!valid) {
+      throw new Error(
+        `"times" needs one value per keyframe (${keyframes}), going from 0 to 1 without going back.`,
+      )
+    }
+  }
+
+  return {
+    ...timing,
+    curve: { type, duration, ease: eases.map(resolveEasing), times },
+  }
+}
+
+function isEasingList(ease: Easing | readonly Easing[]): ease is readonly Easing[] {
+  return Array.isArray(ease) && ease.length > 0 && typeof ease[0] !== 'number'
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+import type { View } from '@nativescript/core'
+import type { SpringName, Transition } from './transition.js'
+
+/** A value to animate to, or keyframes. `null` stands for the value the view has when the animation starts. */
+export type KeyframeValue = number | readonly (number | null)[]
+
+export interface Keyframes {
+  opacity?: KeyframeValue
+  /** Same as `translateX`, in DIPs. */
+  x?: KeyframeValue
+  /** Same as `translateY`, in DIPs. */
+  y?: KeyframeValue
+  /** Sets `scaleX` and `scaleY` together. */
+  scale?: KeyframeValue
+  scaleX?: KeyframeValue
+  scaleY?: KeyframeValue
+  /** Degrees. */
+  rotate?: KeyframeValue
+  rotateX?: KeyframeValue
+  rotateY?: KeyframeValue
+}
+
+/** A view, or anything that holds one: a NativeScript-Vue element, an Angular `ElementRef`. */
+export type Target =
+  View | { readonly nativeView: View } | { readonly nativeElement: View }
+
+export interface Stagger {
+  /** Milliseconds between one target and the next. */
+  each: number
+  /** Which target starts first. */
+  from?: 'first' | 'last' | 'center' | number
+}
+
+export type AnimateOptions = Transition & {
+  [K in keyof Keyframes]?: Transition | SpringName
+} & {
+  /** With several targets, delays each one by this much more than the previous. */
+  stagger?: number | Stagger
+}