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

package/src/size-layout.ts

@@ -0,0 +1,237 @@
+import { GridLayout, StackLayout, Utils, View, unsetValue } from '@nativescript/core'
+
+export type SizeAxis = 'width' | 'height'
+export type SizeValue = number | 'auto'
+export type SizeValues = Partial<Record<SizeAxis, SizeValue>>
+export type SizePixels = Record<SizeAxis, number>
+
+type MeasuredView = View & {
+  _currentWidthMeasureSpec?: number
+  _currentHeightMeasureSpec?: number
+  _oldLeft?: number
+  _oldTop?: number
+  _oldRight?: number
+  _oldBottom?: number
+}
+const overlays = new WeakMap<View, Map<SizeAxis, object>>()
+
+/** One live tree: speculative measurement never lays out or duplicates its views. */
+export function sizeLayout(
+  view: View,
+  axes: readonly SizeAxis[],
+  replacing: readonly SizeAxis[] = [],
+  read: () => SizePixels = () => view.getActualSize(),
+) {
+  const parent = view.parent
+  if (
+    view.isLoaded &&
+    !(parent instanceof StackLayout) &&
+    !(parent instanceof GridLayout)
+  )
+    throw new TypeError('animateSize needs a child of StackLayout or GridLayout.')
+  const style = view.style as unknown as Record<string, unknown>
+  for (const axis of axes) {
+    const initial = view[axis]
+    if (
+      typeof initial === 'object' &&
+      initial !== null &&
+      (initial.unit === 'dip' || initial.unit === 'px')
+    )
+      dimension(initial.value, `initial ${axis}`)
+    else dimension(initial, `initial ${axis}`)
+    const key = `keyframe:${axis}`
+    if (
+      !replacing.includes(axis) &&
+      style[key] !== unsetValue &&
+      style[key] !== undefined
+    )
+      throw new Error(`animateSize cannot own ${axis} during a CSS keyframe animation.`)
+  }
+  let writing = false
+  let disposed = false
+  let claimed = false
+  const identity = {}
+  const claim = () => {
+    if (claimed || disposed) return
+    claimed = true
+    const current = overlays.get(view) ?? new Map<SizeAxis, object>()
+    for (const axis of axes) current.set(axis, identity)
+    overlays.set(view, current)
+  }
+  const owns = (axis: SizeAxis) => overlays.get(view)?.get(axis) === identity
+  let releaseHooks = () => {}
+  const write = (values: SizeValues) => {
+    if (disposed) return
+    claim()
+    writing = true
+    try {
+      for (const axis of axes)
+        if (owns(axis) && values[axis] !== undefined)
+          style[`keyframe:${axis}`] = bounded(view, axis, values[axis]!)
+    } finally {
+      writing = false
+    }
+  }
+  const clear = () => {
+    writing = true
+    try {
+      for (const axis of axes) if (owns(axis)) style[`keyframe:${axis}`] = unsetValue
+    } finally {
+      writing = false
+    }
+  }
+  const root = () => {
+    let node = view as MeasuredView
+    while (node.parent instanceof View && node.parent.typeName !== 'Page')
+      node = node.parent as MeasuredView
+    return node
+  }
+  const specs = (node: MeasuredView) => {
+    // Core's last layout allocation excludes transforms; UIView.frame does not.
+    const cached = [node._oldLeft, node._oldTop, node._oldRight, node._oldBottom]
+    const bounds =
+      cached.every((value) => Number.isFinite(value)) &&
+      cached[2]! > cached[0]! &&
+      cached[3]! > cached[1]!
+        ? { left: cached[0]!, top: cached[1]!, right: cached[2]!, bottom: cached[3]! }
+        : node._getCurrentLayoutBounds()
+    const layout = Utils.layout
+    return {
+      bounds,
+      width:
+        node._currentWidthMeasureSpec ??
+        layout.makeMeasureSpec(Math.max(0, bounds.right - bounds.left), layout.EXACTLY),
+      height:
+        node._currentHeightMeasureSpec ??
+        layout.makeMeasureSpec(Math.max(0, bounds.bottom - bounds.top), layout.EXACTLY),
+    }
+  }
+  const measure = () => {
+    const node = root()
+    const spec = specs(node)
+    view.requestLayout()
+    node.measure(spec.width, spec.height)
+    return { node, ...spec }
+  }
+  return {
+    read,
+    write,
+    ready() {
+      const { bounds } = specs(root())
+      return bounds.right > bounds.left && bounds.bottom > bounds.top
+    },
+    measure(destination: SizeValues): SizePixels {
+      const held = Object.fromEntries(
+        axes.map((axis) => [axis, style[`keyframe:${axis}`]]),
+      )
+      try {
+        write(destination)
+        measure()
+        const dip = Utils.layout.toDeviceIndependentPixels
+        return {
+          width: dip(view.getMeasuredWidth()),
+          height: dip(view.getMeasuredHeight()),
+        }
+      } finally {
+        writing = true
+        try {
+          for (const axis of axes)
+            if (!disposed && owns(axis)) style[`keyframe:${axis}`] = held[axis]
+        } finally {
+          writing = false
+        }
+      }
+    },
+    /** Flush the restored/current declarations before any draw can see probe measurements. */
+    layout() {
+      const { node, bounds } = measure()
+      node.layout(bounds.left, bounds.top, bounds.right, bounds.bottom)
+    },
+    commit(values?: SizeValues) {
+      writing = true
+      try {
+        if (values)
+          for (const axis of axes)
+            if (owns(axis) && values[axis] !== undefined)
+              view[axis] = bounded(view, axis, values[axis]!)
+      } finally {
+        writing = false
+        clear()
+      }
+    },
+    watch(takeover: () => void) {
+      claim()
+      const undo: (() => void)[] = []
+      releaseHooks = () =>
+        undo
+          .splice(0)
+          .reverse()
+          .forEach((off) => off())
+      // A local/CSS write hidden under the animation override still takes ownership.
+      for (const axis of axes)
+        for (const name of [axis, `css:${axis}`, `keyframe:${axis}`]) {
+          const own = Object.getOwnPropertyDescriptor(style, name)
+          let source: object | null = style
+          let descriptor: PropertyDescriptor | undefined
+          while (source && !descriptor) {
+            descriptor = Object.getOwnPropertyDescriptor(source, name)
+            source = Object.getPrototypeOf(source)
+          }
+          if (!descriptor?.set || !descriptor.get || own?.configurable === false)
+            throw new Error(`animateSize cannot observe ownership of ${name}.`)
+          const original = descriptor
+          const set = function (this: object, value: unknown) {
+            if (!writing) takeover()
+            original.set!.call(this, value)
+          }
+          Object.defineProperty(style, name, {
+            configurable: true,
+            get: original.get,
+            set,
+          })
+          undo.push(() => {
+            if (Object.getOwnPropertyDescriptor(style, name)?.set !== set) return
+            if (own) Object.defineProperty(style, name, own)
+            else delete style[name]
+          })
+        }
+    },
+    dispose() {
+      disposed = true
+      releaseHooks()
+      clear()
+      const current = overlays.get(view)
+      for (const axis of axes) if (owns(axis)) current!.delete(axis)
+      if (!current?.size) overlays.delete(view)
+    },
+  }
+}
+
+function bounded(view: View, axis: SizeAxis, value: SizeValue): SizeValue {
+  if (value === 'auto') return value
+  const minimum = axis === 'width' ? view.minWidth : view.minHeight
+  const maximum = axis === 'width' ? view.maxWidth : view.maxHeight
+  const dip = Utils.layout.toDeviceIndependentPixels
+  const min =
+    typeof minimum === 'number'
+      ? minimum
+      : dip((axis === 'width' ? view.effectiveMinWidth : view.effectiveMinHeight) ?? 0)
+  const max =
+    typeof maximum === 'number'
+      ? maximum
+      : dip(
+          (axis === 'width' ? view.effectiveMaxWidth : view.effectiveMaxHeight) ??
+            Infinity,
+        )
+  return Math.min(max, Math.max(0, min, value))
+}
+
+export function dimension(value: unknown, label: string): asserts value is SizeValue {
+  if (
+    value !== 'auto' &&
+    (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+  )
+    throw new RangeError(
+      `animateSize ${label} must be a nonnegative finite DIP number or "auto"; percentages and unit objects are unsupported.`,
+    )
+}

package/src/size.ts

@@ -0,0 +1,302 @@
+import { Application } from '@nativescript/core'
+import type { View } from '@nativescript/core'
+import { toView } from './animate.js'
+import { onReducedMotion, reducedMotion } from './config.js'
+import { getDriver } from './driver/index.js'
+import type { Animation } from './engine.js'
+import { createClock, type PlaybackClock } from './playback.js'
+import { createTrack, type Track } from './track.js'
+import {
+  resolveTransition,
+  springs,
+  type Spring,
+  type SpringName,
+  type Tween,
+} from './transition.js'
+import {
+  dimension,
+  sizeLayout,
+  type SizeAxis,
+  type SizePixels,
+  type SizeValues,
+} from './size-layout.js'
+import type { Target } from './types.js'
+
+export type SizeDimensions = SizeValues
+export type SizeOptions =
+  | Omit<Spring, 'repeat' | 'repeatType' | 'repeatDelay'>
+  | Omit<Tween, 'repeat' | 'repeatType' | 'repeatDelay' | 'times' | 'easeTrack'>
+export interface SizeAnimation extends Animation {
+  pause(): void
+  play(): void
+  readonly paused: boolean
+  /** Hold the current size; restore:true releases the temporary size back to the original declaration. */
+  stop(options?: { restore?: boolean }): void
+}
+const owners = new WeakMap<
+  View,
+  { animation: SizeAnimation; axes: readonly SizeAxis[] }
+>()
+
+/** Animate the actual layout box, including intrinsic auto sizes. Layout runs in JS on the UI thread. */
+export function animateSize(
+  target: Target,
+  dimensions: SizeDimensions,
+  options?: SizeOptions | SpringName,
+): SizeAnimation
+export function animateSize(
+  target: Target,
+  dimensions: SizeDimensions,
+  change: () => void,
+  options?: SizeOptions | SpringName,
+): SizeAnimation
+export function animateSize(
+  target: Target,
+  dimensions: SizeDimensions,
+  changeOrOptions?: (() => void) | SizeOptions | SpringName,
+  options?: SizeOptions | SpringName,
+): SizeAnimation {
+  const view = toView(target)
+  if (!dimensions || typeof dimensions !== 'object' || Array.isArray(dimensions))
+    throw new TypeError('animateSize takes a width/height object.')
+  const axes = Object.keys(dimensions) as SizeAxis[]
+  if (!axes.length || axes.some((axis) => axis !== 'width' && axis !== 'height'))
+    throw new TypeError('animateSize needs width and/or height.')
+  for (const axis of axes) dimension(dimensions[axis], axis)
+  const destination = { ...dimensions }
+  const change = typeof changeOrOptions === 'function' ? changeOrOptions : undefined
+  if (change?.constructor.name === 'AsyncFunction')
+    throw new TypeError('animateSize changes must be synchronous.')
+  const transition = normalize(
+    change ? options : (changeOrOptions as SizeOptions | SpringName | undefined),
+  )
+  // Solve before ownership changes, including custom easing/physical-spring validation.
+  const validation = createTrack('x', [0, 100], transition, 0)
+  if (!Number.isFinite(validation.end) || !validation.values.every(Number.isFinite))
+    throw new RangeError('animateSize needs a finite curve with finite samples.')
+  const previous = owners.get(view)
+  const driver = getDriver()
+  const layout = sizeLayout(view, axes, previous?.axes, () => {
+    const frame = driver.layoutFrame?.(view)
+    return frame ? { width: frame.width, height: frame.height } : view.getActualSize()
+  })
+  // Release the previous overlay only after every caller-supplied input was validated.
+  const start = layout.read()
+  previous?.animation.stop({ restore: true })
+  let resolve!: (value: boolean) => void
+  let reject!: (error: unknown) => void
+  const finished = new Promise<boolean>((done, fail) => {
+    resolve = done
+    reject = fail
+  })
+  let settled = false
+  let paused = false
+  let initialized = false
+  let cancelFrame: (() => void) | undefined
+  let unwatch: (() => void) | undefined
+  let clock: PlaybackClock | undefined
+  let tracks = new Map<SizeAxis, Track>()
+  let endpoint: SizePixels | undefined
+  const cleanup = () => {
+    cancelFrame?.()
+    cancelFrame = undefined
+    clock?.cancel()
+    clock = undefined
+    unwatch?.()
+    layout.dispose()
+    view.off('unloaded', unloaded)
+    Application.off(Application.suspendEvent, unloaded)
+    if (owners.get(view)?.animation === animation) owners.delete(view)
+  }
+  const finish = (success: boolean, error?: unknown) => {
+    if (settled) return
+    settled = true
+    cleanup()
+    if (error !== undefined) reject(error)
+    else resolve(success)
+  }
+  const complete = () => {
+    layout.commit(destination)
+    layout.layout()
+    finish(true)
+  }
+  const stop = (restore = false) => {
+    if (settled) return
+    layout.commit(restore ? undefined : layout.read())
+    finish(false)
+    view.requestLayout()
+  }
+  function unloaded() {
+    stop(true)
+  }
+  const schedule = () => {
+    if (!cancelFrame && !settled && !paused) cancelFrame = driver.frame(tick)
+  }
+  function tick() {
+    cancelFrame = undefined
+    if (settled || paused) return
+    try {
+      if (!view.isLoaded || view.visibility === 'collapse' || !view.nativeViewProtected) {
+        stop(true)
+        return
+      }
+      const next = layout.measure(destination)
+      if (settled) return
+      if (axes.some((axis) => !Number.isFinite(next[axis]) || next[axis] < 0))
+        throw new Error('animateSize measured an invalid native size.')
+      if (reducedMotion()) {
+        complete()
+        return
+      }
+      if (
+        !initialized &&
+        axes.every((axis) => Math.abs(next[axis] - start[axis]) < 0.5)
+      ) {
+        complete()
+        return
+      }
+      const elapsed = clock?.time() ?? 0
+      if (
+        !endpoint ||
+        axes.some((axis) => Math.abs(next[axis] - endpoint![axis]) > 0.5)
+      ) {
+        const from = initialized ? layout.read() : start
+        const fresh = new Map<SizeAxis, Track>()
+        for (const axis of axes)
+          fresh.set(
+            axis,
+            createTrack(
+              'x',
+              [from[axis], next[axis]],
+              initialized ? { ...transition, delay: 0 } : transition,
+              tracks.get(axis)?.velocityAt(elapsed) ?? 0,
+            ),
+          )
+        tracks = fresh
+        endpoint = next
+        clock?.cancel()
+        const end = Math.max(...[...tracks.values()].map((track) => track.end))
+        clock = driver.clock?.(end) ?? createClock(() => driver.now())
+        initialized = true
+      }
+      const time = clock!.time()
+      if ([...tracks.values()].every((track) => time >= track.end)) {
+        complete()
+        return
+      }
+      const values: SizeValues = {}
+      for (const [axis, track] of tracks) values[axis] = Math.max(0, track.valueAt(time))
+      layout.write(values)
+      layout.layout()
+      if (settled) return
+      schedule()
+    } catch (error) {
+      layout.commit()
+      view.requestLayout()
+      finish(false, error)
+    }
+  }
+  const animation: SizeAnimation = {
+    finished,
+    then: (done, fail) => finished.then(done, fail),
+    get paused() {
+      return paused
+    },
+    stop: (options) => stop(options?.restore === true),
+    pause() {
+      if (settled || paused) return
+      paused = true
+      clock?.pause()
+      cancelFrame?.()
+      cancelFrame = undefined
+    },
+    play() {
+      if (settled || !paused) return
+      paused = false
+      clock?.play()
+      schedule()
+    },
+  }
+  owners.set(view, { animation, axes })
+  try {
+    layout.watch(() => stop(true))
+    layout.write(start)
+    view.on('unloaded', unloaded)
+    Application.on(Application.suspendEvent, unloaded)
+    unwatch = onReducedMotion((reduced) => {
+      if (reduced && !settled) {
+        try {
+          complete()
+        } catch (error) {
+          finish(false, error)
+        }
+      }
+    })
+    const result: unknown = change?.()
+    if (result && typeof (result as PromiseLike<unknown>).then === 'function')
+      throw new TypeError('animateSize changes must be synchronous.')
+    if (!view.isLoaded || view.visibility === 'collapse' || !layout.ready()) {
+      layout.commit(destination)
+      finish(false)
+    } else schedule()
+  } catch (error) {
+    stop(true)
+    throw error
+  }
+  return animation
+}
+
+function normalize(input?: SizeOptions | SpringName) {
+  if (typeof input === 'string') {
+    if (!Object.hasOwn(springs, input))
+      throw new TypeError(`Unknown size spring "${input}".`)
+    input = springs[input]
+  }
+  if (
+    input !== undefined &&
+    (!input || typeof input !== 'object' || Array.isArray(input))
+  )
+    throw new TypeError('Invalid animateSize options.')
+  const allowed = new Set([
+    'type',
+    'duration',
+    'ease',
+    'stiffness',
+    'damping',
+    'mass',
+    'bounce',
+    'velocity',
+    'delay',
+  ])
+  for (const [key, value] of Object.entries(input ?? {})) {
+    if (!allowed.has(key))
+      throw new TypeError(
+        `Unsupported animateSize option "${key}"; repeat and seek are not supported.`,
+      )
+    if (value === undefined) continue
+    if (
+      key !== 'type' &&
+      key !== 'ease' &&
+      (typeof value !== 'number' || !Number.isFinite(value))
+    )
+      throw new RangeError(`animateSize ${key} must be finite.`)
+    if (key === 'type' && value !== 'spring' && value !== 'tween')
+      throw new TypeError('Invalid size transition type.')
+    if (typeof value === 'number') {
+      if (['duration', 'delay', 'damping'].includes(key) && value < 0)
+        throw new RangeError(`${key} must be nonnegative.`)
+      if (['mass', 'stiffness'].includes(key) && value <= 0)
+        throw new RangeError(`${key} must be positive.`)
+      if (key === 'bounce' && (value < -1 || value > 1))
+        throw new RangeError('bounce must be between -1 and 1.')
+    }
+  }
+  const resolved = resolveTransition(input ?? {}, 'x', 2)
+  if (
+    resolved.curve.type === 'spring' &&
+    input?.duration === 0 &&
+    !('stiffness' in input || 'damping' in input || 'mass' in input)
+  )
+    throw new RangeError('Use a zero-duration tween for immediate sizing.')
+  return resolved
+}

package/src/types.ts

@@ -84,7 +84,7 @@ 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

package/src/vue/index.ts

@@ -40,6 +40,8 @@ import {
   type GradientOptions,
   type Transition,
 } from '../index.js'
+import { isDerived } from '../motion-value.js'
+import { prepareGradient, type GradientValues } from '../gradient.js'
 import { currentKeyboard } from '../keyboard.js'
 
 type Host = NSVElement
@@ -70,7 +72,10 @@ 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 }>()
+const gradients = new WeakMap<
+  object,
+  { gradient: Gradient; colors: number; release?: () => void }
+>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -82,6 +87,7 @@ function split<T>(
 
 function same(a: unknown, b: unknown): boolean {
   if (Object.is(a, b)) return true
+  if (isDerived(a) || isDerived(b)) return false
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
     return false
   if (Array.isArray(a) !== Array.isArray(b)) return false
@@ -161,17 +167,35 @@ function paint(el: Host, value: GradientValue, animated: boolean) {
     (Transition | SpringName)?,
   ]
   const current = gradients.get(el)
+  prepareGradient(options)
   const colors = options.colors.length
+  const hasBindings = [
+    options.angle,
+    options.radius,
+    options.center?.x,
+    options.center?.y,
+    ...options.colors,
+    ...(options.stops ?? []),
+  ].some(isDerived)
   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)
+    const previous = current.release
+    if (hasBindings) current.release = current.gradient.bind(values)
+    else {
+      if (animated && current.colors === colors)
+        current.gradient.animate(values as GradientValues, transition)
+      else current.gradient.set(values as GradientValues)
+      current.release = undefined
+    }
+    previous?.()
     current.colors = colors
     return
   }
   current?.gradient.remove()
-  gradients.set(el, { gradient: gradient(el, options), colors })
+  // Track directive ownership explicitly, including bindings omitted on a later update.
+  const made = gradient(el, options)
+  const release = hasBindings ? made.bind(options) : undefined
+  gradients.set(el, { gradient: made, colors, release })
 }
 
 /**