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

package/src/haptics.ts

@@ -1,45 +1,76 @@
-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'
 
-export type HapticStyle = 'light' | 'medium' | 'heavy'
+import type { HapticStyle, HapticOptions } from './core/haptic.js'
+export { resolveHaptic } from './core/haptic.js'
+export type { HapticStyle, HapticOptions, Haptic } from './core/haptic.js'
 
-export interface HapticOptions {
-  style: HapticStyle
-  /** Points from 0 to 1 over the finite animation, excluding its initial delay. Defaults to arrival. */
-  times?: readonly number[]
-}
-
-export type Haptic = HapticStyle | HapticOptions | false
+const PREPARE_AHEAD = 100
+const MAX_LATENESS = 100
 
-/** Validate before any running animation is interrupted. */
-export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undefined {
-  if (haptic === undefined || haptic === false) return undefined
-  const options = typeof haptic === 'string' ? { style: haptic } : haptic
-  if (!options || !['light', 'medium', 'heavy'].includes(options.style))
-    throw new TypeError('Haptic style must be light, medium or heavy.')
-  const times = options.times
-  if (
-    times !== undefined &&
-    (!Array.isArray(times) ||
-      times.length === 0 ||
-      Array.from(times).some(
-        (time, i) =>
-          !Number.isFinite(time) ||
-          time <= 0 ||
-          time > 1 ||
-          (i > 0 && time <= times[i - 1]!),
-      ))
-  )
-    throw new RangeError(
-      'Haptic times must be increasing points greater than 0 and at most 1.',
-    )
-  return { style: options.style, times: times && [...times] }
+interface Feedback {
+  active(): boolean
+  enabled(): boolean
+  prepare?(): void
+  fire(): void
 }
 
-const PREPARE_AHEAD = 100
-const MAX_LATENESS = 100
-const COMPLETION_TOLERANCE = 20
+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 +81,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 +93,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 +109,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 +185,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,53 @@
-export { animate, decay, stop } from './animate.js'
+export { timeline } from './sequence.js'
+export { seekableTimeline } from './seekable-timeline.js'
+export type { SeekableStep } from './seekable-timeline.js'
+export type { TimelineAnimation, TimelineStep, PlayableAnimation } from './sequence.js'
+export { playbackProgress } from './motion-value.js'
+export { animate, decay, set, stop, toView } 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 { ScrollHeaderSurface } from './scroll-header/surface.js'
+export type {
+  ScrollHeader,
+  ScrollHeaderOptions,
+  ScrollViewHeaderOptions,
+  ScrollHeaderItem,
+  ScrollHeaderRefreshContext,
+  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 +78,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 +120,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'