@rafaelaugusto/jolt 0.1.0-beta.4 → 0.1.0-beta.6

package/src/text-layout.ts

@@ -1,6 +1,12 @@
 /** TextKit lays out the complete string before any glyphs are separated. */
 type Insets = { top: number; left: number; bottom: number; right: number }
 type NativeLabel = UILabel & { padding?: Insets; borderThickness?: Insets }
+/** The characters one piece draws, as UTF-16 offsets into the label text. */
+export interface TextPiece {
+  text: string
+  location: number
+  length: number
+}
 const MAX_PIECES = 256
 const MAX_PIXELS = 4_000_000
 
@@ -30,7 +36,7 @@ export function textLayer(native: NativeLabel, by: 'letter' | 'word') {
   if (native.adjustsFontSizeToFitWidth) return undefined
   const original = native.attributedText
   const text = original?.string ?? native.text ?? ''
-  if (!text.trim()) return { text, layer: undefined }
+  if (!text.trim()) return { text, layer: undefined, pieces: [] as TextPiece[] }
   const string = NSString.stringWithString(text)
   const full = { location: 0, length: string.length }
   const attributed = original
@@ -169,11 +175,17 @@ export function textLayer(native: NativeLabel, by: 'letter' | 'word') {
   )
   if (attachments) return undefined
   const shadowColor = native.shadowColor
+  const drawn: TextPiece[] = []
   try {
     native.shadowColor = null
     for (const { range, rect } of pieces) {
       const fragment = NSMutableAttributedString.alloc().initWithAttributedString(hidden)
       const characters = manager.characterRangeForGlyphRangeActualGlyphRange(range, null)
+      drawn.push({
+        text: string.substringWithRange(characters),
+        location: characters.location,
+        length: characters.length,
+      })
       attributed.enumerateAttributesInRangeOptionsUsingBlock(
         characters,
         0 as NSAttributedStringEnumerationOptions,
@@ -212,5 +224,5 @@ export function textLayer(native: NativeLabel, by: 'letter' | 'word') {
     else native.text = text
     native.shadowColor = shadowColor
   }
-  return { text, layer }
+  return { text, layer, pieces: drawn }
 }

package/src/text.ts

@@ -1,8 +1,10 @@
 import { stopIOSColorText } from './driver/ios-color.js'
-import { Application, Label, isIOS } from '@nativescript/core'
+import { Application, Label, Utils, isAndroid, isIOS } from '@nativescript/core'
 import { textProperty, formattedTextProperty } from '@nativescript/core/ui/text-base'
 import { toView } from './animate.js'
+import { reducedMotion, timeScale } from './config.js'
 import type { Animation } from './engine.js'
+import { completion, forgetCompletion, watchLabel } from './label.js'
 import { textLayer } from './text-layout.js'
 import type { Target } from './types.js'
 
@@ -20,34 +22,8 @@ export interface TextOptions {
 }
 type Options = Required<TextOptions>
 const running = new WeakMap<Label, TextAnimation>()
-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',
-]
 
-/** Reveals the text of an iOS Label without splitting its layout or accessibility element. */
+/** Reveals the text of a Label without splitting its layout or accessibility element. */
 export function animateText(target: Target, options: TextOptions = {}): Animation {
   const config: Options = {
     by: options.by ?? 'letter',
@@ -69,41 +45,14 @@ export function animateText(target: Target, options: TextOptions = {}): Animatio
   return new TextAnimation(view, config)
 }
 
-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: 'JoltTextAnimationDelegate' },
-    )
-  }
-  const delegate = Delegate.new()
-  callbacks.set(delegate, callback)
-  return delegate
-}
-
 class TextAnimation implements Animation {
   readonly finished: Promise<boolean>
   private resolve!: (finished: boolean) => void
-  private readonly formatted: Label['formattedText']
   private settled = false
   private queued = false
-  private native: UILabel | undefined
+  private native: UILabel | android.widget.TextView | undefined
+  private reveal: org.rafaelaugusto.jolt.TextReveal | undefined
+  private unwatch: (() => void) | undefined
   private bounds: CGRect | undefined
   private layer: CALayer | undefined
   private originalText: string | null = null
@@ -121,23 +70,19 @@ class TextAnimation implements Animation {
       this.resolve = resolve
     })
     if (isIOS) stopIOSColorText(view)
-    this.formatted = view.formattedText
     running.set(view, this)
-    if (!isIOS) {
+    if (!isIOS && !isAndroid) {
       this.end(false)
       return
     }
-    if (options.duration === 0 || UIAccessibilityIsReduceMotionEnabled()) {
+    if (options.duration === 0 || reducedMotion()) {
       this.end(true)
       return
     }
     view.on('loaded', this.schedule)
     view.on('layoutChanged', this.layoutChanged)
     view.on('unloaded', this.stop)
-    view.on('textChange', this.changed)
-    view.on('formattedTextChange', this.changed)
-    this.formatted?.on('propertyChange', this.changed)
-    for (const event of styleEvents) view.style.on(event, this.changed)
+    this.unwatch = watchLabel(view, this.changed)
     this.schedule()
   }
 
@@ -151,9 +96,14 @@ class TextAnimation implements Animation {
   stop = () => this.end(false)
   private changed = () => this.end(false, true)
   private motionChanged = () => {
-    if (UIAccessibilityIsReduceMotionEnabled()) this.end(true)
+    if (reducedMotion()) this.end(true)
   }
   private layoutChanged = () => {
+    if (isAndroid) {
+      if (!this.reveal) this.schedule()
+      else if (this.view.nativeViewProtected !== this.native) this.stop()
+      return
+    }
     const native = this.view.nativeViewProtected as UILabel | undefined
     const a = this.bounds
     const b = native?.bounds
@@ -176,7 +126,7 @@ class TextAnimation implements Animation {
     this.queued = true
     void Promise.resolve().then(() => {
       this.queued = false
-      if (this.settled || this.layer || !this.view.isLoaded) return
+      if (this.settled || this.layer || this.reveal || !this.view.isLoaded) return
       try {
         this.start()
       } catch {
@@ -185,21 +135,21 @@ class TextAnimation implements Animation {
     })
   }
   private start() {
-    if (this.options.duration === 0 || UIAccessibilityIsReduceMotionEnabled())
-      return this.end(true)
+    if (this.options.duration === 0 || reducedMotion()) return this.end(true)
     if (this.view.visibility !== 'visible') return this.end(false)
+    if (isAndroid) return this.startAndroid()
     const native = this.view.nativeViewProtected as UILabel | undefined
     if (!(native instanceof UILabel) || !native.window) return
     if (native.bounds.size.width <= 0 || native.bounds.size.height <= 0) return
     const prepared = textLayer(native, this.options.by)
     if (!prepared) return this.end(false)
     if (!prepared.layer?.sublayers?.count) return this.end(true)
+    const slowdown = 1 / timeScale()
+    const duration = this.options.duration * slowdown
+    const stagger = this.options.stagger * slowdown
+    const delay = this.options.delay * slowdown
     if (
-      !Number.isFinite(
-        this.options.delay +
-          this.options.duration +
-          (prepared.layer.sublayers.count - 1) * this.options.stagger,
-      )
+      !Number.isFinite(delay + duration + (prepared.layer.sublayers.count - 1) * stagger)
     )
       return this.end(false)
     this.native = native
@@ -209,7 +159,7 @@ class TextAnimation implements Animation {
     this.originalAttributed = native.attributedText
     this.accessibility = native.accessibilityLabel
     this.temporaryAccessibility = this.accessibility ?? prepared.text
-    const { duration, delay, stagger, y } = this.options
+    const { y } = this.options
     const start = CACurrentMediaTime()
     CATransaction.begin()
     CATransaction.setDisableActions(true)
@@ -247,24 +197,55 @@ class TextAnimation implements Animation {
       CATransaction.commit()
     }
   }
+  private startAndroid() {
+    const native = this.view.nativeViewProtected as android.widget.TextView | undefined
+    if (!(native instanceof android.widget.TextView)) return this.end(false)
+    const { by, duration, stagger, delay, y } = this.options
+    let reveal: org.rafaelaugusto.jolt.TextReveal
+    try {
+      reveal = new org.rafaelaugusto.jolt.TextReveal(
+        native,
+        by === 'word',
+        Math.round(duration),
+        Math.round(stagger),
+        Math.round(delay),
+        y * Utils.layout.getDisplayDensity(),
+        new org.rafaelaugusto.jolt.TextReveal.Callback({
+          onEnd: (finished: boolean) => {
+            if (this.reveal !== reveal) return
+            this.reveal = undefined
+            this.end(finished)
+          },
+        }),
+      )
+    } catch {
+      // A JS-only update cannot install the native plugin. Keep the label as it is.
+      return this.end(false)
+    }
+    if (!reveal.isSupported()) return this.end(false)
+    this.native = native
+    this.reveal = reveal
+    reveal.start()
+  }
   private end(finished: boolean, refresh = false) {
     if (this.settled) return
     this.settled = true
-    const { view, native, layer } = this
+    const { view, layer } = this
+    const native = this.native as UILabel | undefined
+    const reveal = this.reveal
+    this.reveal = undefined
+    reveal?.cancel()
     view.off('loaded', this.schedule)
     view.off('layoutChanged', this.layoutChanged)
     view.off('unloaded', this.stop)
-    view.off('textChange', this.changed)
-    view.off('formattedTextChange', this.changed)
-    this.formatted?.off('propertyChange', this.changed)
-    for (const event of styleEvents) view.style.off(event, this.changed)
+    this.unwatch?.()
     if (running.get(view) === this) running.delete(view)
     if (this.observer)
       Application.ios.removeNotificationObserver(
         this.observer,
         UIAccessibilityReduceMotionStatusDidChangeNotification,
       )
-    if (this.delegate) callbacks.delete(this.delegate)
+    if (this.delegate) forgetCompletion(this.delegate)
     if (native && layer) {
       CATransaction.begin()
       CATransaction.setDisableActions(true)

package/src/track.ts

@@ -1,9 +1,11 @@
+import { clampDecoration, isDecorationProperty } from './decoration.js'
 import { linear } from './easing.js'
 import { solveDecay } from './decay.js'
 import { precision, type Property } from './properties.js'
 import { solveSpring, springPhysics } from './spring.js'
 import type { Curve, ResolvedTransition } from './transition.js'
 import { colorMixer, isColorProperty, type ColorProperty } from './color.js'
+import { reducedMotion, timeScale } from './config.js'
 
 /**
  * One property animated over time. The curve is computed here and sampled,
@@ -49,13 +51,22 @@ export function createTrack(
   velocity: number,
 ): Track {
   if (isColorProperty(property)) return colorTrack(property, keyframes, transition)
-  const { curve, delay, repeat, reverse } = transition
-  const motion =
+  const { curve, repeat, reverse } = transition
+  if (property !== 'opacity' && reducedMotion())
+    return instantTrack(
+      property,
+      restingValue(property, keyframes, curve, repeat, reverse),
+    )
+  const slowdown = 1 / timeScale()
+  const delay = transition.delay * slowdown
+  const motion = slow(
     curve.type === 'spring'
-      ? spring(property, keyframes, curve, velocity)
+      ? spring(property, keyframes, curve, velocity * slowdown, slowdown)
       : curve.type === 'decay'
-        ? decay(property, keyframes[0]!, curve)
-        : tween(keyframes, curve)
+        ? decay(property, keyframes[0]!, curve, slowdown)
+        : tween(keyframes, curve, slowdown),
+    slowdown,
+  )
   const { duration } = motion
   const first = motion.values[0]!
   const last = motion.values.at(-1)!
@@ -72,7 +83,7 @@ export function createTrack(
     return reverse && iteration % 2 === 1 ? [duration - local, -1] : [local, 1]
   }
 
-  return {
+  const track: Track = {
     property,
     delay,
     duration,
@@ -94,6 +105,57 @@ export function createTrack(
       return motion.velocity(time) * direction
     },
   }
+  if (!isDecorationProperty(property)) return track
+  return {
+    ...track,
+    values: track.values.map((value) => clampDecoration(property, value)),
+    to: clampDecoration(property, track.to),
+    valueAt: (elapsed) => clampDecoration(property, track.valueAt(elapsed)),
+  }
+}
+
+/** Already at its end: the engine writes the value and plays nothing. */
+export function instantTrack(property: Property, value: number): Track {
+  const to = isDecorationProperty(property) ? clampDecoration(property, value) : value
+  return {
+    property,
+    delay: 0,
+    duration: 0,
+    repeat: 0,
+    reverse: false,
+    times: [0, 1],
+    values: [to, to],
+    to,
+    end: 0,
+    arrival: 0,
+    valueAt: () => to,
+    velocityAt: () => 0,
+  }
+}
+
+function restingValue(
+  property: Property,
+  keyframes: readonly number[],
+  curve: Curve,
+  repeat: number,
+  reverse: boolean,
+) {
+  const first = keyframes[0]!
+  if (!Number.isFinite(repeat) || (reverse && repeat % 2 === 1)) return first
+  if (curve.type !== 'decay') return keyframes.at(-1)!
+  const landing = solveDecay(
+    first,
+    curve.velocity,
+    curve.friction,
+    precision[property],
+  ).to
+  return curve.snap ? closest(curve.snap, landing) : landing
+}
+
+function closest(stops: readonly number[], target: number) {
+  return stops.reduce((best, stop) =>
+    Math.abs(stop - target) < Math.abs(best - target) ? stop : best,
+  )
 }
 
 function colorTrack(
@@ -148,28 +210,46 @@ function colorTrack(
   }
 }
 
+/** Plays the same trajectory over a longer or shorter time. */
+function slow(motion: Motion, factor: number): Motion {
+  if (factor === 1) return motion
+  return {
+    ...motion,
+    duration: motion.duration * factor,
+    position: (time) => motion.position(time / factor),
+    velocity: (time) => motion.velocity(time / factor) / factor,
+  }
+}
+
+/** Keyframes per second of playback, so slowed curves stay smooth. */
+function samples(duration: number, density: number) {
+  return Math.max(
+    1,
+    Math.min(
+      MAX_DECAY_SAMPLES,
+      Math.ceil(((duration * density) / 1000) * SAMPLES_PER_SECOND),
+    ),
+  )
+}
+
 function decay(
   property: Property,
   from: number,
   curve: Extract<Curve, { type: 'decay' }>,
+  density: number,
 ): Motion {
   const motion = solveDecay(from, curve.velocity, curve.friction, precision[property])
   if (curve.snap) {
-    const to = curve.snap.reduce((closest, stop) =>
-      Math.abs(stop - motion.to) < Math.abs(closest - motion.to) ? stop : closest,
-    )
     return spring(
       property,
-      [from, to],
+      [from, closest(curve.snap, motion.to)],
       { type: 'spring', physics: springPhysics({}), velocity: curve.velocity },
       0,
+      density,
     )
   }
 
-  const steps = Math.max(
-    1,
-    Math.min(MAX_DECAY_SAMPLES, Math.ceil((motion.duration / 1000) * SAMPLES_PER_SECOND)),
-  )
+  const steps = samples(motion.duration, density)
   const times: number[] = []
   const values: number[] = []
   for (let i = 0; i <= steps; i++) {
@@ -193,6 +273,7 @@ function spring(
   [from, to]: readonly number[],
   curve: Extract<Curve, { type: 'spring' }>,
   velocity: number,
+  density: number,
 ): Motion {
   const motion = solveSpring(
     curve.physics,
@@ -201,7 +282,7 @@ function spring(
     curve.velocity ?? velocity,
     precision[property],
   )
-  const steps = Math.max(1, Math.ceil((motion.duration / 1000) * SAMPLES_PER_SECOND))
+  const steps = samples(motion.duration, density)
   const times: number[] = []
   const values: number[] = []
   for (let i = 0; i <= steps; i++) {
@@ -214,6 +295,7 @@ function spring(
 function tween(
   keyframes: readonly number[],
   curve: Extract<Curve, { type: 'tween' }>,
+  density: number,
 ): Motion {
   const { duration, ease } = curve
   const offsets = curve.times ?? keyframes.map((_, i) => i / (keyframes.length - 1))
@@ -237,16 +319,7 @@ function tween(
     const from = keyframes[i]!
     const to = keyframes[i + 1]!
     const easing = ease[i]!
-    const steps =
-      easing === linear || from === to
-        ? 1
-        : Math.max(
-            1,
-            Math.min(
-              MAX_DECAY_SAMPLES,
-              Math.ceil(((span * duration) / 1000) * SAMPLES_PER_SECOND),
-            ),
-          )
+    const steps = easing === linear || from === to ? 1 : samples(span * duration, density)
     for (let step = 1; step <= steps; step++) {
       times.push(start + (span * step) / steps)
       values.push(step === steps ? to : from + (to - from) * easing(step / steps))

package/src/transition.ts

@@ -1,5 +1,6 @@
 import { resolveEasing, type Easing, type EasingFunction } from './easing.js'
 import type { Property } from './properties.js'
+import { isDecorationProperty } from './decoration.js'
 import { isColorProperty } from './color.js'
 import { springPhysics, type SpringPhysics } from './spring.js'
 
@@ -106,6 +107,7 @@ export function resolveTransition(
       : hasCurve(transition) ||
           property === 'opacity' ||
           isColorProperty(property) ||
+          isDecorationProperty(property) ||
           keyframes > 2
         ? 'tween'
         : 'spring')
@@ -135,7 +137,8 @@ export function resolveTransition(
   if (
     duration < 0 ||
     Number.isNaN(duration) ||
-    (isColorProperty(property) && !Number.isFinite(duration))
+    ((isColorProperty(property) || isDecorationProperty(property)) &&
+      !Number.isFinite(duration))
   ) {
     throw new RangeError(`Invalid duration: ${duration}.`)
   }

package/src/types.ts

@@ -7,10 +7,29 @@ import type { ColorKeyframes } from './color.js'
 export type KeyframeValue = number | readonly (number | null)[]
 
 export interface Keyframes {
+  /** One continuous SVG path, expressed as translation coordinates in DIPs. */
+  path?: string
+  /** Face the path's forward tangent (+X artwork). Requires path. */
+  orient?: boolean
   backgroundColor?: ColorKeyframes
   /** Uniform starting edge colors; widths and radii may differ. */
   borderColor?: ColorKeyframes
   color?: ColorKeyframes
+  /** Uniform circular corners, in DIPs. */
+  borderRadius?: KeyframeValue
+  /** Uniform visual border width, in DIPs. Content layout uses the final width. */
+  borderWidth?: KeyframeValue
+  /** iOS: opacity of one existing boxShadow, from 0 to 1. */
+  shadowOpacity?: KeyframeValue
+  /** iOS: native blur radius in DIPs (half Core's boxShadow blurRadius). */
+  shadowRadius?: KeyframeValue
+  /** iOS: offset of one existing boxShadow, in DIPs. */
+  shadowOffsetX?: KeyframeValue
+  shadowOffsetY?: KeyframeValue
+  /** Android: base elevation in DIPs. */
+  elevation?: KeyframeValue
+  /** Android: dynamic Z offset in DIPs. Native state changes may replace it. */
+  translationZ?: KeyframeValue
   opacity?: KeyframeValue
   /** Same as `translateX`, in DIPs. */
   x?: KeyframeValue
@@ -26,6 +45,9 @@ export interface Keyframes {
   rotateY?: KeyframeValue
 }
 
+/** Properties that can be timed or stopped independently. A path owns x/y and optionally rotate. */
+export type KeyframeProperty = Exclude<keyof Keyframes, 'path' | 'orient'>
+
 /** A view, or anything that holds one: a NativeScript-Vue element, an Angular `ElementRef`. */
 export type Target =
   View | { readonly nativeView: View } | { readonly nativeElement: View }
@@ -51,7 +73,7 @@ export interface Stagger {
 }
 
 export type AnimateOptions = Transition & {
-  [K in keyof Keyframes]?: Transition | SpringName
+  [K in KeyframeProperty | 'path']?: Transition | SpringName
 } & {
   /** Offset translations/rotations and multiply scale/opacity by their values at the start. */
   relative?: boolean