@rafaelaugusto/jolt 0.1.0-beta.8 → 0.1.0-rc.1

package/src/motion-states.ts

@@ -1,10 +1,12 @@
-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 { Spring, Tween, SpringName } from './transition.js'
+import type { KeyframeProperty, Keyframes, Target, Values } from './types.js'
+import type { View } from '@nativescript/core'
+import { mergeTransitions, springs } from './transition.js'
+import type { Gravity, Spring, Tween, SpringName } from './transition.js'
 import type { MotionScope } from './motion-scope.js'
 
 /** Absolute endpoints only; keyframe arrays, paths and relative offsets are not states. */
@@ -20,21 +22,34 @@ 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
+  | Omit<Gravity, 'repeat' | 'repeatType'>
+/** 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 +58,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 +107,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 +117,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 +141,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 +181,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 +243,61 @@ 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',
+  'acceleration',
+  'restitution',
+])
+
+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 +305,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 &&