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

package/src/items.ts

@@ -0,0 +1,140 @@
+import { ListView, View, type EventData, type ItemEventData } from '@nativescript/core'
+import { animate, endingValues, startingValues, toView } from './animate.js'
+import { getDriver } from './driver/index.js'
+import { stopView } from './engine.js'
+import type { PresetName } from './presets.js'
+import { writeValue } from './properties.js'
+import type { SpringName } from './transition.js'
+import type { AnimateOptions, Keyframes, Target } from './types.js'
+
+export type ItemsOptions = AnimateOptions & {
+  /** Animate each data item only the first time it shows up. Defaults to false. */
+  once?: boolean
+}
+
+interface Pending {
+  index: number
+  section: number | undefined
+  item: unknown
+  key: string
+}
+
+type Row = View & {
+  bindingContext?: unknown
+  _listViewItemIndex?: number
+  _listViewSectionIndex?: number
+}
+
+interface Source extends View {
+  items?: unknown
+  _getDataItem?(index: number): unknown
+  _getDataItemInSection?(section: number, index: number): unknown
+}
+
+/**
+ * Plays an animation on each row of a list as it comes on screen. Rows are
+ * recycled, so a row that is reused for another item starts over, or settles
+ * at the end values when that item was already shown and `once` is set.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * animateItems(listView, 'fadeInUp')
+ * animateItems(listView, 'fadeInUp', { once: true })
+ * ```
+ */
+export function animateItems(
+  list: Target,
+  animation: Keyframes | PresetName,
+  options?: ItemsOptions | SpringName,
+): () => void {
+  const source = toView(list) as Source
+  const { once = false, ...rest } = typeof options === 'object' ? options : {}
+  if (rest.stagger !== undefined)
+    throw new TypeError('animateItems animates one row at a time; stagger has no effect.')
+  const transition: AnimateOptions | SpringName | undefined =
+    typeof options === 'string' ? options : rest
+  const properties = [...startingValues(animation, transition).keys()]
+  const ends = endingValues(animation, transition)
+
+  const rows = new Set<Row>()
+  const seenItems = new WeakSet<object>()
+  const seenKeys = new Set<string>()
+  const pending: Pending[] = []
+  let queued = false
+  let disposed = false
+
+  const settle = (row: Row) => {
+    stopView(row, properties)
+    for (const [property, value] of ends)
+      if (value !== null) writeValue(row, property, value)
+    getDriver().sync?.(row)
+  }
+  const show = (row: Row, { item, key }: Pending) => {
+    rows.add(row)
+    const tracked = typeof item === 'object' && item !== null
+    const seen = tracked ? seenItems.has(item) : seenKeys.has(key)
+    if (tracked) seenItems.add(item)
+    else seenKeys.add(key)
+    if (once && seen) settle(row)
+    else {
+      stopView(row, properties)
+      animate(row, animation, transition)
+    }
+  }
+  const flush = () => {
+    queued = false
+    if (disposed) return
+    const current = new Set<Row>()
+    const fresh: Row[] = []
+    source.eachChildView((child: Row) => {
+      current.add(child)
+      if (!rows.has(child)) fresh.push(child)
+      return true
+    })
+    for (const row of rows) if (!current.has(row)) rows.delete(row)
+    for (const entry of pending.splice(0)) {
+      const row =
+        fresh.find(
+          (candidate) =>
+            candidate._listViewItemIndex === entry.index &&
+            candidate._listViewSectionIndex === entry.section,
+        ) ??
+        fresh.find(
+          (candidate) =>
+            entry.item !== undefined && candidate.bindingContext === entry.item,
+        )
+      if (!row) continue
+      fresh.splice(fresh.indexOf(row), 1)
+      show(row, entry)
+    }
+  }
+  const onItemLoading = (event: EventData) => {
+    const { index, section, view } = event as ItemEventData
+    const item =
+      section === undefined
+        ? source._getDataItem?.(index)
+        : source._getDataItemInSection?.(section, index)
+    const entry: Pending = { index, section, item, key: `${section ?? ''}:${index}` }
+    if (view instanceof View) {
+      show(view, entry)
+      return
+    }
+    pending.push(entry)
+    if (queued) return
+    queued = true
+    void Promise.resolve().then(flush)
+  }
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    source.off(ListView.itemLoadingEvent, onItemLoading)
+    source.off('unloaded', cleanup)
+    pending.length = 0
+    for (const row of rows) settle(row)
+    rows.clear()
+  }
+
+  source.on(ListView.itemLoadingEvent, onItemLoading)
+  source.on('unloaded', cleanup)
+  return cleanup
+}

package/src/keyboard.ts

@@ -0,0 +1,291 @@
+import { Application, Utils, isAndroid, isIOS, type View } from '@nativescript/core'
+import { stop, toView } from './animate.js'
+import type { EasingFunction, EasingName } from './easing.js'
+import type { Spring, Transition } from './transition.js'
+import type { Target } from './types.js'
+
+export interface KeyboardOptions {
+  /** DIPs kept between the view's bottom edge and the keyboard. Defaults to zero. */
+  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']
+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() {
+  if (android.os.Build.VERSION.SDK_INT < 30) return undefined
+  const density = Utils.layout.getDisplayDensity()
+  let observer: org.rafaelaugusto.jolt.KeyboardObserver | 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 = 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
+ * own speed and curve, and lets it back down when the keyboard hides.
+ * Returns a function that removes the effect.
+ *
+ * ```ts
+ * const release = followKeyboard(composer)
+ * followKeyboard(sendButton, { offset: 12 })
+ * ```
+ */
+export function followKeyboard(
+  target: Target,
+  options: KeyboardOptions = {},
+): () => void {
+  const view = toView(target)
+  const offset = options.offset ?? 0
+  if (!Number.isFinite(offset)) throw new RangeError('Keyboard offset must be finite.')
+  if (isIOS) return followIOS(view, offset)
+  if (isAndroid) return followAndroid(view, offset)
+  return () => {}
+}
+
+function followIOS(view: View, offset: number) {
+  let disposed = false
+  let current = 0
+  const onKeyboard = (notification: NSNotification) => {
+    if (disposed || !view.isLoaded) return
+    const native = view.nativeViewProtected as UIView | undefined
+    const window = native?.window
+    const info = notification.userInfo
+    if (!native || !window || !info) return
+    const end = info.objectForKey(UIKeyboardFrameEndUserInfoKey)?.CGRectValue as
+      CGRect | undefined
+    if (!end) return
+    const keyboard = window.convertRectFromWindow(end, null)
+    const hidden =
+      keyboard.size.height <= 0 || keyboard.origin.y >= window.bounds.size.height
+    const frame = native.convertRectToView(native.bounds, null)
+    const bottom = frame.origin.y + frame.size.height - view.translateY
+    const overlap = hidden ? 0 : Math.max(0, bottom + offset - keyboard.origin.y)
+    if (overlap === current) return
+    current = overlap
+    stop(view, ['y'])
+    const apply = () => {
+      view.translateY = overlap ? -overlap : 0
+    }
+    const duration = numberIn(info, UIKeyboardAnimationDurationUserInfoKey)
+    if (!duration) return apply()
+    const curve = numberIn(info, UIKeyboardAnimationCurveUserInfoKey)
+    // The keyboard's curve is private; shifted into the options it still applies.
+    UIView.animateWithDurationDelayOptionsAnimationsCompletion(
+      duration,
+      0,
+      ((curve << 16) | BEGIN_FROM_CURRENT_STATE) as UIViewAnimationOptions,
+      apply,
+      () => {},
+    )
+  }
+  const observer = Application.ios.addNotificationObserver(
+    UIKeyboardWillChangeFrameNotification,
+    onKeyboard,
+  )
+  const cleanup = () => {
+    if (disposed) return
+    disposed = true
+    Application.ios.removeNotificationObserver(
+      observer,
+      UIKeyboardWillChangeFrameNotification,
+    )
+    view.off('unloaded', cleanup)
+    if (current) view.translateY = 0
+  }
+  view.on('unloaded', cleanup)
+  return cleanup
+}
+
+function followAndroid(view: View, offset: number) {
+  if (android.os.Build.VERSION.SDK_INT < 30) return () => {}
+  const density = Utils.layout.getDisplayDensity()
+  let disposed = false
+  let follower: org.rafaelaugusto.jolt.KeyboardFollower | 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.KeyboardFollower(
+        native,
+        offset * density,
+        new org.rafaelaugusto.jolt.KeyboardFollower.Listener({
+          onStart: () => stop(view, ['y']),
+          onSettled: (translation) => {
+            view.translateY = translation / density
+          },
+        }),
+      )
+    } 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
+      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/label.ts

@@ -0,0 +1,76 @@
+import type { Label } from '@nativescript/core'
+
+const callbacks = new WeakMap<NSObject, (finished: boolean) => void>()
+let Delegate: typeof NSObject | undefined
+const styleEvents = [
+  'fontInternalChange',
+  'colorChange',
+  'textAlignmentChange',
+  'textDecorationChange',
+  'textTransformChange',
+  'letterSpacingChange',
+  'lineHeightChange',
+  'textShadowChange',
+  'textStrokeChange',
+  'whiteSpaceChange',
+  'textOverflowChange',
+  'maxLinesChange',
+  'paddingLeftChange',
+  'paddingRightChange',
+  'paddingTopChange',
+  'paddingBottomChange',
+  'visibilityChange',
+  'directionChange',
+  'borderLeftWidthChange',
+  'borderRightWidthChange',
+  'borderTopWidthChange',
+  'borderBottomWidthChange',
+]
+
+/** Reports text, formatted text and style changes of a Label until the returned function is called. */
+export function watchLabel(view: Label, onChange: () => void): () => void {
+  const formatted = view.formattedText
+  view.on('textChange', onChange)
+  view.on('formattedTextChange', onChange)
+  formatted?.on('propertyChange', onChange)
+  for (const event of styleEvents) view.style.on(event, onChange)
+  return () => {
+    view.off('textChange', onChange)
+    view.off('formattedTextChange', onChange)
+    formatted?.off('propertyChange', onChange)
+    for (const event of styleEvents) view.style.off(event, onChange)
+  }
+}
+
+/** A CAAnimationDelegate that reports when its animation stops. Release it with `forgetCompletion`. */
+export function completion(
+  callback: (finished: boolean) => void,
+): NSObject & CAAnimationDelegate {
+  if (!Delegate) {
+    const base = NSObject as typeof NSObject & {
+      extend(
+        methods: object,
+        options: { protocols: unknown[]; name: string },
+      ): typeof NSObject
+    }
+    Delegate = base.extend(
+      {
+        animationDidStopFinished(
+          this: NSObject,
+          _animation: CAAnimation,
+          finished: boolean,
+        ) {
+          callbacks.get(this)?.(finished)
+        },
+      },
+      { protocols: [CAAnimationDelegate], name: 'JoltLabelAnimationDelegate' },
+    )
+  }
+  const delegate = Delegate.new()
+  callbacks.set(delegate, callback)
+  return delegate
+}
+
+export function forgetCompletion(delegate: NSObject) {
+  callbacks.delete(delegate)
+}