fusee-framework 1.7.0 → 1.9.0

package/README.md

@@ -1,139 +1,206 @@
-# Fusée Framework 🚀
-**v1.7.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
-
-Fusée is a custom, high-performance fine-grained reactive JavaScript framework built for speed and simplicity. It features a recursive, non-greedy compiler, a signals-based reactivity engine, Dependency Injection for components and a comprehensive CLI for instant application scaffolding.
-
----
-
-## ⚡ Quick Start
-
-The fastest way to get started with Fusée is via the **Go-Powered CLI**:
-
-```bash
-# 1. Install Fusée CLI globally
-npm install -g fusee-framework
-
-# 2. Scaffold a new high-performance project
-create-fusee-app my-awesome-app
-# or simply
-fusee init my-awesome-app
-```
-Follow the interactive prompt to choose your template (**JavaScript** or **TypeScript**) and launch your app instantly!
-
----
-
-## 🏗️ File-Based Routing (Nuxt-style)
-Fusée now supports automated, file-based routing. No more manual route definitions!
-
-- **Pages**: Just drop a file in `app/pages/` and it becomes a route.
-- **Layouts**: Use `app/pages/_layout.js` to wrap your pages in consistent UI structures.
-- **Dynamic Routes**: Support for `[id].js` style dynamic parameters.
-
-```bash
-# Generate a new page instantly
-fusee generate page contact
-```
-
----
-
-## 🔥 Key Features
-
-- **New Go-Powered CLI**: Blazing fast project scaffolding and resource generation.
-- **Signals-First Reactivity**: Modern atomic updates that ensure only the modified parts of the DOM are touched.
-- **Nuxt-style File Routing**: Automated route discovery with layout support.
-- **Recursive Hybrid Compiler**: A robust architectural approach to node traversal.
-- **Optimized Directives**: Native support for `f-if`, `f-for`, `f-model`, `f-text`, `f-cloak` and more.
-- **Performance Shield (`f-once`)**: Isolate and stabilize static subtrees.
-- **Vite Integration**: Full support for the fastest development workflow and HMR.
-
----
-
-## 🛠 Project Structure
-
-A typical Fusée project looks like this:
-
-- **`framework/`**: The core reactive engine.
-- **`app/`**: Your application logic (routes, components).
-- **`index.html`**: The entry point of your reactive world.
-
----
-
-## 📝 Example Component
-
-```javascript
-export const Welcome = defineComponent({
-    setup() {
-        const name = signal('World');
-        const count = signal(0);
-        const double = computed(() => count() * 2);
-
-        return {
-            name,
-            count,
-            double,
-            inc: () => count(count() + 1),
-            template: `
-                <div class="card">
-                    <h2>Hello, {{ name }}!</h2>
-                    <input f-model="name" placeholder="Name" />
-                    
-                    <button @click.debounce.300ms="inc">
-                        Clicked {{ count }} times
-                    </button>
-                    
-                    <p f-if="count() > 0">
-                        Double: <strong>{{ double }}</strong>
-                    </p>
-                </div>
-            `
-        };
-    }
-});
-```
-
----
-
-## ✅ Quality Assurance & Testing
-
-Fusée is built with a test-driven mindset to ensure the reliability of its reactivity engine and component lifecycle.
-
-- **Total Tests:** `468`
-- **Status:** `All Passed`
-- **Framework:** [Vitest](https://vitest.dev/)
-- **Environment:** JSDOM (Browser simulation)
-
-### Running Tests
-
-```bash
-# Run all tests (easiest)
-npm test
-
-# Run all tests with verbose output
-npx vitest --reporter=verbose
-
-# Run type tests only
-npx vitest run --typecheck
-
-# Run tests in watch mode
-npx vitest
-```
-
-### Test Coverage includes:
-*   **Reactivity Engine:** 100% (Signals, Batching, Computed, Watchers).
-*   **Component System:** Props, Slots, Async Components, and Lifecycle Hooks.
-*   **Dependency Injection:** Nested Provide/Inject and Shadowing.
-*   **Directives:** `f-if`, `f-for`, `f-model`, and Event Modifiers.
-*   **Events:** Event delegation and native event handling.
-*   **Memory Safety:** Explicit checks for memory leaks and automatic effect disposal.
-*   **Type Safety:** Comprehensive TypeScript definitions and type tests.
-*   **Integration Tests:** Advanced module combinations and edge cases.
-
----
-
-## 🚀 Future Roadmap
-
-- [ ] Advanced state management and SSR support
-- [ ] Lightweight compiler which transforms declarative HTML into optimized runtime instructions
-- [ ] Integrated backend development support
-
-Built with ❤️ by me, Sebi Somu, a forward-thinking JavaScript Architect.
+# Fusée Framework
+
+**v1.9.0 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+
+Fusée is a custom, high-performance fine-grained reactive JavaScript framework built for speed and simplicity. It features a recursive, non-greedy compiler, a signals-based reactivity engine, Dependency Injection for components and a comprehensive CLI for instant application scaffolding.
+
+---
+
+## Quick Start
+
+The fastest way to get started with Fusée is via the **Go-Powered CLI**:
+
+```bash
+# 1. Install Fusée CLI globally
+npm install -g fusee-framework
+
+# 2. Scaffold a new high-performance project
+create-fusee-app my-awesome-app
+# or simply
+fusee init my-awesome-app
+```
+
+Follow the interactive prompt to choose your template (**JavaScript** or **TypeScript**) and launch your app instantly!
+
+---
+
+## File-Based Routing (Nuxt-style)
+
+Fusée now supports automated, file-based routing!
+
+- **Pages**: Just drop a file in `app/pages/` and it becomes a route.
+- **Layouts**: Use `app/pages/_layout.js` to wrap your pages in consistent UI structures.
+- **Dynamic Routes**: Support for `[id].js` style dynamic parameters.
+
+```bash
+# Generate a new page instantly
+fusee generate page contact
+```
+
+---
+
+## Build-Time HTML Template Compiler (New in v1.9)
+
+Fusée now features a fully integrated **Build-Time Template Compiler** powered by the `fuseeCompilerPlugin` for Vite. Instead of parsing and compiling HTML strings at runtime, Fusée compiles external HTML templates into highly optimized virtual DOM creation calls (`h`, `hText`, `hIf`, `hFor`) during the build/dev stage.
+
+### Why use the Build-Time Compiler?
+
+- **Zero Runtime Overhead**: No template parsing in the browser, leading to smaller bundles and faster page load speeds.
+- **Separation of Concerns**: Write clean HTML in `.template.html` files with full editor autocomplete, syntax highlighting, and formatting support.
+- **Compile-Time Warnings**: Errors in template syntax are caught immediately in your terminal or browser console during development.
+
+### How to use it:
+
+1. **Create an HTML template file** (e.g., `Welcome.template.html`):
+
+```html
+<div class="card">
+  <h2>Hello, {{ name }}!</h2>
+  <input f-model="name" placeholder="Type a name..." />
+
+  <button @click="increment">Clicked {{ count }} times</button>
+
+  <p f-if="count() > 0">Double: <strong>{{ double }}</strong></p>
+</div>
+```
+
+2. **Import and bind the `render` function** in your component file (e.g., `Welcome.js`):
+
+```javascript
+import { render } from "./Welcome.template.html";
+
+export const Welcome = defineComponent({
+  render,
+  setup() {
+    const name = signal("World");
+    const count = signal(0);
+    const double = computed(() => count() * 2);
+
+    return {
+      name,
+      count,
+      double,
+      increment: () => count(count() + 1),
+    };
+  },
+});
+```
+
+Vite intercepts the `.template.html` import, runs the compiler, and inlines the generated JavaScript render code seamlessly!
+
+Benchmark results for specific stress tests (from https://github.com/codegenixdev/js-frontend-frameworks-benchmark):
+
+| Action                             | Avg Duration (ms) |
+| :--------------------------------- | :---------------- |
+| Create 50,000 Rows                 | 12.60             |
+| Update Every 10th Row (Salary +50) | 15.90             |
+| Swap 2nd and 9th-to-last Rows      | 4.60              |
+| Clear All Rows                     | 0.70              |
+| **Total Average**                  | **33.80**         |
+
+---
+
+## Key Features
+
+- **New Go-Powered CLI**: Blazing fast project scaffolding and resource generation.
+- **Signals/Resources-First Reactivity**: Modern atomic updates that ensure only the modified parts of the DOM are touched.
+- **Nuxt-style File Routing**: Automated route discovery with layout support.
+- **Recursive Hybrid Compiler**: A robust architectural approach to node traversal.
+- **Optimized Directives**: Native support for `f-if`, `f-for`, `f-model`, `f-text`, `f-cloak` and more.
+- **Performance Shield (`f-once`)**: Isolate and stabilize static subtrees.
+- **Vite Integration**: Full support for the fastest development workflow and HMR.
+- **Dependency Injection**: Nested Provide/Inject and Shadowing.
+- **Memory Safety**: Explicit checks for memory leaks and automatic effect disposal.
+
+---
+
+## Project Structure
+
+A typical Fusée project looks like this:
+
+- **`framework/`**: The core reactive engine.
+- **`app/`**: Your application logic (routes, components).
+- **`index.html`**: The entry point of your reactive world.
+
+---
+
+## Example Component
+
+```javascript
+export const Welcome = defineComponent({
+  setup() {
+    const name = signal("World");
+    const count = signal(0);
+    const double = computed(() => count() * 2);
+
+    return {
+      name,
+      count,
+      double,
+      inc: () => count(count() + 1),
+      template: `
+                <div class="card">
+                    <h2>Hello, {{ name }}!</h2>
+                    <input f-model="name" placeholder="Name" />
+                    
+                    <button @click.debounce.300ms="inc">
+                        Clicked {{ count }} times
+                    </button>
+                    
+                    <p f-if="count() > 0">
+                        Double: <strong>{{ double }}</strong>
+                    </p>
+                </div>
+            `,
+    };
+  },
+});
+```
+
+---
+
+## Quality Assurance & Testing
+
+Fusée is built with a test-driven mindset to ensure the reliability of its reactivity engine and component lifecycle.
+
+- **Total Tests:** `550`
+- **Status:** `All Passed`
+- **Framework:** [Vitest](https://vitest.dev/)
+- **Environment:** JSDOM (Browser simulation)
+
+### Running Tests
+
+```bash
+# Run all tests (easiest)
+npm test
+
+# Run all tests with verbose output
+npx vitest --reporter=verbose
+
+# Run type tests only
+npx vitest run --typecheck
+
+# Run tests in watch mode
+npx vitest
+```
+
+### Test Coverage includes:
+
+- **Reactivity Engine:** 100% (Signals, Batching, Computed, Watchers).
+- **Component System:** Props, Slots, Async Components, and Lifecycle Hooks.
+- **Dependency Injection:** Nested Provide/Inject and Shadowing.
+- **Directives:** `f-if`, `f-for`, `f-model`, and Event Modifiers.
+- **Events:** Event delegation and native event handling.
+- **Memory Safety:** Explicit checks for memory leaks and automatic effect disposal.
+- **Type Safety:** Comprehensive TypeScript definitions and type tests.
+- **Integration Tests:** Advanced module combinations and edge cases.
+
+---
+
+## Future Roadmap
+
+- [ ] Advanced state management and SSR support
+- [x] Optimising the existing HTML compiler and remove useless DOM trasversals in lists
+- [ ] Integrated backend development support
+
+Built by me, Sebi Somu, a forward-thinking JavaScript Architect.

package/app/benchmark/benchmark.js

@@ -96,7 +96,7 @@ function renderTable(rows, container) {
         </tr>
       </thead>
       <tbody>
-        <tr f-for="row in rows" :class="row.selected() ? 'selected' : ''">
+        <tr f-for="row in rows" :key="row.id" :class="row.selected() ? 'selected' : ''">
           <td>{{ row.id }}</td>
           <td>{{ row.label() }}</td>
           <td>
@@ -166,7 +166,7 @@ const benchmarks = {
       <table>
         <thead><tr><th>ID</th><th>Label</th></tr></thead>
         <tbody>
-          <tr f-for="row in rows" :class="row.selected() ? 'selected' : ''">
+          <tr f-for="row in rows" :key="row.id" :class="row.selected() ? 'selected' : ''">
             <td>{{ row.id }}</td>
             <td>{{ row.label() }}</td>
           </tr>

package/app/benchmark/vite.config.js

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vite'
+import path from 'path'
+
+export default defineConfig({
+    root: './app/benchmark',
+
+    resolve: {
+        alias: {
+            'fusee-framework': path.resolve(__dirname, '../../framework'),
+        }
+    },
+
+    server: {
+        port: 5173,
+        open: true,
+        hmr: true,
+    },
+
+    build: {
+        outDir: '../../dist-benchmark',
+        emptyOutDir: true,
+    }
+})

package/app/main.js

@@ -1,4 +1,6 @@
-import { createRouter, mountOutlet, defineAsyncComponent, generateRoutes } from '../framework/index.js'
+import { createRouter, mountOutlet, generateRoutes, directive, provideGlobal } from '../framework/index.js'
+import { APP_CONFIG, LoggerService } from './services.js'
+
 import { Loading } from './components/Loading.js'
 
 directive('focus', {
@@ -17,13 +19,32 @@ directive('highlight', {
     }
 })
 
-const pages = import.meta.glob('./pages/**/*.{js,ts}')
+const pages = import.meta.glob('./pages/**/*.js')
+
 const routes = generateRoutes(pages, {
     loadingComponent: Loading
 })
 
-createRouter(routes)
+provideGlobal(LoggerService);
+
+provideGlobal({
+    provide: APP_CONFIG,
+    useValue: {
+        title: 'Fusee v2 App',
+        version: '2.0.0-beta'
+    }
+});
+
+// Scroll behavior configuration
+createRouter(routes, {
+    scrollBehavior: {
+        scrollToTop: true,
+        scrollToAnchor: true,
+        saveScrollPosition: true
+    }
+})
 
 const outlet = document.getElementById('app')
 if (!outlet) throw new Error('[app] #app element not found in DOM')
+
 mountOutlet(outlet)

package/app/main.ts

@@ -60,7 +60,13 @@ routes.push({
 
 
 
-createRouter(routes)
+createRouter(routes, {
+    scrollBehavior: {
+        scrollToTop: true,
+        scrollToAnchor: true,
+        saveScrollPosition: true
+    }
+})
 
 
 

package/app/pages/_layout.js

@@ -1,26 +1,53 @@
 import { defineComponent } from '../../framework/index.js'
 
+
+
 export const RootLayout = defineComponent({
+
     setup() {
+
         return {
+
             template: `
+
                 <div class="root-layout">
+
                     <nav>
+
                         <a href="/" f-link>Home</a>
+
                         <a href="/about" f-link>About</a>
+
                         <a href="/test-for" f-link>Loops Test</a>
+
                         <a href="/dynamic" f-link style="color: #ec4899;">Dynamic Components</a>
+
                         <a href="/composables" f-link style="color: #34d399;">Composables</a>
+
                         <a href="/users" f-link style="color: #f59e0b;">👥 Users (Nested)</a>
+
                         <a href="/router-example" f-link style="color: #8b8bff;">🔗 Router Example</a>
+                        <a href="/async-work" f-link style="color: #34d399;">⚡ Async Work</a>
+
                     </nav>
+
                     
+
                     <main class="content-wrap">
+
                         <!-- This is where all pages will be rendered -->
+
                         <div data-router-view></div>
+
                     </main>
+
                 </div>
+
             `
+
         }
+
     }
+
 })
+

package/app/pages/async-work.js

@@ -0,0 +1,65 @@
+import { defineComponent, signal, resource } from '../../framework/index.js'
+
+export default defineComponent({
+    setup() {
+        const userId = signal(1)
+
+        const [user, { refetch }] = resource(userId, async (id) => {
+            const response = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
+            if (!response.ok) throw new Error('User not found')
+            return response.json()
+        })
+
+        return {
+            userId,
+            user,
+            refetch,
+            next: () => userId(userId() + 1),
+            prev: () => userId() > 1 && userId(userId() - 1),
+            template: `
+                <div class="page">
+                    <h1>⚡ Async Work with Resources</h1>
+                    <p>This page demonstrates the new <code>resource</code> primitive, inspired by SolidJS. It handles async data fetching with reactive loading and error states.</p>
+                    
+                    <div class="demo-section">
+                        <div class="flex gap-2 mb-6">
+                            <button @click="prev" class="cmp-btn minus" :disabled="userId() <= 1">← Previous</button>
+                            <button @click="next" class="cmp-btn plus">Next User →</button>
+                            <button @click="refetch" class="cmp-btn reset">🔄 Refetch</button>
+                            <span class="ml-4 flex items-center">Current ID: <strong>{{ userId }}</strong></span>
+                        </div>
+
+                        <div f-if="user.loading()">
+                            <div class="action-btn btn-loading">Fetching data from API...</div>
+                        </div>
+
+                        <div f-if="user.error()">
+                            <div class="action-btn btn-error">
+                                <strong>Error:</strong> {{ user.error().message }}
+                            </div>
+                        </div>
+
+                        <div f-if="user() && !user.loading()">
+                            <div class="theme-box theme-dark">
+                                <h2 class="text-xl font-bold mb-2">{{ user().name }}</h2>
+                                <p><strong>Username:</strong> @{{ user().username }}</p>
+                                <p><strong>Email:</strong> {{ user().email }}</p>
+                                <p><strong>Website:</strong> <a :href="'https://' + user().website" target="_blank" style="color: #8b8bff">{{ user().website }}</a></p>
+                                <p><strong>Company:</strong> {{ user().company.name }}</p>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div class="info-section">
+                        <h2>How it works:</h2>
+                        <ul>
+                            <li><strong>Reactive Source:</strong> The fetcher automatically reruns when <code>userId</code> changes.</li>
+                            <li><strong>State Tracking:</strong> <code>user.loading()</code> and <code>user.error()</code> are signals updated by the framework.</li>
+                            <li><strong>Batching:</strong> Loading and data states are updated atomically to prevent UI flickers.</li>
+                        </ul>
+                    </div>
+                </div>
+            `
+        }
+    }
+})

package/app/pages/index.js

@@ -52,10 +52,21 @@ export const Home = defineComponent({
                     <p>This is an SPA built with my own JavaScript custom framework!</p>
                     <p>Made with passion by Sebastian Șomu</p>
 
+                    <!-- Navigation -->
+                    <div style="display: flex; gap: 0.5rem; flex-wrap: wrap; margin: 1.5rem 0; padding: 1rem; background: #2a2a2a; border-radius: 8px;">
+                        <a href="#classlist" f-link style="color: #f59e0b; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🎨 f-classList</a>
+                        <a href="#userform" f-link style="color: #10b981; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">📝 User Form</a>
+                        <a href="#counter" f-link style="color: #3b82f6; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🔢 Counter</a>
+                        <a href="#emit" f-link style="color: #4da6ff; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🧪 Emit Events</a>
+                        <a href="#slots" f-link style="color: #8b5cf6; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🎴 Slots</a>
+                        <a href="#interpolation" f-link style="color: #e83e8c; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🔤 Interpolation</a>
+                        <a href="#provide" f-link style="color: #4CAF50; text-decoration: none; padding: 0.5rem 1rem; background: #3a3a3a; border-radius: 4px;">🔗 Provide/Inject</a>
+                    </div>
+
                     <button @click="changeTitle" class="primary-btn" style="margin-bottom: 20px;">Change App Title</button>
 
                     <!-- 🎨 f-classList Demo -->
-                    <h3 style="margin-top: 40px; margin-bottom: 20px; color: #f59e0b;">🎨 f-classList Demo</h3>
+                    <h3 id="classlist" style="margin-top: 40px; margin-bottom: 20px; color: #f59e0b;">🎨 f-classList Demo</h3>
                     <div class="demo-box" f-classList="basicClasses">
                         Demo Box (hover me!)
                     </div>
@@ -71,16 +82,18 @@ export const Home = defineComponent({
                         </button>
                     </div>
 
+                    <h3 id="userform" style="margin-top: 40px; margin-bottom: 20px; color: #10b981;">📝 User Form Demo</h3>
                     {{ UserForm }}
                     
+                    <h3 id="counter" style="margin-top: 40px; margin-bottom: 20px; color: #3b82f6;">🔢 Counter Demo</h3>
                     {{ CounterSection @counter-change="handleCounterChange" @counter-reset="handleCounterReset" @custom-event="handleCustomEvent" :pageTitle="title" }}
                     
                     <!-- 🧪 EMIT TEST - NEW SEPARATE COMPONENT -->
-                    <h3 style="margin-top: 40px; margin-bottom: 20px; color: #4da6ff;">🧪 EMIT EVENTS TEST LAB</h3>
+                    <h3 id="emit" style="margin-top: 40px; margin-bottom: 20px; color: #4da6ff;">🧪 EMIT EVENTS TEST LAB</h3>
                     {{ EmitTest @simple-click="handleSimpleClick" @click-with-data="handleClickWithData" @object-event="handleObjectEvent" }}
                     
                     <!-- 🧪 Slots Test -->
-                    <h3 style="margin-top: 40px; margin-bottom: 20px;">🎴 Slots Test</h3>
+                    <h3 id="slots" style="margin-top: 40px; margin-bottom: 20px;">🎴 Slots Test</h3>
                     
                     {{ Card title="Custom Card" }}
                         <template slot="header">
@@ -100,7 +113,7 @@ export const Home = defineComponent({
                     {{ /Card }}
                     
                     <!-- 🧪 INTERPOLATION TEST -->
-                    <h3 style="margin-top: 40px; margin-bottom: 20px; color: #e83e8c;">🔤 INTERPOLATION TEST</h3>
+                    <h3 id="interpolation" style="margin-top: 40px; margin-bottom: 20px; color: #e83e8c;">🔤 INTERPOLATION TEST</h3>
                     <div style="background: #2a2a2a; padding: 15px; border-radius: 8px; border: 1px solid #444;">
                         <p><strong>Escaped Braces:</strong> \\{{ this is not evaluated }}</p>
                         <p><strong>String Literal with Braces:</strong> {{ "Look, {{ braces }} inside a string!" }}</p>
@@ -108,8 +121,15 @@ export const Home = defineComponent({
                     </div>
 
                     <!-- 🧪 PROVIDE / INJECT TEST -->
-                    <h3 style="margin-top: 40px; margin-bottom: 20px; color: #4CAF50;">🔗 PROVIDE / INJECT TEST</h3>
+                    <h3 id="provide" style="margin-top: 40px; margin-bottom: 20px; color: #4CAF50;">🔗 PROVIDE / INJECT TEST</h3>
                     {{ ParentComponent }}
+
+                    <!-- Back to top -->
+                    <div style="text-align: center; margin-top: 3rem; padding: 2rem;">
+                        <a href="/" f-link style="color: white; text-decoration: none; padding: 0.75rem 1.5rem; background: #3b82f6; border-radius: 6px; font-weight: bold;">
+                            ⬆️ Back to Top
+                        </a>
+                    </div>
                 </div>
             `
         }

package/app/pages/index.ts

@@ -50,6 +50,15 @@ export const Home = defineComponent({
                     <p>This is an SPA built with my own (TypeScript!) custom framework!</p>
                     <p>Made with passion by Sebastian Șomu</p>
 
+                    <div style="display: flex; gap: 0.75rem; flex-wrap: wrap; margin: 1rem 0;">
+                        <a href="/scroll-demo" f-link class="cmp-btn" style="background: linear-gradient(135deg, #8b8bff, #6b6bff);">
+                            🔽 Scroll Behavior Demo
+                        </a>
+                        <a href="/users" f-link class="cmp-btn">
+                            👥 Router Example
+                        </a>
+                    </div>
+
                     <button @click="changeTitle" class="primary-btn" style="margin-bottom: 20px;">Change App Title</button>
 
                     <h3 style="margin-top: 40px; margin-bottom: 20px; color: #f59e0b;">🎨 f-classList Demo</h3>