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

package/src/mixer.ts

@@ -0,0 +1,264 @@
+import type { View } from '@nativescript/core'
+import { getDriver } from './driver/index.js'
+import { readValue, writeValue, type Property } from './properties.js'
+import type { Track } from './track.js'
+
+/** The channel of regular animations; layers are named next to it. */
+export const BASE = ''
+
+const SAMPLES_PER_SECOND = 60
+const MAX_SAMPLES = 6000
+/** Endless channels loop natively over the least common multiple of their periods, up to this. */
+const MAX_LOOP = 30000
+/** Beyond it, the composition is played in windows and sampled again at each one. */
+const WINDOW = 4000
+
+export const multiplies = (property: Property) =>
+  property === 'opacity' || property === 'scaleX' || property === 'scaleY'
+export const identity = (property: Property) => (multiplies(property) ? 1 : 0)
+export const layerable = (property: Property) =>
+  multiplies(property) ||
+  property === 'x' ||
+  property === 'y' ||
+  property === 'rotate' ||
+  property === 'rotateX' ||
+  property === 'rotateY'
+
+interface Channel {
+  track: Track
+  anchor: number
+  offset: number
+  paused: boolean
+  onEnd: (finished: boolean) => void
+  timer?: () => void
+}
+
+/** What the engine holds instead of a driver handle while a property is mixed. */
+export class MixHandle {
+  constructor(
+    readonly mix: Mix,
+    readonly key: string,
+  ) {}
+  elapsed() {
+    return this.mix.elapsed(this.key)
+  }
+  control(position: number, paused: boolean) {
+    this.mix.control(this.key, position, paused)
+  }
+}
+
+const mixes = new WeakMap<View, Map<Property, Mix>>()
+
+export function mixOf(view: View, property: Property): Mix | undefined {
+  return mixes.get(view)?.get(property)
+}
+
+export function mixesOf(view: View): Mix[] {
+  return [...(mixes.get(view)?.values() ?? [])]
+}
+
+export function mixFor(view: View, property: Property): Mix {
+  let properties = mixes.get(view)
+  if (!properties) mixes.set(view, (properties = new Map()))
+  let mix = properties.get(property)
+  if (!mix) properties.set(property, (mix = new Mix(view, property)))
+  return mix
+}
+
+/** One property of one view: a base and named layers, played natively as one composite track. */
+export class Mix {
+  private readonly rests = new Map<string, number>()
+  private readonly channels = new Map<string, Channel>()
+  private native: unknown
+  private generation = 0
+
+  constructor(
+    readonly view: View,
+    readonly property: Property,
+  ) {
+    this.rests.set(BASE, readValue(view, property))
+  }
+
+  rest(key: string): number {
+    return (
+      this.rests.get(key) ??
+      (key === BASE ? readValue(this.view, this.property) : identity(this.property))
+    )
+  }
+
+  setRest(key: string, value: number) {
+    this.rests.set(key, value)
+    this.compose()
+  }
+
+  adopt(
+    key: string,
+    track: Track,
+    startedAt: number,
+    onEnd: (finished: boolean) => void,
+  ) {
+    this.channels.get(key)?.timer?.()
+    const channel: Channel = { track, anchor: startedAt, offset: 0, paused: false, onEnd }
+    this.channels.set(key, channel)
+    this.schedule(key, channel)
+    this.compose()
+    return new MixHandle(this, key)
+  }
+
+  elapsed(key: string, now = getDriver().now()): number {
+    const channel = this.channels.get(key)
+    if (!channel) return 0
+    return channel.paused ? channel.offset : channel.offset + now - channel.anchor
+  }
+
+  control(key: string, position: number, paused: boolean) {
+    const channel = this.channels.get(key)
+    if (!channel) return
+    channel.timer?.()
+    channel.timer = undefined
+    channel.offset = position
+    channel.anchor = getDriver().now()
+    channel.paused = paused
+    if (!paused) this.schedule(key, channel)
+    this.compose()
+  }
+
+  /**
+   * A channel leaves: replaced, stopped or done. A stopped layer takes its contribution
+   * with it; anything else rests where it is.
+   */
+  detach(key: string, stopped: boolean) {
+    const channel = this.channels.get(key)
+    if (!channel) return
+    const value = channel.track.valueAt(this.elapsed(key))
+    channel.timer?.()
+    this.channels.delete(key)
+    this.rests.set(key, stopped && key !== BASE ? identity(this.property) : value)
+    this.compose()
+  }
+
+  /** Everything stops: what is on screen becomes the base, and layers are cleared. */
+  freeze() {
+    const value = this.value()
+    for (const [key, channel] of [...this.channels]) {
+      channel.timer?.()
+      this.channels.delete(key)
+      channel.onEnd(false)
+    }
+    this.rests.clear()
+    this.rests.set(BASE, value)
+    this.compose()
+  }
+
+  /** The composed value on screen at `time`. */
+  value(time = getDriver().now()): number {
+    const now = getDriver().now()
+    let result = this.part(BASE, time, now)
+    const keys = new Set([...this.rests.keys(), ...this.channels.keys()])
+    for (const key of keys) {
+      if (key === BASE) continue
+      const part = this.part(key, time, now)
+      result = multiplies(this.property) ? result * part : result + part
+    }
+    return result
+  }
+
+  private part(key: string, time: number, now: number) {
+    const channel = this.channels.get(key)
+    if (!channel) return this.rest(key)
+    const elapsed = channel.paused
+      ? channel.offset
+      : channel.offset + now - channel.anchor + (time - now)
+    return channel.track.valueAt(elapsed)
+  }
+
+  private schedule(key: string, channel: Channel) {
+    const remaining = channel.track.end - this.elapsed(key)
+    if (!Number.isFinite(remaining)) return
+    channel.timer = getDriver().after(Math.max(0, remaining), () => {
+      if (this.channels.get(key) !== channel) return
+      this.channels.delete(key)
+      this.rests.set(key, channel.track.valueAt(channel.track.end))
+      channel.onEnd(true)
+      this.compose()
+    })
+  }
+
+  /** Samples the composition from now and plays it as one native track. */
+  private compose() {
+    const driver = getDriver()
+    const now = driver.now()
+    const instance = ++this.generation
+    const previous = this.native
+    this.native = undefined
+
+    let finite = 0
+    const periods: number[] = []
+    for (const [key, channel] of this.channels) {
+      if (channel.paused) continue
+      const elapsed = this.elapsed(key, now)
+      const { track } = channel
+      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, Math.round(track.duration * (track.reverse ? 2 : 1))))
+    }
+
+    if (previous !== undefined) driver.stop(this.view, previous)
+    const loop = finite <= 0 && periods.length ? leastCommonMultiple(periods) : undefined
+    if (finite <= 0 && !periods.length) {
+      writeValue(this.view, this.property, this.value(now))
+      driver.sync?.(this.view)
+      this.dissolve()
+      return
+    }
+
+    const span = finite > 0 ? finite : (loop ?? WINDOW)
+    const steps = Math.max(
+      1,
+      Math.min(MAX_SAMPLES, Math.ceil((span / 1000) * SAMPLES_PER_SECOND)),
+    )
+    const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+    const values = times.map((time) => this.value(now + time * span))
+    const endless = loop !== undefined
+    const at = (elapsed: number) =>
+      this.value(now + (endless ? elapsed % span : Math.min(Math.max(elapsed, 0), span)))
+    const track: Track = {
+      property: this.property,
+      delay: 0,
+      duration: span,
+      repeat: endless ? Infinity : 0,
+      reverse: false,
+      times,
+      values,
+      to: endless ? values[0]! : values[steps]!,
+      end: endless ? Infinity : span,
+      arrival: endless ? Infinity : span,
+      valueAt: at,
+      velocityAt: (elapsed) => (at(elapsed + 0.5) - at(elapsed - 0.5)) * 1000,
+    }
+    writeValue(this.view, this.property, track.to)
+    this.native = driver.play(this.view, track, now, (finished = true) => {
+      if (instance !== this.generation || !finished) return
+      this.native = undefined
+      this.compose()
+    })
+  }
+
+  private dissolve() {
+    if (this.channels.size) return
+    for (const [key, value] of this.rests)
+      if (key !== BASE && value !== identity(this.property)) return
+    const properties = mixes.get(this.view)
+    if (properties?.get(this.property) === this) properties.delete(this.property)
+  }
+}
+
+function leastCommonMultiple(periods: readonly number[]): number | undefined {
+  const gcd = (a: number, b: number): number => (b ? gcd(b, a % b) : a)
+  let result = periods[0]!
+  for (const period of periods.slice(1)) {
+    result = (result / gcd(result, period)) * period
+    if (result > MAX_LOOP) return undefined
+  }
+  return result
+}

package/src/motion-scope.ts

@@ -1,6 +1,7 @@
 import { animate, decay } from './animate.js'
 import { press } from './press.js'
 import { drag } from './drag.js'
+import { gradient } from './gradient.js'
 import { animateLayout, type LayoutOptions } from './layout.js'
 import type { SpringName } from './transition.js'
 import { sequence } from './sequence.js'
@@ -39,14 +40,16 @@ export interface MotionScope {
   sequence: typeof sequence
   press: typeof press
   drag: typeof drag
+  /** Removed with the scope; suspending it stops a gradient animation where it is. */
+  gradient: typeof gradient
   states<
-    T extends Record<string, Target>,
+    T extends Record<string, Target | null>,
     const S extends Record<string, MotionState<keyof T>>,
   >(
     targets: T,
     definitions: MotionDefinitions<T, S>,
-    options?: Omit<MotionStatesOptions, 'scope'>,
-  ): MotionStates<Extract<keyof S, string>>
+    options?: Omit<MotionStatesOptions<Extract<keyof T, string>>, 'scope'>,
+  ): MotionStates<Extract<keyof S, string>, Extract<keyof T, string>>
   /** Adopt an existing handle. Completed animations are released automatically. */
   add<T extends MotionResource>(resource: T): T
   /** Attach a subscription, detach on suspension, and recreate on resume. */
@@ -189,9 +192,8 @@ export function motionScope(): MotionScope {
           : animateLayout(container, changeOrOptions),
       )
     },
-    animate(...args) {
-      return startOwned(() => animate(...args))
-    },
+    animate: ((...args: Parameters<typeof animate>) =>
+      startOwned(() => animate(...args))) as typeof animate,
     decay(...args) {
       return startOwned(() => decay(...args))
     },
@@ -204,6 +206,12 @@ export function motionScope(): MotionScope {
     drag(...args) {
       return startOwned(() => drag(...args))
     },
+    gradient(target, options) {
+      assertActive()
+      const made = gradient(target, options)
+      scope.add({ pause: () => made.stop(), play() {}, dispose: () => made.remove() })
+      return made
+    },
     states(targets, definitions, options) {
       return startOwned(() => motionStates(targets, definitions, options))
     },

package/src/motion-states.ts

@@ -1,9 +1,11 @@
-import { prepareAnimation, toView } from './animate.js'
+import { endingValues, prepareAnimation, set, toView } from './animate.js'
 import { isColorProperty, type ColorValue } from './color.js'
 import { isProperty } from './properties.js'
 import type { Animation } from './engine.js'
 import type { PlaybackAnimation } from './playback.js'
-import type { KeyframeProperty, Keyframes, Target } from './types.js'
+import type { KeyframeProperty, Keyframes, Target, Values } from './types.js'
+import type { View } from '@nativescript/core'
+import { mergeTransitions, springs } from './transition.js'
 import type { Spring, Tween, SpringName } from './transition.js'
 import type { MotionScope } from './motion-scope.js'
 
@@ -20,21 +22,33 @@ export type MotionDefinitions<T, S> = S & {
     [K in keyof S[N]]: Record<Exclude<keyof S[N][K], KeyframeProperty>, never>
   }
 }
-export type StateTransition =
+type StateCurve =
   | SpringName
   | Omit<Spring, 'repeat' | 'repeatType'>
   | Omit<Tween, 'repeat' | 'repeatType'>
-export interface MotionStatesOptions {
-  transition?: StateTransition
+/** One transition for every target, or a main one with some targets set apart by name. */
+export type StateTransition<T extends string = string> =
+  | StateCurve
+  | (Exclude<StateCurve, SpringName> &
+      (string extends T ? unknown : { [K in T]?: StateCurve }))
+export interface MotionStatesOptions<T extends string = string> {
+  transition?: StateTransition<T>
   scope?: MotionScope
 }
-export interface MotionStates<S extends string = string> {
+export interface MotionStates<S extends string = string, T extends string = string> {
   /** Latest requested state, not a claim that playback has finished. */
   readonly current: S | undefined
   readonly settled: S | undefined
   readonly disposed: boolean
   readonly paused: boolean
-  to(state: S, transition?: StateTransition): Animation
+  to(state: S, transition?: StateTransition<T>): Animation
+  /**
+   * Point a target at a new view, or at none with `null`. The new view takes the current
+   * state at once, or joins the transition in progress from where it is.
+   */
+  attach(target: T, view: Target | null): void
+  /** A stable callback for a template ref: attaches the element and detaches it on unmount. */
+  ref(target: T): (view: Target | null) => void
   pause(): void
   play(): void
   stop(): void
@@ -43,28 +57,38 @@ export interface MotionStates<S extends string = string> {
 
 /** Coordinated named targets. Omitted properties freeze when leaving their previous state. */
 export function motionStates<
-  T extends Record<string, Target>,
+  T extends Record<string, Target | null>,
   const S extends Record<string, MotionState<keyof T>>,
 >(
   targets: T,
   definitions: MotionDefinitions<T, S>,
-  options: MotionStatesOptions = {},
-): MotionStates<Extract<keyof S, string>> {
+  options: MotionStatesOptions<Extract<keyof T, string>> = {},
+): MotionStates<Extract<keyof S, string>, Extract<keyof T, string>> {
   type Name = Extract<keyof S, string>
-  const views = new Map(
-    Object.entries(targets).map(([name, target]) => [name, toView(target)]),
+  type Slot = Extract<keyof T, string>
+  const views = new Map<string, View | null>(
+    Object.entries(targets).map(([name, target]) => [
+      name,
+      target === null ? null : toView(target),
+    ]),
   )
-  if (new Set(views.values()).size !== views.size)
+  const assigned = [...views.values()].filter(Boolean)
+  if (new Set(assigned).size !== assigned.length)
     throw new TypeError('Motion state targets must refer to distinct views.')
-  const states = new Map<string, [Target, Keyframes][]>()
-  const defaults = normalize(options.transition)
+  for (const name of views.keys())
+    if (curveKeys.has(name))
+      throw new TypeError(
+        `A motion target can't be named "${name}", like a transition option.`,
+      )
+  const states = new Map<string, [string, Keyframes][]>()
+  const defaults = normalize(options.transition, views)
   for (const [name, state] of Object.entries(definitions)) {
     if (!state || typeof state !== 'object' || Array.isArray(state))
       throw new TypeError(`Invalid motion state "${name}".`)
-    const rows: [Target, Keyframes][] = []
+    const rows: [string, Keyframes][] = []
     for (const [target, values] of Object.entries(state)) {
+      if (!views.has(target)) throw new TypeError(`Unknown motion target "${target}".`)
       const view = views.get(target)
-      if (!view) throw new TypeError(`Unknown motion target "${target}".`)
       if (!values || typeof values !== 'object' || Array.isArray(values))
         throw new TypeError(`Invalid motion values for "${target}".`)
       const frames: Keyframes = {}
@@ -82,8 +106,9 @@ export function motionStates<
         Object.assign(frames, { [property]: value })
       }
       // Validate every definition up front without claiming any native property.
-      prepareAnimation(view, frames, defaults)
-      rows.push([view, frames])
+      if (view) prepareAnimation(view, frames, timingFor(defaults, target))
+      else endingValues(frames, timingFor(defaults, target))
+      rows.push([target, frames])
     }
     states.set(name, rows)
   }
@@ -91,8 +116,14 @@ export function motionStates<
   let settled: Name | undefined
   let disposed = false
   let paused = false
-  let active: { handle: Animation; children: PlaybackAnimation[] } | undefined
-  const controller: MotionStates<Name> = {
+  let active:
+    { handle: Animation; children: PlaybackAnimation[]; timing: Timing } | undefined
+  const refs = new Map<string, (view: Target | null) => void>()
+  const framesFor = (state: Name | undefined, target: string) =>
+    state === undefined
+      ? undefined
+      : states.get(state)!.find(([slot]) => slot === target)?.[1]
+  const controller: MotionStates<Name, Slot> = {
     get current() {
       return current
     },
@@ -109,10 +140,11 @@ export function motionStates<
       if (disposed) throw new Error('Motion states controller is disposed.')
       const rows = states.get(name)
       if (!rows) throw new TypeError(`Unknown motion state "${name}".`)
-      const timing = transition === undefined ? defaults : normalize(transition)
-      const prepared = rows.map(([view, frames]) =>
-        prepareAnimation(view, frames, timing),
-      )
+      const timing = normalize(transition, views, defaults)
+      const prepared = rows.flatMap(([target, frames]) => {
+        const view = views.get(target)
+        return view ? [prepareAnimation(view, frames, timingFor(timing, target))] : []
+      })
       const previous = active
       const children: PlaybackAnimation[] = []
       // Start replacements first: the engine transfers visible position AND velocity.
@@ -148,12 +180,45 @@ export function motionStates<
         },
         then: (resolve, reject) => finished.then(resolve, reject),
       }
-      active = { handle, children }
+      active = { handle, children, timing }
       current = name
       // Also cancels old, omitted properties, without touching the new owners.
       previous?.handle.stop()
       return handle
     },
+    attach(target, next) {
+      if (disposed) throw new Error('Motion states controller is disposed.')
+      if (!views.has(target)) throw new TypeError(`Unknown motion target "${target}".`)
+      const view = next === null ? null : toView(next)
+      if (views.get(target) === view) return
+      if (view)
+        for (const [other, assignedView] of views)
+          if (other !== target && assignedView === view)
+            throw new TypeError('Motion state targets must refer to distinct views.')
+      if (view)
+        for (const [, rows] of states)
+          for (const [slot, frames] of rows)
+            if (slot === target)
+              prepareAnimation(view, frames, timingFor(defaults, target))
+      views.set(target, view)
+      const frames = view ? framesFor(current, target) : undefined
+      if (!view || !frames) return
+      if (active) {
+        const child = prepareAnimation(view, frames, timingFor(active.timing, target))()
+        active.children.push(child)
+        if (paused) child.pause()
+      } else set(view, frames as Values)
+    },
+    ref(target) {
+      let callback = refs.get(target)
+      if (!callback) {
+        callback = (view) => {
+          if (!disposed) controller.attach(target, view)
+        }
+        refs.set(target, callback)
+      }
+      return callback
+    },
     pause() {
       if (disposed || paused) return
       paused = true
@@ -177,8 +242,59 @@ export function motionStates<
   return options.scope ? options.scope.add(controller) : controller
 }
 
-function normalize(transition: StateTransition | undefined): StateTransition {
-  if (transition === undefined) return 'snappy'
+const curveKeys = new Set([
+  'type',
+  'delay',
+  'duration',
+  'ease',
+  'times',
+  'stiffness',
+  'damping',
+  'mass',
+  'bounce',
+  'velocity',
+])
+
+type Curve = Exclude<StateCurve, SpringName>
+interface Timing {
+  readonly main: StateCurve
+  readonly targets: ReadonlyMap<string, StateCurve>
+}
+
+/** The transition one target plays: its own merged over the main one, or the main one. */
+function timingFor(timing: Timing, target: string): StateCurve {
+  const own = timing.targets.get(target)
+  if (own === undefined) return timing.main
+  const main = typeof timing.main === 'string' ? springs[timing.main] : timing.main
+  return mergeTransitions(main, typeof own === 'string' ? springs[own] : own) as Curve
+}
+
+const snappy: Timing = { main: 'snappy', targets: new Map() }
+
+/** A transition that only names targets keeps the fallback for everything else. */
+function normalize(
+  transition: StateTransition | undefined,
+  targets: ReadonlyMap<string, unknown>,
+  fallback = snappy,
+): Timing {
+  if (transition === undefined) return fallback
+  if (typeof transition === 'string')
+    return { main: curve(transition), targets: new Map() }
+  if (!transition || typeof transition !== 'object')
+    throw new TypeError('Invalid state transition.')
+  const main: Record<string, unknown> = {}
+  const own = new Map<string, StateCurve>()
+  for (const [key, value] of Object.entries(transition)) {
+    if (targets.has(key)) {
+      if (value !== undefined) own.set(key, curve(value as StateCurve))
+    } else main[key] = value
+  }
+  if (own.size && !Object.keys(main).length)
+    return { main: fallback.main, targets: new Map([...fallback.targets, ...own]) }
+  return { main: curve(main as Curve), targets: own }
+}
+
+function curve(transition: StateCurve): StateCurve {
   if (typeof transition === 'string') {
     if (!['smooth', 'snappy', 'bouncy'].includes(transition))
       throw new TypeError('Unknown state spring.')
@@ -186,20 +302,8 @@ function normalize(transition: StateTransition | undefined): StateTransition {
   }
   if (!transition || typeof transition !== 'object')
     throw new TypeError('Invalid state transition.')
-  const allowed = new Set([
-    'type',
-    'delay',
-    'duration',
-    'ease',
-    'times',
-    'stiffness',
-    'damping',
-    'mass',
-    'bounce',
-    'velocity',
-  ])
   for (const key of Object.keys(transition))
-    if (!allowed.has(key))
+    if (!curveKeys.has(key))
       throw new TypeError(`State transitions do not support "${key}".`)
   if (
     transition.duration !== undefined &&