@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

package/src/animate.ts

@@ -17,16 +17,26 @@ import { DEFAULT_FRICTION, solveDecay } from './decay.js'
 import {
   arrivalOf,
   setArrival,
+  stopLayer,
   stopView,
   ViewAnimation,
   type Animation,
   type Plan,
 } from './engine.js'
 import { getPreset, type PresetName } from './presets.js'
+import {
+  asRoot,
+  detachBindings,
+  isMotionValue,
+  type MotionValue,
+  type ValueAnimationOptions,
+} from './motion-value.js'
 import { resolveHaptic, type Haptic } from './haptics.js'
+import { layerable } from './mixer.js'
 import { isProperty, precision, type Property } from './properties.js'
 import {
   hasCurve,
+  fitTransition,
   mergeTransitions,
   resolveTransition,
   springs,
@@ -42,6 +52,7 @@ import type {
   KeyframeProperty,
   Stagger,
   Target,
+  Values,
 } from './types.js'
 
 interface Options {
@@ -50,24 +61,45 @@ interface Options {
   stagger: number | Stagger | undefined
   relative: boolean | undefined
   haptic: Haptic | undefined
+  layer?: string
 }
 
 /**
  * Animates one view, or several. Takes keyframes or the name of a preset,
- * and a transition or the name of a spring.
+ * and a transition or the name of a spring. A motion value animates to a number.
  *
  * ```ts
  * animate(card, 'fadeInUp')
  * animate(card, { scale: 1.1, rotate: [0, 90] }, 'bouncy')
  * animate(rows, 'fadeInUp', { stagger: 40 })
+ * animate(progress, 1, 'snappy')
  * ```
  */
+export function animate(
+  value: MotionValue,
+  to: number | readonly (number | null)[],
+  transition?: ValueAnimationOptions | SpringName,
+): PlaybackAnimation
 export function animate(
   target: Target | readonly Target[],
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
-): PlaybackAnimation {
-  return prepareAnimation(target, animation, options)()
+): PlaybackAnimation
+export function animate(
+  target: Target | readonly Target[] | MotionValue,
+  animation: Keyframes | PresetName | number | readonly (number | null)[],
+  options?: AnimateOptions | SpringName,
+): PlaybackAnimation | Animation {
+  if (isMotionValue(target))
+    return asRoot(target).animate(
+      animation as number | readonly (number | null)[],
+      options as ValueAnimationOptions | SpringName | undefined,
+    )
+  return prepareAnimation(
+    target as Target | readonly Target[],
+    animation as Keyframes | PresetName,
+    options,
+  )()
 }
 
 /** Validate and snapshot a complete animation before changing any view ownership. */
@@ -76,7 +108,7 @@ export function prepareAnimation(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): () => PlaybackAnimation {
-  const { keyframes, base, overrides, stagger, relative, haptic, path } = prepare(
+  const { keyframes, base, overrides, stagger, relative, haptic, path, layer } = prepare(
     animation,
     options,
   )
@@ -87,8 +119,15 @@ export function prepareAnimation(
     for (const property of Object.keys(keyframes))
       if (isColorProperty(property)) validateColorTarget(view, property)
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
-    const plans = plan(keyframes, base, overrides, 0, relative, path)
-    return () => new ViewAnimation(view, plans, feedback)
+    const plans = plan(keyframes, base, overrides, 0, relative, path, layer)
+    return () => {
+      if (layer === undefined)
+        detachBindings(
+          view,
+          plans.map(({ property }) => property),
+        )
+      return new ViewAnimation(view, plans, feedback)
+    }
   }
 
   const views = target.map(toView)
@@ -96,6 +135,7 @@ export function prepareAnimation(
     for (const property of Object.keys(keyframes))
       if (isColorProperty(property)) validateColorTarget(view, property)
       else if (isDecorationProperty(property)) validateDecorationTarget(view, property)
+  const seed = Math.random()
   const plans = views.map((_, index) =>
     plan(
       keyframes,
@@ -104,11 +144,20 @@ export function prepareAnimation(
       staggerDelay(stagger, index, views.length),
       relative,
       path,
+      layer,
+      seed,
     ),
   )
   return () =>
     playbackGroup(
-      views.map((view, index) => new ViewAnimation(view, plans[index]!, feedback, true)),
+      views.map((view, index) => {
+        if (layer === undefined)
+          detachBindings(
+            view,
+            plans[index]!.map(({ property }) => property),
+          )
+        return new ViewAnimation(view, plans[index]!, feedback, true)
+      }),
     )
 }
 
@@ -185,15 +234,63 @@ export function decay(
   )
 }
 
-/** Stops all or selected properties at their current values. `scale` stops both axes. */
+/**
+ * Stops all or selected properties at their current values. `scale` stops both axes.
+ * A motion value stops where it is, and so do the views bound to it.
+ */
+export function stop(value: MotionValue, options?: { layer?: string }): void
 export function stop(
   target: Target | readonly Target[],
   properties?: readonly KeyframeProperty[],
+  options?: { layer?: string },
+): void
+export function stop(
+  target: Target | readonly Target[] | MotionValue,
+  properties?: readonly KeyframeProperty[] | { layer?: string },
+  options?: { layer?: string },
 ) {
-  const expanded = properties?.flatMap<Property>((property) =>
+  if (isMotionValue(target))
+    return asRoot(target).stop((properties as { layer?: string } | undefined)?.layer)
+  if (properties && !Array.isArray(properties))
+    throw new TypeError('View properties must be an array.')
+  const expanded = (
+    properties as readonly KeyframeProperty[] | undefined
+  )?.flatMap<Property>((property) =>
     property === 'scale' ? ['scaleX', 'scaleY'] : [property],
   )
-  for (const view of toViews(target)) stopView(view, expanded)
+  for (const view of toViews(target as Target | readonly Target[]))
+    if (options?.layer !== undefined) stopLayer(view, options.layer, expanded)
+    else stopView(view, expanded)
+}
+
+/**
+ * Applies values at once, stopping whatever animates those properties.
+ * `scale` sets both axes. A view that isn't loaded yet gets them right away.
+ *
+ * ```ts
+ * set(logo, { opacity: 1, scale: 1, y: 0 })
+ * ```
+ */
+export function set(value: MotionValue, to: number): void
+export function set(target: Target | readonly Target[], values: Values): void
+export function set(
+  target: Target | readonly Target[] | MotionValue,
+  values: Values | number,
+) {
+  if (isMotionValue(target)) return asRoot(target).set(values as number)
+  if (values === null || typeof values !== 'object' || Array.isArray(values))
+    throw new TypeError('set() takes an object of values.')
+  const keyframes: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) continue
+    if (key !== 'scale' && !isProperty(key)) throw new Error(`Can't set "${key}".`)
+    if (value === null || Array.isArray(value))
+      throw new TypeError(
+        `set() takes one value per property, got ${String(value)} for "${key}".`,
+      )
+    keyframes[key] = [value, value]
+  }
+  animate(target as Target | readonly Target[], keyframes as Keyframes, { duration: 0 })
 }
 
 /** Plays several animations as one: finished once they all are, and stopped together. */
@@ -256,6 +353,7 @@ function resolveAnimation(
     stagger: user.stagger ?? own.stagger,
     relative: user.relative ?? own.relative,
     haptic: user.haptic ?? own.haptic,
+    layer: user.layer,
   }
 }
 
@@ -282,16 +380,21 @@ function normalize(options: AnimateOptions | SpringName | undefined): Options {
   let stagger: Options['stagger']
   let relative: Options['relative']
   let haptic: Options['haptic']
+  let layer: Options['layer']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
-    if (key === 'stagger') stagger = value as Options['stagger']
+    if (key === 'layer') {
+      if (typeof value !== 'string' || !value)
+        throw new TypeError('A layer is named by a nonempty string.')
+      layer = value
+    } else if (key === 'stagger') stagger = value as Options['stagger']
     else if (key === 'relative') relative = value as Options['relative']
     else if (key === 'haptic') haptic = value as Options['haptic']
     else if (key === 'path' || key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger, relative, haptic }
+  return { base, overrides, stagger, relative, haptic, layer }
 }
 
 function plan(
@@ -301,8 +404,16 @@ function plan(
   offset: number,
   relative = false,
   path?: PreparedPath,
+  layer?: string,
+  seed = Math.random(),
 ): Plan[] {
+  if (layer !== undefined && path)
+    throw new Error("A path owns x and y; it can't play on a layer.")
   return expand(keyframes, path).map(([property, frames]) => {
+    if (layer !== undefined && !layerable(property))
+      throw new Error(
+        `Layers apply to x, y, scale, rotation and opacity; "${property}" has a single owner.`,
+      )
     if (path?.properties.includes(property as 'x' | 'y' | 'rotate')) {
       if (
         !Number.isFinite(path.transition.delay + offset) ||
@@ -322,12 +433,13 @@ function plan(
     const override =
       overrides[property] ?? (property.startsWith('scale') ? overrides.scale : undefined)
     const transition = resolveTransition(
-      override ? mergeTransitions(base, override) : base,
+      fitTransition(override ? mergeTransitions(base, override) : base, frames.length),
       property,
       frames.length,
     )
     transition.delay += offset
-    return { property, keyframes: frames, transition, relative }
+    if (transition.seed !== undefined) transition.seed = seed
+    return { property, keyframes: frames, transition, relative, layer }
   })
 }
 
@@ -336,8 +448,10 @@ export function startingValues(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ) {
-  const { keyframes, relative, path } = prepare(animation, options)
+  const { keyframes, relative, path, layer } = prepare(animation, options)
   if (!keyframes) throw new Error(`Unknown preset "${animation}".`)
+  if (layer !== undefined)
+    return new Map(expand(keyframes, path).map(([property]) => [property, null]))
   return new Map(
     expand(keyframes, path).map(([property, [first]]) => [
       property,

package/src/blur/index.ts

@@ -0,0 +1,195 @@
+import { Application, type View } from '@nativescript/core'
+import { toView } from '../animate.js'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import { TimedAnimation } from '../timed-animation.js'
+import { createTrack, instantTrack, type Track } from '../track.js'
+import {
+  resolveTransition,
+  springs,
+  type Transition,
+  type SpringName,
+} from '../transition.js'
+import type { Target } from '../types.js'
+import { createBlur, type BlurPainter } from './native.js'
+import type { Blur, BlurOptions, BlurSnapshot } from './types.js'
+export type { Blur, BlurOptions, BlurSnapshot } from './types.js'
+
+const owners = new WeakMap<View, BlurOwner>()
+function amount(value: number) {
+  if (!Number.isFinite(value) || value < 0 || value > 1)
+    throw new RangeError('Blur amount must be within 0..1.')
+  return value
+}
+/** Blur a dedicated content view after native layout. Keep sharp controls in a sibling. */
+export function blur(target: Target, options: BlurOptions = {}): Blur {
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Invalid blur options.')
+  const settings: Required<BlurOptions> = {
+    amount: amount(options.amount ?? 0),
+    radius: options.radius ?? 24,
+    style: options.style ?? 'system',
+  }
+  if (!Number.isFinite(settings.radius) || settings.radius < 1 || settings.radius > 64)
+    throw new RangeError('Blur radius must be within 1..64 DIPs.')
+  if (!['system', 'light', 'dark'].includes(settings.style))
+    throw new TypeError('Invalid blur style.')
+  const view = toView(target)
+  if (!view.isLoaded || !view.nativeViewProtected)
+    throw new Error('Create blur after native layout.')
+  if (owners.has(view)) throw new Error('This view already owns blur. Dispose it first.')
+  return new BlurOwner(view, settings)
+}
+class BlurOwner implements Blur {
+  disposed = false
+  private painter?: BlurPainter
+  private native?: object
+  private state: BlurSnapshot
+  private active?: { animation: TimedAnimation; track: Track; destination: number }
+  private suspended = false
+  private backgrounded = false
+  private offReduced: () => void
+  constructor(
+    private readonly view: View,
+    private readonly options: Required<BlurOptions>,
+  ) {
+    this.attach(options.amount)
+    this.state = this.painter!.snapshot()
+    owners.set(view, this)
+    view.on('loaded', this.layout)
+    view.on('layoutChanged', this.layout)
+    view.on('unloaded', this.unload)
+    Application.on(Application.suspendEvent, this.background)
+    Application.on(Application.resumeEvent, this.foreground)
+    this.offReduced = onReducedMotion((value) => {
+      if (!value || !this.active) return
+      const destination = this.active.destination
+      this.set(destination)
+    })
+  }
+  private alive() {
+    if (this.disposed) throw new Error('Blur has been disposed.')
+  }
+  private attach(value: number) {
+    this.painter = createBlur(this.view, { ...this.options, amount: value })
+    this.native = this.view.nativeViewProtected
+  }
+  private layout = () => {
+    if (this.disposed || !this.view.isLoaded || !this.view.nativeViewProtected) return
+    if (this.native && this.native !== this.view.nativeViewProtected) this.unload()
+    if (!this.painter) {
+      this.attach(this.state.amount)
+      if (this.active) {
+        this.painter!.play(this.active.track)
+        this.painter!.control(this.active.animation.time, true)
+      }
+    }
+    this.painter!.resize()
+    if (!this.backgrounded && this.suspended) {
+      this.active?.animation.play()
+      this.suspended = false
+    }
+  }
+  private unload = () => {
+    if (!this.backgrounded || !this.active) this.stop()
+    this.state = this.snapshot()
+    this.painter?.dispose()
+    this.painter = undefined
+    this.native = undefined
+  }
+  private background = () => {
+    if (this.backgrounded) return
+    this.backgrounded = true
+    this.suspended = !!this.active && !this.active.animation.paused
+    if (this.suspended) this.active!.animation.pause()
+  }
+  private foreground = () => {
+    this.backgrounded = false
+    if (this.painter) {
+      if (this.suspended) this.active?.animation.play()
+      this.suspended = false
+    }
+  }
+  snapshot(): BlurSnapshot {
+    if (this.painter) this.state = this.painter.snapshot()
+    return {
+      ...this.state,
+      attached: !!this.painter,
+      appliedAmount: this.painter ? this.state.appliedAmount : 0,
+      nativeAnimations: this.painter ? this.state.nativeAnimations : 0,
+    }
+  }
+  set(value: number) {
+    this.alive()
+    amount(value)
+    this.stop()
+    this.state.amount = value
+    this.painter?.paint(value)
+  }
+  animate(value: number, options: Transition | SpringName = {}) {
+    this.alive()
+    amount(value)
+    if (!this.painter || !this.view.isLoaded)
+      throw new Error('Load blur before animating.')
+    if (typeof options === 'string' && !Object.hasOwn(springs, options))
+      throw new TypeError('Unknown blur spring.')
+    const settings = typeof options === 'string' ? springs[options] : options
+    if ('layer' in settings)
+      throw new TypeError('Blur owns one animation; named layers are not supported.')
+    const transition = resolveTransition(settings, 'opacity', 2)
+    const from = this.snapshot().amount
+    const velocity =
+      this.active && !this.active.animation.paused
+        ? this.active.track.velocityAt(this.active.animation.time)
+        : 0
+    const track =
+      reducedMotion() || this.state.backend === 'none'
+        ? instantTrack('opacity', value)
+        : createTrack('opacity', [from, value], transition, velocity)
+    this.stop()
+    let animation: TimedAnimation
+    animation = new TimedAnimation(
+      track.end,
+      track.arrival,
+      (time, paused) => this.painter?.control(time, paused),
+      (completed) => {
+        const current = completed
+          ? Math.max(0, Math.min(1, track.to))
+          : this.snapshot().amount
+        this.state.amount = current
+        this.painter?.paint(current)
+        if (this.active?.animation === animation) this.active = undefined
+      },
+    )
+    this.active = { animation, track, destination: value }
+    try {
+      if (track.end > 0) this.painter.play(track)
+      else this.painter.paint(value)
+      animation.start()
+      if (this.backgrounded && this.active) {
+        this.suspended = true
+        animation.pause()
+      }
+    } catch (e) {
+      animation.stop()
+      throw e
+    }
+    return animation
+  }
+  stop() {
+    this.active?.animation.stop()
+    this.suspended = false
+  }
+  dispose() {
+    if (this.disposed) return
+    this.stop()
+    this.unload()
+    this.disposed = true
+    this.offReduced()
+    this.view.off('loaded', this.layout)
+    this.view.off('layoutChanged', this.layout)
+    this.view.off('unloaded', this.unload)
+    Application.off(Application.suspendEvent, this.background)
+    Application.off(Application.resumeEvent, this.foreground)
+    owners.delete(this.view)
+  }
+}

package/src/blur/native.ts

@@ -0,0 +1,70 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { Track } from '../track.js'
+import type { BlurOptions, BlurSnapshot } from './types.js'
+
+export interface BlurPainter {
+  paint(amount: number): void
+  play(track: Track): void
+  control(time: number, paused: boolean): void
+  resize(): void
+  snapshot(): BlurSnapshot
+  dispose(): void
+}
+type Factory = (view: View, options: Required<BlurOptions>) => BlurPainter
+let override: Factory | undefined
+/** Internal seam for lifecycle tests. */
+export function setBlurFactory(value: Factory | undefined) {
+  override = value
+}
+export const createBlur: Factory = (view, options) => {
+  if (override) return override(view, options)
+  let native: {
+    paint(value: number): void
+    play(program: string): void
+    resize(): void
+    snapshot(): string
+    dispose(): void
+  }
+  let control: (time: number, paused: boolean) => void
+  if (isIOS) {
+    if (typeof JoltBlur === 'undefined')
+      throw new Error('Rebuild the native app to install animated blur.')
+    const effect = JoltBlur.attachOptions(
+      view.nativeViewProtected,
+      JSON.stringify(options),
+    )
+    native = effect
+    control = (time, paused) => effect.controlPaused(time, paused)
+  } else {
+    if (
+      typeof org === 'undefined' ||
+      typeof org.rafaelaugusto.jolt.BlurEffect !== 'function'
+    )
+      throw new Error('Rebuild the native app to install animated blur.')
+    const effect = new org.rafaelaugusto.jolt.BlurEffect(
+      view.nativeViewProtected,
+      options.radius,
+    )
+    native = effect
+    control = (time, paused) => effect.control(time, paused)
+  }
+  native.paint(options.amount)
+  return {
+    paint: (amount) => native.paint(amount),
+    play: (track) =>
+      native.play(
+        JSON.stringify({
+          times: track.times,
+          values: track.values,
+          duration: track.duration,
+          delay: track.delay,
+          repeat: track.repeat === Infinity ? -1 : track.repeat,
+          reverse: track.reverse,
+        }),
+      ),
+    control,
+    resize: () => native.resize(),
+    snapshot: () => JSON.parse(native.snapshot()),
+    dispose: () => native.dispose(),
+  }
+}

package/src/blur/types.ts

@@ -0,0 +1,32 @@
+import type { PlaybackAnimation } from '../playback.js'
+import type { SpringName, Transition } from '../transition.js'
+
+export interface BlurOptions {
+  /** Initial intensity, 0..1. Defaults to 0 (clear). */
+  amount?: number
+  /** Android maximum radius in DIPs, 1..64. Defaults to 24. iOS uses a system material. */
+  radius?: number
+  /** iOS material. Defaults to system. Android ignores this option. */
+  style?: 'system' | 'light' | 'dark'
+}
+export interface BlurSnapshot {
+  amount: number
+  /** iOS animator fraction or Android radius/maxRadius; 0 for the unsupported fallback. */
+  appliedAmount: number
+  backend: 'ios-material' | 'android-render-effect' | 'none'
+  attached: boolean
+  nativeAnimations: number
+  frames: number
+  width: number
+  height: number
+}
+export interface Blur {
+  readonly disposed: boolean
+  /** Retarget from the displayed amount. One owner per view. */
+  animate(amount: number, transition?: Transition | SpringName): PlaybackAnimation
+  set(amount: number): void
+  stop(): void
+  snapshot(): BlurSnapshot
+  /** Remove the owned effect and lifecycle listeners. */
+  dispose(): void
+}

package/src/bottom-sheet/geometry.ts

@@ -0,0 +1,84 @@
+export type SheetSnap = number | `${number}%` | 'content'
+
+export interface SheetStop {
+  point: SheetSnap
+  height: number
+  y: number
+}
+
+export interface SheetGeometry {
+  height: number
+  closedY: number
+  top: number
+  stops: SheetStop[]
+}
+
+export function validateSnaps(points: readonly SheetSnap[]): void {
+  if (!Array.isArray(points) || !points.length)
+    throw new TypeError('bottomSheet() needs at least one snap point.')
+  for (const point of points) {
+    if (point === 'content') continue
+    if (typeof point === 'number' && Number.isFinite(point) && point > 0) continue
+    if (typeof point === 'string' && /^(?:\d+(?:\.\d+)?|\.\d+)%$/.test(point)) {
+      const percent = Number.parseFloat(point)
+      if (percent > 0 && percent <= 100) continue
+    }
+    throw new RangeError(
+      'Sheet snaps must be positive DIPs, 0–100% (exclusive of 0), or content.',
+    )
+  }
+  if (new Set(points).size !== points.length)
+    throw new RangeError('Sheet snap points must not repeat.')
+}
+
+/** Keyboard overlap is relative to the host, so adjustResize is not subtracted twice. */
+export function sheetGeometry(
+  points: readonly SheetSnap[],
+  hostHeight: number,
+  hostBottom: number,
+  windowHeight: number,
+  keyboardHeight: number,
+  safeTop: number,
+  safeBottom: number,
+  contentHeight: number,
+): SheetGeometry {
+  const top = Math.max(0, safeTop)
+  const overlap = Math.max(
+    0,
+    Math.min(hostHeight, hostBottom - (windowHeight - keyboardHeight)),
+  )
+  const bottom = Math.max(Math.max(0, safeBottom), overlap)
+  const height = Math.max(1, hostHeight - top - bottom)
+  const closedY = Math.max(height, hostHeight - top)
+  const stops = points.map((point) => {
+    const desired =
+      point === 'content'
+        ? contentHeight
+        : typeof point === 'number'
+          ? point
+          : (Number.parseFloat(point) / 100) * height
+    const visible = Math.max(1, Math.min(height, desired))
+    return { point, height: visible, y: height - visible }
+  })
+  return { height, closedY, top, stops }
+}
+
+/** Projection selects a stop; the native spring retains the actual release velocity. */
+export function releaseStop(
+  geometry: SheetGeometry,
+  y: number,
+  velocity: number,
+  dismissible: boolean,
+): SheetStop | undefined {
+  const projected = y + Math.max(-4000, Math.min(4000, velocity)) * 0.2
+  let distance = dismissible ? Math.abs(projected - geometry.closedY) : Infinity
+  let result: SheetStop | undefined
+  for (const stop of geometry.stops) {
+    const next = Math.abs(projected - stop.y)
+    if (next <= distance) {
+      distance = next
+      result = stop
+    }
+  }
+  return result
+}