@rafaelaugusto/jolt 0.1.0-beta.6 → 0.1.0-beta.8

package/src/motion-scope.ts

@@ -0,0 +1,265 @@
+import { animate, decay } from './animate.js'
+import { press } from './press.js'
+import { drag } from './drag.js'
+import { sequence } from './sequence.js'
+import {
+  motionStates,
+  type MotionState,
+  type MotionDefinitions,
+  type MotionStates,
+  type MotionStatesOptions,
+} from './motion-states.js'
+import type { Target } from './types.js'
+
+/** A cleanup function or a handle owned exclusively by one scope. */
+export type MotionResource = (() => void) | { stop(): void } | { dispose(): void }
+type Controlled = {
+  pause?: () => void
+  play?: () => void
+  readonly paused?: boolean
+  readonly finished?: Promise<unknown>
+}
+interface Entry {
+  resource?: MotionResource
+  setup?: () => MotionResource
+  resume: boolean
+}
+const owners = new WeakMap<object, object>()
+
+export interface MotionScope {
+  readonly disposed: boolean
+  readonly suspended: boolean
+  /** Owned handles/subscriptions, including suspended subscription factories. */
+  readonly size: number
+  animate: typeof animate
+  decay: typeof decay
+  sequence: typeof sequence
+  press: typeof press
+  drag: typeof drag
+  states<
+    T extends Record<string, Target>,
+    const S extends Record<string, MotionState<keyof T>>,
+  >(
+    targets: T,
+    definitions: MotionDefinitions<T, S>,
+    options?: Omit<MotionStatesOptions, 'scope'>,
+  ): MotionStates<Extract<keyof S, 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. */
+  use(setup: () => MotionResource): () => void
+  /** Pause playable handles; cancel non-playable ones; detach subscriptions. */
+  suspend(): void
+  resume(): void
+  /** Cancel all owned work without destroying the scope, e.g. when recycling a cell. */
+  reset(): void
+  dispose(): void
+}
+
+/** Framework-independent ownership. Native unload never permanently destroys a scope. */
+export function motionScope(): MotionScope {
+  const entries = new Set<Entry>()
+  const adopted = new Map<MotionResource, Entry>()
+  const identity = {}
+  let disposed = false
+  let suspended = false
+  let clearing = false
+  const assertAlive = () => {
+    if (disposed) throw new Error('Motion scope is disposed.')
+    if (clearing) throw new Error('Motion scope is resetting.')
+  }
+  const assertActive = () => {
+    assertAlive()
+    if (suspended)
+      throw new Error('Motion scope is suspended; resume it before starting work.')
+  }
+  const validate = (resource: MotionResource) => {
+    if (
+      typeof resource !== 'function' &&
+      (!resource ||
+        (typeof (resource as { dispose?: unknown }).dispose !== 'function' &&
+          typeof (resource as { stop?: unknown }).stop !== 'function'))
+    )
+      throw new TypeError(
+        'A motion resource must be a cleanup function or expose stop()/dispose().',
+      )
+    const finished = (resource as Controlled).finished
+    if (finished && typeof finished.then !== 'function')
+      throw new TypeError('Resource finished must be a promise.')
+    if (owners.has(resource) && owners.get(resource) !== identity)
+      throw new Error('Motion resource already belongs to another scope.')
+  }
+  const forget = (entry: Entry) => {
+    const resource = entry.resource
+    if (resource) {
+      owners.delete(resource)
+      adopted.delete(resource)
+      entry.resource = undefined
+    }
+    entry.resume = false
+  }
+  const disposeResource = (resource: MotionResource) => {
+    if (typeof resource === 'function') resource()
+    else if (typeof (resource as { dispose?: unknown }).dispose === 'function')
+      (resource as { dispose(): void }).dispose()
+    else (resource as { stop(): void }).stop()
+  }
+  const release = (entry: Entry) => {
+    const resource = entry.resource
+    forget(entry)
+    if (!resource) return
+    disposeResource(resource)
+  }
+  const remove = (entry: Entry) => {
+    entries.delete(entry)
+    release(entry)
+  }
+  const attach = (entry: Entry, resource: MotionResource) => {
+    validate(resource)
+    if (adopted.has(resource))
+      throw new Error('Subscription factory returned an already owned resource.')
+    entry.resource = resource
+    adopted.set(resource, entry)
+    owners.set(resource, identity)
+    const finished = (resource as Controlled).finished
+    if (!entry.setup && finished) {
+      const settled = () => {
+        if (entry.resource !== resource) return
+        forget(entry)
+        entries.delete(entry)
+      }
+      void finished.then(settled, settled)
+    }
+  }
+  const startSubscription = (entry: Entry) => {
+    const resource = entry.setup!()
+    validate(resource)
+    // Setup may synchronously navigate away, suspend or remove its own scope.
+    if (disposed || suspended || !entries.has(entry)) {
+      if (!owners.has(resource)) disposeResource(resource)
+      return
+    }
+    attach(entry, resource)
+  }
+  // One bad cleanup must not strand the other subscriptions.
+  const visit = (action: (entry: Entry) => void) => {
+    const errors: unknown[] = []
+    for (const entry of [...entries]) {
+      if (!entries.has(entry)) continue
+      try {
+        action(entry)
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    if (errors.length)
+      throw new AggregateError(errors, 'Motion scope cleanup/lifecycle failed.')
+  }
+  const startOwned = <T extends MotionResource>(factory: () => T): T => {
+    assertActive()
+    const resource = factory()
+    try {
+      return scope.add(resource)
+    } catch (error) {
+      if (!owners.has(resource)) disposeResource(resource)
+      throw error
+    }
+  }
+  const scope: MotionScope = {
+    get disposed() {
+      return disposed
+    },
+    get suspended() {
+      return suspended
+    },
+    get size() {
+      return entries.size
+    },
+    animate(...args) {
+      return startOwned(() => animate(...args))
+    },
+    decay(...args) {
+      return startOwned(() => decay(...args))
+    },
+    sequence(...args) {
+      return startOwned(() => sequence(...args))
+    },
+    press(...args) {
+      return scope.use(() => press(...args))
+    },
+    drag(...args) {
+      return startOwned(() => drag(...args))
+    },
+    states(targets, definitions, options) {
+      return startOwned(() => motionStates(targets, definitions, options))
+    },
+    add(resource) {
+      assertActive()
+      validate(resource)
+      if (adopted.has(resource)) return resource
+      const entry: Entry = { resume: false }
+      attach(entry, resource)
+      entries.add(entry)
+      return resource
+    },
+    use(setup) {
+      assertAlive()
+      if (typeof setup !== 'function')
+        throw new TypeError('Motion subscription needs a factory.')
+      const entry: Entry = { setup, resume: false }
+      entries.add(entry)
+      try {
+        if (!suspended) startSubscription(entry)
+      } catch (error) {
+        remove(entry)
+        throw error
+      }
+      return () => remove(entry)
+    },
+    suspend() {
+      if (disposed || suspended) return
+      suspended = true
+      visit((entry) => {
+        if (entry.setup) {
+          release(entry)
+          return
+        }
+        const resource = entry.resource as Controlled | undefined
+        if (
+          typeof resource?.pause === 'function' &&
+          typeof resource.play === 'function'
+        ) {
+          entry.resume = resource.paused !== true
+          if (entry.resume) resource.pause()
+        } else remove(entry)
+      })
+    },
+    resume() {
+      if (disposed || !suspended) return
+      suspended = false
+      visit((entry) => {
+        if (disposed || suspended) return
+        if (entry.setup) startSubscription(entry)
+        else if (entry.resume) {
+          entry.resume = false
+          ;(entry.resource as Controlled).play?.()
+        }
+      })
+    },
+    reset() {
+      if (disposed || clearing) return
+      clearing = true
+      try {
+        visit(remove)
+      } finally {
+        clearing = false
+      }
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      visit(remove)
+    },
+  }
+  return scope
+}

package/src/motion-states.ts

@@ -0,0 +1,215 @@
+import { prepareAnimation, 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 { MotionScope } from './motion-scope.js'
+
+/** Absolute endpoints only; keyframe arrays, paths and relative offsets are not states. */
+export type MotionValues = {
+  [K in KeyframeProperty]?: K extends 'color' | 'backgroundColor' | 'borderColor'
+    ? ColorValue
+    : number
+}
+export type MotionState<K extends PropertyKey = string> = Partial<Record<K, MotionValues>>
+/** Preserve inference while rejecting unknown target/property keys. */
+export type MotionDefinitions<T, S> = S & {
+  [N in keyof S]: Record<Exclude<keyof S[N], keyof T>, never> & {
+    [K in keyof S[N]]: Record<Exclude<keyof S[N][K], KeyframeProperty>, never>
+  }
+}
+export type StateTransition =
+  | SpringName
+  | Omit<Spring, 'repeat' | 'repeatType'>
+  | Omit<Tween, 'repeat' | 'repeatType'>
+export interface MotionStatesOptions {
+  transition?: StateTransition
+  scope?: MotionScope
+}
+export interface MotionStates<S 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
+  pause(): void
+  play(): void
+  stop(): void
+  dispose(): void
+}
+
+/** Coordinated named targets. Omitted properties freeze when leaving their previous state. */
+export function motionStates<
+  T extends Record<string, Target>,
+  const S extends Record<string, MotionState<keyof T>>,
+>(
+  targets: T,
+  definitions: MotionDefinitions<T, S>,
+  options: MotionStatesOptions = {},
+): MotionStates<Extract<keyof S, string>> {
+  type Name = Extract<keyof S, string>
+  const views = new Map(
+    Object.entries(targets).map(([name, target]) => [name, toView(target)]),
+  )
+  if (new Set(views.values()).size !== views.size)
+    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, state] of Object.entries(definitions)) {
+    if (!state || typeof state !== 'object' || Array.isArray(state))
+      throw new TypeError(`Invalid motion state "${name}".`)
+    const rows: [Target, Keyframes][] = []
+    for (const [target, values] of Object.entries(state)) {
+      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 = {}
+      for (const [property, value] of Object.entries(values)) {
+        if (value === undefined) continue
+        if (property !== 'scale' && !isProperty(property))
+          throw new TypeError(`Invalid motion state property "${property}".`)
+        if (
+          !isColorProperty(property) &&
+          (typeof value !== 'number' || !Number.isFinite(value))
+        )
+          throw new TypeError(`Motion state "${property}" requires a finite endpoint.`)
+        if (Array.isArray(value) || value === null)
+          throw new TypeError(`Motion state "${property}" requires a single endpoint.`)
+        Object.assign(frames, { [property]: value })
+      }
+      // Validate every definition up front without claiming any native property.
+      prepareAnimation(view, frames, defaults)
+      rows.push([view, frames])
+    }
+    states.set(name, rows)
+  }
+  let current: Name | undefined
+  let settled: Name | undefined
+  let disposed = false
+  let paused = false
+  let active: { handle: Animation; children: PlaybackAnimation[] } | undefined
+  const controller: MotionStates<Name> = {
+    get current() {
+      return current
+    },
+    get settled() {
+      return settled
+    },
+    get disposed() {
+      return disposed
+    },
+    get paused() {
+      return paused
+    },
+    to(name, transition) {
+      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 previous = active
+      const children: PlaybackAnimation[] = []
+      // Start replacements first: the engine transfers visible position AND velocity.
+      try {
+        for (const start of prepared) {
+          const child = start()
+          children.push(child)
+          if (paused) child.pause()
+        }
+      } catch (error) {
+        children.forEach((child) => child.stop())
+        previous?.handle.stop()
+        active = undefined
+        throw error
+      }
+      let cancelled = false
+      const finished = Promise.all(children.map((child) => child.finished)).then(
+        (results) => {
+          const completed =
+            !cancelled && !disposed && active?.handle === handle && results.every(Boolean)
+          if (active?.handle === handle) {
+            active = undefined
+            if (completed) settled = name
+          }
+          return completed
+        },
+      )
+      const handle: Animation = {
+        finished,
+        stop() {
+          cancelled = true
+          children.forEach((child) => child.stop())
+        },
+        then: (resolve, reject) => finished.then(resolve, reject),
+      }
+      active = { handle, children }
+      current = name
+      // Also cancels old, omitted properties, without touching the new owners.
+      previous?.handle.stop()
+      return handle
+    },
+    pause() {
+      if (disposed || paused) return
+      paused = true
+      active?.children.forEach((child) => child.pause())
+    },
+    play() {
+      if (disposed || !paused) return
+      paused = false
+      active?.children.forEach((child) => child.play())
+    },
+    stop() {
+      active?.handle.stop()
+      active = undefined
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      controller.stop()
+    },
+  }
+  return options.scope ? options.scope.add(controller) : controller
+}
+
+function normalize(transition: StateTransition | undefined): StateTransition {
+  if (transition === undefined) return 'snappy'
+  if (typeof transition === 'string') {
+    if (!['smooth', 'snappy', 'bouncy'].includes(transition))
+      throw new TypeError('Unknown state spring.')
+    return transition
+  }
+  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))
+      throw new TypeError(`State transitions do not support "${key}".`)
+  if (
+    transition.duration !== undefined &&
+    (!Number.isFinite(transition.duration) || transition.duration < 0)
+  )
+    throw new RangeError('State transition duration must be finite and nonnegative.')
+  if (
+    transition.delay !== undefined &&
+    (!Number.isFinite(transition.delay) || transition.delay < 0)
+  )
+    throw new RangeError('State transition delay must be finite and nonnegative.')
+  return { ...transition }
+}

package/src/press.ts

@@ -1,6 +1,7 @@
 import { Color, type EventData, type TouchGestureEventData } from '@nativescript/core'
 import { isColorProperty } from './color.js'
 import { animate, startingValues, toView } from './animate.js'
+import type { PlaybackAnimation } from './playback.js'
 import { readValue } from './properties.js'
 import type { SpringName, Transition } from './transition.js'
 import type { AnimateOptions, Keyframes, Target } from './types.js'
@@ -25,6 +26,7 @@ export function press(
   const view = toView(target)
   const properties = [...startingValues(pressed, options).keys()]
   let rest: Keyframes | undefined
+  let active: PlaybackAnimation | undefined
 
   const onTouch = (event: EventData) => {
     const { action } = event as TouchGestureEventData
@@ -35,9 +37,9 @@ export function press(
           isColorProperty(p) ? new Color(readValue(view, p)) : readValue(view, p),
         ]),
       )
-      animate(view, pressed, options ?? pressIn)
+      active = animate(view, pressed, options ?? pressIn)
     } else if ((action === 'up' || action === 'cancel') && rest) {
-      animate(
+      active = animate(
         view,
         rest,
         typeof options === 'object'
@@ -48,6 +50,16 @@ export function press(
     }
   }
 
+  const cancel = () => {
+    active?.stop()
+    active = undefined
+    rest = undefined
+  }
   view.on('touch', onTouch)
-  return () => view.off('touch', onTouch)
+  view.on('unloaded', cancel)
+  return () => {
+    view.off('touch', onTouch)
+    view.off('unloaded', cancel)
+    cancel()
+  }
 }

package/src/track.ts

@@ -1,6 +1,7 @@
 import { clampDecoration, isDecorationProperty } from './decoration.js'
 import { linear } from './easing.js'
 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'
@@ -62,9 +63,11 @@ export function createTrack(
   const motion = slow(
     curve.type === 'spring'
       ? spring(property, keyframes, curve, velocity * slowdown, slowdown)
-      : curve.type === 'decay'
-        ? decay(property, keyframes[0]!, curve, slowdown)
-        : tween(keyframes, curve, slowdown),
+      : curve.type === 'drag'
+        ? dragMotion(keyframes[0]!, curve, slowdown)
+        : curve.type === 'decay'
+          ? decay(property, keyframes[0]!, curve, slowdown)
+          : tween(keyframes, curve, slowdown),
     slowdown,
   )
   const { duration } = motion
@@ -94,7 +97,9 @@ export function createTrack(
     to: !finite || endsBackwards ? first : last,
     end,
     arrival:
-      (curve.type === 'spring' || (curve.type === 'decay' && curve.snap !== undefined)) &&
+      (curve.type === 'spring' ||
+        curve.type === 'drag' ||
+        (curve.type === 'decay' && curve.snap !== undefined)) &&
       repeat === 0
         ? delay + arrival(motion)
         : end,
@@ -142,6 +147,7 @@ function restingValue(
 ) {
   const first = keyframes[0]!
   if (!Number.isFinite(repeat) || (reverse && repeat % 2 === 1)) return first
+  if (curve.type === 'drag') return solveDragRelease(first, curve).to
   if (curve.type !== 'decay') return keyframes.at(-1)!
   const landing = solveDecay(
     first,
@@ -232,6 +238,21 @@ function samples(duration: number, density: number) {
   )
 }
 
+function dragMotion(
+  from: number,
+  curve: Extract<Curve, { type: 'drag' }>,
+  density: number,
+): Motion {
+  const motion = solveDragRelease(from, curve)
+  const steps = samples(motion.duration, density)
+  const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
+  return {
+    ...motion,
+    times,
+    values: times.map((time) => motion.position(time * motion.duration)),
+  }
+}
+
 function decay(
   property: Property,
   from: number,

package/src/transition.ts

@@ -3,6 +3,7 @@ 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'
 
 export interface Timing {
   /** Milliseconds to wait before starting. The first keyframe is applied right away. */
@@ -47,6 +48,7 @@ export const springs: Record<SpringName, Spring> = {
 }
 
 export type Curve =
+  | DragCurve
   | {
       type: 'tween'
       duration: number

package/src/vue/index.ts

@@ -2,6 +2,9 @@ import {
   BaseTransition,
   defineComponent,
   h,
+  onUnmounted,
+  onActivated,
+  onDeactivated,
   type App,
   type BaseTransitionProps,
   type NSVElement,
@@ -9,8 +12,9 @@ import {
   type PropType,
 } from 'nativescript-vue'
 import {
-  animate,
   press,
+  motionScope,
+  type MotionScope,
   type AnimateOptions,
   type Keyframes,
   type PlaybackAnimation,
@@ -39,6 +43,7 @@ export interface TransitionProps {
 }
 
 const animations = new WeakMap<object, PlaybackAnimation>()
+const scopes = new WeakMap<object, MotionScope>()
 const removers = new WeakMap<object, () => void>()
 
 function split<T>(
@@ -65,13 +70,16 @@ function same(a: unknown, b: unknown): boolean {
 
 function play(el: Host, value: AnimateValue) {
   const [animation, options] = split<PresetName | Keyframes>(value)
-  const handle = animate(el, animation, options)
+  let scope = scopes.get(el)
+  if (!scope) scopes.set(el, (scope = motionScope()))
+  const handle = scope.animate(el, animation, options)
   animations.set(el, handle)
   return handle
 }
 
 function cancel(el: Host) {
-  animations.get(el)?.stop()
+  scopes.get(el)?.dispose()
+  scopes.delete(el)
   animations.delete(el)
 }
 
@@ -187,3 +195,12 @@ export function install(app: App) {
 }
 
 export default { install }
+
+/** Call in setup(): suspend cached components and dispose only on actual unmount. */
+export function useMotionScope(): MotionScope {
+  const scope = motionScope()
+  onUnmounted(() => scope.dispose())
+  onDeactivated(() => scope.suspend())
+  onActivated(() => scope.resume())
+  return scope
+}