@rafaelaugusto/jolt 0.1.0-beta.11 → 0.1.0-beta.13

package/src/track.ts

@@ -4,7 +4,7 @@ import { solveDecay } from './decay.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'
 
@@ -74,7 +74,9 @@ export function createTrack(
     played,
     transition.repeat,
     transition.reverse,
-    (transition.repeatDelay ?? 0) * slowdown,
+    transition.repeatDelay ?? 0,
+    slowdown,
+    transition.seed,
   )
   const { duration } = motion
   const first = motion.values[0]!
@@ -222,32 +224,44 @@ 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 `pause` ms before each repeat, inside the keyframes, so both
+ * 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.
+ * 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,
-  pause: number,
+  delay: number | RepeatDelayRange,
+  slowdown: number,
+  seed = Math.random(),
 ): { motion: Motion; repeat: number; reverse: boolean } {
-  if (pause <= 0 || repeat <= 0 || motion.duration === 0)
+  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 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)
+      if (i > 0) segments.push(hold())
       segments.push(play(reverse && i % 2 === 1))
     }
-  else segments.push(play(false), hold, ...(reverse ? [play(true), hold] : []))
+  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) =>
@@ -260,8 +274,6 @@ function pauseBetweenRepeats(
     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[] = []
@@ -273,7 +285,9 @@ function pauseBetweenRepeats(
       const jumps =
         next !== undefined &&
         (next.kind === 'forward' ? motion.values[0] : motion.values[last]) !== held
-      times.push((start + segment.duration - (jumps ? jump : 0)) / total)
+      // 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
     }
@@ -319,6 +333,17 @@ function pauseBetweenRepeats(
   }
 }
 
+/** 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

package/src/transition.ts

@@ -12,10 +12,15 @@ 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
+  /**
+   * Milliseconds to hold the end value before each repeat. The first play doesn't wait.
+   * `[min, max]` draws a new pause for each repeat.
+   */
+  repeatDelay?: number | RepeatDelayRange
 }
 
+export type RepeatDelayRange = readonly [min: number, max: number]
+
 export interface Tween extends Timing {
   type?: 'tween'
   /** Milliseconds. */
@@ -107,7 +112,9 @@ export interface ResolvedTransition {
   delay: number
   repeat: number
   reverse: boolean
-  repeatDelay?: number
+  repeatDelay?: number | RepeatDelayRange
+  /** Draws the pauses of a `repeatDelay` range; tracks of one animation share it. */
+  seed?: number
 }
 
 const springKeys = ['stiffness', 'damping', 'mass', 'bounce', 'velocity'] as const
@@ -137,11 +144,53 @@ export function timingOf(transition: Transition): Timing {
   return timing
 }
 
-/** Timing merges key by key, the curve is taken whole from whichever side has one. */
+const isSpring = (transition: Transition) =>
+  transition.type === 'spring' ||
+  springKeys.some((key) => (transition as Spring)[key] !== undefined)
+
+/** Curve keys a merged transition took from the main one rather than from its override. */
+const inherited = new WeakMap<Transition, ReadonlySet<string>>()
+
+/**
+ * Timing merges key by key. Over a tween, a curve that stays a tween merges key by key too;
+ * otherwise 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) }
+  if (!hasCurve(override)) {
+    const merged = { ...base, ...timingOf(override) }
+    const taken = inherited.get(base)
+    if (taken) inherited.set(merged, taken)
+    return merged
+  }
+  if (!hasCurve(base) || isSpring(base) || isSpring(override))
+    return { ...timingOf(base), ...override }
+  const merged = { ...base, ...override } as Transition
+  const own = override as Record<string, unknown>
+  inherited.set(
+    merged,
+    new Set(
+      curveKeys.filter(
+        (key) =>
+          (base as Record<string, unknown>)[key] !== undefined && own[key] === undefined,
+      ),
+    ),
+  )
+  return merged
+}
+
+/** Drops inherited `times` and per-segment easings that don't fit this property's keyframes. */
+export function fitTransition(transition: Transition, keyframes: number): Transition {
+  const taken = inherited.get(transition)
+  if (!taken) return transition
+  const tween = { ...transition } as Tween
+  const segments = (ease: Tween['ease']) =>
+    ease !== undefined && isEasingList(ease) ? ease.length : undefined
+  if (taken.has('times') && tween.times && tween.times.length !== keyframes)
+    delete tween.times
+  if (taken.has('ease') && (segments(tween.ease) ?? keyframes - 1) !== keyframes - 1)
+    delete tween.ease
+  if (taken.has('easeTrack') && segments(tween.ease) !== undefined) delete tween.easeTrack
+  return tween
 }
 
 export function resolveTransition(
@@ -167,13 +216,23 @@ export function resolveTransition(
   if (repeat < 0 || Number.isNaN(repeat))
     throw new RangeError(`Invalid repeat: ${repeat}.`)
   const repeatDelay = transition.repeatDelay ?? 0
-  if (!Number.isFinite(repeatDelay) || repeatDelay < 0)
-    throw new RangeError(`Invalid repeat delay: ${repeatDelay}.`)
+  const [shortest, longest] =
+    typeof repeatDelay === 'number' ? [repeatDelay, repeatDelay] : repeatDelay
+  if (
+    (typeof repeatDelay !== 'number' &&
+      (!Array.isArray(repeatDelay) || repeatDelay.length !== 2)) ||
+    !Number.isFinite(shortest) ||
+    !Number.isFinite(longest) ||
+    shortest! < 0 ||
+    shortest! > longest!
+  )
+    throw new RangeError(`Invalid repeat delay: ${JSON.stringify(repeatDelay)}.`)
   const timing = {
     delay,
     repeat,
     reverse: transition.repeatType === 'reverse',
-    ...(repeatDelay > 0 && repeat > 0 && { repeatDelay }),
+    ...(longest! > 0 && repeat > 0 && { repeatDelay }),
+    ...(longest! > shortest! && repeat > 0 && { seed: Math.random() }),
   }
 
   if (type === 'spring') {

package/src/types.ts

@@ -86,4 +86,9 @@ export type AnimateOptions = Transition & {
   stagger?: number | Stagger
   /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
   haptic?: Haptic
+  /**
+   * Plays on a named layer, on top of the property's other animations instead of replacing
+   * them. Translations and rotations add; scale and opacity multiply.
+   */
+  layer?: string
 }

package/src/value-observers.ts

@@ -0,0 +1,133 @@
+import { Application, Color, Trace } from '@nativescript/core'
+import { getDriver } from './driver/index.js'
+
+export interface SubscribeOptions {
+  /** Deliver the current value synchronously when subscribing. Defaults to true. */
+  immediate?: boolean
+}
+
+/** `time` is milliseconds on the native animation clock, shared by a notification batch. */
+export type ValueListener<T> = (value: T, time: number) => void
+
+interface Observer {
+  read(value: number): number
+  color: boolean
+  listener: ValueListener<number | Color>
+  previous: number
+}
+
+// Only sources that need a frame live here. Idle subscriptions retain no global root reference.
+const pending = new Set<ValueObservers>()
+let cancelFrame: (() => void) | undefined
+let listening = false
+let suspended = false
+
+function suspend() {
+  suspended = true
+  cancelFrame?.()
+  cancelFrame = undefined
+}
+
+function resume() {
+  suspended = false
+  schedule()
+}
+
+function schedule() {
+  if (!pending.size) {
+    cancelFrame?.()
+    cancelFrame = undefined
+    if (listening && !suspended) {
+      Application.off(Application.suspendEvent, suspend)
+      Application.off(Application.resumeEvent, resume)
+      listening = false
+    }
+    return
+  }
+  if (!listening) {
+    Application.on(Application.suspendEvent, suspend)
+    Application.on(Application.resumeEvent, resume)
+    listening = true
+  }
+  if (cancelFrame || suspended) return
+  cancelFrame = getDriver().frame(() => {
+    cancelFrame = undefined
+    const time = getDriver().now()
+    const sources = [...pending]
+    pending.clear()
+    // Capture every source before calling any listener: reentrant writes belong to the next batch.
+    const deliveries = sources.map((source) => source.snapshot(time))
+    for (const source of sources) if (source.active) pending.add(source)
+    for (const deliver of deliveries) deliver()
+    schedule()
+  })
+}
+
+function deliver(observer: Observer, value: number, time: number) {
+  try {
+    observer.listener(observer.color ? new Color(value) : value, time)
+  } catch (error) {
+    // A consumer failure must not interrupt other consumers or strand the shared frame source.
+    Trace.write(
+      `Jolt motion value subscriber failed: ${error instanceof Error ? error.stack : String(error)}`,
+      Trace.categories.Error,
+      Trace.messageType.error,
+    )
+  }
+}
+
+/** Root-owned subscriptions; mappings are evaluated only for consumers that opted in. */
+export class ValueObservers {
+  private readonly observers = new Set<Observer>()
+  private running = false
+
+  constructor(private readonly read: (time: number) => number) {}
+
+  get active() {
+    return this.running && this.observers.size > 0
+  }
+
+  subscribe(
+    read: (value: number) => number,
+    color: boolean,
+    listener: ValueListener<number | Color>,
+    options: SubscribeOptions = {},
+  ): () => void {
+    if (typeof listener !== 'function')
+      throw new TypeError('subscribe() needs a listener function.')
+    const time = getDriver().now()
+    const observer = { read, color, listener, previous: read(this.read(time)) }
+    this.observers.add(observer)
+    if (options.immediate !== false) deliver(observer, observer.previous, time)
+    if (this.active) this.changed(true)
+    return () => {
+      this.observers.delete(observer)
+      if (!this.observers.size) {
+        pending.delete(this)
+        schedule()
+      }
+    }
+  }
+
+  changed(running: boolean) {
+    this.running = running
+    if (this.observers.size) {
+      pending.add(this)
+      schedule()
+    }
+  }
+
+  snapshot(time: number): () => void {
+    const value = this.read(time)
+    const deliveries = [...this.observers].flatMap((observer) => {
+      const next = observer.read(value)
+      if (Object.is(next, observer.previous)) return []
+      observer.previous = next
+      return [{ observer, next }]
+    })
+    return () => {
+      for (const { observer, next } of deliveries)
+        if (this.observers.has(observer)) deliver(observer, next, time)
+    }
+  }
+}

package/src/value-track.ts

@@ -0,0 +1,71 @@
+import { instantTrack, type Track } from './track.js'
+
+export interface ValuePart {
+  readonly track: Track
+  readonly elapsed: number
+  readonly base: number
+  readonly span: number
+}
+
+/** Compile scalar addition before any binding's mapping. The snapshot is independent of later edits. */
+export function valueTrack(parts: readonly ValuePart[], rest: number) {
+  const value = (time: number) =>
+    parts.reduce(
+      (sum, part) =>
+        sum + part.base + part.span * part.track.valueAt(part.elapsed + time),
+      rest,
+    )
+  let finite = 0
+  const periods: number[] = []
+  for (const { track, elapsed } of parts) {
+    if (Number.isFinite(track.end)) finite = Math.max(finite, track.end - elapsed)
+    else if (elapsed < track.delay) finite = Math.max(finite, track.delay - elapsed)
+    else periods.push(Math.max(1, track.duration * (track.reverse ? 2 : 1)))
+  }
+  if (finite <= 0 && !periods.length)
+    return { track: instantTrack('x', value(0)), windowed: false }
+  const loop = finite <= 0 && periods.length ? commonPeriod(periods) : undefined
+  // Bound finite compositions too: a minutes-long base must not undersample a short pulse.
+  const duration = finite > 0 ? Math.min(finite, 4000) : (loop ?? 4000)
+  const steps = Math.max(1, Math.min(6000, Math.ceil((duration * 60) / 1000)))
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  const values = times.map((time) => value(time * duration))
+  const endless = loop !== undefined
+  const at = (time: number) =>
+    value(
+      endless
+        ? ((time % duration) + duration) % duration
+        : Math.min(duration, Math.max(0, time)),
+    )
+  const track: Track = {
+    property: 'x',
+    delay: 0,
+    duration,
+    repeat: endless ? Infinity : 0,
+    reverse: false,
+    times,
+    values,
+    to: endless ? values[0]! : values[steps]!,
+    end: endless ? Infinity : duration,
+    arrival: endless ? Infinity : duration,
+    valueAt: at,
+    velocityAt: (time) => (at(time + 0.5) - at(time - 0.5)) * 1000,
+  }
+  return {
+    track,
+    windowed:
+      finite > duration ||
+      (!endless && parts.some(({ track }) => !Number.isFinite(track.end))),
+  }
+}
+
+function commonPeriod(periods: readonly number[]) {
+  const gcd = (a: number, b: number): number => (b ? gcd(b, a % b) : a)
+  let total = 1
+  for (const period of periods) {
+    if (!Number.isInteger(period)) return undefined
+    total = (total / gcd(total, period)) * period
+    if (total > 30000) return undefined
+  }
+  return total
+}

package/src/vue/index.ts

@@ -15,10 +15,19 @@ import {
   type Ref,
 } from 'nativescript-vue'
 import {
+  gradient,
   press,
   motionScope,
+  bind,
+  motionValue,
+  scrollValue,
   onKeyboard,
   onReducedMotion,
+  stop,
+  type Bindings,
+  type MotionValue,
+  type ScrollValue,
+  type Target,
   reducedMotion,
   type KeyboardState,
   type MotionScope,
@@ -27,6 +36,9 @@ import {
   type PlaybackAnimation,
   type PresetName,
   type SpringName,
+  type Gradient,
+  type GradientOptions,
+  type Transition,
 } from '../index.js'
 import { currentKeyboard } from '../keyboard.js'
 
@@ -37,6 +49,11 @@ type Options = AnimateOptions | SpringName
 export type AnimateValue =
   PresetName | Keyframes | readonly [animation: PresetName | Keyframes, options?: Options]
 
+/** The gradient, alone or paired with the transition for later changes. */
+export type GradientValue =
+  | GradientOptions
+  | readonly [gradient: GradientOptions, transition?: Transition | SpringName]
+
 /** The pressed keyframes, alone or paired with a transition. */
 export type PressValue = Keyframes | readonly [pressed: Keyframes, options?: Options]
 
@@ -53,6 +70,7 @@ export interface TransitionProps {
 const animations = new WeakMap<object, PlaybackAnimation>()
 const scopes = new WeakMap<object, MotionScope>()
 const removers = new WeakMap<object, () => void>()
+const gradients = new WeakMap<object, { gradient: Gradient; colors: number }>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -137,6 +155,47 @@ export const vPress: ObjectDirective<Host, PressValue | undefined> = {
   },
 }
 
+function paint(el: Host, value: GradientValue, animated: boolean) {
+  const [options, transition] = (Array.isArray(value) ? value : [value]) as [
+    GradientOptions,
+    (Transition | SpringName)?,
+  ]
+  const current = gradients.get(el)
+  const colors = options.colors.length
+  if (current && current.gradient.type === options.type) {
+    const { type, ...values } = options
+    if (animated && current.colors === colors)
+      current.gradient.animate(values, transition)
+    else current.gradient.set(values)
+    current.colors = colors
+    return
+  }
+  current?.gradient.remove()
+  gradients.set(el, { gradient: gradient(el, options), colors })
+}
+
+/**
+ * Paints a native gradient behind the element, and animates to the new values when they change.
+ * A change of type, or of the number of colors, applies at once.
+ *
+ * ```vue
+ * <GridLayout v-gradient="{ type: 'linear', colors: ['#18181B', '#3F3F46'], angle: 135 }" />
+ * <GridLayout v-gradient="[{ type: 'linear', colors: active ? hot : cold }, 'snappy']" />
+ * ```
+ */
+export const vGradient: ObjectDirective<Host, GradientValue> = {
+  mounted(el, { value }) {
+    paint(el, value, false)
+  },
+  updated(el, { value, oldValue }) {
+    if (!same(value, oldValue)) paint(el, value, true)
+  },
+  unmounted(el) {
+    gradients.get(el)?.gradient.remove()
+    gradients.delete(el)
+  },
+}
+
 /** The hooks `JoltTransition` hands to Vue's `BaseTransition`. */
 export function transitionHooks(props: TransitionProps): BaseTransitionProps<Host> {
   const run = (value: AnimateValue | undefined) => (el: Host, done: () => void) => {
@@ -195,10 +254,11 @@ export const JoltTransition = defineComponent({
   },
 })
 
-/** Registers `v-animate`, `v-press` and `JoltTransition` on the app. */
+/** Registers `v-animate`, `v-press`, `v-gradient` and `JoltTransition` on the app. */
 export function install(app: App) {
   app.directive('animate', vAnimate)
   app.directive('press', vPress)
+  app.directive('gradient', vGradient)
   app.component('JoltTransition', JoltTransition)
 }
 
@@ -229,3 +289,40 @@ export function useKeyboard(): Readonly<Ref<KeyboardState>> {
   onUnmounted(off)
   return readonly(keyboard) as Readonly<Ref<KeyboardState>>
 }
+
+/** Call in setup(): a motion value that stops when the component unmounts. */
+export function useMotionValue(initial = 0): MotionValue {
+  const value = motionValue(initial)
+  onUnmounted(() => stop(value))
+  return value
+}
+
+/**
+ * Call in setup(): a template ref that binds motion values to the element on mount
+ * and releases them on unmount. A recreated element picks the values up again.
+ */
+export function useBinding(bindings: Bindings): (element: Target | null) => void {
+  let element: Target | null = null
+  let release: (() => void) | undefined
+  onUnmounted(() => {
+    release?.()
+    release = undefined
+  })
+  return (next) => {
+    if (next === element) return
+    release?.()
+    release = undefined
+    element = next
+    if (next) release = bind(next, bindings)
+  }
+}
+
+/**
+ * Call in setup(): a scroll offset as a value. Pass its `ref` to the ScrollView's
+ * template ref; it stops following when the component unmounts.
+ */
+export function useScrollValue(options?: { axis?: 'x' | 'y' }): ScrollValue {
+  const value = scrollValue(null, options)
+  onUnmounted(() => value.dispose())
+  return value
+}