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

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

package/src/sampling.ts

@@ -0,0 +1,173 @@
+/** Maximum linear interpolation error in property units, not screen pixels. */
+export interface SamplingOptions {
+  duration: number
+  position(time: number): number
+  tolerance: number
+  /** Bound on linear interpolation error across this complete interval. */
+  errorBound?(start: number, end: number): number
+  /** Playback milliseconds per source millisecond. */
+  slowdown?: number
+  /** Unknown user functions retain at least 120 uniform intervals per second. */
+  custom?: boolean
+  /** Mandatory times in source milliseconds, including piecewise curve seams. */
+  breakpoints?: readonly number[]
+  /** Non-expansive property clamp and the values where its slope changes. */
+  projection?: { apply(value: number): number; breaks: readonly number[] }
+}
+
+export const MAX_SAMPLE_INTERVALS = 6000
+const MAX_EVALUATIONS = 24000
+const MAX_DEPTH = 24
+const MAX_INTERVAL_MS = 100
+const PROBES = [0.25, 0.5, 0.75] as const
+const NO_BREAKS: readonly number[] = []
+
+export interface SampledCurve {
+  times: number[]
+  values: number[]
+  sampling: {
+    method: 'adaptive' | 'uniform-fallback'
+    tolerance: number
+    /** Only true when every accepted interval passed an analytical bound. */
+    bounded: boolean
+    evaluations: number
+    reason?: 'sample-limit' | 'evaluation-limit' | 'invalid-bound'
+  }
+}
+
+/** Curves are sampled only at setup. Work and output are bounded independently. */
+export function sampleCurve(options: SamplingOptions): SampledCurve {
+  const {
+    duration,
+    position,
+    tolerance,
+    errorBound,
+    custom = false,
+    slowdown = 1,
+  } = options
+  let evaluations = 0
+  const project = options.projection?.apply ?? ((value: number) => value)
+  const at = (time: number) => {
+    evaluations++
+    return position(time)
+  }
+  const maxInterval = (custom ? 1000 / 120 : MAX_INTERVAL_MS) / slowdown
+  const seeds = Math.max(1, Math.ceil(duration / maxInterval))
+  let reason: SampledCurve['sampling']['reason']
+  const initial = at(0)
+  const times = [0],
+    values = [project(initial)]
+  const append = (time: number, value: number) => {
+    if (times.length >= MAX_SAMPLE_INTERVALS + 1) {
+      reason = 'sample-limit'
+      return
+    }
+    times.push(duration > 0 ? time / duration : 1)
+    values.push(project(value))
+  }
+  const split = (a: number, b: number, va: number, vb: number, depth: number) => {
+    if (reason) return
+    if (evaluations >= MAX_EVALUATIONS) {
+      reason = 'evaluation-limit'
+      return
+    }
+    let accepted: boolean
+    if (errorBound) {
+      let bound = errorBound(a, b)
+      // Clamping is non-expansive, but clamping a chord's endpoints can create a
+      // different chord. Bound that extra error at each crossed clamp boundary.
+      let clampError = 0
+      for (const edge of options.projection?.breaks ?? NO_BREAKS) {
+        const fraction = (edge - va) / (vb - va)
+        if (fraction > 0 && fraction < 1)
+          clampError = Math.max(
+            clampError,
+            Math.abs(
+              project(edge) - (project(va) + (project(vb) - project(va)) * fraction),
+            ),
+          )
+      }
+      bound += clampError
+      if (!Number.isFinite(bound) || bound < 0) {
+        reason = 'invalid-bound'
+        return
+      }
+      accepted = bound <= tolerance
+    } else {
+      // Three probes plus a safety margin, never a mathematical guarantee for a user function.
+      let error = 0
+      for (const fraction of PROBES)
+        error = Math.max(
+          error,
+          Math.abs(
+            project(at(a + (b - a) * fraction)) -
+              (project(va) + (project(vb) - project(va)) * fraction),
+          ),
+        )
+      accepted = error <= tolerance * 0.5
+    }
+    if (accepted) {
+      append(b, vb)
+      return
+    }
+    const mid = (a + b) / 2
+    if (depth >= MAX_DEPTH || mid === a || mid === b) {
+      reason = 'sample-limit'
+      return
+    }
+    const vm = at(mid)
+    split(a, mid, va, vm, depth + 1)
+    split(mid, b, vm, vb, depth + 1)
+  }
+  if (seeds > MAX_SAMPLE_INTERVALS || !Number.isFinite(duration)) reason = 'sample-limit'
+  else if (duration === 0) append(0, at(0))
+  else {
+    const boundaries = [
+      ...new Set([
+        ...Array.from({ length: seeds + 1 }, (_, i) =>
+          i === seeds ? duration : (duration * i) / seeds,
+        ),
+        ...(options.breakpoints ?? []).filter((t) => t > 0 && t < duration),
+      ]),
+    ].sort((a, b) => a - b)
+    let previous = initial
+    for (let i = 0; i < boundaries.length - 1 && !reason; i++) {
+      const a = boundaries[i]!,
+        b = boundaries[i + 1]!
+      const value = at(b)
+      split(a, b, previous, value, 0)
+      previous = value
+    }
+  }
+  if (!reason)
+    return {
+      times,
+      values,
+      sampling: { method: 'adaptive', tolerance, bounded: !!errorBound, evaluations },
+    }
+  // Preserve the old capped 60 Hz representation if refinement cannot meet its budget.
+  // Explicit segment endpoints are still retained by the caller. No precision claim on fallback.
+  const steps = Math.max(
+    1,
+    Math.min(MAX_SAMPLE_INTERVALS, Math.ceil((duration * slowdown * 60) / 1000)),
+  )
+  const fallbackTimes = [
+    ...new Set([
+      ...Array.from({ length: steps + 1 }, (_, i) => i / steps),
+      ...(options.breakpoints ?? [])
+        .filter((t) => t > 0 && t < duration)
+        .map((t) => t / duration),
+    ]),
+  ].sort((a, b) => a - b)
+  return {
+    times: fallbackTimes,
+    values: fallbackTimes.map((t) => project(at(t * duration))),
+    sampling: {
+      method: 'uniform-fallback',
+      tolerance,
+      bounded: false,
+      evaluations,
+      reason,
+    },
+  }
+}

package/src/scene-appearance.ts

@@ -0,0 +1,92 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import { Color } from '@nativescript/core'
+import { colorMixer, parseColor, type ColorValue } from './color.js'
+import { registerNativeProperty, type NativeProperty } from './native-property.js'
+
+const clamp = (n: number) => Math.max(0, Math.min(1, n))
+function scalar(name: string, maximum: number, create: (target: object) => object) {
+  return registerNativeProperty<number>({
+    name: `jolt.scenekit/${name}`,
+    units: [
+      name === 'light-intensity'
+        ? 'lumens (PBR); 1000 = unit multiplier otherwise'
+        : 'opacity fraction',
+    ],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0 || value > maximum)
+        throw new RangeError(`${name} needs a finite value in 0..${maximum}.`)
+    },
+    interpolate: (a, b, t) => Math.max(0, Math.min(maximum, a + (b - a) * t)),
+    create,
+  })
+}
+function color(name: string, create: (target: object) => object) {
+  return registerNativeProperty<ColorValue>({
+    name: `jolt.scenekit/${name}`,
+    // Premultiply the sampled sRGB channels, so native linear interpolation also handles zero alpha.
+    units: [
+      'premultiplied sRGB red',
+      'premultiplied sRGB green',
+      'premultiplied sRGB blue',
+      'alpha',
+    ],
+    platforms: ['ios'],
+    encode(value) {
+      const argb = parseColor(value),
+        alpha = (argb >>> 24) / 255
+      return [
+        (((argb >>> 16) & 255) / 255) * alpha,
+        (((argb >>> 8) & 255) / 255) * alpha,
+        ((argb & 255) / 255) * alpha,
+        alpha,
+      ]
+    },
+    decode(values) {
+      const alpha = clamp(values[3]!)
+      const channel = (i: number) =>
+        Math.round(clamp(alpha ? values[i]! / alpha : 0) * 255)
+      return new Color(
+        ((Math.round(alpha * 255) << 24) |
+          (channel(0) << 16) |
+          (channel(1) << 8) |
+          channel(2)) >>>
+          0,
+      )
+    },
+    interpolate: (a, b, t) => new Color(colorMixer(parseColor(a), parseColor(b))(t)),
+    create,
+  })
+}
+
+/** SCNLight intensity, finite and nonnegative. Non-spatial: retains timing under reduced motion. */
+export const sceneKitLightIntensity: (light: SCNLight) => NativeProperty<number> = scalar(
+  'light-intensity',
+  Infinity,
+  (target) => JoltReferenceProperties.sceneLightIntensity(target as NSObject),
+)
+/** Solid UIColor/CGColor light color. Returns a normalized sRGB Color from get(). */
+export const sceneKitLightColor: (light: SCNLight) => NativeProperty<ColorValue> = color(
+  'light-color',
+  (target) => JoltReferenceProperties.sceneLightColor(target as NSObject),
+)
+/** SCNMaterial transparency in 0..1; does not change transparencyMode/transparent contents. */
+export const sceneKitMaterialTransparency: (
+  material: SCNMaterial,
+) => NativeProperty<number> = scalar('material-transparency', 1, (target) =>
+  JoltReferenceProperties.sceneMaterialTransparency(target as NSObject),
+)
+/** Solid color diffuse contents only; never converts a texture into a color. */
+export const sceneKitMaterialDiffuse: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-diffuse', (target) =>
+  JoltReferenceProperties.sceneMaterialDiffuse(target as NSObject),
+)
+/** Solid color emission contents only; does not make the material illuminate nearby geometry. */
+export const sceneKitMaterialEmission: (
+  material: SCNMaterial,
+) => NativeProperty<ColorValue> = color('material-emission', (target) =>
+  JoltReferenceProperties.sceneMaterialEmission(target as NSObject),
+)