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

package/src/interactive-navigation/index.ts

@@ -0,0 +1,398 @@
+import { ReturnScope } from '../shared-navigation/return-signal.js'
+import {
+  Application,
+  Image,
+  isIOS,
+  SharedTransition,
+  Transition,
+  Trace,
+  type EventData,
+  type Frame,
+  type NavigationTransition,
+  type Page,
+  type NavigationData,
+} from '@nativescript/core'
+import {
+  resolveReturnTarget,
+  validateReturnTarget,
+  focusReturnTarget,
+  type SharedReturnTarget,
+} from '../shared-navigation/return-target.js'
+import { find, radius, supportedImage } from '../shared-navigation/targets.js'
+import { onReducedMotion, reducedMotion, timeScale } from '../config.js'
+import { springPhysics } from '../spring.js'
+import { springs, type Spring } from '../transition.js'
+
+export type InteractiveNavigationState =
+  'ready' | 'animating' | 'idle' | 'dragging' | 'finishing' | 'cancelling' | 'disposed'
+export interface InteractiveNavigationEvent {
+  state: InteractiveNavigationState
+  outcome?: 'completed' | 'cancelled'
+  shared?: { status: 'ready' | 'unavailable'; reason?: string }
+  /** Present on finishing/cancelling. Velocity is page widths per second. */
+  release?: Readonly<{ progress: number; velocity: number }>
+}
+export interface InteractiveNavigationOptions {
+  /** Optional stable image/card identity in the two pages. Unsupported pairs use normal page motion. */
+  shared?: { tag: string; maxSnapshotPixels?: number; returnTarget?: SharedReturnTarget }
+  /** Same physics as Jolt's live springs. Default smooth; settling is bounded at 3 s. */
+  spring?:
+    | keyof typeof springs
+    | Pick<Spring, 'duration' | 'bounce' | 'stiffness' | 'damping' | 'mass'>
+  /** Synchronous extra gate. Page.enableSwipeBackNavigation is always respected. */
+  canBegin?: () => boolean
+  /** Lifecycle only. Finger updates and spring playback stay in Objective-C. */
+  onState?: (event: InteractiveNavigationEvent) => void
+}
+export interface InteractiveNavigation {
+  readonly supported: boolean
+  /** Use for ONE pushed Frame entry. Pass to Frame.navigate or router.push. */
+  readonly transition: NavigationTransition | undefined
+  readonly state: InteractiveNavigationState
+  /** Rolls back a held drag. A release already committed to UIKit finishes normally. */
+  cancel(): void
+  /** Detaches the gesture; future programmatic back uses UIKit's default transition. */
+  dispose(): void
+}
+
+/** Interactive iOS page navigation using Core's existing UINavigationController delegate. */
+export function interactiveNavigation(
+  frame: Frame,
+  options: InteractiveNavigationOptions = {},
+): InteractiveNavigation {
+  if (
+    options.shared &&
+    (typeof options.shared.tag !== 'string' || !options.shared.tag.trim())
+  )
+    throw new TypeError('A nonempty sharedTransitionTag is required.')
+  validateReturnTarget(options.shared?.returnTarget)
+  const budget = options.shared?.maxSnapshotPixels ?? 8_000_000
+  if (!Number.isSafeInteger(budget) || budget <= 0 || budget > 32_000_000)
+    throw new RangeError('maxSnapshotPixels must be a positive integer at most 32000000.')
+  const input =
+    typeof options.spring === 'string' ? springs[options.spring] : options.spring
+  if (options.spring !== undefined && !input)
+    throw new TypeError('Unknown navigation spring.')
+  for (const [key, value] of Object.entries(input ?? {}) as [string, unknown][]) {
+    if (!['type', 'duration', 'bounce', 'stiffness', 'damping', 'mass'].includes(key))
+      throw new TypeError(`Unsupported navigation spring option: ${key}.`)
+    if (key === 'type' && value !== 'spring')
+      throw new TypeError('Interactive navigation requires a spring.')
+    if (key !== 'type' && (typeof value !== 'number' || !Number.isFinite(value)))
+      throw new RangeError(`${key} must be finite.`)
+    if (['duration', 'stiffness', 'mass'].includes(key) && (value as number) <= 0)
+      throw new RangeError(`${key} must be positive.`)
+    if (key === 'damping' && (value as number) < 0)
+      throw new RangeError('damping must be nonnegative.')
+  }
+  const physics = springPhysics(input ?? springs.smooth)
+  if (Object.values(physics).some((value) => !Number.isFinite(value)))
+    throw new RangeError('Navigation spring physics must be finite.')
+  const supported = isIOS && typeof JoltInteractiveNavigation !== 'undefined'
+  let state: InteractiveNavigationState = 'ready'
+  let native: JoltInteractiveNavigation | undefined, page: Page | undefined
+  let candidate: Page | undefined
+  let start: (() => void) | undefined
+  let transitioning = false
+  let fromPage: Page | undefined, toPage: Page | undefined
+  let shared: InteractiveNavigationEvent['shared']
+  let targetScope: ReturnScope | undefined
+  let detachTarget: (() => void) | undefined
+  let resolvedReturn: import('@nativescript/core').View | undefined
+  let returning = false
+  const originalPage = frame.currentPage
+  function prepareShared() {
+    if (!native || !options.shared) return
+    if (returning && options.shared.returnTarget && toPage) {
+      targetScope?.abort()
+      detachTarget?.()
+      detachTarget = undefined
+      const scope = (targetScope = new ReturnScope())
+      resolvedReturn = undefined
+      const targetPage = toPage,
+        owner = native,
+        sharedOptions = options.shared
+      void resolveReturnTarget(
+        sharedOptions.returnTarget!,
+        sharedOptions.tag,
+        targetPage,
+        scope.signal,
+      ).then((result) => {
+        if (scope.signal.aborted || state === 'disposed' || native !== owner) return
+        if (result.view) {
+          resolvedReturn = result.view
+          installShared()
+          const target = result.view
+          const invalidated = () => {
+            shared = { status: 'unavailable', reason: 'target-invalidated' }
+            owner.cancel()
+          }
+          const events = [
+            'bindingContextChange',
+            'sharedTransitionTagChange',
+            'imageSourceChange',
+            'unloaded',
+          ]
+          for (const event of events) target.on(event, invalidated)
+          detachTarget = () => {
+            for (const event of events) target.off(event, invalidated)
+          }
+        } else shared = { status: 'unavailable', reason: result.reason }
+        owner.completeSharedPreparation()
+      })
+      return
+    }
+    installShared()
+  }
+  function installShared() {
+    if (!native || !options.shared) return
+    const unavailable = (reason: string) => {
+      shared = { status: 'unavailable', reason }
+    }
+    if (reducedMotion()) return unavailable('reduced-motion')
+    const sources = find(fromPage, options.shared.tag, true),
+      targets = find(toPage, options.shared.tag, true)
+    if (sources.length !== 1)
+      return unavailable(sources.length ? 'duplicate-source' : 'missing-source')
+    if (targets.length !== 1)
+      return unavailable(targets.length ? 'duplicate-target' : 'missing-target')
+    const source = sources[0]!,
+      target = targets[0]!,
+      image = source instanceof Image
+    if (
+      image &&
+      (!supportedImage(source) ||
+        !supportedImage(target) ||
+        (source.src !== target.src && source.imageSource !== target.imageSource))
+    )
+      return unavailable('unsupported-image')
+    if (!image && target instanceof Image) return unavailable('content-mismatch')
+    try {
+      shared = native.prepareSharedFromToImageFromRadiusToRadiusMaxPixels(
+        source.nativeViewProtected,
+        target.nativeViewProtected,
+        image,
+        radius(source),
+        radius(target),
+        budget,
+      )
+        ? { status: 'ready' }
+        : { status: 'unavailable', reason: 'unsupported-geometry' }
+    } catch {
+      unavailable('native-unavailable')
+    }
+  }
+  let transition: NavigationTransition | undefined
+  let releaseMotion: (() => void) | undefined
+  const emit = (
+    next: InteractiveNavigationState,
+    outcome?: InteractiveNavigationEvent['outcome'],
+    release?: InteractiveNavigationEvent['release'],
+  ) => {
+    if (state === 'disposed') return
+    state = next
+    try {
+      options.onState?.({
+        state,
+        ...(shared ? { shared } : {}),
+        ...(outcome ? { outcome } : {}),
+        ...(release ? { release } : {}),
+      })
+    } catch (error) {
+      Trace.write(
+        `Interactive navigation observer failed: ${String(error)}`,
+        'Jolt',
+        Trace.messageType.error,
+      )
+    }
+  }
+  const cancel = () => {
+    targetScope?.abort()
+    native?.cancel()
+  }
+  const unload = () => control.dispose()
+  const shown = () => native?.sync()
+  const swipeChanged = () => {
+    void Promise.resolve().then(shown)
+  }
+  const arrived = () => {
+    if (transitioning) return
+    // clearHistory/replace/programmatic pop also release the entry's recognizer.
+    if (
+      page &&
+      frame.currentPage !== page &&
+      !frame.backStack.some((entry) => entry.resolvedPage === page)
+    )
+      void Promise.resolve().then(() => control.dispose())
+    else shown()
+  }
+  const entering = (args: EventData) => {
+    const event = args as NavigationData
+    if (!page && !event.isBack) candidate = event.entry?.resolvedPage
+  }
+  class PageMotion extends Transition {
+    override setupInteractiveGesture(callback: () => void) {
+      start = callback
+    }
+    override iosNavigatedController(
+      nav: UINavigationController,
+      operation: number,
+      from: UIViewController,
+      to: UIViewController,
+    ) {
+      if (state === 'disposed' || nav !== frame.ios.controller) return undefined
+      if (operation === 1) {
+        // An entry owns one transition. Reusing its instance never steals another page.
+        if (page || candidate?.ios !== to) return undefined
+        page = candidate
+        page.on('enableSwipeBackNavigationChange', swipeChanged)
+      }
+      if (!page) return undefined
+      const pages = [
+        originalPage,
+        page,
+        ...frame.backStack.map((entry) => entry.resolvedPage),
+      ]
+      fromPage = pages.find((candidate) => candidate?.ios === from)
+      toPage = pages.find((candidate) => candidate?.ios === to)
+      shared = undefined
+      returning = operation !== 1
+      transitioning = true
+      if (!native) {
+        native = JoltInteractiveNavigation.attachStiffnessDampingMassShouldBeginOnEvent(
+          nav,
+          physics.stiffness,
+          physics.damping,
+          physics.mass,
+          () => {
+            try {
+              return (
+                state === 'idle' &&
+                !!start &&
+                !reducedMotion() &&
+                !!page &&
+                frame.currentPage === page &&
+                page.enableSwipeBackNavigation &&
+                frame.canGoBack() &&
+                (options.canBegin?.() ?? true) === true
+              )
+            } catch {
+              return false
+            }
+          },
+          (event) => {
+            if (state === 'disposed') return
+            if (event === 8) {
+              prepareShared()
+              return
+            }
+            if (event === 2) {
+              transitioning = true
+              frame.transitionId = this.id
+              SharedTransition.updateState(this.id, {
+                interactiveBegan: true,
+                interactiveCancelled: false,
+              })
+              emit('dragging')
+              start?.()
+            } else if (event === 3 || event === 4) {
+              emit(
+                event === 3 ? 'finishing' : 'cancelling',
+                undefined,
+                native && { progress: native.progress, velocity: native.velocity },
+              )
+            } else if (event === 0) emit('animating')
+            else {
+              targetScope?.abort()
+              targetScope = undefined
+              detachTarget?.()
+              detachTarget = undefined
+              if (returning && event !== 6 && toPage && options.shared?.returnTarget) {
+                let focus = resolvedReturn
+                if (!focus)
+                  try {
+                    focus = options.shared.returnTarget.fallbackFocus?.(toPage)
+                  } catch {}
+                focusReturnTarget(toPage, focus)
+              }
+              transitioning = false
+              SharedTransition.updateState(this.id, {
+                interactiveBegan: false,
+                interactiveCancelled: event === 6,
+              })
+              emit(
+                'idle',
+                event === 5 ? 'completed' : event === 6 ? 'cancelled' : undefined,
+              )
+              arrived()
+            }
+          },
+        )
+      }
+      if (options.shared) native.sharedEnabled = true
+      native.sharedDeferred = !!(returning && options.shared?.returnTarget)
+      native.prepareOperationPresentedReducedTimeScale(
+        operation,
+        page.ios,
+        reducedMotion(),
+        timeScale(),
+      )
+      return native
+    }
+    override iosInteractionDismiss() {
+      return native?.interactive ? native : undefined
+    }
+  }
+  const control: InteractiveNavigation = {
+    supported,
+    get transition() {
+      return transition
+    },
+    get state() {
+      return state
+    },
+    cancel,
+    dispose() {
+      if (state === 'disposed') return
+      targetScope?.abort()
+      targetScope = undefined
+      detachTarget?.()
+      detachTarget = undefined
+      // Complete UIKit's context before releasing Core's interactive state.
+      native?.disposeRestoringSwipe(
+        !!page?.enableSwipeBackNavigation && frame.canGoBack(),
+      )
+      native = undefined
+      emit('disposed')
+      releaseMotion?.()
+      frame.off('unloaded', unload)
+      frame.off('navigatingTo', entering)
+      frame.off('navigatedTo', arrived)
+      frame.off('viewControllerShown', shown)
+      Application.off(Application.suspendEvent, cancel)
+      if (transition?.instance) SharedTransition.finishState(transition.instance.id)
+      page?.off('enableSwipeBackNavigationChange', swipeChanged)
+      start = undefined
+      page = undefined
+      candidate = undefined
+      fromPage = undefined
+      toPage = undefined
+    },
+  }
+  if (supported) {
+    if (!frame.isLoaded || !frame.ios?.controller)
+      throw new Error('Create interactiveNavigation after the Frame is loaded.')
+    transition = SharedTransition.custom(new PageMotion(), {
+      interactive: { dismiss: {} },
+    })
+    frame.on('navigatingTo', entering)
+    frame.on('navigatedTo', arrived)
+    frame.on('viewControllerShown', shown)
+    frame.on('unloaded', unload)
+    Application.on(Application.suspendEvent, cancel)
+    releaseMotion = onReducedMotion((value) => {
+      if (value) cancel()
+    })
+  }
+  return control
+}

package/src/ios-plugin.d.ts

@@ -1,3 +1,136 @@
+declare class JoltBlur extends NSObject {
+  static attachOptions(view: UIView, options: string): JoltBlur
+  static liveCount(): number
+  static activeCount(): number
+  paint(amount: number): void
+  play(program: string): void
+  controlPaused(time: number, paused: boolean): void
+  resize(): void
+  snapshot(): string
+  dispose(): void
+}
+declare class JoltSensorSource extends NSObject {
+  static createOptionsOnState(
+    kind: string,
+    options: string,
+    changed: () => void,
+  ): JoltSensorSource
+  static activeCount(): number
+  static sourceCount(): number
+  connectIndex(node: JoltLiveSpring, index: number): void
+  setEnabledPaused(active: boolean, paused: boolean): void
+  snapshot(): string
+  recenter(): void
+  replay(trace: string): void
+  dispose(): void
+}
+declare class JoltScrollHeader extends NSObject {
+  static attachNodeTitleToolbarTitleToolbarDiagnosticOptionsOnState(
+    list: UITableView,
+    node: JoltLiveSpring,
+    title: UIView,
+    toolbarTitle: UIView,
+    toolbar: UIView,
+    diagnostic: UILabel | null,
+    options: string,
+    onState: () => void,
+  ): JoltScrollHeader
+  static activeCount(): number
+  configure(options: string): void
+  snapshot(): string
+  scrollAnimated(offset: number, animated: boolean): void
+  setEnabled(value: boolean): void
+  dispose(): void
+}
+declare class JoltMotionProbe extends NSObject {
+  static startViewCapacityHertz(
+    view: UIView,
+    capacity: number,
+    hertz: number,
+  ): JoltMotionProbe
+  static activeCount(): number
+  drain(): string
+  dispose(): void
+}
+declare class JoltReorderHandle extends UIButton {
+  onMove: ((direction: number) => void) | null
+}
+declare class JoltReorderSession extends NSObject {
+  static attachOptionsOnState(
+    list: UITableView,
+    options: string,
+    callback: (state: number, index: number, toIndex: number) => void,
+  ): JoltReorderSession
+  readonly active: boolean
+  registerHandle(view: UIView): void
+  setEnabled(enabled: boolean): void
+  setReducedMotion(reduced: boolean): void
+  cancel(): void
+  dispose(): void
+}
+declare class JoltGestureSession extends NSObject {
+  static supportsContactEvents(): boolean
+  static supportsScrollReplay(): boolean
+  static hasSession(surface: UIView): boolean
+  replayScrollDeltaVelocity(phase: number, delta: number, velocity: number): void
+  replayScrollOffset(offset: number): void
+  static attachScrollXYScaleRotationOptionsOnState(
+    surface: UIView,
+    scroll: UIScrollView | null,
+    x: JoltLiveSpring,
+    y: JoltLiveSpring,
+    scale: JoltLiveSpring,
+    rotation: JoltLiveSpring,
+    options: string,
+    onState: (state: number, velocityX: number, velocityY: number) => void,
+  ): JoltGestureSession
+  readonly active: boolean
+  cancel(): void
+  refreshScrollDelegate(): void
+  setEnabled(value: boolean): void
+  settleXYScaleRotationAnimated(
+    x: number,
+    y: number,
+    scale: number,
+    rotation: number,
+    animated: boolean,
+  ): void
+  updateLeftRightTopBottom(left: number, right: number, top: number, bottom: number): void
+  dispose(): void
+}
+declare class JoltLiveSpring extends NSObject {
+  static createStiffnessDampingMassRestDeltaRestSpeedReduced(
+    initial: number,
+    stiffness: number,
+    damping: number,
+    mass: number,
+    restDelta: number,
+    restSpeed: number,
+    reduced: boolean,
+  ): JoltLiveSpring
+  static activeCount(): number
+  static nodeCount(): number
+  static sync(view: UIView): void
+  readonly position: number
+  readonly velocity: number
+  readonly moving: boolean
+  followMappings(source: JoltLiveSpring, mappings: string): void
+  updateInput(snapshot: string): void
+  setTarget(value: number): void
+  setReduced(value: boolean): void
+  setPaused(value: boolean): void
+  bindPropertyMappings(
+    view: UIView,
+    property: string,
+    mappings: string,
+  ): JoltLiveSpringBinding
+  dispose(): void
+}
+declare class JoltLiveSpringBinding extends NSObject {
+  readonly value: number
+  setLayers(inputs: string): void
+  cancel(): void
+}
 declare class JoltInteractiveAnimation extends NSObject {
   static startViewLayersKeyPathValuesTimesDurationDelayRepeatReverseFinalValueStartedAtCompletion(
     view: UIView,
@@ -79,3 +212,149 @@ declare class JoltPhotoZoom extends NSObject {
   layout(): void
   stop(): void
 }
+
+declare class JoltPropertySink extends NSObject {
+  static scalarTargetKeyPath(target: NSObject, keyPath: string): JoltPropertySink
+  readonly dimensions: number
+  readonly alive: boolean
+  readonly compiled: boolean
+  read(): NSArray<number>
+  write(values: NSArray<number>): void
+  dispose(): void
+}
+declare class JoltPropertyPlayer extends NSObject {
+  static startSinkTimesValuesFinalValueDurationDelayRepeatReverseCompletion(
+    sink: JoltPropertySink,
+    times: NSArray<number>,
+    values: NSArray<number>,
+    finalValue: NSArray<number>,
+    duration: number,
+    delay: number,
+    repeat: number,
+    reverse: boolean,
+    completion: (completed: boolean) => void,
+  ): JoltPropertyPlayer
+  readonly elapsed: number
+  readonly frames: number
+  static activeCount(): number
+  controlPaused(time: number, paused: boolean): void
+  cancel(): void
+}
+declare class JoltReferenceProperties extends NSObject {
+  static sceneFieldOfView(camera: NSObject): JoltPropertySink
+  static sceneCameraSinkCount(): number
+  static sceneCameraWriteCount(): number
+  static mapCoordinate(target: NSObject): JoltPropertySink
+  static mapCamera(target: NSObject): JoltPropertySink
+  static scenePose(target: NSObject): JoltPropertySink
+  static sceneLightIntensity(target: NSObject): JoltPropertySink
+  static sceneLightColor(target: NSObject): JoltPropertySink
+  static sceneMaterialTransparency(target: NSObject): JoltPropertySink
+  static sceneMaterialDiffuse(target: NSObject): JoltPropertySink
+  static sceneMaterialEmission(target: NSObject): JoltPropertySink
+  static sceneAppearanceSinkCount(): number
+  static sceneAppearanceWriteCount(): number
+}
+
+declare class JoltSceneShaderProperties extends NSObject {
+  static environmentError(
+    scene: NSObject,
+    error: interop.Reference<NSError>,
+  ): JoltPropertySink | null
+  static uniformNameConfigurationError(
+    target: NSObject,
+    name: string,
+    configuration: string,
+    error: interop.Reference<NSError>,
+  ): JoltPropertySink | null
+  static sinkCount(): number
+  static writeCount(): number
+}
+
+declare class JoltSharedLayoutFlight extends UIView {
+  holdPageMaxPixels(page: UIView, maxPixels: number): boolean
+  fadeOnEnd(duration: number, onEnd: (completed: boolean) => void): void
+  static captureNavigationImageRadiusMaxPixels(
+    view: UIView,
+    radius: number,
+    maxPixels: number,
+  ): JoltSharedLayoutFlight | null
+  static captureClippedNavigationImageRadiusMaxPixels(
+    view: UIView,
+    radius: number,
+    maxPixels: number,
+  ): JoltSharedLayoutFlight | null
+  prepareNavigationImageRadiusMaxPixels(
+    view: UIView,
+    radius: number,
+    maxPixels: number,
+  ): string | null
+  static captureImageRadiusMaxPixels(
+    view: UIView,
+    image: boolean,
+    radius: number,
+    maxPixels: number,
+  ): JoltSharedLayoutFlight | null
+  static activeCount(): number
+  pixels(): number
+  state(): string
+  prepareImageRadiusMaxPixels(
+    view: UIView,
+    image: boolean,
+    radius: number,
+    maxPixels: number,
+  ): string | null
+  freeze(maxPixels: number): boolean
+  playOnEnd(configuration: string, onEnd: (completed: boolean) => void): void
+  dispose(): void
+}
+declare class JoltInteractiveNavigation extends NSObject {
+  sharedEnabled: boolean
+  sharedDeferred: boolean
+  completeSharedPreparation(): void
+  prepareSharedFromToImageFromRadiusToRadiusMaxPixels(
+    from: UIView,
+    to: UIView,
+    image: boolean,
+    fromRadius: number,
+    toRadius: number,
+    maxPixels: number,
+  ): boolean
+  static attachStiffnessDampingMassShouldBeginOnEvent(
+    nav: UINavigationController,
+    stiffness: number,
+    damping: number,
+    mass: number,
+    shouldBegin: () => boolean,
+    onEvent: (event: number) => void,
+  ): JoltInteractiveNavigation
+  static activeCount(): number
+  static recognizerCount(): number
+  readonly interactive: boolean
+  readonly progress: number
+  readonly velocity: number
+  prepareOperationPresentedReducedTimeScale(
+    operation: number,
+    presented: UIViewController,
+    reduced: boolean,
+    timeScale: number,
+  ): void
+  sync(): void
+  cancel(): void
+  disposeRestoringSwipe(enabled: boolean): void
+}
+
+declare class JoltCircleWorld extends NSObject {
+  static createOptions(container: UIView, options: string): JoltCircleWorld
+  static worldCount(): number
+  static activeCount(): number
+  connectIndex(view: UIView, index: number): void
+  setEnabled(active: boolean): void
+  resizeHeight(width: number, height: number): void
+  impulseXY(index: number, x: number, y: number): void
+  attachOptions(index: number, options: string): void
+  snapToTarget(index: number, target: number): void
+  reset(): void
+  snapshot(): string
+  dispose(): void
+}