@rafaelaugusto/jolt 0.1.0-beta.1 → 0.1.0-beta.10

package/src/image-effect-native.ts

@@ -0,0 +1,129 @@
+import { Utils, isAndroid, isIOS, type Image, type ImageSource } from '@nativescript/core'
+
+export interface ImageEffectSettings {
+  mode: number
+  x: number
+  y: number
+  amplitude: number
+  radius: number
+  duration: number
+  seed: number
+  to?: ImageSource
+}
+
+export interface ImageRenderer {
+  readonly backend: 'metal' | 'agsl'
+  readonly progress: number
+  readonly frames: number
+  readonly textureBytes: number
+  readonly longestFrameMs: number
+  play(endpoint: number): void
+  pause(): void
+  resume(): void
+  seek(progress: number): void
+  finish(endpoint: number): void
+  stop(preserveImage?: boolean): void
+}
+
+export function createImageRenderer(
+  image: Image,
+  settings: ImageEffectSettings,
+  ended: (completed: boolean, progress: number) => void,
+): ImageRenderer | undefined {
+  const { mode, x, y, amplitude, radius, duration, seed, to } = settings
+  if (isIOS && typeof JoltImageEffect !== 'undefined') {
+    const native =
+      JoltImageEffect.createWithViewDestinationModeOriginXOriginYAmplitudeRadiusDurationSeedListener(
+        image.nativeViewProtected,
+        to?.ios ?? null,
+        mode,
+        x,
+        y,
+        amplitude,
+        radius,
+        duration,
+        seed,
+        ended,
+      )
+    if (!native) return undefined
+    return {
+      backend: 'metal',
+      get progress() {
+        return native.progress
+      },
+      get frames() {
+        return native.frames
+      },
+      get textureBytes() {
+        return native.textureBytes
+      },
+      get longestFrameMs() {
+        return native.longestFrame * 1000
+      },
+      play: (p) => native.play(p),
+      pause: () => native.pause(),
+      resume: () => native.resume(),
+      seek: (p) => native.seek(p),
+      finish: (p) => native.finish(p),
+      stop: (preserveImage) =>
+        preserveImage ? native.stopPreservingImage() : native.stop(),
+    }
+  }
+  if (isAndroid && android.os.Build.VERSION.SDK_INT >= 33) {
+    const density = Utils.layout.getDisplayDensity()
+    const background = image.nativeViewProtected.getBackground()
+    // NativeScript draws bitmap pixels itself: ImageView.getImageMatrix() does
+    // not describe its stretch, EXIF rotation or inner border clipping.
+    const geometry = Array.create('float', 6)
+    geometry[0] = image.imageSource?.rotationAngle ?? 0
+    geometry[1] = to?.rotationAngle ?? 0
+    const corners = ['TopLeft', 'TopRight', 'BottomRight', 'BottomLeft']
+    corners.forEach((corner, i) => {
+      geometry[i + 2] = background?.[`getBorder${corner}Radius`]?.() ?? 0
+    })
+    const native = new org.rafaelaugusto.jolt.ImageEffect(
+      image.nativeViewProtected,
+      image.imageSource?.android ?? null,
+      to?.android ?? null,
+      geometry,
+      mode,
+      x * density,
+      y * density,
+      amplitude * density,
+      radius * density,
+      duration,
+      seed,
+      (image as Image & { touchListener?: android.view.View.OnTouchListener })
+        .touchListener ?? null,
+      new org.rafaelaugusto.jolt.ImageEffect.Listener({ onEnd: ended }),
+    )
+    if (!native.isSupported()) {
+      const reason = native.getFailureReason()
+      native.stop()
+      throw new Error(reason)
+    }
+    return {
+      backend: 'agsl',
+      get progress() {
+        return native.getProgress()
+      },
+      get frames() {
+        return native.getFrames()
+      },
+      get textureBytes() {
+        return native.getTextureBytes()
+      },
+      get longestFrameMs() {
+        return native.getLongestFrameNanos() / 1e6
+      },
+      play: (p) => native.play(p),
+      pause: () => native.pause(),
+      resume: () => native.resume(),
+      seek: (p) => native.seek(p),
+      finish: (p) => native.finish(p),
+      stop: (preserveImage) =>
+        preserveImage ? native.stopPreservingImage() : native.stop(),
+    }
+  }
+  return undefined
+}

package/src/image-effect.ts

@@ -0,0 +1,336 @@
+import {
+  Application,
+  Image,
+  ImageSource,
+  isIOS,
+  type EventData,
+} from '@nativescript/core'
+import { toView } from './animate.js'
+import { reducedMotion, timeScale } from './config.js'
+import type { Animation } from './engine.js'
+import { ownImage } from './image-owner.js'
+import { createImageRenderer, type ImageRenderer } from './image-effect-native.js'
+import type { Target } from './types.js'
+
+export type ImageEffectName = 'ripple' | 'distortion' | 'dissolve'
+export interface ImageEffectOptions {
+  /** Origin in target-local DIPs; defaults to the center. */
+  origin?: { x: number; y: number }
+  /** Maximum displacement in DIPs, 0..64. Defaults to 8. */
+  amplitude?: number
+  /** Influence radius in DIPs, greater than zero. Defaults to 96. */
+  radius?: number
+  /** Milliseconds for a finite effect (or drag release). Defaults to 650. */
+  duration?: number
+  /** Deterministic dissolve noise seed, 0..65535. Defaults to 1. */
+  seed?: number
+  /** Loaded destination raster for dissolve. */
+  to?: ImageSource
+  /** Prepare at progress zero without starting. */
+  paused?: boolean
+}
+export interface ImageEffectDiagnostics {
+  backend: 'waiting' | 'metal' | 'agsl' | 'fallback'
+  reason?: 'reduced-motion' | 'unsupported' | 'not-visible'
+  /** Native setup error, when available. Intended for developer diagnostics. */
+  detail?: string
+  frames: number
+  textureBytes: number
+  peakTextureBytes: number
+  preparationMs: number
+  longestFrameMs: number
+}
+export interface ImageEffect extends Animation {
+  readonly effect: ImageEffectName
+  readonly paused: boolean
+  /** Finite progress; distortion rejects seeking because it follows native touch input. */
+  progress: number
+  readonly diagnostics: Readonly<ImageEffectDiagnostics>
+  pause(): void
+  play(): void
+  /** Reverse a finite effect from its current pixels. Terminal handles remain terminal. */
+  reverse(): void
+  /** Complete immediately at the current direction's endpoint. */
+  finish(): void
+}
+
+const names: readonly ImageEffectName[] = ['ripple', 'distortion', 'dissolve']
+const surfaceChanges = [
+  'tintColorChange',
+  ...['TopLeft', 'TopRight', 'BottomRight', 'BottomLeft'].map(
+    (corner) => `border${corner}RadiusChange`,
+  ),
+  ...['Top', 'Right', 'Bottom', 'Left'].flatMap((edge) => [
+    `padding${edge}Change`,
+    `border${edge}WidthChange`,
+  ]),
+]
+
+/** Optional native image effects. Stop restores the source; dissolve completion commits its destination. */
+export function imageEffect(
+  target: Target,
+  effect: ImageEffectName,
+  options: ImageEffectOptions = {},
+): ImageEffect {
+  const image = toView(target)
+  if (!(image instanceof Image))
+    throw new TypeError('imageEffect() expects a NativeScript Image.')
+  if (!names.includes(effect))
+    throw new TypeError(`Unknown image effect: ${String(effect)}.`)
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Image effect options must be an object.')
+  const amplitude = options.amplitude ?? 8,
+    radius = options.radius ?? 96
+  const duration = options.duration ?? 650,
+    seed = options.seed ?? 1
+  if (!Number.isFinite(amplitude) || amplitude < 0 || amplitude > 64)
+    throw new RangeError('Image displacement must be between 0 and 64 DIPs.')
+  if (
+    !Number.isFinite(radius) ||
+    radius <= 0 ||
+    !Number.isFinite(duration) ||
+    duration <= 0
+  )
+    throw new RangeError('Image radius and duration must be positive finite numbers.')
+  if (!Number.isInteger(seed) || seed < 0 || seed > 65535)
+    throw new RangeError('Image seed must be an integer between 0 and 65535.')
+  if (
+    options.origin &&
+    (!Number.isFinite(options.origin.x) || !Number.isFinite(options.origin.y))
+  )
+    throw new RangeError('Image origin must contain finite local coordinates.')
+  if (options.paused !== undefined && typeof options.paused !== 'boolean')
+    throw new TypeError('paused must be a boolean.')
+  if (
+    effect === 'dissolve' &&
+    (!(options.to instanceof ImageSource) ||
+      !Number.isFinite(options.to.width) ||
+      !Number.isFinite(options.to.height) ||
+      options.to.width <= 0 ||
+      options.to.height <= 0)
+  )
+    throw new TypeError('Dissolve requires a loaded destination ImageSource.')
+  return new Effect(image, effect, {
+    ...options,
+    amplitude,
+    radius,
+    duration: duration / timeScale(),
+    seed,
+  })
+}
+
+class Effect implements ImageEffect {
+  readonly finished: Promise<boolean>
+  private resolve!: (completed: boolean) => void
+  private renderer: ImageRenderer | undefined
+  private releaseOwnership: () => void = () => {}
+  private terminal = false
+  private queued = false
+  private committing = false
+  private userPaused: boolean
+  private suspended = false
+  private position = 0
+  private direction: 0 | 1 = 1
+  private dimensions = ''
+  private stats: ImageEffectDiagnostics = {
+    backend: 'waiting',
+    frames: 0,
+    textureBytes: 0,
+    peakTextureBytes: 0,
+    preparationMs: 0,
+    longestFrameMs: 0,
+  }
+  private reduceObserver:
+    ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly image: Image,
+    readonly effect: ImageEffectName,
+    private readonly options: ImageEffectOptions &
+      Required<Pick<ImageEffectOptions, 'amplitude' | 'radius' | 'duration' | 'seed'>>,
+  ) {
+    this.userPaused = options.paused ?? false
+    this.finished = new Promise((resolve) => {
+      this.resolve = resolve
+    })
+    this.releaseOwnership = ownImage(image, this.stop)
+    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.style.on('visibilityChange', this.visible)
+    for (const event of surfaceChanges) image.style.on(event, this.changed)
+    Application.on(Application.suspendEvent, this.suspend)
+    Application.on(Application.resumeEvent, this.resume)
+    if (isIOS)
+      this.reduceObserver = Application.ios.addNotificationObserver(
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+        this.preferences,
+      )
+    this.schedule()
+  }
+  then<TResult1 = boolean, TResult2 = never>(
+    fulfilled?: ((value: boolean) => TResult1 | PromiseLike<TResult1>) | null,
+    rejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.finished.then(fulfilled, rejected)
+  }
+  get paused() {
+    return this.userPaused
+  }
+  get progress() {
+    return this.renderer?.progress ?? this.position
+  }
+  set progress(value: number) {
+    if (this.effect === 'distortion')
+      throw new TypeError('Distortion follows touch input and cannot be scrubbed.')
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+      throw new RangeError('Image progress must be between 0 and 1.')
+    if (this.terminal) return
+    this.position = value
+    this.renderer?.seek(value)
+  }
+  get diagnostics(): Readonly<ImageEffectDiagnostics> {
+    return {
+      ...this.stats,
+      ...(this.renderer
+        ? {
+            frames: this.renderer.frames,
+            textureBytes: this.renderer.textureBytes,
+            longestFrameMs: this.renderer.longestFrameMs,
+          }
+        : {}),
+    }
+  }
+  pause = () => {
+    if (this.terminal) return
+    this.userPaused = true
+    this.renderer?.pause()
+  }
+  play = () => {
+    if (this.terminal) return
+    this.userPaused = false
+    if (this.suspended) return
+    if (this.renderer) {
+      if (this.effect === 'distortion') this.renderer.resume()
+      else this.renderer.play(this.direction)
+    } else this.schedule()
+  }
+  reverse = () => {
+    if (this.effect === 'distortion')
+      throw new TypeError('Distortion has no finite playback direction.')
+    if (this.terminal) return
+    this.direction = this.direction === 1 ? 0 : 1
+    this.play()
+  }
+  finish = () => {
+    if (this.terminal) return
+    if (this.effect === 'distortion') return this.stop()
+    this.complete(true, this.direction)
+  }
+  stop = () => this.complete(false, this.progress)
+  private complete = (completed: boolean, position: number, preserveImage = false) => {
+    if (this.terminal) return
+    this.terminal = true
+    this.position = position
+    this.stats = { ...this.diagnostics, textureBytes: 0 }
+    this.renderer?.stop(preserveImage)
+    this.renderer = undefined
+    this.releaseOwnership()
+    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.style.off('visibilityChange', this.visible)
+    for (const event of surfaceChanges) this.image.style.off(event, this.changed)
+    Application.off(Application.suspendEvent, this.suspend)
+    Application.off(Application.resumeEvent, this.resume)
+    if (this.reduceObserver)
+      Application.ios.removeNotificationObserver(
+        this.reduceObserver,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+    this.reduceObserver = undefined
+    if (completed && this.effect === 'dissolve' && position === 1) {
+      this.committing = true
+      // The view may clear its ImageSource on disposal. Keep the caller's
+      // destination reusable by giving the view its own wrapper.
+      const destination = new ImageSource(this.options.to!.getNativeSource())
+      destination.rotationAngle = this.options.to!.rotationAngle
+      this.image.imageSource = destination
+      this.committing = false
+    }
+    this.resolve(completed)
+  }
+  private changed = (event?: EventData) => {
+    if (this.committing) return
+    if (this.renderer)
+      this.complete(false, this.progress, event?.eventName === 'imageSourceChange')
+    else this.schedule()
+  }
+  private suspend = () => {
+    this.suspended = true
+    this.renderer?.pause()
+  }
+  private resume = () => {
+    this.suspended = false
+    this.schedule()
+    if (!this.userPaused) this.play()
+  }
+  private visible = () => {
+    if (this.image.visibility !== 'visible') this.stop()
+  }
+  private preferences = () => {
+    if (reducedMotion()) this.fallback('reduced-motion')
+  }
+  private fallback(reason: ImageEffectDiagnostics['reason']) {
+    this.stats = { ...this.stats, backend: 'fallback', reason }
+    // Reduced/unsupported rendering still performs a requested content change.
+    if (this.effect === 'dissolve' && this.direction === 1) {
+      this.complete(true, 1)
+    } else this.complete(false, 0)
+  }
+  private schedule = () => {
+    if (this.queued || this.terminal) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.terminal || this.suspended || !this.image.isLoaded) return
+      if (reducedMotion()) return this.fallback('reduced-motion')
+      if (this.image.visibility !== 'visible') return this.fallback('not-visible')
+      const { width, height } = this.image.getActualSize()
+      if (width <= 0 || height <= 0) return
+      const dimensions = `${width}:${height}`
+      if (this.renderer) {
+        if (this.dimensions !== dimensions) this.stop()
+        return
+      }
+      if (!this.image.imageSource) return
+      this.dimensions = dimensions
+      const started = Date.now()
+      try {
+        this.renderer = createImageRenderer(
+          this.image,
+          {
+            ...this.options,
+            mode: names.indexOf(this.effect),
+            x: this.options.origin?.x ?? width / 2,
+            y: this.options.origin?.y ?? height / 2,
+          },
+          this.complete,
+        )
+      } catch (error) {
+        this.stats.preparationMs = Date.now() - started
+        this.stats.detail = String(error)
+        return this.fallback('unsupported')
+      }
+      if (!this.renderer) return this.fallback('unsupported')
+      this.stats.backend = this.renderer.backend
+      this.stats.preparationMs = Date.now() - started
+      this.stats.peakTextureBytes = this.renderer.textureBytes
+      this.renderer.pause()
+      if (this.position) this.renderer.seek(this.position)
+      if (!this.userPaused && !this.suspended) this.play()
+    })
+  }
+}

package/src/image-owner.ts

@@ -0,0 +1,12 @@
+import type { Image } from '@nativescript/core'
+
+/** Rendering effects share one image surface; ordinary view transforms stay independent. */
+const owners = new WeakMap<Image, () => void>()
+
+export function ownImage(image: Image, stop: () => void): () => void {
+  owners.get(image)?.()
+  owners.set(image, stop)
+  return () => {
+    if (owners.get(image) === stop) owners.delete(image)
+  }
+}

package/src/index.ts

@@ -1,12 +1,69 @@
-export { animate, stop } from './animate.js'
+export { animate, decay, set, 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 { 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 { 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, 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'
+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, 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 { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
+export type { PlaybackAnimation } from './playback.js'
 export type { Animation } from './engine.js'
+export type { ColorValue, ColorKeyframes } from './color.js'
 export type * from './types.js'
+export { motionScope } from './motion-scope.js'
+export type { MotionScope, MotionResource } from './motion-scope.js'
+export { motionStates } from './motion-states.js'
+export type {
+  MotionStates,
+  MotionStatesOptions,
+  MotionState,
+  MotionValues,
+  StateTransition,
+} from './motion-states.js'
+
+export { animateLayout } from './layout.js'
+export type { LayoutOptions } from './layout.js'

package/src/interaction-surface.ts

@@ -0,0 +1,41 @@
+import type { View, ViewBase } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Target } from './types.js'
+
+const surfaces = new WeakMap<ViewBase, Set<object>>()
+export interface InteractionSurface {
+  readonly disposed: boolean
+  /** Existing animations retain their driver until they end. Disables future opt-in. */
+  dispose(): void
+}
+
+/** Opt a view/subtree into native geometry updates before starting its animations. */
+export function interactionSurface(target: Target): InteractionSurface {
+  const view = toView(target)
+  let tokens = surfaces.get(view)
+  if (!tokens) surfaces.set(view, (tokens = new Set()))
+  const token = {}
+  tokens.add(token)
+  let disposed = false
+  return {
+    get disposed() {
+      return disposed
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      tokens.delete(token)
+      if (!tokens.size) surfaces.delete(view)
+    },
+  }
+}
+
+/** Evaluated at animation start; no per-frame JS traversal. */
+export function hasInteractionSurface(view: View): boolean {
+  let current: ViewBase | undefined = view
+  while (current) {
+    if (surfaces.get(current)?.size) return true
+    current = current.parent
+  }
+  return false
+}

package/src/ios-plugin.d.ts

@@ -0,0 +1,81 @@
+declare class JoltInteractiveAnimation extends NSObject {
+  static startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
+    view: UIView,
+    layers: NSArray<CALayer>,
+    keyPath: string,
+    values: NSArray<number>,
+    times: NSArray<number>,
+    duration: number,
+    delay: number,
+    repeat: number,
+    reverse: boolean,
+    finalValue: number,
+    startedAt: number,
+    completion: (completed: boolean) => void,
+  ): JoltInteractiveAnimation
+  static syncViewExcluding(view: UIView, keyPath: string | null): void
+  static valueForViewKeyPath(view: UIView, keyPath: string): number | null
+  static activeCount(): number
+  readonly elapsed: number
+  controlPaused(elapsed: number, paused: boolean): void
+  cancel(): void
+}
+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
+}