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

package/src/transition.ts

@@ -1,9 +1,10 @@
-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'
+import { DEFAULT_ACCELERATION, DEFAULT_RESTITUTION } from './gravity.js'
 
 export interface Timing {
   /** Milliseconds to wait before starting. The first keyframe is applied right away. */
@@ -12,8 +13,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.
+   * `[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. */
@@ -22,6 +30,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 {
@@ -37,7 +50,19 @@ export interface Spring extends Timing {
   velocity?: number
 }
 
-export type Transition = Tween | Spring
+export interface Gravity extends Timing {
+  type: 'gravity'
+  /** Positive acceleration toward the final value, in units per second squared. Default 1800. */
+  acceleration?: number
+  /** Fraction of impact speed retained by each bounce, from 0 (no bounce) to less than 1. Default 0.55. */
+  restitution?: number
+  /** Signed units per second. Defaults to the velocity of the animation it interrupts. */
+  velocity?: number
+  /** Duration is determined by the physical parameters. */
+  duration?: never
+}
+
+export type Transition = Tween | Spring | Gravity
 
 export type SpringName = 'smooth' | 'snappy' | 'bouncy'
 
@@ -47,13 +72,51 @@ export const springs: Record<SpringName, Spring> = {
   bouncy: { type: 'spring', duration: 550, bounce: 0.4 },
 }
 
+export interface OrigamiSpring {
+  /** React Native's default is 7. */
+  friction?: number
+  /** React Native's default is 40. */
+  tension?: number
+}
+
+/**
+ * The spring React Native's `Animated.spring` plays for `friction` and `tension`,
+ * converted with the same Origami formulas.
+ *
+ * ```ts
+ * animate(card, { x: 100 }, origamiSpring({ friction: 7, tension: 40 }))
+ * ```
+ */
+export function origamiSpring({
+  friction = 7,
+  tension = 40,
+}: OrigamiSpring = {}): Spring {
+  if (!Number.isFinite(friction) || !Number.isFinite(tension))
+    throw new RangeError('Origami friction and tension must be finite.')
+  const stiffness = (tension - 30) * 3.62 + 194
+  const damping = (friction - 8) * 3 + 25
+  if (stiffness <= 0 || damping < 0)
+    throw new RangeError(
+      `Origami tension ${tension} and friction ${friction} give no spring (stiffness ${stiffness}, damping ${damping}).`,
+    )
+  return { type: 'spring', stiffness, damping, mass: 1 }
+}
+
 export type Curve =
   | DragCurve
+  | {
+      type: 'gravity'
+      acceleration: number
+      restitution: number
+      velocity: number | undefined
+    }
   | {
       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 }
   | {
@@ -68,11 +131,23 @@ export interface ResolvedTransition {
   delay: number
   repeat: number
   reverse: boolean
+  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
-const curveKeys = ['type', 'duration', 'ease', 'times', ...springKeys] as const
-const timingKeys = ['delay', 'repeat', 'repeatType'] as const
+const curveKeys = [
+  'type',
+  'duration',
+  'ease',
+  'times',
+  'easeTrack',
+  'acceleration',
+  'restitution',
+  ...springKeys,
+] as const
+const timingKeys = ['delay', 'repeat', 'repeatType', 'repeatDelay'] as const
 
 export const DEFAULT_DURATION = 300
 
@@ -90,11 +165,59 @@ 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) ||
+    base.type === 'gravity' ||
+    override.type === 'gravity' ||
+    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(
@@ -119,9 +242,63 @@ 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
+  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',
+    ...(longest! > 0 && repeat > 0 && { repeatDelay }),
+    ...(longest! > shortest! && repeat > 0 && { seed: Math.random() }),
+  }
+
+  if (type === 'gravity') {
+    if (property !== 'x' && property !== 'y')
+      throw new TypeError('Gravity applies to x, y or a numeric motion value.')
+    if (keyframes !== 2)
+      throw new TypeError('Gravity needs a start and one fixed landing position.')
+    const gravity = transition as Gravity
+    const acceleration = gravity.acceleration ?? DEFAULT_ACCELERATION
+    const restitution = gravity.restitution ?? DEFAULT_RESTITUTION
+    if (!Number.isFinite(acceleration) || acceleration <= 0)
+      throw new RangeError('Gravity acceleration must be finite and positive.')
+    if (!Number.isFinite(restitution) || restitution < 0 || restitution >= 1)
+      throw new RangeError('Gravity restitution must be at least 0 and less than 1.')
+    if (gravity.velocity !== undefined && !Number.isFinite(gravity.velocity))
+      throw new RangeError('Gravity velocity must be finite.')
+    for (const key of [
+      'duration',
+      'ease',
+      'times',
+      'easeTrack',
+      'stiffness',
+      'damping',
+      'mass',
+      'bounce',
+    ])
+      if ((transition as unknown as Record<string, unknown>)[key] !== undefined)
+        throw new TypeError(
+          `Gravity does not accept "${key}"; timing comes from its physics.`,
+        )
+    return {
+      ...timing,
+      curve: { type, acceleration, restitution, velocity: gravity.velocity },
+    }
+  }
 
   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.`,
@@ -147,6 +324,10 @@ export function resolveTransition(
 
   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(
@@ -168,6 +349,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

@@ -48,6 +48,11 @@ export interface Keyframes {
 /** 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 }
@@ -79,6 +84,11 @@ export type AnimateOptions = Transition & {
   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. */
+  /** Native haptic 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,147 @@
+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,
+    private readonly isRunning?: () => boolean,
+  ) {}
+
+  get size() {
+    return this.observers.size
+  }
+
+  get active() {
+    return (this.isRunning?.() ?? 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()
+    }
+  }
+
+  clear() {
+    this.observers.clear()
+    pending.delete(this)
+    this.running = false
+    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
+}