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

package/src/driver/android-gradient.ts

@@ -0,0 +1,109 @@
+import { Utils, type View } from '@nativescript/core'
+import type { GradientFrame, GradientPainter, GradientType } from '../gradient.js'
+
+const floats = (values: readonly number[]) => {
+  const array = Array.create('float', values.length)
+  values.forEach((value, i) => (array[i] = value))
+  return array
+}
+const ints = (values: readonly number[]) => {
+  const array = Array.create('int', values.length)
+  values.forEach((value, i) => (array[i] = value | 0))
+  return array
+}
+
+/** A gradient drawable stacked on the view's own background: above its color, below its children. */
+export function androidGradient(
+  view: View,
+  type: GradientType,
+): GradientPainter | undefined {
+  let layer: org.rafaelaugusto.jolt.GradientLayer
+  try {
+    layer = new org.rafaelaugusto.jolt.GradientLayer(
+      type === 'linear' ? 0 : type === 'radial' ? 1 : 2,
+    )
+  } catch {
+    // A JS-only update cannot install the native plugin.
+    return undefined
+  }
+  let stack: android.graphics.drawable.LayerDrawable | undefined
+  let queued = false
+
+  const wrap = () => {
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (!native) return
+    const corner = typeof view.borderRadius === 'number' ? view.borderRadius : 0
+    layer.setCorner(corner * Utils.layout.getDisplayDensity())
+    const background = native.getBackground()
+    if (stack && background === stack) return
+    const layers = Array.create(android.graphics.drawable.Drawable, 2)
+    layers[0] = background ?? new android.graphics.drawable.ColorDrawable(0)
+    layers[1] = layer
+    stack = new android.graphics.drawable.LayerDrawable(layers)
+    native.setBackground(stack)
+  }
+  // Core replaces the background drawable when its style changes; stack on the new one.
+  const rewrap = () => {
+    if (queued) return
+    queued = true
+    void Promise.resolve().then(() => {
+      queued = false
+      wrap()
+    })
+  }
+  view.on('loaded', wrap)
+  view.style.on('backgroundInternalChange', rewrap)
+  view.style.on('borderTopLeftRadiusChange', rewrap)
+  wrap()
+
+  return {
+    paint(frame: GradientFrame) {
+      layer.paint(
+        ints(frame.colors),
+        floats(frame.stops),
+        frame.angle,
+        frame.x,
+        frame.y,
+        frame.radius,
+      )
+    },
+    play(frames, times, timing, onEnd) {
+      let active = true
+      layer.play(
+        floats(times),
+        ints(frames.flatMap((frame) => frame.colors)),
+        floats(frames.flatMap((frame) => frame.stops)),
+        floats(frames.flatMap((frame) => [frame.angle, frame.x, frame.y, frame.radius])),
+        Math.round(timing.duration),
+        Math.round(timing.delay),
+        timing.repeat === Infinity ? -1 : timing.repeat,
+        timing.reverse,
+        new org.rafaelaugusto.jolt.GradientLayer.Listener({
+          onEnd: (finished: boolean) => {
+            if (!active) return
+            active = false
+            onEnd(finished)
+          },
+        }),
+      )
+      return {
+        cancel() {
+          if (!active) return
+          active = false
+          layer.cancel()
+          onEnd(false)
+        },
+      }
+    },
+    remove() {
+      view.off('loaded', wrap)
+      view.style.off('backgroundInternalChange', rewrap)
+      view.style.off('borderTopLeftRadiusChange', rewrap)
+      layer.cancel()
+      const native = view.nativeViewProtected as android.view.View | undefined
+      if (native && stack && native.getBackground() === stack)
+        native.setBackground(stack.getDrawable(0))
+      stack = undefined
+    },
+  }
+}

package/src/driver/ios-gradient.ts

@@ -0,0 +1,114 @@
+import { Color, type View } from '@nativescript/core'
+import {
+  gradientPoints,
+  type GradientFrame,
+  type GradientPainter,
+  type GradientType,
+} from '../gradient.js'
+
+const keys = ['colors', 'locations', 'startPoint', 'endPoint'] as const
+
+/** A CAGradientLayer at the back of the view's layer: above its background, below its children. */
+export function iosGradient(view: View, type: GradientType): GradientPainter {
+  const layer = CAGradientLayer.new()
+  layer.type =
+    type === 'linear'
+      ? kCAGradientLayerAxial
+      : type === 'radial'
+        ? kCAGradientLayerRadial
+        : kCAGradientLayerConic
+  let current: GradientFrame | undefined
+  let generation = 0
+
+  const native = () => view.nativeViewProtected as UIView | undefined
+  const size = () => {
+    const bounds = native()?.layer.bounds
+    return { width: bounds?.size.width ?? 0, height: bounds?.size.height ?? 0 }
+  }
+  const values = (frame: GradientFrame) => {
+    const { width, height } = size()
+    const { start, end: toward } = gradientPoints(type, frame, width, height)
+    // Core Animation starts a conic gradient on the side opposite its end point.
+    const end =
+      type === 'conic' ? { x: 2 * start.x - toward.x, y: 2 * start.y - toward.y } : toward
+    return {
+      colors: NSArray.arrayWithArray(
+        frame.colors.map((argb) => new Color(argb).ios.CGColor),
+      ),
+      locations: NSArray.arrayWithArray(frame.stops),
+      startPoint: NSValue.valueWithCGPoint(CGPointMake(start.x, start.y)),
+      endPoint: NSValue.valueWithCGPoint(CGPointMake(end.x, end.y)),
+    }
+  }
+  const attach = () => {
+    const host = native()
+    if (!host) return
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    if (layer.superlayer !== host.layer) host.layer.insertSublayerAtIndex(layer, 0)
+    layer.frame = host.layer.bounds
+    layer.cornerRadius = host.layer.cornerRadius
+    if (current) {
+      const model = values(current)
+      layer.colors = model.colors
+      layer.locations = model.locations
+      layer.startPoint = model.startPoint.CGPointValue
+      layer.endPoint = model.endPoint.CGPointValue
+    }
+    CATransaction.commit()
+  }
+  view.on('loaded', attach)
+  view.on('layoutChanged', attach)
+
+  return {
+    paint(frame) {
+      current = frame
+      generation++
+      for (const key of keys) layer.removeAnimationForKey(`jolt:gradient:${key}`)
+      attach()
+    },
+    play(frames, times, timing, onEnd) {
+      const instance = ++generation
+      current = frames[frames.length - 1]!
+      attach()
+      const sampled = frames.map(values)
+      const now = CACurrentMediaTime()
+      CATransaction.begin()
+      if (timing.repeat !== Infinity)
+        CATransaction.setCompletionBlock(() => {
+          if (instance === generation) onEnd(true)
+        })
+      for (const key of keys) {
+        const animation = CAKeyframeAnimation.animationWithKeyPath(key)
+        animation.values = NSArray.arrayWithArray(sampled.map((value) => value[key]))
+        animation.keyTimes = NSArray.arrayWithArray(times as number[])
+        animation.duration = Math.max(timing.duration, 1) / 1000
+        animation.beginTime = layer.convertTimeFromLayer(now + timing.delay / 1000, null)
+        animation.fillMode = kCAFillModeBackwards
+        if (timing.repeat > 0) {
+          animation.autoreverses = timing.reverse
+          animation.repeatCount = timing.reverse
+            ? (timing.repeat + 1) / 2
+            : timing.repeat + 1
+        }
+        layer.addAnimationForKey(animation, `jolt:gradient:${key}`)
+      }
+      CATransaction.commit()
+      return {
+        cancel() {
+          if (instance !== generation) return
+          generation++
+          for (const key of keys) layer.removeAnimationForKey(`jolt:gradient:${key}`)
+          onEnd(false)
+        },
+      }
+    },
+    remove() {
+      generation++
+      view.off('loaded', attach)
+      view.off('layoutChanged', attach)
+      layer.removeAllAnimations()
+      layer.removeFromSuperlayer()
+    },
+  }
+}

package/src/gradient.ts

@@ -0,0 +1,372 @@
+import { isAndroid, isIOS, type View } from '@nativescript/core'
+import { toView } from './animate.js'
+import { colorMixer, parseColor, type ColorValue } from './color.js'
+import { reducedMotion } from './config.js'
+import { getDriver } from './driver/index.js'
+import { androidGradient } from './driver/android-gradient.js'
+import { iosGradient } from './driver/ios-gradient.js'
+import type { Animation } from './engine.js'
+import { createTrack, type Track } from './track.js'
+import {
+  resolveTransition,
+  springs,
+  type SpringName,
+  type Transition,
+} from './transition.js'
+import type { Target } from './types.js'
+
+export type GradientType = 'linear' | 'radial' | 'conic'
+
+export interface GradientValues {
+  /** Two to eight colors. Animating keeps the count. */
+  colors?: readonly ColorValue[]
+  /** Where each color sits, from 0 to 1. Evenly spaced by default. */
+  stops?: readonly number[]
+  /** Degrees, like CSS: `linear` points this way (180 runs top to bottom), `conic` starts here (0 is up). */
+  angle?: number
+  /** `radial` and `conic`: the center, in fractions of the view's width and height. */
+  center?: { readonly x: number; readonly y: number }
+  /** `radial`: the radius, in fractions of the view's shorter side. */
+  radius?: number
+}
+
+export interface GradientOptions extends GradientValues {
+  type: GradientType
+  colors: readonly ColorValue[]
+}
+
+export interface Gradient {
+  readonly type: GradientType
+  /** Animates to new values from the ones on screen. Colors and stops keep their count. */
+  animate(values: GradientValues, transition?: Transition | SpringName): Animation
+  /** Applies values at once, stopping the animation in progress. */
+  set(values: GradientValues): void
+  /** Stops the animation in progress where it is. */
+  stop(): void
+  /** Takes the gradient off the view. */
+  remove(): void
+}
+
+/** Everything the platform needs to paint one frame. */
+export interface GradientFrame {
+  colors: number[]
+  stops: number[]
+  angle: number
+  x: number
+  y: number
+  radius: number
+}
+
+export interface GradientTiming {
+  duration: number
+  delay: number
+  repeat: number
+  reverse: boolean
+}
+
+export interface GradientPainter {
+  paint(frame: GradientFrame): void
+  /** Plays sampled frames natively; `onEnd(false)` when cancelled. */
+  play(
+    frames: readonly GradientFrame[],
+    times: readonly number[],
+    timing: GradientTiming,
+    onEnd: (finished: boolean) => void,
+  ): { cancel(): void }
+  remove(): void
+}
+
+type PainterFactory = (view: View, type: GradientType) => GradientPainter | undefined
+
+let factory: PainterFactory | undefined
+
+/** Test seam, like `setDriver`. */
+export function setGradientPainter(next: PainterFactory | undefined) {
+  factory = next
+}
+
+function platformPainter(view: View, type: GradientType) {
+  if (isIOS) return iosGradient(view, type)
+  if (isAndroid) return androidGradient(view, type)
+  return undefined
+}
+
+const types: readonly GradientType[] = ['linear', 'radial', 'conic']
+
+/**
+ * Paints a native gradient behind a layout's children and animates it.
+ *
+ * ```ts
+ * const glow = gradient(halo, { type: 'radial', colors: ['#FF0080', '#7928CA00'], radius: 0.8 })
+ * glow.animate({ center: { x: 0.8, y: 0.2 }, radius: 1.2 }, { duration: 2000 })
+ * ```
+ */
+export function gradient(target: Target, options: GradientOptions): Gradient {
+  const view = toView(target)
+  if (!options || !types.includes(options.type))
+    throw new TypeError(`Gradient type must be 'linear', 'radial' or 'conic'.`)
+  const first = resolve(
+    { colors: [], stops: [], angle: 180, x: 0.5, y: 0.5, radius: 0.5 },
+    options,
+    false,
+  )
+  return new GradientController(view, options.type, first)
+}
+
+class GradientController implements Gradient {
+  private painter: GradientPainter | undefined
+  private pending: GradientFrame | undefined
+  private removed = false
+  private model: GradientFrame
+  private running:
+    | {
+        from: GradientFrame
+        to: GradientFrame
+        track: Track
+        startedAt: number
+        handle: { cancel(): void }
+        settle: (finished: boolean) => void
+      }
+    | undefined
+
+  constructor(
+    private readonly view: View,
+    readonly type: GradientType,
+    frame: GradientFrame,
+  ) {
+    this.model = frame
+    this.attach((factory ?? platformPainter)(view, type))
+    view.on('unloaded', this.unloaded)
+  }
+
+  private unloaded = () => this.stop()
+
+  private attach(painter: GradientPainter | undefined) {
+    if (!painter) return
+    if (this.removed) return painter.remove()
+    this.painter = painter
+    painter.paint(this.pending ?? this.model)
+    this.pending = undefined
+  }
+
+  animate(values: GradientValues, transition?: Transition | SpringName): Animation {
+    this.assertActive()
+    const from = this.presented()
+    const to = resolve(from, values, true)
+    const resolved =
+      typeof transition === 'string' ? springOf(transition) : (transition ?? {})
+    const track = createTrack(
+      'opacity',
+      [0, 1],
+      resolveTransition(resolved, 'opacity', 2),
+      0,
+    )
+    const reduced = reducedMotion()
+    const frameAt = (progress: number) => mix(from, to, progress, reduced)
+    this.cancelRunning()
+    this.model = frameAt(track.to)
+
+    let settle!: (finished: boolean) => void
+    const finished = new Promise<boolean>((resolve) => (settle = resolve))
+    const animation: Animation = {
+      finished,
+      stop: () => {
+        if (this.running?.settle === settle) this.stop()
+      },
+      then: (onfulfilled, onrejected) => finished.then(onfulfilled, onrejected),
+    }
+    if (track.end === 0 || !this.painter) {
+      this.paint(this.model)
+      settle(true)
+      return animation
+    }
+    const handle = this.painter.play(
+      track.values.map(frameAt),
+      track.times,
+      {
+        duration: track.duration,
+        delay: track.delay,
+        repeat: track.repeat,
+        reverse: track.reverse,
+      },
+      (completed) => {
+        if (this.running?.settle !== settle) return
+        this.running = undefined
+        settle(completed)
+      },
+    )
+    this.running = {
+      from,
+      to,
+      track,
+      startedAt: getDriver().now(),
+      handle,
+      settle,
+    }
+    return animation
+  }
+
+  set(values: GradientValues) {
+    this.assertActive()
+    const next = resolve(this.presented(), values, false)
+    this.cancelRunning()
+    this.model = next
+    this.paint(next)
+  }
+
+  stop() {
+    if (!this.running) return
+    const current = this.presented()
+    this.cancelRunning()
+    this.model = current
+    this.paint(current)
+  }
+
+  remove() {
+    if (this.removed) return
+    this.cancelRunning()
+    this.removed = true
+    this.view.off('unloaded', this.unloaded)
+    this.painter?.remove()
+    this.painter = undefined
+  }
+
+  private paint(frame: GradientFrame) {
+    if (this.painter) this.painter.paint(frame)
+    else this.pending = frame
+  }
+
+  private presented(): GradientFrame {
+    const running = this.running
+    if (!running) return this.model
+    const elapsed = getDriver().now() - running.startedAt
+    return mix(running.from, running.to, running.track.valueAt(elapsed), reducedMotion())
+  }
+
+  private cancelRunning() {
+    const running = this.running
+    if (!running) return
+    this.running = undefined
+    running.handle.cancel()
+    running.settle(false)
+  }
+
+  private assertActive() {
+    if (this.removed) throw new Error('This gradient was removed.')
+  }
+}
+
+function springOf(name: SpringName): Transition {
+  const spring = springs[name]
+  if (!spring || !Object.hasOwn(springs, name))
+    throw new Error(`Unknown spring "${name}".`)
+  return spring
+}
+
+/** Validates values and fills in what they leave out from `base`. */
+function resolve(
+  base: GradientFrame,
+  values: GradientValues,
+  sameCount: boolean,
+): GradientFrame {
+  if (!values || typeof values !== 'object')
+    throw new TypeError('Gradient values must be an object.')
+  const colors = values.colors ? values.colors.map(parseColor) : base.colors
+  if (colors.length < 2 || colors.length > 8)
+    throw new RangeError('A gradient needs between two and eight colors.')
+  if (sameCount && values.colors && colors.length !== base.colors.length)
+    throw new RangeError(
+      `Animating a gradient keeps its ${base.colors.length} colors; use set() to change the count.`,
+    )
+  const stops = values.stops
+    ? [...values.stops]
+    : values.colors || base.stops.length !== colors.length
+      ? colors.map((_, i) => i / (colors.length - 1))
+      : base.stops
+  if (
+    stops.length !== colors.length ||
+    stops.some(
+      (stop, i) =>
+        !Number.isFinite(stop) || stop < 0 || stop > 1 || stop < (stops[i - 1] ?? 0),
+    )
+  )
+    throw new RangeError(
+      'Gradient stops need one value per color, from 0 to 1, without going back.',
+    )
+  const angle = values.angle ?? base.angle
+  const x = values.center?.x ?? base.x
+  const y = values.center?.y ?? base.y
+  const radius = values.radius ?? base.radius
+  for (const [name, value] of [
+    ['angle', angle],
+    ['center', x],
+    ['center', y],
+    ['radius', radius],
+  ] as const)
+    if (!Number.isFinite(value))
+      throw new RangeError(`Invalid gradient ${name}: ${value}.`)
+  if (radius < 0)
+    throw new RangeError(`Gradient radius must not be negative, got ${radius}.`)
+  return { colors, stops, angle, x, y, radius }
+}
+
+/** One frame between two states. Geometry follows the curve, overshoot included; colors and stops stay between their ends. */
+export function mix(
+  from: GradientFrame,
+  to: GradientFrame,
+  progress: number,
+  reduced = false,
+): GradientFrame {
+  const p = Math.min(Math.max(progress, 0), 1)
+  const g = reduced ? 1 : progress
+  const lerp = (a: number, b: number, t: number) => a + (b - a) * t
+  return {
+    colors: to.colors.map((color, i) => colorMixer(from.colors[i] ?? color, color)(p)),
+    stops: to.stops.map((stop, i) => lerp(from.stops[i] ?? stop, stop, p)),
+    angle: lerp(from.angle, to.angle, g),
+    x: lerp(from.x, to.x, g),
+    y: lerp(from.y, to.y, g),
+    radius: Math.max(0, lerp(from.radius, to.radius, g)),
+  }
+}
+
+/**
+ * The points a platform gradient needs, in unit coordinates of a `width` × `height` box.
+ * Linear follows CSS: the line runs through the center at `angle` and is long enough
+ * for the corners to get the first and last colors.
+ */
+export function gradientPoints(
+  type: GradientType,
+  frame: GradientFrame,
+  width: number,
+  height: number,
+) {
+  const radians = (frame.angle * Math.PI) / 180
+  const sin = Math.sin(radians)
+  const cos = Math.cos(radians)
+  if (type === 'linear') {
+    const length = Math.abs(width * sin) + Math.abs(height * cos)
+    const dx = width > 0 ? (sin * length) / (2 * width) : 0
+    const dy = height > 0 ? (-cos * length) / (2 * height) : 0
+    return { start: { x: 0.5 - dx, y: 0.5 - dy }, end: { x: 0.5 + dx, y: 0.5 + dy } }
+  }
+  const center = { x: frame.x, y: frame.y }
+  const shorter = Math.min(width, height)
+  if (type === 'radial') {
+    const r = frame.radius * shorter
+    return {
+      start: center,
+      end: {
+        x: center.x + (width > 0 ? r / width : 0),
+        y: center.y + (height > 0 ? r / height : 0),
+      },
+    }
+  }
+  return {
+    start: center,
+    end: {
+      x: center.x + (width > 0 ? (sin * shorter) / (2 * width) : 0),
+      y: center.y + (height > 0 ? (-cos * shorter) / (2 * height) : 0),
+    },
+  }
+}

package/src/index.ts

@@ -42,12 +42,26 @@ export type {
   SymbolEffectName,
   SymbolEffectOptions,
 } from './symbol-effect.js'
+export { gradient } from './gradient.js'
+export type {
+  Gradient,
+  GradientOptions,
+  GradientType,
+  GradientValues,
+} from './gradient.js'
 export { configure, onReducedMotion, reducedMotion } from './config.js'
 export type { JoltConfig } from './config.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
-export { springs } from './transition.js'
-export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
+export { origamiSpring, springs } from './transition.js'
+export type {
+  OrigamiSpring,
+  Spring,
+  SpringName,
+  Timing,
+  Transition,
+  Tween,
+} from './transition.js'
 export { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
 export type { PlaybackAnimation } from './playback.js'

package/src/motion-scope.ts

@@ -40,13 +40,13 @@ export interface MotionScope {
   press: typeof press
   drag: typeof drag
   states<
-    T extends Record<string, Target>,
+    T extends Record<string, Target | null>,
     const S extends Record<string, MotionState<keyof T>>,
   >(
     targets: T,
     definitions: MotionDefinitions<T, S>,
     options?: Omit<MotionStatesOptions, 'scope'>,
-  ): MotionStates<Extract<keyof S, string>>
+  ): MotionStates<Extract<keyof S, string>, Extract<keyof T, string>>
   /** Adopt an existing handle. Completed animations are released automatically. */
   add<T extends MotionResource>(resource: T): T
   /** Attach a subscription, detach on suspension, and recreate on resume. */