@rafaelaugusto/jolt 0.1.0-beta.1 → 0.1.0-beta.2

package/dist/symbol-effect.js

@@ -0,0 +1,186 @@
+import { Image, ImageSource, isIOS } from '@nativescript/core';
+import { toView } from './animate.js';
+const running = new WeakMap();
+const names = ['bounce', 'pulse', 'scale', 'variableColor'];
+/**
+ * Plays an iOS 17+ SF Symbol effect on a NativeScript Image.
+ * Scale holds until stopped; replacements also update the Image's src.
+ *
+ * ```ts
+ * symbolEffect(icon, 'bounce')
+ * symbolEffect(icon, { replace: 'sys://heart.fill' })
+ * ```
+ */
+export function symbolEffect(target, effect, options = {}) {
+    const view = toView(target);
+    if (!(view instanceof Image))
+        throw new TypeError('symbolEffect expects an Image.');
+    if (typeof effect === 'string'
+        ? !names.includes(effect)
+        : !effect ||
+            typeof effect.replace !== 'string' ||
+            !/^sys:\/\/[^\s/]+$/.test(effect.replace)) {
+        throw new TypeError('Expected a symbol effect name or { replace: "sys://name" }.');
+    }
+    const speed = options.speed ?? 1;
+    if (!Number.isFinite(speed) || speed <= 0)
+        throw new RangeError('Symbol effect speed must be a positive finite number.');
+    if (options.repeat !== undefined && typeof options.repeat !== 'boolean')
+        throw new TypeError('Symbol effect repeat must be a boolean.');
+    if (options.repeat && (typeof effect !== 'string' || effect === 'scale'))
+        throw new TypeError('Only bounce, pulse and variableColor can repeat.');
+    return new SymbolAnimation(view, effect, speed, options.repeat ?? false);
+}
+class SymbolAnimation {
+    view;
+    effect;
+    speed;
+    repeat;
+    finished;
+    resolve;
+    settled = false;
+    started = false;
+    changingSource = false;
+    waitingForLoad;
+    native;
+    nativeEffect;
+    replacement;
+    constructor(view, effect, speed, repeat) {
+        this.view = view;
+        this.effect = effect;
+        this.speed = speed;
+        this.repeat = repeat;
+        this.finished = new Promise((resolve) => (this.resolve = resolve));
+        this.waitingForLoad = !view.isLoaded;
+        running.get(view)?.stop();
+        running.set(view, this);
+        view.on('unloaded', this.stop);
+        view.on('srcChange', this.sourceChanged);
+        view.on('imageSourceChange', this.imageChanged);
+        view.on('loaded', this.loaded);
+        view.on('isLoadingChange', this.start);
+        this.start();
+    }
+    then(onfulfilled, onrejected) {
+        return this.finished.then(onfulfilled, onrejected);
+    }
+    stop = () => this.end(false, true);
+    sourceChanged = () => {
+        if (!this.changingSource)
+            this.stop();
+    };
+    imageChanged = () => {
+        if (this.changingSource)
+            return;
+        if (this.started)
+            this.stop();
+        else
+            this.start();
+    };
+    loaded = () => {
+        this.waitingForLoad = false;
+        this.start();
+    };
+    start = () => {
+        if (this.settled || this.started)
+            return;
+        if (!isIOS)
+            return this.end(false);
+        const { view, effect } = this;
+        // isLoaded becomes true before NativeScript resumes native property updates.
+        // Wait for the loaded event so intermediate image resets don't start playback.
+        if (this.waitingForLoad ||
+            !view.isLoaded ||
+            !view.nativeViewProtected ||
+            view.isLoading)
+            return;
+        this.started = true;
+        const native = (this.native = view.nativeViewProtected);
+        const reducedMotion = UIAccessibilityIsReduceMotionEnabled();
+        if (typeof effect !== 'string') {
+            // Resolve first so a symbol absent on this OS doesn't clear the current image.
+            if (!ImageSource.fromSystemImageSync(effect.replace.slice(6))?.ios)
+                return this.end(false);
+            const previous = native.image;
+            const loadMode = view.loadMode;
+            this.changingSource = true;
+            try {
+                // Let NativeScript update its source, tint, configuration and pending loads.
+                // Both assignments happen in this turn, before UIKit draws the next frame.
+                view.loadMode = 'sync';
+                view.src = effect.replace;
+            }
+            finally {
+                view.loadMode = loadMode;
+                this.changingSource = false;
+            }
+            // A source-change listener may have started another effect or changed the src.
+            if (this.settled)
+                return;
+            if (view.src !== effect.replace)
+                return this.end(false);
+            const image = native.image;
+            if (!image)
+                return this.end(false);
+            if (reducedMotion ||
+                !previous?.symbolImage ||
+                !native.respondsToSelector('setSymbolImage:withContentTransition:options:completion:'))
+                return this.end(true);
+            this.replacement = image;
+            native.image = previous;
+            native.setSymbolImageWithContentTransitionOptionsCompletion(image, NSSymbolReplaceContentTransition.transition(), this.options(), this.completed);
+            return;
+        }
+        if (reducedMotion ||
+            !native.image?.symbolImage ||
+            !native.respondsToSelector('addSymbolEffect:options:animated:completion:'))
+            return this.end(false);
+        const factories = {
+            bounce: NSSymbolBounceEffect,
+            pulse: NSSymbolPulseEffect,
+            scale: NSSymbolScaleEffect,
+            variableColor: NSSymbolVariableColorEffect,
+        };
+        this.nativeEffect = factories[effect].effect();
+        native.addSymbolEffectOptionsAnimatedCompletion(this.nativeEffect, this.options(), true, this.completed);
+    };
+    options() {
+        const options = this.repeat
+            ? NSSymbolEffectOptions.optionsWithRepeating()
+            : NSSymbolEffectOptions.optionsWithNonRepeating();
+        return options.optionsWithSpeed(this.speed);
+    }
+    completed = (context) => {
+        // Scale's entrance can complete while the effect is still holding its state.
+        if (context.finished && (this.effect === 'scale' || this.repeat))
+            return;
+        this.end(context.finished);
+    };
+    end(finished, remove = false) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        const { view, native, nativeEffect, replacement } = this;
+        view.off('loaded', this.loaded);
+        view.off('isLoadingChange', this.start);
+        view.off('unloaded', this.stop);
+        view.off('srcChange', this.sourceChanged);
+        view.off('imageSourceChange', this.imageChanged);
+        if (running.get(view) === this)
+            running.delete(view);
+        if (remove && native) {
+            if (nativeEffect)
+                native.removeSymbolEffectOfType(nativeEffect);
+            // Content transitions have no removal API. Keep the destination icon.
+            if (replacement && native.image === replacement) {
+                native.image = null;
+                native.image = replacement;
+            }
+        }
+        this.native = undefined;
+        this.nativeEffect = undefined;
+        this.replacement = undefined;
+        this.resolve(finished);
+    }
+}
+//# sourceMappingURL=symbol-effect.js.map

package/dist/symbol-effect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-effect.js","sourceRoot":"","sources":["../src/symbol-effect.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { View } from '@nativescript/core';
+import type { Haptic } from './haptics.js';
 import type { SpringName, Transition } from './transition.js';
 /** A value to animate to, or keyframes. `null` stands for the value the view has when the animation starts. */
 export type KeyframeValue = number | readonly (number | null)[];
@@ -36,5 +37,7 @@ export type AnimateOptions = Transition & {
     relative?: boolean;
     /** With several targets, delays each one by this much more than the previous. */
     stagger?: number | Stagger;
+    /** iOS impact feedback at arrival, or at explicit points in a finite animation. */
+    haptic?: Haptic;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE7D,+GAA+G;AAC/G,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;AAE/D,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,eAAe;IACf,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAED,+FAA+F;AAC/F,MAAM,MAAM,MAAM,GAChB,IAAI,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAEzE,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;KACvC,CAAC,IAAI,MAAM,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU;CACjD,GAAG;IACF,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE7D,+GAA+G;AAC/G,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;AAE/D,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,qCAAqC;IACrC,CAAC,CAAC,EAAE,aAAa,CAAA;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,eAAe;IACf,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB;AAED,+FAA+F;AAC/F,MAAM,MAAM,MAAM,GAChB,IAAI,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAEzE,MAAM,WAAW,OAAO;IACtB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;KACvC,CAAC,IAAI,MAAM,SAAS,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU;CACjD,GAAG;IACF,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1B,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafaelaugusto/jolt",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Native animations for NativeScript: presets, springs, keyframes and stagger in one call.",
   "keywords": [
     "nativescript",
@@ -39,6 +39,7 @@
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
+    "benchmark:typecheck": "tsc -p benchmarks/tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "format": "prettier --write .",

package/src/animate.ts

@@ -8,6 +8,7 @@ import {
   type Plan,
 } from './engine.js'
 import { getPreset, type PresetName } from './presets.js'
+import { resolveHaptic, type Haptic } from './haptics.js'
 import { isProperty, type Property } from './properties.js'
 import {
   hasCurve,
@@ -30,6 +31,7 @@ interface Options {
   overrides: Partial<Record<keyof Keyframes, Transition>>
   stagger: number | Stagger | undefined
   relative: boolean | undefined
+  haptic: Haptic | undefined
 }
 
 /**
@@ -47,12 +49,17 @@ export function animate(
   animation: Keyframes | PresetName,
   options?: AnimateOptions | SpringName,
 ): Animation {
-  const { keyframes, base, overrides, stagger, relative } = prepare(animation, options)
+  const { keyframes, base, overrides, stagger, relative, haptic } = prepare(
+    animation,
+    options,
+  )
+  const feedback = resolveHaptic(haptic)
 
   if (!isList(target)) {
     return new ViewAnimation(
       toView(target),
       plan(keyframes, base, overrides, 0, relative),
+      feedback,
     )
   }
 
@@ -69,6 +76,7 @@ export function animate(
             staggerDelay(stagger, index, views.length),
             relative,
           ),
+          feedback,
         ),
     ),
   )
@@ -133,33 +141,43 @@ function prepare(
       : { ...own.overrides, ...user.overrides },
     stagger: user.stagger ?? own.stagger,
     relative: user.relative ?? own.relative,
+    haptic: user.haptic ?? own.haptic,
   }
 }
 
 function normalize(options: AnimateOptions | SpringName | undefined): Options {
   if (options === undefined)
-    return { base: {}, overrides: {}, stagger: undefined, relative: undefined }
+    return {
+      base: {},
+      overrides: {},
+      stagger: undefined,
+      relative: undefined,
+      haptic: undefined,
+    }
   if (typeof options === 'string')
     return {
       base: spring(options),
       overrides: {},
       stagger: undefined,
       relative: undefined,
+      haptic: undefined,
     }
 
   const base: Record<string, unknown> = {}
   const overrides: Options['overrides'] = {}
   let stagger: Options['stagger']
   let relative: Options['relative']
+  let haptic: Options['haptic']
   for (const [key, value] of Object.entries(options)) {
     if (value === undefined) continue
     if (key === 'stagger') stagger = value as Options['stagger']
     else if (key === 'relative') relative = value as Options['relative']
+    else if (key === 'haptic') haptic = value as Options['haptic']
     else if (key === 'scale' || isProperty(key)) {
       overrides[key] = typeof value === 'string' ? spring(value as SpringName) : value
     } else base[key] = value
   }
-  return { base, overrides, stagger, relative }
+  return { base, overrides, stagger, relative, haptic }
 }
 
 function plan(

package/src/driver/ios.ts

@@ -58,6 +58,17 @@ export function createIOSDriver(): Driver {
       }
 
       const animation = CAKeyframeAnimation.animationWithKeyPath(keyPaths[track.property])
+      // iOS 15+. The app must opt in through CADisableMinimumFrameDurationOnPhone.
+      if (animation.respondsToSelector('setPreferredFrameRateRange:')) {
+        const nativeView = view.nativeViewProtected as UIView
+        const screen = nativeView.window?.screen ?? UIScreen.mainScreen
+        const maximum = Math.min(120, screen.maximumFramesPerSecond)
+        animation.preferredFrameRateRange = CAFrameRateRangeMake(
+          Math.min(80, maximum),
+          maximum,
+          maximum,
+        )
+      }
       animation.values = NSArray.arrayWithArray(
         track.values.map((value) => (rotation ? radians(value) : value)),
       )

package/src/engine.ts

@@ -1,5 +1,6 @@
 import type { View } from '@nativescript/core'
 import { getDriver } from './driver/index.js'
+import { playHaptics, type HapticOptions } from './haptics.js'
 import { readValue, writeValue, type Property } from './properties.js'
 import { createTrack, type Track } from './track.js'
 import type { ResolvedTransition } from './transition.js'
@@ -7,11 +8,11 @@ import type { ResolvedTransition } from './transition.js'
 export interface Animation extends PromiseLike<boolean> {
   /**
    * Resolves with `true` once the animation played to the end, or with `false`
-   * if it was stopped or another animation took over one of its properties.
+   * if it was stopped, superseded or skipped.
    * Never rejects.
    */
   readonly finished: Promise<boolean>
-  /** Stops where it is. The view keeps the values it had at that moment. */
+  /** Stops playback. Property animations keep their current values; symbol effects are removed. */
   stop(): void
 }
 
@@ -56,10 +57,12 @@ export class ViewAnimation implements Animation {
   private cancelWait: (() => void) | undefined
   private arrive!: () => void
   private cancelArrival: (() => void) | undefined
+  private haptics: ReturnType<typeof playHaptics>
 
   constructor(
     readonly view: View,
     plans: readonly Plan[],
+    private readonly haptic?: HapticOptions,
   ) {
     this.finished = new Promise((resolve) => (this.resolve = resolve))
     setArrival(this, new Promise<void>((resolve) => (this.arrive = resolve)))
@@ -77,6 +80,7 @@ export class ViewAnimation implements Animation {
   stop() {
     if (this.settled) return
     this.cancelWait?.()
+    this.haptics?.cancel()
     const now = getDriver().now()
     for (const entry of this.entries) {
       if (!entry.done) release(entry, now, true)
@@ -86,7 +90,10 @@ export class ViewAnimation implements Animation {
   }
 
   ended(finished: boolean) {
-    if (!finished) this.complete = false
+    if (!finished) {
+      this.complete = false
+      this.haptics?.cancel()
+    }
     if (--this.pending === 0) this.settle()
   }
 
@@ -137,6 +144,8 @@ export class ViewAnimation implements Animation {
       this.pending++
     }
 
+    this.haptics = playHaptics(this.view, tracks, this.haptic, driver, now)
+
     for (const entry of this.entries) {
       entry.handle = driver.play(this.view, entry.track, now, () => {
         if (entry.done) return
@@ -174,6 +183,9 @@ export class ViewAnimation implements Animation {
     if (this.settled) return
     this.settled = true
     this.cancelArrival?.()
+    if (this.complete) this.haptics?.finish()
+    else this.haptics?.cancel()
+    this.haptics = undefined
     this.arrive()
     this.resolve(this.complete)
   }

package/src/haptics.ts

@@ -0,0 +1,125 @@
+import { isIOS, type View } from '@nativescript/core'
+import type { Driver } from './driver/index.js'
+import type { Track } from './track.js'
+
+export type HapticStyle = 'light' | 'medium' | 'heavy'
+
+export interface HapticOptions {
+  style: HapticStyle
+  /** Points from 0 to 1 over the finite animation, excluding its initial delay. Defaults to arrival. */
+  times?: readonly number[]
+}
+
+export type Haptic = HapticStyle | HapticOptions | false
+
+/** Validate before any running animation is interrupted. */
+export function resolveHaptic(haptic: Haptic | undefined): HapticOptions | undefined {
+  if (haptic === undefined || haptic === false) return undefined
+  const options = typeof haptic === 'string' ? { style: haptic } : haptic
+  if (!options || !['light', 'medium', 'heavy'].includes(options.style))
+    throw new TypeError('Haptic style must be light, medium or heavy.')
+  const times = options.times
+  if (
+    times !== undefined &&
+    (!Array.isArray(times) ||
+      times.length === 0 ||
+      Array.from(times).some(
+        (time, i) =>
+          !Number.isFinite(time) ||
+          time <= 0 ||
+          time > 1 ||
+          (i > 0 && time <= times[i - 1]!),
+      ))
+  )
+    throw new RangeError(
+      'Haptic times must be increasing points greater than 0 and at most 1.',
+    )
+  return { style: options.style, times: times && [...times] }
+}
+
+const PREPARE_AHEAD = 100
+const MAX_LATENESS = 100
+const COMPLETION_TOLERANCE = 20
+
+/** Discrete feedback only: animation playback remains entirely native. */
+export function playHaptics(
+  view: View,
+  tracks: readonly Track[],
+  options: HapticOptions | undefined,
+  driver: Driver,
+  startedAt: number,
+) {
+  if (!isIOS || !options || typeof UIImpactFeedbackGenerator === 'undefined') return
+  const moving = tracks.filter(
+    (track) =>
+      track.duration > 0 && track.values.some((value) => value !== track.values[0]),
+  )
+  if (!moving.length) return
+  const end = Math.max(...tracks.map((track) => track.end))
+  if (!Number.isFinite(end)) return
+  const delay = Math.min(...moving.map((track) => track.delay))
+  const offsets = options.times
+    ? options.times.map((time) => delay + (end - delay) * time)
+    : [Math.max(...tracks.map((track) => track.arrival))]
+  const styles = {
+    light: 0,
+    medium: 1,
+    heavy: 2,
+  } satisfies Record<HapticStyle, UIImpactFeedbackStyle>
+  let generator: UIImpactFeedbackGenerator | undefined =
+    UIImpactFeedbackGenerator.alloc().initWithStyle(styles[options.style])
+  const native = view.nativeViewProtected as UIView
+  let next = 0
+  let cancelPrepare: (() => void) | undefined
+  let cancelImpact: (() => void) | undefined
+
+  const active = () =>
+    view.isLoaded &&
+    view.nativeViewProtected === native &&
+    !!native.window &&
+    UIApplication.sharedApplication.applicationState === 0 // UIApplicationState.Active
+
+  const cancel = () => {
+    cancelPrepare?.()
+    cancelImpact?.()
+    cancelPrepare = cancelImpact = undefined
+    generator = undefined
+    view.off('unloaded', cancel)
+  }
+
+  const fire = (tolerance = 0) => {
+    const elapsed = driver.now() - startedAt
+    // A busy UI thread can delay timers. Drop stale impacts instead of replaying
+    // several old taps at once when it becomes responsive again.
+    while (next < offsets.length && offsets[next]! <= elapsed + tolerance) {
+      const offset = offsets[next++]!
+      if (active() && elapsed - offset <= MAX_LATENESS) generator?.impactOccurred()
+    }
+  }
+
+  const schedule = () => {
+    if (!generator || next === offsets.length) return cancel()
+    const remaining = startedAt + offsets[next]! - driver.now()
+    if (active()) generator.prepare()
+    if (remaining > PREPARE_AHEAD) {
+      cancelPrepare = driver.after(remaining - PREPARE_AHEAD, () => {
+        if (active()) generator?.prepare()
+      })
+    }
+    cancelImpact = driver.after(Math.max(0, remaining), () => {
+      fire()
+      schedule()
+    })
+  }
+
+  view.on('unloaded', cancel)
+  schedule()
+  return {
+    cancel,
+    finish() {
+      // Native completion may beat the timer at the final keyframe by a frame.
+      fire(COMPLETION_TOLERANCE)
+      cancel()
+    },
+  }
+}

package/src/index.ts

@@ -2,6 +2,17 @@ export { animate, stop } from './animate.js'
 export { sequence } from './sequence.js'
 export type { Step } from './sequence.js'
 export { press } from './press.js'
+export type { Haptic, HapticOptions, HapticStyle } from './haptics.js'
+export { confetti, particles } from './particles.js'
+export type { ConfettiOptions, ParticleOptions } from './particles.js'
+export { shimmer } from './shimmer.js'
+export type { ShimmerOptions } from './shimmer.js'
+export { symbolEffect } from './symbol-effect.js'
+export type {
+  SymbolEffect,
+  SymbolEffectName,
+  SymbolEffectOptions,
+} from './symbol-effect.js'
 export { definePreset, presets } from './presets.js'
 export type { Preset, PresetName, Presets } from './presets.js'
 export { springs } from './transition.js'