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

package/src/liquid.ts

@@ -0,0 +1,287 @@
+import { Application, Image, isIOS } from '@nativescript/core'
+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. */
+  intensity?: number
+  /** Milliseconds per seamless cycle. Defaults to 8000. */
+  duration?: number
+}
+
+export interface LiquidEffect {
+  /** Freeze the current deformation. */
+  pause(): void
+  /** Continue from the paused deformation. */
+  resume(): void
+  /** Remove the effect and restore the image. Idempotent. */
+  stop(): void
+}
+
+const running = new WeakMap<Image, LiquidEffect>()
+const key = 'jolt:liquid'
+const columns = 24
+const rows = 24
+const steps = 64
+const noop = () => {}
+
+/** Deforms a raster image with native iOS texture warps. Android leaves it unchanged. */
+export function liquid(target: Target, options: LiquidOptions = {}): LiquidEffect {
+  const settings = {
+    intensity: options.intensity ?? 0.7,
+    duration: options.duration ?? 8000,
+  }
+  if (
+    !Number.isFinite(settings.intensity) ||
+    settings.intensity < 0 ||
+    settings.intensity > 1
+  )
+    throw new RangeError('Liquid intensity must be between zero and one.')
+  if (!Number.isFinite(settings.duration) || settings.duration <= 0)
+    throw new RangeError('Liquid duration must be a positive finite number.')
+  const image = toView(target)
+  if (!(image instanceof Image)) throw new TypeError('Expected a NativeScript Image.')
+  running.get(image)?.stop()
+  if (!isIOS || settings.intensity === 0) return { pause: noop, resume: noop, stop: noop }
+  return new Liquid(image, settings)
+}
+
+class Liquid implements LiquidEffect {
+  private releaseOwnership: (() => void) | undefined
+  private stopped = false
+  private queued = false
+  private pausedByUser = false
+  private active = UIApplication.sharedApplication.applicationState === 0 // UIApplicationStateActive
+  private native: UIImageView | undefined
+  private original: UIImage | undefined
+  private source: Image['imageSource'] | undefined
+  private renderer: SKView | undefined
+  private scene: SKScene | undefined
+  private sprite: SKSpriteNode | undefined
+  private observers: [
+    string,
+    ReturnType<typeof Application.ios.addNotificationObserver>,
+  ][] = []
+
+  constructor(
+    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)
+    image.on('unloaded', this.unloaded)
+    image.style.on('visibilityChange', this.schedule)
+    image.style.on('tintColorChange', this.schedule)
+    this.observe(UIAccessibilityReduceMotionStatusDidChangeNotification, this.schedule)
+    this.observe(UIApplicationWillResignActiveNotification, this.suspend)
+    this.observe(UIApplicationDidBecomeActiveNotification, this.activate)
+    this.schedule()
+  }
+
+  pause = () => {
+    this.pausedByUser = true
+    if (this.renderer) this.renderer.paused = true
+  }
+  resume = () => {
+    if (this.stopped) return
+    this.pausedByUser = false
+    this.schedule()
+  }
+  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)
+    this.image.style.off('visibilityChange', this.schedule)
+    this.image.style.off('tintColorChange', this.schedule)
+    for (const [name, observer] of this.observers)
+      Application.ios.removeNotificationObserver(observer, name)
+    this.observers = []
+    if (running.get(this.image) === this) running.delete(this.image)
+    this.remove()
+  }
+  private observe(name: string, callback: () => void) {
+    this.observers.push([name, Application.ios.addNotificationObserver(name, callback)])
+  }
+  private suspend = () => {
+    this.active = false
+    if (this.renderer) this.renderer.paused = true
+  }
+  private activate = () => {
+    this.active = true
+    this.schedule()
+  }
+  private unloaded = () => this.remove()
+  private schedule = () => {
+    if (this.stopped || this.queued) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.stopped) return
+      try {
+        this.update()
+      } catch (error) {
+        this.stop()
+        throw error
+      }
+    })
+  }
+  private update() {
+    if (
+      !this.image.isLoaded ||
+      this.image.visibility !== 'visible' ||
+      this.image.tintColor ||
+      reducedMotion()
+    )
+      return this.remove()
+    const native = this.image.nativeViewProtected as UIImageView | undefined
+    if (!(native instanceof UIImageView) || !native.window) return this.remove()
+    if (
+      this.native &&
+      (this.native !== native ||
+        native.image !== null ||
+        this.image.imageSource !== this.source)
+    )
+      this.remove()
+    const source = this.original ?? native.image
+    if (
+      !source?.CGImage ||
+      source.images?.count ||
+      source.renderingMode === 2 /* AlwaysTemplate */
+    )
+      return this.remove()
+    if (source.size.width * source.size.height * source.scale ** 2 > 16_777_216)
+      return this.remove()
+    const bounds = native.bounds
+    if (
+      bounds.size.width <= 0 ||
+      bounds.size.height <= 0 ||
+      source.size.width <= 0 ||
+      source.size.height <= 0
+    )
+      return this.remove()
+    if (!this.renderer) {
+      // A paused SKView cannot draw its first frame. Keep the original visible
+      // until rendering can start, including source changes while paused.
+      if (this.pausedByUser || !this.active) return
+      this.create(native, source)
+    }
+    const renderer = this.renderer!
+    renderer.frame = CGRectMake(
+      bounds.origin.x,
+      bounds.origin.y,
+      bounds.size.width,
+      bounds.size.height,
+    )
+    this.scene!.size = CGSizeMake(bounds.size.width, bounds.size.height)
+    const iw = source.size.width
+    const ih = source.size.height
+    const { width, height } = bounds.size
+    const stretch = this.image.stretch
+    const scale =
+      stretch === 'aspectFill'
+        ? Math.max(width / iw, height / ih)
+        : Math.min(width / iw, height / ih)
+    this.sprite!.size = CGSizeMake(
+      stretch === 'fill' ? width : stretch === 'none' ? iw : iw * scale,
+      stretch === 'fill' ? height : stretch === 'none' ? ih : ih * scale,
+    )
+    this.sprite!.position = CGPointMake(width / 2, height / 2)
+    renderer.paused = this.pausedByUser || !this.active
+  }
+  private create(native: UIImageView, source: UIImage) {
+    const renderer = SKView.alloc().initWithFrame(native.bounds)
+    this.renderer = renderer
+    this.native = native
+    this.original = source
+    this.source = this.image.imageSource
+    renderer.opaque = false
+    renderer.backgroundColor = UIColor.clearColor
+    renderer.allowsTransparency = true
+    renderer.asynchronous = true
+    renderer.userInteractionEnabled = false
+    renderer.accessibilityElementsHidden = true
+    renderer.clipsToBounds = true
+    renderer.preferredFramesPerSecond = Math.min(
+      120,
+      native.window?.screen?.maximumFramesPerSecond ?? 60,
+    )
+    renderer.paused = true
+    const scene = SKScene.sceneWithSize(native.bounds.size)
+    this.scene = scene
+    scene.backgroundColor = UIColor.clearColor
+    scene.scaleMode = 3 // SKSceneScaleModeResizeFill
+    const texture = SKTexture.textureWithImage(source)
+    const sprite = SKSpriteNode.spriteNodeWithTexture(texture)
+    this.sprite = sprite
+    const warps: SKWarpGeometryGrid[] = []
+    const times: number[] = []
+    for (let step = 0; step <= steps; step++) {
+      const positions = liquidGrid(
+        columns,
+        rows,
+        step === steps ? 0 : step / steps,
+        this.settings.intensity,
+      )
+      warps.push(
+        SKWarpGeometryGrid.gridWithColumnsRowsSourcePositionsDestPositions(
+          columns,
+          rows,
+          null,
+          positions,
+        ),
+      )
+      times.push(((step / steps) * this.settings.duration) / 1000)
+    }
+    const loop = SKAction.animateWithWarpsTimes(warps, times)
+    if (!loop) throw new Error('Unable to create the liquid warp action.')
+    sprite.warpGeometry = SKWarpGeometryGrid.gridWithColumnsRows(columns, rows)
+    const entrance = SKAction.warpToDuration(
+      warps[0]!,
+      Math.min(0.35, this.settings.duration / 10000),
+    )
+    if (!entrance) throw new Error('Unable to create the liquid entrance.')
+    sprite.runActionWithKey(
+      SKAction.sequence([entrance, SKAction.repeatActionForever(loop)]),
+      key,
+    )
+    scene.addChild(sprite)
+    renderer.presentScene(scene)
+    native.addSubview(renderer)
+    native.image = null
+  }
+  private remove() {
+    const { renderer, sprite, native, original } = this
+    if (renderer) {
+      renderer.paused = true
+      sprite?.removeAllActions()
+      sprite?.removeFromParent()
+      renderer.presentScene(null)
+      renderer.removeFromSuperview()
+    }
+    if (
+      native &&
+      native.image === null &&
+      original &&
+      this.image.imageSource === this.source
+    ) {
+      native.image = original
+      // Core couldn't turn the suppressed UIImage into a template while it was
+      // hidden. Reapply its public native setter when a tint takes over.
+      if (this.image.tintColor)
+        (this.image as unknown as Record<symbol, (value: unknown) => void>)[
+          tintColorProperty.setNative
+        ]!(this.image.tintColor)
+    }
+    this.renderer = this.scene = this.sprite = this.native = this.original = undefined
+    this.source = undefined
+  }
+}

package/src/loader.ts

@@ -0,0 +1,202 @@
+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'
+
+export interface LoaderOptions {
+  /** Defaults to 'dots'. */
+  style?: LoaderStyle
+  /** A NativeScript color string. Defaults to '#71717a'. */
+  color?: string
+  /** Maximum width and height in DIPs, fitted inside the target. Defaults to 48. */
+  size?: number
+  /** Milliseconds per cycle. Defaults to 1200. */
+  duration?: number
+}
+
+const running = new WeakMap<View, () => void>()
+const key = 'jolt:loader'
+
+/**
+ * Adds a centered native iOS loading indicator. Returns an idempotent cleanup.
+ * Unloading releases native resources; loading resumes until explicitly stopped.
+ * Reduce Motion keeps the indicator static. Android is a no-op.
+ */
+export function loader(target: Target, options: LoaderOptions = {}): () => void {
+  const settings: Required<LoaderOptions> = {
+    style: options.style ?? 'dots',
+    color: options.color ?? '#71717a',
+    size: options.size ?? 48,
+    duration: options.duration ?? 1200,
+  }
+  if (!['dots', 'bars', 'ring'].includes(settings.style))
+    throw new TypeError('Unknown loader style.')
+  if (typeof settings.color !== 'string' || !Color.isValid(settings.color))
+    throw new TypeError('Loader color must be a valid color string.')
+  for (const name of ['size', 'duration'] as const)
+    if (!Number.isFinite(settings[name]) || settings[name] <= 0)
+      throw new RangeError(`Loader ${name} must be a positive finite number.`)
+  const view = toView(target)
+  running.get(view)?.()
+  if (!isIOS) return () => {}
+  return new Loader(view, settings).stop
+}
+
+class Loader {
+  private stopped = false
+  private queued = false
+  private waitingForLoad: boolean
+  private native: UIView | undefined
+  private layer: CAReplicatorLayer | undefined
+  private item: CALayer | undefined
+  private animating = false
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: View,
+    private readonly settings: Required<LoaderOptions>,
+  ) {
+    this.waitingForLoad = !view.isLoaded
+    running.set(view, this.stop)
+    view.on('loaded', this.loaded)
+    view.on('layoutChanged', this.schedule)
+    view.on('unloaded', this.unloaded)
+    this.schedule()
+  }
+
+  stop = () => {
+    if (this.stopped) return
+    this.stopped = true
+    this.view.off('loaded', this.loaded)
+    this.view.off('layoutChanged', this.schedule)
+    this.view.off('unloaded', this.unloaded)
+    if (running.get(this.view) === this.stop) running.delete(this.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
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.stopped) return
+      try {
+        this.update()
+      } catch (error) {
+        this.stop()
+        throw error
+      }
+    })
+  }
+
+  private update() {
+    if (this.waitingForLoad || !this.view.isLoaded) return
+    const native = this.view.nativeViewProtected as UIView | undefined
+    if (!native?.window) return this.remove()
+    const bounds = native.layer.bounds
+    const size = Math.min(this.settings.size, bounds.size.width, bounds.size.height)
+    if (size <= 0) return this.remove()
+    if (this.native && this.native !== native) this.remove()
+    this.observer ??= Application.ios.addNotificationObserver(
+      UIAccessibilityReduceMotionStatusDidChangeNotification,
+      this.schedule,
+    )
+
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      if (!this.layer) {
+        this.native = native
+        this.layer = CAReplicatorLayer.new()
+        this.layer.name = key
+        this.item = CALayer.new()
+        this.item.backgroundColor = new Color(this.settings.color).ios.CGColor
+        this.layer.addSublayer(this.item)
+        native.layer.addSublayer(this.layer)
+      }
+      const layer = this.layer
+      const item = this.item!
+      const { style, duration } = this.settings
+      layer.bounds = CGRectMake(0, 0, size, size)
+      layer.position = CGPointMake(
+        bounds.origin.x + bounds.size.width / 2,
+        bounds.origin.y + bounds.size.height / 2,
+      )
+      layer.instanceCount = style === 'dots' ? 3 : style === 'bars' ? 5 : 12
+      layer.instanceDelay = duration / 1000 / (style === 'ring' ? 12 : 5)
+      if (style === 'ring') {
+        const diameter = size * 0.16
+        item.bounds = CGRectMake(0, 0, diameter, diameter)
+        item.position = CGPointMake(size / 2, diameter / 2)
+        item.cornerRadius = diameter / 2
+        layer.instanceTransform = CATransform3DMakeRotation((2 * Math.PI) / 12, 0, 0, 1)
+      } else {
+        const width = size * (style === 'dots' ? 0.2 : 0.12)
+        const height = style === 'dots' ? width : size * 0.75
+        item.bounds = CGRectMake(0, 0, width, height)
+        item.position = CGPointMake(width / 2, size / 2)
+        item.cornerRadius = width / 2
+        layer.instanceTransform = CATransform3DMakeTranslation(
+          (size - width) / (layer.instanceCount - 1),
+          0,
+          0,
+        )
+      }
+      const reduced = reducedMotion()
+      item.opacity = style === 'ring' ? 0.35 : 1
+      if (reduced && this.animating) {
+        item.removeAnimationForKey(key)
+        this.animating = false
+      } else if (!reduced && !this.animating) {
+        const animation = CAKeyframeAnimation.animationWithKeyPath(
+          style === 'ring'
+            ? 'opacity'
+            : style === 'bars'
+              ? 'transform.scale.y'
+              : 'transform.scale',
+        )
+        animation.values = NSArray.arrayWithArray(
+          style === 'ring' ? [1, 0.2] : [0.35, 1, 0.35, 0.35],
+        )
+        animation.keyTimes = NSArray.arrayWithArray(
+          style === 'ring' ? [0, 1] : [0, 0.3, 0.6, 1],
+        )
+        animation.duration = duration / 1000
+        animation.repeatCount = Infinity
+        // Start one cycle in so every delayed copy is already participating.
+        animation.beginTime =
+          item.convertTimeFromLayer(CACurrentMediaTime(), null) - animation.duration
+        item.addAnimationForKey(animation, key)
+        this.animating = true
+      }
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private remove() {
+    this.item?.removeAnimationForKey(key)
+    this.layer?.removeFromSuperlayer()
+    this.item = this.layer = this.native = undefined
+    this.animating = false
+  }
+}