@rafaelaugusto/jolt 0.1.0-beta.12 → 0.1.0-beta.14

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,3 +1,6 @@
+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 } from './motion-value.js'
 export type {
@@ -7,7 +10,9 @@ export type {
   MapOptions,
   MotionValue,
   ScrollValue,
+  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'
@@ -64,6 +69,7 @@ export type {
   GradientOptions,
   GradientType,
   GradientValues,
+  GradientBindings,
 } from './gradient.js'
 export { configure, onReducedMotion, reducedMotion } from './config.js'
 export type { JoltConfig } from './config.js'

package/src/ios-plugin.d.ts

@@ -79,3 +79,43 @@ declare class JoltPhotoZoom extends NSObject {
   layout(): void
   stop(): void
 }
+
+declare class JoltPropertySink extends NSObject {
+  static scalarTargetKeyPath(target: NSObject, keyPath: string): JoltPropertySink
+  readonly dimensions: number
+  readonly alive: boolean
+  readonly compiled: boolean
+  read(): NSArray<number>
+  write(values: NSArray<number>): void
+  dispose(): void
+}
+declare class JoltPropertyPlayer extends NSObject {
+  static startSinkTimesValuesFinalValueDurationDelayRepeatReverseCompletion(
+    sink: JoltPropertySink,
+    times: NSArray<number>,
+    values: NSArray<number>,
+    finalValue: NSArray<number>,
+    duration: number,
+    delay: number,
+    repeat: number,
+    reverse: boolean,
+    completion: (completed: boolean) => void,
+  ): JoltPropertyPlayer
+  readonly elapsed: number
+  readonly frames: number
+  static activeCount(): number
+  controlPaused(time: number, paused: boolean): void
+  cancel(): void
+}
+declare class JoltReferenceProperties extends NSObject {
+  static mapCoordinate(target: NSObject): JoltPropertySink
+  static mapCamera(target: NSObject): JoltPropertySink
+  static scenePose(target: NSObject): JoltPropertySink
+  static sceneLightIntensity(target: NSObject): JoltPropertySink
+  static sceneLightColor(target: NSObject): JoltPropertySink
+  static sceneMaterialTransparency(target: NSObject): JoltPropertySink
+  static sceneMaterialDiffuse(target: NSObject): JoltPropertySink
+  static sceneMaterialEmission(target: NSObject): JoltPropertySink
+  static sceneAppearanceSinkCount(): number
+  static sceneAppearanceWriteCount(): number
+}

package/src/motion-scope.ts

@@ -4,7 +4,7 @@ import { drag } from './drag.js'
 import { gradient } from './gradient.js'
 import { animateLayout, type LayoutOptions } from './layout.js'
 import type { SpringName } from './transition.js'
-import { sequence } from './sequence.js'
+import { sequence, timeline } from './sequence.js'
 import {
   motionStates,
   type MotionState,
@@ -38,9 +38,10 @@ export interface MotionScope {
   animate: typeof animate
   decay: typeof decay
   sequence: typeof sequence
+  timeline: typeof timeline
   press: typeof press
   drag: typeof drag
-  /** Removed with the scope; suspending it stops a gradient animation where it is. */
+  /** Removed with the scope; suspension holds bindings until resume and stops concrete playback. */
   gradient: typeof gradient
   states<
     T extends Record<string, Target | null>,
@@ -197,6 +198,9 @@ export function motionScope(): MotionScope {
     decay(...args) {
       return startOwned(() => decay(...args))
     },
+    timeline(...args) {
+      return startOwned(() => timeline(...args))
+    },
     sequence(...args) {
       return startOwned(() => sequence(...args))
     },
@@ -209,7 +213,14 @@ export function motionScope(): MotionScope {
     gradient(target, options) {
       assertActive()
       const made = gradient(target, options)
-      scope.add({ pause: () => made.stop(), play() {}, dispose: () => made.remove() })
+      scope.add({
+        get paused() {
+          return made.suspended
+        },
+        pause: () => made.suspend(),
+        play: () => made.resume(),
+        dispose: () => made.remove(),
+      })
       return made
     },
     states(targets, definitions, options) {