@rafaelaugusto/jolt 0.1.0-beta.12 → 0.1.0-beta.14

package/src/motion-value.ts

@@ -20,14 +20,7 @@ import {
   validateDecorationTarget,
 } from './decoration.js'
 import { getDriver } from './driver/index.js'
-import {
-  setArrival,
-  setBase,
-  stopBase,
-  ViewAnimation,
-  type Animation,
-  type Plan,
-} from './engine.js'
+import { setBase, stopBase, ViewAnimation, type Animation, type Plan } from './engine.js'
 import { linear } from './easing.js'
 import { isProperty, type Property } from './properties.js'
 import { createTrack, instantTrack, type Track } from './track.js'
@@ -39,19 +32,32 @@ import {
   type Transition,
 } from './transition.js'
 import type { KeyframeProperty, Target } from './types.js'
+import { playbackSource, type PlaybackAnimation, type PlaybackClock } from './playback.js'
+import { TimedAnimation } from './timed-animation.js'
+import { valueTrack } from './value-track.js'
+import {
+  ValueObservers,
+  type SubscribeOptions,
+  type ValueListener,
+} from './value-observers.js'
 
 export interface MapOptions {
   /** Hold the first and last outputs outside the input range. Defaults to `true`. */
   clamp?: boolean
 }
 
+/** Named motion value layers add scalar offsets before derived mappings. */
+export type ValueAnimationOptions = Transition & { layer?: string }
+
 declare const motionValueBrand: unique symbol
 
 /** A number derived from a motion value, ready to bind to a view. */
 export interface DerivedValue {
   /** The value now, while it animates too. */
   get(): number
-  /** Maps through input and output ranges, like React Native's `interpolate`. */
+  /** Observe changes in JavaScript on the native frame clock. Unsubscribe when finished. */
+  subscribe(listener: ValueListener<number>, options?: SubscribeOptions): () => void
+  /** Maps through ascending or descending input ranges, like React Native's `interpolate`. */
   to(
     input: readonly number[],
     output: readonly number[],
@@ -63,6 +69,8 @@ export interface DerivedValue {
 /** A color derived from a motion value, for `backgroundColor`, `borderColor` or `color`. */
 export interface DerivedColor {
   get(): Color
+  /** Observe mapped color changes in JavaScript on the native frame clock. */
+  subscribe(listener: ValueListener<Color>, options?: SubscribeOptions): () => void
 }
 
 /** A number that animates natively and drives every view property bound to it. */
@@ -88,12 +96,13 @@ interface Run {
   readonly track: Track
   readonly base: number
   readonly span: number
-  readonly animation: Animation
+  readonly animation: TimedAnimation
   readonly startedAt: number
-  readonly settle: (finished: boolean) => void
-  readonly cancel: () => void
+  readonly clock?: Pick<PlaybackClock, 'time'>
 }
 
+type Presentation = Pick<Run, 'track' | 'base' | 'span' | 'startedAt' | 'clock'>
+
 const bound = new WeakMap<View, Map<Property, Binding>>()
 
 class Derived {
@@ -112,6 +121,10 @@ class Derived {
     return this.color ? new Color(value) : value
   }
 
+  subscribe(listener: ValueListener<number | Color>, options?: SubscribeOptions) {
+    return this.root.observers.subscribe(this.read, this.color, listener, options)
+  }
+
   to(
     input: readonly number[],
     output: readonly (number | ColorValue)[],
@@ -126,46 +139,71 @@ class Derived {
 
 class Root extends Derived {
   readonly bindings = new Set<Binding>()
-  private current: number
-  private run: Run | undefined
+  readonly listeners = new Set<() => void>()
+  readonly observers = new ValueObservers((time) => this.raw(time))
+  private readonly rests = new Map<string, number>()
+  private readonly runs = new Map<string, Run>()
+  private presentation: Presentation | undefined
+  private cancelPresentation: (() => void) | undefined
 
   constructor(initial: number) {
     super(undefined, (value) => value, false)
     if (!Number.isFinite(initial))
       throw new RangeError(`A motion value starts from a finite number, got ${initial}.`)
-    this.current = initial
+    this.rests.set('', initial)
+  }
+
+  raw(time = getDriver().now()): number {
+    let result = 0
+    for (const key of new Set([...this.rests.keys(), ...this.runs.keys()]))
+      result += this.part(key, time)
+    return result
+  }
+
+  /** Drag input owns only the base; bounds and snap points stay in base units. */
+  base(): number {
+    return this.part('')
+  }
+
+  private part(key: string, time = getDriver().now()): number {
+    const run = this.runs.get(key)
+    return run
+      ? run.base + run.span * run.track.valueAt(this.runTime(run, time))
+      : (this.rests.get(key) ?? 0)
   }
 
-  raw(): number {
-    const run = this.run
-    if (!run) return this.current
-    return run.base + run.span * run.track.valueAt(getDriver().now() - run.startedAt)
+  private runTime(run: Presentation, time = getDriver().now()) {
+    return run.clock?.time() ?? time - run.startedAt
   }
 
-  private velocity(): number {
-    const run = this.run
-    if (!run) return 0
-    return run.span * run.track.velocityAt(getDriver().now() - run.startedAt)
+  private velocity(key: string): number {
+    const run = this.runs.get(key)
+    if (!run || run.animation.paused) return 0
+    return run.span * run.track.velocityAt(this.runTime(run))
   }
 
   animate(
     target: number | readonly (number | null)[],
-    transition: Transition | SpringName = {},
-  ): Animation {
-    const from = this.raw()
+    transition: ValueAnimationOptions | SpringName = {},
+  ): PlaybackAnimation {
+    const options: ValueAnimationOptions =
+      typeof transition === 'string' ? springOf(transition) : transition
+    const key = options.layer === undefined ? '' : layerName(options.layer)
+    const from = this.part(key)
     const frames = (typeof target === 'number' ? [null, target] : [...target]).map(
       (frame) => (frame === null ? from : frame),
     )
     if (frames.length < 2) frames.unshift(from)
     if (frames.some((frame) => typeof frame !== 'number' || !Number.isFinite(frame)))
       throw new RangeError(`Invalid motion value keyframes: ${JSON.stringify(target)}.`)
-    const options = typeof transition === 'string' ? springOf(transition) : transition
     const resolved = resolveTransition(options, 'x', frames.length)
     const base = Math.min(...frames)
     const span = Math.max(...frames) - base
-    const velocity = this.velocity()
-    this.halt()
-    if (span === 0) return this.jump(frames.at(-1)!)
+    const velocity = this.velocity(key)
+    if (span === 0) {
+      this.halt(key)
+      return this.jump(frames.at(-1)!, key)
+    }
 
     // Sampled in the value's own range so springs settle relative to the distance.
     const track = createTrack(
@@ -174,99 +212,158 @@ class Root extends Derived {
       resolved,
       velocity / span,
     )
-    return this.start(track, base, span)
+    this.halt(key)
+    return track.end === 0
+      ? this.jump(base + span * track.to, key)
+      : this.start(track, base, span, key)
   }
 
   /** Plays a track sampled in the value's own units, such as a drag release. */
-  play(track: Track): Animation {
-    this.halt()
-    return track.end === 0 ? this.jump(track.to) : this.start(track, 0, 1)
+  play(track: Track): PlaybackAnimation {
+    this.halt('')
+    return track.end === 0 ? this.jump(track.to, '') : this.start(track, 0, 1, '')
   }
 
-  private jump(value: number): Animation {
-    const { animation, settle } = this.handle()
-    this.current = value
-    for (const binding of this.bindings) binding.sync()
-    settle(true)
-    setArrival(animation, Promise.resolve())
+  private jump(value: number, key: string): PlaybackAnimation {
+    this.rests.set(key, value)
+    this.sync()
+    const animation = new TimedAnimation(
+      0,
+      0,
+      () => {},
+      () => {},
+    )
+    animation.start()
     return animation
   }
 
-  private handle() {
-    let settle!: (finished: boolean) => void
-    const finished = new Promise<boolean>((resolve) => (settle = resolve))
-    const animation: Animation = {
-      finished,
-      stop: () => {
-        if (this.run?.animation === animation) this.stop()
-      },
-      then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
-    }
-    return { animation, settle }
-  }
-
-  private start(track: Track, base: number, span: number): Animation {
-    const { animation, settle } = this.handle()
-    let arrive: () => void = () => {}
-    let run: Run | undefined
+  private start(
+    track: Track,
+    base: number,
+    span: number,
+    key: string,
+  ): PlaybackAnimation {
     const driver = getDriver()
-    setArrival(animation, new Promise<void>((resolve) => (arrive = resolve)))
-    const timers = [
-      Number.isFinite(track.end)
-        ? driver.after(track.end, () => {
-            if (this.run !== run) return
-            this.current = base + span * track.to
-            this.run = undefined
-            arrive()
-            settle(true)
-          })
-        : undefined,
-      Number.isFinite(track.arrival)
-        ? driver.after(track.arrival, () => arrive())
-        : undefined,
-    ]
-    this.run = run = {
+    const animation = new TimedAnimation(
+      track.end,
+      track.arrival,
+      () => this.sync(),
+      (completed) => {
+        if (this.runs.get(key)?.animation !== animation) return
+        const held = base + span * track.valueAt(animation.time)
+        this.runs.delete(key)
+        if (!completed && key !== '') this.rests.delete(key)
+        else this.rests.set(key, completed ? base + span * track.to : held)
+        this.sync()
+      },
+    )
+    const run: Run = {
       track,
       base,
       span,
       animation,
       startedAt: driver.now(),
-      settle: (completed) => {
-        arrive()
-        settle(completed)
-      },
-      cancel: () => timers.forEach((cancel) => cancel?.()),
+      clock: { time: () => animation.time },
     }
-    for (const binding of this.bindings) binding.sync()
+    this.runs.set(key, run)
+    this.sync()
+    animation.start()
     return animation
   }
 
   set(value: number) {
     if (!Number.isFinite(value))
       throw new RangeError(`A motion value takes a finite number, got ${value}.`)
-    this.halt()
-    this.current = value
-    for (const binding of this.bindings) binding.sync()
+    for (const key of [...this.runs.keys()]) this.halt(key)
+    this.rests.clear()
+    this.rests.set('', value)
+    this.sync()
+  }
+
+  setBase(value: number) {
+    if (!Number.isFinite(value))
+      throw new RangeError('A motion value takes a finite number.')
+    this.halt('')
+    this.rests.set('', value)
+    this.sync()
+  }
+
+  stopBase() {
+    this.stopChannel('')
   }
 
-  stop() {
-    if (!this.run) return
+  stop(layer?: string) {
+    if (layer !== undefined) return this.stopChannel(layerName(layer))
+    if (!this.runs.size && this.rests.size === 1) return
     const value = this.raw()
-    this.halt()
-    this.current = value
+    for (const key of [...this.runs.keys()]) this.halt(key)
+    this.rests.clear()
+    this.rests.set('', value)
+    this.sync()
+  }
+
+  private stopChannel(key: string) {
+    if (!this.runs.has(key) && (key === '' || !this.rests.has(key))) return
+    const held = this.part(key)
+    this.halt(key)
+    if (key === '') this.rests.set(key, held)
+    else this.rests.delete(key)
+    this.sync()
+  }
+
+  private sync() {
+    this.cancelPresentation?.()
+    this.cancelPresentation = undefined
+    const now = getDriver().now()
+    let rest = 0
+    for (const [key, value] of this.rests) if (!this.runs.has(key)) rest += value
+    const runs = [...this.runs.values()].filter((run) => !run.animation.paused)
+    for (const [key, run] of this.runs)
+      if (run.animation.paused) rest += this.part(key, now)
+    if (!runs.length) this.presentation = undefined
+    else if (runs.length === 1) {
+      const run = runs[0]!
+      this.presentation = { ...run, base: run.base + rest }
+    } else {
+      const { track, windowed } = valueTrack(
+        runs.map((run) => ({
+          track: run.track,
+          base: run.base,
+          span: run.span,
+          elapsed: this.runTime(run, now),
+        })),
+        rest,
+      )
+      const driver = getDriver()
+      const clock = driver.clock?.(track.end)
+      this.presentation = { track, base: 0, span: 1, startedAt: now, clock }
+      const cancelWindow = windowed
+        ? driver.after(track.end, () => this.sync())
+        : undefined
+      this.cancelPresentation = () => {
+        cancelWindow?.()
+        clock?.cancel()
+      }
+    }
+    this.changed()
+  }
+
+  protected changed() {
     for (const binding of this.bindings) binding.sync()
+    for (const listener of [...this.listeners]) listener()
+    this.observers.changed(this.running)
   }
 
   /** The plan that plays this value's run, mapped, on one bound property. */
   plan(binding: Binding): Plan {
-    const run = this.run
+    const run = this.presentation
     const { property, read } = binding
     const write = (value: number) =>
       isDecorationProperty(property)
         ? clampDecoration(property, read(value))
         : read(value)
     if (!run) {
-      const value = write(this.current)
+      const value = write(this.raw())
       return {
         property,
         keyframes: [],
@@ -312,23 +409,38 @@ class Root extends Derived {
     return { property, keyframes: [], transition, track: mapped }
   }
 
+  /** Capture the current native presentation clock, even if a later command replaces it. */
+  captureTime(): () => number {
+    const run = this.presentation
+    return run ? () => this.runTime(run) : () => 0
+  }
+
   elapsed(): number {
-    return this.run ? getDriver().now() - this.run.startedAt : 0
+    return this.presentation ? this.runTime(this.presentation) : 0
+  }
+
+  get paused(): boolean {
+    return this.runs.size > 0 && !this.running
   }
 
   get running(): boolean {
-    return this.run !== undefined
+    return [...this.runs.values()].some((run) => !run.animation.paused)
   }
 
-  private halt() {
-    const run = this.run
+  private halt(key: string) {
+    const run = this.runs.get(key)
     if (!run) return
-    this.run = undefined
-    run.cancel()
-    run.settle(false)
+    this.runs.delete(key)
+    run.animation.stop()
   }
 }
 
+function layerName(name: string): string {
+  if (typeof name !== 'string' || !name.length)
+    throw new TypeError('A layer is named by a nonempty string.')
+  return name
+}
+
 const still: ResolvedTransition = {
   curve: { type: 'tween', duration: 0, ease: [linear], times: undefined },
   delay: 0,
@@ -424,9 +536,13 @@ function attach(view: View, property: Property, source: Derived) {
           getDriver().sync?.(view)
         return
       }
-      const elapsed = root.elapsed()
       const animation = new ViewAnimation(view, [root.plan(binding)])
-      if (elapsed > 1 && animation.duration > 0) animation.seekTime(elapsed)
+      // Native keyframe setup can take time, especially for a composite track on Android.
+      // Catch up after construction so each binding joins the source's current phase.
+      const elapsed = root.elapsed()
+      if (root.paused) animation.pause()
+      if ((elapsed > 1 || root.paused) && animation.duration > 0)
+        animation.seekTime(elapsed)
       binding.animation = animation
     },
   }
@@ -444,6 +560,155 @@ function attach(view: View, property: Property, source: Derived) {
   }
 }
 
+/** A read-only value on an existing finite animation's clock. No second animation or timer. */
+export function playbackProgress(animation: Animation): DerivedValue {
+  const source = playbackSource(animation)
+  if (!Number.isFinite(source.read().duration))
+    throw new RangeError('Progress requires a finite animation.')
+  const root = new PlaybackValue(source)
+  return new Derived(root, (value) => value, false) as unknown as DerivedValue
+}
+
+class PlaybackValue extends Root {
+  constructor(private readonly playback: ReturnType<typeof playbackSource>) {
+    super(0)
+    const source = playback
+    const off = source.subscribe(() => {
+      this.changed()
+      if (source.read().settled) off()
+    })
+    if (source.read().settled) off()
+    this.observers.changed(this.running)
+  }
+
+  override raw() {
+    const state = this.playback.read()
+    return (
+      state.position ??
+      (state.completed
+        ? 1
+        : state.duration > 0
+          ? Math.max(0, Math.min(1, state.time / state.duration))
+          : 0)
+    )
+  }
+
+  override get running() {
+    const state = this.playback.read()
+    return state.ready && !state.settled && !state.paused && state.duration > 0
+  }
+
+  override get paused() {
+    return this.playback.read().paused
+  }
+  override captureTime() {
+    return () => this.playback.read().time
+  }
+  override elapsed() {
+    return this.playback.read().time
+  }
+
+  override plan(binding: Binding): Plan {
+    const state = this.playback.read()
+    if (!state.ready || state.settled || state.duration === 0)
+      return {
+        property: binding.property,
+        keyframes: [],
+        transition: still,
+        track: () => instantTrack(binding.property, binding.read(this.raw())),
+      }
+    // Bypass timeScale: the source duration is already in platform playback milliseconds.
+    const duration = state.duration
+    const at = (ms: number) => binding.read(Math.max(0, Math.min(1, ms / duration)))
+    const track: Track = {
+      property: binding.property,
+      delay: 0,
+      duration,
+      repeat: 0,
+      reverse: false,
+      times: [0, 1],
+      values: [at(0), at(duration)],
+      to: at(duration),
+      end: duration,
+      arrival: duration,
+      valueAt: at,
+      velocityAt: (ms) => (at(ms + 0.5) - at(ms - 0.5)) * 1000,
+    }
+    // Piecewise/color derivations need intermediate samples, not only the two endpoints.
+    const steps = Math.max(1, Math.min(6000, Math.ceil((duration * 60) / 1000)))
+    const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+    return {
+      property: binding.property,
+      keyframes: [],
+      transition: still,
+      track: () =>
+        reducedMotion() &&
+        binding.property !== 'opacity' &&
+        !isColorProperty(binding.property)
+          ? instantTrack(binding.property, at(duration))
+          : { ...track, times, values: times.map((time) => at(time * duration)) },
+    }
+  }
+}
+
+/** Internal compound-binding bridge. One raw snapshot per root keeps sibling mappings coherent. */
+export function valueSource(source: DerivedValue | DerivedColor, color: boolean) {
+  if (!(source instanceof Derived) || source.color !== color)
+    throw new TypeError(
+      `Gradient component needs a ${color ? 'color' : 'numeric'} Jolt value.`,
+    )
+  const { root, read } = source
+  return {
+    identity: root,
+    read,
+    snapshot() {
+      return {
+        track: root.plan({ property: 'opacity', read: (value) => value } as Binding)
+          .track!(),
+        elapsed: root.elapsed(),
+        time: root.captureTime(),
+        running: root.running,
+        value: root.raw(),
+      }
+    },
+    subscribe(listener: () => void) {
+      root.listeners.add(listener)
+      return () => {
+        root.listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** Treat values as opaque identities in declarative option comparisons. */
+export function isDerived(value: unknown): value is DerivedValue | DerivedColor {
+  return value instanceof Derived
+}
+
+/** Internal native-adapter bridge. Mappings are sampled at boundaries, never per frame. */
+export function valuePlayback(source: DerivedValue) {
+  if (!(source instanceof Derived) || source.color)
+    throw new TypeError('A native binding needs a numeric Jolt value.')
+  const { root, read } = source
+  return {
+    snapshot() {
+      return {
+        track: root.plan({ property: 'opacity', read } as Binding).track!(),
+        elapsed: root.elapsed(),
+        paused: root.paused,
+        running: root.running,
+        value: read(root.raw()),
+      }
+    },
+    subscribe(listener: () => void) {
+      root.listeners.add(listener)
+      return () => {
+        root.listeners.delete(listener)
+      }
+    },
+  }
+}
+
 function release(binding: Binding) {
   binding.root.bindings.delete(binding)
   binding.view.off('loaded', binding.sync)
@@ -472,12 +737,22 @@ function mapping(
     throw new RangeError(
       `to() has ${input.length} inputs but ${output.length} outputs; give one output per input.`,
     )
+  if (input.some((value) => !Number.isFinite(value)))
+    throw new RangeError('to() inputs must all be finite numbers.')
+  const descending = input[input.length - 1]! < input[0]!
   if (
     input.some(
-      (value, i) => !Number.isFinite(value) || value < (input[i - 1] ?? -Infinity),
+      (value, i) => i > 0 && (descending ? value > input[i - 1]! : value < input[i - 1]!),
     )
   )
-    throw new RangeError('to() inputs must be finite and never decrease.')
+    throw new RangeError(
+      'to() inputs must be monotonic (ascending or descending); ranges cannot change direction.',
+    )
+  // Normalize pairs together, without changing caller-owned arrays or duplicate-stop rules.
+  if (descending) {
+    input = [...input].reverse()
+    output = [...output].reverse()
+  }
   const color = typeof output[0] !== 'number'
   const numbers = color ? output.map((value) => parseColor(value)) : (output as number[])
   if (

package/src/native/index.ts

@@ -0,0 +1,23 @@
+export { registerNativeProperty, checkNativeProperty } from '../native-property.js'
+export type { NativeProperty, NativePropertyDefinition } from '../native-property.js'
+export type { NativeSink } from '../native-property-driver.js'
+export {
+  mapKitCoordinate,
+  mapKitCamera,
+  mapLibreCoordinate,
+  mapLibreCamera,
+  sceneKitPose,
+} from '../native-properties.js'
+export type {
+  Coordinate,
+  MapKitCamera,
+  MapLibreCamera,
+  ScenePose,
+} from '../native-properties.js'
+export {
+  sceneKitLightIntensity,
+  sceneKitLightColor,
+  sceneKitMaterialTransparency,
+  sceneKitMaterialDiffuse,
+  sceneKitMaterialEmission,
+} from '../scene-appearance.js'