gsap-nuxt-module 1.1.8 → 1.1.9

package/README.md

@@ -120,6 +120,31 @@ onMounted(() => {
 </script>
 ```
 
+### Context form (recommended)
+
+Pass a `setup` function to wrap animations in a [`gsap.context()`](https://gsap.com/docs/v3/GSAP/gsap.context/).
+The context reverts automatically when the component unmounts — no `onUnmounted` boilerplate needed.
+During page navigation, cleanup is deferred until after the leave transition finishes.
+
+```ts
+<script setup lang="ts">
+const containerRef = ref<HTMLElement | null>(null)
+
+useGsap(() => {
+  gsap.from('.box', { opacity: 0, y: 30, duration: 0.6 })
+}, { scope: containerRef })
+</script>
+
+<template>
+  <div ref="containerRef">
+    <div class="box">I animate in safely</div>
+  </div>
+</template>
+```
+
+Returns `{ contextSafe }` for wrapping event handlers that add animations after mount.
+See the [full docs](https://lucaargentieri.github.io/gsap-nuxt-module/composables/use-gsap) for all options.
+
 ## Available composables
 
 | Composable | Plugin | `nuxt.config.ts` key |
@@ -154,8 +179,7 @@ export default defineNuxtConfig({
 
 ## Cleanup
 
-GSAP animations are not automatically cleaned up when a component unmounts.
-Use `onUnmounted` to prevent memory leaks.
+When using `useGsap()` with a setup function, cleanup is automatic. When using the zero-arg form, use `onUnmounted` to prevent memory leaks.
 
 Plugin registration is handled once by the module at app startup — never call `gsap.registerPlugin()` manually.
 In components, clean up only the instances your component created (tweens, timelines, ScrollTrigger instances, Draggable instances, etc.).

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=3.0.0"
   },
-  "version": "1.1.8",
+  "version": "1.1.9",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/composables/createGsapComposable.d.ts

@@ -1,10 +1,43 @@
 import { gsap } from 'gsap';
 import type { ComputedRef, Ref, WatchSource } from 'vue';
-type ContextSafeFn = <F extends (...args: unknown[]) => unknown>(fn: F) => F;
+/**
+ * Wraps an event handler so it runs inside the active GSAP context.
+ *
+ * **Note:** return values are discarded when a context exists — `ctx.add()`
+ * returns `void`. Use `contextSafe` only for void side-effect handlers
+ * (DOM events, pointer callbacks, etc.).
+ */
+type ContextSafeFn = <F extends (...args: unknown[]) => void>(fn: F) => F;
 export interface UseGsapOptions {
     scope?: Ref<HTMLElement | null> | ComputedRef<HTMLElement | null>;
     dependencies?: WatchSource | WatchSource[];
     revertOnUpdate?: boolean;
+    /**
+     * When to revert the GSAP context during page navigation.
+     *
+     * @deprecated This option has no behavioral effect. Both `'unmount'` and
+     * `'route-leave'` produce identical behavior: the GSAP context is reverted
+     * after the leave transition finishes, when the component unmounts via
+     * `onScopeDispose`. Kept for backward compatibility only.
+     *
+     * - `'unmount'` (default) — reverts after the leave transition finishes,
+     *   when the component is unmounted via `onScopeDispose`.
+     * - `'route-leave'` — semantically identical to `'unmount'`.
+     *
+     * In both cases, animations continue to play during the leave transition,
+     * then are reverted once the component unmounts.
+     *
+     * **Note:** if a `router.beforeEach` guard rejects navigation *after*
+     * `onBeforeRouteLeave` is registered, the `onBeforeRouteLeave` hook will still
+     * have fired and set `isLeavingViaRoute` to `true`, but the component will not unmount.
+     * The context remains active and animations continue until the next successful
+     * navigation.
+     *
+     * @example
+     * // Continuous animation that should play through the page-leave transition
+     * useGsap(() => { ... }, { cleanupOn: 'route-leave' })
+     */
+    cleanupOn?: 'unmount' | 'route-leave';
 }
 /**
  * Zero-argument overload — returns the raw GSAP instance.
@@ -92,7 +125,7 @@ export declare const useScrollTrigger: () => {
     snapDirectional(incrementOrArray: number | number[]): ScrollTrigger.SnapDirectionalFunc;
     sort(func?: Function): ScrollTrigger[];
     update(): void;
-} | null;
+};
 export declare const useScrollSmoother: () => {
     new (vars: ScrollSmoother.Vars): {
         readonly scrollTrigger: ScrollTrigger;
@@ -120,7 +153,7 @@ export declare const useScrollSmoother: () => {
     create(vars: ScrollSmoother.Vars): ScrollSmoother;
     get(): ScrollSmoother | undefined;
     refresh(safe?: boolean): void;
-} | null;
+};
 export declare const useSplitText: () => {
     new (target: gsap.DOMTarget, vars?: SplitText.Vars): {
         readonly chars: Element[];
@@ -134,14 +167,14 @@ export declare const useSplitText: () => {
         split(vars: SplitText.Vars): SplitText;
     };
     create(target: gsap.DOMTarget, vars?: SplitText.Vars): SplitText;
-} | null;
+};
 export declare const useMotionPathHelper: () => {
     new (target: gsap.DOMTarget, vars?: MotionPathHelper.Vars): {
         kill(): void;
     };
     create(target: gsap.DOMTarget, vars?: MotionPathHelper.Vars): MotionPathHelper;
     editPath(target: gsap.DOMTarget, vars?: MotionPathHelper.EditPathVars): MotionPathHelper;
-} | null;
+};
 export declare const useDraggable: () => {
     new (target: gsap.DOMTarget, vars?: Draggable.Vars): {
         readonly autoScroll: number;
@@ -194,7 +227,7 @@ export declare const useDraggable: () => {
     get(target: gsap.DOMTarget): Draggable;
     hitTest(testObject1: Draggable.TestObject, testObject2: Draggable.TestObject, threshold?: number | string): boolean;
     timeSinceDrag(): number;
-} | null;
+};
 export declare const useFlip: () => {
     new (): {};
     readonly version: string;
@@ -212,7 +245,7 @@ export declare const useFlip: () => {
     register(core: typeof globalThis.gsap): void;
     ElementState: typeof Flip.ElementState;
     FlipState: typeof Flip.FlipState;
-} | null;
+};
 export declare const useObserver: () => {
     new (): {
         readonly deltaX: number;
@@ -244,14 +277,14 @@ export declare const useObserver: () => {
     create(vars: Observer.ObserverVars): Observer;
     getAll(): Observer[];
     getById(id: string): Observer | undefined;
-} | null;
+};
 export declare const useGSDevTools: () => {
     new (target: gsap.DOMTarget, vars?: GSDevTools.Vars): {
         kill(): void;
     };
     create(vars?: GSDevTools.Vars): GSDevTools;
     getById(id: string): GSDevTools | null;
-} | null;
+};
 export declare const useCustomEase: () => {
     new (id: string, data?: string | number[], config?: CustomEaseConfig): {
         id: string;
@@ -265,19 +298,19 @@ export declare const useCustomEase: () => {
     register(core: object): void;
     get(id: string): EaseFunction;
     getSVGData(ease: CustomEase | EaseFunction | string, config?: CustomEaseConfig): string;
-} | null;
+};
 export declare const useCustomWiggle: () => {
     new (id: string, vars?: CustomWiggleVars): {
         ease: EaseFunction;
     };
     create(id: string, vars?: CustomWiggleVars): EaseFunction;
     register(core: object): void;
-} | null;
+};
 export declare const useCustomBounce: () => {
     new (id: string, vars?: CustomBounceVars): {
         ease: EaseFunction;
     };
     create(id: string, vars?: CustomBounceVars): EaseFunction;
     register(core: object): void;
-} | null;
+};
 export {};

package/dist/runtime/composables/createGsapComposable.js

@@ -1,5 +1,7 @@
+import { useNuxtApp } from "#app";
 import { gsap } from "gsap";
 import { onMounted, onScopeDispose, watch } from "vue";
+import { onBeforeRouteLeave } from "vue-router";
 import { createGsapComposable } from "../create-gsap-composable.js";
 export function useGsap(setup, options) {
   if (!setup) return gsap;
@@ -7,31 +9,47 @@ export function useGsap(setup, options) {
     return { contextSafe: (fn) => fn };
   }
   let ctx = null;
+  let isLeavingViaRoute = false;
   const runSetup = () => {
     const scope = options?.scope?.value ?? void 0;
     ctx = gsap.context(setup, scope);
   };
+  onBeforeRouteLeave(() => {
+    isLeavingViaRoute = true;
+    const nuxtApp = useNuxtApp();
+    nuxtApp.hooks.hookOnce("page:transition:finish", () => {
+      ctx?.revert();
+      ctx = null;
+    });
+  });
   onMounted(() => {
     runSetup();
   });
   if (options?.dependencies !== void 0) {
     const deps = Array.isArray(options.dependencies) ? options.dependencies : [options.dependencies];
-    watch(deps, () => {
-      if (options.revertOnUpdate === false) return;
-      ctx?.revert();
-      runSetup();
-    }, { flush: "post" });
+    watch(
+      deps,
+      () => {
+        if (options.revertOnUpdate === false) return;
+        ctx?.revert();
+        runSetup();
+      },
+      { flush: "post" }
+    );
   }
   onScopeDispose(() => {
-    ctx?.revert();
-    ctx = null;
+    if (!isLeavingViaRoute) {
+      ctx?.revert();
+      ctx = null;
+    }
   });
   const contextSafe = (fn) => {
     return ((...args) => {
       if (ctx) {
-        return ctx.add(() => fn(...args));
+        ctx.add(() => fn(...args));
+      } else {
+        fn(...args);
       }
-      return fn(...args);
     });
   };
   return { contextSafe };

package/dist/runtime/create-gsap-composable.d.ts

@@ -2,7 +2,8 @@
  * Factory that creates a composable returning a registered GSAP plugin.
  *
  * The returned composable reads the plugin from `nuxtApp` at call time.
- * Returns `null` during SSR (plugin is client-only).
+ * This is a client-only composable — it is safe to call on the server but
+ * will return an inert value (the plugin is never registered server-side).
  * Throws on the client if the plugin was not enabled in `nuxt.config.ts`.
  *
  * **Cleanup is the caller's responsibility.**
@@ -12,4 +13,4 @@
  * @param pluginName - Name of the GSAP plugin as registered in nuxtApp.
  * @param fallbackMessage - Optional custom error message for missing plugin.
  */
-export declare function createGsapComposable<T>(pluginName: string, fallbackMessage?: string): () => T | null;
+export declare function createGsapComposable<T>(pluginName: string, fallbackMessage?: string): () => NonNullable<T>;

package/dist/runtime/gsap-plugins.d.ts

@@ -1,3 +1,7 @@
+/**
+ * This object contains lazy-loaded GSAP plugins for use in the application.
+ *
+ */
 export declare const gsapPlugins: {
     ScrollTrigger: () => Promise<{
         new (vars: ScrollTrigger.StaticVars, animation?: gsap.core.Animation): {

package/dist/runtime/gsap-plugins.js

@@ -1,4 +1,3 @@
-import { loadDraggable, loadFlip, loadObserver } from "./gsap-loaders.js";
 export const gsapPlugins = {
   // Scroll Plugins
   ScrollTrigger: () => import("gsap/ScrollTrigger").then((mod) => mod.ScrollTrigger),
@@ -14,10 +13,10 @@ export const gsapPlugins = {
   MotionPathPlugin: () => import("gsap/MotionPathPlugin").then((mod) => mod.MotionPathPlugin),
   MotionPathHelper: () => import("gsap/MotionPathHelper").then((mod) => mod.MotionPathHelper),
   // UI Plugins
-  Flip: () => loadFlip().then((mod) => mod.Flip),
-  Draggable: () => loadDraggable().then((mod) => mod.Draggable),
+  Flip: () => import("gsap/Flip").then((mod) => mod.Flip),
+  Draggable: () => import("gsap/Draggable").then((mod) => mod.Draggable),
   InertiaPlugin: () => import("gsap/InertiaPlugin").then((mod) => mod.InertiaPlugin),
-  Observer: () => loadObserver().then((mod) => mod.Observer),
+  Observer: () => import("gsap/Observer").then((mod) => mod.Observer),
   // Other Plugins
   PixiPlugin: () => import("gsap/PixiPlugin").then((mod) => mod.PixiPlugin),
   EaselPlugin: () => import("gsap/EaselPlugin").then((mod) => mod.EaselPlugin),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsap-nuxt-module",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "GSAP integration for Nuxt.",
   "repository": "LucaArgentieri/gsap-nuxt-module",
   "author": "Luca Argentieri",

package/dist/runtime/gsap-loaders.d.ts

@@ -1,3 +0,0 @@
-export function loadFlip(): Promise<typeof import("gsap/Flip")>;
-export function loadDraggable(): Promise<typeof import("gsap/Draggable")>;
-export function loadObserver(): Promise<typeof import("gsap/Observer")>;

package/dist/runtime/gsap-loaders.js

@@ -1,7 +0,0 @@
-// @ts-nocheck
-
-export const loadFlip = () => import('gsap/Flip')
-
-export const loadDraggable = () => import('gsap/Draggable')
-
-export const loadObserver = () => import('gsap/Observer')