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

package/src/track.ts

@@ -1,7 +1,12 @@
+import { clampDecoration, isDecorationProperty } from './decoration.js'
 import { linear } from './easing.js'
+import { solveDecay } from './decay.js'
+import { solveDragRelease } from './drag-physics.js'
 import { precision, type Property } from './properties.js'
-import { solveSpring } from './spring.js'
+import { solveSpring, springPhysics } from './spring.js'
 import type { Curve, ResolvedTransition } from './transition.js'
+import { colorMixer, isColorProperty, type ColorProperty } from './color.js'
+import { reducedMotion, timeScale } from './config.js'
 
 /**
  * One property animated over time. The curve is computed here and sampled,
@@ -37,18 +42,40 @@ interface Motion {
 }
 
 const SAMPLES_PER_SECOND = 60
+const MAX_DECAY_SAMPLES = 6000
 const ARRIVAL_TOLERANCE = 0.05
 
 export function createTrack(
   property: Property,
   keyframes: readonly number[],
-  { curve, delay, repeat, reverse }: ResolvedTransition,
+  transition: ResolvedTransition,
   velocity: number,
 ): Track {
-  const motion =
+  if (isColorProperty(property)) return colorTrack(property, keyframes, transition)
+  const { curve } = transition
+  if (property !== 'opacity' && reducedMotion())
+    return instantTrack(
+      property,
+      restingValue(property, keyframes, curve, transition.repeat, transition.reverse),
+    )
+  const slowdown = 1 / timeScale()
+  const delay = transition.delay * slowdown
+  const played = slow(
     curve.type === 'spring'
-      ? spring(property, keyframes, curve, velocity)
-      : tween(keyframes, curve)
+      ? spring(property, keyframes, curve, velocity * slowdown, slowdown)
+      : curve.type === 'drag'
+        ? dragMotion(keyframes[0]!, curve, slowdown)
+        : curve.type === 'decay'
+          ? decay(property, keyframes[0]!, curve, slowdown)
+          : tween(keyframes, curve, slowdown),
+    slowdown,
+  )
+  const { motion, repeat, reverse } = pauseBetweenRepeats(
+    played,
+    transition.repeat,
+    transition.reverse,
+    (transition.repeatDelay ?? 0) * slowdown,
+  )
   const { duration } = motion
   const first = motion.values[0]!
   const last = motion.values.at(-1)!
@@ -65,7 +92,7 @@ export function createTrack(
     return reverse && iteration % 2 === 1 ? [duration - local, -1] : [local, 1]
   }
 
-  return {
+  const track: Track = {
     property,
     delay,
     duration,
@@ -75,7 +102,13 @@ export function createTrack(
     values: motion.values,
     to: !finite || endsBackwards ? first : last,
     end,
-    arrival: curve.type === 'spring' && repeat === 0 ? delay + arrival(motion) : end,
+    arrival:
+      (curve.type === 'spring' ||
+        curve.type === 'drag' ||
+        (curve.type === 'decay' && curve.snap !== undefined)) &&
+      transition.repeat === 0
+        ? delay + arrival(motion)
+        : end,
     valueAt: (elapsed) => motion.position(localTime(elapsed)[0]),
     velocityAt: (elapsed) => {
       if (elapsed <= delay || elapsed >= end) return 0
@@ -83,6 +116,271 @@ export function createTrack(
       return motion.velocity(time) * direction
     },
   }
+  if (!isDecorationProperty(property)) return track
+  return {
+    ...track,
+    values: track.values.map((value) => clampDecoration(property, value)),
+    to: clampDecoration(property, track.to),
+    valueAt: (elapsed) => clampDecoration(property, track.valueAt(elapsed)),
+  }
+}
+
+/** Already at its end: the engine writes the value and plays nothing. */
+export function instantTrack(property: Property, value: number): Track {
+  const to = isDecorationProperty(property) ? clampDecoration(property, value) : value
+  return {
+    property,
+    delay: 0,
+    duration: 0,
+    repeat: 0,
+    reverse: false,
+    times: [0, 1],
+    values: [to, to],
+    to,
+    end: 0,
+    arrival: 0,
+    valueAt: () => to,
+    velocityAt: () => 0,
+  }
+}
+
+function restingValue(
+  property: Property,
+  keyframes: readonly number[],
+  curve: Curve,
+  repeat: number,
+  reverse: boolean,
+) {
+  const first = keyframes[0]!
+  if (!Number.isFinite(repeat) || (reverse && repeat % 2 === 1)) return first
+  if (curve.type === 'drag') return solveDragRelease(first, curve).to
+  if (curve.type !== 'decay') return keyframes.at(-1)!
+  const landing = solveDecay(
+    first,
+    curve.velocity,
+    curve.friction,
+    precision[property],
+  ).to
+  return curve.snap ? closest(curve.snap, landing) : landing
+}
+
+function closest(stops: readonly number[], target: number) {
+  return stops.reduce((best, stop) =>
+    Math.abs(stop - target) < Math.abs(best - target) ? stop : best,
+  )
+}
+
+function colorTrack(
+  property: ColorProperty,
+  colors: readonly number[],
+  transition: ResolvedTransition,
+): Track {
+  const progress = createTrack(
+    'opacity',
+    colors.map((_, i) => i),
+    transition,
+    0,
+  )
+  const mixes = colors.slice(1).map((color, i) => colorMixer(colors[i]!, color))
+  const colorAt = (position: number) => {
+    const p = Math.max(0, Math.min(colors.length - 1, position))
+    const segment = Math.min(mixes.length - 1, Math.floor(p))
+    return mixes[segment]!(p - segment)
+  }
+  // Linear timing still needs intermediate colors: native RGB interpolation is
+  // only the short bridge between these perceptually spaced samples.
+  const steps = Math.max(
+    1,
+    Math.min(
+      MAX_DECAY_SAMPLES,
+      Math.ceil((progress.duration / 1000) * SAMPLES_PER_SECOND),
+    ),
+  )
+  const times = [
+    ...new Set([
+      ...progress.times,
+      ...Array.from({ length: steps + 1 }, (_, i) => i / steps),
+    ]),
+  ].sort((a, b) => a - b)
+  return {
+    ...progress,
+    property,
+    times,
+    values: times.map((time) =>
+      colorAt(
+        time === 0
+          ? progress.values[0]!
+          : time === 1
+            ? progress.values.at(-1)!
+            : progress.valueAt(progress.delay + time * progress.duration),
+      ),
+    ),
+    to: colorAt(progress.to),
+    valueAt: (elapsed) => colorAt(progress.valueAt(elapsed)),
+    // Packed colors have no scalar velocity to carry into another spring.
+    velocityAt: () => 0,
+  }
+}
+
+/**
+ * Holds the end value for `pause` ms before each repeat, inside the keyframes, so both
+ * platforms play it natively. Finite repeats are laid out one after another, with no
+ * wait after the last; endless ones loop a cycle that waits at each turn.
+ */
+function pauseBetweenRepeats(
+  motion: Motion,
+  repeat: number,
+  reverse: boolean,
+  pause: number,
+): { motion: Motion; repeat: number; reverse: boolean } {
+  if (pause <= 0 || repeat <= 0 || motion.duration === 0)
+    return { motion, repeat, reverse }
+  type Segment = { kind: 'forward' | 'backward' | 'hold'; duration: number }
+  const play = (backward: boolean): Segment => ({
+    kind: backward ? 'backward' : 'forward',
+    duration: motion.duration,
+  })
+  const hold: Segment = { kind: 'hold', duration: pause }
+  const segments: Segment[] = []
+  if (Number.isFinite(repeat))
+    for (let i = 0; i <= repeat; i++) {
+      if (i > 0) segments.push(hold)
+      segments.push(play(reverse && i % 2 === 1))
+    }
+  else segments.push(play(false), hold, ...(reverse ? [play(true), hold] : []))
+
+  const total = segments.reduce((sum, segment) => sum + segment.duration, 0)
+  const starts = segments.map((_, i) =>
+    segments.slice(0, i).reduce((sum, segment) => sum + segment.duration, 0),
+  )
+  const last = motion.values.length - 1
+  const endOf = (i: number) => {
+    const segment = segments[i]!
+    if (segment.kind === 'forward') return motion.values[last]!
+    if (segment.kind === 'backward') return motion.values[0]!
+    return endOf(i - 1)
+  }
+  // A loop jumps back to its start at the end of the hold, not across it.
+  const jump = Math.min(1, pause / 10)
+
+  const times: number[] = []
+  const values: number[] = []
+  segments.forEach((segment, i) => {
+    const start = starts[i]!
+    if (segment.kind === 'hold') {
+      const held = endOf(i - 1)
+      const next = segments[i + 1]
+      const jumps =
+        next !== undefined &&
+        (next.kind === 'forward' ? motion.values[0] : motion.values[last]) !== held
+      times.push((start + segment.duration - (jumps ? jump : 0)) / total)
+      values.push(held)
+      return
+    }
+    for (let k = 0; k <= last; k++) {
+      const index = segment.kind === 'forward' ? k : last - k
+      const offset = motion.times[index]!
+      const time = segment.kind === 'forward' ? offset : 1 - offset
+      if (k === 0 && i > 0 && values.at(-1) === motion.values[index]) continue
+      times.push((start + time * motion.duration) / total)
+      values.push(motion.values[index]!)
+    }
+  })
+
+  const locate = (time: number) => {
+    let i = 0
+    while (i < segments.length - 1 && time >= starts[i + 1]!) i++
+    return [i, time - starts[i]!] as const
+  }
+  return {
+    motion: {
+      duration: total,
+      times,
+      values,
+      position: (time) => {
+        const [i, local] = locate(Math.max(0, Math.min(total, time)))
+        const segment = segments[i]!
+        if (segment.kind === 'hold') return endOf(i - 1)
+        return motion.position(
+          segment.kind === 'forward' ? local : motion.duration - local,
+        )
+      },
+      velocity: (time) => {
+        const [i, local] = locate(Math.max(0, Math.min(total, time)))
+        const segment = segments[i]!
+        if (segment.kind === 'hold') return 0
+        return segment.kind === 'forward'
+          ? motion.velocity(local)
+          : -motion.velocity(motion.duration - local)
+      },
+    },
+    repeat: Number.isFinite(repeat) ? 0 : Infinity,
+    reverse: false,
+  }
+}
+
+/** Plays the same trajectory over a longer or shorter time. */
+function slow(motion: Motion, factor: number): Motion {
+  if (factor === 1) return motion
+  return {
+    ...motion,
+    duration: motion.duration * factor,
+    position: (time) => motion.position(time / factor),
+    velocity: (time) => motion.velocity(time / factor) / factor,
+  }
+}
+
+/** Keyframes per second of playback, so slowed curves stay smooth. */
+function samples(duration: number, density: number) {
+  return Math.max(
+    1,
+    Math.min(
+      MAX_DECAY_SAMPLES,
+      Math.ceil(((duration * density) / 1000) * SAMPLES_PER_SECOND),
+    ),
+  )
+}
+
+function dragMotion(
+  from: number,
+  curve: Extract<Curve, { type: 'drag' }>,
+  density: number,
+): Motion {
+  const motion = solveDragRelease(from, curve)
+  const steps = samples(motion.duration, density)
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  return {
+    ...motion,
+    times,
+    values: times.map((time) => motion.position(time * motion.duration)),
+  }
+}
+
+function decay(
+  property: Property,
+  from: number,
+  curve: Extract<Curve, { type: 'decay' }>,
+  density: number,
+): Motion {
+  const motion = solveDecay(from, curve.velocity, curve.friction, precision[property])
+  if (curve.snap) {
+    return spring(
+      property,
+      [from, closest(curve.snap, motion.to)],
+      { type: 'spring', physics: springPhysics({}), velocity: curve.velocity },
+      0,
+      density,
+    )
+  }
+
+  const steps = samples(motion.duration, density)
+  const times: number[] = []
+  const values: number[] = []
+  for (let i = 0; i <= steps; i++) {
+    times.push(i / steps)
+    values.push(motion.position((i / steps) * motion.duration))
+  }
+  return { ...motion, times, values }
 }
 
 function arrival({ times, values, duration }: Motion) {
@@ -99,6 +397,7 @@ function spring(
   [from, to]: readonly number[],
   curve: Extract<Curve, { type: 'spring' }>,
   velocity: number,
+  density: number,
 ): Motion {
   const motion = solveSpring(
     curve.physics,
@@ -107,7 +406,7 @@ function spring(
     curve.velocity ?? velocity,
     precision[property],
   )
-  const steps = Math.max(1, Math.ceil((motion.duration / 1000) * SAMPLES_PER_SECOND))
+  const steps = samples(motion.duration, density)
   const times: number[] = []
   const values: number[] = []
   for (let i = 0; i <= steps; i++) {
@@ -120,7 +419,9 @@ function spring(
 function tween(
   keyframes: readonly number[],
   curve: Extract<Curve, { type: 'tween' }>,
+  density: number,
 ): Motion {
+  if (curve.track && curve.track !== linear) return easedTrack(keyframes, curve, density)
   const { duration, ease } = curve
   const offsets = curve.times ?? keyframes.map((_, i) => i / (keyframes.length - 1))
 
@@ -143,10 +444,7 @@ function tween(
     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))
+    const steps = easing === linear || from === to ? 1 : samples(span * duration, density)
     for (let step = 1; step <= steps; step++) {
       times.push(start + (span * step) / steps)
       values.push(step === steps ? to : from + (to - from) * easing(step / steps))
@@ -161,3 +459,40 @@ function tween(
     values,
   }
 }
+
+/** One easing over the whole timeline, then straight lines between keyframes, sampled evenly in time. */
+function easedTrack(
+  keyframes: readonly number[],
+  curve: Extract<Curve, { type: 'tween' }>,
+  density: number,
+): Motion {
+  const { duration, track: ease = linear } = curve
+  const offsets = curve.times ?? keyframes.map((_, i) => i / (keyframes.length - 1))
+  const last = keyframes.length - 1
+
+  // Like `interpolate`, an easing past 0 or 1 extends the first or last segment.
+  const at = (progress: number) => {
+    let i = 0
+    while (i < last - 1 && progress > offsets[i + 1]!) i++
+    const start = offsets[i]!
+    const span = offsets[i + 1]! - start
+    const from = keyframes[i]!
+    const to = keyframes[i + 1]!
+    if (span <= 0) return progress < start ? from : to
+    return from + ((to - from) * (progress - start)) / span
+  }
+  const position = (time: number) =>
+    at(ease(duration > 0 ? Math.min(Math.max(time / duration, 0), 1) : 1))
+
+  const steps = samples(duration, density)
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  return {
+    duration,
+    position,
+    velocity: (time) => (position(time + 0.5) - position(time - 0.5)) * 1000,
+    times,
+    values: times.map((time, i) =>
+      i === steps ? keyframes[last]! : position(time * duration),
+    ),
+  }
+}

package/src/transition.ts

@@ -1,6 +1,9 @@
-import { resolveEasing, type Easing, type EasingFunction } from './easing.js'
+import { linear, resolveEasing, type Easing, type EasingFunction } from './easing.js'
 import type { Property } from './properties.js'
+import { isDecorationProperty } from './decoration.js'
+import { isColorProperty } from './color.js'
 import { springPhysics, type SpringPhysics } from './spring.js'
+import type { DragCurve } from './drag-physics.js'
 
 export interface Timing {
   /** Milliseconds to wait before starting. The first keyframe is applied right away. */
@@ -9,6 +12,8 @@ export interface Timing {
   repeat?: number
   /** `reverse` plays every other repeat backwards. */
   repeatType?: 'loop' | 'reverse'
+  /** Milliseconds to hold the end value before each repeat. The first play doesn't wait. */
+  repeatDelay?: number
 }
 
 export interface Tween extends Timing {
@@ -19,6 +24,11 @@ export interface Tween extends Timing {
   ease?: Easing | readonly Easing[]
   /** Where each keyframe sits, from 0 to 1. Evenly spaced by default. */
   times?: readonly number[]
+  /**
+   * Run one `ease` over the whole track instead of each segment, with straight lines
+   * between keyframes, like React Native's `interpolate`.
+   */
+  easeTrack?: boolean
 }
 
 export interface Spring extends Timing {
@@ -45,24 +55,41 @@ export const springs: Record<SpringName, Spring> = {
 }
 
 export type Curve =
+  | DragCurve
   | {
       type: 'tween'
       duration: number
       ease: readonly EasingFunction[]
       times: readonly number[] | undefined
+      /** One easing over the whole track; `ease` is then linear per segment. */
+      track?: EasingFunction
     }
   | { type: 'spring'; physics: SpringPhysics; velocity: number | undefined }
+  | {
+      type: 'decay'
+      friction: number
+      velocity: number
+      snap: readonly number[] | undefined
+    }
 
 export interface ResolvedTransition {
   curve: Curve
   delay: number
   repeat: number
   reverse: boolean
+  repeatDelay?: number
 }
 
 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
+const curveKeys = [
+  'type',
+  'duration',
+  'ease',
+  'times',
+  'easeTrack',
+  ...springKeys,
+] as const
+const timingKeys = ['delay', 'repeat', 'repeatType', 'repeatDelay'] as const
 
 export const DEFAULT_DURATION = 300
 
@@ -96,7 +123,11 @@ export function resolveTransition(
     transition.type ??
     (springKeys.some((key) => (transition as Spring)[key] !== undefined)
       ? 'spring'
-      : hasCurve(transition) || property === 'opacity' || keyframes > 2
+      : hasCurve(transition) ||
+          property === 'opacity' ||
+          isColorProperty(property) ||
+          isDecorationProperty(property) ||
+          keyframes > 2
         ? 'tween'
         : 'spring')
 
@@ -105,9 +136,19 @@ export function resolveTransition(
   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' }
+  const repeatDelay = transition.repeatDelay ?? 0
+  if (!Number.isFinite(repeatDelay) || repeatDelay < 0)
+    throw new RangeError(`Invalid repeat delay: ${repeatDelay}.`)
+  const timing = {
+    delay,
+    repeat,
+    reverse: transition.repeatType === 'reverse',
+    ...(repeatDelay > 0 && repeat > 0 && { repeatDelay }),
+  }
 
   if (type === 'spring') {
+    if ((transition as Tween).easeTrack)
+      throw new TypeError('easeTrack applies to tweens, not springs.')
     if (keyframes > 2) {
       throw new Error(
         `A spring goes from one value to another, but "${property}" has ${keyframes} keyframes. Use a tween for keyframes.`,
@@ -122,12 +163,21 @@ export function resolveTransition(
 
   const tween = transition as Tween
   const duration = tween.duration ?? DEFAULT_DURATION
-  if (duration < 0 || Number.isNaN(duration)) {
+  if (
+    duration < 0 ||
+    Number.isNaN(duration) ||
+    ((isColorProperty(property) || isDecorationProperty(property)) &&
+      !Number.isFinite(duration))
+  ) {
     throw new RangeError(`Invalid duration: ${duration}.`)
   }
 
   const segments = keyframes - 1
   const ease = tween.ease ?? 'easeOut'
+  if (tween.easeTrack && isEasingList(ease))
+    throw new TypeError(
+      'easeTrack runs one easing over the whole track; pass a single ease.',
+    )
   const eases = isEasingList(ease) ? ease : Array.from({ length: segments }, () => ease)
   if (eases.length !== segments) {
     throw new Error(
@@ -149,6 +199,13 @@ export function resolveTransition(
     }
   }
 
+  if (tween.easeTrack) {
+    const track = resolveEasing(ease as Easing)
+    return {
+      ...timing,
+      curve: { type, duration, ease: eases.map(() => linear), times, track },
+    }
+  }
   return {
     ...timing,
     curve: { type, duration, ease: eases.map(resolveEasing), times },

package/src/types.ts

@@ -1,10 +1,35 @@
 import type { View } from '@nativescript/core'
+import type { Haptic } from './haptics.js'
 import type { SpringName, Transition } from './transition.js'
+import type { ColorKeyframes } from './color.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 {
+  /** One continuous SVG path, expressed as translation coordinates in DIPs. */
+  path?: string
+  /** Face the path's forward tangent (+X artwork). Requires path. */
+  orient?: boolean
+  backgroundColor?: ColorKeyframes
+  /** Uniform starting edge colors; widths and radii may differ. */
+  borderColor?: ColorKeyframes
+  color?: ColorKeyframes
+  /** Uniform circular corners, in DIPs. */
+  borderRadius?: KeyframeValue
+  /** Uniform visual border width, in DIPs. Content layout uses the final width. */
+  borderWidth?: KeyframeValue
+  /** iOS: opacity of one existing boxShadow, from 0 to 1. */
+  shadowOpacity?: KeyframeValue
+  /** iOS: native blur radius in DIPs (half Core's boxShadow blurRadius). */
+  shadowRadius?: KeyframeValue
+  /** iOS: offset of one existing boxShadow, in DIPs. */
+  shadowOffsetX?: KeyframeValue
+  shadowOffsetY?: KeyframeValue
+  /** Android: base elevation in DIPs. */
+  elevation?: KeyframeValue
+  /** Android: dynamic Z offset in DIPs. Native state changes may replace it. */
+  translationZ?: KeyframeValue
   opacity?: KeyframeValue
   /** Same as `translateX`, in DIPs. */
   x?: KeyframeValue
@@ -20,10 +45,31 @@ export interface Keyframes {
   rotateY?: KeyframeValue
 }
 
+/** Properties that can be timed or stopped independently. A path owns x/y and optionally rotate. */
+export type KeyframeProperty = Exclude<keyof Keyframes, 'path' | 'orient'>
+
+/** One value per property, as `set()` applies them. */
+export type Values = {
+  [K in KeyframeProperty]?: Exclude<Keyframes[K], readonly unknown[]>
+}
+
 /** A view, or anything that holds one: a NativeScript-Vue element, an Angular `ElementRef`. */
 export type Target =
   View | { readonly nativeView: View } | { readonly nativeElement: View }
 
+/** Translation velocities in DIPs per second. Omitted axes keep their current motion. */
+export interface DecayVelocity {
+  x?: number
+  y?: number
+}
+
+export interface DecayOptions {
+  /** Velocity multiplier per millisecond, between 0 and 1 exclusively. Defaults to 0.998. */
+  friction?: number
+  /** Spring to the closest stop to the projected landing, shared or set per axis. */
+  snap?: readonly number[] | { x?: readonly number[]; y?: readonly number[] }
+}
+
 export interface Stagger {
   /** Milliseconds between one target and the next. */
   each: number
@@ -32,10 +78,12 @@ export interface Stagger {
 }
 
 export type AnimateOptions = Transition & {
-  [K in keyof Keyframes]?: Transition | SpringName
+  [K in KeyframeProperty | 'path']?: Transition | SpringName
 } & {
   /** Offset translations/rotations and multiply scale/opacity by their values at the start. */
   relative?: boolean
   /** With several targets, delays each one by this much more than the previous. */
   stagger?: number | Stagger
+  /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
+  haptic?: Haptic
 }