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

package/src/drag.ts

@@ -0,0 +1,395 @@
+import {
+  Application,
+  type EventData,
+  type PanGestureEventData,
+  type TouchGestureEventData,
+  type View,
+} from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import { DEFAULT_FRICTION } from './decay.js'
+import { DragInput } from './drag-input.js'
+import {
+  clampDrag,
+  resistDrag,
+  resumeDrag,
+  solveDragRelease,
+  type DragCurve,
+} from './drag-physics.js'
+import { currentValue, ViewAnimation, type Plan } from './engine.js'
+import type { PlaybackAnimation } from './playback.js'
+import { readValue, writeValue } from './properties.js'
+import type { Target } from './types.js'
+
+export interface DragPoint {
+  readonly x: number
+  readonly y: number
+}
+export interface DragEvent extends DragPoint {
+  /** DIPs per second, in the same coordinates as the translation. */
+  readonly velocityX: number
+  readonly velocityY: number
+}
+export interface DragRelease extends DragEvent {
+  readonly target: DragPoint
+  /** False on interruption/cancellation. Check before applying completion effects. */
+  readonly animation: PlaybackAnimation
+}
+export interface DragOptions {
+  /** Defaults to both. One finger only. */
+  axis?: 'x' | 'y' | 'both'
+  /** Absolute translateX/translateY limits in DIPs; omitted edges are unbounded. */
+  bounds?: { left?: number; right?: number; top?: number; bottom?: number }
+  /** Closest stop to the projected landing. Arrays apply to every enabled axis. */
+  snap?: readonly number[] | { x?: readonly number[]; y?: readonly number[] }
+  /** Resist beyond bounds and spring back. Defaults to false (hard limits). */
+  rubberband?: boolean
+  /** Decay retention per millisecond. Defaults to 0.998. */
+  friction?: number
+  onStart?: (event: DragEvent) => void
+  onMove?: (event: DragEvent) => void
+  onRelease?: (event: DragRelease) => void
+  onCancel?: (event: DragEvent) => void
+  onSettle?: (position: DragPoint) => void
+}
+export interface Drag {
+  readonly dragging: boolean
+  readonly settling: boolean
+  readonly paused: boolean
+  readonly disposed: boolean
+  /** Current presentation, including a native release animation in flight. */
+  readonly position: DragPoint
+  /** Cancel contact/release at its visible position, keeping the subscription. */
+  cancel(): void
+  /** Cancel and detach input. play() accepts new gestures; cancelled work stays cancelled. */
+  pause(): void
+  play(): void
+  dispose(): void
+}
+
+type Axis = 'x' | 'y'
+interface Settings {
+  axes: Axis[]
+  curves: Record<Axis, DragCurve>
+  callbacks: Pick<
+    DragOptions,
+    'onStart' | 'onMove' | 'onRelease' | 'onCancel' | 'onSettle'
+  >
+}
+const owners = new WeakMap<View, Drag>()
+
+function settings(options: DragOptions): Settings {
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Drag options must be an object.')
+  const axis = options.axis ?? 'both'
+  if (!['x', 'y', 'both'].includes(axis))
+    throw new TypeError('Drag axis must be x, y or both.')
+  const friction = options.friction ?? DEFAULT_FRICTION
+  if (!Number.isFinite(friction) || friction <= 0 || friction >= 1)
+    throw new RangeError('Drag friction must be between 0 and 1 exclusively.')
+  if (options.rubberband !== undefined && typeof options.rubberband !== 'boolean')
+    throw new TypeError('Drag rubberband must be boolean.')
+  const bounds = options.bounds ?? {}
+  if (
+    typeof bounds !== 'object' ||
+    Array.isArray(bounds) ||
+    Object.entries(bounds).some(
+      ([key, value]) =>
+        !['left', 'right', 'top', 'bottom'].includes(key) ||
+        (value !== undefined && !Number.isFinite(value)),
+    )
+  )
+    throw new RangeError('Drag bounds must have finite left/right/top/bottom edges.')
+  const x: readonly [number, number] = [
+    bounds.left ?? -Infinity,
+    bounds.right ?? Infinity,
+  ]
+  const y: readonly [number, number] = [
+    bounds.top ?? -Infinity,
+    bounds.bottom ?? Infinity,
+  ]
+  if (x[0] > x[1] || y[0] > y[1]) throw new RangeError('Drag bounds must be ordered.')
+  const snap = options.snap
+  const shared = Array.isArray(snap)
+  if (
+    snap !== undefined &&
+    !shared &&
+    (!snap ||
+      typeof snap !== 'object' ||
+      Object.keys(snap).some((key) => key !== 'x' && key !== 'y'))
+  )
+    throw new TypeError('Drag snap must be an array or x/y arrays.')
+  const stops = (
+    value: readonly number[] | undefined,
+    range: readonly [number, number],
+  ) => {
+    if (value === undefined) return undefined
+    if (
+      !Array.isArray(value) ||
+      !value.length ||
+      ![...value].every((n) => Number.isFinite(n) && n >= range[0] && n <= range[1])
+    )
+      throw new RangeError('Drag snap needs nonempty finite positions within bounds.')
+    return [...value]
+  }
+  const perAxis = snap as { x?: readonly number[]; y?: readonly number[] } | undefined
+  const axes: Axis[] = axis === 'both' ? ['x', 'y'] : [axis]
+  const curves = Object.fromEntries(
+    (['x', 'y'] as const).map((key) => [
+      key,
+      {
+        type: 'drag',
+        velocity: 0,
+        friction,
+        bounds: key === 'x' ? x : y,
+        snap: stops(
+          shared && axes.includes(key) ? snap : perAxis?.[key],
+          key === 'x' ? x : y,
+        ),
+        rubberband: options.rubberband ?? false,
+      },
+    ]),
+  ) as Record<Axis, DragCurve>
+  const callbacks = {
+    onStart: options.onStart,
+    onMove: options.onMove,
+    onRelease: options.onRelease,
+    onCancel: options.onCancel,
+    onSettle: options.onSettle,
+  }
+  for (const callback of Object.values(callbacks))
+    if (callback !== undefined && typeof callback !== 'function')
+      throw new TypeError('Drag callbacks must be functions.')
+  return { axes, curves, callbacks }
+}
+
+/** Main-thread pan updates; release physics play through Jolt's native animation drivers. */
+export function drag(target: Target, options: DragOptions = {}): Drag {
+  const view = toView(target)
+  const config = settings(options) // Invalid replacements leave the existing owner intact.
+  const previous = owners.get(view)
+  const controller = new DragController(view, config)
+  owners.set(view, controller)
+  // onCancel may synchronously install another drag. The most recent owner wins.
+  try {
+    previous?.dispose()
+  } catch (error) {
+    controller.dispose()
+    throw error
+  }
+  return controller
+}
+
+class DragController implements Drag {
+  private active = false
+  private disabled = false
+  private destroyed = false
+  private background = false
+  private attached = false
+  private blocked = false
+  private generation = 0
+  private release: PlaybackAnimation | undefined
+  private input = new DragInput()
+  private origin = { x: 0, y: 0 }
+  private last: DragEvent = { x: 0, y: 0, velocityX: 0, velocityY: 0 }
+  private lengths = { x: 200, y: 200 }
+  constructor(
+    private view: View,
+    private config: Settings,
+  ) {
+    view.on('loaded', this.attach)
+    view.on('unloaded', this.unload)
+    Application.on(Application.suspendEvent, this.suspend)
+    Application.on(Application.resumeEvent, this.resume)
+    this.attach()
+  }
+  get dragging() {
+    return this.active
+  }
+  get settling() {
+    return !!this.release
+  }
+  get paused() {
+    return this.disabled
+  }
+  get disposed() {
+    return this.destroyed
+  }
+  get position(): DragPoint {
+    return { x: currentValue(this.view, 'x'), y: currentValue(this.view, 'y') }
+  }
+  cancel = () => {
+    const wasActive = this.active
+    this.active = false
+    this.blocked = true
+    this.generation++
+    const release = this.release
+    this.release = undefined
+    release?.stop()
+    this.input.reset()
+    if (wasActive)
+      this.config.callbacks.onCancel?.({ ...this.last, velocityX: 0, velocityY: 0 })
+  }
+  pause = () => {
+    if (this.destroyed || this.disabled) return
+    this.disabled = true
+    this.detach()
+  }
+  play = () => {
+    if (this.destroyed) return
+    this.disabled = false
+    this.attach()
+  }
+  dispose = () => {
+    if (this.destroyed) return
+    this.destroyed = true
+    this.view.off('loaded', this.attach)
+    this.view.off('unloaded', this.unload)
+    Application.off(Application.suspendEvent, this.suspend)
+    Application.off(Application.resumeEvent, this.resume)
+    if (owners.get(this.view) === this) owners.delete(this.view)
+    this.detach()
+  }
+  private attach = () => {
+    if (
+      this.attached ||
+      this.destroyed ||
+      this.disabled ||
+      this.background ||
+      !this.view.isLoaded
+    )
+      return
+    this.blocked = false
+    this.attached = true
+    this.view.on('touch', this.touch)
+    this.view.on('pan', this.pan)
+  }
+  private detach = () => {
+    this.attached = false
+    this.view.off('touch', this.touch)
+    this.view.off('pan', this.pan)
+    this.cancel()
+  }
+  private unload = () => this.detach()
+  private suspend = () => {
+    this.background = true
+    this.detach()
+  }
+  private resume = () => {
+    this.background = false
+    this.attach()
+  }
+  private touch = (data: EventData) => {
+    const event = data as TouchGestureEventData
+    if (event.action === 'down') {
+      this.cancel()
+      this.blocked = false
+    } else if (event.action === 'cancel') this.cancel()
+  }
+  private pan = (data: EventData) => {
+    const event = data as PanGestureEventData
+    if (!this.attached || this.destroyed || this.disabled || this.background) return
+    if (this.view.isEnabled === false) {
+      this.cancel()
+      return
+    }
+    if (event.state === 1) this.input.reset()
+    const input = this.input.read(event, this.view)
+    if (input.cancelled) {
+      this.cancel()
+      return
+    }
+    if (this.blocked) return
+    if (event.state === 1) {
+      this.cancel()
+      if (!this.attached || this.destroyed || this.disabled) return
+      this.blocked = false
+      // Claim just the enabled axes, preserving the native presentation on takeover.
+      stop(this.view, this.config.axes)
+      this.origin = { x: readValue(this.view, 'x'), y: readValue(this.view, 'y') }
+      const size =
+        (this.view.parent as View | undefined)?.getActualSize() ??
+        this.view.getActualSize()
+      this.lengths = {
+        x: Math.max(1, size.width || 200),
+        y: Math.max(1, size.height || 200),
+      }
+      this.active = true
+      this.last = { ...this.origin, velocityX: 0, velocityY: 0 }
+      for (const axis of this.config.axes) {
+        const curve = this.config.curves[axis]
+        if (!curve.rubberband) continue
+        const resumed = resumeDrag(this.origin[axis], curve.bounds, this.lengths[axis])
+        this.origin[axis] = resumed.origin
+        this.lengths[axis] = resumed.length
+      }
+      this.input.read(event, this.view)
+      this.emit(() => this.config.callbacks.onStart?.({ ...this.last }))
+    }
+    if (!this.active) return
+    const generation = this.generation
+    if (Number.isFinite(input.x) && Number.isFinite(input.y)) {
+      const position = { x: this.last.x, y: this.last.y }
+      let vx = 0,
+        vy = 0
+      for (const axis of this.config.axes) {
+        const curve = this.config.curves[axis]
+        const raw = this.origin[axis] + input[axis]
+        const distance = raw - clampDrag(raw, curve.bounds)
+        const resistance =
+          distance === 0
+            ? 1
+            : curve.rubberband
+              ? 0.55 / (1 + Math.abs(distance) / this.lengths[axis]) ** 2
+              : 0
+        position[axis] = curve.rubberband
+          ? resistDrag(raw, curve.bounds, this.lengths[axis])
+          : clampDrag(raw, curve.bounds)
+        if (axis === 'x') vx = input.velocityX * resistance
+        else vy = input.velocityY * resistance
+        stop(this.view, [axis])
+        writeValue(this.view, axis, position[axis])
+      }
+      this.last = { ...position, velocityX: vx, velocityY: vy }
+      if (event.state !== 3)
+        this.emit(() => this.config.callbacks.onMove?.({ ...this.last }))
+    }
+    if (!this.active || generation !== this.generation) return
+    if (event.state === 3) this.emit(() => this.finish())
+  }
+  private emit(callback: () => void) {
+    try {
+      callback()
+    } catch (error) {
+      // A failing application callback must not leave live input or an orphaned fling.
+      this.active = false
+      this.dispose()
+      throw error
+    }
+  }
+  private finish() {
+    this.active = false
+    const generation = ++this.generation
+    const event = { ...this.last }
+    const target = { x: event.x, y: event.y }
+    const plans: Plan[] = this.config.axes.map((axis) => {
+      const curve = {
+        ...this.config.curves[axis],
+        velocity: axis === 'x' ? event.velocityX : event.velocityY,
+      }
+      target[axis] = solveDragRelease(event[axis], curve).to
+      return {
+        property: axis,
+        keyframes: [null, null],
+        transition: { curve, delay: 0, repeat: 0, reverse: false },
+      }
+    })
+    const animation = new ViewAnimation(this.view, plans)
+    this.release = animation
+    void animation.finished.then((finished) => {
+      if (generation !== this.generation || this.destroyed) return
+      this.release = undefined
+      if (finished) this.config.callbacks.onSettle?.({ ...target })
+    })
+    this.emit(() => this.config.callbacks.onRelease?.({ ...event, target, animation }))
+  }
+}

package/src/driver/android-color.ts

@@ -0,0 +1,170 @@
+import { type View } from '@nativescript/core'
+import { readColor, type ColorProperty } from '../color.js'
+import { androidPlayback, type AndroidPlayback } from './android-playback.js'
+import type { PlaybackCommand } from '../playback.js'
+import type { Track } from '../track.js'
+
+interface NativeTarget {
+  getColor(): number
+  setColor(value: number): void
+  isSupported(): boolean
+}
+interface ColorHandle {
+  control(elapsed: number, paused: boolean, command?: PlaybackCommand): void
+  cancel(): void
+  elapsed(): number
+  target: NativeTarget
+}
+const playing = new WeakMap<View, Map<ColorProperty, ColorHandle>>()
+
+export function syncAndroidColor(view: View) {
+  for (const handle of playing.get(view)?.values() ?? [])
+    handle.target.setColor(handle.target.getColor())
+}
+
+export function presentedAndroidColor(view: View, property: ColorProperty): number {
+  const active = playing.get(view)?.get(property)
+  if (active) return active.target.getColor() >>> 0
+  if (property === 'color' && view.nativeViewProtected instanceof android.widget.TextView)
+    return view.nativeViewProtected.getCurrentTextColor() >>> 0
+  return readColor(view, property)
+}
+
+export function playAndroidColor(
+  view: View,
+  track: Track,
+  onEnd: (finished?: boolean) => void,
+): ColorHandle {
+  const property = track.property as ColorProperty
+  const changes =
+    property === 'borderColor'
+      ? [
+          'borderTopColorChange',
+          'borderRightColorChange',
+          'borderBottomColorChange',
+          'borderLeftColorChange',
+        ]
+      : [`${property}Change`]
+  const bridge = globalThis as unknown as {
+    org: {
+      rafaelaugusto: {
+        jolt: {
+          ColorTarget: new (
+            view: android.view.View,
+            property: number,
+            color: number,
+          ) => NativeTarget
+        }
+      }
+    }
+  }
+  let target: NativeTarget
+  try {
+    target = new bridge.org.rafaelaugusto.jolt.ColorTarget(
+      view.nativeViewProtected,
+      property === 'backgroundColor' ? 0 : property === 'borderColor' ? 1 : 2,
+      track.values[0]! | 0,
+    )
+  } catch {
+    // A JS-only update cannot install the native plugin. Keep the final model.
+    onEnd(false)
+    return {
+      cancel() {},
+      control() {},
+      elapsed: () => 0,
+      target: {
+        getColor: () => readColor(view, property),
+        setColor() {},
+        isSupported: () => false,
+      },
+    }
+  }
+  const frames = Array.create(android.animation.Keyframe, track.values.length)
+  track.values.forEach((value, index) => {
+    frames[index] = android.animation.Keyframe.ofInt(track.times[index]!, value | 0)
+  })
+  const holder = android.animation.PropertyValuesHolder.ofKeyframe('color', frames)
+  holder.setEvaluator(new android.animation.ArgbEvaluator())
+  const holders = Array.create(android.animation.PropertyValuesHolder, 1)
+  holders[0] = holder
+  const animator = android.animation.ObjectAnimator.ofPropertyValuesHolder(
+    target as unknown as java.lang.Object,
+    holders,
+  )
+  animator.setDuration(Math.max(track.duration, 1))
+  animator.setStartDelay(track.delay)
+  animator.setInterpolator(new android.view.animation.LinearInterpolator())
+  if (track.repeat > 0) {
+    animator.setRepeatCount(
+      Number.isFinite(track.repeat)
+        ? track.repeat
+        : android.animation.ValueAnimator.INFINITE,
+    )
+    animator.setRepeatMode(
+      track.reverse
+        ? android.animation.ValueAnimator.REVERSE
+        : android.animation.ValueAnimator.RESTART,
+    )
+  }
+  let stopped = false,
+    queued = false
+  const cleanup = () => {
+    if (stopped) return
+    stopped = true
+    view.off('unloaded', cancel)
+    if (property === 'color') {
+      view.off('textChange', invalidate)
+      view.off('formattedTextChange', invalidate)
+    }
+    for (const name of changes) view.style.off(name, invalidate)
+    if (playing.get(view)?.get(property) === handle) playing.get(view)?.delete(property)
+  }
+  let player: AndroidPlayback | undefined
+  const cancel = () => {
+    if (stopped) return
+    cleanup()
+    player?.cancel()
+    onEnd(false)
+  }
+  const invalidate = () => {
+    if (stopped || queued) return
+    queued = true
+    void Promise.resolve().then(() => {
+      queued = false
+      if (!stopped) cancel()
+    })
+  }
+  const handle: ColorHandle = {
+    target,
+    elapsed: () => player?.elapsed() ?? 0,
+    control(time, paused, command) {
+      player?.control(time, paused, command)
+    },
+    cancel() {
+      cleanup()
+      player?.cancel()
+    },
+  }
+  let entries = playing.get(view)
+  if (!entries) playing.set(view, (entries = new Map()))
+  entries.set(property, handle)
+  view.on('unloaded', cancel)
+  if (property === 'color') {
+    view.on('textChange', invalidate)
+    view.on('formattedTextChange', invalidate)
+  }
+  for (const name of changes) view.style.on(name, invalidate)
+  if (target.isSupported()) {
+    target.setColor(track.values[0]! | 0)
+    player = androidPlayback(animator, track, () => {
+      if (!stopped) {
+        cleanup()
+        onEnd()
+      }
+    })
+  } else {
+    cleanup()
+    onEnd(false)
+  }
+  return handle
+}