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

package/src/live-spring-driver.ts

@@ -37,6 +37,8 @@ export interface LiveNode {
   moving(): boolean
   follow(source: LiveNode, maps: readonly LiveMapping[]): void
   update(input: LiveInput): void
+  /** Several sampled inputs over a rest value, each on its own clock, summed natively. */
+  inputs(rest: number, inputs: readonly LiveInput[]): void
   reduced(value: boolean): void
   paused(value: boolean): void
   bind(view: View, property: NumericProperty, maps: readonly LiveMapping[]): LiveBinding
@@ -58,6 +60,17 @@ export function liveSpringDriver(): LiveSpringDriver {
     )
   return nativeDriver
 }
+/** Native composition is optional: an app binary without the classes keeps sampled playback. */
+export function liveComposition(): LiveSpringDriver | undefined {
+  return override ?? (available() ? nativeDriver : undefined)
+}
+export const stillPhysics: LiveSpringPhysics = {
+  stiffness: 100,
+  damping: 20,
+  mass: 1,
+  restDelta: 0.001,
+  restSpeed: 0.01,
+}
 function available() {
   return isAndroid
     ? typeof org !== 'undefined' &&
@@ -104,6 +117,7 @@ const nativeDriver: LiveSpringDriver = {
           input.running
             ? native.updateInput(JSON.stringify(input))
             : native.setTarget(input.value),
+        inputs: (rest, inputs) => native.setInputs(rest, JSON.stringify(inputs)),
         reduced: (value) => native.setReduced(value),
         paused: (value) => native.setPaused(value),
         bind(view, property, maps) {
@@ -145,6 +159,7 @@ const nativeDriver: LiveSpringDriver = {
         input.running
           ? native.updateInput(JSON.stringify(input))
           : native.setTarget(input.value),
+      inputs: (rest, inputs) => native.setInputsRest(JSON.stringify(inputs), rest),
       reduced: (value) => native.setReduced(value),
       paused: (value) => native.setPaused(value),
       bind(view, property, maps) {

package/src/mixer.ts

@@ -2,7 +2,13 @@ import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import type { Track } from './track.js'
-import type { LiveInput } from './live-spring-driver.js'
+import {
+  liveComposition,
+  stillPhysics,
+  type LiveBinding,
+  type LiveInput,
+  type LiveNode,
+} from './live-spring-driver.js'
 
 /** The channel of regular animations; layers are named next to it. */
 export const BASE = ''
@@ -11,7 +17,10 @@ const SAMPLES_PER_SECOND = 60
 const MAX_SAMPLES = 6000
 /** Endless channels loop natively over the least common multiple of their periods, up to this. */
 const MAX_LOOP = 30000
-/** Beyond it, the composition is played in windows and sampled again at each one. */
+/**
+ * Beyond it, a native composer plays the layers without rebuilding. An app binary
+ * without the native classes falls back to windows sampled again every few seconds.
+ */
 const WINDOW = 4000
 
 export const multiplies = (property: Property) =>
@@ -69,6 +78,7 @@ export function mixFor(view: View, property: Property): Mix {
 /** One property of one view: a base and named layers, played natively as one composite track. */
 export class Mix {
   private live: { read(): number; layers(inputs: readonly LiveInput[]): void } | undefined
+  private composer: { node: LiveNode; binding: LiveBinding } | undefined
   private readonly rests = new Map<string, number>()
   private readonly channels = new Map<string, Channel>()
   private native: unknown
@@ -93,6 +103,7 @@ export class Mix {
     read(): number
     layers(inputs: readonly LiveInput[]): void
   }): () => void {
+    this.release()
     this.live = base
     this.compose()
     return () => {
@@ -201,6 +212,30 @@ export class Mix {
     })
   }
 
+  /** Every channel and rest as a native layer; the base is one of them unless something else owns it. */
+  private inputs(now: number, withBase: boolean): LiveInput[] {
+    const layers: LiveInput[] = []
+    for (const key of new Set([...this.rests.keys(), ...this.channels.keys()])) {
+      if (key === BASE && !withBase) continue
+      const channel = this.channels.get(key)
+      const value = this.part(key, now, now)
+      const track = channel?.track
+      layers.push({
+        value,
+        running: !!channel && !channel.paused,
+        elapsed: this.elapsed(key, now),
+        duration: track?.duration ?? 0,
+        delay: track?.delay ?? 0,
+        repeat: track ? (Number.isFinite(track.repeat) ? track.repeat : -1) : 0,
+        reverse: track?.reverse ?? false,
+        to: track?.to ?? value,
+        times: track?.times ?? [],
+        values: track?.values ?? [],
+      })
+    }
+    return layers
+  }
+
   /** Samples the composition from now and plays it as one native track. */
   private compose() {
     const driver = getDriver()
@@ -211,26 +246,7 @@ export class Mix {
 
     if (this.live) {
       if (previous !== undefined) driver.stop(this.view, previous)
-      const layers: LiveInput[] = []
-      for (const key of new Set([...this.rests.keys(), ...this.channels.keys()])) {
-        if (key === BASE) continue
-        const channel = this.channels.get(key)
-        const value = this.part(key, now, now)
-        const track = channel?.track
-        layers.push({
-          value,
-          running: !!channel && !channel.paused,
-          elapsed: this.elapsed(key, now),
-          duration: track?.duration ?? 0,
-          delay: track?.delay ?? 0,
-          repeat: track ? (Number.isFinite(track.repeat) ? track.repeat : -1) : 0,
-          reverse: track?.reverse ?? false,
-          to: track?.to ?? value,
-          times: track?.times ?? [],
-          values: track?.values ?? [],
-        })
-      }
-      this.live.layers(layers)
+      this.live.layers(this.inputs(now, false))
       return
     }
 
@@ -248,11 +264,14 @@ export class Mix {
     if (previous !== undefined) driver.stop(this.view, previous)
     const loop = finite <= 0 && periods.length ? leastCommonMultiple(periods) : undefined
     if (finite <= 0 && !periods.length) {
+      this.release()
       writeValue(this.view, this.property, this.value(now))
       driver.sync?.(this.view)
       this.dissolve()
       return
     }
+    if (finite <= 0 && loop === undefined && this.composeNatively(now)) return
+    this.release()
 
     const span = finite > 0 ? finite : (loop ?? WINDOW)
     const steps = Math.max(
@@ -292,6 +311,27 @@ export class Mix {
     if (elapsed > 1) driver.control?.(this.view, native, elapsed, false)
   }
 
+  /** Endless layers with no common period play on a native composer instead of rolling windows. */
+  private composeNatively(now: number): boolean {
+    const live = liveComposition()
+    if (!live || !layerable(this.property) || !this.view.nativeViewProtected) return false
+    if (!this.composer) {
+      const node = live.create(identity(this.property), stillPhysics, true)
+      const binding = node.bind(this.view, this.property, [])
+      this.composer = { node, binding }
+    }
+    this.composer.binding.layers(this.inputs(now, true))
+    return true
+  }
+
+  private release() {
+    const composer = this.composer
+    if (!composer) return
+    this.composer = undefined
+    composer.binding.cancel()
+    composer.node.dispose()
+  }
+
   private dissolve() {
     if (this.live || this.channels.size) return
     for (const [key, value] of this.rests)

package/src/motion-value.ts

@@ -16,13 +16,16 @@ import {
 } from './color.js'
 import { onReducedMotion, reducedMotion, timeScale } from './config.js'
 import { springPhysics, type SpringParams } from './spring.js'
-import { mixFor } from './mixer.js'
+import { layerable, mixFor } from './mixer.js'
 import {
+  type LiveBinding,
+  type LiveInput,
+  type LiveMapping,
+  type LiveNode,
+  liveComposition,
   liveSpringDriver,
+  stillPhysics,
   syncLiveSprings,
-  type LiveNode,
-  type LiveMapping,
-  type LiveBinding,
 } from './live-spring-driver.js'
 import {
   clampDecoration,
@@ -44,7 +47,7 @@ import {
 import type { KeyframeProperty, Target } from './types.js'
 import { playbackSource, type PlaybackAnimation, type PlaybackClock } from './playback.js'
 import { TimedAnimation } from './timed-animation.js'
-import { valueTrack } from './value-track.js'
+import { compositionSpan, valueTrack } from './value-track.js'
 import {
   ValueObservers,
   type SubscribeOptions,
@@ -108,6 +111,8 @@ interface Run {
   readonly track: Track
   readonly base: number
   readonly span: number
+  /** The track's samples in the value's units, ready for a native composer. */
+  readonly scaled: readonly number[]
   readonly animation: TimedAnimation
   readonly startedAt: number
   readonly clock?: Pick<PlaybackClock, 'time'>
@@ -213,7 +218,10 @@ class Root extends Derived {
   private readonly rests = new Map<string, number>()
   private readonly runs = new Map<string, Run>()
   private presentation: Presentation | undefined
+  private presented = false
   private cancelPresentation: (() => void) | undefined
+  private composer: LiveNode | undefined
+  private composition: { rest: number; inputs: LiveInput[] } | undefined
 
   constructor(initial: number) {
     super(undefined, (value) => value, false)
@@ -345,6 +353,7 @@ class Root extends Derived {
       track,
       base,
       span,
+      scaled: track.values.map((value) => base + span * value),
       animation,
       startedAt: driver.now(),
       clock: { time: () => animation.time },
@@ -398,6 +407,74 @@ class Root extends Derived {
   private sync() {
     this.cancelPresentation?.()
     this.cancelPresentation = undefined
+    this.presentation = undefined
+    this.presented = false
+    const now = getDriver().now()
+    const runs = [...this.runs.values()].filter((run) => !run.animation.paused)
+    const span =
+      runs.length > 1
+        ? compositionSpan(
+            runs.map((run) => ({ track: run.track, elapsed: this.runTime(run, now) })),
+          )
+        : undefined
+    this.composition = span?.windowed && liveComposition() ? this.inputs(now) : undefined
+    if (this.composition)
+      this.composer?.inputs(this.composition.rest, this.composition.inputs)
+    else {
+      this.settle()
+      this.present()
+    }
+    this.changed()
+  }
+
+  /** Every run as a native input on its own clock; rests and paused runs stand still. */
+  private inputs(now: number) {
+    let rest = 0
+    for (const [key, value] of this.rests) if (!this.runs.has(key)) rest += value
+    const inputs: LiveInput[] = []
+    for (const run of this.runs.values()) {
+      const elapsed = this.runTime(run, now)
+      const { track } = run
+      inputs.push({
+        value: run.base + run.span * track.valueAt(elapsed),
+        running: !run.animation.paused,
+        elapsed,
+        duration: track.duration,
+        delay: track.delay,
+        repeat: Number.isFinite(track.repeat) ? track.repeat : -1,
+        reverse: track.reverse,
+        to: run.base + run.span * track.to,
+        times: track.times,
+        values: run.scaled,
+      })
+    }
+    return { rest, inputs }
+  }
+
+  /** The native composer a binding joins while this value would otherwise roll windows. */
+  composerNode(): LiveNode | undefined {
+    const composition = this.composition
+    if (!composition) return undefined
+    if (!this.composer) {
+      const live = liveComposition()
+      if (!live) return undefined
+      this.composer = live.create(this.raw(), stillPhysics, true)
+      this.composer.inputs(composition.rest, composition.inputs)
+    }
+    return this.composer
+  }
+
+  /** Drops the composer once no binding needs it or the composition stops rolling. */
+  settle() {
+    if (this.composition && this.bindings.size) return
+    this.composer?.dispose()
+    this.composer = undefined
+  }
+
+  /** Sampled at once for tracks, on demand while bindings sit on the composer. */
+  private present(): Presentation | undefined {
+    if (this.presented) return this.presentation
+    this.presented = true
     const now = getDriver().now()
     let rest = 0
     for (const [key, value] of this.rests) if (!this.runs.has(key)) rest += value
@@ -429,7 +506,7 @@ class Root extends Derived {
         clock?.cancel()
       }
     }
-    this.changed()
+    return this.presentation
   }
 
   protected changed() {
@@ -440,7 +517,7 @@ class Root extends Derived {
 
   /** The plan that plays this value's run, mapped, on one bound property. */
   plan(binding: Binding): Plan {
-    const run = this.presentation
+    const run = this.present()
     const { property, read } = binding
     const write = (value: number) =>
       isDecorationProperty(property)
@@ -495,12 +572,13 @@ class Root extends Derived {
 
   /** Capture the current native presentation clock, even if a later command replaces it. */
   captureTime(): () => number {
-    const run = this.presentation
+    const run = this.present()
     return run ? () => this.runTime(run) : () => 0
   }
 
   elapsed(): number {
-    return this.presentation ? this.runTime(this.presentation) : 0
+    const run = this.present()
+    return run ? this.runTime(run) : 0
   }
 
   get paused(): boolean {
@@ -862,6 +940,16 @@ function attach(view: View, property: Property, source: Derived) {
   const root = source.root
   if (root instanceof SpringRoot)
     return attachSpring(view, property as NumericProperty, source, root)
+  let native: LiveBinding | undefined, composer: LiveNode | undefined
+  let releaseMix: (() => void) | undefined
+  const detach = () => {
+    if (!native) return
+    native.cancel()
+    releaseMix?.()
+    releaseMix = undefined
+    native = composer = undefined
+    syncLiveSprings(view)
+  }
   const binding: Binding = {
     view,
     property,
@@ -870,6 +958,24 @@ function attach(view: View, property: Property, source: Derived) {
     read: source.read,
     sync() {
       if (!view.isLoaded || !view.nativeViewProtected) return
+      const node = layerable(property) && !source.color ? root.composerNode() : undefined
+      if (node) {
+        if (composer === node) return
+        detach()
+        binding.animation?.stop()
+        binding.animation = undefined
+        stopBase(view, [property])
+        const handle = node.bind(view, property as NumericProperty, source.mappings)
+        native = handle
+        composer = node
+        releaseMix = mixFor(view, property).attachLive({
+          read: () => handle.value(),
+          layers: (layers) => handle.layers(layers),
+        })
+        syncLiveSprings(view)
+        return
+      }
+      detach()
       if (!root.running) {
         // A value at rest writes straight through, so scroll offsets cost one write per event.
         binding.animation?.stop()
@@ -894,12 +1000,17 @@ function attach(view: View, property: Property, source: Derived) {
         animation.seekTime(elapsed)
       binding.animation = animation
     },
+    cleanup() {
+      view.off('unloaded', detach)
+      detach()
+    },
   }
   let properties = bound.get(view)
   if (!properties) bound.set(view, (properties = new Map()))
   properties.set(property, binding)
   root.bindings.add(binding)
   view.on('loaded', binding.sync)
+  view.on('unloaded', detach)
   try {
     binding.sync()
   } catch (error) {
@@ -1134,6 +1245,7 @@ function release(binding: Binding) {
   const properties = bound.get(binding.view)
   if (properties?.get(binding.property) === binding) properties.delete(binding.property)
   binding.cleanup?.()
+  binding.root.settle()
 }
 
 /** A regular animation on a bound property takes it over; the value keeps its other bindings. */

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 {

package/src/value-track.ts

@@ -15,22 +15,12 @@ export function valueTrack(parts: readonly ValuePart[], rest: number) {
         sum + part.base + part.span * part.track.valueAt(part.elapsed + time),
       rest,
     )
-  let finite = 0
-  const periods: number[] = []
-  for (const { track, elapsed } of parts) {
-    if (Number.isFinite(track.end)) finite = Math.max(finite, track.end - elapsed)
-    else if (elapsed < track.delay) finite = Math.max(finite, track.delay - elapsed)
-    else periods.push(Math.max(1, track.duration * (track.reverse ? 2 : 1)))
-  }
-  if (finite <= 0 && !periods.length)
-    return { track: instantTrack('x', value(0)), windowed: false }
-  const loop = finite <= 0 && periods.length ? commonPeriod(periods) : undefined
-  // Bound finite compositions too: a minutes-long base must not undersample a short pulse.
-  const duration = finite > 0 ? Math.min(finite, 4000) : (loop ?? 4000)
+  const span = compositionSpan(parts)
+  if (!span) return { track: instantTrack('x', value(0)), windowed: false }
+  const { duration, endless, windowed } = span
   const steps = Math.max(1, Math.min(6000, Math.ceil((duration * 60) / 1000)))
   const times = Array.from({ length: steps + 1 }, (_, i) => i / steps)
   const values = times.map((time) => value(time * duration))
-  const endless = loop !== undefined
   const at = (time: number) =>
     value(
       endless
@@ -51,8 +41,29 @@ export function valueTrack(parts: readonly ValuePart[], rest: number) {
     valueAt: at,
     velocityAt: (time) => (at(time + 0.5) - at(time - 0.5)) * 1000,
   }
+  return { track, windowed }
+}
+
+/**
+ * How long one sampled composition can play before it needs rebuilding. A rolling
+ * window repeats every four seconds; native composition avoids it entirely.
+ */
+export function compositionSpan(parts: readonly Pick<ValuePart, 'track' | 'elapsed'>[]) {
+  let finite = 0
+  const periods: number[] = []
+  for (const { track, elapsed } of parts) {
+    if (Number.isFinite(track.end)) finite = Math.max(finite, track.end - elapsed)
+    else if (elapsed < track.delay) finite = Math.max(finite, track.delay - elapsed)
+    else periods.push(Math.max(1, track.duration * (track.reverse ? 2 : 1)))
+  }
+  if (finite <= 0 && !periods.length) return undefined
+  const loop = finite <= 0 && periods.length ? commonPeriod(periods) : undefined
+  // Bound finite compositions too: a minutes-long base must not undersample a short pulse.
+  const duration = finite > 0 ? Math.min(finite, 4000) : (loop ?? 4000)
+  const endless = loop !== undefined
   return {
-    track,
+    duration,
+    endless,
     windowed:
       finite > duration ||
       (!endless && parts.some(({ track }) => !Number.isFinite(track.end))),