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

package/src/presets.ts

@@ -5,6 +5,9 @@ export interface Preset {
   transition: AnimateOptions
 }
 
+/** Add custom preset names through module augmentation, with `true` as each value. */
+export interface Presets {}
+
 const fadeIn = { duration: 300, ease: 'easeOut' } as const
 const fadeOut = { duration: 200, ease: 'easeIn' } as const
 const enter = { type: 'spring', duration: 500, bounce: 0 } as const
@@ -77,28 +80,30 @@ export const presets = {
 
   pulse: {
     keyframes: { scale: [1, 1.06, 1] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   bounce: {
     keyframes: { y: [0, -18, 0, -8, 0] },
     transition: {
       duration: 650,
+      relative: true,
       times: [0, 0.3, 0.6, 0.8, 1],
       ease: ['easeOut', 'easeIn', 'easeOut', 'easeIn'],
     },
   },
   shake: {
     keyframes: { x: [0, -10, 10, -8, 8, -4, 4, 0] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   wiggle: {
     keyframes: { rotate: [0, -8, 8, -5, 5, 0] },
-    transition: { duration: 500, ease: 'easeInOut' },
+    transition: { duration: 500, ease: 'easeInOut', relative: true },
   },
   heartbeat: {
     keyframes: { scale: [1, 1.15, 1, 1.15, 1, 1] },
     transition: {
       duration: 1000,
+      relative: true,
       times: [0, 0.14, 0.28, 0.42, 0.7, 1],
       ease: 'easeInOut',
     },
@@ -110,25 +115,44 @@ export const presets = {
     },
     transition: {
       duration: 800,
+      relative: true,
       times: [0, 0.3, 0.4, 0.5, 0.65, 0.75, 1],
       ease: 'easeInOut',
     },
   },
   flash: {
     keyframes: { opacity: [1, 0, 1, 0, 1] },
-    transition: { duration: 800, ease: 'easeInOut' },
+    transition: { duration: 800, ease: 'easeInOut', relative: true },
   },
   tada: {
     keyframes: {
       scale: [1, 0.9, 0.9, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1.1, 1],
       rotate: [0, -3, -3, 3, -3, 3, -3, 3, -3, 3, 0],
     },
-    transition: { duration: 1000, ease: 'easeInOut' },
+    transition: { duration: 1000, ease: 'easeInOut', relative: true },
   },
   spin: {
     keyframes: { rotate: [0, 360] },
-    transition: { duration: 1000, ease: 'linear' },
+    transition: { duration: 1000, ease: 'linear', relative: true },
   },
 } satisfies Record<string, Preset>
 
-export type PresetName = keyof typeof presets
+export type PresetName = keyof typeof presets | Extract<keyof Presets, string>
+
+const customPresets = new Map<string, Preset>()
+
+/** Registers a custom preset. Registering it again replaces it for future animations. */
+export function definePreset(name: PresetName, preset: Preset): void {
+  if (Object.hasOwn(presets, name)) {
+    throw new Error(`Preset "${name}" is built in and cannot be replaced.`)
+  }
+  customPresets.set(name, preset)
+}
+
+export function getPreset(name: PresetName): Preset {
+  const preset =
+    customPresets.get(name) ??
+    (Object.hasOwn(presets, name) ? presets[name as keyof typeof presets] : undefined)
+  if (!preset) throw new Error(`Unknown preset "${name}".`)
+  return preset
+}

package/src/press.ts

@@ -1,6 +1,8 @@
-import type { EventData, TouchGestureEventData } from '@nativescript/core'
-import { animate, toView } from './animate.js'
-import { isProperty, readValue, type Property } from './properties.js'
+import { Color, type EventData, type TouchGestureEventData } from '@nativescript/core'
+import { isColorProperty } from './color.js'
+import { animate, startingValues, toView } from './animate.js'
+import type { PlaybackAnimation } from './playback.js'
+import { readValue } from './properties.js'
 import type { SpringName, Transition } from './transition.js'
 import type { AnimateOptions, Keyframes, Target } from './types.js'
 
@@ -22,22 +24,42 @@ export function press(
   options?: AnimateOptions | SpringName,
 ): () => void {
   const view = toView(target)
-  const properties = Object.keys(pressed).flatMap((key): Property[] =>
-    key === 'scale' ? ['scaleX', 'scaleY'] : isProperty(key) ? [key] : [],
-  )
+  const properties = [...startingValues(pressed, options).keys()]
   let rest: Keyframes | undefined
+  let active: PlaybackAnimation | undefined
 
   const onTouch = (event: EventData) => {
     const { action } = event as TouchGestureEventData
     if (action === 'down' && !rest && view.isEnabled !== false) {
-      rest = Object.fromEntries(properties.map((p) => [p, readValue(view, p)]))
-      animate(view, pressed, options ?? pressIn)
+      rest = Object.fromEntries(
+        properties.map((p) => [
+          p,
+          isColorProperty(p) ? new Color(readValue(view, p)) : readValue(view, p),
+        ]),
+      )
+      active = animate(view, pressed, options ?? pressIn)
     } else if ((action === 'up' || action === 'cancel') && rest) {
-      animate(view, rest, options ?? release)
+      active = animate(
+        view,
+        rest,
+        typeof options === 'object'
+          ? { ...options, relative: false }
+          : (options ?? release),
+      )
       rest = undefined
     }
   }
 
+  const cancel = () => {
+    active?.stop()
+    active = undefined
+    rest = undefined
+  }
   view.on('touch', onTouch)
-  return () => view.off('touch', onTouch)
+  view.on('unloaded', cancel)
+  return () => {
+    view.off('touch', onTouch)
+    view.off('unloaded', cancel)
+    cancel()
+  }
 }

package/src/properties.ts

@@ -1,7 +1,15 @@
-import type { View } from '@nativescript/core'
+import { Color, type View } from '@nativescript/core'
+import {
+  isDecorationProperty,
+  readDecoration,
+  writeDecoration,
+  type DecorationProperty,
+} from './decoration.js'
+import { isColorProperty, readColor, type ColorProperty } from './color.js'
 
-export type Property =
+export type NumericProperty =
   'opacity' | 'x' | 'y' | 'scaleX' | 'scaleY' | 'rotate' | 'rotateX' | 'rotateY'
+export type Property = NumericProperty | ColorProperty | DecorationProperty
 
 const viewKeys = {
   opacity: 'opacity',
@@ -12,9 +20,9 @@ const viewKeys = {
   rotate: 'rotate',
   rotateX: 'rotateX',
   rotateY: 'rotateY',
-} as const satisfies Record<Property, keyof View>
+} as const satisfies Record<NumericProperty, keyof View>
 
-const defaults: Record<Property, number> = {
+const defaults: Record<NumericProperty, number> = {
   opacity: 1,
   x: 0,
   y: 0,
@@ -25,8 +33,19 @@ const defaults: Record<Property, number> = {
   rotateY: 0,
 }
 
-/** How close to its target a spring has to be to count as settled. */
+/** How close to its target a spring or decay has to be to count as settled. */
 export const precision: Record<Property, number> = {
+  borderRadius: 0.1,
+  borderWidth: 0.1,
+  shadowOpacity: 0.002,
+  shadowRadius: 0.1,
+  shadowOffsetX: 0.1,
+  shadowOffsetY: 0.1,
+  elevation: 0.1,
+  translationZ: 0.1,
+  backgroundColor: 0.002,
+  borderColor: 0.002,
+  color: 0.002,
   opacity: 0.002,
   x: 0.25,
   y: 0.25,
@@ -38,14 +57,21 @@ export const precision: Record<Property, number> = {
 }
 
 export function isProperty(key: string): key is Property {
-  return key in viewKeys
+  return Object.hasOwn(viewKeys, key) || isColorProperty(key) || isDecorationProperty(key)
 }
 
 export function readValue(view: View, property: Property): number {
+  if (isColorProperty(property)) return readColor(view, property)
+  if (isDecorationProperty(property)) return readDecoration(view, property)
   const value = view[viewKeys[property]]
   return typeof value === 'number' && !Number.isNaN(value) ? value : defaults[property]
 }
 
 export function writeValue(view: View, property: Property, value: number) {
+  if (isColorProperty(property)) {
+    view[property] = new Color(value)
+    return
+  }
+  if (isDecorationProperty(property)) return writeDecoration(view, property, value)
   view[viewKeys[property]] = value
 }

package/src/reveal.ts

@@ -0,0 +1,374 @@
+import { Application, isIOS, type View } from '@nativescript/core'
+import { toView } from './animate.js'
+import { resolveEasing } from './easing.js'
+import type { Animation } from './engine.js'
+import type { Target } from './types.js'
+import { reducedMotion } from './config.js'
+
+export interface RevealOptions {
+  /** Circle origin in DIPs from the target's top-left corner. Defaults to its center. */
+  from?: { x: number; y: number }
+  /** Milliseconds. Defaults to 400; zero changes visibility immediately. */
+  duration?: number
+}
+
+export interface ConcealOptions {
+  /** Circle destination in DIPs from the target's top-left corner. Defaults to its center. */
+  to?: { x: number; y: number }
+  /** Milliseconds. Defaults to 400; zero changes visibility immediately. */
+  duration?: number
+}
+
+type Circle = { x: number; y: number; radius: number }
+type MaskedView = UIView & { originalMask?: CALayer | null; maskType?: unknown }
+type Snapshot = { circle: Circle; native: UIView; bounds: CGRect }
+const running = new WeakMap<View, CircularAnimation>()
+const callbacks = new WeakMap<NSObject, (finished: boolean) => void>()
+const ease = resolveEasing('easeInOut')
+const key = 'jolt:reveal'
+let Delegate: typeof NSObject | undefined
+
+/** Reveals an iOS view through an expanding circle, then removes the temporary mask. */
+export function reveal(target: Target, options: RevealOptions = {}): Animation {
+  return start(target, true, options.from, options.duration ?? 400)
+}
+
+/** Contracts an iOS view to a point, then sets visibility to 'hidden' without collapsing layout. */
+export function conceal(target: Target, options: ConcealOptions = {}): Animation {
+  return start(target, false, options.to, options.duration ?? 400)
+}
+
+function start(
+  target: Target,
+  opening: boolean,
+  point: { x: number; y: number } | undefined,
+  duration: number,
+): Animation {
+  if (!Number.isFinite(duration) || duration < 0)
+    throw new RangeError('Reveal duration must be a nonnegative finite number.')
+  if (
+    point !== undefined &&
+    (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y))
+  )
+    throw new TypeError('Reveal origin must have finite x and y coordinates.')
+  const view = toView(target)
+  const previous = running.get(view)
+  const snapshot = previous?.snapshot()
+  const original = previous?.originalVisibility ?? view.visibility
+  previous?.stop()
+  return new CircularAnimation(
+    view,
+    opening,
+    point && { ...point },
+    duration,
+    original,
+    snapshot,
+  )
+}
+
+function sameBounds(a: CGRect, b: CGRect) {
+  return (
+    a.origin.x === b.origin.x &&
+    a.origin.y === b.origin.y &&
+    a.size.width === b.size.width &&
+    a.size.height === b.size.height
+  )
+}
+
+function path(circle: Circle): CAShapeLayer['path'] {
+  // Keep the same oval topology even at the closed endpoint.
+  const radius = Math.max(0.01, circle.radius)
+  return UIBezierPath.bezierPathWithOvalInRect(
+    CGRectMake(circle.x - radius, circle.y - radius, radius * 2, radius * 2),
+  ).CGPath
+}
+
+function completion(
+  callback: (finished: boolean) => void,
+): NSObject & CAAnimationDelegate {
+  if (!Delegate) {
+    // Use the runtime subclass API so published JS needs no NativeClass transform.
+    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: 'JoltCircularRevealDelegate' },
+    )
+  }
+  const delegate = Delegate.new()
+  callbacks.set(delegate, callback)
+  return delegate
+}
+
+class CircularAnimation implements Animation {
+  readonly finished: Promise<boolean>
+  private resolve!: (finished: boolean) => void
+  private settled = false
+  private queued = false
+  private changingVisibility = false
+  private waitingForLoad: boolean
+  private native: MaskedView | undefined
+  private bounds: CGRect | undefined
+  private wrapper: CALayer | undefined
+  private shape: CAShapeLayer | undefined
+  private originalMask: CALayer | null = null
+  private savedMask: CALayer | null = null
+  private delegate: NSObject | undefined
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+  private from: Circle | undefined
+  private to: Circle | undefined
+  private startedAt = 0
+
+  constructor(
+    private readonly view: View,
+    private readonly opening: boolean,
+    private readonly point: { x: number; y: number } | undefined,
+    private readonly duration: number,
+    readonly originalVisibility: View['visibility'],
+    private readonly inherited?: Snapshot,
+  ) {
+    this.finished = new Promise((resolve) => {
+      this.resolve = resolve
+    })
+    this.waitingForLoad = !view.isLoaded
+    running.set(view, this)
+    if (!isIOS) {
+      this.end(false)
+      return
+    }
+    view.on('loaded', this.loaded)
+    view.on('layoutChanged', this.layoutChanged)
+    view.on('unloaded', this.stop)
+    view.style.on('backgroundInternalChange', this.stop)
+    view.style.on('visibilityChange', this.visibilityChanged)
+    if (opening && view.visibility === 'collapse') this.visibility('hidden')
+    this.schedule()
+  }
+
+  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)
+  }
+
+  /** Cancels and restores visibility from before the interrupted reveal/conceal chain. */
+  stop = () => this.end(false)
+
+  snapshot(): Snapshot | undefined {
+    if (!this.shape || !this.native || !this.bounds || !this.from || !this.to) return
+    const presented = this.shape.presentationLayer() as CAShapeLayer | null
+    let circle: Circle
+    if (presented?.path) {
+      const box = CGPathGetBoundingBox(presented.path)
+      circle = {
+        x: box.origin.x + box.size.width / 2,
+        y: box.origin.y + box.size.height / 2,
+        radius: box.size.width / 2,
+      }
+    } else {
+      const progress = ease(
+        Math.max(
+          0,
+          Math.min(1, ((CACurrentMediaTime() - this.startedAt) * 1000) / this.duration),
+        ),
+      )
+      const lerp = (a: number, b: number) => a + (b - a) * progress
+      circle = {
+        x: lerp(this.from.x, this.to.x),
+        y: lerp(this.from.y, this.to.y),
+        radius: lerp(this.from.radius, this.to.radius),
+      }
+    }
+    return { circle, native: this.native, bounds: this.bounds }
+  }
+
+  private visibility(value: View['visibility']) {
+    this.changingVisibility = true
+    try {
+      this.view.visibility = value
+    } finally {
+      this.changingVisibility = false
+    }
+  }
+
+  private visibilityChanged = () => {
+    if (!this.changingVisibility) this.end(false, true)
+  }
+
+  private loaded = () => {
+    this.waitingForLoad = false
+    this.schedule()
+  }
+
+  private layoutChanged = () => {
+    if (this.shape) {
+      const native = this.view.nativeViewProtected as UIView | undefined
+      if (
+        native !== this.native ||
+        !native?.window ||
+        !sameBounds(native.layer.bounds, this.bounds!)
+      ) {
+        this.stop()
+        return
+      }
+    }
+    this.schedule()
+  }
+
+  private schedule = () => {
+    if (this.settled || this.queued) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.settled) return
+      try {
+        this.update()
+      } catch (error) {
+        this.stop()
+        throw error
+      }
+    })
+  }
+
+  private motionChanged = () => {
+    if (reducedMotion()) this.end(true)
+  }
+
+  private update() {
+    if (!this.opening && !this.inherited && this.view.visibility !== 'visible')
+      return this.end(true, true)
+    if (this.duration === 0 || reducedMotion()) return this.end(true)
+    if (this.waitingForLoad || !this.view.isLoaded) return
+    const native = this.view.nativeViewProtected as MaskedView | undefined
+    if (this.shape) {
+      if (native !== this.native || native?.layer.mask !== this.wrapper) this.stop()
+      return
+    }
+    if (!native?.window) return
+    const bounds = native.layer.bounds
+    if (bounds.size.width <= 0 || bounds.size.height <= 0) return
+    const inherited =
+      this.inherited?.native === native && sameBounds(this.inherited.bounds, bounds)
+        ? this.inherited.circle
+        : undefined
+    const x = this.point
+      ? bounds.origin.x + this.point.x
+      : (inherited?.x ?? bounds.origin.x + bounds.size.width / 2)
+    const y = this.point
+      ? bounds.origin.y + this.point.y
+      : (inherited?.y ?? bounds.origin.y + bounds.size.height / 2)
+    const radius =
+      Math.hypot(
+        Math.max(
+          Math.abs(x - bounds.origin.x),
+          Math.abs(x - bounds.origin.x - bounds.size.width),
+        ),
+        Math.max(
+          Math.abs(y - bounds.origin.y),
+          Math.abs(y - bounds.origin.y - bounds.size.height),
+        ),
+      ) + 1
+    this.from = inherited ?? { x, y, radius: this.opening ? 0 : radius }
+    this.to = { x, y, radius: this.opening ? radius : 0 }
+    this.native = native
+    this.bounds = bounds
+    this.originalMask = native.layer.mask
+    this.savedMask =
+      native.maskType != null ? (native.originalMask ?? null) : this.originalMask
+
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      // A plain container prevents Core from mistaking our circle for its own clip path.
+      const wrapper = (this.wrapper = CALayer.new())
+      const shape = (this.shape = CAShapeLayer.new())
+      wrapper.name = key
+      for (const layer of [wrapper, shape]) {
+        layer.bounds = bounds
+        layer.position = CGPointMake(
+          bounds.origin.x + bounds.size.width / 2,
+          bounds.origin.y + bounds.size.height / 2,
+        )
+      }
+      shape.fillColor = UIColor.blackColor.CGColor
+      shape.path = path(this.to)
+      wrapper.addSublayer(shape)
+      // Same coordinate space as the original host, including bounds origins.
+      native.layer.mask = null
+      wrapper.mask = this.originalMask
+      native.layer.mask = wrapper
+      const animation = CABasicAnimation.animationWithKeyPath('path')
+      animation.fromValue = path(this.from)
+      animation.toValue = shape.path
+      animation.duration = this.duration / 1000
+      animation.timingFunction = CAMediaTimingFunction.functionWithName(
+        kCAMediaTimingFunctionEaseInEaseOut,
+      )
+      this.delegate = animation.delegate = completion((finished) => this.end(finished))
+      this.startedAt = CACurrentMediaTime()
+      shape.addAnimationForKey(animation, key)
+      this.observer = Application.ios.addNotificationObserver(
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+        this.motionChanged,
+      )
+      this.visibility('visible')
+    } finally {
+      CATransaction.commit()
+    }
+  }
+
+  private end(finished: boolean, keepVisibility = false) {
+    if (this.settled) return
+    this.settled = true
+    const { view, native, wrapper, shape } = this
+    view.off('loaded', this.loaded)
+    view.off('layoutChanged', this.layoutChanged)
+    view.off('unloaded', this.stop)
+    view.style.off('backgroundInternalChange', this.stop)
+    view.style.off('visibilityChange', this.visibilityChanged)
+    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 (native && wrapper) {
+      CATransaction.begin()
+      CATransaction.setDisableActions(true)
+      try {
+        // Hide before removing a closed mask so conceal never flashes its content.
+        if (!keepVisibility)
+          this.visibility(
+            finished ? (this.opening ? 'visible' : 'hidden') : this.originalVisibility,
+          )
+        shape?.removeAnimationForKey(key)
+        wrapper.mask = null
+        if (native.layer.mask === wrapper) native.layer.mask = this.originalMask
+        // Core can save the temporary mask while installing a new clip/border mask.
+        if (native.originalMask === wrapper) native.originalMask = this.savedMask
+      } finally {
+        CATransaction.commit()
+      }
+    } else if (isIOS && !keepVisibility) {
+      this.visibility(
+        finished ? (this.opening ? 'visible' : 'hidden') : this.originalVisibility,
+      )
+    }
+    this.native = this.wrapper = this.shape = this.delegate = this.observer = undefined
+    this.resolve(finished)
+  }
+}

package/src/roll-diff.ts

@@ -0,0 +1,57 @@
+export interface Grapheme {
+  text: string
+  /** UTF-16 offsets, the units NSString locations and Java char indices use. */
+  start: number
+  end: number
+}
+
+export interface RollChange {
+  /** The grapheme that rolls in, placed in the new text. */
+  next: Grapheme
+  /** The grapheme it replaces at the same position from the end, when there is one. */
+  previous: Grapheme | undefined
+}
+
+export interface RollDiff {
+  /** Positions that differ, from the last one backwards. */
+  changes: RollChange[]
+  /** Old graphemes to the left of the new text's first one; they roll out alone. */
+  removed: Grapheme[]
+}
+
+const segmenter =
+  typeof Intl !== 'undefined' && 'Segmenter' in Intl
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : undefined
+
+export function graphemes(text: string): Grapheme[] {
+  if (segmenter)
+    return [...segmenter.segment(text)].map(({ segment, index }) => ({
+      text: segment,
+      start: index,
+      end: index + segment.length,
+    }))
+  const pieces: Grapheme[] = []
+  let offset = 0
+  for (const character of text) {
+    pieces.push({ text: character, start: offset, end: offset + character.length })
+    offset += character.length
+  }
+  return pieces
+}
+
+/** Aligns both texts on their last grapheme, so the units digit stays put when the count grows. */
+export function diffFromEnd(previous: string, next: string): RollDiff {
+  const before = graphemes(previous)
+  const after = graphemes(next)
+  const changes: RollChange[] = []
+  const removed: Grapheme[] = []
+  const count = Math.max(before.length, after.length)
+  for (let offset = 1; offset <= count; offset++) {
+    const old = before[before.length - offset]
+    const piece = after[after.length - offset]
+    if (!piece) removed.push(old!)
+    else if (!old || old.text !== piece.text) changes.push({ next: piece, previous: old })
+  }
+  return { changes, removed }
+}