@rafaelaugusto/jolt 0.1.0-beta.1 → 0.1.0-beta.11

package/src/config.ts

@@ -0,0 +1,84 @@
+import { getDriver } from './driver/index.js'
+
+export interface JoltConfig {
+  /** Playback speed for every engine animation. `0.2` plays everything five times slower. */
+  timeScale?: number
+  /**
+   * When transforms, paths, decorations and decay jump to their end instead of animating.
+   * `user` follows the platform setting. Opacity and colors still animate.
+   */
+  reducedMotion?: 'user' | 'always' | 'never'
+}
+
+const settings: Required<JoltConfig> = { timeScale: 1, reducedMotion: 'user' }
+const listeners = new Set<(reduced: boolean) => void>()
+let reported = false
+let unwatch: (() => void) | undefined
+const preferences: readonly JoltConfig['reducedMotion'][] = ['user', 'always', 'never']
+
+/**
+ * Global settings, applied to animations that start after the call.
+ *
+ * ```ts
+ * configure({ timeScale: 0.2 }) // tune a spring in slow motion
+ * configure({ reducedMotion: 'always' }) // check the reduced layout
+ * ```
+ */
+export function configure(options: JoltConfig): void {
+  if (options === null || typeof options !== 'object')
+    throw new TypeError('configure() takes an options object.')
+  const { timeScale, reducedMotion } = options
+  if (timeScale !== undefined && (!Number.isFinite(timeScale) || timeScale <= 0))
+    throw new RangeError(`Time scale must be a positive finite number, got ${timeScale}.`)
+  if (reducedMotion !== undefined && !preferences.includes(reducedMotion))
+    throw new TypeError(
+      `Reduced motion must be 'user', 'always' or 'never', got ${String(reducedMotion)}.`,
+    )
+  if (timeScale !== undefined) settings.timeScale = timeScale
+  if (reducedMotion !== undefined) {
+    settings.reducedMotion = reducedMotion
+    changed()
+  }
+}
+
+export function timeScale(): number {
+  return settings.timeScale
+}
+
+/** Whether motion is reduced right now. `user` asks the platform each time. */
+export function reducedMotion(): boolean {
+  if (settings.reducedMotion === 'user') return getDriver().reducedMotion?.() ?? false
+  return settings.reducedMotion === 'always'
+}
+
+/**
+ * Calls back with the new value whenever `reducedMotion()` changes, from `configure()`
+ * or the platform setting. Returns a cleanup function.
+ *
+ * ```ts
+ * const off = onReducedMotion((reduced) => (illustration.visibility = reduced ? 'visible' : 'collapse'))
+ * ```
+ */
+export function onReducedMotion(callback: (reduced: boolean) => void): () => void {
+  if (typeof callback !== 'function')
+    throw new TypeError('onReducedMotion() takes a callback.')
+  const listener = (reduced: boolean) => callback(reduced)
+  if (listeners.size === 0) {
+    reported = reducedMotion()
+    unwatch = getDriver().watchReducedMotion?.(changed)
+  }
+  listeners.add(listener)
+  return () => {
+    if (!listeners.delete(listener) || listeners.size > 0) return
+    unwatch?.()
+    unwatch = undefined
+  }
+}
+
+function changed() {
+  if (listeners.size === 0) return
+  const reduced = reducedMotion()
+  if (reduced === reported) return
+  reported = reduced
+  for (const listener of [...listeners]) listener(reduced)
+}

package/src/decay.ts

@@ -0,0 +1,45 @@
+export interface DecayMotion {
+  duration: number
+  to: number
+  position(time: number): number
+  velocity(time: number): number
+}
+
+/** Velocity retains this fraction every millisecond, independently of the display's refresh rate. */
+export const DEFAULT_FRICTION = 0.998
+
+/** Exponential motion, with velocity in units per second and time in milliseconds. */
+export function solveDecay(
+  from: number,
+  velocity: number,
+  friction: number,
+  precision: number,
+): DecayMotion {
+  const rate = -Math.log(friction)
+  const distance = velocity / (1000 * rate)
+  const to = from + distance
+  // Stop only when both the remaining distance and speed are imperceptible.
+  const duration =
+    velocity === 0
+      ? 0
+      : Math.ceil(
+          Math.max(
+            0,
+            Math.log(Math.abs(distance) / precision) / rate,
+            Math.log(Math.abs(velocity) / (precision * 10)) / rate,
+          ),
+        )
+
+  if (!Number.isFinite(to) || !Number.isFinite(duration) || duration > 2_147_483_647) {
+    throw new RangeError('Decay velocity and friction produce an unplayable motion.')
+  }
+
+  return {
+    duration,
+    to,
+    position: (time) =>
+      time >= duration ? to : from - distance * Math.expm1(-rate * Math.max(0, time)),
+    velocity: (time) =>
+      time >= duration ? 0 : velocity * Math.exp(-rate * Math.max(0, time)),
+  }
+}

package/src/decoration.ts

@@ -0,0 +1,180 @@
+import { preserveZeroShadow } from './driver/ios-shadow.js'
+import { Color, Utils, isAndroid, type View } from '@nativescript/core'
+
+type Shadow = Exclude<View['boxShadow'], string>[number]
+export type DecorationProperty =
+  | 'borderRadius'
+  | 'borderWidth'
+  | 'shadowOpacity'
+  | 'shadowRadius'
+  | 'shadowOffsetX'
+  | 'shadowOffsetY'
+  | 'elevation'
+  | 'translationZ'
+
+export const decorationProperties: readonly DecorationProperty[] = [
+  'borderRadius',
+  'borderWidth',
+  'shadowOpacity',
+  'shadowRadius',
+  'shadowOffsetX',
+  'shadowOffsetY',
+  'elevation',
+  'translationZ',
+]
+export const radiusKeys = [
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomRightRadius',
+  'borderBottomLeftRadius',
+] as const
+export const widthKeys = [
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+] as const
+const writing = new WeakSet<View>()
+export const isWritingDecoration = (view: View) => writing.has(view)
+export const isDecorationProperty = (key: string): key is DecorationProperty =>
+  decorationProperties.includes(key as DecorationProperty)
+
+/** Core lengths may be numbers, px strings or parsed { value, unit } lengths. */
+export function dip(value: unknown): number {
+  if (value === undefined || value === null) return 0
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string') {
+    const match = /^(-?(?:\d+(?:\.\d*)?|\.\d+))(dip|px)?$/.exec(value.trim())
+    if (match)
+      return Number(match[1]) / (match[2] === 'px' ? Utils.layout.getDisplayDensity() : 1)
+  }
+  if (typeof value === 'object' && 'value' in value && 'unit' in value) {
+    const length = value as { value: number; unit: string }
+    if (Number.isFinite(length.value) && (length.unit === 'dip' || length.unit === 'px'))
+      return length.value / (length.unit === 'px' ? Utils.layout.getDisplayDensity() : 1)
+  }
+  throw new TypeError('Decoration animations require finite DIP or px lengths.')
+}
+
+export function singleShadow(view: View): Shadow {
+  const shadows = view.boxShadow
+  if (!Array.isArray(shadows) || shadows.length !== 1 || shadows[0]!.inset)
+    throw new TypeError('Shadow animation requires one existing outer boxShadow.')
+  return shadows[0]!
+}
+
+export function validateDecorationTarget(view: View, property: DecorationProperty) {
+  const shadow = property.startsWith('shadow')
+  const z = property === 'elevation' || property === 'translationZ'
+  if ((shadow && isAndroid) || (z && !isAndroid))
+    throw new TypeError(`"${property}" is only supported on ${z ? 'Android' : 'iOS'}.`)
+  if (z) return
+  if (view.style.clipPath || view.style.cornerShape === 'squircle')
+    throw new TypeError(
+      'Decoration animations require circular corners without a clipPath.',
+    )
+  for (const keys of [radiusKeys, widthKeys]) {
+    const values = keys.map((key) => dip(view[key]))
+    if (values.some((value) => value !== values[0]))
+      throw new TypeError(
+        'Decoration animations require uniform border widths and radii.',
+      )
+  }
+  const colors = [
+    view.borderTopColor,
+    view.borderRightColor,
+    view.borderBottomColor,
+    view.borderLeftColor,
+  ].map((color) => color?.argb ?? 0)
+  if (colors.some((color) => color !== colors[0]))
+    throw new TypeError('Decoration animations require uniform border colors.')
+  if (shadow) {
+    const value = singleShadow(view)
+    for (const length of [
+      value.offsetX,
+      value.offsetY,
+      value.blurRadius,
+      value.spreadRadius,
+    ])
+      dip(length)
+  }
+  if (
+    property === 'borderRadius' &&
+    isAndroid &&
+    view.boxShadow &&
+    (!Array.isArray(view.boxShadow) || view.boxShadow.length)
+  )
+    throw new TypeError(
+      'Animate Android radius with elevation shadows; CSS boxShadow caches its shape.',
+    )
+}
+
+export function validateDecorationFrames(
+  property: DecorationProperty,
+  frames: readonly (number | null)[],
+) {
+  if (
+    frames.some((value) => value !== null && clampDecoration(property, value) !== value)
+  )
+    throw new RangeError(`Invalid keyframes for "${property}".`)
+}
+export function clampDecoration(property: DecorationProperty, value: number): number {
+  if (property === 'shadowOpacity') return Math.max(0, Math.min(1, value))
+  return property === 'borderRadius' ||
+    property === 'borderWidth' ||
+    property === 'shadowRadius' ||
+    property === 'elevation'
+    ? Math.max(0, value)
+    : value
+}
+
+export function readDecoration(view: View, property: DecorationProperty): number {
+  if (property === 'borderRadius') {
+    const radius = !isAndroid ? view.nativeViewProtected?.layer?.cornerRadius : undefined
+    return typeof radius === 'number' ? radius : dip(view.borderTopLeftRadius)
+  }
+  if (property === 'borderWidth') return dip(view.borderTopWidth)
+  if (property === 'elevation')
+    return view.nativeViewProtected?.getElevation
+      ? view.nativeViewProtected.getElevation() / Utils.layout.getDisplayDensity()
+      : view.androidElevation || 0
+  if (property === 'translationZ')
+    return (
+      view.nativeViewProtected?.getTranslationZ?.() / Utils.layout.getDisplayDensity() ||
+      0
+    )
+  const shadow = singleShadow(view)
+  if (property === 'shadowOpacity')
+    return ((shadow.color?.argb ?? 0xff000000) >>> 24) / 255
+  return property === 'shadowRadius'
+    ? dip(shadow.blurRadius) / 2
+    : dip(property === 'shadowOffsetX' ? shadow.offsetX : shadow.offsetY)
+}
+
+export function writeDecoration(view: View, property: DecorationProperty, raw: number) {
+  const value = clampDecoration(property, raw)
+  writing.add(view)
+  try {
+    if (property === 'borderRadius' || property === 'borderWidth') view[property] = value
+    else if (property === 'elevation') view.androidElevation = value
+    else if (property === 'translationZ')
+      view.nativeViewProtected?.setTranslationZ?.(
+        value * Utils.layout.getDisplayDensity(),
+      )
+    else {
+      const shadow = { ...singleShadow(view) }
+      if (property === 'shadowOpacity')
+        shadow.color = new Color(
+          ((Math.round(value * 255) << 24) | ((shadow.color?.argb ?? 0) & 0xffffff)) >>>
+            0,
+        )
+      else if (property === 'shadowRadius') shadow.blurRadius = value * 2
+      else if (property === 'shadowOffsetX') shadow.offsetX = value
+      else shadow.offsetY = value
+      view.boxShadow = [shadow]
+      if (!isAndroid) preserveZeroShadow(view)
+    }
+  } finally {
+    writing.delete(view)
+  }
+}

package/src/drag-input.ts

@@ -0,0 +1,74 @@
+import { Utils, type PanGestureEventData, type View } from '@nativescript/core'
+import { getDriver } from './driver/index.js'
+
+interface Sample {
+  x: number
+  y: number
+  time: number
+}
+
+/** Android's raw coordinates avoid feedback from translating the touched view. */
+export class DragInput {
+  private samples: Sample[] = []
+  private lastMoved = 0
+  reset() {
+    this.samples = []
+    this.lastMoved = 0
+  }
+  read(event: PanGestureEventData, view: View) {
+    const ios = event.ios as UIPanGestureRecognizer | undefined
+    const android = event.android?.current as android.view.MotionEvent | undefined
+    const parent = view.parent?.nativeViewProtected ?? view.nativeViewProtected
+    const delta = ios
+      ? ios.translationInView(parent)
+      : { x: event.deltaX, y: event.deltaY }
+    const density = Utils.layout.getDisplayDensity()
+    const sample: Sample = android
+      ? {
+          x: android.getRawX() / density,
+          y: android.getRawY() / density,
+          time: Number(android.getEventTime()),
+        }
+      : { ...delta, time: getDriver().now() }
+    if (
+      Number.isFinite(sample.x) &&
+      Number.isFinite(sample.y) &&
+      Number.isFinite(sample.time)
+    ) {
+      const previous = this.samples.at(-1)
+      if (!previous || sample.x !== previous.x || sample.y !== previous.y)
+        this.lastMoved = sample.time
+      // Replace duplicate times (Android sends began + changed for the same event).
+      if (this.samples.at(-1)?.time === sample.time) this.samples.pop()
+      this.samples.push(sample)
+      while (this.samples.length > 2 && this.samples[1]!.time < sample.time - 100)
+        this.samples.shift()
+    }
+    const first = this.samples[0]
+    const elapsed = first ? sample.time - first.time : 0
+    // UIKit may retain its last movement velocity when the finger holds still
+    // before lifting. A stale velocity must not turn that hold into a fling.
+    const nativeVelocity = ios
+      ? sample.time - this.lastMoved > 100
+        ? { x: 0, y: 0 }
+        : ios.velocityInView(parent)
+      : undefined
+    const velocity = nativeVelocity ?? {
+      x: elapsed > 0 && elapsed <= 150 ? ((sample.x - first!.x) * 1000) / elapsed : 0,
+      y: elapsed > 0 && elapsed <= 150 ? ((sample.y - first!.y) * 1000) / elapsed : 0,
+    }
+    const action = android?.getActionMasked()
+    return {
+      x: delta.x,
+      y: delta.y,
+      velocityX: Number.isFinite(velocity.x) ? velocity.x : 0,
+      velocityY: Number.isFinite(velocity.y) ? velocity.y : 0,
+      cancelled:
+        event.state === 0 ||
+        action === 3 ||
+        action === 5 ||
+        action === 6 ||
+        (android ? android.getPointerCount() > 1 : (ios?.numberOfTouches ?? 1) > 1),
+    }
+  }
+}

package/src/drag-physics.ts

@@ -0,0 +1,110 @@
+import { solveDecay } from './decay.js'
+import { solveSpring, springPhysics } from './spring.js'
+
+export interface DragCurve {
+  type: 'drag'
+  velocity: number
+  friction: number
+  bounds: readonly [number, number]
+  snap?: readonly number[]
+  rubberband: boolean
+}
+
+export const clampDrag = (value: number, [min, max]: readonly [number, number]) =>
+  Math.max(min, Math.min(max, value))
+
+/** Bounded resistance; coordinates and the resistance length are DIPs. */
+export function resistDrag(
+  value: number,
+  bounds: readonly [number, number],
+  length: number,
+) {
+  const edge = clampDrag(value, bounds)
+  const distance = value - edge
+  return edge + (distance / (1 + Math.abs(distance) / length)) * 0.55
+}
+
+/** Recover the finger-space origin when grabbing an already rubberbanded pose. */
+export function resumeDrag(
+  value: number,
+  bounds: readonly [number, number],
+  length: number,
+) {
+  const edge = clampDrag(value, bounds)
+  const distance = value - edge
+  // A native edge spring or external owner can exceed the usual resistance range.
+  // Expand it for this gesture so every finite visible pose has a stable inverse.
+  length = Math.max(length, Math.abs(distance) * 4)
+  return { origin: edge + distance / (0.55 - Math.abs(distance) / length), length }
+}
+
+export function dragDestination(from: number, curve: DragCurve) {
+  const projected = solveDecay(from, curve.velocity, curve.friction, 0.25).to
+  if (curve.snap)
+    return curve.snap.reduce((best, point) =>
+      Math.abs(point - projected) < Math.abs(best - projected) ? point : best,
+    )
+  return clampDrag(projected, curve.bounds)
+}
+
+/** One precomputed motion. Native keyframes play both the coast and edge recovery. */
+export function solveDragRelease(from: number, curve: DragCurve) {
+  const to = dragDestination(from, curve)
+  const coast = solveDecay(from, curve.velocity, curve.friction, 0.25)
+  const edge = clampDrag(from, curve.bounds)
+  const springTo = (start: number, target: number, velocity: number) => {
+    const motion = solveSpring(
+      springPhysics({ duration: 500, bounce: 0 }),
+      start,
+      target,
+      velocity,
+      0.25,
+    )
+    const position = (time: number) => {
+      const value = time >= motion.duration ? target : motion.position(time)
+      return curve.rubberband ? value : clampDrag(value, curve.bounds)
+    }
+    return {
+      ...motion,
+      position,
+      velocity: (time: number) => {
+        const raw = motion.position(time)
+        return time >= motion.duration ||
+          (!curve.rubberband && raw !== clampDrag(raw, curve.bounds))
+          ? 0
+          : motion.velocity(time)
+      },
+    }
+  }
+  if (curve.snap || from !== edge)
+    return {
+      ...springTo(from, curve.snap ? to : edge, curve.velocity),
+      to: curve.snap ? to : edge,
+    }
+  if (to === coast.to) return coast
+
+  // Reach the boundary with the decay's actual velocity, then absorb that velocity.
+  const rate = -Math.log(curve.friction)
+  const collision = Math.max(
+    0,
+    -Math.log1p((-(to - from) * rate * 1000) / curve.velocity) / rate,
+  )
+  const recovery = springTo(to, to, coast.velocity(collision))
+  const duration = collision + (curve.rubberband ? recovery.duration : 0)
+  return {
+    to,
+    duration,
+    position: (time: number) =>
+      time >= duration
+        ? to
+        : time < collision
+          ? coast.position(time)
+          : recovery.position(time - collision),
+    velocity: (time: number) =>
+      time >= duration
+        ? 0
+        : time < collision
+          ? coast.velocity(time)
+          : recovery.velocity(time - collision),
+  }
+}