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

package/src/gravity.ts

@@ -0,0 +1,107 @@
+export interface GravityMotion {
+  duration: number
+  /** Exact impact and turning-point times, in milliseconds. */
+  breakpoints: number[]
+  position(time: number): number
+  velocity(time: number): number
+  interpolationError(start: number, end: number): number
+}
+
+export const DEFAULT_ACCELERATION = 1800
+export const DEFAULT_RESTITUTION = 0.55
+const MAX_FLIGHTS = 512
+const MAX_DURATION = 60_000
+
+/** Ballistic flights against one fixed boundary; no numerical integration or frame loop. */
+export function solveGravity(
+  from: number,
+  to: number,
+  acceleration: number,
+  restitution: number,
+  velocity: number,
+  precision: number,
+): GravityMotion {
+  if (
+    ![from, to, acceleration, restitution, velocity, precision].every(Number.isFinite) ||
+    acceleration <= 0 ||
+    restitution < 0 ||
+    restitution >= 1 ||
+    precision <= 0
+  )
+    throw new RangeError(
+      'Invalid gravity position, acceleration, restitution or velocity.',
+    )
+
+  const direction = to < from ? -1 : 1
+  const distance = Math.abs(to - from)
+  let speed = velocity * direction
+  const impact = Math.hypot(speed, Math.sqrt(2 * acceleration * distance))
+  if (!Number.isFinite(impact))
+    throw new RangeError('Gravity motion exceeds the finite numeric range.')
+  // This form avoids cancellation when moving quickly toward a nearby boundary.
+  let seconds =
+    speed >= 0
+      ? distance === 0
+        ? 0
+        : (2 * distance) / (impact + speed)
+      : (impact - speed) / acceleration
+  let duration = 0
+  const flights: { start: number; end: number; origin: number; speed: number }[] = []
+  const breakpoints: number[] = []
+  const addFlight = (origin: number, initial: number, length: number) => {
+    const end = duration + length * 1000
+    if (!Number.isFinite(end) || end > MAX_DURATION || flights.length >= MAX_FLIGHTS)
+      throw new RangeError(
+        'Gravity motion must settle within 60 seconds and 512 flights.',
+      )
+    if (length > 0) {
+      const apex = duration - (initial / acceleration) * 1000
+      if (apex > duration && apex < end) breakpoints.push(apex)
+      flights.push({ start: duration, end, origin, speed: initial })
+      breakpoints.push(end)
+      duration = end
+    }
+  }
+  addFlight(-distance, speed, seconds)
+  speed = impact * restitution
+  while (speed > precision * 10 || (speed * speed) / (2 * acceleration) > precision) {
+    seconds = (2 * speed) / acceleration
+    addFlight(0, -speed, seconds)
+    speed *= restitution
+  }
+  const flightAt = (time: number) => {
+    let lo = 0,
+      hi = flights.length - 1
+    while (lo < hi) {
+      const mid = (lo + hi) >>> 1
+      if (time >= flights[mid]!.end) lo = mid + 1
+      else hi = mid
+    }
+    return flights[lo]!
+  }
+  return {
+    duration,
+    breakpoints,
+    position(time) {
+      if (time >= duration) return to
+      if (time <= 0) return from
+      const flight = flightAt(time)
+      const t = (time - flight.start) / 1000
+      return (
+        to +
+        direction *
+          Math.min(0, flight.origin + flight.speed * t + (acceleration * t * t) / 2)
+      )
+    },
+    velocity(time) {
+      if (duration === 0 || time >= duration) return 0
+      const flight = flightAt(Math.max(0, time))
+      return (
+        direction *
+        (flight.speed + (acceleration * (Math.max(0, time) - flight.start)) / 1000)
+      )
+    },
+    // Valid between mandatory impact seams. Each flight is an exact quadratic.
+    interpolationError: (start, end) => (acceleration * ((end - start) / 1000) ** 2) / 8,
+  }
+}

package/src/haptics.ts

@@ -1,4 +1,4 @@
-import { isIOS, type View } from '@nativescript/core'
+import { isAndroid, isIOS, type View } from '@nativescript/core'
 import type { Driver } from './driver/index.js'
 import type { Track } from './track.js'
 
@@ -39,7 +39,69 @@ export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undef
 
 const PREPARE_AHEAD = 100
 const MAX_LATENESS = 100
-const COMPLETION_TOLERANCE = 20
+
+interface Feedback {
+  active(): boolean
+  enabled(): boolean
+  prepare?(): void
+  fire(): void
+}
+
+function feedbackFor(
+  view: View,
+  style: HapticStyle,
+  driver: Driver,
+): Feedback | undefined {
+  if (isAndroid) {
+    if (typeof android === 'undefined' || driver.reducedMotion?.()) return
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (!native) return
+    const sdk = android.os.Build.VERSION.SDK_INT
+    const constants = android.view.HapticFeedbackConstants
+    const effect =
+      style === 'heavy'
+        ? constants.LONG_PRESS
+        : style === 'medium' && sdk >= 23
+          ? constants.CONTEXT_CLICK
+          : style === 'light' && sdk >= 21
+            ? constants.CLOCK_TICK
+            : constants.KEYBOARD_TAP
+    return {
+      // Animator scale zero must also silence opacity/color feedback when
+      // configure({ reducedMotion: 'never' }) keeps a logical track alive.
+      enabled: () => !driver.reducedMotion?.(),
+      active: () =>
+        view.isLoaded &&
+        view.nativeViewProtected === native &&
+        !!native.getWindowToken() &&
+        native.getWindowVisibility() === 0 &&
+        native.isShown() &&
+        native.hasWindowFocus(),
+      // No ignore-setting flags, forced vibration or permission. A false result
+      // means the system declined this request; do not retry with a stronger effect.
+      fire: () => {
+        native.performHapticFeedback(effect)
+      },
+    }
+  }
+  if (!isIOS || typeof UIImpactFeedbackGenerator === 'undefined') return
+  const styles = { light: 0, medium: 1, heavy: 2 } satisfies Record<
+    HapticStyle,
+    UIImpactFeedbackStyle
+  >
+  const generator = UIImpactFeedbackGenerator.alloc().initWithStyle(styles[style])
+  const native = view.nativeViewProtected as UIView
+  return {
+    enabled: () => true,
+    active: () =>
+      view.isLoaded &&
+      view.nativeViewProtected === native &&
+      !!native.window &&
+      UIApplication.sharedApplication.applicationState === 0,
+    prepare: () => generator.prepare(),
+    fire: () => generator.impactOccurred(),
+  }
+}
 
 /** Discrete feedback only: animation playback remains entirely native. */
 export function playHaptics(
@@ -50,7 +112,7 @@ export function playHaptics(
   startedAt: number,
   elapsedTime = () => driver.now() - startedAt,
 ) {
-  if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
+  if (!options) return
   const moving = tracks.filter(
     (track) =>
       track.duration > 0 && track.values.some((value) => value !== track.values[0]),
@@ -62,25 +124,13 @@ export function playHaptics(
   const offsets = options.times
     ? options.times.map((time) => delay + (end - delay) * time)
     : [Math.max(...tracks.map((track) => track.arrival))]
-  const styles = {
-    light: 0,
-    medium: 1,
-    heavy: 2,
-  } satisfies Record<HapticStyle, UIImpactFeedbackStyle>
-  let generator: UIImpactFeedbackGenerator | undefined =
-    UIImpactFeedbackGenerator.alloc().initWithStyle(styles[options.style])
-  const native = view.nativeViewProtected as UIView
+  let feedback = feedbackFor(view, options.style, driver)
+  if (!feedback) return
   let paused = false
   let next = 0
   let cancelPrepare: (() => void) | undefined
   let cancelImpact: (() => void) | undefined
 
-  const active = () =>
-    view.isLoaded &&
-    view.nativeViewProtected === native &&
-    !!native.window &&
-    UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
-
   const cancelTimers = () => {
     cancelPrepare?.()
     cancelImpact?.()
@@ -90,28 +140,54 @@ export function playHaptics(
     cancelPrepare?.()
     cancelImpact?.()
     cancelPrepare = cancelImpact = undefined
-    generator = undefined
+    feedback = undefined
     view.off('unloaded', cancel)
   }
 
-  const fire = (tolerance = 0) => {
-    const elapsed = elapsedTime()
+  const fire = (elapsed = elapsedTime()) => {
     // A busy UI thread can delay timers. Drop stale impacts instead of replaying
     // several old taps at once when it becomes responsive again.
-    while (next < offsets.length && offsets[next]! <= elapsed + tolerance) {
+    while (next < offsets.length && offsets[next]! <= elapsed) {
       const offset = offsets[next++]!
-      if (active() && elapsed - offset <= MAX_LATENESS) generator?.impactOccurred()
+      if (feedback?.enabled() && feedback.active() && elapsed - offset <= MAX_LATENESS)
+        feedback.fire()
     }
   }
 
   const schedule = () => {
     if (paused) return
-    if (!generator || next === offsets.length) return cancel()
+    if (!feedback?.enabled() || next === offsets.length) return cancel()
+    if (isAndroid) {
+      // Start pending markers together with the visual animators. Chaining a
+      // new ValueAnimator from each impact adds another first-frame startup
+      // delay, which can wrongly make subsequent points stale at fast scales.
+      const markers = new Set<() => void>()
+      cancelImpact = () => {
+        for (const release of markers) release()
+        markers.clear()
+      }
+      const arm = (index: number) => {
+        if (!feedback?.enabled()) return cancel()
+        // Native durations are integer milliseconds; zero completes synchronously.
+        const remaining = Math.max(1, offsets[index]! - elapsedTime())
+        const release = driver.after(remaining, () => {
+          markers.delete(release)
+          if (!feedback || paused) return
+          if (!feedback.enabled()) return cancel()
+          fire()
+          if (next === offsets.length) cancel()
+          else if (next <= index) arm(index)
+        })
+        markers.add(release)
+      }
+      for (let index = next; index < offsets.length; index++) arm(index)
+      return
+    }
     const remaining = offsets[next]! - elapsedTime()
-    if (active()) generator.prepare()
-    if (remaining > PREPARE_AHEAD) {
+    if (feedback.active()) feedback.prepare?.()
+    if (feedback.prepare && remaining > PREPARE_AHEAD) {
       cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
-        if (active()) generator?.prepare()
+        if (feedback?.active()) feedback.prepare?.()
       })
     }
     cancelImpact = driver.after(Math.max(0, remaining), () => {
@@ -140,8 +216,10 @@ export function playHaptics(
       schedule()
     },
     finish() {
-      // Native completion may beat the timer at the final keyframe by a frame.
-      fire(COMPLETION_TOLERANCE)
+      // Native completion proves that the final frame was reached, even when
+      // a scaled/resumed clock sample is one frame behind. Earlier impacts are
+      // still judged against the end position, so stale points are not replayed.
+      fire(Math.max(end, elapsedTime()))
       cancel()
     },
   }

package/src/image-effect.ts

@@ -43,6 +43,7 @@ export interface ImageEffectDiagnostics {
 export interface ImageEffect extends Animation {
   readonly effect: ImageEffectName
   readonly paused: boolean
+  readonly duration: number
   /** Finite progress; distortion rejects seeking because it follows native touch input. */
   progress: number
   readonly diagnostics: Readonly<ImageEffectDiagnostics>
@@ -157,7 +158,7 @@ class Effect implements ImageEffect {
     for (const event of ['loaded', 'layoutChanged']) image.on(event, this.schedule)
     for (const event of ['imageSourceChange', 'stretchChange'])
       image.on(event, this.changed)
-    image.on('unloaded', this.stop)
+    image.on('unloaded', this.unloaded)
     image.style.on('visibilityChange', this.visible)
     for (const event of surfaceChanges) image.style.on(event, this.changed)
     Application.on(Application.suspendEvent, this.suspend)
@@ -178,6 +179,9 @@ class Effect implements ImageEffect {
   get paused() {
     return this.userPaused
   }
+  get duration() {
+    return this.effect === 'distortion' ? Infinity : this.options.duration
+  }
   get progress() {
     return this.renderer?.progress ?? this.position
   }
@@ -240,7 +244,7 @@ class Effect implements ImageEffect {
     for (const event of ['loaded', 'layoutChanged']) this.image.off(event, this.schedule)
     for (const event of ['imageSourceChange', 'stretchChange'])
       this.image.off(event, this.changed)
-    this.image.off('unloaded', this.stop)
+    this.image.off('unloaded', this.unloaded)
     this.image.style.off('visibilityChange', this.visible)
     for (const event of surfaceChanges) this.image.style.off(event, this.changed)
     Application.off(Application.suspendEvent, this.suspend)
@@ -272,6 +276,10 @@ class Effect implements ImageEffect {
     this.suspended = true
     this.renderer?.pause()
   }
+  private unloaded = () => {
+    if (Application.suspended && this.userPaused) return
+    this.stop()
+  }
   private resume = () => {
     this.suspended = false
     this.schedule()

package/src/index.ts

@@ -1,17 +1,47 @@
-export { animate, decay, stop } from './animate.js'
+export { timeline } from './sequence.js'
+export type { TimelineAnimation, TimelineStep, PlayableAnimation } from './sequence.js'
+export { playbackProgress } from './motion-value.js'
+export { animate, decay, set, stop } from './animate.js'
+export { bind, motionValue, scrollValue, springValue } from './motion-value.js'
+export type {
+  Bindings,
+  DerivedColor,
+  DerivedValue,
+  MapOptions,
+  MotionValue,
+  ScrollValue,
+  SpringValue,
+  SpringValueOptions,
+  ValueAnimationOptions,
+} from './motion-value.js'
+export type { SubscribeOptions, ValueListener } from './value-observers.js'
 export { sequence } from './sequence.js'
 export type { Step, SequenceOptions, SequencePosition } from './sequence.js'
 export { press } from './press.js'
 export { interactionSurface } from './interaction-surface.js'
 export type { InteractionSurface } from './interaction-surface.js'
 export { drag } from './drag.js'
-export type { Drag, DragOptions, DragPoint, DragEvent, DragRelease } from './drag.js'
+export type {
+  Drag,
+  DragOptions,
+  DragValueOptions,
+  DragPoint,
+  DragEvent,
+  DragRelease,
+} from './drag.js'
 export { scrollLinked } from './scroll-linked.js'
 export type { ScrollLinkedOptions } from './scroll-linked.js'
+export { scrollHeader } from './scroll-header/index.js'
+export type {
+  ScrollHeader,
+  ScrollHeaderOptions,
+  ScrollHeaderGeometry,
+  ScrollHeaderSnapshot,
+} from './scroll-header/index.js'
 export { animateItems } from './items.js'
 export type { ItemsOptions } from './items.js'
-export { followKeyboard } from './keyboard.js'
-export type { KeyboardOptions } from './keyboard.js'
+export { followKeyboard, onKeyboard } from './keyboard.js'
+export type { KeyboardOptions, KeyboardState } from './keyboard.js'
 export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
 export { confetti, particles } from './particles.js'
 export type { ConfettiOptions, ParticleOptions } from './particles.js'
@@ -42,12 +72,29 @@ export type {
   SymbolEffectName,
   SymbolEffectOptions,
 } from './symbol-effect.js'
-export { configure } from './config.js'
+export { gradient } from './gradient.js'
+export type {
+  Gradient,
+  GradientOptions,
+  GradientType,
+  GradientValues,
+  GradientBindings,
+} from './gradient.js'
+export { configure, onReducedMotion, reducedMotion } from './config.js'
 export type { JoltConfig } from './config.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
-export { springs } from './transition.js'
-export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
+export { origamiSpring, springs } from './transition.js'
+export type {
+  OrigamiSpring,
+  Gravity,
+  RepeatDelayRange,
+  Spring,
+  SpringName,
+  Timing,
+  Transition,
+  Tween,
+} from './transition.js'
 export { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
 export type { PlaybackAnimation } from './playback.js'
@@ -67,3 +114,5 @@ export type {
 
 export { animateLayout } from './layout.js'
 export type { LayoutOptions } from './layout.js'
+export { animateSize } from './size.js'
+export type { SizeAnimation, SizeDimensions, SizeOptions } from './size.js'