@rafaelaugusto/jolt 0.1.0-beta.16 → 0.1.0-beta.17

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/scene-shader.ts

@@ -0,0 +1,139 @@
+/// <reference types="@nativescript/types-ios/lib/ios/objc-x86_64/objc!SceneKit" preserve="true" />
+import {
+  nativePropertyTarget,
+  registerNativeProperty,
+  type NativeProperty,
+} from './native-property.js'
+
+export type SceneUniformType = 'float' | 'float2' | 'float3' | 'float4'
+export type SceneUniformValue<T extends SceneUniformType> = T extends 'float'
+  ? number
+  : T extends 'float2'
+    ? readonly [number, number]
+    : T extends 'float3'
+      ? readonly [number, number, number]
+      : readonly [number, number, number, number]
+export interface SceneUniformOptions<T extends SceneUniformType> {
+  type: T
+  /** Finite inclusive limits applied to every component; spring overshoot is clamped. */
+  range: readonly [number, number]
+  /** One application-defined unit per component. Vectors have no implicit color conversion. */
+  units: readonly string[]
+  /** Spatial uniforms jump under Reduced Motion; appearance uniforms keep their timing. */
+  motion: 'spatial' | 'appearance'
+}
+function runtime() {
+  if (typeof JoltSceneShaderProperties === 'undefined')
+    throw new Error(
+      'Update @rafaelaugusto/jolt-native and rebuild the native app to use SceneKit environment and shader adapters.',
+    )
+  return JoltSceneShaderProperties
+}
+function sink(
+  create: (error: interop.Reference<NSError>) => JoltPropertySink | null,
+): JoltPropertySink {
+  const error = new interop.Reference<NSError>()
+  const result = create(error)
+  if (!result)
+    throw new Error(
+      error.value?.localizedDescription ??
+        'Invalid SceneKit property target or shader schema.',
+    )
+  return result
+}
+
+/** Scene environment multiplier, nonnegative; leaves the environment/background images untouched. */
+export const sceneKitEnvironmentIntensity: (scene: SCNScene) => NativeProperty<number> =
+  registerNativeProperty<number>({
+    name: 'jolt.scenekit/environment-intensity',
+    units: ['environment illumination multiplier'],
+    platforms: ['ios'],
+    encode: (value) => [value],
+    decode: (values) => values[0]!,
+    validate(value) {
+      if (!Number.isFinite(value) || value < 0)
+        throw new RangeError('Environment intensity must be finite and nonnegative.')
+    },
+    interpolate: (a, b, t) => Math.max(0, a + (b - a) * t),
+    create: (target) =>
+      sink((error) => runtime().environmentError(target as NSObject, error)),
+  })
+
+/** Declared Metal shaderModifiers input, initialized by the application before attachment. */
+export function sceneKitUniform<T extends SceneUniformType>(
+  target: SCNMaterial | SCNGeometry,
+  name: string,
+  options: SceneUniformOptions<T>,
+): NativeProperty<SceneUniformValue<T>> {
+  if (
+    typeof name !== 'string' ||
+    !/^[A-Za-z][A-Za-z0-9_]*$/.test(name) ||
+    /^(u_|a_|v_|scn_)/.test(name)
+  )
+    throw new TypeError(
+      'Use a declared custom uniform identifier without a reserved SceneKit prefix or KVC path.',
+    )
+  if (!options || !['float', 'float2', 'float3', 'float4'].includes(options.type))
+    throw new TypeError('Shader uniforms support float, float2, float3 and float4.')
+  const count = options.type === 'float' ? 1 : Number(options.type.slice(-1))
+  const range = options.range
+  if (
+    !Array.isArray(range) ||
+    range.length !== 2 ||
+    !range.every((n) => Number.isFinite(n) && Math.abs(n) <= 3.4028234663852886e38) ||
+    range[0] >= range[1]
+  )
+    throw new RangeError('Declare an ordered finite range for the shader components.')
+  if (
+    !Array.isArray(options.units) ||
+    options.units.length !== count ||
+    options.units.some((unit) => typeof unit !== 'string' || !unit.trim())
+  )
+    throw new TypeError('Declare one nonempty unit for each shader component.')
+  if (!['spatial', 'appearance'].includes(options.motion))
+    throw new TypeError('Declare whether the shader motion is spatial or appearance.')
+  // Copy the schema: caller mutation cannot change an already attached native sink.
+  const [low, high] = range,
+    type = options.type,
+    units = [...options.units]
+  const vector = (value: SceneUniformValue<T>): number[] => {
+    const values = type === 'float' ? [value] : value
+    if (
+      !Array.isArray(values) ||
+      values.length !== count ||
+      values.some(
+        (n) => typeof n !== 'number' || !Number.isFinite(n) || n < low || n > high,
+      )
+    )
+      throw new RangeError(
+        `${name} needs ${count} finite component(s) in ${low}..${high}.`,
+      )
+    return [...values] as number[]
+  }
+  return nativePropertyTarget(target, {
+    name: `jolt.scenekit/uniform-${name}`,
+    units,
+    platforms: ['ios'],
+    spatial: options.motion === 'spatial',
+    encode: vector,
+    decode: (values) =>
+      (type === 'float' ? values[0]! : [...values]) as SceneUniformValue<T>,
+    interpolate(a, b, t) {
+      const first = vector(a),
+        last = vector(b)
+      const result = first.map((value, i) =>
+        Math.max(low, Math.min(high, value + (last[i]! - value) * t)),
+      )
+      return (type === 'float' ? result[0]! : result) as SceneUniformValue<T>
+    },
+    create: (object) =>
+      sink((error) =>
+        runtime().uniformNameConfigurationError(
+          object as NSObject,
+          name,
+          JSON.stringify({ type, low, high }),
+          error,
+        ),
+      ),
+  })
+}