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

package/src/image-effect.ts

@@ -0,0 +1,336 @@
+import {
+  Application,
+  Image,
+  ImageSource,
+  isIOS,
+  type EventData,
+} from '@nativescript/core'
+import { toView } from './animate.js'
+import { reducedMotion, timeScale } from './config.js'
+import type { Animation } from './engine.js'
+import { ownImage } from './image-owner.js'
+import { createImageRenderer, type ImageRenderer } from './image-effect-native.js'
+import type { Target } from './types.js'
+
+export type ImageEffectName = 'ripple' | 'distortion' | 'dissolve'
+export interface ImageEffectOptions {
+  /** Origin in target-local DIPs; defaults to the center. */
+  origin?: { x: number; y: number }
+  /** Maximum displacement in DIPs, 0..64. Defaults to 8. */
+  amplitude?: number
+  /** Influence radius in DIPs, greater than zero. Defaults to 96. */
+  radius?: number
+  /** Milliseconds for a finite effect (or drag release). Defaults to 650. */
+  duration?: number
+  /** Deterministic dissolve noise seed, 0..65535. Defaults to 1. */
+  seed?: number
+  /** Loaded destination raster for dissolve. */
+  to?: ImageSource
+  /** Prepare at progress zero without starting. */
+  paused?: boolean
+}
+export interface ImageEffectDiagnostics {
+  backend: 'waiting' | 'metal' | 'agsl' | 'fallback'
+  reason?: 'reduced-motion' | 'unsupported' | 'not-visible'
+  /** Native setup error, when available. Intended for developer diagnostics. */
+  detail?: string
+  frames: number
+  textureBytes: number
+  peakTextureBytes: number
+  preparationMs: number
+  longestFrameMs: number
+}
+export interface ImageEffect extends Animation {
+  readonly effect: ImageEffectName
+  readonly paused: boolean
+  /** Finite progress; distortion rejects seeking because it follows native touch input. */
+  progress: number
+  readonly diagnostics: Readonly<ImageEffectDiagnostics>
+  pause(): void
+  play(): void
+  /** Reverse a finite effect from its current pixels. Terminal handles remain terminal. */
+  reverse(): void
+  /** Complete immediately at the current direction's endpoint. */
+  finish(): void
+}
+
+const names: readonly ImageEffectName[] = ['ripple', 'distortion', 'dissolve']
+const surfaceChanges = [
+  'tintColorChange',
+  ...['TopLeft', 'TopRight', 'BottomRight', 'BottomLeft'].map(
+    (corner) => `border${corner}RadiusChange`,
+  ),
+  ...['Top', 'Right', 'Bottom', 'Left'].flatMap((edge) => [
+    `padding${edge}Change`,
+    `border${edge}WidthChange`,
+  ]),
+]
+
+/** Optional native image effects. Stop restores the source; dissolve completion commits its destination. */
+export function imageEffect(
+  target: Target,
+  effect: ImageEffectName,
+  options: ImageEffectOptions = {},
+): ImageEffect {
+  const image = toView(target)
+  if (!(image instanceof Image))
+    throw new TypeError('imageEffect() expects a NativeScript Image.')
+  if (!names.includes(effect))
+    throw new TypeError(`Unknown image effect: ${String(effect)}.`)
+  if (!options || typeof options !== 'object')
+    throw new TypeError('Image effect options must be an object.')
+  const amplitude = options.amplitude ?? 8,
+    radius = options.radius ?? 96
+  const duration = options.duration ?? 650,
+    seed = options.seed ?? 1
+  if (!Number.isFinite(amplitude) || amplitude < 0 || amplitude > 64)
+    throw new RangeError('Image displacement must be between 0 and 64 DIPs.')
+  if (
+    !Number.isFinite(radius) ||
+    radius <= 0 ||
+    !Number.isFinite(duration) ||
+    duration <= 0
+  )
+    throw new RangeError('Image radius and duration must be positive finite numbers.')
+  if (!Number.isInteger(seed) || seed < 0 || seed > 65535)
+    throw new RangeError('Image seed must be an integer between 0 and 65535.')
+  if (
+    options.origin &&
+    (!Number.isFinite(options.origin.x) || !Number.isFinite(options.origin.y))
+  )
+    throw new RangeError('Image origin must contain finite local coordinates.')
+  if (options.paused !== undefined && typeof options.paused !== 'boolean')
+    throw new TypeError('paused must be a boolean.')
+  if (
+    effect === 'dissolve' &&
+    (!(options.to instanceof ImageSource) ||
+      !Number.isFinite(options.to.width) ||
+      !Number.isFinite(options.to.height) ||
+      options.to.width <= 0 ||
+      options.to.height <= 0)
+  )
+    throw new TypeError('Dissolve requires a loaded destination ImageSource.')
+  return new Effect(image, effect, {
+    ...options,
+    amplitude,
+    radius,
+    duration: duration / timeScale(),
+    seed,
+  })
+}
+
+class Effect implements ImageEffect {
+  readonly finished: Promise<boolean>
+  private resolve!: (completed: boolean) => void
+  private renderer: ImageRenderer | undefined
+  private releaseOwnership: () => void = () => {}
+  private terminal = false
+  private queued = false
+  private committing = false
+  private userPaused: boolean
+  private suspended = false
+  private position = 0
+  private direction: 0 | 1 = 1
+  private dimensions = ''
+  private stats: ImageEffectDiagnostics = {
+    backend: 'waiting',
+    frames: 0,
+    textureBytes: 0,
+    peakTextureBytes: 0,
+    preparationMs: 0,
+    longestFrameMs: 0,
+  }
+  private reduceObserver:
+    ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly image: Image,
+    readonly effect: ImageEffectName,
+    private readonly options: ImageEffectOptions &
+      Required<Pick<ImageEffectOptions, 'amplitude' | 'radius' | 'duration' | 'seed'>>,
+  ) {
+    this.userPaused = options.paused ?? false
+    this.finished = new Promise((resolve) => {
+      this.resolve = resolve
+    })
+    this.releaseOwnership = ownImage(image, this.stop)
+    for (const event of ['loaded', 'layoutChanged']) image.on(event, this.schedule)
+    for (const event of ['imageSourceChange', 'stretchChange'])
+      image.on(event, this.changed)
+    image.on('unloaded', this.stop)
+    image.style.on('visibilityChange', this.visible)
+    for (const event of surfaceChanges) image.style.on(event, this.changed)
+    Application.on(Application.suspendEvent, this.suspend)
+    Application.on(Application.resumeEvent, this.resume)
+    if (isIOS)
+      this.reduceObserver = Application.ios.addNotificationObserver(
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+        this.preferences,
+      )
+    this.schedule()
+  }
+  then<TResult1 = boolean, TResult2 = never>(
+    fulfilled?: ((value: boolean) => TResult1 | PromiseLike<TResult1>) | null,
+    rejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.finished.then(fulfilled, rejected)
+  }
+  get paused() {
+    return this.userPaused
+  }
+  get progress() {
+    return this.renderer?.progress ?? this.position
+  }
+  set progress(value: number) {
+    if (this.effect === 'distortion')
+      throw new TypeError('Distortion follows touch input and cannot be scrubbed.')
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+      throw new RangeError('Image progress must be between 0 and 1.')
+    if (this.terminal) return
+    this.position = value
+    this.renderer?.seek(value)
+  }
+  get diagnostics(): Readonly<ImageEffectDiagnostics> {
+    return {
+      ...this.stats,
+      ...(this.renderer
+        ? {
+            frames: this.renderer.frames,
+            textureBytes: this.renderer.textureBytes,
+            longestFrameMs: this.renderer.longestFrameMs,
+          }
+        : {}),
+    }
+  }
+  pause = () => {
+    if (this.terminal) return
+    this.userPaused = true
+    this.renderer?.pause()
+  }
+  play = () => {
+    if (this.terminal) return
+    this.userPaused = false
+    if (this.suspended) return
+    if (this.renderer) {
+      if (this.effect === 'distortion') this.renderer.resume()
+      else this.renderer.play(this.direction)
+    } else this.schedule()
+  }
+  reverse = () => {
+    if (this.effect === 'distortion')
+      throw new TypeError('Distortion has no finite playback direction.')
+    if (this.terminal) return
+    this.direction = this.direction === 1 ? 0 : 1
+    this.play()
+  }
+  finish = () => {
+    if (this.terminal) return
+    if (this.effect === 'distortion') return this.stop()
+    this.complete(true, this.direction)
+  }
+  stop = () => this.complete(false, this.progress)
+  private complete = (completed: boolean, position: number, preserveImage = false) => {
+    if (this.terminal) return
+    this.terminal = true
+    this.position = position
+    this.stats = { ...this.diagnostics, textureBytes: 0 }
+    this.renderer?.stop(preserveImage)
+    this.renderer = undefined
+    this.releaseOwnership()
+    for (const event of ['loaded', 'layoutChanged']) this.image.off(event, this.schedule)
+    for (const event of ['imageSourceChange', 'stretchChange'])
+      this.image.off(event, this.changed)
+    this.image.off('unloaded', this.stop)
+    this.image.style.off('visibilityChange', this.visible)
+    for (const event of surfaceChanges) this.image.style.off(event, this.changed)
+    Application.off(Application.suspendEvent, this.suspend)
+    Application.off(Application.resumeEvent, this.resume)
+    if (this.reduceObserver)
+      Application.ios.removeNotificationObserver(
+        this.reduceObserver,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+    this.reduceObserver = undefined
+    if (completed && this.effect === 'dissolve' && position === 1) {
+      this.committing = true
+      // The view may clear its ImageSource on disposal. Keep the caller's
+      // destination reusable by giving the view its own wrapper.
+      const destination = new ImageSource(this.options.to!.getNativeSource())
+      destination.rotationAngle = this.options.to!.rotationAngle
+      this.image.imageSource = destination
+      this.committing = false
+    }
+    this.resolve(completed)
+  }
+  private changed = (event?: EventData) => {
+    if (this.committing) return
+    if (this.renderer)
+      this.complete(false, this.progress, event?.eventName === 'imageSourceChange')
+    else this.schedule()
+  }
+  private suspend = () => {
+    this.suspended = true
+    this.renderer?.pause()
+  }
+  private resume = () => {
+    this.suspended = false
+    this.schedule()
+    if (!this.userPaused) this.play()
+  }
+  private visible = () => {
+    if (this.image.visibility !== 'visible') this.stop()
+  }
+  private preferences = () => {
+    if (reducedMotion()) this.fallback('reduced-motion')
+  }
+  private fallback(reason: ImageEffectDiagnostics['reason']) {
+    this.stats = { ...this.stats, backend: 'fallback', reason }
+    // Reduced/unsupported rendering still performs a requested content change.
+    if (this.effect === 'dissolve' && this.direction === 1) {
+      this.complete(true, 1)
+    } else this.complete(false, 0)
+  }
+  private schedule = () => {
+    if (this.queued || this.terminal) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.terminal || this.suspended || !this.image.isLoaded) return
+      if (reducedMotion()) return this.fallback('reduced-motion')
+      if (this.image.visibility !== 'visible') return this.fallback('not-visible')
+      const { width, height } = this.image.getActualSize()
+      if (width <= 0 || height <= 0) return
+      const dimensions = `${width}:${height}`
+      if (this.renderer) {
+        if (this.dimensions !== dimensions) this.stop()
+        return
+      }
+      if (!this.image.imageSource) return
+      this.dimensions = dimensions
+      const started = Date.now()
+      try {
+        this.renderer = createImageRenderer(
+          this.image,
+          {
+            ...this.options,
+            mode: names.indexOf(this.effect),
+            x: this.options.origin?.x ?? width / 2,
+            y: this.options.origin?.y ?? height / 2,
+          },
+          this.complete,
+        )
+      } catch (error) {
+        this.stats.preparationMs = Date.now() - started
+        this.stats.detail = String(error)
+        return this.fallback('unsupported')
+      }
+      if (!this.renderer) return this.fallback('unsupported')
+      this.stats.backend = this.renderer.backend
+      this.stats.preparationMs = Date.now() - started
+      this.stats.peakTextureBytes = this.renderer.textureBytes
+      this.renderer.pause()
+      if (this.position) this.renderer.seek(this.position)
+      if (!this.userPaused && !this.suspended) this.play()
+    })
+  }
+}

package/src/image-owner.ts

@@ -0,0 +1,12 @@
+import type { Image } from '@nativescript/core'
+
+/** Rendering effects share one image surface; ordinary view transforms stay independent. */
+const owners = new WeakMap<Image, () => void>()
+
+export function ownImage(image: Image, stop: () => void): () => void {
+  owners.get(image)?.()
+  owners.set(image, stop)
+  return () => {
+    if (owners.get(image) === stop) owners.delete(image)
+  }
+}

package/src/index.ts

@@ -1,12 +1,83 @@
-export { animate, stop } from './animate.js'
+export { animate, decay, set, stop } from './animate.js'
 export { sequence } from './sequence.js'
-export type { Step } from './sequence.js'
+export type { Step, SequenceOptions, SequencePosition } from './sequence.js'
 export { press } from './press.js'
+export { interactionSurface } from './interaction-surface.js'
+export type { InteractionSurface } from './interaction-surface.js'
+export { drag } from './drag.js'
+export type { Drag, DragOptions, DragPoint, DragEvent, DragRelease } from './drag.js'
+export { scrollLinked } from './scroll-linked.js'
+export type { ScrollLinkedOptions } from './scroll-linked.js'
+export { animateItems } from './items.js'
+export type { ItemsOptions } from './items.js'
+export { followKeyboard, onKeyboard } from './keyboard.js'
+export type { KeyboardOptions, KeyboardState } from './keyboard.js'
+export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
+export { confetti, particles } from './particles.js'
+export type { ConfettiOptions, ParticleOptions } from './particles.js'
+export { shimmer } from './shimmer.js'
+export type { ShimmerOptions } from './shimmer.js'
+export { liquid } from './liquid.js'
+export type { LiquidOptions, LiquidEffect } from './liquid.js'
+export { imageEffect } from './image-effect.js'
+export type {
+  ImageEffect,
+  ImageEffectName,
+  ImageEffectOptions,
+  ImageEffectDiagnostics,
+} from './image-effect.js'
+export { zoomable } from './zoomable.js'
+export type { Zoomable, ZoomableOptions, ZoomState, PhotoDismissal } from './zoomable.js'
+export { loader } from './loader.js'
+export type { LoaderOptions, LoaderStyle } from './loader.js'
+export { reveal, conceal } from './reveal.js'
+export type { RevealOptions, ConcealOptions } from './reveal.js'
+export { animateText } from './text.js'
+export type { TextOptions } from './text.js'
+export { rollTo } from './roll.js'
+export type { RollOptions } from './roll.js'
+export { symbolEffect } from './symbol-effect.js'
+export type {
+  SymbolEffect,
+  SymbolEffectName,
+  SymbolEffectOptions,
+} from './symbol-effect.js'
+export { gradient } from './gradient.js'
+export type {
+  Gradient,
+  GradientOptions,
+  GradientType,
+  GradientValues,
+} from './gradient.js'
+export { configure, onReducedMotion, reducedMotion } from './config.js'
+export type { JoltConfig } from './config.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
-export { springs } from './transition.js'
-export type { Spring, SpringName, Timing, Transition, Tween } from './transition.js'
+export { origamiSpring, springs } from './transition.js'
+export type {
+  OrigamiSpring,
+  Spring,
+  SpringName,
+  Timing,
+  Transition,
+  Tween,
+} from './transition.js'
 export { cubicBezier } from './easing.js'
 export type { CubicBezier, Easing, EasingFunction, EasingName } from './easing.js'
+export type { PlaybackAnimation } from './playback.js'
 export type { Animation } from './engine.js'
+export type { ColorValue, ColorKeyframes } from './color.js'
 export type * from './types.js'
+export { motionScope } from './motion-scope.js'
+export type { MotionScope, MotionResource } from './motion-scope.js'
+export { motionStates } from './motion-states.js'
+export type {
+  MotionStates,
+  MotionStatesOptions,
+  MotionState,
+  MotionValues,
+  StateTransition,
+} from './motion-states.js'
+
+export { animateLayout } from './layout.js'
+export type { LayoutOptions } from './layout.js'

package/src/interaction-surface.ts

@@ -0,0 +1,41 @@
+import type { View, ViewBase } from '@nativescript/core'
+import { toView } from './animate.js'
+import type { Target } from './types.js'
+
+const surfaces = new WeakMap<ViewBase, Set<object>>()
+export interface InteractionSurface {
+  readonly disposed: boolean
+  /** Existing animations retain their driver until they end. Disables future opt-in. */
+  dispose(): void
+}
+
+/** Opt a view/subtree into native geometry updates before starting its animations. */
+export function interactionSurface(target: Target): InteractionSurface {
+  const view = toView(target)
+  let tokens = surfaces.get(view)
+  if (!tokens) surfaces.set(view, (tokens = new Set()))
+  const token = {}
+  tokens.add(token)
+  let disposed = false
+  return {
+    get disposed() {
+      return disposed
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      tokens.delete(token)
+      if (!tokens.size) surfaces.delete(view)
+    },
+  }
+}
+
+/** Evaluated at animation start; no per-frame JS traversal. */
+export function hasInteractionSurface(view: View): boolean {
+  let current: ViewBase | undefined = view
+  while (current) {
+    if (surfaces.get(current)?.size) return true
+    current = current.parent
+  }
+  return false
+}

package/src/ios-plugin.d.ts

@@ -0,0 +1,81 @@
+declare class JoltInteractiveAnimation extends NSObject {
+  static startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
+    view: UIView,
+    layers: NSArray<CALayer>,
+    keyPath: string,
+    values: NSArray<number>,
+    times: NSArray<number>,
+    duration: number,
+    delay: number,
+    repeat: number,
+    reverse: boolean,
+    finalValue: number,
+    startedAt: number,
+    completion: (completed: boolean) => void,
+  ): JoltInteractiveAnimation
+  static syncViewExcluding(view: UIView, keyPath: string | null): void
+  static valueForViewKeyPath(view: UIView, keyPath: string): number | null
+  static activeCount(): number
+  readonly elapsed: number
+  controlPaused(elapsed: number, paused: boolean): void
+  cancel(): void
+}
+declare class JoltImageEffect extends NSObject {
+  stopPreservingImage(): void
+  static createWithViewDestinationModeOriginXOriginYAmplitudeRadiusDurationSeedListener(
+    image: UIImageView,
+    destination: UIImage | null,
+    mode: number,
+    x: number,
+    y: number,
+    amplitude: number,
+    radius: number,
+    duration: number,
+    seed: number,
+    listener: (completed: boolean, progress: number) => void,
+  ): JoltImageEffect | null
+  readonly progress: number
+  readonly paused: boolean
+  readonly frames: number
+  readonly longestFrame: number
+  readonly textureBytes: number
+  play(endpoint: number): void
+  pause(): void
+  resume(): void
+  seek(progress: number): void
+  finish(endpoint: number): void
+  stop(): void
+}
+declare class JoltPhotoZoom extends NSObject {
+  static attachImageViewportMinimumMaximumDoubleTapDismissReducedBackdropChromeOnDismissOnSettled(
+    image: UIImageView,
+    viewport: UIView,
+    minimum: number,
+    maximum: number,
+    doubleTap: number,
+    dismiss: boolean,
+    reduced: boolean,
+    backdrop: UIView | null,
+    chrome: UIView | null,
+    onDismiss: (
+      x: number,
+      y: number,
+      scale: number,
+      velocity: number,
+      progress: number,
+    ) => void,
+    onSettled: (x: number, y: number, scale: number) => void,
+  ): JoltPhotoZoom
+  readonly x: number
+  readonly y: number
+  readonly scale: number
+  readonly dismissProgress: number
+  readonly dismissPending: boolean
+  zoomFocusXFocusYAnimated(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
+}

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
+}