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

package/src/reorder/index.ts

@@ -0,0 +1,243 @@
+import { Application, ListView, Trace, type View } from '@nativescript/core'
+import { onReducedMotion, reducedMotion } from '../config.js'
+import { coreListAdapter } from './list-view.js'
+import { itemKeys, moveAt, sameKeys } from './model.js'
+import type {
+  Reorder,
+  ReorderAdapter,
+  ReorderAdapterDriver,
+  ReorderCancelReason,
+  ReorderKey,
+  ReorderNativeEvent,
+  ReorderOptions,
+} from './types.js'
+
+export { coreListAdapter }
+export { ReorderHandle } from './handle.js'
+export { ReorderSurface } from './surface.js'
+export type * from './types.js'
+
+const owners = new WeakMap<View, { dispose(): void }>()
+function report(callback: () => void) {
+  try {
+    callback()
+  } catch (error) {
+    Trace.write(
+      `Jolt reorder callback failed: ${String(error)}`,
+      Trace.categories.Error,
+      Trace.messageType.error,
+    )
+  }
+}
+
+/** Reorder a flat, vertical Core ListView, or an explicitly supported adapter. */
+export function reorder<T, K extends ReorderKey = ReorderKey>(
+  source: ListView | ReorderAdapter<T>,
+  options: ReorderOptions<T, K>,
+): Reorder<K> {
+  if (
+    !options ||
+    typeof options.key !== 'function' ||
+    typeof options.onCommit !== 'function'
+  )
+    throw new TypeError('reorder() requires key(item) and onCommit(move).')
+  const adapter = source instanceof ListView ? coreListAdapter<T>(source) : source
+  if (
+    !adapter?.view ||
+    typeof adapter.items !== 'function' ||
+    typeof adapter.subscribe !== 'function' ||
+    typeof adapter.attach !== 'function'
+  )
+    throw new TypeError('Provide a Core ListView or a ReorderAdapter.')
+  for (const callback of [options.onStart, options.onCancel])
+    if (callback !== undefined && typeof callback !== 'function')
+      throw new TypeError('Reorder callbacks must be functions.')
+  if (
+    options.handle !== undefined &&
+    typeof options.handle !== 'string' &&
+    typeof options.handle !== 'function'
+  )
+    throw new TypeError('The reorder handle must be a view id or resolver.')
+  const longPress = options.longPress ?? 350,
+    edgeSize = options.edge?.size ?? 72,
+    edgeSpeed = options.edge?.speed ?? 640
+  if (!Number.isFinite(longPress) || longPress < 150 || longPress > 2000)
+    throw new RangeError('Reorder longPress must be between 150 and 2000 ms.')
+  if (![edgeSize, edgeSpeed].every((value) => Number.isFinite(value) && value > 0))
+    throw new RangeError('Reorder edge size and speed must be positive finite numbers.')
+
+  const view = adapter.view
+  let keys = itemKeys(adapter.items(), options.key)
+  owners.get(view)?.dispose()
+  let driver: ReorderAdapterDriver | undefined,
+    active: { key: K; index: number; keys: K[] } | undefined,
+    disposed = false,
+    paused = false
+  const read = () => itemKeys(adapter.items(), options.key)
+
+  function cancel(reason: ReorderCancelReason) {
+    const previous = active
+    active = undefined
+    driver?.cancel()
+    if (previous) report(() => options.onCancel?.({ key: previous.key, reason }))
+  }
+  function refresh() {
+    if (disposed) return
+    let next: K[]
+    try {
+      next = read()
+    } catch (error) {
+      cancel('data-changed')
+      throw error
+    }
+    if (active) cancel(next.includes(active.key) ? 'data-changed' : 'removed')
+    keys = next
+  }
+  function event(event: ReorderNativeEvent) {
+    if (disposed || paused) return
+    if (event.type === 'start') {
+      keys = read()
+      const key = keys[event.index]
+      if (key === undefined) {
+        driver?.cancel()
+        return
+      }
+      active = { key, index: event.index, keys: [...keys] }
+      report(() => options.onStart?.(key))
+    } else if (event.type === 'cancel') {
+      cancel(event.geometryChanged ? 'geometry-changed' : 'cancelled')
+    } else {
+      const previous = active
+      if (!previous) return
+      const next = read()
+      if (!sameKeys(previous.keys, next) || event.index !== previous.index) {
+        cancel(next.includes(previous.key) ? 'data-changed' : 'removed')
+        keys = next
+        return
+      }
+      const move = moveAt(previous.keys, previous.index, event.toIndex)
+      active = undefined
+      if (move) report(() => options.onCommit(move))
+      else report(() => options.onCancel?.({ key: previous.key, reason: 'unchanged' }))
+      keys = read()
+    }
+  }
+  function moveTo(key: K, toIndex: number): boolean {
+    if (disposed || paused) return false
+    cancel('cancelled')
+    keys = read()
+    const move = moveAt(keys, keys.indexOf(key), toIndex)
+    if (!move) return false
+    report(() => options.onCommit(move))
+    keys = read()
+    return true
+  }
+  function attach() {
+    if (disposed || driver || !view.isLoaded) return
+    keys = read()
+    driver = adapter.attach({
+      handle: options.handle,
+      longPress,
+      edgeSize,
+      edgeSpeed,
+      reducedMotion: reducedMotion(),
+      accessibility: {
+        moveUp: options.accessibility?.moveUp ?? 'Move up',
+        moveDown: options.accessibility?.moveDown ?? 'Move down',
+      },
+      event: (input) => {
+        try {
+          event(input)
+        } catch (error) {
+          cancel('data-changed')
+          report(() => {
+            throw error
+          })
+        }
+      },
+      move: (index, direction) => {
+        keys = read()
+        const key = keys[index]
+        return key !== undefined && moveTo(key, index + direction) ? key : undefined
+      },
+      keyAt: (index) => keys[index],
+      indexOf: (key) => {
+        try {
+          return read().indexOf(key as K)
+        } catch {
+          return -1
+        }
+      },
+    })
+    driver.setEnabled(!paused)
+  }
+  function unload() {
+    cancel('unloaded')
+    driver?.dispose()
+    driver = undefined
+  }
+  const suspend = () => cancel('cancelled')
+  const releaseItems = adapter.subscribe(refresh)
+  const releaseReduced = onReducedMotion((value) => driver?.setReducedMotion(value))
+  const result: Reorder<K> = {
+    get activeKey() {
+      return active?.key
+    },
+    get disposed() {
+      return disposed
+    },
+    move(key, beforeKey) {
+      if (disposed || paused) return false
+      const current = read(),
+        from = current.indexOf(key)
+      if (from < 0 || beforeKey === key) return false
+      const before = beforeKey === null ? current.length : current.indexOf(beforeKey)
+      return before < 0 ? false : moveTo(key, before > from ? before - 1 : before)
+    },
+    moveUp(key) {
+      if (disposed || paused) return false
+      return moveTo(key, read().indexOf(key) - 1)
+    },
+    moveDown(key) {
+      if (disposed || paused) return false
+      return moveTo(key, read().indexOf(key) + 1)
+    },
+    cancel: () => cancel('cancelled'),
+    refresh,
+    pause() {
+      paused = true
+      cancel('disabled')
+      driver?.setEnabled(false)
+    },
+    play() {
+      if (!disposed) {
+        paused = false
+        driver?.setEnabled(true)
+      }
+    },
+    dispose() {
+      if (disposed) return
+      cancel('disposed')
+      disposed = true
+      driver?.dispose()
+      driver = undefined
+      releaseItems()
+      releaseReduced()
+      view.off('loaded', attach)
+      view.off('unloaded', unload)
+      Application.off(Application.suspendEvent, suspend)
+      if (owners.get(view) === result) owners.delete(view)
+    },
+  }
+  owners.set(view, result)
+  view.on('loaded', attach)
+  view.on('unloaded', unload)
+  Application.on(Application.suspendEvent, suspend)
+  try {
+    attach()
+  } catch (error) {
+    result.dispose()
+    throw error
+  }
+  return result
+}

package/src/reorder/list-view.ts

@@ -0,0 +1,262 @@
+import {
+  ListView,
+  isIOS,
+  type EventData,
+  type ItemEventData,
+  type View,
+} from '@nativescript/core'
+import { sheetActions as viewActions } from '../bottom-sheet/native.js'
+import type { ReorderAdapter, ReorderKey } from './types.js'
+import { ReorderHandle } from './handle.js'
+import { ReorderSurface } from './surface.js'
+
+/** Flat Core ListView only. Sectioned lists and plugin collection views need another adapter. */
+export function coreListAdapter<T>(list: ListView): ReorderAdapter<T> {
+  if (!(list instanceof ListView)) throw new TypeError('Expected a Core ListView.')
+  function validate() {
+    if (list.sectioned || list.stickyHeader || list.showSearch)
+      throw new TypeError(
+        'Reorder supports flat Core lists without built-in headers or search.',
+      )
+  }
+  validate()
+  return {
+    view: list,
+    items() {
+      validate()
+      const source = list.items
+      return Array.from({ length: source?.length ?? 0 }, (_, index) =>
+        Array.isArray(source) ? source[index] : source.getItem(index),
+      ) as T[]
+    },
+    subscribe(changed) {
+      let source:
+        | {
+            on?(event: string, listener: () => void): void
+            off?(event: string, listener: () => void): void
+          }
+        | undefined
+      const replaced = () => {
+        source?.off?.('change', changed)
+        source = list.items as typeof source
+        source?.on?.('change', changed)
+        changed()
+      }
+      list.on('itemsChange', replaced)
+      replaced()
+      return () => {
+        list.off('itemsChange', replaced)
+        source?.off?.('change', changed)
+      }
+    },
+    attach(config) {
+      validate()
+      const options = JSON.stringify({
+        longPress: config.longPress,
+        edgeSize: config.edgeSize,
+        edgeSpeed: config.edgeSpeed,
+        reducedMotion: config.reducedMotion,
+        handles: config.handle !== undefined,
+      })
+      let draggedKey: ReorderKey | undefined
+      const event = (state: number, index: number, toIndex: number) => {
+        if (state === 1) {
+          config.event({ type: 'start', index })
+          draggedKey = config.keyAt(index)
+        } else if (state === 2) {
+          const key = draggedKey
+          draggedKey = undefined
+          config.event({ type: 'commit', index, toIndex })
+          if (key !== undefined) focusKey(key, false)
+        } else {
+          draggedKey = undefined
+          config.event({ type: 'cancel', geometryChanged: toIndex === 1 })
+        }
+      }
+      let native: {
+        registerHandle(view: any): void
+        setEnabled(value: boolean): void
+        setReducedMotion(value: boolean): void
+        cancel(): void
+        dispose(): void
+      }
+      if (isIOS) {
+        if (typeof JoltReorderSession === 'undefined')
+          throw new Error('Rebuild the native app to use reorder().')
+        native = JoltReorderSession.attachOptionsOnState(
+          list.nativeViewProtected,
+          options,
+          event,
+        )
+      } else {
+        if (
+          !(list.parent instanceof ReorderSurface) ||
+          list.parent.getChildrenCount() !== 1
+        )
+          throw new TypeError(
+            'On Android, make the Core ListView the only child of a ReorderSurface.',
+          )
+        if (typeof org.rafaelaugusto.jolt.ReorderSession === 'undefined')
+          throw new Error('Rebuild the native app to use reorder().')
+        native = new org.rafaelaugusto.jolt.ReorderSession(
+          list.parent.nativeViewProtected,
+          list.nativeViewProtected,
+          options,
+          new org.rafaelaugusto.jolt.ReorderSession.Listener({ onState: event }),
+        )
+      }
+      type Row = {
+        index: number
+        handle?: View
+        release(): void
+        timer?: ReturnType<typeof setTimeout>
+      }
+      const rows = new Map<View, Row>()
+      let ended = false
+      let focusTimer: ReturnType<typeof setTimeout> | undefined
+      function moveRow(row: Row, direction: -1 | 1, accessible: boolean) {
+        const key = config.move(row.index, direction)
+        if (key !== undefined) focusKey(key, accessible)
+      }
+      function reveal(index: number) {
+        // Run once after the app commits and Core rebinds. Estimated iOS heights
+        // can move the dropped row outside the viewport during reloadData.
+        if (isIOS) {
+          const table = list.nativeViewProtected as UITableView
+          table.layoutIfNeeded()
+          const path = NSIndexPath.indexPathForRowInSection(index, 0)
+          const rect = table.rectForRowAtIndexPath(path)
+          const top = table.bounds.origin.y + table.adjustedContentInset.top
+          const bottom =
+            table.bounds.origin.y +
+            table.bounds.size.height -
+            table.adjustedContentInset.bottom
+          // Keep the target away from an edge while UIKit resolves estimated heights.
+          if (rect.origin.y < top || rect.origin.y + rect.size.height > bottom)
+            table.scrollToRowAtIndexPathAtScrollPositionAnimated(path, 2, false)
+        } else {
+          const table = list.nativeViewProtected as android.widget.ListView
+          const cell = table.getChildAt(index - table.getFirstVisiblePosition())
+          if (!cell) list.scrollToIndex(index)
+          else {
+            const top = cell.getTop() - table.getPaddingTop()
+            const bottom = cell.getBottom() - table.getHeight() + table.getPaddingBottom()
+            if (top < 0) table.scrollListBy(top)
+            else if (bottom > 0) table.scrollListBy(bottom)
+          }
+        }
+      }
+      function focusKey(key: ReorderKey, accessible: boolean) {
+        if (ended) return
+        if (focusTimer !== undefined) clearTimeout(focusTimer)
+        let attempts = 0
+        const focus = () => {
+          focusTimer = undefined
+          if (ended) return
+          const index = config.indexOf(key)
+          if (index < 0) return
+          reveal(index)
+          const target = [...rows.values()].find(
+            (entry) => entry.index === index && entry.handle?.isLoaded,
+          )
+          if (target?.handle && list.isItemAtIndexVisible(index)) {
+            target.handle.focus()
+            if (accessible) target.handle.accessibilityScreenChanged()
+          } else if (attempts++ < 4) {
+            focusTimer = setTimeout(focus, 30)
+          }
+        }
+        // Core lays out recycled rows after Vue flushes its new items.
+        focusTimer = setTimeout(focus, 30)
+      }
+      function loaded(data: EventData) {
+        const args = data as ItemEventData
+        if (!args.view || ended) return
+        const view = args.view
+        let row = rows.get(view)
+        if (!row) {
+          row = { index: args.index, release() {} }
+          rows.set(view, row)
+        }
+        row.index = args.index
+        if (row.timer !== undefined) clearTimeout(row.timer)
+        const current = row
+        // Vue/Core finishes binding and creating native children after itemLoading.
+        row.timer = setTimeout(() => {
+          current.timer = undefined
+          if (ended) return
+          const handle =
+            typeof config.handle === 'function'
+              ? config.handle(view)
+              : typeof config.handle === 'string'
+                ? view.getViewById<View>(config.handle)
+                : view
+          if (!handle?.nativeViewProtected) return
+          if (current.handle !== handle) {
+            current.release()
+            current.handle = handle
+            const releaseActions = viewActions(handle, [
+              {
+                label: config.accessibility.moveUp,
+                run: () => moveRow(current, -1, true),
+              },
+              {
+                label: config.accessibility.moveDown,
+                run: () => moveRow(current, 1, true),
+              },
+            ])
+            let releaseKeys = () => {}
+            if (handle instanceof ReorderHandle) {
+              const move = (direction: number) =>
+                moveRow(current, direction < 0 ? -1 : 1, false)
+              if (isIOS) {
+                const button = handle.nativeViewProtected as JoltReorderHandle
+                button.onMove = move
+                releaseKeys = () => {
+                  button.onMove = null
+                }
+              } else {
+                const button =
+                  handle.nativeViewProtected as org.rafaelaugusto.jolt.ReorderHandle
+                button.setMoveListener(
+                  new org.rafaelaugusto.jolt.ReorderHandle.MoveListener({ move }),
+                )
+                releaseKeys = () => button.setMoveListener(null)
+              }
+            }
+            current.release = () => {
+              releaseKeys()
+              releaseActions()
+            }
+          }
+          native.registerHandle(handle.nativeViewProtected)
+        }, 0)
+      }
+      const driver = {
+        cancel: () => native.cancel(),
+        setEnabled: (value: boolean) => native.setEnabled(value),
+        setReducedMotion: (value: boolean) => native.setReducedMotion(value),
+        dispose() {
+          if (ended) return
+          ended = true
+          if (focusTimer !== undefined) clearTimeout(focusTimer)
+          list.off('itemLoading', loaded)
+          for (const row of rows.values()) {
+            if (row.timer !== undefined) clearTimeout(row.timer)
+            row.release()
+          }
+          rows.clear()
+          native.dispose()
+        },
+      }
+      list.on('itemLoading', loaded)
+      try {
+        list.refresh()
+      } catch (error) {
+        driver.dispose()
+        throw error
+      }
+      return driver
+    },
+  }
+}

package/src/reorder/model.ts

@@ -0,0 +1,47 @@
+import type { ReorderKey, ReorderMove } from './types.js'
+
+export function itemKeys<T, K extends ReorderKey>(
+  items: readonly T[],
+  key: (item: T) => K,
+): K[] {
+  const keys = items.map(key)
+  if (
+    keys.some(
+      (value) =>
+        (typeof value !== 'string' && typeof value !== 'number') ||
+        (typeof value === 'number' && !Number.isFinite(value)),
+    )
+  )
+    throw new TypeError('Reorder keys must be strings or finite numbers.')
+  if (new Set(keys).size !== keys.length)
+    throw new TypeError('Reorder keys must be unique and stable across recycling.')
+  return keys
+}
+
+export function sameKeys<K>(a: readonly K[], b: readonly K[]): boolean {
+  return a.length === b.length && a.every((key, index) => key === b[index])
+}
+
+/** toIndex is the final position, after removing the dragged item. */
+export function moveAt<K extends ReorderKey>(
+  keys: readonly K[],
+  fromIndex: number,
+  toIndex: number,
+): ReorderMove<K> | undefined {
+  if (
+    !Number.isInteger(fromIndex) ||
+    !Number.isInteger(toIndex) ||
+    fromIndex < 0 ||
+    toIndex < 0 ||
+    fromIndex >= keys.length ||
+    toIndex >= keys.length ||
+    fromIndex === toIndex
+  )
+    return undefined
+  return {
+    key: keys[fromIndex]!,
+    beforeKey: keys[toIndex < fromIndex ? toIndex : toIndex + 1] ?? null,
+    fromIndex,
+    toIndex,
+  }
+}

package/src/reorder/surface.ts

@@ -0,0 +1,10 @@
+import { GridLayout, isAndroid } from '@nativescript/core'
+
+/** Android dispatch boundary: owns the drag after the source cell is recycled. */
+export class ReorderSurface extends GridLayout {
+  override createNativeView(): ReturnType<GridLayout['createNativeView']> {
+    return isAndroid
+      ? new org.rafaelaugusto.jolt.ReorderSurface(this._context)
+      : super.createNativeView()
+  }
+}

package/src/reorder/types.ts

@@ -0,0 +1,87 @@
+import type { View } from '@nativescript/core'
+
+export type ReorderKey = string | number
+export type ReorderCancelReason =
+  | 'cancelled'
+  | 'unchanged'
+  | 'data-changed'
+  | 'removed'
+  | 'unloaded'
+  | 'disposed'
+  | 'disabled'
+  | 'geometry-changed'
+
+export interface ReorderMove<K extends ReorderKey = ReorderKey> {
+  key: K
+  /** Insert before this identity; null appends. The app owns the mutation. */
+  beforeKey: K | null
+  fromIndex: number
+  toIndex: number
+}
+
+export interface ReorderOptions<T, K extends ReorderKey = ReorderKey> {
+  key(item: T): K
+  /** View id, or a resolver within a realized row. Omit to drag anywhere on the row. */
+  handle?: string | ((row: View) => View | undefined)
+  onCommit(move: ReorderMove<K>): void
+  onStart?: (key: K) => void
+  onCancel?: (event: { key: K; reason: ReorderCancelReason }) => void
+  /** Long-press activation in milliseconds; default 350. */
+  longPress?: number
+  /** Edge region in DIPs and maximum native autoscroll speed in DIPs/second. */
+  edge?: { size?: number; speed?: number }
+  accessibility?: { moveUp?: string; moveDown?: string }
+}
+
+export interface Reorder<K extends ReorderKey = ReorderKey> {
+  readonly activeKey: K | undefined
+  readonly disposed: boolean
+  /** A keyboard/button alternative. Returns false for a missing key or unchanged order. */
+  move(key: K, beforeKey: K | null): boolean
+  moveUp(key: K): boolean
+  moveDown(key: K): boolean
+  cancel(): void
+  /** Call after in-place changes to a plain array or row geometry. */
+  refresh(): void
+  pause(): void
+  play(): void
+  dispose(): void
+}
+
+export type ReorderNativeEvent =
+  | { type: 'start'; index: number }
+  | { type: 'commit'; index: number; toIndex: number }
+  | { type: 'cancel'; geometryChanged?: boolean }
+
+export interface ReorderAdapterDriver {
+  cancel(): void
+  setEnabled(enabled: boolean): void
+  setReducedMotion(reduced: boolean): void
+  dispose(): void
+}
+
+/**
+ * Optional list-plugin integration. Indices refer to the current items until a
+ * change invalidates the gesture. Drivers own native input, measured variable
+ * heights, snapshot overlays, recycled-cell restoration and edge scrolling.
+ * Emit only lifecycle events; do not bridge pointer/display frames to JS.
+ */
+export interface ReorderAdapter<T> {
+  readonly view: View
+  items(): readonly T[]
+  /** Notify synchronously when identities/order/content change. */
+  subscribe(changed: () => void): () => void
+  attach(config: {
+    handle: ReorderOptions<T>['handle']
+    longPress: number
+    edgeSize: number
+    edgeSpeed: number
+    reducedMotion: boolean
+    accessibility: { moveUp: string; moveDown: string }
+    event(event: ReorderNativeEvent): void
+    /** Returns the moved identity; resolve it again after the app updates data. */
+    move(index: number, direction: -1 | 1): ReorderKey | undefined
+    keyAt(index: number): ReorderKey | undefined
+    indexOf(key: ReorderKey): number
+  }): ReorderAdapterDriver
+}