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

package/src/transition.ts

@@ -12,10 +12,15 @@ export interface Timing {
   repeat?: number
   /** `reverse` plays every other repeat backwards. */
   repeatType?: 'loop' | 'reverse'
-  /** Milliseconds to hold the end value before each repeat. The first play doesn't wait. */
-  repeatDelay?: number
+  /**
+   * Milliseconds to hold the end value before each repeat. The first play doesn't wait.
+   * `[min, max]` draws a new pause for each repeat.
+   */
+  repeatDelay?: number | RepeatDelayRange
 }
 
+export type RepeatDelayRange = readonly [min: number, max: number]
+
 export interface Tween extends Timing {
   type?: 'tween'
   /** Milliseconds. */
@@ -54,6 +59,36 @@ export const springs: Record<SpringName, Spring> = {
   bouncy: { type: 'spring', duration: 550, bounce: 0.4 },
 }
 
+export interface OrigamiSpring {
+  /** React Native's default is 7. */
+  friction?: number
+  /** React Native's default is 40. */
+  tension?: number
+}
+
+/**
+ * The spring React Native's `Animated.spring` plays for `friction` and `tension`,
+ * converted with the same Origami formulas.
+ *
+ * ```ts
+ * animate(card, { x: 100 }, origamiSpring({ friction: 7, tension: 40 }))
+ * ```
+ */
+export function origamiSpring({
+  friction = 7,
+  tension = 40,
+}: OrigamiSpring = {}): Spring {
+  if (!Number.isFinite(friction) || !Number.isFinite(tension))
+    throw new RangeError('Origami friction and tension must be finite.')
+  const stiffness = (tension - 30) * 3.62 + 194
+  const damping = (friction - 8) * 3 + 25
+  if (stiffness <= 0 || damping < 0)
+    throw new RangeError(
+      `Origami tension ${tension} and friction ${friction} give no spring (stiffness ${stiffness}, damping ${damping}).`,
+    )
+  return { type: 'spring', stiffness, damping, mass: 1 }
+}
+
 export type Curve =
   | DragCurve
   | {
@@ -77,7 +112,9 @@ export interface ResolvedTransition {
   delay: number
   repeat: number
   reverse: boolean
-  repeatDelay?: number
+  repeatDelay?: number | RepeatDelayRange
+  /** Draws the pauses of a `repeatDelay` range; tracks of one animation share it. */
+  seed?: number
 }
 
 const springKeys = ['stiffness', 'damping', 'mass', 'bounce', 'velocity'] as const
@@ -107,11 +144,53 @@ export function timingOf(transition: Transition): Timing {
   return timing
 }
 
-/** Timing merges key by key, the curve is taken whole from whichever side has one. */
+const isSpring = (transition: Transition) =>
+  transition.type === 'spring' ||
+  springKeys.some((key) => (transition as Spring)[key] !== undefined)
+
+/** Curve keys a merged transition took from the main one rather than from its override. */
+const inherited = new WeakMap<Transition, ReadonlySet<string>>()
+
+/**
+ * Timing merges key by key. Over a tween, a curve that stays a tween merges key by key too;
+ * otherwise the curve is taken whole from whichever side has one.
+ */
 export function mergeTransitions(base: Transition, override: Transition): Transition {
-  return hasCurve(override)
-    ? { ...timingOf(base), ...override }
-    : { ...base, ...timingOf(override) }
+  if (!hasCurve(override)) {
+    const merged = { ...base, ...timingOf(override) }
+    const taken = inherited.get(base)
+    if (taken) inherited.set(merged, taken)
+    return merged
+  }
+  if (!hasCurve(base) || isSpring(base) || isSpring(override))
+    return { ...timingOf(base), ...override }
+  const merged = { ...base, ...override } as Transition
+  const own = override as Record<string, unknown>
+  inherited.set(
+    merged,
+    new Set(
+      curveKeys.filter(
+        (key) =>
+          (base as Record<string, unknown>)[key] !== undefined && own[key] === undefined,
+      ),
+    ),
+  )
+  return merged
+}
+
+/** Drops inherited `times` and per-segment easings that don't fit this property's keyframes. */
+export function fitTransition(transition: Transition, keyframes: number): Transition {
+  const taken = inherited.get(transition)
+  if (!taken) return transition
+  const tween = { ...transition } as Tween
+  const segments = (ease: Tween['ease']) =>
+    ease !== undefined && isEasingList(ease) ? ease.length : undefined
+  if (taken.has('times') && tween.times && tween.times.length !== keyframes)
+    delete tween.times
+  if (taken.has('ease') && (segments(tween.ease) ?? keyframes - 1) !== keyframes - 1)
+    delete tween.ease
+  if (taken.has('easeTrack') && segments(tween.ease) !== undefined) delete tween.easeTrack
+  return tween
 }
 
 export function resolveTransition(
@@ -137,13 +216,23 @@ export function resolveTransition(
   if (repeat < 0 || Number.isNaN(repeat))
     throw new RangeError(`Invalid repeat: ${repeat}.`)
   const repeatDelay = transition.repeatDelay ?? 0
-  if (!Number.isFinite(repeatDelay) || repeatDelay < 0)
-    throw new RangeError(`Invalid repeat delay: ${repeatDelay}.`)
+  const [shortest, longest] =
+    typeof repeatDelay === 'number' ? [repeatDelay, repeatDelay] : repeatDelay
+  if (
+    (typeof repeatDelay !== 'number' &&
+      (!Array.isArray(repeatDelay) || repeatDelay.length !== 2)) ||
+    !Number.isFinite(shortest) ||
+    !Number.isFinite(longest) ||
+    shortest! < 0 ||
+    shortest! > longest!
+  )
+    throw new RangeError(`Invalid repeat delay: ${JSON.stringify(repeatDelay)}.`)
   const timing = {
     delay,
     repeat,
     reverse: transition.repeatType === 'reverse',
-    ...(repeatDelay > 0 && repeat > 0 && { repeatDelay }),
+    ...(longest! > 0 && repeat > 0 && { repeatDelay }),
+    ...(longest! > shortest! && repeat > 0 && { seed: Math.random() }),
   }
 
   if (type === 'spring') {

package/src/types.ts

@@ -86,4 +86,9 @@ export type AnimateOptions = Transition & {
   stagger?: number | Stagger
   /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
   haptic?: Haptic
+  /**
+   * Plays on a named layer, on top of the property's other animations instead of replacing
+   * them. Translations and rotations add; scale and opacity multiply.
+   */
+  layer?: string
 }

package/src/vue/index.ts

@@ -15,10 +15,19 @@ import {
   type Ref,
 } from 'nativescript-vue'
 import {
+  gradient,
   press,
   motionScope,
+  bind,
+  motionValue,
+  scrollValue,
   onKeyboard,
   onReducedMotion,
+  stop,
+  type Bindings,
+  type MotionValue,
+  type ScrollValue,
+  type Target,
   reducedMotion,
   type KeyboardState,
   type MotionScope,
@@ -27,6 +36,9 @@ import {
   type PlaybackAnimation,
   type PresetName,
   type SpringName,
+  type Gradient,
+  type GradientOptions,
+  type Transition,
 } from '../index.js'
 import { currentKeyboard } from '../keyboard.js'
 
@@ -37,6 +49,11 @@ type Options = AnimateOptions | SpringName
 export type AnimateValue =
   PresetName | Keyframes | readonly [animation: PresetName | Keyframes, options?: Options]
 
+/** The gradient, alone or paired with the transition for later changes. */
+export type GradientValue =
+  | GradientOptions
+  | readonly [gradient: GradientOptions, transition?: Transition | SpringName]
+
 /** The pressed keyframes, alone or paired with a transition. */
 export type PressValue = Keyframes | readonly [pressed: Keyframes, options?: Options]
 
@@ -53,6 +70,7 @@ export interface TransitionProps {
 const animations = new WeakMap<object, PlaybackAnimation>()
 const scopes = new WeakMap<object, MotionScope>()
 const removers = new WeakMap<object, () => void>()
+const gradients = new WeakMap<object, { gradient: Gradient; colors: number }>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -137,6 +155,47 @@ export const vPress: ObjectDirective<Host, PressValue | undefined> = {
   },
 }
 
+function paint(el: Host, value: GradientValue, animated: boolean) {
+  const [options, transition] = (Array.isArray(value) ? value : [value]) as [
+    GradientOptions,
+    (Transition | SpringName)?,
+  ]
+  const current = gradients.get(el)
+  const colors = options.colors.length
+  if (current && current.gradient.type === options.type) {
+    const { type, ...values } = options
+    if (animated && current.colors === colors)
+      current.gradient.animate(values, transition)
+    else current.gradient.set(values)
+    current.colors = colors
+    return
+  }
+  current?.gradient.remove()
+  gradients.set(el, { gradient: gradient(el, options), colors })
+}
+
+/**
+ * Paints a native gradient behind the element, and animates to the new values when they change.
+ * A change of type, or of the number of colors, applies at once.
+ *
+ * ```vue
+ * <GridLayout v-gradient="{ type: 'linear', colors: ['#18181B', '#3F3F46'], angle: 135 }" />
+ * <GridLayout v-gradient="[{ type: 'linear', colors: active ? hot : cold }, 'snappy']" />
+ * ```
+ */
+export const vGradient: ObjectDirective<Host, GradientValue> = {
+  mounted(el, { value }) {
+    paint(el, value, false)
+  },
+  updated(el, { value, oldValue }) {
+    if (!same(value, oldValue)) paint(el, value, true)
+  },
+  unmounted(el) {
+    gradients.get(el)?.gradient.remove()
+    gradients.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) => {
@@ -195,10 +254,11 @@ export const JoltTransition = defineComponent({
   },
 })
 
-/** Registers `v-animate`, `v-press` and `JoltTransition` on the app. */
+/** Registers `v-animate`, `v-press`, `v-gradient` and `JoltTransition` on the app. */
 export function install(app: App) {
   app.directive('animate', vAnimate)
   app.directive('press', vPress)
+  app.directive('gradient', vGradient)
   app.component('JoltTransition', JoltTransition)
 }
 
@@ -229,3 +289,40 @@ export function useKeyboard(): Readonly<Ref<KeyboardState>> {
   onUnmounted(off)
   return readonly(keyboard) as Readonly<Ref<KeyboardState>>
 }
+
+/** Call in setup(): a motion value that stops when the component unmounts. */
+export function useMotionValue(initial = 0): MotionValue {
+  const value = motionValue(initial)
+  onUnmounted(() => stop(value))
+  return value
+}
+
+/**
+ * Call in setup(): a template ref that binds motion values to the element on mount
+ * and releases them on unmount. A recreated element picks the values up again.
+ */
+export function useBinding(bindings: Bindings): (element: Target | null) => void {
+  let element: Target | null = null
+  let release: (() => void) | undefined
+  onUnmounted(() => {
+    release?.()
+    release = undefined
+  })
+  return (next) => {
+    if (next === element) return
+    release?.()
+    release = undefined
+    element = next
+    if (next) release = bind(next, bindings)
+  }
+}
+
+/**
+ * Call in setup(): a scroll offset as a value. Pass its `ref` to the ScrollView's
+ * template ref; it stops following when the component unmounts.
+ */
+export function useScrollValue(options?: { axis?: 'x' | 'y' }): ScrollValue {
+  const value = scrollValue(null, options)
+  onUnmounted(() => value.dispose())
+  return value
+}