@thinkpixellab-public/px-vue 4.1.26 → 4.1.27

package/composables/loadGsap.js

@@ -0,0 +1,60 @@
+// composables/loadGsap.js
+
+/**
+ * Lazy loading utilities for GSAP and ScrollTrigger
+ * 
+ * These functions provide race-condition-safe loading of GSAP libraries.
+ * They ensure single initialization even with concurrent calls.
+ */
+
+let gsapPromise = null;
+let scrollTriggerPromise = null;
+
+/**
+ * Loads the GSAP library lazily
+ * 
+ * @returns {Promise} Promise that resolves to the GSAP instance
+ * 
+ * @example
+ * // Direct usage (not recommended - use useGsap composable instead)
+ * import { loadGsap } from '@thinkpixellab-public/px-vue/composables/loadGsap';
+ * 
+ * const gsap = await loadGsap();
+ * gsap.to('.element', { x: 100 });
+ */
+export const loadGsap = async () => {
+    if (!gsapPromise) {
+        gsapPromise = import('gsap').then(module => module.gsap);
+    }
+    return gsapPromise;
+};
+
+/**
+ * Loads GSAP with ScrollTrigger plugin registered
+ * 
+ * @returns {Promise} Promise that resolves to { gsap, ScrollTrigger }
+ * 
+ * @example
+ * // Direct usage (not recommended - use useScrollAnimation composable instead)
+ * import { loadScrollTrigger } from '@thinkpixellab-public/px-vue/composables/loadGsap';
+ * 
+ * const { gsap, ScrollTrigger } = await loadScrollTrigger();
+ * 
+ * gsap.to('.element', {
+ *   x: 100,
+ *   scrollTrigger: {
+ *     trigger: '.element',
+ *     start: 'top center'
+ *   }
+ * });
+ */
+export const loadScrollTrigger = async () => {
+    if (!scrollTriggerPromise) {
+        scrollTriggerPromise = (async () => {
+            const [gsap, { ScrollTrigger }] = await Promise.all([loadGsap(), import('gsap/ScrollTrigger')]);
+            gsap.registerPlugin(ScrollTrigger);
+            return { gsap, ScrollTrigger };
+        })();
+    }
+    return scrollTriggerPromise;
+};

package/composables/loadLenis.js

@@ -0,0 +1,82 @@
+// composables/loadLenis.js
+
+/**
+ * Lazy loading utilities for Lenis smooth scrolling
+ * 
+ * These functions provide race-condition-safe loading and initialization of Lenis.
+ * The instance is shared across all components for consistent scroll behavior.
+ */
+
+let lenisPromise = null;
+let lenisInstancePromise = null;
+
+/**
+ * Loads the Lenis class lazily
+ * 
+ * @returns {Promise} Promise that resolves to the Lenis constructor
+ * 
+ * @example
+ * // Direct usage (not recommended - use useLenis composable instead)
+ * import { loadLenis } from '@thinkpixellab-public/px-vue/composables/loadLenis';
+ * 
+ * const Lenis = await loadLenis();
+ * const customLenis = new Lenis({
+ *   duration: 2,
+ *   smoothWheel: true
+ * });
+ */
+export const loadLenis = async () => {
+    if (!lenisPromise) {
+        lenisPromise = import('lenis').then(module => module.default);
+    }
+    return lenisPromise;
+};
+
+/**
+ * Loads a shared Lenis instance with default configuration
+ * 
+ * Returns the same instance across all calls for consistent scroll behavior.
+ * Starts with autoRaf enabled - useScrollAnimation will take over RAF control when needed.
+ * 
+ * @returns {Promise} Promise that resolves to the shared Lenis instance
+ * 
+ * @example
+ * // Direct usage (not recommended - use useLenis composable instead)
+ * import { loadLenisInstance } from '@thinkpixellab-public/px-vue/composables/loadLenis';
+ * 
+ * const lenis = await loadLenisInstance();
+ * 
+ * // smooth scroll to element
+ * lenis.scrollTo('#section-2', { duration: 1.5 });
+ * 
+ * // listen to scroll events
+ * lenis.on('scroll', (e) => {
+ *   console.log('Scroll position:', e.scroll);
+ * });
+ * 
+ * @example
+ * // Configuration details
+ * // The shared instance is created with:
+ * // {
+ * //   smoothWheel: false,     // disabled for better performance
+ * //   smoothTouch: false,     // disabled for mobile compatibility  
+ * //   autoRaf: true          // auto RAF until ScrollTrigger takes over
+ * // }
+ */
+export const loadLenisInstance = async () => {
+    if (!lenisInstancePromise) {
+        lenisInstancePromise = (async () => {
+            const Lenis = await loadLenis();
+
+            const lenisInstance = new Lenis({
+                smoothWheel: false,
+                smoothTouch: false,
+                autoRaf: true,
+            });
+
+            return lenisInstance;
+        })();
+    }
+
+    return lenisInstancePromise;
+};

package/composables/useGsap.js

@@ -0,0 +1,81 @@
+// composables/useGsap.js
+import { loadGsap } from './loadGsap';
+
+/**
+ * Ensures GSAP is loaded and available globally.
+ * After calling this composable, you can use gsap directly as a global.
+ *
+ * @returns {Object} Object with ready promise that resolves when GSAP is loaded
+ *
+ * @example
+ * // Basic usage in a Vue component
+ * import { useGsap } from '@thinkpixellab-public/px-vue/composables/useGsap';
+ *
+ * export default {
+ *   setup() {
+ *     const { ready } = useGsap();
+ *
+ *     onMounted(async () => {
+ *       await ready;
+ *
+ *       // gsap is now available globally
+ *       gsap.to('.my-element', {
+ *         duration: 1,
+ *         x: 100,
+ *         opacity: 0.5
+ *       });
+ *     });
+ *   }
+ * }
+ *
+ * @example
+ * // With refs and cleanup
+ * import { ref, onMounted, onBeforeUnmount } from 'vue';
+ * import { useGsap } from '@thinkpixellab-public/px-vue/composables/useGsap';
+ *
+ * export default {
+ *   setup() {
+ *     useGsap(); // ensures gsap loads
+ *     const myElement = ref(null);
+ *     let animation = null;
+ *
+ *     onMounted(() => {
+ *       // gsap is available globally
+ *       animation = gsap.to(myElement.value, {
+ *         duration: 2,
+ *         rotation: 360,
+ *         repeat: -1
+ *       });
+ *     });
+ *
+ *     onBeforeUnmount(() => {
+ *       if (animation) {
+ *         animation.kill();
+ *       }
+ *     });
+ *
+ *     return { myElement };
+ *   }
+ * }
+ *
+ * @example  
+ * // Immediate usage if you know GSAP is already loaded
+ * import { useGsap } from '@thinkpixellab-public/px-vue/composables/useGsap';
+ *
+ * export default {
+ *   setup() {
+ *     useGsap(); // triggers load if needed
+ *
+ *     // can use gsap immediately in most cases
+ *     const tl = gsap.timeline();
+ *   }
+ * }
+ */
+export const useGsap = () => {
+    if (process.server) {
+        return { ready: Promise.resolve() };
+    }
+
+    const ready = loadGsap();
+    return { ready };
+};

package/composables/useLenis.js

@@ -0,0 +1,86 @@
+// composables/useLenis.js
+import { loadLenisInstance } from './loadLenis';
+
+/**
+ * Vue composable for using Lenis smooth scrolling
+ * 
+ * Provides access to a shared Lenis instance with autoRaf enabled.
+ * Perfect for components that need smooth scrolling without ScrollTrigger integration.
+ * 
+ * @returns {Object} Object with getLenis loader function
+ * 
+ * @example
+ * // Basic usage for smooth scrolling
+ * import { useLenis } from '@thinkpixellab-public/px-vue/composables/useLenis';
+ * 
+ * export default {
+ *   setup() {
+ *     const { getLenis } = useLenis();
+ *     
+ *     onMounted(async () => {
+ *       const lenis = await getLenis();
+ *       
+ *       // scroll to top smoothly
+ *       lenis.scrollTo(0);
+ *       
+ *       // scroll to element
+ *       lenis.scrollTo('#my-section');
+ *       
+ *       // scroll to specific position
+ *       lenis.scrollTo(500, { duration: 2 });
+ *     });
+ *   }
+ * }
+ * 
+ * @example
+ * // Listen to scroll events for parallax
+ * import { ref, onMounted } from 'vue';
+ * import { useLenis } from '@thinkpixellab-public/px-vue/composables/useLenis';
+ * 
+ * export default {
+ *   setup() {
+ *     const { getLenis } = useLenis();
+ *     const parallaxOffset = ref(0);
+ *     
+ *     onMounted(async () => {
+ *       const lenis = await getLenis();
+ *       
+ *       lenis.on('scroll', (e) => {
+ *         parallaxOffset.value = e.scroll * 0.5;
+ *       });
+ *     });
+ *     
+ *     return { parallaxOffset };
+ *   }
+ * }
+ * 
+ * @example
+ * // Custom scroll behavior
+ * import { useLenis } from '@thinkpixellab-public/px-vue/composables/useLenis';
+ * 
+ * export default {
+ *   setup() {
+ *     const { getLenis } = useLenis();
+ *     
+ *     const scrollToSection = async (selector) => {
+ *       const lenis = await getLenis();
+ *       
+ *       lenis.scrollTo(selector, {
+ *         duration: 1.5,
+ *         easing: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t
+ *       });
+ *     };
+ *     
+ *     return { scrollToSection };
+ *   }
+ * }
+ */
+export const useLenis = () => {
+    if (process.server) {
+        return { getLenis: () => null };
+    }
+
+    return { 
+        getLenis: loadLenisInstance
+    };
+};

package/composables/useScrollAnimations.js

@@ -0,0 +1,142 @@
+// composables/useScrollAnimation.js
+import { loadScrollTrigger } from './loadGsap';
+import { loadLenisInstance } from './loadLenis';
+
+let scrollTriggerPromise = null;
+
+/**
+ * Vue composable for scroll-triggered animations with GSAP ScrollTrigger and Lenis
+ * 
+ * Ensures GSAP, ScrollTrigger, and Lenis are loaded and configured for optimal scroll animations.
+ * Automatically manages RAF control transfer from Lenis to GSAP for optimal performance.
+ * After ready resolves, gsap and ScrollTrigger are available globally.
+ * 
+ * @returns {Object} Object with ready promise and getLenis function
+ * 
+ * @example
+ * // Basic scroll-triggered animation
+ * import { useScrollAnimation } from '@thinkpixellab-public/px-vue/composables/useScrollAnimations';
+ * 
+ * export default {
+ *   setup() {
+ *     const { ready } = useScrollAnimation();
+ *     
+ *     onMounted(async () => {
+ *       await ready;
+ *       
+ *       // gsap and ScrollTrigger are now available globally
+ *       gsap.to('.fade-in', {
+ *         opacity: 1,
+ *         y: 0,
+ *         scrollTrigger: {
+ *           trigger: '.fade-in',
+ *           start: 'top 80%',
+ *           end: 'bottom 20%',
+ *           scrub: true
+ *         }
+ *       });
+ *     });
+ *   }
+ * }
+ * 
+ * @example
+ * // Parallax scrolling with Lenis integration
+ * import { useScrollAnimation } from '@thinkpixellab-public/px-vue/composables/useScrollAnimations';
+ * 
+ * export default {
+ *   setup() {
+ *     const { ready, getLenis } = useScrollAnimation();
+ *     
+ *     onMounted(async () => {
+ *       await ready;
+ *       const lenis = await getLenis();
+ *       
+ *       // smooth scroll to section
+ *       lenis.scrollTo('#section-2', { duration: 2 });
+ *       
+ *       // parallax background with global gsap
+ *       gsap.to('.bg-parallax', {
+ *         yPercent: -50,
+ *         ease: 'none',
+ *         scrollTrigger: {
+ *           trigger: '.parallax-section',
+ *           start: 'top bottom',
+ *           end: 'bottom top',
+ *           scrub: true
+ *         }
+ *       });
+ *     });
+ *   }
+ * }
+ * 
+ * @example
+ * // Complex timeline with ScrollTrigger
+ * import { ref, onMounted } from 'vue';
+ * import { useScrollAnimation } from '@thinkpixellab-public/px-vue/composables/useScrollAnimations';
+ * 
+ * export default {
+ *   setup() {
+ *     const { ready } = useScrollAnimation();
+ *     const container = ref(null);
+ *     
+ *     onMounted(async () => {
+ *       await ready;
+ *       
+ *       // gsap is available globally
+ *       const tl = gsap.timeline({
+ *         scrollTrigger: {
+ *           trigger: container.value,
+ *           start: 'top center',
+ *           end: 'bottom center',
+ *           scrub: 1,
+ *           pin: true
+ *         }
+ *       });
+ *       
+ *       tl.from('.item-1', { x: -100, opacity: 0 })
+ *         .from('.item-2', { x: 100, opacity: 0 }, '-=0.5')
+ *         .from('.item-3', { y: 100, opacity: 0 }, '-=0.3');
+ *     });
+ *     
+ *     return { container };
+ *   }
+ * }
+ */
+export const useScrollAnimation = () => {
+    if (process.server) {
+        return {
+            ready: Promise.resolve(),
+            getLenis: () => null,
+        };
+    }
+
+    const init = async () => {
+        if (!scrollTriggerPromise) {
+            scrollTriggerPromise = (async () => {
+                const [{ gsap, ScrollTrigger }, lenis] = await Promise.all([
+                    loadScrollTrigger(),
+                    loadLenisInstance(),
+                ]);
+
+                // Take over RAF control from Lenis
+                lenis.stop();
+
+                lenis.on('scroll', ScrollTrigger.update);
+                gsap.ticker.add(time => {
+                    lenis.raf(time * 1000);
+                });
+                gsap.ticker.lagSmoothing(0);
+
+                // ScrollTrigger is now available globally
+                return { lenis };
+            })();
+        }
+
+        return scrollTriggerPromise;
+    };
+
+    return {
+        ready: init().then(() => {}), // resolves when ScrollTrigger is ready
+        getLenis: async () => (await init()).lenis,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinkpixellab-public/px-vue",
-    "version": "4.1.26",
+    "version": "4.1.27",
     "description": "General purpose Vue components and helpers that can be used across projects.",
     "author": {
         "name": "Pixel Lab"
@@ -29,8 +29,9 @@
         "chrono-node": "^2.7.8",
         "dateformat": "^5.0.3",
         "figma-squircle": "^1.1.0",
-        "gsap": "^3.12.7",
+        "gsap": "^3.13.0",
         "highlight.js": "^11.11.1",
+        "lenis": "^1.1.17",
         "mitt": "^3.0.1",
         "qr-code-styling": "^1.9.2",
         "sortablejs": "^1.15.6",