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

package/src/vue/index.ts

@@ -0,0 +1,231 @@
+import {
+  BaseTransition,
+  defineComponent,
+  h,
+  onUnmounted,
+  onActivated,
+  onDeactivated,
+  readonly,
+  shallowRef,
+  type App,
+  type BaseTransitionProps,
+  type NSVElement,
+  type ObjectDirective,
+  type PropType,
+  type Ref,
+} from 'nativescript-vue'
+import {
+  press,
+  motionScope,
+  onKeyboard,
+  onReducedMotion,
+  reducedMotion,
+  type KeyboardState,
+  type MotionScope,
+  type AnimateOptions,
+  type Keyframes,
+  type PlaybackAnimation,
+  type PresetName,
+  type SpringName,
+} from '../index.js'
+import { currentKeyboard } from '../keyboard.js'
+
+type Host = NSVElement
+type Options = AnimateOptions | SpringName
+
+/** A preset name or keyframes, alone or paired with a transition. */
+export type AnimateValue =
+  PresetName | Keyframes | readonly [animation: PresetName | Keyframes, options?: Options]
+
+/** The pressed keyframes, alone or paired with a transition. */
+export type PressValue = Keyframes | readonly [pressed: Keyframes, options?: Options]
+
+export interface TransitionProps {
+  /** Played when the child is inserted. */
+  enter?: AnimateValue
+  /** Played before the child is removed. */
+  leave?: AnimateValue
+  /** Also play `enter` on the first render. */
+  appear?: boolean
+  mode?: 'in-out' | 'out-in' | 'default'
+}
+
+const animations = new WeakMap<object, PlaybackAnimation>()
+const scopes = new WeakMap<object, MotionScope>()
+const removers = new WeakMap<object, () => void>()
+
+function split<T>(
+  value: T | readonly [T, Options?],
+): [animation: T, options: Options | undefined] {
+  return Array.isArray(value)
+    ? [value[0] as T, value[1] as Options | undefined]
+    : [value as T, undefined]
+}
+
+function same(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+    return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const keys = Object.keys(a)
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) =>
+      same((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]),
+    )
+  )
+}
+
+function play(el: Host, value: AnimateValue) {
+  const [animation, options] = split<PresetName | Keyframes>(value)
+  let scope = scopes.get(el)
+  if (!scope) scopes.set(el, (scope = motionScope()))
+  const handle = scope.animate(el, animation, options)
+  animations.set(el, handle)
+  return handle
+}
+
+function cancel(el: Host) {
+  scopes.get(el)?.dispose()
+  scopes.delete(el)
+  animations.delete(el)
+}
+
+function attach(el: Host, value: PressValue | undefined) {
+  const [pressed, options] = value === undefined ? [] : split<Keyframes>(value)
+  removers.set(el, press(el, pressed, options))
+}
+
+/**
+ * Plays an animation when the element mounts, and again whenever the value changes.
+ *
+ * ```vue
+ * <Label v-animate="'fadeInUp'" />
+ * <Label v-animate="['popIn', { delay: 200 }]" />
+ * ```
+ */
+export const vAnimate: ObjectDirective<Host, AnimateValue> = {
+  mounted(el, { value }) {
+    play(el, value)
+  },
+  updated(el, { value, oldValue }) {
+    if (!same(value, oldValue)) play(el, value)
+  },
+  unmounted: cancel,
+}
+
+/**
+ * Press feedback while a finger is on the element.
+ *
+ * ```vue
+ * <GridLayout v-press />
+ * <GridLayout v-press="{ scale: 0.95 }" />
+ * ```
+ */
+export const vPress: ObjectDirective<Host, PressValue | undefined> = {
+  mounted(el, { value }) {
+    attach(el, value)
+  },
+  updated(el, { value, oldValue }) {
+    if (same(value, oldValue)) return
+    removers.get(el)?.()
+    attach(el, value)
+  },
+  unmounted(el) {
+    removers.get(el)?.()
+    removers.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) => {
+    if (value === undefined) {
+      done()
+      return
+    }
+    const handle = play(el, value)
+    void handle.finished.then(() => {
+      if (animations.get(el) === handle) animations.delete(el)
+      done()
+    })
+  }
+  const hooks: BaseTransitionProps<Host> = {
+    onEnter: run(props.enter),
+    onEnterCancelled: cancel,
+    onLeave: run(props.leave),
+    onLeaveCancelled: cancel,
+  }
+  if (props.appear) {
+    hooks.onAppear = hooks.onEnter
+    hooks.onAppearCancelled = cancel
+  }
+  return hooks
+}
+
+const value = {
+  type: [String, Object, Array] as PropType<AnimateValue>,
+  default: undefined,
+}
+
+/**
+ * Animates a child in and out. Vue keeps the element until the leave animation settles.
+ *
+ * ```vue
+ * <JoltTransition enter="popIn" leave="fadeOut">
+ *   <Label v-if="visible" text="Saved" />
+ * </JoltTransition>
+ * ```
+ */
+export const JoltTransition = defineComponent({
+  name: 'JoltTransition',
+  props: {
+    enter: value,
+    leave: value,
+    appear: Boolean,
+    mode: { type: String as PropType<TransitionProps['mode']>, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () =>
+      h(
+        BaseTransition,
+        { ...transitionHooks(props), mode: props.mode, appear: props.appear },
+        slots,
+      )
+  },
+})
+
+/** Registers `v-animate`, `v-press` and `JoltTransition` on the app. */
+export function install(app: App) {
+  app.directive('animate', vAnimate)
+  app.directive('press', vPress)
+  app.component('JoltTransition', JoltTransition)
+}
+
+export default { install }
+
+/** Call in setup(): suspend cached components and dispose only on actual unmount. */
+export function useMotionScope(): MotionScope {
+  const scope = motionScope()
+  onUnmounted(() => scope.dispose())
+  onDeactivated(() => scope.suspend())
+  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>>
+}

package/src/zoom-native.ts

@@ -0,0 +1,124 @@
+import { Utils, isIOS, type Image, type View } from '@nativescript/core'
+
+export interface ZoomSnapshot {
+  x: number
+  y: number
+  scale: number
+  progress: number
+  pending: boolean
+}
+export interface ZoomDriver {
+  readonly native: object
+  readonly state: ZoomSnapshot
+  zoom(scale: number, x: number, y: number, animated: boolean): void
+  reset(animated: boolean): void
+  requestDismiss(): void
+  setReduced(value: boolean): void
+  setActive(value: boolean): void
+  layout(): void
+  stop(): void
+}
+export interface ZoomSettings {
+  minimum: number
+  maximum: number
+  doubleTap: number
+  dismiss: boolean
+  reduced: boolean
+  backdrop?: View
+  chrome?: View
+}
+
+export function createZoomDriver(
+  image: Image,
+  viewport: View,
+  options: ZoomSettings,
+  dismiss: (
+    x: number,
+    y: number,
+    scale: number,
+    velocity: number,
+    progress: number,
+  ) => void,
+  settled: (x: number, y: number, scale: number) => void,
+): ZoomDriver {
+  const { minimum, maximum, doubleTap, reduced, backdrop, chrome } = options
+  if (isIOS) {
+    const native =
+      JoltPhotoZoom.attachImageViewportMinimumMaximumDoubleTapDismissReducedBackdropChromeOnDismissOnSettled(
+        image.nativeViewProtected,
+        viewport.nativeViewProtected,
+        minimum,
+        maximum,
+        doubleTap,
+        options.dismiss,
+        reduced,
+        backdrop?.nativeViewProtected ?? null,
+        chrome?.nativeViewProtected ?? null,
+        dismiss,
+        settled,
+      )
+    return {
+      native,
+      get state() {
+        return {
+          x: native.x,
+          y: native.y,
+          scale: native.scale,
+          progress: native.dismissProgress,
+          pending: native.dismissPending,
+        }
+      },
+      zoom: (s, x, y, a) => native.zoomFocusXFocusYAnimated(s, x, y, a),
+      reset: (a) => native.reset(a),
+      requestDismiss: () => native.requestDismiss(),
+      setReduced: (r) => native.setReduced(r),
+      setActive: (a) => native.setActive(a),
+      layout: () => native.layout(),
+      stop: () => native.stop(),
+    }
+  }
+  const density = Utils.layout.getDisplayDensity()
+  const source = image.imageSource!
+  const angle = Math.abs((source.rotationAngle ?? 0) % 180)
+  const swapped = angle > 45 && angle < 135
+  const native = new org.rafaelaugusto.jolt.PhotoZoom(
+    image.nativeViewProtected,
+    viewport.nativeViewProtected,
+    swapped ? source.height : source.width,
+    swapped ? source.width : source.height,
+    minimum,
+    maximum,
+    doubleTap,
+    options.dismiss,
+    reduced,
+    backdrop?.nativeViewProtected ?? null,
+    chrome?.nativeViewProtected ?? null,
+    (viewport as View & { touchListener?: android.view.View.OnTouchListener })
+      .touchListener ?? null,
+    (image as View & { touchListener?: android.view.View.OnTouchListener })
+      .touchListener ?? null,
+    new org.rafaelaugusto.jolt.PhotoZoom.Listener({
+      onDismiss: dismiss,
+      onSettled: settled,
+    }),
+  )
+  return {
+    native,
+    get state() {
+      return {
+        x: native.getX(),
+        y: native.getY(),
+        scale: native.getScale(),
+        progress: native.getDismissProgress(),
+        pending: native.isDismissPending(),
+      }
+    },
+    zoom: (s, x, y, a) => native.zoom(s, x * density, y * density, a),
+    reset: (a) => native.reset(a),
+    requestDismiss: () => native.requestDismiss(),
+    setReduced: (r) => native.setReduced(r),
+    setActive: (a) => native.setActive(a),
+    layout: () => {},
+    stop: () => native.stop(),
+  }
+}

package/src/zoomable.ts

@@ -0,0 +1,330 @@
+import { Application, Image, isIOS, type View } from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import { reducedMotion } from './config.js'
+import { ownImage } from './image-owner.js'
+import { createZoomDriver, type ZoomDriver, type ZoomSnapshot } from './zoom-native.js'
+import type { Target } from './types.js'
+
+export type ZoomState = Readonly<ZoomSnapshot>
+export interface PhotoDismissal {
+  readonly state: ZoomState
+  /** Release velocity in viewport-local DIPs per second. */
+  readonly velocity: number
+  /** Return to the viewer. False means this intent is obsolete. */
+  cancel(): boolean
+  /** Release the controller. Navigate only when this returns true. */
+  complete(): boolean
+}
+export interface ZoomableOptions {
+  /** Direct parent of the Image. Its bounds are the clipping/pointer viewport. */
+  viewport?: Target
+  /** Relative zoom range. Defaults to [1, 5]; minimum must be >= 1. */
+  scale?: readonly [number, number]
+  /** Double-tap zoom, clamped into the configured range. Defaults to 2.5. */
+  doubleTap?: number
+  dismiss?: 'vertical' | false
+  /** These views follow dismissal natively; no JS progress callback is needed. */
+  backdrop?: Target
+  chrome?: Target
+  /** One terminal intent per drag/programmatic close. App/router owns navigation. */
+  onDismiss?: (dismissal: PhotoDismissal) => void
+  /** Called at rest, never on each pointer/frame update. */
+  onSettled?: (state: ZoomState) => void
+  /** Setup failed after loading; resources are disposed before this callback. */
+  onError?: (error: Error) => void
+}
+export interface Zoomable {
+  readonly ready: boolean
+  readonly error: Error | undefined
+  readonly state: ZoomState
+  /** Native adapter entry point for native navigation integrations. */
+  readonly nativeController: object | undefined
+  zoomTo(scale: number, focus?: { x: number; y: number }, animated?: boolean): void
+  reset(animated?: boolean): void
+  requestDismiss(): void
+  cancelDismiss(): void
+  dispose(): void
+}
+
+/** Makes an Image interactive without per-frame JS. Owns its transforms until disposed. */
+export function zoomable(target: Target, options: ZoomableOptions = {}): Zoomable {
+  const image = toView(target)
+  if (!(image instanceof Image))
+    throw new TypeError('zoomable() expects a NativeScript Image.')
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Zoom options must be an object.')
+  const viewport = options.viewport
+    ? toView(options.viewport)
+    : (image.parent as View | undefined)
+  if (!viewport)
+    throw new TypeError('A zoom viewport is required before the image has a parent.')
+  const scale = options.scale ?? [1, 5]
+  if (
+    !Array.isArray(scale) ||
+    scale.length !== 2 ||
+    !scale.every(Number.isFinite) ||
+    scale[0]! < 1 ||
+    scale[1]! < scale[0]!
+  )
+    throw new RangeError(
+      'Zoom scale must be [minimum, maximum], with 1 <= minimum <= maximum.',
+    )
+  const doubleTap = options.doubleTap ?? 2.5
+  if (!Number.isFinite(doubleTap) || doubleTap < 1)
+    throw new RangeError('Double-tap zoom must be a finite number >= 1.')
+  if (
+    options.dismiss !== undefined &&
+    options.dismiss !== false &&
+    options.dismiss !== 'vertical'
+  )
+    throw new TypeError("Dismiss must be 'vertical' or false.")
+  for (const callback of [options.onDismiss, options.onSettled, options.onError])
+    if (callback !== undefined && typeof callback !== 'function')
+      throw new TypeError('Zoom callbacks must be functions.')
+  const backdrop = options.backdrop ? toView(options.backdrop) : undefined
+  const chrome = options.chrome ? toView(options.chrome) : undefined
+  if (
+    backdrop === image ||
+    chrome === image ||
+    backdrop === viewport ||
+    chrome === viewport
+  )
+    throw new TypeError(
+      'Dismissal backdrop/chrome must be separate from the image and viewport.',
+    )
+  if (image.parent && image.parent !== viewport)
+    throw new TypeError('The zoom viewport must be the image’s direct parent.')
+  if (
+    image.rotate ||
+    image.rotateX ||
+    image.rotateY ||
+    image.scaleX <= 0 ||
+    image.scaleY <= 0
+  )
+    throw new TypeError(
+      'Zoom supports positive axis-aligned image transforms; rotate an ancestor instead.',
+    )
+  return new Photo(image, viewport, { ...options, doubleTap, scale, backdrop, chrome })
+}
+
+class Photo implements Zoomable {
+  private failure: Error | undefined
+  private suspended = false
+  private driver: ZoomDriver | undefined
+  private stopped = false
+  private queued = false
+  private releaseOwnership: () => void = () => {}
+  private generation = 0
+  private reduceObserver:
+    ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+  private latest: ZoomSnapshot
+  constructor(
+    private readonly image: Image,
+    private readonly viewport: View,
+    private readonly options: Omit<ZoomableOptions, 'backdrop' | 'chrome'> & {
+      scale: readonly [number, number]
+      doubleTap: number
+      backdrop?: View
+      chrome?: View
+    },
+  ) {
+    this.latest = { x: 0, y: 0, scale: options.scale[0], progress: 0, pending: false }
+    this.releaseOwnership = ownImage(image, this.dispose)
+    stop(image, ['x', 'y', 'scaleX', 'scaleY'])
+    for (const view of [image, viewport]) {
+      view.on('loaded', this.schedule)
+      view.on('layoutChanged', this.schedule)
+      view.on('unloaded', this.dispose)
+    }
+    image.on('imageSourceChange', this.sourceChanged)
+    image.on('stretchChange', this.sourceChanged)
+    Application.on(Application.suspendEvent, this.suspend)
+    Application.on(Application.resumeEvent, this.resume)
+    if (isIOS)
+      this.reduceObserver = Application.ios.addNotificationObserver(
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+        this.preferences,
+      )
+    this.schedule()
+  }
+  get ready() {
+    return !!this.driver
+  }
+  get error() {
+    return this.failure
+  }
+  get state(): ZoomState {
+    return { ...(this.driver?.state ?? this.latest) }
+  }
+  get nativeController() {
+    return this.driver?.native
+  }
+  zoomTo(value: number, focus?: { x: number; y: number }, animated = true) {
+    if (
+      !Number.isFinite(value) ||
+      value < this.options.scale[0] ||
+      value > this.options.scale[1]
+    )
+      throw new RangeError('Zoom must be within the configured scale range.')
+    if (focus && (!Number.isFinite(focus.x) || !Number.isFinite(focus.y)))
+      throw new RangeError('Zoom focus must be finite.')
+    if (this.stopped) return
+    const size = this.viewport.getActualSize()
+    this.driver?.zoom(
+      value,
+      focus?.x ?? size.width / 2,
+      focus?.y ?? size.height / 2,
+      animated,
+    )
+  }
+  reset(animated = true) {
+    this.generation++
+    this.driver?.reset(animated)
+  }
+  requestDismiss() {
+    this.driver?.requestDismiss()
+  }
+  cancelDismiss() {
+    this.reset(true)
+  }
+  dispose = () => {
+    if (this.stopped) return
+    this.stopped = true
+    this.generation++
+    this.latest = {
+      x: 0,
+      y: 0,
+      scale: this.options.scale[0],
+      progress: 0,
+      pending: false,
+    }
+    this.driver?.stop()
+    this.driver = undefined
+    this.releaseOwnership()
+    for (const view of [this.image, this.viewport]) {
+      view.off('loaded', this.schedule)
+      view.off('layoutChanged', this.schedule)
+      view.off('unloaded', this.dispose)
+    }
+    this.image.off('imageSourceChange', this.sourceChanged)
+    this.image.off('stretchChange', this.sourceChanged)
+    Application.off(Application.suspendEvent, this.suspend)
+    Application.off(Application.resumeEvent, this.resume)
+    if (this.reduceObserver)
+      Application.ios.removeNotificationObserver(
+        this.reduceObserver,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+    this.reduceObserver = undefined
+  }
+  private dismissed = (
+    x: number,
+    y: number,
+    scale: number,
+    velocity: number,
+    progress: number,
+  ) => {
+    if (this.stopped) return
+    const generation = ++this.generation
+    const valid = () => !this.stopped && generation === this.generation
+    const dismissal: PhotoDismissal = {
+      state: { x, y, scale, progress, pending: true },
+      velocity,
+      cancel: () => {
+        if (!valid()) return false
+        this.cancelDismiss()
+        return true
+      },
+      complete: () => {
+        if (!valid()) return false
+        this.dispose()
+        return true
+      },
+    }
+    if (this.options.onDismiss) this.options.onDismiss(dismissal)
+    else dismissal.cancel()
+  }
+  private settled = (x: number, y: number, scale: number) => {
+    if (this.stopped) return
+    this.generation++
+    this.latest = { x, y, scale, progress: 0, pending: false }
+    this.options.onSettled?.({ ...this.latest })
+  }
+  private sourceChanged = () => {
+    this.generation++
+    this.driver?.stop()
+    this.driver = undefined
+    this.schedule()
+  }
+  private suspend = () => {
+    this.suspended = true
+    this.generation++
+    this.driver?.setActive(false)
+  }
+  private resume = () => {
+    this.suspended = false
+    this.preferences()
+    this.driver?.setActive(true)
+    this.schedule()
+  }
+  private preferences = () => this.driver?.setReduced(reducedMotion())
+  private schedule = () => {
+    if (this.stopped || this.queued) return
+    this.queued = true
+    void Promise.resolve()
+      .then(() => {
+        this.queued = false
+        if (
+          this.stopped ||
+          this.suspended ||
+          !this.image.isLoaded ||
+          !this.viewport.isLoaded
+        )
+          return
+        if (this.driver) {
+          this.driver.layout()
+          return
+        }
+        if (this.image.parent !== this.viewport)
+          throw new TypeError('Zoom viewport must remain the direct image parent.')
+        const size = this.viewport.getActualSize()
+        const imageSize = this.image.getActualSize(),
+          source = this.image.imageSource
+        if (
+          size.width <= 0 ||
+          size.height <= 0 ||
+          imageSize.width <= 0 ||
+          imageSize.height <= 0 ||
+          !source ||
+          !Number.isFinite(source.width) ||
+          !Number.isFinite(source.height) ||
+          source.width <= 0 ||
+          source.height <= 0
+        )
+          return
+        if (isIOS && typeof JoltPhotoZoom === 'undefined')
+          throw new Error('Rebuild the native app to install Jolt photo gestures.')
+        this.driver = createZoomDriver(
+          this.image,
+          this.viewport,
+          {
+            minimum: this.options.scale[0],
+            maximum: this.options.scale[1],
+            doubleTap: this.options.doubleTap,
+            dismiss: this.options.dismiss === 'vertical',
+            reduced: reducedMotion(),
+            backdrop: this.options.backdrop,
+            chrome: this.options.chrome,
+          },
+          this.dismissed,
+          this.settled,
+        )
+      })
+      .catch((error: unknown) => {
+        if (this.stopped) return
+        this.failure = error instanceof Error ? error : new Error(String(error))
+        this.dispose()
+        this.options.onError?.(this.failure)
+      })
+  }
+}