@squeditor/squeditor-framework 1.0.2 → 1.0.4

package/README.md

@@ -1,37 +1,28 @@
-# ⚡️ 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.
-
-## 🚀 Key Features
-
-### 🛠 Zero-Runtime PHP Templating
-Develop using familiar WordPress-style functions like `get_template_part()` and `get_section()`, use PHP arrays as your data layer, and leverage loops to build complex layouts. The production build "snaps" everything into pure HTML, requiring zero server-side processing.
+We implement AI Agents skills to help you build your website easily in minutes. You can use AI Agents to generate well organized and clean code, components, sections, and pages and ship landing pages and saas and agency websites 10x faster.
 
-### 🧩 Selective UIKit 3 Integration
-Stop loading massive component libraries. Squeditor Framework uses a **Component Manifest System** (via `uikit-manifest.json`) to tree-shake UIKit. Use only what you need (like a Slider or Modal) and Squeditor Framework will automatically bundle just the necessary SCSS and JS.
+### Showcase and Demo
 
-### 🎨 Token-Based Styling Architecture
-Fully themeable via a centralized Design Token system (`_tokens.scss`). Every component and layout utility consumes CSS Custom Properties (`--sq-*`), allowing you to swap entire visual identities or color schemas (Light/Dark) instantly across the site.
+[Main Demo](https://squeditor.com/showcase/main-demo/)
+[All Components](https://squeditor.com/showcase/all-components/)
+[Style Guide](https://squeditor.com/showcase/style-guide/)
+[GSAP Animations](https://squeditor.com/showcase/gsap-animations/)
 
-### 🌓 Built-in Light/Dark Mode
-Native support for `sq-theme-dark` classes and Tailwind's `dark:` utilities. The framework detects schema settings from the environment (or URL) and applies them globally to the body, ensuring a seamless and premium dark mode experience.
+[Full Documentation](https://docs.squeditor.com)
 
-### 📚 Section-Based Workflow
-Build pages in minutes using a library of pre-built, token-aware section variants:
-- **Hero**: Video, Split, Centered
-- **Cards**: Grids, Horizontal, Feature lists
-- **CTA**: Split, Banner, In-line
-- **Global**: Responsive Header, Deep-linked Footer
+### Key Features
 
-### 📖 Automatic Style Guide
-Every project includes an automatically generated `style-guide.php` page that renders every active component and its variants, serving as your project's living documentation.
+- Zero-Runtime PHP Templating
+- Selective UIKit 3 Integration
+- Token-Based Styling Architecture
+- Built-in Light/Dark Mode
+- Section-Based Workflow
+- Automatic Style Guide
 
 ---
 
-## 🏗 Project Architecture
+### Project Architecture
 
 ```bash
 [workspace-root]/
@@ -43,9 +34,9 @@ Every project includes an automatically generated `style-guide.php` page that re
 
 ---
 
-## 🏁 Getting Started
+### Getting Started
 
-### 1. Scaffold a New Project
+#### 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, simply run the following command in your terminal:
@@ -54,7 +45,7 @@ npx @squeditor/squeditor-framework your-project-name
 ```
 *(Replace `your-project-name` with your desired folder name).*
 
-### 2. Development
+#### 2. Development
 Navigate into your newly generated project folder, install its dependencies, and start the development server:
 ```bash
 cd your-project-name
@@ -67,7 +58,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
@@ -75,7 +66,7 @@ npm run build
 
 ---
 
-## 🛠 Technology Stack
+### Technology Stack
 
 - **Dev Engine**: PHP 8.2+ (as a templating pre-processor)
 - **CSS Architecture**: Tailwind CSS + SCSS (Layered Overrides)
@@ -86,13 +77,13 @@ npm run build
 
 ---
 
-## 🤝 Contributing
+### Contributing
 
 We welcome contributions! Whether it's adding new section variants, improving the build pipeline, or refining the token system, feel free to open a PR.
 
 ---
 
-## 📄 License
+### License
 
 Squeditor Framework is released under the [MIT License](LICENSE).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squeditor/squeditor-framework",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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/php/functions.php

@@ -90,3 +90,48 @@ function parse_frontmatter(string $file): array {
     }
     return [];
 }
+
+/**
+ * Load an asset file's contents directly (e.g., for inline SVG).
+ *
+ * @param string $path  Path relative to src/assets/, e.g., 'static/icons/vite.svg'
+ * @return string       File contents or empty string if not found
+ */
+function get_asset(string $path): string {
+    $full_path = SRC_PATH . '/assets/' . ltrim($path, '/');
+    if (!file_exists($full_path)) {
+        trigger_error("Asset not found: {$full_path}", E_USER_WARNING);
+        return '';
+    }
+    return file_get_contents($full_path);
+}
+
+/**
+ * Load an image file's contents directly (e.g., for inline SVG images) or return an <img> tag.
+ *
+ * @param string $filename  Filename inside src/assets/static/images/, e.g., 'logo.svg'
+ * @param string $alt       Alt text for the image (if returning an <img> tag)
+ * @param string $class     Custom CSS class(es) to add to the <img> tag
+ * @param bool   $inline    Whether to return raw file contents (e.g. inline SVG). Default false.
+ * @return string           Image tag or file contents, or empty string if not found
+ */
+function get_image(string $filename, string $alt = '', string $class = '', bool $inline = false): string {
+    $full_path = SRC_PATH . '/assets/static/images/' . ltrim($filename, '/');
+    if (!file_exists($full_path)) {
+        trigger_error("Image not found: {$full_path}", E_USER_WARNING);
+        return '';
+    }
+    
+    if ($inline) {
+        return file_get_contents($full_path);
+    }
+    
+    // We assume images are served from /assets/static/images/ relative to document root
+    // This path might need to be adjusted based on the server setup, but for now 
+    // it returns a relative web path.
+    $web_path = '/assets/static/images/' . ltrim($filename, '/');
+    
+    $class_attr = $class !== '' ? sprintf(' class="%s"', htmlspecialchars($class)) : '';
+    
+    return sprintf('<img src="%s" alt="%s"%s>', htmlspecialchars($web_path), htmlspecialchars($alt), $class_attr);
+}

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();
+});