@rafaelaugusto/jolt 0.1.0-rc.2 → 0.1.0-rc.3

package/src/interactive-navigation/modal.ts

@@ -0,0 +1,306 @@
+import {
+  Application,
+  isIOS,
+  SharedTransition,
+  Trace,
+  Transition,
+  View,
+  type NavigationTransition,
+} from '@nativescript/core'
+import { onReducedMotion, reducedMotion, timeScale } from '../config.js'
+import { springPhysics } from '../spring.js'
+import { springs, type Spring } from '../transition.js'
+
+export type InteractiveModalState =
+  | 'ready'
+  | 'presenting'
+  | 'idle'
+  | 'dragging'
+  | 'finishing'
+  | 'cancelling'
+  | 'closed'
+  | 'disposed'
+export interface InteractiveModalEvent {
+  state: InteractiveModalState
+  outcome?: 'completed' | 'cancelled'
+  /** Modal heights per second; supplied only at release. */
+  release?: Readonly<{ progress: number; velocity: number }>
+}
+export interface InteractiveModalOptions {
+  spring?:
+    | keyof typeof springs
+    | Pick<Spring, 'duration' | 'bounce' | 'stiffness' | 'damping' | 'mass'>
+  /** Synchronous gesture gate. Core's cancelable:false is also respected. */
+  canBegin?: () => boolean
+  /** Boundaries only; gesture updates and settling execute in Objective-C. */
+  onState?: (event: InteractiveModalEvent) => void
+}
+export interface InteractiveModal {
+  readonly supported: boolean
+  /** Use for one Core showModal / NativeScript-Vue $showModal presentation. */
+  readonly transition: NavigationTransition | undefined
+  readonly state: InteractiveModalState
+  /** Close once, forwarding Core's callback arguments. Queues during opening. */
+  close(...args: unknown[]): boolean
+  /** Roll back a held drag; an already committed release finishes normally. */
+  cancel(): void
+  /** Detach without closing the modal. Core closeModal remains available. */
+  dispose(): void
+}
+
+/** A full-window iOS modal transition using NativeScript's modal owner/delegate. */
+export function interactiveModal(
+  options: InteractiveModalOptions = {},
+): InteractiveModal {
+  const input =
+    typeof options.spring === 'string' ? springs[options.spring] : options.spring
+  if (options.spring !== undefined && !input) throw new TypeError('Unknown modal 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 modal spring option: ${key}.`)
+    if (key === 'type' && value !== 'spring')
+      throw new TypeError('Modal motion 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('Modal spring physics must be finite.')
+  const supported =
+    isIOS &&
+    typeof JoltInteractiveModal !== 'undefined' &&
+    typeof View.closedModallyEvent === 'string'
+  let state: InteractiveModalState = 'ready'
+  let transition: NavigationTransition | undefined
+  let view: View | undefined, native: JoltInteractiveModal | undefined
+  let start: (() => void) | undefined, offMotion: (() => void) | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let pendingClose: unknown[] | undefined
+  let disposing = false,
+    suspended = false,
+    shown = false,
+    returning = false
+  const update = (value: {
+    interactiveBegan?: boolean
+    interactiveCancelled?: boolean
+  }) => {
+    if (transition?.instance) SharedTransition.updateState(transition.instance.id, value)
+  }
+  const emit = (
+    next: InteractiveModalState,
+    outcome?: InteractiveModalEvent['outcome'],
+    release?: InteractiveModalEvent['release'],
+  ) => {
+    if (state === 'disposed') return
+    state = next
+    try {
+      options.onState?.({
+        state,
+        ...(outcome ? { outcome } : {}),
+        ...(release ? { release } : {}),
+      })
+    } catch (error) {
+      Trace.write(
+        `Interactive modal observer failed: ${String(error)}`,
+        'Jolt',
+        Trace.messageType.error,
+      )
+    }
+  }
+  const release = () => {
+    if (state === 'disposed') return
+    if (timer !== undefined) clearTimeout(timer)
+    timer = undefined
+    view?.off('shownModally', arrived)
+    view?.off('closedModally', closed)
+    view?.off('unloaded', unloaded)
+    Application.off(Application.suspendEvent, suspend)
+    Application.off(Application.resumeEvent, resume)
+    offMotion?.()
+    offMotion = undefined
+    native?.dispose()
+    native = undefined
+    if (transition?.instance) SharedTransition.finishState(transition.instance.id)
+    view = undefined
+    start = undefined
+    pendingClose = undefined
+    emit('disposed')
+  }
+  const cancelled = () => {
+    if (state === 'disposed') return
+    // UIKit's dismissal completion must observe interactiveCancelled before we
+    // clear it. Core clears interactiveBegan after preserving the modal's owner.
+    const core = transition?.instance && SharedTransition.getState(transition.instance.id)
+    if (core?.interactiveBegan) {
+      timer = setTimeout(cancelled, 10)
+      return
+    }
+    timer = undefined
+    update({ interactiveCancelled: false })
+    emit('idle', 'cancelled')
+    if (disposing) release()
+  }
+  const arrived = () => {
+    shown = true
+    // UIKit skips animator creation for Core's animated:false. Keep ordinary
+    // close usable; no native interactive recognizer is attached in that mode.
+    if (state === 'ready') emit('idle')
+    if (pendingClose && state === 'idle') {
+      const args = pendingClose
+      pendingClose = undefined
+      control.close(...args)
+    }
+  }
+  const closed = () => {
+    if (state === 'disposed' || state === 'closed') return
+    emit('closed', 'completed')
+    release()
+  }
+  const checkDetached = () => {
+    timer = undefined
+    if (
+      !suspended &&
+      view &&
+      !view.isLoaded &&
+      !view.viewController?.presentingViewController
+    )
+      control.dispose()
+  }
+  const unloaded = () => {
+    if (state === 'cancelling') return
+    if (timer !== undefined) clearTimeout(timer)
+    timer = setTimeout(checkDetached, 0)
+  }
+  const suspend = () => {
+    suspended = true
+    native?.cancel()
+  }
+  const resume = () => {
+    suspended = false
+    if (state !== 'cancelling') unloaded()
+  }
+  class ModalMotion extends Transition {
+    override setupInteractiveGesture(callback: () => void, modal: View) {
+      if (view || state === 'disposed')
+        throw new Error('Use a fresh interactiveModal for each presentation.')
+      view = modal
+      start = callback
+      view.on('shownModally', arrived)
+      view.on('closedModally', closed)
+      view.on('unloaded', unloaded)
+    }
+    override iosPresentedController(presented: UIViewController) {
+      if (native || state === 'disposed' || !view) return undefined
+      returning = false
+      native = JoltInteractiveModal.attachStiffnessDampingMassShouldBeginOnEvent(
+        presented,
+        physics.stiffness,
+        physics.damping,
+        physics.mass,
+        () => {
+          try {
+            return (
+              !disposing &&
+              shown &&
+              state === 'idle' &&
+              !suspended &&
+              (options.canBegin?.() ?? true) === true
+            )
+          } catch {
+            return false
+          }
+        },
+        (event) => {
+          if (state === 'disposed') return
+          if (event === 2) {
+            update({ interactiveBegan: true, interactiveCancelled: false })
+            emit('dragging')
+            start?.()
+          } else if (event === 3 || event === 4) {
+            update({ interactiveCancelled: event === 4 })
+            emit(
+              event === 3 ? 'finishing' : 'cancelling',
+              undefined,
+              native && { progress: native.progress, velocity: native.velocity },
+            )
+          } else if (event === 0) emit(returning ? 'finishing' : 'presenting')
+          else if (event === 1) {
+            emit('idle')
+            if (disposing) release()
+            else if (shown) arrived()
+          } else if (event === 6) cancelled()
+          // Core's closedModally event owns final disposal and callback delivery.
+        },
+      )
+      native.preparePresentingReducedTimeScale(true, reducedMotion(), timeScale())
+      return native
+    }
+    override iosDismissedController() {
+      if (!native || state === 'disposed') return undefined
+      returning = true
+      native.preparePresentingReducedTimeScale(false, reducedMotion(), timeScale())
+      return native
+    }
+    override iosInteractionDismiss() {
+      return native?.interactive ? native : undefined
+    }
+  }
+  const control: InteractiveModal = {
+    supported,
+    get transition() {
+      return transition
+    },
+    get state() {
+      return state
+    },
+    close(...args) {
+      if (
+        !supported ||
+        disposing ||
+        ['closed', 'disposed', 'dragging', 'finishing', 'cancelling'].includes(state)
+      )
+        return false
+      if (!shown || state === 'presenting' || state === 'ready') {
+        if (pendingClose) return false
+        pendingClose = args
+        return true
+      }
+      if (!view) return false
+      update({ interactiveBegan: false, interactiveCancelled: false })
+      emit('finishing')
+      view.closeModal(...args)
+      return true
+    },
+    cancel() {
+      native?.cancel()
+    },
+    dispose() {
+      if (state === 'disposed' || disposing) return
+      disposing = true
+      pendingClose = undefined
+      native?.cancel()
+      if (
+        state !== 'dragging' &&
+        state !== 'cancelling' &&
+        state !== 'finishing' &&
+        state !== 'presenting'
+      )
+        release()
+    },
+  }
+  if (supported) {
+    transition = SharedTransition.custom(new ModalMotion(), {
+      interactive: { dismiss: {} },
+    })
+    Application.on(Application.suspendEvent, suspend)
+    Application.on(Application.resumeEvent, resume)
+    offMotion = onReducedMotion((value) => {
+      if (value) control.cancel()
+    })
+  }
+  return control
+}

package/src/ios-plugin.d.ts

@@ -343,6 +343,28 @@ declare class JoltInteractiveNavigation extends NSObject {
   cancel(): void
   disposeRestoringSwipe(enabled: boolean): void
 }
+declare class JoltInteractiveModal extends NSObject {
+  static attachStiffnessDampingMassShouldBeginOnEvent(
+    controller: UIViewController,
+    stiffness: number,
+    damping: number,
+    mass: number,
+    shouldBegin: () => boolean,
+    onEvent: (event: number) => void,
+  ): JoltInteractiveModal
+  static activeCount(): number
+  static recognizerCount(): number
+  readonly interactive: boolean
+  readonly progress: number
+  readonly velocity: number
+  preparePresentingReducedTimeScale(
+    presenting: boolean,
+    reduced: boolean,
+    timeScale: number,
+  ): void
+  cancel(): void
+  dispose(): void
+}
 
 declare class JoltCircleWorld extends NSObject {
   static createOptions(container: UIView, options: string): JoltCircleWorld

package/src/scroll-header/geometry.ts

@@ -61,13 +61,18 @@ export function headerGeometry(
   }
 }
 
-/** Keep the visible rows anchored when late artwork/text changes the header height. */
+/** Keep collapsed rows relative to the pinned edge; keep expanded content in place. */
 export function resizedOffset(
   offset: number,
   before: ScrollHeaderGeometry,
   after: ScrollHeaderGeometry,
 ) {
-  return offset <= 0 ? 0 : Math.max(0, offset + after.spacer - before.spacer)
+  if (offset <= 0) return 0
+  // Growing the compact title/section must not cover the previously visible row.
+  // Its position relative to the pinned bottom is range + row position - offset.
+  const delta =
+    offset >= before.range ? after.range - before.range : after.spacer - before.spacer
+  return Math.max(0, offset + delta)
 }
 
 export function restoredOffset(

package/src/scroll-header/index.ts

@@ -137,6 +137,7 @@ export function scrollHeader(list: ListView, options: ScrollHeaderOptions): Scro
   const host = list.parent
   const saved = {
     clip: host.clipToBounds,
+    nativeClip: isIOS ? (host.nativeViewProtected as UIView)?.clipsToBounds : undefined,
     headerClip: header.clipToBounds,
     headerY: header.translateY,
     titleY: title.translateY,
@@ -284,6 +285,13 @@ export function scrollHeader(list: ListView, options: ScrollHeaderOptions): Scro
   }
   const measure = async () => {
     if (ended || !list.isLoaded || !header.isLoaded) return
+    // Core's default-valued property can be true while a plain UIView still
+    // has clipping disabled. Apply it when the native host exists, too.
+    if (isIOS && host.nativeViewProtected) {
+      const container = host.nativeViewProtected as UIView
+      saved.nativeClip ??= container.clipsToBounds
+      container.clipsToBounds = true
+    }
     const generation = revision
     await layout(host)
     if (ended || generation !== revision) return
@@ -509,6 +517,10 @@ export function scrollHeader(list: ListView, options: ScrollHeaderOptions): Scro
       set(artwork, { y: saved.artworkY, scaleX: saved.scaleX, scaleY: saved.scaleY })
       artwork.originY = saved.originY
       host.clipToBounds = saved.clip
+      if (isIOS && host.nativeViewProtected && saved.nativeClip !== undefined) {
+        const container = host.nativeViewProtected as UIView
+        if (container.clipsToBounds) container.clipsToBounds = saved.nativeClip
+      }
       header.clipToBounds = saved.headerClip
       options.setSpacerHeight(options.originalSpacerHeight ?? 0)
       if (owners.get(list) === control) owners.delete(list)

package/src/shapes/index.ts

@@ -44,7 +44,7 @@ function resolve(base: ShapeFrame, values: ShapeValues): ShapeFrame {
     )
   return { path, start, end }
 }
-/** Draw an owned native vector surface over a view. Create after native layout. */
+/** Draw an owned native vector surface over a view. Attaches once the view is loaded. */
 export function shape(target: Target, options: ShapeOptions): Shape {
   if (!options || typeof options !== 'object')
     throw new TypeError('Shape options are required.')
@@ -77,8 +77,6 @@ export function shape(target: Target, options: ShapeOptions): Shape {
   )
     throw new TypeError('Invalid shape cap, join or fill rule.')
   const view = toView(target)
-  if (!view.isLoaded || !view.nativeViewProtected)
-    throw new Error('Create shapes after native layout.')
   if (owners.has(view))
     throw new Error('This view already owns a shape. Dispose it first.')
   return new ShapeOwner(view, style, frame)
@@ -92,6 +90,7 @@ class ShapeOwner implements Shape {
     track: Track
     from: ShapeFrame
     to: ShapeFrame
+    started: boolean
   }
   private suspended = false
   private backgrounded = false
@@ -101,7 +100,7 @@ class ShapeOwner implements Shape {
     private readonly style: ShapeStyle,
     private frame: ShapeFrame,
   ) {
-    this.attach()
+    if (view.isLoaded && view.nativeViewProtected) this.attach()
     owners.set(view, this)
     view.on('loaded', this.layout)
     view.on('layoutChanged', this.layout)
@@ -128,7 +127,8 @@ class ShapeOwner implements Shape {
     if (this.native && this.native !== this.view.nativeViewProtected) this.unload()
     if (!this.painter) {
       this.attach()
-      if (this.active) {
+      if (this.active && !this.active.started) this.begin()
+      else if (this.active) {
         const { from, to, track, animation } = this.active
         this.painter!.play(from, to, track)
         this.painter!.control(animation.time, true)
@@ -140,6 +140,18 @@ class ShapeOwner implements Shape {
       this.suspended = false
     }
   }
+  private begin() {
+    const { from, to, track, animation } = this.active!
+    this.active!.started = true
+    if (track.end > 0) {
+      this.painter!.play(from, to, track)
+      animation.seekTime(0)
+    } else {
+      this.frame = to
+      this.painter!.paint(to)
+    }
+    animation.start()
+  }
   private unload = () => {
     if (this.backgrounded && this.active) this.frame = this.painter?.read() ?? this.frame
     else this.stop()
@@ -180,9 +192,7 @@ class ShapeOwner implements Shape {
   }
   animate(values: ShapeValues, options: Transition | SpringName = {}) {
     this.alive()
-    if (!this.painter || !this.view.isLoaded)
-      throw new Error('Load the shape before animating.')
-    const from = this.painter.read(),
+    const from = this.painter?.read() ?? this.frame,
       to = resolve(from, values)
     compatible(from.path, to.path)
     if (typeof options === 'string' && !Object.hasOwn(springs, options))
@@ -229,8 +239,9 @@ class ShapeOwner implements Shape {
         if (this.active?.animation === animation) this.active = undefined
       },
     )
-    this.active = { animation, track, from, to }
+    this.active = { animation, track, from, to, started: !!this.painter }
     try {
+      if (!this.painter) return animation
       if (track.end > 0) this.painter.play(from, to, track)
       else {
         this.frame = to

package/src/types.ts

@@ -53,9 +53,12 @@ export type Values = {
   [K in KeyframeProperty]?: Exclude<Keyframes[K], readonly unknown[]>
 }
 
-/** A view, or anything that holds one: a NativeScript-Vue element, an Angular `ElementRef`. */
+/** A view, or anything that holds one: a NativeScript-Vue element or component instance, an Angular `ElementRef`. */
 export type Target =
-  View | { readonly nativeView: View } | { readonly nativeElement: View }
+  | View
+  | { readonly nativeView: View }
+  | { readonly nativeElement: View }
+  | { readonly $el: View | { readonly nativeView: View } }
 
 /** Translation velocities in DIPs per second. Omitted axes keep their current motion. */
 export interface DecayVelocity {