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

package/src/vue/index.ts

@@ -5,22 +5,44 @@ import {
   onUnmounted,
   onActivated,
   onDeactivated,
+  readonly,
+  shallowRef,
   type App,
   type BaseTransitionProps,
   type NSVElement,
   type ObjectDirective,
   type PropType,
+  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,
   type AnimateOptions,
   type Keyframes,
   type PlaybackAnimation,
   type PresetName,
   type SpringName,
+  type Gradient,
+  type GradientOptions,
+  type Transition,
 } from '../index.js'
+import { isDerived } from '../motion-value.js'
+import { prepareGradient, type GradientValues } from '../gradient.js'
+import { currentKeyboard } from '../keyboard.js'
 
 type Host = NSVElement
 type Options = AnimateOptions | SpringName
@@ -29,6 +51,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]
 
@@ -45,6 +72,10 @@ 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; release?: () => void }
+>()
 
 function split<T>(
   value: T | readonly [T, Options?],
@@ -56,6 +87,7 @@ function split<T>(
 
 function same(a: unknown, b: unknown): boolean {
   if (Object.is(a, b)) return true
+  if (isDerived(a) || isDerived(b)) return false
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
     return false
   if (Array.isArray(a) !== Array.isArray(b)) return false
@@ -129,6 +161,65 @@ 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)
+  prepareGradient(options)
+  const colors = options.colors.length
+  const hasBindings = [
+    options.angle,
+    options.radius,
+    options.center?.x,
+    options.center?.y,
+    ...options.colors,
+    ...(options.stops ?? []),
+  ].some(isDerived)
+  if (current && current.gradient.type === options.type) {
+    const { type, ...values } = options
+    const previous = current.release
+    if (hasBindings) current.release = current.gradient.bind(values)
+    else {
+      if (animated && current.colors === colors)
+        current.gradient.animate(values as GradientValues, transition)
+      else current.gradient.set(values as GradientValues)
+      current.release = undefined
+    }
+    previous?.()
+    current.colors = colors
+    return
+  }
+  current?.gradient.remove()
+  // Track directive ownership explicitly, including bindings omitted on a later update.
+  const made = gradient(el, options)
+  const release = hasBindings ? made.bind(options) : undefined
+  gradients.set(el, { gradient: made, colors, release })
+}
+
+/**
+ * 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) => {
@@ -187,10 +278,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)
 }
 
@@ -204,3 +296,57 @@ export function useMotionScope(): MotionScope {
   onActivated(() => scope.resume())
   return scope
 }
+
+/** Call in setup(): whether motion is reduced, kept up to date until the component unmounts. */
+export function useReducedMotion(): Readonly<Ref<boolean>> {
+  const reduced = shallowRef(reducedMotion())
+  const off = onReducedMotion((value) => (reduced.value = value))
+  onUnmounted(off)
+  return readonly(reduced)
+}
+
+/** Call in setup(): the keyboard's state, kept up to date until the component unmounts. */
+export function useKeyboard(): Readonly<Ref<KeyboardState>> {
+  const keyboard = shallowRef<KeyboardState>(currentKeyboard())
+  const off = onKeyboard((next) => (keyboard.value = next))
+  keyboard.value = currentKeyboard()
+  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
+}

package/src/zoomable.ts

@@ -12,7 +12,7 @@ export interface PhotoDismissal {
   readonly velocity: number
   /** Return to the viewer. False means this intent is obsolete. */
   cancel(): boolean
-  /** Release the controller. Navigate only when this returns true. */
+  /** Release explicitly when the image outlives its route. Unloading also disposes it. */
   complete(): boolean
 }
 export interface ZoomableOptions {