@rafaelaugusto/jolt 0.1.0-rc.13 → 0.1.0-rc.14

package/src/core/text-pieces.ts

@@ -0,0 +1,52 @@
+import { graphemes, type Grapheme } from './roll-diff.js'
+
+export type TextGrouping = 'letter' | 'word'
+
+/** A grapheme or word segment, with its position in text order. */
+export interface TextPiece extends Grapheme {
+  group: number
+}
+
+/** Text effects split at most this many graphemes. */
+export const MAX_TEXT_GRAPHEMES = 256
+
+/**
+ * Letters are extended grapheme clusters. Words are the Unicode word segments the
+ * platform reports, with spaces and punctuation as pieces of their own.
+ */
+export function textPieces(text: string, by: TextGrouping): TextPiece[] {
+  if (by === 'letter') return graphemes(text).map((part, group) => ({ ...part, group }))
+  const pieces: TextPiece[] = []
+  if (typeof Intl === 'undefined' || !('Segmenter' in Intl)) {
+    let start = 0
+    for (const [segment] of text.matchAll(/\s+|\S+/gu)) {
+      pieces.push({
+        text: segment,
+        start,
+        end: start + segment.length,
+        group: pieces.length,
+      })
+      start += segment.length
+    }
+    return pieces
+  }
+  const segmenter = new Intl.Segmenter(undefined, { granularity: 'word' })
+  for (const { segment, index } of segmenter.segment(text))
+    pieces.push({
+      text: segment,
+      start: index,
+      end: index + segment.length,
+      group: pieces.length,
+    })
+  return pieces
+}
+
+/** Whitespace keeps its place in the order but draws nothing. */
+export function isVisiblePiece(piece: Pick<TextPiece, 'text'>): boolean {
+  return piece.text.trim() !== ''
+}
+
+/** Milliseconds from the start of the effect until the piece at `index` begins. */
+export function staggeredStart(index: number, stagger: number, delay: number): number {
+  return delay + index * stagger
+}

package/src/drag.ts

@@ -54,6 +54,8 @@ export interface DragOptions {
   rubberband?: boolean
   /** Decay retention per millisecond. Defaults to 0.998. */
   friction?: number
+  /** A descendant view that alone receives the pan; the dragged view still moves. */
+  handle?: Target
   onStart?: (event: DragEvent) => void
   onMove?: (event: DragEvent) => void
   onRelease?: (event: DragRelease) => void
@@ -92,6 +94,7 @@ interface Settings {
   axes: Axis[]
   curves: Record<Axis, DragCurve>
   value: Root | undefined
+  handle: View | undefined
   callbacks: Pick<DragOptions, 'onStart' | 'onMove' | 'onCancel' | 'onSettle'> & {
     onRelease?: (event: DragRelease<Animation>) => void
   }
@@ -185,7 +188,13 @@ function settings(options: DragOptions | DragValueOptions): Settings {
   for (const callback of Object.values(callbacks))
     if (callback !== undefined && typeof callback !== 'function')
       throw new TypeError('Drag callbacks must be functions.')
-  return { axes, curves, value: value && asRoot(value), callbacks }
+  const handle = options.handle === undefined ? undefined : toView(options.handle)
+  return { axes, curves, value: value && asRoot(value), handle, callbacks }
+}
+function inside(view: View, handle: View) {
+  for (let node = handle.parent as View | undefined; node; node = node.parent as View)
+    if (node === view) return true
+  return false
 }
 
 /**
@@ -198,12 +207,16 @@ export function drag(target: Target, options: DragOptions | DragValueOptions = {
   return createDrag(target, options)
 }
 
+export interface AnchoredDrag extends Drag {
+  /** Offset an active contact's translation in DIPs without moving it under the finger. */
+  shift(x: number, y: number): void
+}
 /** Internal adapter hook: inspect the final input before native release motion changes model values. */
 export function dragBeforeRelease(
   target: Target,
   options: DragOptions,
   beforeRelease: () => void,
-): Drag {
+): AnchoredDrag {
   return createDrag(target, options, beforeRelease)
 }
 
@@ -211,9 +224,11 @@ function createDrag(
   target: Target,
   options: DragOptions | DragValueOptions,
   beforeRelease?: () => void,
-): Drag {
+): AnchoredDrag {
   const view = toView(target)
   const config = settings(options) // Invalid replacements leave the existing owner intact.
+  if (config.handle && !inside(view, config.handle))
+    throw new TypeError('A drag handle must be a descendant of the dragged view.')
   const previous = owners.get(view)
   const controller = new DragController(view, config, beforeRelease)
   owners.set(view, controller)
@@ -227,7 +242,7 @@ function createDrag(
   return controller
 }
 
-class DragController implements Drag {
+class DragController implements AnchoredDrag {
   private active = false
   private disabled = false
   private destroyed = false
@@ -238,15 +253,20 @@ class DragController implements Drag {
   private release: Animation | undefined
   private input = new DragInput()
   private origin = { x: 0, y: 0 }
+  private delta = { x: 0, y: 0, velocityX: 0, velocityY: 0 }
   private last: DragEvent = { x: 0, y: 0, velocityX: 0, velocityY: 0 }
   private lengths = { x: 200, y: 200 }
+  private surface: View
   constructor(
     private view: View,
     private config: Settings,
     private beforeRelease?: () => void,
   ) {
-    view.on('loaded', this.attach)
-    view.on('unloaded', this.unload)
+    this.surface = config.handle ?? view
+    for (const node of new Set([view, this.surface])) {
+      node.on('loaded', this.attach)
+      node.on('unloaded', this.unload)
+    }
     Application.on(Application.suspendEvent, this.suspend)
     Application.on(Application.resumeEvent, this.resume)
     this.attach()
@@ -293,8 +313,10 @@ class DragController implements Drag {
   dispose = () => {
     if (this.destroyed) return
     this.destroyed = true
-    this.view.off('loaded', this.attach)
-    this.view.off('unloaded', this.unload)
+    for (const node of new Set([this.view, this.surface])) {
+      node.off('loaded', this.attach)
+      node.off('unloaded', this.unload)
+    }
     Application.off(Application.suspendEvent, this.suspend)
     Application.off(Application.resumeEvent, this.resume)
     if (owners.get(this.view) === this) owners.delete(this.view)
@@ -306,20 +328,27 @@ class DragController implements Drag {
       this.destroyed ||
       this.disabled ||
       this.background ||
-      !this.view.isLoaded
+      !this.view.isLoaded ||
+      !this.surface.isLoaded
     )
       return
     this.blocked = false
     this.attached = true
-    this.view.on('touch', this.touch)
-    this.view.on('pan', this.pan)
+    this.surface.on('touch', this.touch)
+    this.surface.on('pan', this.pan)
   }
   private detach = () => {
     this.attached = false
-    this.view.off('touch', this.touch)
-    this.view.off('pan', this.pan)
+    this.surface.off('touch', this.touch)
+    this.surface.off('pan', this.pan)
     this.cancel()
   }
+  shift = (x: number, y: number) => {
+    if (!this.active || this.destroyed || !Number.isFinite(x) || !Number.isFinite(y))
+      return
+    this.origin = { x: this.origin.x + x, y: this.origin.y + y }
+    this.place()
+  }
   private unload = () => this.detach()
   private suspend = () => {
     this.background = true
@@ -339,7 +368,11 @@ class DragController implements Drag {
   private pan = (data: EventData) => {
     const event = data as PanGestureEventData
     if (!this.attached || this.destroyed || this.disabled || this.background) return
-    if (this.view.isEnabled === false) {
+    if (
+      this.view.isEnabled === false ||
+      this.surface.isEnabled === false ||
+      (this.surface !== this.view && !inside(this.view, this.surface))
+    ) {
       this.cancel()
       return
     }
@@ -385,31 +418,13 @@ class DragController implements Drag {
     if (!this.active) return
     const generation = this.generation
     if (Number.isFinite(input.x) && Number.isFinite(input.y)) {
-      const position = { x: this.last.x, y: this.last.y }
-      let vx = 0,
-        vy = 0
-      for (const axis of this.config.axes) {
-        const curve = this.config.curves[axis]
-        const raw = this.origin[axis] + input[axis]
-        const distance = raw - clampDrag(raw, curve.bounds)
-        const resistance =
-          distance === 0
-            ? 1
-            : curve.rubberband
-              ? 0.55 / (1 + Math.abs(distance) / this.lengths[axis]) ** 2
-              : 0
-        position[axis] = curve.rubberband
-          ? resistDrag(raw, curve.bounds, this.lengths[axis])
-          : clampDrag(raw, curve.bounds)
-        if (axis === 'x') vx = input.velocityX * resistance
-        else vy = input.velocityY * resistance
-        if (this.config.value) this.config.value.setBase(position[axis])
-        else {
-          stopBase(this.view, [axis])
-          setBase(this.view, axis, position[axis])
-        }
+      this.delta = {
+        x: input.x,
+        y: input.y,
+        velocityX: input.velocityX,
+        velocityY: input.velocityY,
       }
-      this.last = { ...position, velocityX: vx, velocityY: vy }
+      this.place()
       if (event.state !== 3)
         this.emit(() => this.config.callbacks.onMove?.({ ...this.last }))
     }
@@ -420,6 +435,34 @@ class DragController implements Drag {
         if (this.active && generation === this.generation) this.finish()
       })
   }
+  private place() {
+    const input = this.delta
+    const position = { x: this.last.x, y: this.last.y }
+    let vx = 0,
+      vy = 0
+    for (const axis of this.config.axes) {
+      const curve = this.config.curves[axis]
+      const raw = this.origin[axis] + input[axis]
+      const distance = raw - clampDrag(raw, curve.bounds)
+      const resistance =
+        distance === 0
+          ? 1
+          : curve.rubberband
+            ? 0.55 / (1 + Math.abs(distance) / this.lengths[axis]) ** 2
+            : 0
+      position[axis] = curve.rubberband
+        ? resistDrag(raw, curve.bounds, this.lengths[axis])
+        : clampDrag(raw, curve.bounds)
+      if (axis === 'x') vx = input.velocityX * resistance
+      else vy = input.velocityY * resistance
+      if (this.config.value) this.config.value.setBase(position[axis])
+      else {
+        stopBase(this.view, [axis])
+        setBase(this.view, axis, position[axis])
+      }
+    }
+    this.last = { ...position, velocityX: vx, velocityY: vy }
+  }
   private emit(callback: () => void) {
     try {
       callback()

package/src/drop-zones.ts

@@ -1,6 +1,6 @@
 import { Application, Trace, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
-import { dragBeforeRelease, type Drag, type DragOptions } from './drag.js'
+import { dragBeforeRelease, type AnchoredDrag, type DragOptions } from './drag.js'
 import {
   createDropPolicy,
   type DropOptions,
@@ -9,7 +9,15 @@ import {
 } from './core/drop.js'
 import type { Target } from './types.js'
 
-export type { DropEvent, DropTarget, DropZones, DropEffect } from './core/drop.js'
+export type {
+  DropEvent,
+  DropMoveEvent,
+  DropPadding,
+  DropRect,
+  DropTarget,
+  DropZones,
+  DropEffect,
+} from './core/drop.js'
 export interface DropZoneOptions extends DropOptions<View> {
   drag?: Omit<DragOptions, 'onStart' | 'onMove' | 'onRelease' | 'onCancel' | 'onSettle'>
 }
@@ -27,7 +35,7 @@ export function dropZones(target: Target, options: DropZoneOptions): DropZones {
     'value' in inputOptions
   )
     throw new TypeError('Drop zones own drag callbacks and move the source view itself.')
-  let input: Drag | undefined,
+  let input: AnchoredDrag | undefined,
     handoff = false,
     background = Application.suspended
   const geometry = isIOS ? undefined : new org.rafaelaugusto.jolt.DropGeometry()
@@ -80,6 +88,8 @@ export function dropZones(target: Target, options: DropZoneOptions): DropZones {
       bounds,
       enabled: () => !background,
       cancelDrag: cancelInput,
+      translation: () => input?.position ?? { x: 0, y: 0 },
+      shift: (x, y) => input?.shift(x, y),
       error: (error) =>
         Trace.write(String(error), Trace.categories.Error, Trace.messageType.error),
     },

package/src/engine.ts

@@ -393,13 +393,18 @@ export class ViewAnimation implements PlaybackAnimation {
     for (const { previous } of made) if (previous) release(previous, now, false)
     const tracks = made.map(({ track }) => track)
 
-    for (const { track, layer } of made) {
+    for (const { track, layer, previous } of made) {
       const mix =
         layer !== undefined
           ? mixing(this.view, track.property)
           : mixOf(this.view, track.property)
-      if (!mix) writeValue(this.view, track.property, track.to)
-      else if (track.end === 0) mix.setRest(layer ?? BASE, track.to)
+      if (!mix) {
+        writeValue(this.view, track.property, track.to)
+        // Core skips the native setter when the model already holds the value, which
+        // leaves the cancelled animator's last frame on screen.
+        if (previous && track.end === 0)
+          driver.commit?.(this.view, track.property, track.to)
+      } else if (track.end === 0) mix.setRest(layer ?? BASE, track.to)
     }
     driver.sync?.(this.view)
 

package/src/index.ts

@@ -29,6 +29,9 @@ export type {
   DropZones,
   DropTarget,
   DropEvent,
+  DropMoveEvent,
+  DropPadding,
+  DropRect,
   DropEffect,
 } from './drop-zones.js'
 export type {

package/src/loader.ts

@@ -2,8 +2,9 @@ import { Application, Color, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
 import { reducedMotion } from './config.js'
+import { loaderDefinition, type LoaderStyle } from './core/loading.js'
 
-export type LoaderStyle = 'dots' | 'bars' | 'ring'
+export type { LoaderStyle }
 
 export interface LoaderOptions {
   /** Defaults to 'dots'. */
@@ -26,10 +27,10 @@ const key = 'jolt:loader'
  */
 export function loader(target: Target, options: LoaderOptions = {}): () => void {
   const settings: Required<LoaderOptions> = {
-    style: options.style ?? 'dots',
-    color: options.color ?? '#71717a',
-    size: options.size ?? 48,
-    duration: options.duration ?? 1200,
+    style: options.style ?? loaderDefinition.style,
+    color: options.color ?? loaderDefinition.color,
+    size: options.size ?? loaderDefinition.size,
+    duration: options.duration ?? loaderDefinition.duration,
   }
   if (!['dots', 'bars', 'ring'].includes(settings.style))
     throw new TypeError('Unknown loader style.')
@@ -136,22 +137,28 @@ class Loader {
       const layer = this.layer
       const item = this.item!
       const { style, duration } = this.settings
+      const kind = loaderDefinition.kinds[style]
       layer.bounds = CGRectMake(0, 0, size, size)
       layer.position = CGPointMake(
         bounds.origin.x + bounds.size.width / 2,
         bounds.origin.y + bounds.size.height / 2,
       )
-      layer.instanceCount = style === 'dots' ? 3 : style === 'bars' ? 5 : 12
-      layer.instanceDelay = duration / 1000 / (style === 'ring' ? 12 : 5)
+      layer.instanceCount = kind.count
+      layer.instanceDelay = duration / 1000 / kind.stagger
       if (style === 'ring') {
-        const diameter = size * 0.16
+        const diameter = size * kind.width
         item.bounds = CGRectMake(0, 0, diameter, diameter)
         item.position = CGPointMake(size / 2, diameter / 2)
         item.cornerRadius = diameter / 2
-        layer.instanceTransform = CATransform3DMakeRotation((2 * Math.PI) / 12, 0, 0, 1)
+        layer.instanceTransform = CATransform3DMakeRotation(
+          (2 * Math.PI) / kind.count,
+          0,
+          0,
+          1,
+        )
       } else {
-        const width = size * (style === 'dots' ? 0.2 : 0.12)
-        const height = style === 'dots' ? width : size * 0.75
+        const width = size * kind.width
+        const height = size * kind.height
         item.bounds = CGRectMake(0, 0, width, height)
         item.position = CGPointMake(width / 2, size / 2)
         item.cornerRadius = width / 2
@@ -162,24 +169,20 @@ class Loader {
         )
       }
       const reduced = reducedMotion()
-      item.opacity = style === 'ring' ? 0.35 : 1
+      item.opacity = kind.rest
       if (reduced && this.animating) {
         item.removeAnimationForKey(key)
         this.animating = false
       } else if (!reduced && !this.animating) {
         const animation = CAKeyframeAnimation.animationWithKeyPath(
-          style === 'ring'
+          kind.property === 'opacity'
             ? 'opacity'
-            : style === 'bars'
+            : kind.property === 'scaleY'
               ? 'transform.scale.y'
               : 'transform.scale',
         )
-        animation.values = NSArray.arrayWithArray(
-          style === 'ring' ? [1, 0.2] : [0.35, 1, 0.35, 0.35],
-        )
-        animation.keyTimes = NSArray.arrayWithArray(
-          style === 'ring' ? [0, 1] : [0, 0.3, 0.6, 1],
-        )
+        animation.values = NSArray.arrayWithArray([...kind.values])
+        animation.keyTimes = NSArray.arrayWithArray([...kind.times])
         animation.duration = duration / 1000
         animation.repeatCount = Infinity
         // Start one cycle in so every delayed copy is already participating.

package/src/reveal.ts

@@ -4,6 +4,7 @@ import { resolveEasing } from './easing.js'
 import type { Animation } from './engine.js'
 import type { Target } from './types.js'
 import { reducedMotion } from './config.js'
+import { revealDefinition } from './core/loading.js'
 
 export interface RevealOptions {
   /** Circle origin in DIPs from the target's top-left corner. Defaults to its center. */
@@ -24,18 +25,18 @@ type MaskedView = UIView & { originalMask?: CALayer | null; maskType?: unknown }
 type Snapshot = { circle: Circle; native: UIView; bounds: CGRect }
 const running = new WeakMap<View, CircularAnimation>()
 const callbacks = new WeakMap<NSObject, (finished: boolean) => void>()
-const ease = resolveEasing('easeInOut')
+const ease = resolveEasing(revealDefinition.ease)
 const key = 'jolt:reveal'
 let Delegate: typeof NSObject | undefined
 
 /** Reveals an iOS view through an expanding circle, then removes the temporary mask. */
 export function reveal(target: Target, options: RevealOptions = {}): Animation {
-  return start(target, true, options.from, options.duration ?? 400)
+  return start(target, true, options.from, options.duration ?? revealDefinition.duration)
 }
 
 /** Contracts an iOS view to a point, then sets visibility to 'hidden' without collapsing layout. */
 export function conceal(target: Target, options: ConcealOptions = {}): Animation {
-  return start(target, false, options.to, options.duration ?? 400)
+  return start(target, false, options.to, options.duration ?? revealDefinition.duration)
 }
 
 function start(

package/src/shimmer.ts

@@ -2,6 +2,7 @@ import { Application, isIOS, type View } from '@nativescript/core'
 import { toView } from './animate.js'
 import type { Target } from './types.js'
 import { reducedMotion } from './config.js'
+import { shimmerDefinition } from './core/loading.js'
 
 export interface ShimmerOptions {
   /** Milliseconds per sweep. Defaults to 1500. */
@@ -21,7 +22,7 @@ type MaskedView = UIView & { originalMask?: CALayer | null }
  */
 export function shimmer(target: Target, options: ShimmerOptions = {}): () => void {
   const view = toView(target)
-  const duration = options.duration ?? 1500
+  const duration = options.duration ?? shimmerDefinition.duration
   if (!Number.isFinite(duration) || duration <= 0)
     throw new RangeError('Shimmer duration must be a positive finite number.')
   running.get(view)?.()
@@ -138,15 +139,16 @@ class Shimmer {
 
   private createGradient(): CAGradientLayer {
     const gradient = CAGradientLayer.new()
-    const dim = UIColor.colorWithWhiteAlpha(1, 0.35).CGColor
+    const { mask } = shimmerDefinition
+    const dim = UIColor.colorWithWhiteAlpha(1, mask.opacity).CGColor
     gradient.colors = NSArray.arrayWithArray([dim, UIColor.whiteColor.CGColor, dim])
     gradient.startPoint = CGPointMake(0, 0.5)
     gradient.endPoint = CGPointMake(1, 0.5)
 
     // A three-width mask lets the band enter and leave while every stop stays
     // within the documented 0...1 range for CAGradientLayer.locations.
-    const from = NSArray.arrayWithArray([0, 0.125, 0.25])
-    const to = NSArray.arrayWithArray([0.75, 0.875, 1])
+    const from = NSArray.arrayWithArray([...mask.from])
+    const to = NSArray.arrayWithArray([...mask.to])
     gradient.locations = from
     const animation = CABasicAnimation.animationWithKeyPath('locations')
     animation.fromValue = from