@rafaelaugusto/jolt 0.1.0-beta.13 → 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/index.ts

@@ -69,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

@@ -111,4 +111,11 @@ 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

@@ -41,7 +41,7 @@ export interface MotionScope {
   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>,
@@ -213,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) {

package/src/motion-value.ts

@@ -409,6 +409,12 @@ class Root extends Derived {
     return { property, keyframes: [], transition, track: mapped }
   }
 
+  /** Capture the current native presentation clock, even if a later command replaces it. */
+  captureTime(): () => number {
+    const run = this.presentation
+    return run ? () => this.runTime(run) : () => 0
+  }
+
   elapsed(): number {
     return this.presentation ? this.runTime(this.presentation) : 0
   }
@@ -595,6 +601,9 @@ class PlaybackValue extends Root {
   override get paused() {
     return this.playback.read().paused
   }
+  override captureTime() {
+    return () => this.playback.read().time
+  }
   override elapsed() {
     return this.playback.read().time
   }
@@ -642,6 +651,40 @@ class PlaybackValue extends Root {
   }
 }
 
+/** Internal compound-binding bridge. One raw snapshot per root keeps sibling mappings coherent. */
+export function valueSource(source: DerivedValue | DerivedColor, color: boolean) {
+  if (!(source instanceof Derived) || source.color !== color)
+    throw new TypeError(
+      `Gradient component needs a ${color ? 'color' : 'numeric'} Jolt value.`,
+    )
+  const { root, read } = source
+  return {
+    identity: root,
+    read,
+    snapshot() {
+      return {
+        track: root.plan({ property: 'opacity', read: (value) => value } as Binding)
+          .track!(),
+        elapsed: root.elapsed(),
+        time: root.captureTime(),
+        running: root.running,
+        value: root.raw(),
+      }
+    },
+    subscribe(listener: () => void) {
+      root.listeners.add(listener)
+      return () => {
+        root.listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** Treat values as opaque identities in declarative option comparisons. */
+export function isDerived(value: unknown): value is DerivedValue | DerivedColor {
+  return value instanceof Derived
+}
+
 /** Internal native-adapter bridge. Mappings are sampled at boundaries, never per frame. */
 export function valuePlayback(source: DerivedValue) {
   if (!(source instanceof Derived) || source.color)

package/src/native/index.ts

@@ -14,3 +14,10 @@ export type {
   MapLibreCamera,
   ScenePose,
 } from '../native-properties.js'
+export {
+  sceneKitLightIntensity,
+  sceneKitLightColor,
+  sceneKitMaterialTransparency,
+  sceneKitMaterialDiffuse,
+  sceneKitMaterialEmission,
+} from '../scene-appearance.js'

package/src/particles.ts

@@ -1,7 +1,8 @@
-import { Application, Color, isIOS, type View } from '@nativescript/core'
+import { Application, Color, isAndroid, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
-import { reducedMotion } from './config.js'
+import { onReducedMotion, reducedMotion } from './config.js'
+import { androidParticles } from './driver/android-particles.js'
 
 export interface ConfettiOptions {
   /** Approximate number of particles in the burst. Defaults to 80. */
@@ -38,7 +39,10 @@ export interface ParticleOptions {
   duration?: number
 }
 
-type Settings = Required<Omit<ParticleOptions, 'duration'>> & { duration?: number }
+export type ParticleSettings = Required<Omit<ParticleOptions, 'duration'>> & {
+  duration?: number
+}
+type Settings = ParticleSettings
 const bursts = new WeakMap<View, () => void>()
 const emitters = new WeakMap<View, () => void>()
 const palette = ['#facc15', '#ef4444', '#3b82f6', '#22c55e', '#a855f7']
@@ -46,7 +50,7 @@ const textures = new Map<Settings['shape'], UIImage>()
 const radians = (degrees: number) => (degrees * Math.PI) / 180
 const BURST_DURATION = 200
 
-/** Bursts from the target's center into its window. iOS only; returns immediate cleanup. */
+/** Bursts from the target's center into its window. Returns immediate cleanup. */
 export function confetti(target: Target, options: ConfettiOptions = {}): () => void {
   const count = number('count', options.count ?? 80, 0, 10000)
   if (!Number.isInteger(count)) throw new RangeError('Particle count must be an integer.')
@@ -70,7 +74,7 @@ export function confetti(target: Target, options: ConfettiOptions = {}): () => v
   return start(target, settings, true)
 }
 
-/** Adds a native particle emitter to the target. iOS only; returns immediate cleanup. */
+/** Adds a native particle emitter to the target. Returns immediate cleanup. */
 export function particles(target: Target, options: ParticleOptions = {}): () => void {
   return start(target, resolve(options), false)
 }
@@ -79,7 +83,9 @@ function start(target: Target, settings: Settings, overlay: boolean): () => void
   const view = toView(target)
   const running = overlay ? bursts : emitters
   running.get(view)?.()
-  if (!isIOS || settings.rate === 0 || reducedMotion()) return () => {}
+  if (settings.rate === 0 || reducedMotion()) return () => {}
+  if (isAndroid) return androidParticles(view, settings, overlay, running)
+  if (!isIOS) return () => {}
   return new Emitter(view, settings, overlay, running).stop
 }
 
@@ -141,7 +147,7 @@ class Emitter {
   private native: UIView | undefined
   private window: UIWindow | undefined
   private timer: ReturnType<typeof setTimeout> | undefined
-  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+  private unwatch: (() => void) | undefined
 
   constructor(
     private readonly view: View,
@@ -153,6 +159,8 @@ class Emitter {
     view.on('loaded', this.schedule)
     view.on('layoutChanged', this.schedule)
     view.on('unloaded', this.stop)
+    Application.on(Application.suspendEvent, this.stop)
+    this.unwatch = onReducedMotion(this.motionChanged)
     this.schedule()
   }
 
@@ -162,17 +170,14 @@ class Emitter {
     this.view.off('loaded', this.schedule)
     this.view.off('layoutChanged', this.schedule)
     this.view.off('unloaded', this.stop)
+    Application.off(Application.suspendEvent, this.stop)
     if (this.running.get(this.view) === this.stop) this.running.delete(this.view)
     if (this.timer !== undefined) clearTimeout(this.timer)
-    if (this.observer)
-      Application.ios.removeNotificationObserver(
-        this.observer,
-        UIAccessibilityReduceMotionStatusDidChangeNotification,
-      )
+    this.unwatch?.()
     this.layer?.removeAllAnimations()
     this.layer?.removeFromSuperlayer()
     this.layer = this.native = this.window = undefined
-    this.timer = this.observer = undefined
+    this.timer = this.unwatch = undefined
   }
 
   private schedule = () => {
@@ -232,10 +237,6 @@ class Emitter {
             ),
             window,
           )
-        this.observer = Application.ios.addNotificationObserver(
-          UIAccessibilityReduceMotionStatusDidChangeNotification,
-          this.motionChanged,
-        )
         if (this.settings.duration !== undefined) {
           // The render server stops emission even if JS is blocked. The timer
           // only removes the empty layer after the last particles have expired.

package/src/scene-appearance.ts

@@ -0,0 +1,92 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import { Color } from '@nativescript/core'
+import { colorMixer, parseColor, type ColorValue } from './color.js'
+import { registerNativeProperty, type NativeProperty } from './native-property.js'
+
+const clamp = (n: number) => Math.max(0, Math.min(1, n))
+function scalar(name: string, maximum: number, create: (target: object) => object) {
+  return registerNativeProperty<number>({
+    name: `jolt.scenekit/${name}`,
+    units: [
+      name === 'light-intensity'
+        ? 'lumens (PBR); 1000 = unit multiplier otherwise'
+        : 'opacity fraction',
+    ],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0 || value > maximum)
+        throw new RangeError(`${name} needs a finite value in 0..${maximum}.`)
+    },
+    interpolate: (a, b, t) => Math.max(0, Math.min(maximum, a + (b - a) * t)),
+    create,
+  })
+}
+function color(name: string, create: (target: object) => object) {
+  return registerNativeProperty<ColorValue>({
+    name: `jolt.scenekit/${name}`,
+    // Premultiply the sampled sRGB channels, so native linear interpolation also handles zero alpha.
+    units: [
+      'premultiplied sRGB red',
+      'premultiplied sRGB green',
+      'premultiplied sRGB blue',
+      'alpha',
+    ],
+    platforms: ['ios'],
+    encode(value) {
+      const argb = parseColor(value),
+        alpha = (argb >>> 24) / 255
+      return [
+        (((argb >>> 16) & 255) / 255) * alpha,
+        (((argb >>> 8) & 255) / 255) * alpha,
+        ((argb & 255) / 255) * alpha,
+        alpha,
+      ]
+    },
+    decode(values) {
+      const alpha = clamp(values[3]!)
+      const channel = (i: number) =>
+        Math.round(clamp(alpha ? values[i]! / alpha : 0) * 255)
+      return new Color(
+        ((Math.round(alpha * 255) << 24) |
+          (channel(0) << 16) |
+          (channel(1) << 8) |
+          channel(2)) >>>
+          0,
+      )
+    },
+    interpolate: (a, b, t) => new Color(colorMixer(parseColor(a), parseColor(b))(t)),
+    create,
+  })
+}
+
+/** SCNLight intensity, finite and nonnegative. Non-spatial: retains timing under reduced motion. */
+export const sceneKitLightIntensity: (light: SCNLight) => NativeProperty<number> = scalar(
+  'light-intensity',
+  Infinity,
+  (target) => JoltReferenceProperties.sceneLightIntensity(target as NSObject),
+)
+/** Solid UIColor/CGColor light color. Returns a normalized sRGB Color from get(). */
+export const sceneKitLightColor: (light: SCNLight) => NativeProperty<ColorValue> = color(
+  'light-color',
+  (target) => JoltReferenceProperties.sceneLightColor(target as NSObject),
+)
+/** SCNMaterial transparency in 0..1; does not change transparencyMode/transparent contents. */
+export const sceneKitMaterialTransparency: (
+  material: SCNMaterial,
+) => NativeProperty<number> = scalar('material-transparency', 1, (target) =>
+  JoltReferenceProperties.sceneMaterialTransparency(target as NSObject),
+)
+/** Solid color diffuse contents only; never converts a texture into a color. */
+export const sceneKitMaterialDiffuse: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-diffuse', (target) =>
+  JoltReferenceProperties.sceneMaterialDiffuse(target as NSObject),
+)
+/** Solid color emission contents only; does not make the material illuminate nearby geometry. */
+export const sceneKitMaterialEmission: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-emission', (target) =>
+  JoltReferenceProperties.sceneMaterialEmission(target as NSObject),
+)

package/src/types.ts

@@ -84,7 +84,7 @@ export type AnimateOptions = Transition & {
   relative?: boolean
   /** With several targets, delays each one by this much more than the previous. */
   stagger?: number | Stagger
-  /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
+  /** Native haptic feedback at arrival, or at explicit points in a finite animation. */
   haptic?: Haptic
   /**
    * Plays on a named layer, on top of the property's other animations instead of replacing

package/src/vue/index.ts

@@ -40,6 +40,8 @@ import {
   type GradientOptions,
   type Transition,
 } from '../index.js'
+import { isDerived } from '../motion-value.js'
+import { prepareGradient, type GradientValues } from '../gradient.js'
 import { currentKeyboard } from '../keyboard.js'
 
 type Host = NSVElement
@@ -70,7 +72,10 @@ export interface TransitionProps {
 const animations = new WeakMap<object, PlaybackAnimation>()
 const scopes = new WeakMap<object, MotionScope>()
 const removers = new WeakMap<object, () => void>()
-const gradients = new WeakMap<object, { gradient: Gradient; colors: number }>()
+const gradients = new WeakMap<
+  object,
+  { gradient: Gradient; colors: number; release?: () => void }
+>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -82,6 +87,7 @@ function split<T>(
 
 function same(a: unknown, b: unknown): boolean {
   if (Object.is(a, b)) return true
+  if (isDerived(a) || isDerived(b)) return false
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
     return false
   if (Array.isArray(a) !== Array.isArray(b)) return false
@@ -161,17 +167,35 @@ function paint(el: Host, value: GradientValue, animated: boolean) {
     (Transition | SpringName)?,
   ]
   const current = gradients.get(el)
+  prepareGradient(options)
   const colors = options.colors.length
+  const hasBindings = [
+    options.angle,
+    options.radius,
+    options.center?.x,
+    options.center?.y,
+    ...options.colors,
+    ...(options.stops ?? []),
+  ].some(isDerived)
   if (current && current.gradient.type === options.type) {
     const { type, ...values } = options
-    if (animated && current.colors === colors)
-      current.gradient.animate(values, transition)
-    else current.gradient.set(values)
+    const previous = current.release
+    if (hasBindings) current.release = current.gradient.bind(values)
+    else {
+      if (animated && current.colors === colors)
+        current.gradient.animate(values as GradientValues, transition)
+      else current.gradient.set(values as GradientValues)
+      current.release = undefined
+    }
+    previous?.()
     current.colors = colors
     return
   }
   current?.gradient.remove()
-  gradients.set(el, { gradient: gradient(el, options), colors })
+  // Track directive ownership explicitly, including bindings omitted on a later update.
+  const made = gradient(el, options)
+  const release = hasBindings ? made.bind(options) : undefined
+  gradients.set(el, { gradient: made, colors, release })
 }
 
 /**