@rafaelaugusto/jolt 0.1.0-beta.5 → 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

@@ -5,6 +5,7 @@ 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,
@@ -50,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)!
@@ -104,6 +114,50 @@ export function createTrack(
   }
 }
 
+/** 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(
   property: ColorProperty,
   colors: readonly number[],
@@ -156,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++) {
@@ -201,6 +273,7 @@ function spring(
   [from, to]: readonly number[],
   curve: Extract<Curve, { type: 'spring' }>,
   velocity: number,
+  density: number,
 ): Motion {
   const motion = solveSpring(
     curve.physics,
@@ -209,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++) {
@@ -222,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))
@@ -245,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/types.ts

@@ -7,6 +7,10 @@ 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
@@ -41,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 }
@@ -66,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

package/src/vue/index.ts

@@ -0,0 +1,189 @@
+import {
+  BaseTransition,
+  defineComponent,
+  h,
+  type App,
+  type BaseTransitionProps,
+  type NSVElement,
+  type ObjectDirective,
+  type PropType,
+} from 'nativescript-vue'
+import {
+  animate,
+  press,
+  type AnimateOptions,
+  type Keyframes,
+  type PlaybackAnimation,
+  type PresetName,
+  type SpringName,
+} from '../index.js'
+
+type Host = NSVElement
+type Options = AnimateOptions | SpringName
+
+/** A preset name or keyframes, alone or paired with a transition. */
+export type AnimateValue =
+  PresetName | Keyframes | readonly [animation: PresetName | Keyframes, options?: Options]
+
+/** The pressed keyframes, alone or paired with a transition. */
+export type PressValue = Keyframes | readonly [pressed: Keyframes, options?: Options]
+
+export interface TransitionProps {
+  /** Played when the child is inserted. */
+  enter?: AnimateValue
+  /** Played before the child is removed. */
+  leave?: AnimateValue
+  /** Also play `enter` on the first render. */
+  appear?: boolean
+  mode?: 'in-out' | 'out-in' | 'default'
+}
+
+const animations = new WeakMap<object, PlaybackAnimation>()
+const removers = new WeakMap<object, () => void>()
+
+function split<T>(
+  value: T | readonly [T, Options?],
+): [animation: T, options: Options | undefined] {
+  return Array.isArray(value)
+    ? [value[0] as T, value[1] as Options | undefined]
+    : [value as T, undefined]
+}
+
+function same(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+    return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const keys = Object.keys(a)
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) =>
+      same((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
+    )
+  )
+}
+
+function play(el: Host, value: AnimateValue) {
+  const [animation, options] = split<PresetName | Keyframes>(value)
+  const handle = animate(el, animation, options)
+  animations.set(el, handle)
+  return handle
+}
+
+function cancel(el: Host) {
+  animations.get(el)?.stop()
+  animations.delete(el)
+}
+
+function attach(el: Host, value: PressValue | undefined) {
+  const [pressed, options] = value === undefined ? [] : split<Keyframes>(value)
+  removers.set(el, press(el, pressed, options))
+}
+
+/**
+ * Plays an animation when the element mounts, and again whenever the value changes.
+ *
+ * ```vue
+ * <Label v-animate="'fadeInUp'" />
+ * <Label v-animate="['popIn', { delay: 200 }]" />
+ * ```
+ */
+export const vAnimate: ObjectDirective<Host, AnimateValue> = {
+  mounted(el, { value }) {
+    play(el, value)
+  },
+  updated(el, { value, oldValue }) {
+    if (!same(value, oldValue)) play(el, value)
+  },
+  unmounted: cancel,
+}
+
+/**
+ * Press feedback while a finger is on the element.
+ *
+ * ```vue
+ * <GridLayout v-press />
+ * <GridLayout v-press="{ scale: 0.95 }" />
+ * ```
+ */
+export const vPress: ObjectDirective<Host, PressValue | undefined> = {
+  mounted(el, { value }) {
+    attach(el, value)
+  },
+  updated(el, { value, oldValue }) {
+    if (same(value, oldValue)) return
+    removers.get(el)?.()
+    attach(el, value)
+  },
+  unmounted(el) {
+    removers.get(el)?.()
+    removers.delete(el)
+  },
+}
+
+/** The hooks `JoltTransition` hands to Vue's `BaseTransition`. */
+export function transitionHooks(props: TransitionProps): BaseTransitionProps<Host> {
+  const run = (value: AnimateValue | undefined) => (el: Host, done: () => void) => {
+    if (value === undefined) {
+      done()
+      return
+    }
+    const handle = play(el, value)
+    void handle.finished.then(() => {
+      if (animations.get(el) === handle) animations.delete(el)
+      done()
+    })
+  }
+  const hooks: BaseTransitionProps<Host> = {
+    onEnter: run(props.enter),
+    onEnterCancelled: cancel,
+    onLeave: run(props.leave),
+    onLeaveCancelled: cancel,
+  }
+  if (props.appear) {
+    hooks.onAppear = hooks.onEnter
+    hooks.onAppearCancelled = cancel
+  }
+  return hooks
+}
+
+const value = {
+  type: [String, Object, Array] as PropType<AnimateValue>,
+  default: undefined,
+}
+
+/**
+ * Animates a child in and out. Vue keeps the element until the leave animation settles.
+ *
+ * ```vue
+ * <JoltTransition enter="popIn" leave="fadeOut">
+ *   <Label v-if="visible" text="Saved" />
+ * </JoltTransition>
+ * ```
+ */
+export const JoltTransition = defineComponent({
+  name: 'JoltTransition',
+  props: {
+    enter: value,
+    leave: value,
+    appear: Boolean,
+    mode: { type: String as PropType<TransitionProps['mode']>, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () =>
+      h(
+        BaseTransition,
+        { ...transitionHooks(props), mode: props.mode, appear: props.appear },
+        slots,
+      )
+  },
+})
+
+/** Registers `v-animate`, `v-press` and `JoltTransition` on the app. */
+export function install(app: App) {
+  app.directive('animate', vAnimate)
+  app.directive('press', vPress)
+  app.component('JoltTransition', JoltTransition)
+}
+
+export default { install }