fancoolo-fx 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# @fancoolo/fx — Fancoolo FX
+
+A class-driven GSAP animation wrapper for WordPress and static sites. Add a CSS class to any element and it animates — no JavaScript needed per page.
+
+## Install
+
+```bash
+npm install
+```
+
+## Usage
+
+Load GSAP + plugins + FX as separate script tags — no build step needed:
+
+```html
+<!-- 1. GSAP core -->
+<script src="node_modules/gsap/dist/gsap.min.js"></script>
+<!-- 2. GSAP plugins -->
+<script src="node_modules/gsap/dist/ScrollTrigger.min.js"></script>
+<script src="node_modules/gsap/dist/SplitText.min.js"></script>
+<!-- 3. Fancoolo FX -->
+<script src="src/fx.js"></script>
+```
+
+Then add classes in your HTML. Done. FX auto-initializes on DOMContentLoaded.
+
+## Quick Start
+
+```html
+<h1 class="fx-text-reveal-pl">Hello World</h1>
+```
+
+The heading animates with a masked line-reveal on page load.
+
+## Available Effects
+
+| Effect | Page Load | Scroll Trigger | Description |
+|--------|-----------|----------------|-------------|
+| Text Reveal | `.fx-text-reveal-pl` | `.fx-text-reveal-st` | Split lines, mask, slide up |
+| Reveal | `.fx-reveal-pl` | `.fx-reveal-st` | Slide up + fade |
+| Spin Reveal | `.fx-spin-reveal-pl` | `.fx-spin-reveal-st` | Rotate + scale in |
+| BG Reveal | `.fx-bg-reveal-pl` | `.fx-bg-reveal-st` | Background slide up |
+| Scale In | `.fx-scale-in-pl` | `.fx-scale-in-st` | Scale up + fade |
+
+**Three trigger modes:**
+- `-pl` — **Page load**: animates when the DOM is ready
+- `-st` — **Scroll trigger**: animates when the element enters the viewport
+- **No suffix** — **Section trigger**: bare `.fx-text-reveal` inside a `<section>` is auto scroll-triggered using the section as the trigger
+
+## How Scroll Triggering Works
+
+When FX sees a scroll-triggered element (`-st` suffix or bare class inside a section), it creates a GSAP ScrollTrigger with these defaults:
+
+- **`start: 'top 85%'`** — the animation fires when the top of the element (or its section) reaches 85% down from the top of the viewport
+- **`once: true`** — plays once, doesn't replay on re-scroll
+
+For grouped siblings (same class, same parent), the parent is used as the shared trigger — so all items animate together with stagger, rather than each triggering independently.
+
+## Section Auto-Trigger
+
+Elements with bare `.fx-*` classes (no `-pl`/`-st` suffix) inside a `<section>` are automatically scroll-triggered using the section as the trigger:
+
+```html
+<section>
+    <h2 class="fx-text-reveal">This auto-triggers on scroll</h2>
+    <p class="fx-text-reveal">No suffix needed inside a section</p>
+    <img src="photo.jpg" class="fx-reveal" />
+</section>
+```
+
+Change the container selector via config:
+
+```js
+FX.config.sectionSelector = '.animate-section';  // only sections with this class
+FX.config.sectionSelector = 'section, .wp-block-group';  // multiple selectors
+```
+
+## Tag-Based Auto-Animation
+
+For zero-class animation, configure `tagMap` to automatically animate elements by their tag name inside sections:
+
+```html
+<!-- Set config BEFORE the FX script loads -->
+<script>
+    window.__FX_CONFIG__ = {
+        tagMap: {
+            'h1,h2,h3,h4,h5,h6': 'textReveal',
+            'p,blockquote':       'textReveal',
+            'img,video':          'reveal',
+        }
+    };
+</script>
+<script src="dist/fx.min.js"></script>
+```
+
+Or configure after load and re-init:
+
+```js
+FX.config.tagMap = { 'h1,h2,h3': 'textReveal', 'img': 'reveal' };
+FX.init();
+```
+
+Elements already animated by explicit `.fx-*` classes are skipped — tagMap only picks up unhandled elements.
+
+## Auto-Stagger
+
+Sibling elements with the same class are automatically staggered (0.15s between each):
+
+```html
+<div>
+    <p class="fx-text-reveal-st">First paragraph</p>
+    <p class="fx-text-reveal-st">Second paragraph</p>
+    <p class="fx-text-reveal-st">Third paragraph</p>
+</div>
+```
+
+## Modifier Classes
+
+Override timing per-element using modifier classes (Gutenberg-friendly — no inline styles needed):
+
+| Class | Default | Description |
+|-------|---------|-------------|
+| `fx-duration-[n]` | `1.2` (text) / `1` (others) | Animation duration in seconds |
+| `fx-delay-[n]` | `0` | Start delay in seconds |
+| `fx-stagger-[n]` | `0.1` | Delay between staggered items |
+| `fx-ease-[name]` | `power3.out` | GSAP easing function |
+
+```html
+<h2 class="fx-text-reveal-st fx-duration-[2] fx-stagger-[0.25]">
+    Slower and wider stagger
+</h2>
+```
+
+Add these in Gutenberg via the "Additional CSS class(es)" field alongside the effect class.
+
+## JavaScript API
+
+For compound sequences or dynamic content, use the `FX` global:
+
+```js
+FX.textReveal(document.querySelector('.hero-title'), {
+    trigger: 'scroll',
+    delay: 0.3,
+    scrollTrigger: { trigger: '.hero-section' }
+});
+```
+
+### API Reference
+
+All functions accept `(element, options)`:
+
+| Function | Options |
+|----------|---------|
+| `textReveal(el, opts)` | `duration`, `ease`, `stagger`, `delay`, `trigger`, `scrollTrigger` |
+| `reveal(el, opts)` | `y` (default 80), `duration`, `ease`, `delay`, `trigger`, `scrollTrigger` |
+| `spinReveal(el, opts)` | `rotation` (default -30), `scale` (default 0.9), `duration`, `ease`, `delay`, `trigger`, `scrollTrigger` |
+| `bgReveal(el, opts)` | `duration`, `ease`, `delay`, `trigger`, `scrollTrigger` |
+| `scaleIn(el, opts)` | `scale` (default 0.92), `duration`, `ease`, `delay`, `trigger`, `scrollTrigger` |
+
+Set `trigger: 'scroll'` to enable ScrollTrigger. Pass `scrollTrigger: { trigger: someEl }` to use a different trigger element.
+
+## 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
+
+For compound sequences, create a project-specific JS file loaded after fx.js:
+
+```js
+// animations.js — loaded after fx.js
+document.addEventListener('DOMContentLoaded', function () {
+    var hero = document.querySelector('.hero');
+    if (hero) {
+        FX.scaleIn(hero.querySelector('.card'), { trigger: 'scroll', scrollTrigger: { trigger: hero } });
+        FX.textReveal(hero.querySelector('h2'), { trigger: 'scroll', delay: 0.2, scrollTrigger: { trigger: hero } });
+    }
+});
+```
+
+## File Structure
+
+```
+├── package.json                ← npm deps (gsap)
+├── node_modules/gsap/dist/     ← GSAP core + plugins (loaded via script tags)
+├── src/fx.js                   ← Fancoolo FX
+├── example/
+│   ├── index.html              ← Demo page
+│   └── src/animations.js       ← Sample project-specific code
+├── CLAUDE.md                   ← Project context for Claude
+└── README.md
+```
+
+## WordPress / Gutenberg
+
+Fancoolo FX uses CSS classes which you can add via the "Additional CSS class(es)" field in the block sidebar. No data attributes or inline styles needed.

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "fancoolo-fx",
+  "version": "1.0.0",
+  "description": "A class-driven GSAP animation wrapper for WordPress and static sites.",
+  "main": "src/fx.js",
+  "keywords": ["gsap", "animation", "scrolltrigger", "splittext", "wordpress", "gutenberg"],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "gsap": "^3.14.2"
+  }
+}

package/src/fx.js

@@ -0,0 +1,386 @@
+/**
+ * Fancoolo FX — A class-driven GSAP animation wrapper
+ *
+ * Load GSAP + plugins BEFORE this file:
+ *   <script src="node_modules/gsap/dist/gsap.min.js"></script>
+ *   <script src="node_modules/gsap/dist/ScrollTrigger.min.js"></script>
+ *   <script src="node_modules/gsap/dist/SplitText.min.js"></script>
+ *   <script src="src/fx.js"></script>
+ *
+ * Three ways to trigger animations:
+ *
+ *   1. Explicit classes with trigger suffix:
+ *      .fx-text-reveal-pl  (page load)
+ *      .fx-text-reveal-st  (scroll trigger)
+ *
+ *   2. Bare classes inside <section> — auto scroll-triggered:
+ *      <section>
+ *        <h2 class="fx-text-reveal">Auto scroll-triggered by section</h2>
+ *      </section>
+ *
+ *   3. Tag-based auto-animation (zero classes):
+ *      FX.config.tagMap = { 'h1,h2,h3': 'textReveal', 'img': 'reveal' }
+ *
+ * Modifier classes (Gutenberg-friendly):
+ *   .fx-duration-[1.5]  .fx-delay-[0.3]  .fx-stagger-[0.2]  .fx-ease-[power2.inOut]
+ *
+ * JS API:
+ *   FX.textReveal(el, { trigger: 'scroll', delay: 0.2 })
+ */
+(function () {
+    'use strict';
+
+    if (typeof gsap === 'undefined' || typeof SplitText === 'undefined' || typeof ScrollTrigger === 'undefined') {
+        console.error('[FX] Missing dependencies. Load gsap, ScrollTrigger, and SplitText before fx.js');
+        return;
+    }
+
+    gsap.registerPlugin(ScrollTrigger, SplitText);
+
+    // ── Config ──────────────────────────────────
+
+    var config = {
+        /**
+         * CSS selector for section containers.
+         * Elements with bare .fx-* classes (no -pl/-st suffix) inside matching
+         * containers are auto scroll-triggered using the container as trigger.
+         */
+        sectionSelector: 'section',
+
+        /**
+         * Default ScrollTrigger start position.
+         * Format: "triggerPosition viewportPosition"
+         * Examples: 'top 85%', 'top center', 'top 90%', 'center center'
+         * See: https://gsap.com/docs/v3/Plugins/ScrollTrigger/
+         */
+        scrollStart: 'top 85%',
+
+        /**
+         * Whether scroll-triggered animations play only once.
+         * Set to false to replay every time the element enters the viewport.
+         */
+        scrollOnce: true,
+
+        /**
+         * Map of CSS selectors → effect names for zero-class auto-animation.
+         * Elements matching these selectors inside sections get animated automatically.
+         * Set to null/false to disable. Override before DOMContentLoaded or call FX.init().
+         *
+         * Example:
+         *   FX.config.tagMap = {
+         *       'h1,h2,h3,h4,h5,h6': 'textReveal',
+         *       'p,blockquote':       'textReveal',
+         *       'img,video':          'reveal',
+         *   }
+         */
+        tagMap: null,
+    };
+
+    // ── Defaults ────────────────────────────────
+
+    var EFFECT_DEFAULTS = {
+        textReveal:  { duration: 1.2, ease: 'power3.out', stagger: 0.1 },
+        reveal:      { duration: 1,   ease: 'power3.out' },
+        spinReveal:  { duration: 1.4, ease: 'power3.out' },
+        bgReveal:    { duration: 1,   ease: 'power3.out' },
+        scaleIn:     { duration: 1,   ease: 'power3.out' },
+    };
+
+    // ── Helpers ──────────────────────────────────
+
+    function getClassModifier(el, name, fallback) {
+        var prefix = 'fx-' + name + '-[';
+        for (var i = 0; i < el.classList.length; i++) {
+            var cls = el.classList[i];
+            if (cls.indexOf(prefix) === 0 && cls.charAt(cls.length - 1) === ']') {
+                var val = cls.slice(prefix.length, -1);
+                var num = parseFloat(val);
+                return isNaN(num) ? val : num;
+            }
+        }
+        return fallback;
+    }
+
+    function resolveOptions(el, effectName, overrides) {
+        var d = EFFECT_DEFAULTS[effectName];
+        return {
+            duration: getClassModifier(el, 'duration', overrides.duration != null ? overrides.duration : d.duration),
+            ease:     getClassModifier(el, 'ease',     overrides.ease     != null ? overrides.ease     : d.ease),
+            stagger:  getClassModifier(el, 'stagger',  overrides.stagger  != null ? overrides.stagger  : (d.stagger || 0)),
+            delay:    getClassModifier(el, 'delay',     overrides.delay    != null ? overrides.delay    : 0),
+        };
+    }
+
+    function buildScrollTrigger(el, scrollTriggerOpts) {
+        var defaults = {
+            start: config.scrollStart,
+            once: config.scrollOnce,
+        };
+        var st = { trigger: scrollTriggerOpts.trigger || el };
+        for (var key in defaults) st[key] = defaults[key];
+        for (var key2 in scrollTriggerOpts) st[key2] = scrollTriggerOpts[key2];
+
+        // Per-element override: fx-start-[top center] or fx-start-[top 70%]
+        var startOverride = getClassModifier(el, 'start', null);
+        if (startOverride !== null) st.start = startOverride;
+
+        return st;
+    }
+
+    // ── Effects ──────────────────────────────────
+
+    function textReveal(el, opts) {
+        opts = opts || {};
+        var o = resolveOptions(el, 'textReveal', opts);
+
+        var split = new SplitText(el, { type: 'lines', linesClass: 'line-wrapper' });
+
+        split.lines.forEach(function (line) {
+            var wrapper = document.createElement('div');
+            wrapper.style.overflow = 'hidden';
+            line.parentNode.insertBefore(wrapper, line);
+            wrapper.appendChild(line);
+        });
+
+        var tweenVars = {
+            y: '100%',
+            opacity: 0,
+            duration: o.duration,
+            ease: o.ease,
+            stagger: o.stagger,
+            delay: o.delay,
+            onComplete: function () {
+                split.lines.forEach(function (line) {
+                    line.style.transform = '';
+                    line.style.opacity = '';
+                });
+            },
+        };
+
+        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
+            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+        }
+
+        gsap.from(split.lines, tweenVars);
+    }
+
+    function reveal(el, opts) {
+        opts = opts || {};
+        var o = resolveOptions(el, 'reveal', opts);
+
+        var tweenVars = {
+            y: opts.y != null ? opts.y : 80,
+            opacity: 0,
+            duration: o.duration,
+            ease: o.ease,
+            delay: o.delay,
+        };
+
+        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
+            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+        }
+
+        gsap.from(el, tweenVars);
+    }
+
+    function spinReveal(el, opts) {
+        opts = opts || {};
+        var o = resolveOptions(el, 'spinReveal', opts);
+
+        var tweenVars = {
+            rotation: opts.rotation != null ? opts.rotation : -30,
+            scale: opts.scale != null ? opts.scale : 0.9,
+            opacity: 0,
+            duration: o.duration,
+            ease: o.ease,
+            delay: o.delay,
+        };
+
+        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
+            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+        }
+
+        gsap.from(el, tweenVars);
+    }
+
+    function bgReveal(el, opts) {
+        opts = opts || {};
+        var o = resolveOptions(el, 'bgReveal', opts);
+
+        var tweenVars = {
+            y: '100%',
+            opacity: 0,
+            duration: o.duration,
+            ease: o.ease,
+            delay: o.delay,
+        };
+
+        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
+            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+        }
+
+        gsap.from(el, tweenVars);
+    }
+
+    function scaleIn(el, opts) {
+        opts = opts || {};
+        var o = resolveOptions(el, 'scaleIn', opts);
+
+        var tweenVars = {
+            scale: opts.scale != null ? opts.scale : 0.92,
+            opacity: 0,
+            duration: o.duration,
+            ease: o.ease,
+            delay: o.delay,
+        };
+
+        if (opts.trigger === 'scroll' || opts.scrollTrigger) {
+            tweenVars.scrollTrigger = buildScrollTrigger(el, opts.scrollTrigger || {});
+        }
+
+        gsap.from(el, tweenVars);
+    }
+
+    // ── Class-to-effect mapping ─────────────────
+
+    var effects = {
+        'fx-text-reveal': textReveal,
+        'fx-reveal':      reveal,
+        'fx-spin-reveal': spinReveal,
+        'fx-bg-reveal':   bgReveal,
+        'fx-scale-in':    scaleIn,
+    };
+
+    var effectsByName = {
+        textReveal: textReveal,
+        reveal: reveal,
+        spinReveal: spinReveal,
+        bgReveal: bgReveal,
+        scaleIn: scaleIn,
+    };
+
+    // ── Helpers ──────────────────────────────────
+
+    function groupByParent(nodeList) {
+        var map = new Map();
+        nodeList.forEach(function (el) {
+            var parent = el.parentElement;
+            if (!map.has(parent)) map.set(parent, []);
+            map.get(parent).push(el);
+        });
+        var groups = [];
+        map.forEach(function (arr) { groups.push(arr); });
+        return groups;
+    }
+
+    function applyScrollGroup(fn, group, triggerEl) {
+        group.forEach(function (el, i) {
+            fn(el, {
+                trigger: 'scroll',
+                delay: i * 0.15,
+                scrollTrigger: { trigger: triggerEl },
+            });
+        });
+    }
+
+    function camelToKebab(str) {
+        return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+    }
+
+    // ── Init ────────────────────────────────────
+
+    function init() {
+        var processed = new Set();
+
+        Object.keys(effects).forEach(function (name) {
+            var fn = effects[name];
+
+            // 1. Page-load variant: .fx-<name>-pl
+            var plGroups = groupByParent(document.querySelectorAll('.' + name + '-pl'));
+            plGroups.forEach(function (group) {
+                group.forEach(function (el, i) {
+                    fn(el, { delay: i * 0.15 });
+                    processed.add(el);
+                });
+            });
+
+            // 2. Explicit scroll-trigger variant: .fx-<name>-st
+            var stGroups = groupByParent(document.querySelectorAll('.' + name + '-st'));
+            stGroups.forEach(function (group) {
+                var triggerEl = group[0].parentElement || group[0];
+                applyScrollGroup(fn, group, triggerEl);
+                group.forEach(function (el) { processed.add(el); });
+            });
+
+            // 3. Bare class inside a section: .fx-<name> (no suffix)
+            if (config.sectionSelector) {
+                document.querySelectorAll(config.sectionSelector).forEach(function (section) {
+                    var bareEls = Array.from(section.querySelectorAll('.' + name))
+                        .filter(function (el) { return !processed.has(el); });
+                    if (bareEls.length === 0) return;
+
+                    var groups = groupByParent(bareEls);
+                    groups.forEach(function (group) {
+                        applyScrollGroup(fn, group, section);
+                        group.forEach(function (el) { processed.add(el); });
+                    });
+                });
+            }
+        });
+
+        // 4. Tag-based auto-animation inside sections
+        if (config.tagMap && config.sectionSelector) {
+            document.querySelectorAll(config.sectionSelector).forEach(function (section) {
+                Object.keys(config.tagMap).forEach(function (selector) {
+                    var effectName = config.tagMap[selector];
+                    var fn = effects['fx-' + camelToKebab(effectName)] || effectsByName[effectName];
+                    if (!fn) return;
+
+                    var els = Array.from(section.querySelectorAll(selector))
+                        .filter(function (el) { return !processed.has(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); });
+                    });
+                });
+            });
+        }
+    }
+
+    // ── Boot ────────────────────────────────────
+
+    function applyPreConfig() {
+        var pre = window.__FX_CONFIG__;
+        if (!pre) return;
+        if (pre.sectionSelector !== undefined) config.sectionSelector = pre.sectionSelector;
+        if (pre.scrollStart !== undefined) config.scrollStart = pre.scrollStart;
+        if (pre.scrollOnce !== undefined) config.scrollOnce = pre.scrollOnce;
+        if (pre.tagMap !== undefined) config.tagMap = pre.tagMap;
+    }
+
+    function boot() {
+        applyPreConfig();
+        init();
+    }
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', boot);
+    } else {
+        boot();
+    }
+
+    // ── Public API ──────────────────────────────
+
+    window.FX = {
+        config: config,
+        textReveal: textReveal,
+        reveal: reveal,
+        spinReveal: spinReveal,
+        bgReveal: bgReveal,
+        scaleIn: scaleIn,
+        init: init,
+    };
+})();