@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/track.ts

@@ -1,10 +1,12 @@
 import { clampDecoration, isDecorationProperty } from './decoration.js'
-import { linear } from './easing.js'
+import { isBuiltinEasing, linear } from './easing.js'
+import { sampleCurve, type SampledCurve } from './sampling.js'
 import { solveDecay } from './decay.js'
+import { solveGravity } from './gravity.js'
 import { solveDragRelease } from './drag-physics.js'
 import { precision, type Property } from './properties.js'
 import { solveSpring, springPhysics } from './spring.js'
-import type { Curve, ResolvedTransition } from './transition.js'
+import type { Curve, RepeatDelayRange, ResolvedTransition } from './transition.js'
 import { colorMixer, isColorProperty, type ColorProperty } from './color.js'
 import { reducedMotion, timeScale } from './config.js'
 
@@ -28,6 +30,8 @@ export interface Track {
   readonly end: number
   /** When it looks done: a spring is close to its target and stays there, long before it settles. */
   readonly arrival: number
+  /** Setup diagnostics; absent on exact linear tracks and compound representations. */
+  readonly sampling?: SampledCurve['sampling']
   valueAt(elapsed: number): number
   /** Units per second. */
   velocityAt(elapsed: number): number
@@ -39,6 +43,7 @@ interface Motion {
   velocity(time: number): number
   times: number[]
   values: number[]
+  sampling?: SampledCurve['sampling']
 }
 
 const SAMPLES_PER_SECOND = 60
@@ -52,24 +57,34 @@ export function createTrack(
   velocity: number,
 ): Track {
   if (isColorProperty(property)) return colorTrack(property, keyframes, transition)
-  const { curve, repeat, reverse } = transition
+  const { curve } = transition
   if (property !== 'opacity' && reducedMotion())
     return instantTrack(
       property,
-      restingValue(property, keyframes, curve, repeat, reverse),
+      restingValue(property, keyframes, curve, transition.repeat, transition.reverse),
     )
   const slowdown = 1 / timeScale()
   const delay = transition.delay * slowdown
-  const motion = slow(
+  const played = slow(
     curve.type === 'spring'
       ? spring(property, keyframes, curve, velocity * slowdown, slowdown)
       : curve.type === 'drag'
-        ? dragMotion(keyframes[0]!, curve, slowdown)
+        ? dragMotion(property, keyframes[0]!, curve, slowdown)
         : curve.type === 'decay'
           ? decay(property, keyframes[0]!, curve, slowdown)
-          : tween(keyframes, curve, slowdown),
+          : curve.type === 'gravity'
+            ? gravity(property, keyframes, curve, velocity * slowdown, slowdown)
+            : tween(property, keyframes, curve, slowdown),
     slowdown,
   )
+  const { motion, repeat, reverse } = pauseBetweenRepeats(
+    played,
+    transition.repeat,
+    transition.reverse,
+    transition.repeatDelay ?? 0,
+    slowdown,
+    transition.seed,
+  )
   const { duration } = motion
   const first = motion.values[0]!
   const last = motion.values.at(-1)!
@@ -94,18 +109,25 @@ export function createTrack(
     reverse,
     times: motion.times,
     values: motion.values,
+    sampling: motion.sampling,
     to: !finite || endsBackwards ? first : last,
     end,
     arrival:
       (curve.type === 'spring' ||
         curve.type === 'drag' ||
         (curve.type === 'decay' && curve.snap !== undefined)) &&
-      repeat === 0
+      transition.repeat === 0
         ? delay + arrival(motion)
         : end,
     valueAt: (elapsed) => motion.position(localTime(elapsed)[0]),
     velocityAt: (elapsed) => {
-      if (elapsed <= delay || elapsed >= end) return 0
+      // At the exact handoff, retain the incoming spring velocity.
+      if (
+        elapsed < delay ||
+        (elapsed === delay && curve.type !== 'spring' && curve.type !== 'gravity') ||
+        elapsed >= end
+      )
+        return 0
       const [time, direction] = localTime(elapsed)
       return motion.velocity(time) * direction
     },
@@ -216,6 +238,126 @@ function colorTrack(
   }
 }
 
+/** An endless loop with drawn pauses plays this many of them, then starts over. */
+const DRAWN_CYCLES = 16
+
+/**
+ * Holds the end value for `delay` 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,
+ * or DRAWN_CYCLES cycles when the waits are drawn from a range.
+ */
+function pauseBetweenRepeats(
+  motion: Motion,
+  repeat: number,
+  reverse: boolean,
+  delay: number | RepeatDelayRange,
+  slowdown: number,
+  seed = Math.random(),
+): { motion: Motion; repeat: number; reverse: boolean } {
+  const [shortest, longest] = typeof delay === 'number' ? [delay, delay] : delay
+  if (longest <= 0 || repeat <= 0 || motion.duration === 0)
+    return { motion, repeat, reverse }
+  const draw = random(seed)
+  const pause = () => (shortest + draw() * (longest - shortest)) * slowdown
+  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 {
+    const cycles = shortest === longest ? (reverse ? 2 : 1) : DRAWN_CYCLES
+    for (let i = 0; i < cycles; i++) segments.push(play(reverse && i % 2 === 1), 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)
+  }
+
+  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
+      // A loop jumps back to its start at the end of the hold, not across it.
+      const jump = jumps ? Math.min(1, segment.duration / 10) : 0
+      times.push((start + segment.duration - jump) / 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,
+  }
+}
+
+/** Mulberry32: the same seed draws the same pauses for every track of one animation. */
+function random(seed: number) {
+  let state = Math.floor(seed * 2 ** 32) >>> 0
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0
+    let t = Math.imul(state ^ (state >>> 15), state | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 2 ** 32
+  }
+}
+
 /** Plays the same trajectory over a longer or shorter time. */
 function slow(motion: Motion, factor: number): Motion {
   if (factor === 1) return motion
@@ -238,18 +380,59 @@ function samples(duration: number, density: number) {
   )
 }
 
+function samplingProjection(property: Property) {
+  return isDecorationProperty(property)
+    ? {
+        apply: (value: number) => clampDecoration(property, value),
+        breaks: property === 'shadowOpacity' ? [0, 1] : [0],
+      }
+    : undefined
+}
+
 function dragMotion(
+  property: Property,
   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)),
+    ...sampleCurve({
+      duration: motion.duration,
+      position: motion.position,
+      tolerance: precision[property],
+      projection: samplingProjection(property),
+      slowdown: density,
+    }),
+  }
+}
+
+function gravity(
+  property: Property,
+  [from, to]: readonly number[],
+  curve: Extract<Curve, { type: 'gravity' }>,
+  velocity: number,
+  density: number,
+): Motion {
+  const motion = solveGravity(
+    from!,
+    to!,
+    curve.acceleration,
+    curve.restitution,
+    curve.velocity ?? velocity,
+    precision[property],
+  )
+  return {
+    ...motion,
+    ...sampleCurve({
+      duration: motion.duration,
+      position: motion.position,
+      tolerance: precision[property],
+      breakpoints: motion.breakpoints,
+      errorBound: motion.interpolationError,
+      slowdown: density,
+    }),
   }
 }
 
@@ -270,23 +453,32 @@ function decay(
     )
   }
 
-  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,
+    ...sampleCurve({
+      duration: motion.duration,
+      position: motion.position,
+      tolerance: precision[property],
+      projection: samplingProjection(property),
+      errorBound: motion.interpolationError,
+      slowdown: density,
+    }),
   }
-  return { ...motion, times, values }
 }
 
-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 arrival({ position, values, duration }: Motion) {
+  // Sequence timing is a compatibility contract, independent of the native representation.
+  // Retain the previous 60 Hz arrival grid without allocating its keyframe arrays.
+  const steps = samples(duration, 1),
+    target = values.at(-1)!
+  let distance = 0
+  for (let i = 0; i < steps; i++)
+    distance = Math.max(distance, Math.abs(position((i / steps) * duration) - target))
+  const tolerance = distance * ARRIVAL_TOLERANCE
+  let i = steps
+  while (i > 0 && Math.abs(position(((i - 1) / steps) * duration) - target) <= tolerance)
+    i--
+  return (i / steps) * duration
 }
 
 function spring(
@@ -303,21 +495,27 @@ function spring(
     curve.velocity ?? velocity,
     precision[property],
   )
-  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(i === steps ? to! : motion.position((i / steps) * motion.duration))
+  return {
+    ...motion,
+    ...sampleCurve({
+      duration: motion.duration,
+      position: motion.position,
+      tolerance: precision[property],
+      projection: samplingProjection(property),
+      errorBound: motion.interpolationError,
+      slowdown: density,
+    }),
   }
-  return { ...motion, times, values }
 }
 
 function tween(
+  property: Property,
   keyframes: readonly number[],
   curve: Extract<Curve, { type: 'tween' }>,
   density: number,
 ): Motion {
+  if (curve.track && curve.track !== linear)
+    return easedTrack(property, keyframes, curve, density)
   const { duration, ease } = curve
   const offsets = curve.times ?? keyframes.map((_, i) => i / (keyframes.length - 1))
 
@@ -334,16 +532,45 @@ function tween(
 
   const times = [0]
   const values = [keyframes[0]!]
+  let sampling: SampledCurve['sampling'] | undefined
   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 : 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))
+    if (easing === linear || from === to || span === 0 || duration === 0) {
+      times.push(start + span)
+      values.push(to)
+    } else {
+      const sampled = sampleCurve({
+        duration: span * duration,
+        slowdown: density,
+        tolerance: precision[property],
+        projection: samplingProjection(property),
+        custom: !isBuiltinEasing(easing),
+        position: (t) =>
+          t >= span * duration ? to : from + (to - from) * easing(t / (span * duration)),
+      })
+      sampling = sampling
+        ? {
+            ...sampled.sampling,
+            method:
+              sampling.method === 'uniform-fallback'
+                ? sampling.method
+                : sampled.sampling.method,
+            reason: sampling.reason ?? sampled.sampling.reason,
+            evaluations: sampling.evaluations + sampled.sampling.evaluations,
+          }
+        : sampled.sampling
+      for (let j = 1; j < sampled.times.length; j++) {
+        times.push(
+          j === sampled.times.length - 1
+            ? offsets[i + 1]!
+            : start + span * sampled.times[j]!,
+        )
+        values.push(sampled.values[j]!)
+      }
     }
   }
 
@@ -353,5 +580,74 @@ function tween(
     velocity: (time) => (position(time + 0.5) - position(time - 0.5)) * 1000,
     times,
     values,
+    sampling,
+  }
+}
+
+/** One easing over the whole timeline, retaining crossings of piecewise keyframe seams. */
+function easedTrack(
+  property: Property,
+  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))
+
+  // Invert each logical knot separately: even adjacent knots making a very narrow
+  // pulse must survive. Custom functions may have undetected crossings; see sampling limits.
+  const breakpoints: number[] = []
+  const probes = 64
+  const eased = Array.from({ length: probes + 1 }, (_, i) => ease(i / probes))
+  for (const offset of offsets.slice(1, -1)) {
+    for (let i = 0; i < probes; i++) {
+      const left = eased[i]!,
+        right = eased[i + 1]!
+      if (
+        offset < Math.min(left, right) ||
+        offset > Math.max(left, right) ||
+        left === right
+      )
+        continue
+      let a = i / probes,
+        b = (i + 1) / probes
+      for (let step = 0; step < 40; step++) {
+        const mid = (a + b) / 2,
+          value = ease(mid)
+        if (value < offset === left < right) a = mid
+        else b = mid
+      }
+      breakpoints.push(((a + b) / 2) * duration)
+    }
+  }
+  const sampled = sampleCurve({
+    duration,
+    slowdown: density,
+    tolerance: precision[property],
+    projection: samplingProjection(property),
+    custom: !isBuiltinEasing(ease),
+    breakpoints,
+    position: (t) => (t >= duration ? keyframes[last]! : position(t)),
+  })
+  return {
+    duration,
+    position,
+    velocity: (time) => (position(time + 0.5) - position(time - 0.5)) * 1000,
+    ...sampled,
   }
 }