@squeditor/squeditor-framework 1.0.1 → 1.0.3

package/README.md

@@ -1,9 +1,6 @@
-# ⚡️ Squeditor Framework
-
 **Squeditor Framework** is a high-performance, developer-first framework for building lightning-fast, static websites. It combines the power of **PHP-style templating** with the modern performance of **Tailwind CSS**, the interactivity of **UIKit 3**, and the speed of **Vite**.
 
-> [!IMPORTANT]
-> Squeditor Framework is NOT a WordPress theme framework or a CMS. It is a build-time framework that uses PHP for development and outputs 100% flat, portable HTML/CSS/JS for production and compatible with Squeditor, Elementor, Gutenberg, and other page builders.
+[Full Documentation](https://docs.squeditor.com)
 
 ## 🚀 Key Features
 
@@ -45,21 +42,16 @@ Every project includes an automatically generated `style-guide.php` page that re
 
 ## 🏁 Getting Started
 
-### 1. Installation
-Clone the repository into your desired workspace folder. This folder will house both the framework and your generated projects:
-```bash
-git clone https://github.com/unistudioco/squeditor-framework.git
-```
-
-### 2. Scaffold a New Project
-Squeditor includes a robust CLI scaffolding tool. It generates a completely clean, minimalist `project-template/` instance next to the core framework, fully pre-configured to utilize the advanced GSAP and UIKit engines without demo bloat.
+### 1. Scaffold a New Project
+Squeditor includes a robust CLI scaffolding tool. It generates a completely clean, minimalist project instance fully pre-configured to utilize the advanced GSAP and UIKit engines without demo bloat.
 
-To scaffold your new project, run the following command from your workspace root (outside `squeditor-framework`):
+To scaffold your new project, simply run the following command in your terminal:
 ```bash
 npx @squeditor/squeditor-framework your-project-name
 ```
+*(Replace `your-project-name` with your desired folder name).*
 
-### 3. Development
+### 2. Development
 Navigate into your newly generated project folder, install its dependencies, and start the development server:
 ```bash
 cd your-project-name
@@ -72,7 +64,7 @@ npm run dev
 > Vite will show a link to `http://127.0.0.1:5173/` in your terminal. **Do not use that link.**
 > Instead, always visit the PHP Server address: **`http://127.0.0.1:3001`**. This is because Squeditor Framework uses PHP for template rendering, and Vite only serves the static assets.
 
-### 4. Build for Production
+### 3. Build for Production
 Generate the static `dist/` folder and a distributable ZIP archive:
 ```bash
 npm run build

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squeditor/squeditor-framework",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Squeditor Framework is a high-performance, developer-first framework for building lightning-fast, static websites. It combines the power of PHP-style templating with the modern performance of Tailwind CSS, the interactivity of UIKit 3, and the speed of Vite.",
   "main": "index.js",
   "publishConfig": {

package/project-template/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "my-project-name",
+  "name": "new-project-name",
   "private": true,
   "scripts": {
     "dev": "node ../squeditor-framework/scripts/dev.js",
@@ -11,7 +11,9 @@
     "preview:vercel": "vercel dist --yes"
   },
   "dependencies": {
+    "@splidejs/splide": "^4.1.4",
     "gsap": "^3.13.0",
+    "swiper": "^12.1.2",
     "uikit": "^3.21.0"
   },
   "devDependencies": {

package/project-template/squeditor.config.js

@@ -1,8 +1,25 @@
-// showcase/squeditor.config.js
+// squeditor.config.js
 module.exports = {
     framework: '../squeditor-framework',
-    name: 'my-project-name',
+    name: 'customer-bundle',
     version: '1.0.0',
+    themes: {
+        'two': {
+            label: 'Two Theme',
+            bodyClass: 'theme-two',
+            scss: 'src/assets/scss/themes/_two.scss',
+            pages: ['404.php', 'slider-test.php'],
+            distSubfolder: '',
+        }
+    },
+    gsap: {
+        plugins: ['ScrollTrigger', 'SplitText', 'Flip', 'Observer'],
+        initScript: 'src/assets/js/gsap-init.js',
+        advancedScript: 'src/assets/js/gsap-advanced.js',
+    },
+    slider: {
+        library: 'splide', // 'swiper', 'splide', or false
+    },
     components: [
         'sticky',
         'utility',
@@ -43,11 +60,6 @@ module.exports = {
         'video',
         'iframe',
     ],
-    gsap: {
-        plugins: ['ScrollTrigger', 'SplitText', 'Flip', 'Observer'],
-        initScript: 'src/assets/js/gsap-init.js',
-        advancedScript: 'src/assets/js/gsap-advanced.js',
-    },
     output: {
         css: 'src/assets/css',
         js: 'src/assets/js',
@@ -55,7 +67,7 @@ module.exports = {
     devServer: { port: 3001, root: 'src' },
     snapshot: {
         baseUrl: 'http://127.0.0.1:3001',
-        pages: ['/', '/404.php'],
+        pages: ['*'],
         outputDir: 'dist',
         rewriteExtension: true,
     },
@@ -75,7 +87,7 @@ module.exports = {
         }
     },
     dist: {
-        zipName: 'my-project-name.zip',
+        zipName: 'squeditor-build.zip',
         previewPlatform: 'netlify',
     },
 };

package/project-template/src/assets/js/_slider_dynamic.js

@@ -0,0 +1,2 @@
+// Auto-generated by build-components.js — DO NOT EDIT
+import './modules/splide-init.js';

package/project-template/src/assets/js/gsap-init.js

@@ -478,6 +478,19 @@ function initTimelines() {
         }
 
         // Initialize timeline with data-gsap-timeline parameters (e.g. {delay: 1, repeat: -1, yoyo: true})
+        // OPT-IN FOUC protection: if the developer set style="visibility: hidden" on the element,
+        // GSAP will manage show/hide. We only use onReverseComplete (reliable) and handle
+        // the "show" part directly in control handlers for bulletproof timing.
+        const isInitiallyHidden = timelineEl.style.visibility === 'hidden';
+        if (isInitiallyHidden) {
+            timelineEl._sqHidden = true; // Flag for control handlers
+            const originalOnReverseComplete = tlConfig.onReverseComplete;
+            tlConfig.onReverseComplete = function() {
+                timelineEl.style.visibility = 'hidden';
+                if (originalOnReverseComplete) originalOnReverseComplete.call(this);
+            };
+        }
+
         const tl = gsap.timeline(tlConfig);
         timelineEl._sqTimeline = tl; // Bind to DOM node so external buttons can trigger it.
 
@@ -548,7 +561,21 @@ function initTimelineControls() {
                     const tl = t._sqTimeline;
                     if (tl) {
                         if (action === 'toggle') {
-                            tl.reversed() ? tl.play() : tl.reverse();
+                            if (t._sqOpen) {
+                                tl.reverse();
+                                t._sqOpen = false;
+                            } else {
+                                if (t._sqHidden) t.style.visibility = 'visible';
+                                tl.play();
+                                t._sqOpen = true;
+                            }
+                        } else if (action === 'play') {
+                            if (t._sqHidden) t.style.visibility = 'visible';
+                            t._sqOpen = true;
+                            tl.play();
+                        } else if (action === 'reverse') {
+                            t._sqOpen = false;
+                            tl.reverse();
                         } else {
                             tl[action]();
                         }

package/project-template/src/assets/js/main.js

@@ -1,6 +1,7 @@
 // src/assets/js/main.js
 import './gsap-init.js';
 import './gsap-advanced.js';
+import './_slider_dynamic.js';
 // SCSS is imported directly in base.php for development (to prevent FOUC) and loaded via <link> in production.
 
 // Remove the dev server FOUC shield

package/project-template/src/assets/js/modules/splide-init.js

@@ -0,0 +1,207 @@
+import Splide, { EventInterface } from '@splidejs/splide';
+
+// Splide CSS is handled separately by build-components.js → slider.min.css
+
+/**
+ * Creates a generic Slide Effect Transition component for Splide,
+ * layering slides while preserving the physical list dimensions for native drag support,
+ * and transitioning specific CSS properties (scale, blur, clip-path).
+ */
+function createEffectTransition(duration, easing, applyStylesFn) {
+    return function CustomTransition(SplideInstance, Components) {
+        const { bind } = EventInterface(SplideInstance);
+        const { list } = Components.Elements;
+        let endCallback;
+        let activeIndex = SplideInstance.index;
+
+        function getBaseTransform(slideEl) {
+            const slides = Components.Elements.slides;
+            const idx = slides.indexOf(slideEl);
+            // Overlaps the slide dynamically without destroying the container's physical width flow math
+            const isVertical = SplideInstance.options.direction === 'ttb';
+            return isVertical ? `translateY(-${100 * idx}%)` : `translateX(-${100 * idx}%)`;
+        }
+
+        function mount() {
+            bind(list, 'transitionend', e => {
+                const slides = Components.Elements.slides;
+                if (endCallback && slides.includes(e.target)) {
+                    endCallback();
+                    endCallback = null;
+                }
+            });
+
+            const setupSlides = () => {
+                const slides = Components.Elements.slides;
+                activeIndex = SplideInstance.index; // Reset on setup/refresh
+                
+                slides.forEach((slide, index) => {
+                    slide.style.transition = 'none';
+                    // We must NOT use absolute/grid because it destroys Splide's drag threshold math!
+                    // Instead we shift the visual representation only, keeping the phantom DOM bounds intact:
+                    const baseTransform = getBaseTransform(slide);
+                    
+                    slide.style.width = '100%';
+                    slide.style.margin = '0'; // override any Splide inline margins
+                    slide.style.transformOrigin = 'center';
+
+                    if (index === activeIndex) {
+                        slide.style.opacity = '1';
+                        slide.style.zIndex = '1';
+                        slide.style.pointerEvents = 'auto'; // Active slide gets clicks
+                        applyStylesFn(slide, 'in', baseTransform);
+                    } else {
+                        slide.style.opacity = '0';
+                        slide.style.zIndex = '0';
+                        slide.style.pointerEvents = 'none'; // Prevent invisible slides from absorbing clicks
+                        applyStylesFn(slide, 'out', baseTransform);
+                    }
+                });
+            };
+
+            // Run immediately upon component mount and on every refresh
+            setupSlides();
+            SplideInstance.on('refresh', setupSlides);
+        }
+
+        function start(index, done) {
+            const slides = Components.Elements.slides;
+            const prevSlide = slides[activeIndex];
+            const nextSlide = slides[index];
+
+            // Update local tracker to the new index immediately
+            activeIndex = index;
+
+            if (!nextSlide || prevSlide === nextSlide) {
+                done();
+                return;
+            }
+
+            // Clean up unneeded slides right away to avoid visual glitches
+            slides.forEach(slide => {
+                if (slide !== prevSlide && slide !== nextSlide) {
+                    const base = getBaseTransform(slide);
+                    slide.style.transition = 'none';
+                    slide.style.opacity = '0';
+                    slide.style.zIndex = '0';
+                    slide.style.pointerEvents = 'none';
+                    applyStylesFn(slide, 'out', base);
+                }
+            });
+
+            // Outgoing slide animation
+            if (prevSlide) {
+                const prevBase = getBaseTransform(prevSlide);
+                prevSlide.style.transition = `all ${duration}ms ${easing}`;
+                prevSlide.style.zIndex = '1';
+                prevSlide.style.opacity = '0';
+                prevSlide.style.pointerEvents = 'none';
+                applyStylesFn(prevSlide, 'out', prevBase);
+            }
+
+            // Reset incoming slide to 'out' state before animating 'in'
+            const nextBase = getBaseTransform(nextSlide);
+            nextSlide.style.transition = 'none';
+            nextSlide.style.zIndex = '2';
+            nextSlide.style.opacity = '0';
+            nextSlide.style.pointerEvents = 'none';
+            applyStylesFn(nextSlide, 'out', nextBase);
+            
+            // Force browser flow flush so the 'out' state is registered visually
+            void nextSlide.offsetWidth;
+
+            // Incoming slide animation
+            nextSlide.style.transition = `all ${duration}ms ${easing}`;
+            nextSlide.style.opacity = '1';
+            nextSlide.style.pointerEvents = 'auto'; // allow interaction
+            applyStylesFn(nextSlide, 'in', nextBase);
+
+            endCallback = done;
+
+            // Failsafe timeout in case transitionend event gets skipped/missed
+            setTimeout(() => {
+                if (endCallback) {
+                    endCallback();
+                    endCallback = null;
+                }
+            }, duration + 50);
+        }
+
+        function cancel() {
+            endCallback = null;
+        }
+
+        return { mount, start, cancel };
+    };
+}
+
+/**
+ * Pre-defined custom transitions
+ * Developers can extend these following the Splide Docs.
+ * Transition properties manipulate opacity automatically; use `applyStylesFn` for transforms.
+ */
+const CustomTransitions = {
+    'scaleup': createEffectTransition(800, 'cubic-bezier(0.16, 1, 0.3, 1)', (slide, state, base) => {
+        const trans = state === 'in' ? 'scale(1)' : 'scale(0.85)';
+        slide.style.transform = `${base} ${trans}`;
+    }),
+    'scaledown': createEffectTransition(800, 'cubic-bezier(0.16, 1, 0.3, 1)', (slide, state, base) => {
+        const trans = state === 'in' ? 'scale(1)' : 'scale(1.15)';
+        slide.style.transform = `${base} ${trans}`;
+    }),
+    'blurfade': createEffectTransition(800, 'ease-in-out', (slide, state, base) => {
+        slide.style.filter = state === 'in' ? 'blur(0px)' : 'blur(10px)';
+        slide.style.transform = `${base} scale(1)`; // scale(1) required to prevent blur rendering bugs
+    }),
+    'reveal': createEffectTransition(1000, 'cubic-bezier(0.85, 0, 0.15, 1)', (slide, state, base) => {
+        slide.style.clipPath = state === 'in' ? 'inset(0 0 0 0)' : 'inset(100% 0 0 0)';
+        const trans = state === 'in' ? 'translateY(0%)' : 'translateY(15%)';
+        slide.style.transform = `${base} ${trans}`;
+    }),
+};
+
+/**
+ * Initializes all Splide sliders on the page
+ * Configuration is inherently read by Splide directly from the valid JSON `data-splide` attribute
+ */
+export function initSplide() {
+    const splides = document.querySelectorAll('.splide');
+    splides.forEach(el => {
+        try {
+            let optionsStr = el.getAttribute('data-splide');
+            let requestedType = null;
+            let overrideOptions = {};
+
+            if (optionsStr) {
+                const options = JSON.parse(optionsStr);
+                
+                if (options.type && CustomTransitions[options.type]) {
+                    requestedType = options.type;
+                    
+                    // Force the slider into 'fade' mode so the core engine expects stacked slides natively,
+                    // apply 'rewind' to emulate the infinite looping of our custom transitions.
+                    overrideOptions = { type: 'fade', rewind: true };
+
+                    // CRITICAL: Splide natively parses the DOM attribute directly inside its constructor!
+                    // We must alter the original DOM data string before init so it doesn't overwrite 'fade' back
+                    options.type = 'fade';
+                    el.setAttribute('data-splide', JSON.stringify(options));
+                }
+            }
+
+            const splide = new Splide(el, overrideOptions);
+
+            if (requestedType && CustomTransitions[requestedType]) {
+                splide.mount({}, CustomTransitions[requestedType]);
+            } else {
+                splide.mount();
+            }
+        } catch (e) {
+            console.error('[Squeditor] Error initializing Splide slider', el, e);
+        }
+    });
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+    initSplide();
+});

package/project-template/src/assets/js/modules/swiper-init.js

@@ -0,0 +1,216 @@
+import Swiper from 'swiper';
+import { Navigation, Pagination, Autoplay, Parallax, Thumbs, EffectFade, FreeMode } from 'swiper/modules';
+
+// Swiper CSS is handled separately by build-components.js → slider.min.css
+
+function splitTopLevel(str, delimiters = [';', ',']) {
+    const result = [];
+    let current = '';
+    let braceDepth = 0;
+    
+    for (let i = 0; i < str.length; i++) {
+        const char = str[i];
+        if (char === '{') braceDepth++;
+        if (char === '}') braceDepth--;
+        
+        if (braceDepth === 0 && delimiters.includes(char)) {
+            result.push(current);
+            current = '';
+        } else {
+            current += char;
+        }
+    }
+    if (current) result.push(current);
+    return result;
+}
+
+/**
+ * Parses a string like "slidesPerView: 1; md: {slidesPerView: 3}; loop: true"
+ * into a valid JavaScript object.
+ */
+function parseSwiperOptions(optionString) {
+    if (!optionString) return {};
+    
+    const options = {};
+    const statements = splitTopLevel(optionString, [';', ',']);
+    
+    statements.forEach(statement => {
+        statement = statement.trim();
+        if (!statement) return;
+        
+        const firstColon = statement.indexOf(':');
+        if (firstColon > -1) {
+            const key = statement.slice(0, firstColon).trim();
+            let rawValue = statement.slice(firstColon + 1).trim();
+            
+            // Handle nested objects
+            if (rawValue.startsWith('{') && rawValue.endsWith('}')) {
+                const innerString = rawValue.slice(1, -1);
+                options[key] = parseSwiperOptions(innerString);
+            } else {
+                options[key] = parsePrimitive(rawValue);
+            }
+        }
+    });
+    
+    return options;
+}
+
+function parsePrimitive(val) {
+    if (val === 'true') return true;
+    if (val === 'false') return false;
+    if (val === 'null') return null;
+    
+    // Check if it's a number
+    if (!isNaN(vanillaParseFloat(val))) {
+        return vanillaParseFloat(val);
+    }
+    
+    // Remove wrapping quotes if they exist
+    if ((val.startsWith("'") && val.endsWith("'")) || (val.startsWith('"') && val.endsWith('"'))) {
+        return val.slice(1, -1);
+    }
+    
+    return val;
+}
+
+function vanillaParseFloat(val) {
+    if(typeof val === 'string' && val.trim() === '') return NaN;
+    return Number(val);
+}
+
+/**
+ * Maps Tailwind breakpoints to Swiper breakpoints
+ */
+function mapBreakpoints(options) {
+    const swiperBreakpoints = {};
+    const tailwindScreens = {
+        'sm': 640,
+        'md': 768,
+        'lg': 1024,
+        'xl': 1280,
+        '2xl': 1536
+    };
+    
+    let hasBreakpoints = false;
+    
+    // 1. Move root-level 'sm', 'md' directly into swiperBreakpoints
+    Object.keys(tailwindScreens).forEach(screen => {
+        if (options[screen]) {
+            hasBreakpoints = true;
+            swiperBreakpoints[tailwindScreens[screen]] = options[screen];
+            delete options[screen]; // Remove from root options
+        }
+    });
+
+    // 2. Process nested options.breakpoints if it exists
+    if (options.breakpoints) {
+        hasBreakpoints = true;
+        Object.keys(options.breakpoints).forEach(key => {
+            if (tailwindScreens[key]) {
+                swiperBreakpoints[tailwindScreens[key]] = options.breakpoints[key];
+            } else {
+                swiperBreakpoints[key] = options.breakpoints[key];
+            }
+        });
+    }
+    
+    if (hasBreakpoints && Object.keys(swiperBreakpoints).length > 0) {
+        options.breakpoints = swiperBreakpoints;
+    }
+    
+    return options;
+}
+
+/**
+ * Initializes Swiper instance for a single element
+ */
+function initSwiperElement(el) {
+    // Prevent double initialization
+    if (el.swiper) return;
+
+    const rawOptions = el.getAttribute('data-sq-swiper') || '';
+    let parsedOptions = parseSwiperOptions(rawOptions);
+    parsedOptions = mapBreakpoints(parsedOptions);
+
+    // Default Configuration
+    const config = {
+        modules: [Navigation, Pagination, Autoplay, Parallax, Thumbs, EffectFade, FreeMode],
+        speed: 600,
+        // Optional navigation
+        navigation: {},
+        // Optional pagination
+        pagination: {
+            clickable: true
+        },
+        ...parsedOptions
+    };
+
+    // Apply custom detached navigation if specified
+    if (parsedOptions.navNext || parsedOptions.navPrev) {
+        config.navigation = {
+            nextEl: parsedOptions.navNext || null,
+            prevEl: parsedOptions.navPrev || null
+        };
+        // Clean up root
+        delete config.navNext;
+        delete config.navPrev;
+    }
+
+    // Apply custom detached pagination if specified
+    if (parsedOptions.paginationEl) {
+        config.pagination = {
+            el: parsedOptions.paginationEl,
+            clickable: true,
+            type: parsedOptions.paginationType || 'bullets'
+        };
+        delete config.paginationEl;
+        delete config.paginationType;
+    }
+
+    // Handle Thumbs Gallery synchronization
+    if (parsedOptions.thumbs) {
+        const thumbTarget = document.querySelector(parsedOptions.thumbs);
+        if (thumbTarget) {
+            // First, ensure the thumb target is initialized
+            if (!thumbTarget.swiper) {
+                initSwiperElement(thumbTarget);
+            }
+            config.thumbs = {
+                swiper: thumbTarget.swiper
+            };
+        }
+    }
+
+    // Ensure slider has basic class structure required by CSS
+    if (!el.classList.contains('swiper')) {
+        el.classList.add('swiper');
+    }
+
+    const wrapper = el.querySelector(':scope > div');
+    if (wrapper && !wrapper.classList.contains('swiper-wrapper')) {
+        wrapper.classList.add('swiper-wrapper');
+    }
+
+    const slides = wrapper ? wrapper.children : el.children;
+    Array.from(slides).forEach(slide => {
+        if (!slide.classList.contains('swiper-slide')) {
+            slide.classList.add('swiper-slide');
+        }
+    });
+
+    // Initialize!
+    new Swiper(el, config);
+}
+
+/**
+ * Global Initialization
+ */
+export function initSwiper() {
+    const swipers = document.querySelectorAll('[data-sq-swiper]');
+    swipers.forEach(initSwiperElement);
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+    initSwiper();
+});