@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/physics/native.ts

@@ -0,0 +1,121 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { PhysicsSnapshot, PhysicsVector } from './index.js'
+export interface CircleDriver {
+  enabled(active: boolean): void
+  resize(width: number, height: number): void
+  impulse(index: number, x: number, y: number): void
+  attach(index: number, options: NativeAttachment | null): void
+  snapTo(index: number, target: number): void
+  reset(): void
+  snapshot(): Omit<PhysicsSnapshot, 'bodies'> & {
+    bodies: Omit<PhysicsSnapshot['bodies'][number], 'id'>[]
+  }
+  dispose(): void
+}
+export interface NativeAttachment {
+  x: number
+  y: number
+  length: number
+  stiffness: number
+  damping: number
+  line: { color: number; width: number } | null
+}
+interface Configuration {
+  width: number
+  height: number
+  gravity: PhysicsVector
+  restitution: number
+  damping: number
+  bodies: {
+    x: number
+    y: number
+    radius: number
+    mass: number
+    vx: number
+    vy: number
+    attachment: NativeAttachment | null
+    drag: Omit<NativeAttachment, 'x' | 'y'> | null
+    snap: {
+      points: PhysicsVector[]
+      stiffness: number
+      damping: number
+      projection: number
+    } | null
+  }[]
+}
+export type CircleFactory = (
+  container: View,
+  views: readonly View[],
+  options: Configuration,
+) => CircleDriver
+let override: CircleFactory | undefined
+/** Internal test seam; not exported from the physics entry. */
+export function setCircleFactory(factory: CircleFactory | undefined) {
+  override = factory
+}
+export const createCircleDriver: CircleFactory = (container, views, options) => {
+  if (override) return override(container, views, options)
+  if (isIOS) {
+    if (typeof JoltCircleWorld === 'undefined')
+      throw new Error('Rebuild the native app to use physicsWorld().')
+    const native = JoltCircleWorld.createOptions(
+      container.nativeViewProtected,
+      JSON.stringify(options),
+    )
+    try {
+      if (typeof native.attachOptions !== 'function')
+        throw new Error('Rebuild the native app to use physics attachments.')
+      if (
+        options.bodies.some((b) => b.drag) &&
+        typeof native.supportsPointerSpring !== 'function'
+      )
+        throw new Error('Rebuild the native app to use spring dragging.')
+      views.forEach((v, i) => native.connectIndex(v.nativeViewProtected, i))
+    } catch (e) {
+      native.dispose()
+      throw e
+    }
+    return {
+      enabled: (v) => native.setEnabled(v),
+      resize: (w, h) => native.resizeHeight(w, h),
+      impulse: (i, x, y) => native.impulseXY(i, x, y),
+      attach: (i, options) => native.attachOptions(i, JSON.stringify(options)),
+      snapTo: (i, target) => native.snapToTarget(i, target),
+      reset: () => native.reset(),
+      snapshot: () => JSON.parse(native.snapshot()),
+      dispose: () => native.dispose(),
+    }
+  }
+  if (
+    typeof org === 'undefined' ||
+    typeof org.rafaelaugusto.jolt.CircleWorld !== 'function'
+  )
+    throw new Error('Rebuild the native app to use physicsWorld().')
+  const native = new org.rafaelaugusto.jolt.CircleWorld(
+    container.nativeViewProtected,
+    JSON.stringify(options),
+  )
+  try {
+    if (typeof native.attach !== 'function')
+      throw new Error('Rebuild the native app to use physics attachments.')
+    if (
+      options.bodies.some((b) => b.drag) &&
+      typeof native.supportsPointerSpring !== 'function'
+    )
+      throw new Error('Rebuild the native app to use spring dragging.')
+    views.forEach((v, i) => native.connect(v.nativeViewProtected, i))
+  } catch (e) {
+    native.dispose()
+    throw e
+  }
+  return {
+    enabled: (v) => native.setEnabled(v),
+    resize: (w, h) => native.resize(w, h),
+    impulse: (i, x, y) => native.impulse(i, x, y),
+    attach: (i, options) => native.attach(i, JSON.stringify(options)),
+    snapTo: (i, target) => native.snapTo(i, target),
+    reset: () => native.reset(),
+    snapshot: () => JSON.parse(native.snapshot()),
+    dispose: () => native.dispose(),
+  }
+}

package/src/playback-group.ts

@@ -6,7 +6,7 @@ import {
   type ViewAnimation,
 } from './engine.js'
 import { getDriver } from './driver/index.js'
-import { createClock, type PlaybackClock } from './playback.js'
+import { createClock, registerPlayback, type PlaybackClock } from './playback.js'
 import { validateProgress, type PlaybackAnimation } from './playback.js'
 
 /** Staggered views share a finite time range. Shorter children remain seekable
@@ -17,6 +17,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
   let finalProgress: number | undefined
   let clock: PlaybackClock | undefined
   let pendingProgress: number | undefined
+  let changed = () => {}
   const duration = () => Math.max(0, ...children.map((child) => child.duration))
   const ensureClock = () => {
     if (clock || settled || children.some((child) => !child.ready)) return
@@ -44,6 +45,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
     clock?.seek(total * value)
     for (const child of children) child.seekTime(total * value)
     finishIfIdle()
+    changed()
   }
   for (const child of children) {
     child.onIdle(finishIfIdle)
@@ -52,6 +54,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       if (pendingProgress !== undefined && children.every((child) => child.ready))
         seek(pendingProgress)
       finishIfIdle()
+      changed()
     })
   }
   const finished = Promise.all(children.map((child) => child.finished)).then(
@@ -63,6 +66,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
           : 0
       settled = true
       clock?.cancel()
+      changed()
       return results.every(Boolean)
     },
   )
@@ -91,6 +95,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         paused = true
         clock?.pause()
         children.forEach((child) => child.pause())
+        changed()
       }
     },
     play() {
@@ -99,6 +104,7 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
         clock?.play()
         children.forEach((child) => child.play())
         finishIfIdle()
+        changed()
       }
     },
     stop() {
@@ -106,9 +112,19 @@ export function playbackGroup(children: readonly ViewAnimation[]): PlaybackAnima
       settled = true
       clock?.cancel()
       children.forEach((child) => child.stop())
+      changed()
     },
     then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
   }
+  changed = registerPlayback(animation, () => ({
+    position: pendingProgress,
+    time: finalProgress === undefined ? (clock?.time() ?? 0) : finalProgress * duration(),
+    duration: duration(),
+    paused,
+    ready: children.every((child) => child.ready),
+    settled,
+    completed: finalProgress === 1,
+  }))
   setArrival(animation, Promise.all(children.map(arrivalOf)))
   const listeners = new Set<() => void>()
   const timings = children.map((child) => arrivalTimingOf(child)!)

package/src/playback.ts

@@ -23,6 +23,47 @@ export interface PlaybackClock {
   cancel(): void
 }
 
+/** Boundary notifications, never frame callbacks. Consumers sample this same clock. */
+export interface PlaybackState {
+  readonly position?: number
+  readonly time: number
+  readonly duration: number
+  readonly paused: boolean
+  readonly ready: boolean
+  readonly settled: boolean
+  readonly completed: boolean
+}
+
+const sources = new WeakMap<
+  Animation,
+  {
+    read(): PlaybackState
+    listeners: Set<() => void>
+  }
+>()
+
+export function registerPlayback(animation: Animation, read: () => PlaybackState) {
+  const source = { read, listeners: new Set<() => void>() }
+  sources.set(animation, source)
+  return () => {
+    for (const listener of [...source.listeners]) listener()
+  }
+}
+
+export function playbackSource(animation: Animation) {
+  const source = sources.get(animation)
+  if (!source) throw new TypeError('This animation does not expose a playback clock.')
+  return {
+    read: source.read,
+    subscribe(listener: () => void) {
+      source.listeners.add(listener)
+      return () => {
+        source.listeners.delete(listener)
+      }
+    },
+  }
+}
+
 /** Read only on user commands; there is no frame loop in JavaScript. */
 export function createClock(now: () => number, initial = 0): PlaybackClock {
   let offset = initial

package/src/predictive-back/index.ts

@@ -0,0 +1,280 @@
+import { isAndroid, Trace, type View } from '@nativescript/core'
+import { nativeBackSessions } from './presentation.js'
+import { onReducedMotion, reducedMotion, timeScale } from '../config.js'
+import { springPhysics } from '../spring.js'
+import { springs, type Spring } from '../transition.js'
+
+export type PredictiveBackValues = Partial<
+  Record<
+    'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'opacity' | 'rotate',
+    readonly [number, number]
+  >
+>
+export type PredictiveBackState =
+  'idle' | 'tracking' | 'cancelling' | 'finishing' | 'committing' | 'disposed'
+export interface PredictiveBackEvent {
+  state: PredictiveBackState
+  edge?: 'left' | 'right'
+  /** Release sample only; updates during the gesture stay native. Velocity is progress/second. */
+  release?: Readonly<{ progress: number; velocity: number }>
+  outcome?: 'completed' | 'cancelled'
+  reason?: 'rejected' | 'error' | 'timeout'
+}
+export interface PredictiveBackOptions {
+  /** Close the owned surface or navigate once. Return false to spring back after a guard rejects. */
+  commit: (options: { animated: false }) => boolean | void | Promise<boolean | void>
+  spring?:
+    | keyof typeof springs
+    | Pick<Spring, 'duration' | 'bounce' | 'stiffness' | 'damping' | 'mass'>
+  enabled?: boolean
+  /** Mirror x and rotate when starting at the right edge. Default true. */
+  mirrorX?: boolean
+  /** Maximum wait for commit, 1–10000 ms. Default 5000. Does not cancel the caller's promise. */
+  commitTimeout?: number
+  /** Lifecycle only; no per-frame JavaScript notifications. */
+  onState?: (event: PredictiveBackEvent) => void
+}
+export interface PredictiveBack {
+  /** Android 14+, attached view-tree dispatcher owner and the native plugin are required. */
+  readonly supported: boolean
+  readonly state: PredictiveBackState
+  /** Read on demand, never pushed through JavaScript on each frame. */
+  readonly progress: number
+  enabled: boolean
+  /** Accessible button/keyboard equivalent. Unsupported platforms call commit without motion. */
+  back(): void
+  /** Rolls back a held gesture. An OS release already committed continues. */
+  cancel(): void
+  dispose(): void
+}
+const owners = new WeakMap<View, PredictiveBack>()
+
+/** Animate a dedicated surface with Android's system back gesture. Create after the view is attached. */
+export function predictiveBack(
+  view: View,
+  values: PredictiveBackValues,
+  options: PredictiveBackOptions,
+): PredictiveBack {
+  if (!options || typeof options.commit !== 'function')
+    throw new TypeError('predictiveBack requires a commit callback.')
+  if (!values || typeof values !== 'object' || !Object.keys(values).length)
+    throw new TypeError('predictiveBack requires at least one transform or opacity pair.')
+  const parsed: PredictiveBackValues = {}
+  for (const [key, pair] of Object.entries(values)) {
+    if (!['x', 'y', 'scale', 'scaleX', 'scaleY', 'opacity', 'rotate'].includes(key))
+      throw new TypeError(`Unsupported predictive back property: ${key}.`)
+    const neutral = key.startsWith('scale') || key === 'opacity' ? 1 : 0
+    if (
+      !Array.isArray(pair) ||
+      pair.length !== 2 ||
+      pair.some((v) => typeof v !== 'number' || !Number.isFinite(v)) ||
+      pair[0] !== neutral
+    )
+      throw new RangeError(`${key} requires two finite values starting at ${neutral}.`)
+    if (
+      (key.startsWith('scale') && pair[1]! <= 0) ||
+      (key === 'opacity' && (pair[1]! < 0 || pair[1]! > 1))
+    )
+      throw new RangeError(`Invalid ${key} endpoint.`)
+    parsed[key as keyof PredictiveBackValues] = [pair[0]!, pair[1]!]
+  }
+  if (parsed.scale && (parsed.scaleX || parsed.scaleY))
+    throw new TypeError('Use scale or scaleX/scaleY, not both.')
+  for (const key of ['enabled', 'mirrorX'] as const)
+    if (options[key] !== undefined && typeof options[key] !== 'boolean')
+      throw new TypeError(`${key} must be boolean.`)
+  const timeout = options.commitTimeout ?? 5000
+  if (!Number.isFinite(timeout) || timeout < 1 || timeout > 10000)
+    throw new RangeError('commitTimeout must be between 1 and 10000 ms.')
+  const input =
+    typeof options.spring === 'string'
+      ? Object.hasOwn(springs, options.spring)
+        ? springs[options.spring]
+        : undefined
+      : options.spring
+  if (options.spring !== undefined && !input)
+    throw new TypeError('Unknown predictive back spring.')
+  if (input !== undefined && (typeof input !== 'object' || Array.isArray(input)))
+    throw new TypeError('spring must be a named spring or a physics object.')
+  for (const [key, value] of Object.entries(input ?? {}) as [string, unknown][]) {
+    if (!['type', 'duration', 'bounce', 'stiffness', 'damping', 'mass'].includes(key))
+      throw new TypeError(`Unsupported spring option: ${key}.`)
+    if (key === 'type') {
+      if (value !== 'spring') throw new TypeError('A spring is required.')
+      continue
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value))
+      throw new RangeError(`${key} must be finite.`)
+    if (['duration', 'stiffness', 'mass'].includes(key) && value <= 0)
+      throw new RangeError(`${key} must be positive.`)
+    if (key === 'damping' && value < 0)
+      throw new RangeError('damping must be nonnegative.')
+  }
+  const physics = springPhysics(input ?? springs.smooth)
+  if (Object.values(physics).some((v) => !Number.isFinite(v)))
+    throw new RangeError('Spring physics must be finite.')
+  if (owners.has(view))
+    throw new Error(
+      'This view already has a predictive back owner. Dispose it before rebinding.',
+    )
+  let native: org.rafaelaugusto.jolt.PredictiveBackSession | undefined
+  let supported = false,
+    enabled = options.enabled ?? true
+  let state: PredictiveBackState = 'idle',
+    edge: PredictiveBackEvent['edge']
+  let reason: PredictiveBackEvent['reason']
+  let generation = 0,
+    timer: ReturnType<typeof setTimeout> | undefined
+  let offMotion: (() => void) | undefined
+  const emit = (next: PredictiveBackState, extra: Partial<PredictiveBackEvent> = {}) => {
+    state = next
+    try {
+      options.onState?.({ state, ...(edge ? { edge } : {}), ...extra })
+    } catch (error) {
+      Trace.write(
+        `Predictive back observer failed: ${String(error)}`,
+        'Jolt',
+        Trace.messageType.error,
+      )
+    }
+  }
+  const clear = () => {
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+  }
+  const finishCommit = (
+    token: number,
+    accepted: boolean,
+    why?: PredictiveBackEvent['reason'],
+  ) => {
+    if (token !== generation || state !== 'committing') return
+    generation++
+    clear()
+    reason = why
+    if (native) native.completeCommit(accepted)
+    else {
+      emit('idle', {
+        outcome: accepted ? 'completed' : 'cancelled',
+        ...(why ? { reason: why } : {}),
+      })
+      if (accepted) control.dispose()
+    }
+  }
+  const commit = () => {
+    const token = ++generation
+    emit('committing')
+    if (state !== 'committing') return
+    timer = setTimeout(() => finishCommit(token, false, 'timeout'), timeout)
+    try {
+      Promise.resolve(options.commit({ animated: false })).then(
+        (result) =>
+          finishCommit(
+            token,
+            result !== false,
+            result === false ? 'rejected' : undefined,
+          ),
+        () => finishCommit(token, false, 'error'),
+      )
+    } catch {
+      finishCommit(token, false, 'error')
+    }
+  }
+  const cleanup = () => {
+    if (state === 'disposed') return
+    generation++
+    clear()
+    offMotion?.()
+    offMotion = undefined
+    view.off('unloaded', unload)
+    if (owners.get(view) === control) owners.delete(view)
+    native = undefined
+    nativeBackSessions.delete(control)
+    emit('disposed')
+  }
+  const unload = () => {
+    if (state !== 'committing') control.dispose()
+  }
+  const control: PredictiveBack = {
+    get supported() {
+      return supported
+    },
+    get state() {
+      return state
+    },
+    get progress() {
+      return native?.getProgress() ?? 0
+    },
+    get enabled() {
+      return enabled
+    },
+    set enabled(value) {
+      if (typeof value !== 'boolean') throw new TypeError('enabled must be boolean.')
+      if (state === 'disposed') return
+      enabled = value
+      native?.setInputEnabled(value)
+    },
+    back() {
+      if (
+        !enabled ||
+        state === 'disposed' ||
+        state === 'committing' ||
+        state === 'finishing'
+      )
+        return
+      if (native) native.handleOnBackPressed()
+      else commit()
+    },
+    cancel() {
+      native?.cancel()
+    },
+    dispose() {
+      native?.dispose()
+      cleanup()
+    },
+  }
+  if (
+    isAndroid &&
+    typeof org !== 'undefined' &&
+    org.rafaelaugusto?.jolt?.PredictiveBackSession
+  ) {
+    const Native = org.rafaelaugusto.jolt.PredictiveBackSession
+    native =
+      Native.attach(
+        view.nativeViewProtected,
+        JSON.stringify({
+          values: parsed,
+          ...physics,
+          mirrorX: options.mirrorX ?? true,
+          enabled,
+          reduced: reducedMotion(),
+          timeScale: timeScale(),
+        }),
+        new Native.Listener({
+          onState(code, progress, velocity, side) {
+            if (state === 'disposed') return
+            edge = side === 0 ? 'left' : side === 1 ? 'right' : undefined
+            if (code === 1) {
+              reason = undefined
+              emit('tracking')
+            } else if (code === 2 || code === 3)
+              emit(code === 2 ? 'cancelling' : 'finishing', {
+                release: { progress, velocity },
+              })
+            else if (code === 4) commit()
+            else if (code === 5) {
+              emit('idle', { outcome: 'cancelled', ...(reason ? { reason } : {}) })
+              reason = undefined
+            } else if (code === 6) emit('idle', { outcome: 'completed' })
+            else if (code === 7) cleanup()
+          },
+        }),
+      ) ?? undefined
+    supported = !!native
+    if (native) nativeBackSessions.set(control, native)
+  }
+  owners.set(view, control)
+  view.on('unloaded', unload)
+  if (native)
+    offMotion = onReducedMotion((reduced) => native?.setMotion(reduced, timeScale()))
+  return control
+}

package/src/predictive-back/presentation.ts

@@ -0,0 +1,6 @@
+import type { PredictiveBack } from './index.js'
+/** Internal native-to-native composition. Never a JS progress callback. */
+export const nativeBackSessions = new WeakMap<
+  PredictiveBack,
+  org.rafaelaugusto.jolt.PredictiveBackSession
+>()

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 { animate, startingValues, stop, toView } from './animate.js'
+import { identity } from './mixer.js'
 import type { PlaybackAnimation } from './playback.js'
 import { readValue } from './properties.js'
 import type { SpringName, Transition } from './transition.js'
@@ -25,6 +26,7 @@ export function press(
 ): () => void {
   const view = toView(target)
   const properties = [...startingValues(pressed, options).keys()]
+  const layer = typeof options === 'object' ? options.layer : undefined
   let rest: Keyframes | undefined
   let active: PlaybackAnimation | undefined
 
@@ -34,7 +36,11 @@ export function press(
       rest = Object.fromEntries(
         properties.map((p) => [
           p,
-          isColorProperty(p) ? new Color(readValue(view, p)) : readValue(view, p),
+          layer !== undefined
+            ? identity(p)
+            : isColorProperty(p)
+              ? new Color(readValue(view, p))
+              : readValue(view, p),
         ]),
       )
       active = animate(view, pressed, options ?? pressIn)
@@ -52,6 +58,8 @@ export function press(
 
   const cancel = () => {
     active?.stop()
+    // A completed press still holds its layer contribution until it is removed.
+    if (layer !== undefined) stop(view, properties, { layer })
     active = undefined
     rest = undefined
   }

package/src/reorder/handle.ts

@@ -0,0 +1,9 @@
+import { Button, isIOS } from '@nativescript/core'
+
+/** Focusable native handle: Alt/Option + ↑/↓ moves its current item. */
+export class ReorderHandle extends Button {
+  override createNativeView(): ReturnType<Button['createNativeView']> {
+    if (isIOS) return JoltReorderHandle.new()
+    return new org.rafaelaugusto.jolt.ReorderHandle(this._context)
+  }
+}