@rafaelaugusto/jolt 0.1.0-beta.5 → 0.1.0-beta.7

package/src/index.ts

@@ -1,7 +1,13 @@
 export { animate, decay, stop } from './animate.js'
 export { sequence } from './sequence.js'
-export type { Step } from './sequence.js'
+export type { Step, SequenceOptions, SequencePosition } from './sequence.js'
 export { press } from './press.js'
+export { scrollLinked } from './scroll-linked.js'
+export type { ScrollLinkedOptions } from './scroll-linked.js'
+export { animateItems } from './items.js'
+export type { ItemsOptions } from './items.js'
+export { followKeyboard } from './keyboard.js'
+export type { KeyboardOptions } from './keyboard.js'
 export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
 export { confetti, particles } from './particles.js'
 export type { ConfettiOptions, ParticleOptions } from './particles.js'
@@ -9,18 +15,31 @@ export { shimmer } from './shimmer.js'
 export type { ShimmerOptions } from './shimmer.js'
 export { liquid } from './liquid.js'
 export type { LiquidOptions, LiquidEffect } from './liquid.js'
+export { imageEffect } from './image-effect.js'
+export type {
+  ImageEffect,
+  ImageEffectName,
+  ImageEffectOptions,
+  ImageEffectDiagnostics,
+} from './image-effect.js'
+export { zoomable } from './zoomable.js'
+export type { Zoomable, ZoomableOptions, ZoomState, PhotoDismissal } from './zoomable.js'
 export { loader } from './loader.js'
 export type { LoaderOptions, LoaderStyle } from './loader.js'
 export { reveal, conceal } from './reveal.js'
 export type { RevealOptions, ConcealOptions } from './reveal.js'
 export { animateText } from './text.js'
 export type { TextOptions } from './text.js'
+export { rollTo } from './roll.js'
+export type { RollOptions } from './roll.js'
 export { symbolEffect } from './symbol-effect.js'
 export type {
   SymbolEffect,
   SymbolEffectName,
   SymbolEffectOptions,
 } from './symbol-effect.js'
+export { configure } 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'

package/src/ios-plugin.d.ts

@@ -0,0 +1,59 @@
+declare class JoltImageEffect extends NSObject {
+  stopPreservingImage(): void
+  static createWithViewDestinationModeOriginXOriginYAmplitudeRadiusDurationSeedListener(
+    image: UIImageView,
+    destination: UIImage | null,
+    mode: number,
+    x: number,
+    y: number,
+    amplitude: number,
+    radius: number,
+    duration: number,
+    seed: number,
+    listener: (completed: boolean, progress: number) => void,
+  ): JoltImageEffect | null
+  readonly progress: number
+  readonly paused: boolean
+  readonly frames: number
+  readonly longestFrame: number
+  readonly textureBytes: number
+  play(endpoint: number): void
+  pause(): void
+  resume(): void
+  seek(progress: number): void
+  finish(endpoint: number): void
+  stop(): void
+}
+declare class JoltPhotoZoom extends NSObject {
+  static attachImageViewportMinimumMaximumDoubleTapDismissReducedBackdropChromeOnDismissOnSettled(
+    image: UIImageView,
+    viewport: UIView,
+    minimum: number,
+    maximum: number,
+    doubleTap: number,
+    dismiss: boolean,
+    reduced: boolean,
+    backdrop: UIView | null,
+    chrome: UIView | null,
+    onDismiss: (
+      x: number,
+      y: number,
+      scale: number,
+      velocity: number,
+      progress: number,
+    ) => void,
+    onSettled: (x: number, y: number, scale: number) => void,
+  ): JoltPhotoZoom
+  readonly x: number
+  readonly y: number
+  readonly scale: number
+  readonly dismissProgress: number
+  readonly dismissPending: boolean
+  zoomFocusXFocusYAnimated(scale: number, x: number, y: number, animated: boolean): void
+  reset(animated: boolean): void
+  requestDismiss(): void
+  setReduced(value: boolean): void
+  setActive(value: boolean): void
+  layout(): void
+  stop(): void
+}

package/src/items.ts

@@ -0,0 +1,140 @@
+import { ListView, View, type EventData, type ItemEventData } from '@nativescript/core'
+import { animate, endingValues, startingValues, toView } from './animate.js'
+import { getDriver } from './driver/index.js'
+import { stopView } from './engine.js'
+import type { PresetName } from './presets.js'
+import { writeValue } from './properties.js'
+import type { SpringName } from './transition.js'
+import type { AnimateOptions, Keyframes, Target } from './types.js'
+
+export type ItemsOptions = AnimateOptions & {
+  /** Animate each data item only the first time it shows up. Defaults to false. */
+  once?: boolean
+}
+
+interface Pending {
+  index: number
+  section: number | undefined
+  item: unknown
+  key: string
+}
+
+type Row = View & {
+  bindingContext?: unknown
+  _listViewItemIndex?: number
+  _listViewSectionIndex?: number
+}
+
+interface Source extends View {
+  items?: unknown
+  _getDataItem?(index: number): unknown
+  _getDataItemInSection?(section: number, index: number): unknown
+}
+
+/**
+ * Plays an animation on each row of a list as it comes on screen. Rows are
+ * recycled, so a row that is reused for another item starts over, or settles
+ * at the end values when that item was already shown and `once` is set.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * animateItems(listView, 'fadeInUp')
+ * animateItems(listView, 'fadeInUp', { once: true })
+ * ```
+ */
+export function animateItems(
+  list: Target,
+  animation: Keyframes | PresetName,
+  options?: ItemsOptions | SpringName,
+): () => void {
+  const source = toView(list) as Source
+  const { once = false, ...rest } = typeof options === 'object' ? options : {}
+  if (rest.stagger !== undefined)
+    throw new TypeError('animateItems animates one row at a time; stagger has no effect.')
+  const transition: AnimateOptions | SpringName | undefined =
+    typeof options === 'string' ? options : rest
+  const properties = [...startingValues(animation, transition).keys()]
+  const ends = endingValues(animation, transition)
+
+  const rows = new Set<Row>()
+  const seenItems = new WeakSet<object>()
+  const seenKeys = new Set<string>()
+  const pending: Pending[] = []
+  let queued = false
+  let disposed = false
+
+  const settle = (row: Row) => {
+    stopView(row, properties)
+    for (const [property, value] of ends)
+      if (value !== null) writeValue(row, property, value)
+    getDriver().sync?.(row)
+  }
+  const show = (row: Row, { item, key }: Pending) => {
+    rows.add(row)
+    const tracked = typeof item === 'object' && item !== null
+    const seen = tracked ? seenItems.has(item) : seenKeys.has(key)
+    if (tracked) seenItems.add(item)
+    else seenKeys.add(key)
+    if (once && seen) settle(row)
+    else {
+      stopView(row, properties)
+      animate(row, animation, transition)
+    }
+  }
+  const flush = () => {
+    queued = false
+    if (disposed) return
+    const current = new Set<Row>()
+    const fresh: Row[] = []
+    source.eachChildView((child: Row) => {
+      current.add(child)
+      if (!rows.has(child)) fresh.push(child)
+      return true
+    })
+    for (const row of rows) if (!current.has(row)) rows.delete(row)
+    for (const entry of pending.splice(0)) {
+      const row =
+        fresh.find(
+          (candidate) =>
+            candidate._listViewItemIndex === entry.index &&
+            candidate._listViewSectionIndex === entry.section,
+        ) ??
+        fresh.find(
+          (candidate) =>
+            entry.item !== undefined && candidate.bindingContext === entry.item,
+        )
+      if (!row) continue
+      fresh.splice(fresh.indexOf(row), 1)
+      show(row, entry)
+    }
+  }
+  const onItemLoading = (event: EventData) => {
+    const { index, section, view } = event as ItemEventData
+    const item =
+      section === undefined
+        ? source._getDataItem?.(index)
+        : source._getDataItemInSection?.(section, index)
+    const entry: Pending = { index, section, item, key: `${section ?? ''}:${index}` }
+    if (view instanceof View) {
+      show(view, entry)
+      return
+    }
+    pending.push(entry)
+    if (queued) return
+    queued = true
+    void Promise.resolve().then(flush)
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    source.off(ListView.itemLoadingEvent, onItemLoading)
+    source.off('unloaded', cleanup)
+    pending.length = 0
+    for (const row of rows) settle(row)
+    rows.clear()
+  }
+
+  source.on(ListView.itemLoadingEvent, onItemLoading)
+  source.on('unloaded', cleanup)
+  return cleanup
+}

package/src/keyboard.ts

@@ -0,0 +1,132 @@
+import { Application, Utils, isAndroid, isIOS, type View } from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import type { Target } from './types.js'
+
+export interface KeyboardOptions {
+  /** DIPs kept between the view's bottom edge and the keyboard. Defaults to zero. */
+  offset?: number
+}
+
+const BEGIN_FROM_CURRENT_STATE = 4
+
+/**
+ * Lifts the view by its overlap with the software keyboard, at the keyboard's
+ * own speed and curve, and lets it back down when the keyboard hides.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * const release = followKeyboard(composer)
+ * followKeyboard(sendButton, { offset: 12 })
+ * ```
+ */
+export function followKeyboard(
+  target: Target,
+  options: KeyboardOptions = {},
+): () => void {
+  const view = toView(target)
+  const offset = options.offset ?? 0
+  if (!Number.isFinite(offset)) throw new RangeError('Keyboard offset must be finite.')
+  if (isIOS) return followIOS(view, offset)
+  if (isAndroid) return followAndroid(view, offset)
+  return () => {}
+}
+
+function followIOS(view: View, offset: number) {
+  let disposed = false
+  let current = 0
+  const onKeyboard = (notification: NSNotification) => {
+    if (disposed || !view.isLoaded) return
+    const native = view.nativeViewProtected as UIView | undefined
+    const window = native?.window
+    const info = notification.userInfo
+    if (!native || !window || !info) return
+    const end = info.objectForKey(UIKeyboardFrameEndUserInfoKey)?.CGRectValue as
+      CGRect | undefined
+    if (!end) return
+    const keyboard = window.convertRectFromWindow(end, null)
+    const hidden =
+      keyboard.size.height <= 0 || keyboard.origin.y >= window.bounds.size.height
+    const frame = native.convertRectToView(native.bounds, null)
+    const bottom = frame.origin.y + frame.size.height - view.translateY
+    const overlap = hidden ? 0 : Math.max(0, bottom + offset - keyboard.origin.y)
+    if (overlap === current) return
+    current = overlap
+    stop(view, ['y'])
+    const apply = () => {
+      view.translateY = overlap ? -overlap : 0
+    }
+    const duration = info.objectForKey(UIKeyboardAnimationDurationUserInfoKey)
+      ?.doubleValue as number | undefined
+    if (!duration) return apply()
+    const curve =
+      (info.objectForKey(UIKeyboardAnimationCurveUserInfoKey)?.integerValue as
+        number | undefined) ?? 0
+    // The keyboard's curve is private; shifted into the options it still applies.
+    UIView.animateWithDurationDelayOptionsAnimationsCompletion(
+      duration,
+      0,
+      ((curve << 16) | BEGIN_FROM_CURRENT_STATE) as UIViewAnimationOptions,
+      apply,
+      () => {},
+    )
+  }
+  const observer = Application.ios.addNotificationObserver(
+    UIKeyboardWillChangeFrameNotification,
+    onKeyboard,
+  )
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    Application.ios.removeNotificationObserver(
+      observer,
+      UIKeyboardWillChangeFrameNotification,
+    )
+    view.off('unloaded', cleanup)
+    if (current) view.translateY = 0
+  }
+  view.on('unloaded', cleanup)
+  return cleanup
+}
+
+function followAndroid(view: View, offset: number) {
+  if (android.os.Build.VERSION.SDK_INT < 30) return () => {}
+  const density = Utils.layout.getDisplayDensity()
+  let disposed = false
+  let follower: org.rafaelaugusto.jolt.KeyboardFollower | undefined
+  const attach = () => {
+    if (disposed || follower) return
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (!native) return
+    try {
+      follower = new org.rafaelaugusto.jolt.KeyboardFollower(
+        native,
+        offset * density,
+        new org.rafaelaugusto.jolt.KeyboardFollower.Listener({
+          onStart: () => stop(view, ['y']),
+          onSettled: (translation) => {
+            view.translateY = translation / density
+          },
+        }),
+      )
+    } catch {
+      // A JS-only update cannot install the native plugin. Leave the platform's resize in place.
+      return
+    }
+    follower.attach()
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    view.off('loaded', attach)
+    view.off('unloaded', cleanup)
+    if (follower) {
+      follower.detach()
+      follower = undefined
+      view.translateY = 0
+    }
+  }
+  view.on('loaded', attach)
+  view.on('unloaded', cleanup)
+  if (view.isLoaded) attach()
+  return cleanup
+}

package/src/label.ts

@@ -0,0 +1,76 @@
+import type { Label } from '@nativescript/core'
+
+const callbacks = new WeakMap<NSObject, (finished: boolean) => void>()
+let Delegate: typeof NSObject | undefined
+const styleEvents = [
+  'fontInternalChange',
+  'colorChange',
+  'textAlignmentChange',
+  'textDecorationChange',
+  'textTransformChange',
+  'letterSpacingChange',
+  'lineHeightChange',
+  'textShadowChange',
+  'textStrokeChange',
+  'whiteSpaceChange',
+  'textOverflowChange',
+  'maxLinesChange',
+  'paddingLeftChange',
+  'paddingRightChange',
+  'paddingTopChange',
+  'paddingBottomChange',
+  'visibilityChange',
+  'directionChange',
+  'borderLeftWidthChange',
+  'borderRightWidthChange',
+  'borderTopWidthChange',
+  'borderBottomWidthChange',
+]
+
+/** Reports text, formatted text and style changes of a Label until the returned function is called. */
+export function watchLabel(view: Label, onChange: () => void): () => void {
+  const formatted = view.formattedText
+  view.on('textChange', onChange)
+  view.on('formattedTextChange', onChange)
+  formatted?.on('propertyChange', onChange)
+  for (const event of styleEvents) view.style.on(event, onChange)
+  return () => {
+    view.off('textChange', onChange)
+    view.off('formattedTextChange', onChange)
+    formatted?.off('propertyChange', onChange)
+    for (const event of styleEvents) view.style.off(event, onChange)
+  }
+}
+
+/** A CAAnimationDelegate that reports when its animation stops. Release it with `forgetCompletion`. */
+export function completion(
+  callback: (finished: boolean) => void,
+): NSObject & CAAnimationDelegate {
+  if (!Delegate) {
+    const base = NSObject as typeof NSObject & {
+      extend(
+        methods: object,
+        options: { protocols: unknown[]; name: string },
+      ): typeof NSObject
+    }
+    Delegate = base.extend(
+      {
+        animationDidStopFinished(
+          this: NSObject,
+          _animation: CAAnimation,
+          finished: boolean,
+        ) {
+          callbacks.get(this)?.(finished)
+        },
+      },
+      { protocols: [CAAnimationDelegate], name: 'JoltLabelAnimationDelegate' },
+    )
+  }
+  const delegate = Delegate.new()
+  callbacks.set(delegate, callback)
+  return delegate
+}
+
+export function forgetCompletion(delegate: NSObject) {
+  callbacks.delete(delegate)
+}

package/src/liquid.ts

@@ -3,6 +3,8 @@ import { tintColorProperty } from '@nativescript/core/ui/image'
 import { toView } from './animate.js'
 import { liquidGrid } from './liquid-grid.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
+import { ownImage } from './image-owner.js'
 
 export interface LiquidOptions {
   /** Amount of internal deformation, from 0 to 1. Defaults to 0.7. */
@@ -49,6 +51,7 @@ export function liquid(target: Target, options: LiquidOptions = {}): LiquidEffec
 }
 
 class Liquid implements LiquidEffect {
+  private releaseOwnership: (() => void) | undefined
   private stopped = false
   private queued = false
   private pausedByUser = false
@@ -68,6 +71,7 @@ class Liquid implements LiquidEffect {
     private readonly image: Image,
     private readonly settings: Required<LiquidOptions>,
   ) {
+    this.releaseOwnership = ownImage(image, this.stop)
     running.set(image, this)
     for (const event of ['loaded', 'layoutChanged', 'imageSourceChange', 'stretchChange'])
       image.on(event, this.schedule)
@@ -92,6 +96,7 @@ class Liquid implements LiquidEffect {
   stop = () => {
     if (this.stopped) return
     this.stopped = true
+    this.releaseOwnership?.()
     for (const event of ['loaded', 'layoutChanged', 'imageSourceChange', 'stretchChange'])
       this.image.off(event, this.schedule)
     this.image.off('unloaded', this.unloaded)
@@ -134,7 +139,7 @@ class Liquid implements LiquidEffect {
       !this.image.isLoaded ||
       this.image.visibility !== 'visible' ||
       this.image.tintColor ||
-      UIAccessibilityIsReduceMotionEnabled()
+      reducedMotion()
     )
       return this.remove()
     const native = this.image.nativeViewProtected as UIImageView | undefined

package/src/loader.ts

@@ -1,6 +1,7 @@
 import { Application, Color, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export type LoaderStyle = 'dots' | 'bars' | 'ring'
 
@@ -160,7 +161,7 @@ class Loader {
           0,
         )
       }
-      const reduced = UIAccessibilityIsReduceMotionEnabled()
+      const reduced = reducedMotion()
       item.opacity = style === 'ring' ? 0.35 : 1
       if (reduced && this.animating) {
         item.removeAnimationForKey(key)

package/src/particles.ts

@@ -1,6 +1,7 @@
 import { Application, Color, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
 
 export interface ConfettiOptions {
   /** Approximate number of particles in the burst. Defaults to 80. */
@@ -78,8 +79,7 @@ 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 || UIAccessibilityIsReduceMotionEnabled())
-    return () => {}
+  if (!isIOS || settings.rate === 0 || reducedMotion()) return () => {}
   return new Emitter(view, settings, overlay, running).stop
 }
 
@@ -191,12 +191,12 @@ class Emitter {
   }
 
   private motionChanged = () => {
-    if (UIAccessibilityIsReduceMotionEnabled()) this.stop()
+    if (reducedMotion()) this.stop()
   }
 
   private update() {
     if (!this.view.isLoaded) return
-    if (UIAccessibilityIsReduceMotionEnabled()) return this.stop()
+    if (reducedMotion()) return this.stop()
     const native = this.view.nativeViewProtected as UIView | undefined
     const window = native?.window
     if (this.layer && (!native || !window)) return this.stop()

package/src/path.ts

@@ -0,0 +1,124 @@
+import { parsePath, type MotionPath } from './svg-path.js'
+import { reducedMotion, timeScale } from './config.js'
+import { createTrack, instantTrack, type Track } from './track.js'
+import {
+  mergeTransitions,
+  resolveTransition,
+  type Transition,
+  type ResolvedTransition,
+} from './transition.js'
+import type { Keyframes, KeyframeProperty } from './types.js'
+
+export type PathProperty = 'x' | 'y' | 'rotate'
+export interface PreparedPath {
+  readonly properties: readonly PathProperty[]
+  readonly starts: ReadonlyMap<PathProperty, number>
+  readonly transition: ResolvedTransition
+  track(property: PathProperty, offset: number, delay: number): Track
+}
+
+export function preparePath(
+  keyframes: Keyframes,
+  base: Transition,
+  overrides: Partial<Record<KeyframeProperty | 'path', Transition>>,
+): PreparedPath | undefined {
+  if (keyframes.orient !== undefined && typeof keyframes.orient !== 'boolean')
+    throw new TypeError('Path orient must be a boolean.')
+  if (keyframes.path === undefined) {
+    if (keyframes.orient !== undefined) throw new TypeError('orient requires a path.')
+    return undefined
+  }
+  if (keyframes.x !== undefined || keyframes.y !== undefined)
+    throw new TypeError('A path owns x and y; omit explicit x/y keyframes.')
+  if (keyframes.orient && keyframes.rotate !== undefined)
+    throw new TypeError('An oriented path owns rotate; omit explicit rotate keyframes.')
+  if (overrides.x || overrides.y || (keyframes.orient && overrides.rotate))
+    throw new TypeError('Use the path transition to time its coordinates together.')
+  const geometry = parsePath(keyframes.path)
+  const orient = keyframes.orient === true
+  const transition = resolveTransition(
+    overrides.path ? mergeTransitions(base, overrides.path) : base,
+    'opacity',
+    2,
+  )
+  if (
+    !Number.isFinite(transition.curve.type === 'tween' ? transition.curve.duration : 0) ||
+    !Number.isFinite(transition.delay)
+  )
+    throw new RangeError('Path duration and delay must be finite.')
+  const properties: readonly PathProperty[] = orient ? ['x', 'y', 'rotate'] : ['x', 'y']
+  const first = geometry.at(0)
+  let motion: ReturnType<typeof sample> | undefined
+  return {
+    properties,
+    starts: new Map(properties.map((property) => [property, first[property]])),
+    transition,
+    track(property, offset, requested) {
+      motion ??= sample(geometry, transition, orient)
+      const { progress, times, frames } = motion
+      const to = geometry.at(progress.to)[property] + offset
+      if (reducedMotion()) return instantTrack(property, to)
+      const delay = requested / timeScale()
+      const shift = delay - progress.delay
+      const pose = (time: number) =>
+        geometry.at(progress.valueAt(time - shift))[property] + offset
+      return {
+        ...progress,
+        property,
+        delay,
+        end: progress.end + shift,
+        arrival: progress.arrival + shift,
+        times,
+        values: offset
+          ? frames[property].map((value) => value + offset)
+          : frames[property],
+        to,
+        valueAt: pose,
+        velocityAt(time) {
+          if (time <= delay || time >= progress.end + shift) return 0
+          const position = progress.valueAt(time - shift)
+          if (position < 0 || position > 1) return 0
+          const epsilon = Math.min(1e-5, 0.01 / Math.max(1, geometry.length))
+          const a = Math.max(0, position - epsilon),
+            b = Math.min(1, position + epsilon)
+          return (
+            ((geometry.at(b)[property] - geometry.at(a)[property]) / (b - a)) *
+            progress.velocityAt(time - shift)
+          )
+        },
+      }
+    },
+  }
+}
+
+/** Sample scalar timing once, then project all coordinates through the same path. */
+function sample(geometry: MotionPath, transition: ResolvedTransition, orient: boolean) {
+  const progress = createTrack('opacity', [0, 1], transition, 0)
+  const count = Math.max(
+    1,
+    Math.min(
+      6000,
+      Math.max(
+        Math.ceil((progress.duration / 1000) * 60),
+        Math.ceil(geometry.length / 2),
+      ),
+    ),
+  )
+  const times = Array.from({ length: count + 1 }, (_, i) => i / count)
+  const frames: Record<PathProperty, number[]> = { x: [], y: [], rotate: [] }
+  for (const time of times) {
+    const position =
+      time === 0
+        ? 0
+        : time === 1
+          ? 1
+          : progress.valueAt(progress.delay + time * progress.duration)
+    if (!Number.isFinite(position))
+      throw new RangeError('Path easing must return finite progress.')
+    const pose = geometry.at(position)
+    frames.x.push(pose.x)
+    frames.y.push(pose.y)
+    if (orient) frames.rotate.push(pose.rotate)
+  }
+  return { progress, times, frames }
+}