npm - fancoolo-fx - Versions diffs - 1.7.0 → 1.8.1 - Mend

fancoolo-fx 1.7.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -169,11 +169,36 @@ Set `trigger: 'scroll'` to enable ScrollTrigger. Pass `scrollTrigger: { trigger:
 **Resize handling:** Text-based effects (`textReveal`, `typeWriter`, `splitWords`) automatically re-split when the browser width changes. After one-shot animations complete, the SplitText DOM is reverted so text reflows naturally.
+## Preventing Flash of Unstyled Content (FOUC)
+FX uses GSAP's `autoAlpha` internally, so elements with `visibility: hidden` are revealed automatically when their animation starts. Add this CSS **before** any content renders to prevent the flash where elements appear briefly before JS loads:
+```css
+.fx-text-reveal-pl,.fx-text-reveal-st,.fx-text-reveal,
+.fx-reveal-pl,.fx-reveal-st,.fx-reveal,
+.fx-spin-reveal-pl,.fx-spin-reveal-st,.fx-spin-reveal,
+.fx-bg-reveal-pl,.fx-bg-reveal-st,.fx-bg-reveal,
+.fx-scale-in-pl,.fx-scale-in-st,.fx-scale-in,
+.fx-fade-in-pl,.fx-fade-in-st,.fx-fade-in,
+.fx-blur-in-pl,.fx-blur-in-st,.fx-blur-in,
+.fx-clip-up-pl,.fx-clip-up-st,.fx-clip-up,
+.fx-clip-down-pl,.fx-clip-down-st,.fx-clip-down,
+.fx-tilt-in-st,.fx-tilt-in,
+.fx-type-writer-pl,.fx-type-writer-st,.fx-type-writer,
+.fx-draw-svg-pl,.fx-draw-svg-st,.fx-draw-svg,.fx-draw-svg-scrub,
+.fx-split-words-pl,.fx-split-words-st,.fx-split-words,
+.fx-slide-left-pl,.fx-slide-left-st,.fx-slide-left,
+.fx-slide-right-pl,.fx-slide-right-st,.fx-slide-right{visibility:hidden}
+```
+**WordPress:** The plugin injects this CSS automatically in the `<head>` — no action needed.
 ## Using in a New Project
 1. Copy this repo (or `npm install`)
 2. Add the 4 script tags (gsap, ScrollTrigger, SplitText, fx.js)
-3. Add `.fx-*` classes in your HTML
+3. Add the FOUC prevention CSS in your `<head>` (see above)
+4. Add `.fx-*` classes in your HTML
 For compound sequences, create a project-specific JS file loaded after fx.js:

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "fancoolo-fx",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "A class-driven GSAP animation wrapper for WordPress and static sites.",
   "main": "src/fx.js",
   "homepage": "https://krstivoja.github.io/fancoolo-fx/",

package/readme.txt CHANGED Viewed

@@ -68,6 +68,24 @@ Yes. Use the `fx-start-[top center]` modifier class, or set `scrollStart` in the
 == Changelog ==
+= 1.8.1 =
+* Fix: Removed split.revert() calls from textReveal, typeWriter, and splitWords — revert destroys JS state (event listeners, injected DOM) added after SplitText ran
+* Fix: textReveal resize re-splitting fully handled by autoSplit, no manual revert needed
+= 1.8.0 =
+* Refactor: textReveal uses native SplitText `autoSplit`, `mask: "lines"`, and `onSplit` — removes manual overflow wrappers and resize handler
+* Refactor: Responsive and reduced-motion handling via `gsap.matchMedia()` — animations auto-revert when conditions change
+* Refactor: Idempotent `init()` using persistent WeakSet — safe to call multiple times without double-animating
+* Refactor: Scrub effects (tiltIn, parallax, drawSVG scrub) routed through `buildScrollTrigger()` — now support debug markers and `fx-start-[...]` overrides
+* Removed: Manual resize listener, `_splitRegistry`, `document.fonts.ready` blocking — all handled natively by GSAP
+* Enhancement: `FX.refresh()` simplified to `ScrollTrigger.refresh()`
+= 1.7.1 =
+* Fix: FOUC prevention — all effects now use autoAlpha instead of opacity, elements start with visibility:hidden and are revealed by GSAP
+* New: WordPress plugin injects visibility:hidden CSS automatically in the head
+* New: Text-based effects set parent visibility before animating children to prevent flash
+* Enhancement: clipUp/clipDown now include autoAlpha for consistent FOUC handling
 = 1.7.0 =
 * Fix: Text-based effects (textReveal, typeWriter, splitWords) now re-split on browser resize — line breaks stay correct at every viewport width
 * New: SplitText is reverted after one-shot animations complete — text reflows naturally without extra DOM wrappers

package/src/fx.js CHANGED Viewed

@@ -109,6 +109,11 @@
         slideIn:     { duration: 1,   ease: 'power3.out' },
     };
+    // ── State ───────────────────────────────────
+    var _animated = new WeakSet();
+    var _mm = gsap.matchMedia();
     // ── Helpers ──────────────────────────────────
     function getClassModifier(el, name, fallback) {
@@ -157,89 +162,36 @@
         return st;
     }
-    // ── SplitText resize handling ───────────────
-    var _splitRegistry = [];
-    var _lastWidth = window.innerWidth;
-    var _resizeTimer;
-    function registerSplit(entry) {
-        _splitRegistry.push(entry);
-    }
-    function unregisterSplit(entry) {
-        var idx = _splitRegistry.indexOf(entry);
-        if (idx > -1) _splitRegistry.splice(idx, 1);
-    }
-    function refreshSplits() {
-        if (_splitRegistry.length === 0) return;
-        var pending = [];
-        for (var i = _splitRegistry.length - 1; i >= 0; i--) {
-            var entry = _splitRegistry[i];
-            if (entry.tween) entry.tween.kill();
-            if (entry.split) entry.split.revert();
-            pending.push(entry);
-        }
-        _splitRegistry.length = 0;
-        pending.forEach(function (entry) {
-            entry.effectFn(entry.el, entry.opts);
-        });
-        ScrollTrigger.refresh();
-    }
-    window.addEventListener('resize', function () {
-        if (window.innerWidth === _lastWidth) return;
-        _lastWidth = window.innerWidth;
-        clearTimeout(_resizeTimer);
-        _resizeTimer = setTimeout(refreshSplits, 200);
-    });
     // ── Effects ──────────────────────────────────
     function textReveal(el, opts) {
         opts = opts || {};
         var o = resolveOptions(el, 'textReveal', opts);
+        var isScroll = opts.trigger === 'scroll' || opts.scrollTrigger;
+        gsap.set(el, { visibility: 'inherit' });
+        SplitText.create(el, {
+            type: 'lines',
+            mask: 'lines',
+            autoSplit: true,
+            onSplit: function (self) {
+                var tweenVars = {
+                    y: '100%',
+                    autoAlpha: 0,
+                    duration: o.duration,
+                    ease: o.ease,
+                    stagger: o.stagger,
+                    delay: o.delay,
+                };
-        var split = new SplitText(el, { type: 'lines', linesClass: 'line-wrapper' });
+                if (isScroll) {
+                    tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+                }
-        split.lines.forEach(function (line) {
-            var wrapper = document.createElement('div');
-            wrapper.style.overflow = 'hidden';
-            line.parentNode.insertBefore(wrapper, line);
-            wrapper.appendChild(line);
+                return gsap.from(self.lines, tweenVars);
+            },
         });
-        var isOneShot = !(opts.trigger === 'scroll' || opts.scrollTrigger) || config.scrollOnce;
-        var entry = { el: el, split: split, tween: null, effectFn: textReveal, opts: opts };
-        var tweenVars = {
-            y: '100%',
-            opacity: 0,
-            duration: o.duration,
-            ease: o.ease,
-            stagger: o.stagger,
-            delay: o.delay,
-        };
-        if (isOneShot) {
-            tweenVars.onComplete = function () {
-                split.revert();
-                unregisterSplit(entry);
-            };
-        }
-        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
-            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
-        }
-        entry.tween = gsap.from(split.lines, tweenVars);
-        registerSplit(entry);
     }
     function reveal(el, opts) {
@@ -248,7 +200,7 @@
         var tweenVars = {
             y: opts.y != null ? opts.y : 80,
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -268,7 +220,7 @@
         var tweenVars = {
             rotation: opts.rotation != null ? opts.rotation : -30,
             scale: opts.scale != null ? opts.scale : 0.9,
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -287,7 +239,7 @@
         var tweenVars = {
             y: '100%',
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -306,7 +258,7 @@
         var tweenVars = {
             scale: opts.scale != null ? opts.scale : 0.92,
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -324,7 +276,7 @@
         var o = resolveOptions(el, 'fadeIn', opts);
         var tweenVars = {
-            opacity: 0,
+            autoAlpha: 0,
             scale: opts.scale != null ? opts.scale : 0.95,
             duration: o.duration,
             ease: o.ease,
@@ -344,7 +296,7 @@
         var tweenVars = {
             filter: 'blur(' + (opts.blur != null ? opts.blur : 12) + 'px)',
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -363,6 +315,7 @@
         var tweenVars = {
             clipPath: 'inset(100% 0 0 0)',
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -381,6 +334,7 @@
         var tweenVars = {
             clipPath: 'inset(0 0 100% 0)',
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -397,24 +351,24 @@
         opts = opts || {};
         var o = resolveOptions(el, 'tiltIn', opts);
+        var st = buildScrollTrigger(el, opts.scrollTrigger || {});
+        st.end = opts.end || 'top 20%';
+        st.scrub = opts.scrub != null ? opts.scrub : 0.6;
+        delete st.once;
         gsap.fromTo(el, {
             rotationX: opts.rotationX != null ? opts.rotationX : 45,
             scale: opts.scale != null ? opts.scale : 0.8,
-            opacity: opts.opacity != null ? opts.opacity : 0,
+            autoAlpha: opts.opacity != null ? opts.opacity : 0,
             transformPerspective: opts.perspective != null ? opts.perspective : 1000,
             transformOrigin: opts.transformOrigin || 'center bottom',
         }, {
             rotationX: 0,
             scale: 1,
-            opacity: 1,
+            autoAlpha: 1,
             transformPerspective: 1000,
             ease: o.ease,
-            scrollTrigger: {
-                trigger: (opts.scrollTrigger && opts.scrollTrigger.trigger) || el,
-                start: config.scrollStart || 'top 85%',
-                end: opts.end || 'top 20%',
-                scrub: opts.scrub != null ? opts.scrub : 0.6,
-            },
+            scrollTrigger: st,
         });
     }
@@ -422,38 +376,29 @@
         opts = opts || {};
         var o = resolveOptions(el, 'typeWriter', opts);
+        gsap.set(el, { visibility: 'inherit' });
         var split = new SplitText(el, { type: 'chars' });
-        gsap.set(split.chars, { opacity: 0 });
-        var isOneShot = !(opts.trigger === 'scroll' || opts.scrollTrigger) || config.scrollOnce;
-        var entry = { el: el, split: split, tween: null, effectFn: typeWriter, opts: opts };
+        gsap.set(split.chars, { autoAlpha: 0 });
         var tweenVars = {
-            opacity: 1,
+            autoAlpha: 1,
             duration: o.duration,
             ease: o.ease,
             stagger: o.stagger,
             delay: o.delay,
         };
-        if (isOneShot) {
-            tweenVars.onComplete = function () {
-                split.revert();
-                unregisterSplit(entry);
-            };
-        }
         if (opts.trigger === 'scroll' || opts.scrollTrigger) {
             tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
         }
-        entry.tween = gsap.to(split.chars, tweenVars);
-        registerSplit(entry);
+        gsap.to(split.chars, tweenVars);
     }
     function drawSVG(el, opts) {
         opts = opts || {};
         var o = resolveOptions(el, 'drawSVG', opts);
+        gsap.set(el, { visibility: 'inherit' });
         var paths = el.tagName === 'path' || el.tagName === 'line' || el.tagName === 'circle' || el.tagName === 'polyline'
             ? [el]
@@ -471,15 +416,15 @@
         // Scrub mode: SVG draws as user scrolls (class fx-scrub-[0.6] or opts.scrub)
         var scrubVal = getClassModifier(el, 'scrub', opts.scrub != null ? opts.scrub : null);
         if (scrubVal !== null) {
+            var st = buildScrollTrigger(el, opts.scrollTrigger || {});
+            st.end = opts.end || 'top 20%';
+            st.scrub = scrubVal === true || scrubVal === 'true' ? true : scrubVal;
+            delete st.once;
             gsap.to(paths, {
                 strokeDashoffset: 0,
                 ease: o.ease,
-                scrollTrigger: {
-                    trigger: (opts.scrollTrigger && opts.scrollTrigger.trigger) || el,
-                    start: config.scrollStart || 'top 85%',
-                    end: opts.end || 'top 20%',
-                    scrub: scrubVal === true || scrubVal === 'true' ? true : scrubVal,
-                },
+                scrollTrigger: st,
             });
             return;
         }
@@ -503,17 +448,17 @@
         // Read y from modifier class fx-y-[80] or opts or default 50
         var yShift = getClassModifier(el, 'y', opts.y != null ? opts.y : 50);
+        var st = buildScrollTrigger(el, opts.scrollTrigger || {});
+        st.end = opts.end || 'bottom top';
+        st.scrub = opts.scrub != null ? opts.scrub : true;
+        delete st.once;
         gsap.fromTo(el, {
             y: -yShift,
         }, {
             y: yShift,
             ease: 'none',
-            scrollTrigger: {
-                trigger: (opts.scrollTrigger && opts.scrollTrigger.trigger) || el,
-                start: config.scrollStart || 'top 85%',
-                end: opts.end || 'bottom top',
-                scrub: opts.scrub != null ? opts.scrub : true,
-            },
+            scrollTrigger: st,
         });
     }
@@ -521,33 +466,23 @@
         opts = opts || {};
         var o = resolveOptions(el, 'splitWords', opts);
+        gsap.set(el, { visibility: 'inherit' });
         var split = new SplitText(el, { type: 'words' });
-        var isOneShot = !(opts.trigger === 'scroll' || opts.scrollTrigger) || config.scrollOnce;
-        var entry = { el: el, split: split, tween: null, effectFn: splitWords, opts: opts };
         var tweenVars = {
             y: opts.y != null ? opts.y : 30,
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             stagger: o.stagger,
             delay: o.delay,
         };
-        if (isOneShot) {
-            tweenVars.onComplete = function () {
-                split.revert();
-                unregisterSplit(entry);
-            };
-        }
         if (opts.trigger === 'scroll' || opts.scrollTrigger) {
             tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
         }
-        entry.tween = gsap.from(split.words, tweenVars);
-        registerSplit(entry);
+        gsap.from(split.words, tweenVars);
     }
     function slideIn(el, opts) {
@@ -558,7 +493,7 @@
         var tweenVars = {
             x: direction === 'left' ? -xVal : xVal,
-            opacity: 0,
+            autoAlpha: 0,
             duration: o.duration,
             ease: o.ease,
             delay: o.delay,
@@ -644,7 +579,6 @@
     // ── Init ────────────────────────────────────
     function init() {
-        var processed = new Set();
         Object.keys(effects).forEach(function (name) {
             var fn = effects[name];
@@ -654,8 +588,9 @@
             plGroups.forEach(function (group) {
                 group = group.filter(function (el) { return !isExcluded(el); });
                 group.forEach(function (el, i) {
+                    if (_animated.has(el)) return;
                     fn(el, { delay: i * 0.15 });
-                    processed.add(el);
+                    _animated.add(el);
                 });
             });
@@ -667,12 +602,13 @@
             stGroups.forEach(function (group) {
                 group = group.filter(function (el) { return !isExcluded(el); });
                 group.forEach(function (el, i) {
+                    if (_animated.has(el)) return;
                     fn(el, {
                         trigger: 'scroll',
                         delay: i * 0.15,
                         scrollTrigger: { trigger: el },
                     });
-                    processed.add(el);
+                    _animated.add(el);
                 });
             });
@@ -682,18 +618,19 @@
             if (config.sectionSelector) {
                 document.querySelectorAll(config.sectionSelector).forEach(function (section) {
                     var bareEls = Array.from(section.querySelectorAll('.' + name))
-                        .filter(function (el) { return !processed.has(el) && !isExcluded(el); });
+                        .filter(function (el) { return !_animated.has(el) && !isExcluded(el); });
                     if (bareEls.length === 0) return;
                     var groups = groupByParent(bareEls);
                     groups.forEach(function (group) {
                         group.forEach(function (el, i) {
+                            if (_animated.has(el)) return;
                             fn(el, {
                                 trigger: 'scroll',
                                 delay: i * 0.15,
                                 scrollTrigger: { trigger: el },
                             });
-                            processed.add(el);
+                            _animated.add(el);
                         });
                     });
                 });
@@ -702,21 +639,21 @@
         // 4. Scrub-based effects — always scroll-linked, processed before tagMap.
         document.querySelectorAll('.fx-tilt-in-st, .fx-tilt-in-pl, .fx-tilt-in').forEach(function (el) {
-            if (!processed.has(el) && !isExcluded(el)) {
+            if (!_animated.has(el) && !isExcluded(el)) {
                 tiltIn(el);
-                processed.add(el);
+                _animated.add(el);
             }
         });
         document.querySelectorAll('.fx-parallax-st, .fx-parallax-pl, .fx-parallax').forEach(function (el) {
-            if (!processed.has(el) && !isExcluded(el)) {
+            if (!_animated.has(el) && !isExcluded(el)) {
                 parallax(el);
-                processed.add(el);
+                _animated.add(el);
             }
         });
         document.querySelectorAll('.fx-draw-svg-scrub').forEach(function (el) {
-            if (!processed.has(el) && !isExcluded(el)) {
+            if (!_animated.has(el) && !isExcluded(el)) {
                 drawSVG(el, { scrub: getClassModifier(el, 'scrub', 0.6) });
-                processed.add(el);
+                _animated.add(el);
             }
         });
@@ -729,18 +666,19 @@
                     if (!fn) return;
                     var els = Array.from(section.querySelectorAll(selector))
-                        .filter(function (el) { return !processed.has(el) && !isExcluded(el); });
+                        .filter(function (el) { return !_animated.has(el) && !isExcluded(el); });
                     if (els.length === 0) return;
                     var groups = groupByParent(els);
                     groups.forEach(function (group) {
                         applyScrollGroup(fn, group, section);
-                        group.forEach(function (el) { processed.add(el); });
+                        group.forEach(function (el) { _animated.add(el); });
                     });
                 });
             });
         }
-        // 5. fx-stagger-all-[selector] — target children, effect from sibling class
+        // 6. fx-stagger-all-[selector] — target children, effect from sibling class
         //    Requires an effect class on the same element (e.g. fx-reveal-st).
         document.querySelectorAll('[class*="fx-stagger-all-"]').forEach(function (container) {
             // Parse selector from fx-stagger-all-[img,p]
@@ -770,7 +708,7 @@
             var isScroll = container.classList.contains(effectName + '-st') ||
                            container.classList.contains(effectName);
             var children = Array.from(container.querySelectorAll(childSelector))
-                .filter(function (el) { return !processed.has(el); });
+                .filter(function (el) { return !_animated.has(el); });
             if (children.length === 0) return;
             children.forEach(function (child, i) {
@@ -780,7 +718,7 @@
                     opts.scrollTrigger = { trigger: child };
                 }
                 effectFn(child, opts);
-                processed.add(child);
+                _animated.add(child);
             });
         });
@@ -805,17 +743,20 @@
     function boot() {
         applyPreConfig();
-        // Skip animations if OS reduced motion is enabled
-        if (config.respectReducedMotion && window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-            return;
+        // Build media query from config — animations auto-revert when conditions stop matching
+        var parts = [];
+        if (config.disableMobile) {
+            parts.push('(min-width: ' + (config.mobileBreakpoint + 1) + 'px)');
         }
-        // Skip animations on mobile
-        if (config.disableMobile && window.innerWidth <= config.mobileBreakpoint) {
-            return;
+        if (config.respectReducedMotion) {
+            parts.push('(prefers-reduced-motion: no-preference)');
         }
+        var conditions = parts.length > 0 ? parts.join(' and ') : 'all';
-        init();
+        _mm.add(conditions, function () {
+            _animated = new WeakSet();
+            init();
+        });
     }
     if (document.readyState === 'loading') {
@@ -844,6 +785,6 @@
         splitWords: splitWords,
         slideIn: slideIn,
         init: init,
-        refresh: refreshSplits,
+        refresh: function () { ScrollTrigger.refresh(); },
     };
 })();