@rafaelaugusto/jolt 0.1.0-beta.0 → 0.1.0-beta.2

package/src/shimmer.ts

@@ -0,0 +1,179 @@
+import { Application, isIOS, type View } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Target } from './types.js'
+
+export interface ShimmerOptions {
+  /** Milliseconds per sweep. Defaults to 1500. */
+  duration?: number
+}
+
+const running = new WeakMap<View, () => void>()
+const key = 'jolt:shimmer'
+
+// NativeScript saves a mask here while applying clip-path or non-uniform borders.
+type MaskedView = UIView & { originalMask?: CALayer | null }
+
+/**
+ * Sweeps a native gradient mask across an iOS placeholder until stopped.
+ * Waits for layout, respects Reduce Motion and pauses while the view is unloaded.
+ * Android is a no-op. Returns an idempotent cleanup function.
+ */
+export function shimmer(target: Target, options: ShimmerOptions = {}): () => void {
+  const view = toView(target)
+  const duration = options.duration ?? 1500
+  if (!Number.isFinite(duration) || duration <= 0)
+    throw new RangeError('Shimmer duration must be a positive finite number.')
+  running.get(view)?.()
+  if (!isIOS) return () => {}
+  return new Shimmer(view, duration).stop
+}
+
+class Shimmer {
+  private stopped = false
+  private queued = false
+  private waitingForLoad: boolean
+  private native: MaskedView | undefined
+  private owner: CALayer | undefined
+  private gradient: CAGradientLayer | undefined
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: View,
+    private readonly duration: number,
+  ) {
+    this.waitingForLoad = !view.isLoaded
+    running.set(view, this.stop)
+    view.on('loaded', this.loaded)
+    view.on('layoutChanged', this.schedule)
+    view.on('unloaded', this.unloaded)
+    view.style.on('backgroundInternalChange', this.schedule)
+    this.update()
+  }
+
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    const { view } = this
+    view.off('loaded', this.loaded)
+    view.off('layoutChanged', this.schedule)
+    view.off('unloaded', this.unloaded)
+    view.style.off('backgroundInternalChange', this.schedule)
+    if (running.get(view) === this.stop) running.delete(view)
+    this.unloaded()
+  }
+
+  private loaded = () => {
+    this.waitingForLoad = false
+    this.schedule()
+  }
+
+  private unloaded = () => {
+    this.waitingForLoad = true
+    if (this.observer) {
+      Application.ios.removeNotificationObserver(
+        this.observer,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+      this.observer = undefined
+    }
+    this.remove()
+  }
+
+  private schedule = () => {
+    if (this.stopped || this.queued) return
+    this.queued = true
+    // Core raises layoutChanged before redrawing the background and its mask.
+    // Attach after that pass, coalescing events from the same layout.
+    void Promise.resolve().then(() => {
+      this.queued = false
+      this.update()
+    })
+  }
+
+  private update = () => {
+    if (this.stopped || this.waitingForLoad || !this.view.isLoaded) return
+    const native = this.view.nativeViewProtected as MaskedView | undefined
+    if (!native) return
+    this.observer ??= Application.ios.addNotificationObserver(
+      UIAccessibilityReduceMotionStatusDidChangeNotification,
+      this.update,
+    )
+    if (UIAccessibilityIsReduceMotionEnabled()) return this.remove()
+    const bounds = native.layer.bounds
+    if (bounds.size.width <= 0 || bounds.size.height <= 0) return this.remove()
+    if (this.native && this.native !== native) this.remove()
+
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      this.native = native
+      const gradient = (this.gradient ??= this.createGradient())
+      // Leave Core's mask at the root so it can keep updating its path on resize.
+      let owner = native.layer
+      while (owner.mask && owner.mask !== gradient) owner = owner.mask
+      if (this.owner && this.owner !== owner && this.owner.mask === gradient)
+        this.owner.mask = null
+      this.owner = owner
+      owner.mask = gradient
+      // Don't let a later background redraw resurrect our mask after cleanup.
+      if (native.originalMask === gradient) native.originalMask = null
+
+      // Core's CAShapeLayer masks draw a path with zero bounds. In that case the
+      // path uses the view's coordinates; other masks have their own bounds.
+      const area =
+        owner.bounds.size.width > 0 && owner.bounds.size.height > 0
+          ? owner.bounds
+          : bounds
+      gradient.frame = CGRectMake(
+        area.origin.x - area.size.width,
+        area.origin.y,
+        area.size.width * 3,
+        area.size.height,
+      )
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private createGradient(): CAGradientLayer {
+    const gradient = CAGradientLayer.new()
+    const dim = UIColor.colorWithWhiteAlpha(1, 0.35).CGColor
+    gradient.colors = NSArray.arrayWithArray([dim, UIColor.whiteColor.CGColor, dim])
+    gradient.startPoint = CGPointMake(0, 0.5)
+    gradient.endPoint = CGPointMake(1, 0.5)
+
+    // A three-width mask lets the band enter and leave while every stop stays
+    // within the documented 0...1 range for CAGradientLayer.locations.
+    const from = NSArray.arrayWithArray([0, 0.125, 0.25])
+    const to = NSArray.arrayWithArray([0.75, 0.875, 1])
+    gradient.locations = from
+    const animation = CABasicAnimation.animationWithKeyPath('locations')
+    animation.fromValue = from
+    animation.toValue = to
+    animation.duration = this.duration / 1000
+    animation.repeatCount = Infinity
+    animation.removedOnCompletion = false
+    animation.timingFunction = CAMediaTimingFunction.functionWithName(
+      kCAMediaTimingFunctionLinear,
+    )
+    gradient.addAnimationForKey(animation, key)
+    return gradient
+  }
+
+  private remove() {
+    const { gradient, owner, native } = this
+    if (!gradient) return
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      gradient.removeAnimationForKey(key)
+      if (owner?.mask === gradient) owner.mask = null
+      if (native?.originalMask === gradient) native.originalMask = null
+    } finally {
+      CATransaction.commit()
+    }
+    this.owner = undefined
+    this.gradient = undefined
+    this.native = undefined
+  }
+}

package/src/symbol-effect.ts

@@ -0,0 +1,225 @@
+import { Image, ImageSource, isIOS } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Animation } from './engine.js'
+import type { Target } from './types.js'
+
+export type SymbolEffectName = 'bounce' | 'pulse' | 'scale' | 'variableColor'
+
+export type SymbolEffect = SymbolEffectName | { replace: `sys://${string}` }
+
+export interface SymbolEffectOptions {
+  /** Native playback speed multiplier. Defaults to 1. */
+  speed?: number
+  /** Repeat bounce, pulse or variableColor until stopped. Defaults to false. */
+  repeat?: boolean
+}
+
+const running = new WeakMap<Image, SymbolAnimation>()
+const names: readonly string[] = ['bounce', 'pulse', 'scale', 'variableColor']
+
+/**
+ * Plays an iOS 17+ SF Symbol effect on a NativeScript Image.
+ * Scale holds until stopped; replacements also update the Image's src.
+ *
+ * ```ts
+ * symbolEffect(icon, 'bounce')
+ * symbolEffect(icon, { replace: 'sys://heart.fill' })
+ * ```
+ */
+export function symbolEffect(
+  target: Target,
+  effect: SymbolEffect,
+  options: SymbolEffectOptions = {},
+): Animation {
+  const view = toView(target)
+  if (!(view instanceof Image)) throw new TypeError('symbolEffect expects an Image.')
+  if (
+    typeof effect === 'string'
+      ? !names.includes(effect)
+      : !effect ||
+        typeof effect.replace !== 'string' ||
+        !/^sys:\/\/[^\s/]+$/.test(effect.replace)
+  ) {
+    throw new TypeError('Expected a symbol effect name or { replace: "sys://name" }.')
+  }
+  const speed = options.speed ?? 1
+  if (!Number.isFinite(speed) || speed <= 0)
+    throw new RangeError('Symbol effect speed must be a positive finite number.')
+  if (options.repeat !== undefined && typeof options.repeat !== 'boolean')
+    throw new TypeError('Symbol effect repeat must be a boolean.')
+  if (options.repeat && (typeof effect !== 'string' || effect === 'scale'))
+    throw new TypeError('Only bounce, pulse and variableColor can repeat.')
+
+  return new SymbolAnimation(view, effect, speed, options.repeat ?? false)
+}
+
+class SymbolAnimation implements Animation {
+  readonly finished: Promise<boolean>
+  private resolve!: (finished: boolean) => void
+  private settled = false
+  private started = false
+  private changingSource = false
+  private waitingForLoad: boolean
+  private native: UIImageView | undefined
+  private nativeEffect: NSSymbolEffect | undefined
+  private replacement: UIImage | undefined
+
+  constructor(
+    private readonly view: Image,
+    private readonly effect: SymbolEffect,
+    private readonly speed: number,
+    private readonly repeat: boolean,
+  ) {
+    this.finished = new Promise((resolve) => (this.resolve = resolve))
+    this.waitingForLoad = !view.isLoaded
+    running.get(view)?.stop()
+    running.set(view, this)
+    view.on('unloaded', this.stop)
+    view.on('srcChange', this.sourceChanged)
+    view.on('imageSourceChange', this.imageChanged)
+    view.on('loaded', this.loaded)
+    view.on('isLoadingChange', this.start)
+    this.start()
+  }
+
+  then<A = boolean, B = never>(
+    onfulfilled?: ((finished: boolean) => A | PromiseLike<A>) | null,
+    onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+  ): Promise<A | B> {
+    return this.finished.then(onfulfilled, onrejected)
+  }
+
+  stop = () => this.end(false, true)
+
+  private sourceChanged = () => {
+    if (!this.changingSource) this.stop()
+  }
+
+  private imageChanged = () => {
+    if (this.changingSource) return
+    if (this.started) this.stop()
+    else this.start()
+  }
+
+  private loaded = () => {
+    this.waitingForLoad = false
+    this.start()
+  }
+
+  private start = () => {
+    if (this.settled || this.started) return
+    if (!isIOS) return this.end(false)
+    const { view, effect } = this
+    // isLoaded becomes true before NativeScript resumes native property updates.
+    // Wait for the loaded event so intermediate image resets don't start playback.
+    if (
+      this.waitingForLoad ||
+      !view.isLoaded ||
+      !view.nativeViewProtected ||
+      view.isLoading
+    )
+      return
+    this.started = true
+    const native = (this.native = view.nativeViewProtected as UIImageView)
+    const reducedMotion = UIAccessibilityIsReduceMotionEnabled()
+
+    if (typeof effect !== 'string') {
+      // Resolve first so a symbol absent on this OS doesn't clear the current image.
+      if (!ImageSource.fromSystemImageSync(effect.replace.slice(6))?.ios)
+        return this.end(false)
+      const previous = native.image
+      const loadMode = view.loadMode
+      this.changingSource = true
+      try {
+        // Let NativeScript update its source, tint, configuration and pending loads.
+        // Both assignments happen in this turn, before UIKit draws the next frame.
+        view.loadMode = 'sync'
+        view.src = effect.replace
+      } finally {
+        view.loadMode = loadMode
+        this.changingSource = false
+      }
+      // A source-change listener may have started another effect or changed the src.
+      if (this.settled) return
+      if (view.src !== effect.replace) return this.end(false)
+      const image = native.image
+      if (!image) return this.end(false)
+      if (
+        reducedMotion ||
+        !previous?.symbolImage ||
+        !native.respondsToSelector(
+          'setSymbolImage:withContentTransition:options:completion:',
+        )
+      )
+        return this.end(true)
+
+      this.replacement = image
+      native.image = previous
+      native.setSymbolImageWithContentTransitionOptionsCompletion(
+        image,
+        NSSymbolReplaceContentTransition.transition(),
+        this.options(),
+        this.completed,
+      )
+      return
+    }
+
+    if (
+      reducedMotion ||
+      !native.image?.symbolImage ||
+      !native.respondsToSelector('addSymbolEffect:options:animated:completion:')
+    )
+      return this.end(false)
+
+    const factories = {
+      bounce: NSSymbolBounceEffect,
+      pulse: NSSymbolPulseEffect,
+      scale: NSSymbolScaleEffect,
+      variableColor: NSSymbolVariableColorEffect,
+    }
+    this.nativeEffect = factories[effect].effect()
+    native.addSymbolEffectOptionsAnimatedCompletion(
+      this.nativeEffect,
+      this.options(),
+      true,
+      this.completed,
+    )
+  }
+
+  private options(): NSSymbolEffectOptions {
+    const options = this.repeat
+      ? NSSymbolEffectOptions.optionsWithRepeating()
+      : NSSymbolEffectOptions.optionsWithNonRepeating()
+    return options.optionsWithSpeed(this.speed)
+  }
+
+  private completed = (context: UISymbolEffectCompletionContext) => {
+    // Scale's entrance can complete while the effect is still holding its state.
+    if (context.finished && (this.effect === 'scale' || this.repeat)) return
+    this.end(context.finished)
+  }
+
+  private end(finished: boolean, remove = false) {
+    if (this.settled) return
+    this.settled = true
+    const { view, native, nativeEffect, replacement } = this
+    view.off('loaded', this.loaded)
+    view.off('isLoadingChange', this.start)
+    view.off('unloaded', this.stop)
+    view.off('srcChange', this.sourceChanged)
+    view.off('imageSourceChange', this.imageChanged)
+    if (running.get(view) === this) running.delete(view)
+    if (remove && native) {
+      if (nativeEffect) native.removeSymbolEffectOfType(nativeEffect)
+      // Content transitions have no removal API. Keep the destination icon.
+      if (replacement && native.image === replacement) {
+        native.image = null
+        native.image = replacement
+      }
+    }
+    this.native = undefined
+    this.nativeEffect = undefined
+    this.replacement = undefined
+    this.resolve(finished)
+  }
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { View } from '@nativescript/core'
+import type { Haptic } from './haptics.js'
 import type { SpringName, Transition } from './transition.js'
 
 /** A value to animate to, or keyframes. `null` stands for the value the view has when the animation starts. */
@@ -34,6 +35,10 @@ export interface Stagger {
 export type AnimateOptions = Transition & {
   [K in keyof Keyframes]?: Transition | SpringName
 } & {
+  /** Offset translations/rotations and multiply scale/opacity by their values at the start. */
+  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. */
+  haptic?: Haptic
 }