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

package/src/keyboard.ts

@@ -1,5 +1,7 @@
 import { Application, Utils, isAndroid, isIOS, type View } from '@nativescript/core'
-import { stop, toView } from './animate.js'
+import { animate, stop, toView } from './animate.js'
+import type { EasingFunction, EasingName } from './easing.js'
+import type { Spring, Transition, Tween } from './transition.js'
 import type { Target } from './types.js'
 
 export interface KeyboardOptions {
@@ -7,7 +9,180 @@ export interface KeyboardOptions {
   offset?: number
 }
 
+export interface KeyboardState {
+  /** Whether a docked software keyboard covers part of the window. */
+  readonly visible: boolean
+  /** DIPs of the window the keyboard covers, from its bottom edge. Zero when hidden or floating. */
+  readonly height: number
+  /** Milliseconds the keyboard takes to get there. Zero when it changes at once. */
+  readonly duration: number
+  /** The keyboard's own timing, to pass to `animate()` and move in step with it. */
+  readonly transition: Transition
+}
+
 const BEGIN_FROM_CURRENT_STATE = 4
+const IOS_KEYBOARD_CURVE = 7
+// Measured: Core Animation plays the keyboard's spring (stiffness 1000, mass 3) critically damped in 500 ms.
+const iosKeyboard: Spring = {
+  type: 'spring',
+  stiffness: 1000,
+  mass: 3,
+  damping: 2 * Math.sqrt(3000),
+}
+const iosCurves: readonly EasingName[] = ['easeInOut', 'easeIn', 'easeOut', 'linear']
+// Before Android 11 nothing reports the keyboard's timing. Measured on an Android 9 emulator,
+// its window fades and slides into place in about 150 ms, decelerating, and leaves as quickly.
+const LEGACY_DURATION = 150
+const legacyShow: Tween = { duration: LEGACY_DURATION, ease: 'quadOut' }
+const legacyHide: Tween = { duration: LEGACY_DURATION, ease: 'quadIn' }
+const legacy = () => isAndroid && android.os.Build.VERSION.SDK_INT < 30
+const hidden: KeyboardState = Object.freeze({
+  visible: false,
+  height: 0,
+  duration: 0,
+  transition: { duration: 0 },
+})
+
+const listeners = new Set<(keyboard: KeyboardState) => void>()
+let state = hidden
+let unwatch: (() => void) | undefined
+
+/**
+ * Calls back whenever the keyboard shows, hides or changes height, with how much
+ * of the window it covers and its timing. Returns a cleanup function.
+ *
+ * ```ts
+ * const off = onKeyboard(({ visible, transition }) => {
+ *   animate(header, { scale: visible ? 0.8 : 1 }, transition)
+ * })
+ * ```
+ */
+export function onKeyboard(callback: (keyboard: KeyboardState) => void): () => void {
+  if (typeof callback !== 'function')
+    throw new TypeError('onKeyboard() takes a callback.')
+  const listener = (keyboard: KeyboardState) => callback(keyboard)
+  if (listeners.size === 0) {
+    state = hidden
+    unwatch = isIOS ? watchIOS() : isAndroid ? watchAndroid() : undefined
+  }
+  listeners.add(listener)
+  return () => {
+    if (!listeners.delete(listener) || listeners.size > 0) return
+    unwatch?.()
+    unwatch = undefined
+  }
+}
+
+/** The last state reported while someone listens. */
+export function currentKeyboard(): KeyboardState {
+  return state
+}
+
+function update(height: number, duration: number, transition: Transition) {
+  if (height === state.height) return
+  state = Object.freeze({ visible: height > 0, height, duration, transition })
+  for (const listener of [...listeners]) listener(state)
+}
+
+function watchIOS() {
+  const name = UIKeyboardWillChangeFrameNotification
+  const observer = Application.ios.addNotificationObserver(
+    name,
+    (notification: NSNotification) => {
+      const info = notification.userInfo
+      const window = Application.ios.window
+      const end = info?.objectForKey(UIKeyboardFrameEndUserInfoKey)?.CGRectValue as
+        CGRect | undefined
+      if (!info || !window || !end) return
+      const frame = window.convertRectFromWindow(end, null)
+      const bottom = window.bounds.size.height
+      const docked =
+        frame.size.height > 0 &&
+        frame.origin.y < bottom &&
+        frame.origin.y + frame.size.height >= bottom - 0.5
+      const reported = numberIn(info, UIKeyboardAnimationDurationUserInfoKey) * 1000
+      const curve = numberIn(info, UIKeyboardAnimationCurveUserInfoKey)
+      const height = docked ? bottom - frame.origin.y : 0
+      if (!reported) return update(height, 0, { duration: 0 })
+      if (curve === IOS_KEYBOARD_CURVE) return update(height, 500, iosKeyboard)
+      update(height, reported, {
+        duration: reported,
+        ease: iosCurves[curve] ?? 'easeInOut',
+      })
+    },
+  )
+  return () => Application.ios.removeNotificationObserver(observer, name)
+}
+
+function watchAndroid() {
+  const density = Utils.layout.getDisplayDensity()
+  let observer:
+    | org.rafaelaugusto.jolt.KeyboardObserver
+    | org.rafaelaugusto.jolt.KeyboardFrame
+    | undefined
+  let stopped = false
+  const attach = () => {
+    Application.off(Application.launchEvent, attach)
+    if (stopped || observer) return
+    const activity =
+      Application.android.foregroundActivity ?? Application.android.startActivity
+    const root = activity?.getWindow()?.getDecorView()
+    if (!root) return
+    try {
+      observer = legacy()
+        ? new org.rafaelaugusto.jolt.KeyboardFrame(
+            root,
+            new org.rafaelaugusto.jolt.KeyboardFrame.Listener({
+              onChange: (height) =>
+                update(
+                  height / density,
+                  LEGACY_DURATION,
+                  height ? legacyShow : legacyHide,
+                ),
+            }),
+          )
+        : new org.rafaelaugusto.jolt.KeyboardObserver(
+            root,
+            new org.rafaelaugusto.jolt.KeyboardObserver.Listener({
+              onChange: (height, duration, curve) =>
+                update(
+                  height / density,
+                  duration,
+                  duration
+                    ? { duration, ease: curve ? sampled(curve) : 'linear' }
+                    : { duration: 0 },
+                ),
+            }),
+          )
+    } catch {
+      // A JS-only update cannot install the native plugin.
+      return
+    }
+    observer.attach()
+    const height = observer.height() / density
+    if (height > 0) state = Object.freeze({ ...hidden, visible: true, height })
+  }
+  if (Application.android.foregroundActivity ?? Application.android.startActivity)
+    attach()
+  else Application.on(Application.launchEvent, attach)
+  return () => {
+    stopped = true
+    Application.off(Application.launchEvent, attach)
+    observer?.detach()
+    observer = undefined
+  }
+}
+
+function sampled(curve: ArrayLike<number>): EasingFunction {
+  const values = Array.from({ length: curve.length }, (_, i) => curve[i]!)
+  const last = values.length - 1
+  if (last < 1) return (progress) => progress
+  return (progress) => {
+    const position = Math.min(Math.max(progress, 0), 1) * last
+    const index = Math.min(Math.floor(position), last - 1)
+    return values[index]! + (values[index + 1]! - values[index]!) * (position - index)
+  }
+}
 
 /**
  * Lifts the view by its overlap with the software keyboard, at the keyboard's
@@ -55,12 +230,9 @@ function followIOS(view: View, offset: number) {
     const apply = () => {
       view.translateY = overlap ? -overlap : 0
     }
-    const duration = info.objectForKey(UIKeyboardAnimationDurationUserInfoKey)
-      ?.doubleValue as number | undefined
+    const duration = numberIn(info, UIKeyboardAnimationDurationUserInfoKey)
     if (!duration) return apply()
-    const curve =
-      (info.objectForKey(UIKeyboardAnimationCurveUserInfoKey)?.integerValue as
-        number | undefined) ?? 0
+    const curve = numberIn(info, UIKeyboardAnimationCurveUserInfoKey)
     // The keyboard's curve is private; shifted into the options it still applies.
     UIView.animateWithDurationDelayOptionsAnimationsCompletion(
       duration,
@@ -89,7 +261,7 @@ function followIOS(view: View, offset: number) {
 }
 
 function followAndroid(view: View, offset: number) {
-  if (android.os.Build.VERSION.SDK_INT < 30) return () => {}
+  if (legacy()) return followLegacy(view, offset)
   const density = Utils.layout.getDisplayDensity()
   let disposed = false
   let follower: org.rafaelaugusto.jolt.KeyboardFollower | undefined
@@ -130,3 +302,55 @@ function followAndroid(view: View, offset: number) {
   if (view.isLoaded) attach()
   return cleanup
 }
+
+/** Android 7 to 10: no frame-by-frame progress, so the view animates with the keyboard's usual timing. */
+function followLegacy(view: View, offset: number) {
+  const density = Utils.layout.getDisplayDensity()
+  let disposed = false
+  let follower: org.rafaelaugusto.jolt.KeyboardFrameFollower | undefined
+  const attach = () => {
+    if (disposed || follower) return
+    const native = view.nativeViewProtected as android.view.View | undefined
+    if (!native) return
+    try {
+      follower = new org.rafaelaugusto.jolt.KeyboardFrameFollower(
+        native,
+        offset * density,
+        new org.rafaelaugusto.jolt.KeyboardFrameFollower.Listener({
+          onMove: (from, to, keyboard) => {
+            stop(view, ['y'])
+            view.translateY = from / density
+            animate(view, { y: to / density }, keyboard ? legacyShow : legacyHide)
+          },
+        }),
+      )
+    } catch {
+      // A JS-only update cannot install the native plugin. Leave the platform's resize in place.
+      return
+    }
+    follower.attach()
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    view.off('loaded', attach)
+    view.off('unloaded', cleanup)
+    if (follower) {
+      follower.detach()
+      follower = undefined
+      stop(view, ['y'])
+      view.translateY = 0
+    }
+  }
+  view.on('loaded', attach)
+  view.on('unloaded', cleanup)
+  if (view.isLoaded) attach()
+  return cleanup
+}
+
+/** The runtime hands NSNumber values over as plain numbers. */
+function numberIn(info: NSDictionary<unknown, unknown>, key: string): number {
+  const value = info.objectForKey(key) as number | NSNumber | null | undefined
+  if (typeof value === 'number') return value
+  return value?.doubleValue ?? 0
+}

package/src/live-spring-driver.ts

@@ -0,0 +1,181 @@
+import { isAndroid, type View } from '@nativescript/core'
+import type { NumericProperty } from './properties.js'
+import { retainInteractiveLayout } from './driver/ios-layout.js'
+
+export interface LiveMapping {
+  input: readonly number[]
+  output: readonly number[]
+  clamp: boolean
+}
+export interface LiveSpringPhysics {
+  stiffness: number
+  damping: number
+  mass: number
+  restDelta: number
+  restSpeed: number
+}
+export interface LiveInput {
+  value: number
+  running: boolean
+  elapsed: number
+  duration: number
+  delay: number
+  repeat: number
+  reverse: boolean
+  to: number
+  times: readonly number[]
+  values: readonly number[]
+}
+export interface LiveBinding {
+  value(): number
+  layers(inputs: readonly LiveInput[]): void
+  cancel(): void
+}
+export interface LiveNode {
+  position(): number
+  velocity(): number
+  moving(): boolean
+  follow(source: LiveNode, maps: readonly LiveMapping[]): void
+  update(input: LiveInput): void
+  reduced(value: boolean): void
+  paused(value: boolean): void
+  bind(view: View, property: NumericProperty, maps: readonly LiveMapping[]): LiveBinding
+  dispose(): void
+}
+export interface LiveSpringDriver {
+  create(initial: number, physics: LiveSpringPhysics, reduced: boolean): LiveNode
+  sync(view: View): void
+}
+let override: LiveSpringDriver | undefined
+export function setLiveSpringDriver(driver: LiveSpringDriver | undefined) {
+  override = driver
+}
+export function liveSpringDriver(): LiveSpringDriver {
+  if (override) return override
+  if (!available())
+    throw new Error(
+      'springValue() needs the Jolt native classes. Rebuild the native app after upgrading Jolt.',
+    )
+  return nativeDriver
+}
+function available() {
+  return isAndroid
+    ? typeof org !== 'undefined' &&
+        typeof org.rafaelaugusto.jolt.LiveSpring === 'function'
+    : typeof JoltLiveSpring !== 'undefined'
+}
+export function syncLiveSprings(view: View) {
+  if (override) override.sync(view)
+  else if (available() && view.nativeViewProtected) nativeDriver.sync(view)
+}
+const handles = new WeakMap<
+  LiveNode,
+  org.rafaelaugusto.jolt.LiveSpring | JoltLiveSpring
+>()
+/** Internal native input connection; never exposes handles through the public value API. */
+export function nativeLiveNode(node: LiveNode) {
+  const handle = handles.get(node)
+  if (!handle) throw new Error('A gesture needs a native live value node.')
+  return handle
+}
+const nativeDriver: LiveSpringDriver = {
+  create(initial, physics, reduced) {
+    const { stiffness, damping, mass, restDelta, restSpeed } = physics
+    if (isAndroid) {
+      const native = new org.rafaelaugusto.jolt.LiveSpring(
+        initial,
+        stiffness,
+        damping,
+        mass,
+        restDelta,
+        restSpeed,
+        reduced,
+      )
+      const node: LiveNode = {
+        position: () => native.getPosition(),
+        velocity: () => native.getVelocity(),
+        moving: () => native.isMoving(),
+        follow: (source, maps) =>
+          native.follow(
+            handles.get(source) as org.rafaelaugusto.jolt.LiveSpring,
+            JSON.stringify(maps),
+          ),
+        update: (input) =>
+          input.running
+            ? native.updateInput(JSON.stringify(input))
+            : native.setTarget(input.value),
+        reduced: (value) => native.setReduced(value),
+        paused: (value) => native.setPaused(value),
+        bind(view, property, maps) {
+          const binding = native.bind(
+            view.nativeViewProtected,
+            property,
+            JSON.stringify(maps),
+          )
+          return {
+            value: () => binding.getValue(),
+            layers: (inputs) => binding.setLayers(JSON.stringify(inputs)),
+            cancel: () => binding.cancel(),
+          }
+        },
+        dispose: () => native.dispose(),
+      }
+      handles.set(node, native)
+      return node
+    }
+    const native = JoltLiveSpring.createStiffnessDampingMassRestDeltaRestSpeedReduced(
+      initial,
+      stiffness,
+      damping,
+      mass,
+      restDelta,
+      restSpeed,
+      reduced,
+    )
+    const node: LiveNode = {
+      position: () => native.position,
+      velocity: () => native.velocity,
+      moving: () => native.moving,
+      follow: (source, maps) =>
+        native.followMappings(
+          handles.get(source) as JoltLiveSpring,
+          JSON.stringify(maps),
+        ),
+      update: (input) =>
+        input.running
+          ? native.updateInput(JSON.stringify(input))
+          : native.setTarget(input.value),
+      reduced: (value) => native.setReduced(value),
+      paused: (value) => native.setPaused(value),
+      bind(view, property, maps) {
+        const releaseLayout = retainInteractiveLayout(view)
+        let binding: JoltLiveSpringBinding
+        try {
+          binding = native.bindPropertyMappings(
+            view.nativeViewProtected,
+            property,
+            JSON.stringify(maps),
+          )
+        } catch (error) {
+          releaseLayout()
+          throw error
+        }
+        return {
+          value: () => binding.value,
+          layers: (inputs) => binding.setLayers(JSON.stringify(inputs)),
+          cancel: () => {
+            binding.cancel()
+            releaseLayout()
+          },
+        }
+      },
+      dispose: () => native.dispose(),
+    }
+    handles.set(node, native)
+    return node
+  },
+  sync(view) {
+    if (isAndroid) org.rafaelaugusto.jolt.LiveSpring.sync(view.nativeViewProtected)
+    else JoltLiveSpring.sync(view.nativeViewProtected)
+  },
+}