feat(core): add named export autoAnimate, global defaults setter, fast disable; fix(off-viewport): update once when not intersecting

- Named export  alongside default to avoid ESM named import errors (#194)
- Add  to configure global defaults; re-export in Vue and apply via Nuxt runtime config (#216)
- Improve off-viewport initialization by updating coords once when not intersecting; helps Chrome/Firefox outside viewport cases (#222)
-  now cancels in-flight animations and debounces for immediate effect (#215)

Author: cursoragent

src/index.ts

@@ -80,6 +80,10 @@ const enabled = new WeakSet<Element>()
  */
 let root: HTMLElement
 
+/**
+ * Track elements that have had an off-viewport initialization update.
+ */
+const seen = new WeakSet<Element>()
 /**
  * The root’s XY scroll positions.
  */
@@ -148,7 +152,15 @@ function observePosition(el: Element) {
     .map((px) => `${-1 * Math.floor(px)}px`)
     .join(" ")
   const observer = new IntersectionObserver(
-    () => {
+    (entries) => {
+      const entry = entries[0]
+      // If the element is currently not intersecting, ensure we initialize its
+      // coordinates at least once even when off-viewport.
+      if (entry && entry.target === el && !entry.isIntersecting && !seen.has(el)) {
+        seen.add(el)
+        updatePos(el)
+        return
+      }
       ++invocations > 1 && updatePos(el)
     },
     {
@@ -442,7 +454,7 @@ export function getTransitionSizes(
 function getOptions(el: Element): AutoAnimateOptions | AutoAnimationPlugin {
   return TGT in el && options.has((el as Element & { __aa_tgt: Element })[TGT])
     ? options.get((el as Element & { __aa_tgt: Element })[TGT])!
-    : { duration: 250, easing: "ease-in-out" }
+    : (defaultOptions as AutoAnimateOptions)
 }
 
 /**
@@ -783,6 +795,15 @@ export interface AutoAnimateOptions {
   disrespectUserMotionPreference?: boolean
 }
 
+/**
+ * Allows consumers to configure library-wide default options.
+ */
+export function setAutoAnimateDefaults(
+  opts: Partial<AutoAnimateOptions>
+): void {
+  defaultOptions = { ...defaultOptions, ...opts }
+}
+
 /**
  * A custom plugin config object
  */
@@ -805,14 +826,29 @@ export interface AutoAnimationPlugin {
   ): KeyframeEffect | [KeyframeEffect, AutoAnimationPluginOptions]
 }
 
+// Cancel any in-flight animations and immediately sync coordinates
+function cancelAllAnimations(parent: Element) {
+  forEach(parent, (el) => {
+    const anim = animations.get(el)
+    if (anim) {
+      try {
+        anim.cancel()
+      } catch {}
+    }
+    clearTimeout(debounces.get(el))
+    coords.set(el, getCoords(el))
+    observePosition(el)
+  })
+}
+
 /**
  * A function that automatically adds animation effects to itself and its
  * immediate children. Specifically it adds effects for adding, moving, and
  * removing DOM elements.
  * @param el - A parent element to add animations to.
  * @param options - An optional object of options.
  */
-export default function autoAnimate(
+export function autoAnimate(
   el: HTMLElement,
   config: Partial<AutoAnimateOptions> | AutoAnimationPlugin = {}
 ): AnimationController {
@@ -831,7 +867,7 @@ export default function autoAnimate(
       if (isPlugin(config)) {
         options.set(el, config)
       } else {
-        options.set(el, { duration: 250, easing: "ease-in-out", ...config })
+        options.set(el, { ...defaultOptions, ...config })
       }
       mutations.observe(el, { childList: true })
       parents.add(el)
@@ -844,11 +880,14 @@ export default function autoAnimate(
     },
     disable: () => {
       enabled.delete(el)
+      cancelAllAnimations(el)
     },
     isEnabled: () => enabled.has(el),
   })
 }
 
+export default autoAnimate
+
 /**
  * The vue directive.
  */

src/nuxt/runtime/plugin.ts

@@ -1,7 +1,12 @@
-import { defineNuxtPlugin } from "#imports"
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports"
 import { vAutoAnimate } from "@formkit/auto-animate/vue"
+import { setAutoAnimateDefaults } from "@formkit/auto-animate"
 
 export default defineNuxtPlugin((app) => {
+  const config = useRuntimeConfig().public?.autoAnimate
+  if (config && typeof config === "object") {
+    setAutoAnimateDefaults(config as any)
+  }
   // Register the directive
   app.vueApp.directive("auto-animate", vAutoAnimate)
 })

src/vue/index.ts

@@ -5,8 +5,11 @@ import autoAnimate, {
   AutoAnimateOptions,
   AutoAnimationPlugin,
   AnimationController,
+  setAutoAnimateDefaults,
 } from "../index"
 
+export { setAutoAnimateDefaults }
+
 export const vAutoAnimate: Directive<
   HTMLElement,
   Partial<AutoAnimateOptions>