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

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/spring.ts

@@ -18,6 +18,8 @@ export interface SpringMotion {
   position(time: number): number
   /** Units per second. */
   velocity(time: number): number
+  /** Conservative linear interpolation error, including the final settlement snap. */
+  interpolationError(start: number, end: number): number
 }
 
 const MAX_DURATION = 10_000
@@ -54,14 +56,24 @@ export function solveSpring(
   const zeta = damping / (2 * Math.sqrt(stiffness * mass))
 
   let displacement: (t: number) => number
+  let accelerationBound: (start: number, end: number) => number
   if (Math.abs(zeta - 1) < 1e-6) {
     const b = velocity + w0 * x0
     displacement = (t) => Math.exp(-w0 * t) * (x0 + b * t)
+    accelerationBound = (a, end) =>
+      Math.exp(-w0 * a) *
+      (Math.abs(w0 * w0 * (x0 + b * a) - 2 * w0 * b) +
+        w0 * w0 * Math.abs(b) * Math.min(end - a, 1 / (Math.E * w0)))
   } else if (zeta < 1) {
     const wd = w0 * Math.sqrt(1 - zeta * zeta)
     const b = (velocity + zeta * w0 * x0) / wd
     displacement = (t) =>
       Math.exp(-zeta * w0 * t) * (x0 * Math.cos(wd * t) + b * Math.sin(wd * t))
+    const alpha = zeta * w0,
+      q = alpha * alpha - wd * wd
+    const amplitude = Math.hypot(q * x0 - 2 * alpha * wd * b, q * b + 2 * alpha * wd * x0)
+    accelerationBound = (a, end) =>
+      amplitude * Math.max(Math.exp(-alpha * a), Math.exp(-alpha * end))
   } else {
     const s = w0 * Math.sqrt(zeta * zeta - 1)
     const r1 = -zeta * w0 + s
@@ -69,6 +81,9 @@ export function solveSpring(
     const c1 = (velocity - r2 * x0) / (r1 - r2)
     const c2 = x0 - c1
     displacement = (t) => c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t)
+    accelerationBound = (a, end) =>
+      Math.abs(c1 * r1 * r1) * Math.max(Math.exp(r1 * a), Math.exp(r1 * end)) +
+      Math.abs(c2 * r2 * r2) * Math.max(Math.exp(r2 * a), Math.exp(r2 * end))
   }
 
   const position = (time: number) => to + displacement(time / 1000)
@@ -91,5 +106,8 @@ export function solveSpring(
     duration,
     position: (time) => (time >= duration ? to : position(time)),
     velocity: (time) => (time >= duration ? 0 : speed(time)),
+    interpolationError: (start, end) =>
+      (accelerationBound(start / 1000, end / 1000) * ((end - start) / 1000) ** 2) / 8 +
+      (end >= duration ? Math.abs(displacement(duration / 1000)) : 0),
   }
 }

package/src/svg-path.ts

@@ -6,7 +6,11 @@ export interface PathPoint {
 export interface PathPose extends PathPoint {
   rotate: number
 }
-type Segment = { point(t: number): PathPoint; tangent(t: number): PathPoint }
+type Segment = {
+  point(t: number): PathPoint
+  tangent(t: number): PathPoint
+  angle?: number
+}
 type Vertex = PathPoint & {
   segment: number
   t: number
@@ -34,7 +38,7 @@ const checked = (p: PathPoint) => {
 const unwrap = (angle: number, reference: number) =>
   angle + 360 * Math.round((reference - angle) / 360)
 
-class Scanner {
+export class Scanner {
   index = 0
   private hasNumber = false
   constructor(readonly text: string) {}
@@ -89,7 +93,7 @@ function bezier(points: readonly PathPoint[]): Segment {
 }
 
 /** Endpoint-to-center conversion: https://www.w3.org/TR/SVG/implnote.html#ArcConversionEndpointToCenter */
-function arc(
+export function arc(
   a: PathPoint,
   b: PathPoint,
   rx: number,
@@ -130,6 +134,7 @@ function arc(
   if (![cx, cy, rx, ry, start, delta].every(Number.isFinite))
     throw new RangeError('Path arc exceeds finite geometry limits.')
   return {
+    angle: delta,
     point(t) {
       if (t === 0) return a
       if (t === 1) return b