@squeditor/squeditor-framework 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UniStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# ⚡️ 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.
+
+### 🧩 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.
+
+### 🎨 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.
+
+### 🌓 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.
+
+### 📚 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
+
+### 📖 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.
+
+---
+
+## 🏗 Project Architecture
+
+```bash
+[workspace-root]/
+├── php/                    # 🏗 CORE - PHP framework helpers
+├── scripts/                # 🏗 CORE - Build and dev scripts
+├── project-template/       # 🚀 STARTER - Blank project generator
+└── showcase/               # 💎 DEMO - Full-featured example project
+```
+
+---
+
+## 🏁 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.
+
+To scaffold your new project as a sibling to the framework directory, run the following command from your workspace root (outside `squeditor-framework`):
+```bash
+npx squeditor-framework your-project-name
+```
+
+### 3. Development
+Navigate into your newly generated project folder, install its dependencies, and start the development server:
+```bash
+cd your-project-name
+npm install
+npm run dev
+```
+
+> [!CAUTION]
+> **Use Port 3001 for Development**
+> 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
+Generate the static `dist/` folder and a distributable ZIP archive:
+```bash
+npm run build
+```
+
+---
+
+## 🛠 Technology Stack
+
+- **Dev Engine**: PHP 8.2+ (as a templating pre-processor)
+- **CSS Architecture**: Tailwind CSS + SCSS (Layered Overrides)
+- **JS Interactivity**: UIKit 3 (Selective Component Bundling)
+- **Bundler**: Vite 5
+- **Static Generation**: Custom Snapshot Engine
+- **Deployment**: Integrated Netlify/Vercel support
+
+---
+
+## 🤝 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
+
+Squeditor Framework is released under the [MIT License](LICENSE).
+
+---
+
+Built with ❤️ by **Expert Developers** for the modern web.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@squeditor/squeditor-framework",
+  "version": "1.0.0",
+  "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": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unistudioco/squeditor-framework.git"
+  },
+  "keywords": [
+    "squeditor",
+    "framework",
+    "static",
+    "php",
+    "tailwind",
+    "uikit",
+    "vite",
+    "gsap"
+  ],
+  "author": "unistudio.co",
+  "license": "MIT",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/unistudioco/squeditor-framework/issues"
+  },
+  "homepage": "https://github.com/unistudioco/squeditor-framework#readme",
+  "bin": {
+    "squeditor": "./scripts/scaffold.js"
+  }
+}

package/php/functions.php

@@ -0,0 +1,92 @@
+<?php
+// php/functions.php
+
+/**
+ * Include a template part from the template-parts/ directory.
+ * Equivalent to WordPress get_template_part().
+ *
+ * @param string $slug  Folder/file slug, e.g. 'header', 'nav', 'sections/hero/hero-centered'
+ * @param array  $args  Optional associative array passed as $args inside the partial
+ */
+function get_template_part(string $slug, array $args = []): void {
+    $path = SRC_PATH . '/template-parts/' . $slug . '.php';
+    if (!file_exists($path)) {
+        trigger_error("Template part not found: {$path}", E_USER_WARNING);
+        return;
+    }
+    extract($GLOBALS, EXTR_SKIP);
+    global $site;
+    if (!empty($args)) {
+        extract($args, EXTR_SKIP);
+    }
+    include $path;
+}
+
+/**
+ * Include a UIKit3 component partial from the components/ directory.
+ *
+ * @param string $component  Component name, e.g. 'accordion', 'modal'
+ * @param array  $args       Data to pass into the component
+ */
+function get_component(string $component, array $args = []): void {
+    $path = SRC_PATH . '/components/' . $component . '.php';
+    if (!file_exists($path)) {
+        trigger_error("Component not found: {$path}", E_USER_WARNING);
+        return;
+    }
+    extract($GLOBALS, EXTR_SKIP);
+    if (!empty($args)) {
+        extract($args, EXTR_SKIP);
+    }
+    include $path;
+}
+
+/**
+ * Include a section variant.
+ *
+ * @param string $section  Path within sections/, e.g. 'hero/hero-centered'
+ * @param array  $args
+ */
+function get_section(string $section, array $args = []): void {
+    $path = SRC_PATH . '/sections/' . $section . '.php';
+    if (!file_exists($path)) {
+        trigger_error("Section not found: {$path}", E_USER_WARNING);
+        return;
+    }
+    extract($GLOBALS, EXTR_SKIP);
+    if (!empty($args)) {
+        extract($args, EXTR_SKIP);
+    }
+    include $path;
+}
+
+/**
+ * Parse frontmatter from a PHP page file.
+ * Frontmatter is a PHP comment block at the very top of a page file.
+ *
+ * Format inside page files:
+ *   <?php
+ *   /*|
+ *   title: About Us
+ *   description: Learn about our team
+ *   og_image: /assets/static/images/og-about.jpg
+ *   |*\/
+ *
+ * @param  string $file  Absolute path to the PHP page file
+ * @return array         Associative array of frontmatter values
+ */
+function parse_frontmatter(string $file): array {
+    $content = file_get_contents($file);
+    if (preg_match('/\/\*\|(.*?)\|\*\//s', $content, $matches)) {
+        $lines = explode("\n", trim($matches[1]));
+        $data = [];
+        foreach ($lines as $line) {
+            if (str_contains($line, ':')) {
+                [$key, $value] = explode(':', $line, 2);
+                $data[trim($key)] = trim($value);
+            }
+        }
+        return $data;
+    }
+    return [];
+}

package/project-template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "my-project-name",
+  "private": true,
+  "scripts": {
+    "dev": "node ../squeditor-framework/scripts/dev.js",
+    "build:css": "node ../squeditor-framework/scripts/build-components.js && vite build && node ../squeditor-framework/scripts/copy-static.js",
+    "build:snap": "node ../squeditor-framework/scripts/snapshot.js",
+    "build:zip": "node ../squeditor-framework/scripts/package-dist.js && node ../squeditor-framework/scripts/package-customer.js",
+    "build": "npm run build:css && npm run build:snap && npm run build:zip",
+    "preview:netlify": "netlify deploy --dir=dist",
+    "preview:vercel": "vercel dist --yes"
+  },
+  "dependencies": {
+    "gsap": "^3.13.0",
+    "uikit": "^3.21.0"
+  },
+  "devDependencies": {
+    "archiver": "^6.0.0",
+    "autoprefixer": "^10.4.0",
+    "concurrently": "^8.0.0",
+    "fluent-ffmpeg": "^2.1.3",
+    "micromatch": "^4.0.8",
+    "prettier": "^3.8.1",
+    "sass": "^1.70.0",
+    "sharp": "^0.34.5",
+    "tailwindcss": "^3.4.0",
+    "vite": "^5.0.0"
+  }
+}

package/project-template/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+    plugins: {
+        tailwindcss: {},
+        autoprefixer: {},
+    }
+}

package/project-template/squeditor.config.js

@@ -0,0 +1,81 @@
+// showcase/squeditor.config.js
+module.exports = {
+    framework: '../squeditor-framework',
+    name: 'my-project-name',
+    version: '1.0.0',
+    components: [
+        'sticky',
+        'utility',
+        'grid',
+        'nav',
+        'navbar',
+        'icon',
+        'slidenav',
+        'modal',
+        'close',
+        'accordion',
+        'tabs',
+        'switcher',
+        'offcanvas',
+        'drop',
+        'dropbar',
+        'dropnav',
+        'dropdown',
+        'tooltip',
+        'notification',
+        'pagination',
+        'dotnav',
+        'slideshow',
+        'slider',
+        'lightbox',
+        'animation',
+        'visibility',
+        'width',
+        'height',
+        'position',
+        'cover',
+        'parallax',
+        'scrollspy',
+        'transition',
+        'spinner',
+        'inverse',
+        'svg',
+        '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',
+    },
+    devServer: { port: 3001, root: 'src' },
+    snapshot: {
+        baseUrl: 'http://127.0.0.1:3001',
+        pages: ['/', '/404.php'],
+        outputDir: 'dist',
+        rewriteExtension: true,
+    },
+    media: {
+        optimize: {
+            enabled: true,
+            imageQuality: 80,
+            videoQuality: 28, // CRF (Lower is better, 23-28 is standard)
+            include: ['**/*.{jpg,jpeg,png,webp,gif,mp4,webm}'],
+            exclude: []
+        },
+        blur: {
+            enabled: true,
+            amount: 20,
+            include: ['**/*.{jpg,jpeg,png,webp}', '**/*.{mp4,webm}'],
+            exclude: ['**/logos/**', '**/icons/**', '**/placeholder.png']
+        }
+    },
+    dist: {
+        zipName: 'my-project-name.zip',
+        previewPlatform: 'netlify',
+    },
+};

package/project-template/src/404.php

@@ -0,0 +1,21 @@
+<?php
+require_once __DIR__ . '/init.php';
+/*|
+title: Page Not Found
+|*/
+$page_title = '404 - Not Found';
+$body_class = 'page-404';
+
+ob_start();
+?>
+<section class="h-[75vh] flex items-center justify-center text-center">
+  <div>
+    <h1 class="text-9xl font-bold mb-4 opacity-20">404</h1>
+    <h2 class="text-3xl font-bold mb-6">Page Not Found</h2>
+    <p class="mb-8">The page you are looking for does not exist.</p>
+    <a href="index.html" class="btn btn-secondary !h-10 px-10 rounded-full">Return Home</a>
+  </div>
+</section>
+<?php
+$content = ob_get_clean();
+require __DIR__ . '/page-templates/base.php';