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

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/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)
+  }
+}

package/src/reorder/index.ts

@@ -0,0 +1,243 @@
+import { Application, ListView, Trace, type View } from '@nativescript/core'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import { coreListAdapter } from './list-view.js'
+import { itemKeys, moveAt, sameKeys } from './model.js'
+import type {
+  Reorder,
+  ReorderAdapter,
+  ReorderAdapterDriver,
+  ReorderCancelReason,
+  ReorderKey,
+  ReorderNativeEvent,
+  ReorderOptions,
+} from './types.js'
+
+export { coreListAdapter }
+export { ReorderHandle } from './handle.js'
+export { ReorderSurface } from './surface.js'
+export type * from './types.js'
+
+const owners = new WeakMap<View, { dispose(): void }>()
+function report(callback: () => void) {
+  try {
+    callback()
+  } catch (error) {
+    Trace.write(
+      `Jolt reorder callback failed: ${String(error)}`,
+      Trace.categories.Error,
+      Trace.messageType.error,
+    )
+  }
+}
+
+/** Reorder a flat, vertical Core ListView, or an explicitly supported adapter. */
+export function reorder<T, K extends ReorderKey = ReorderKey>(
+  source: ListView | ReorderAdapter<T>,
+  options: ReorderOptions<T, K>,
+): Reorder<K> {
+  if (
+    !options ||
+    typeof options.key !== 'function' ||
+    typeof options.onCommit !== 'function'
+  )
+    throw new TypeError('reorder() requires key(item) and onCommit(move).')
+  const adapter = source instanceof ListView ? coreListAdapter<T>(source) : source
+  if (
+    !adapter?.view ||
+    typeof adapter.items !== 'function' ||
+    typeof adapter.subscribe !== 'function' ||
+    typeof adapter.attach !== 'function'
+  )
+    throw new TypeError('Provide a Core ListView or a ReorderAdapter.')
+  for (const callback of [options.onStart, options.onCancel])
+    if (callback !== undefined && typeof callback !== 'function')
+      throw new TypeError('Reorder callbacks must be functions.')
+  if (
+    options.handle !== undefined &&
+    typeof options.handle !== 'string' &&
+    typeof options.handle !== 'function'
+  )
+    throw new TypeError('The reorder handle must be a view id or resolver.')
+  const longPress = options.longPress ?? 350,
+    edgeSize = options.edge?.size ?? 72,
+    edgeSpeed = options.edge?.speed ?? 640
+  if (!Number.isFinite(longPress) || longPress < 150 || longPress > 2000)
+    throw new RangeError('Reorder longPress must be between 150 and 2000 ms.')
+  if (![edgeSize, edgeSpeed].every((value) => Number.isFinite(value) && value > 0))
+    throw new RangeError('Reorder edge size and speed must be positive finite numbers.')
+
+  const view = adapter.view
+  let keys = itemKeys(adapter.items(), options.key)
+  owners.get(view)?.dispose()
+  let driver: ReorderAdapterDriver | undefined,
+    active: { key: K; index: number; keys: K[] } | undefined,
+    disposed = false,
+    paused = false
+  const read = () => itemKeys(adapter.items(), options.key)
+
+  function cancel(reason: ReorderCancelReason) {
+    const previous = active
+    active = undefined
+    driver?.cancel()
+    if (previous) report(() => options.onCancel?.({ key: previous.key, reason }))
+  }
+  function refresh() {
+    if (disposed) return
+    let next: K[]
+    try {
+      next = read()
+    } catch (error) {
+      cancel('data-changed')
+      throw error
+    }
+    if (active) cancel(next.includes(active.key) ? 'data-changed' : 'removed')
+    keys = next
+  }
+  function event(event: ReorderNativeEvent) {
+    if (disposed || paused) return
+    if (event.type === 'start') {
+      keys = read()
+      const key = keys[event.index]
+      if (key === undefined) {
+        driver?.cancel()
+        return
+      }
+      active = { key, index: event.index, keys: [...keys] }
+      report(() => options.onStart?.(key))
+    } else if (event.type === 'cancel') {
+      cancel(event.geometryChanged ? 'geometry-changed' : 'cancelled')
+    } else {
+      const previous = active
+      if (!previous) return
+      const next = read()
+      if (!sameKeys(previous.keys, next) || event.index !== previous.index) {
+        cancel(next.includes(previous.key) ? 'data-changed' : 'removed')
+        keys = next
+        return
+      }
+      const move = moveAt(previous.keys, previous.index, event.toIndex)
+      active = undefined
+      if (move) report(() => options.onCommit(move))
+      else report(() => options.onCancel?.({ key: previous.key, reason: 'unchanged' }))
+      keys = read()
+    }
+  }
+  function moveTo(key: K, toIndex: number): boolean {
+    if (disposed || paused) return false
+    cancel('cancelled')
+    keys = read()
+    const move = moveAt(keys, keys.indexOf(key), toIndex)
+    if (!move) return false
+    report(() => options.onCommit(move))
+    keys = read()
+    return true
+  }
+  function attach() {
+    if (disposed || driver || !view.isLoaded) return
+    keys = read()
+    driver = adapter.attach({
+      handle: options.handle,
+      longPress,
+      edgeSize,
+      edgeSpeed,
+      reducedMotion: reducedMotion(),
+      accessibility: {
+        moveUp: options.accessibility?.moveUp ?? 'Move up',
+        moveDown: options.accessibility?.moveDown ?? 'Move down',
+      },
+      event: (input) => {
+        try {
+          event(input)
+        } catch (error) {
+          cancel('data-changed')
+          report(() => {
+            throw error
+          })
+        }
+      },
+      move: (index, direction) => {
+        keys = read()
+        const key = keys[index]
+        return key !== undefined && moveTo(key, index + direction) ? key : undefined
+      },
+      keyAt: (index) => keys[index],
+      indexOf: (key) => {
+        try {
+          return read().indexOf(key as K)
+        } catch {
+          return -1
+        }
+      },
+    })
+    driver.setEnabled(!paused)
+  }
+  function unload() {
+    cancel('unloaded')
+    driver?.dispose()
+    driver = undefined
+  }
+  const suspend = () => cancel('cancelled')
+  const releaseItems = adapter.subscribe(refresh)
+  const releaseReduced = onReducedMotion((value) => driver?.setReducedMotion(value))
+  const result: Reorder<K> = {
+    get activeKey() {
+      return active?.key
+    },
+    get disposed() {
+      return disposed
+    },
+    move(key, beforeKey) {
+      if (disposed || paused) return false
+      const current = read(),
+        from = current.indexOf(key)
+      if (from < 0 || beforeKey === key) return false
+      const before = beforeKey === null ? current.length : current.indexOf(beforeKey)
+      return before < 0 ? false : moveTo(key, before > from ? before - 1 : before)
+    },
+    moveUp(key) {
+      if (disposed || paused) return false
+      return moveTo(key, read().indexOf(key) - 1)
+    },
+    moveDown(key) {
+      if (disposed || paused) return false
+      return moveTo(key, read().indexOf(key) + 1)
+    },
+    cancel: () => cancel('cancelled'),
+    refresh,
+    pause() {
+      paused = true
+      cancel('disabled')
+      driver?.setEnabled(false)
+    },
+    play() {
+      if (!disposed) {
+        paused = false
+        driver?.setEnabled(true)
+      }
+    },
+    dispose() {
+      if (disposed) return
+      cancel('disposed')
+      disposed = true
+      driver?.dispose()
+      driver = undefined
+      releaseItems()
+      releaseReduced()
+      view.off('loaded', attach)
+      view.off('unloaded', unload)
+      Application.off(Application.suspendEvent, suspend)
+      if (owners.get(view) === result) owners.delete(view)
+    },
+  }
+  owners.set(view, result)
+  view.on('loaded', attach)
+  view.on('unloaded', unload)
+  Application.on(Application.suspendEvent, suspend)
+  try {
+    attach()
+  } catch (error) {
+    result.dispose()
+    throw error
+  }
+  return result
+}