fusee-framework 1.5.2 → 1.6.0

package/README.md

@@ -1,5 +1,5 @@
 # Fusée Framework 🚀
-**v1.5.2 — Signals-First JS Framework | Atomic Reactivity | Peak Performance**
+**v1.6.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.
 
@@ -80,7 +80,7 @@ export const Welcome = defineComponent({
 
 Fusée is built with a test-driven mindset to ensure the reliability of its reactivity engine and component lifecycle.
 
-- **Total Tests:** `360`
+- **Total Tests:** `385`
 - **Status:** `All Passed`
 - **Framework:** [Vitest](https://vitest.dev/)
 - **Environment:** JSDOM (Browser simulation)
@@ -106,6 +106,7 @@ npx vitest
 *   **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.

package/app/components/Counter.ts

@@ -23,7 +23,7 @@ export const Counter = defineComponent({
         initialValue: { type: String, default: '0' },
         parentTitle: { type: String, default: '' }
     },
-    setup(props: CounterProps): CounterResult {
+    setup(props: CounterProps, { emit }: { emit: (eventName: string, ...args: any[]) => void }): CounterResult {
         const count = signal<number>(Number(props.initialValue) || 0)
         const multiplier = signal<number>(1)
         inspect(count, multiplier)

package/app/main.ts

@@ -33,19 +33,19 @@ const routes: Route[] = [
             loadingComponent: Loading
         }) 
     },
-    { 
-        path: '/test-for', 
+    {
+        path: '/test-for',
         component: defineAsyncComponent({
             loader: () => import('./routes/TestFor.ts'),
             loadingComponent: Loading
-        }) 
+        })
     },
-    { 
-        path: '/dynamic', 
+    {
+        path: '/dynamic',
         component: defineAsyncComponent({
             loader: () => import('./routes/TestDynamic.ts'),
             loadingComponent: Loading
-        }) 
+        })
     },
     {
         path: '/composables',

package/app/routes/Home.js

@@ -9,29 +9,67 @@ export const Home = defineComponent({
     setup() {
         const title = signal('Welcome!')
         inspect(title)
-        
+
+        const isActive = signal(false)
+        const isDisabled = signal(false)
+        const isLarge = signal(false)
+        const basicClasses = computed(() => ({
+            active: isActive(),
+            disabled: isDisabled(),
+            'is-large': isLarge()
+        }))
+
+        const toggleActive = () => isActive(!isActive())
+        const toggleDisabled = () => isDisabled(!isDisabled())
+        const toggleLarge = () => isLarge(!isLarge())
+
         return {
             title,
             changeTitle: () => title('Changed Title!'),
-            
+
+            isActive,
+            isDisabled,
+            isLarge,
+            basicClasses,
+            toggleActive,
+            toggleDisabled,
+            toggleLarge,
+
             // 🧪 Emit Event Handlers
             handleCounterChange: (value) => console.log('📢 Counter changed to:', value),
             handleCounterReset: () => console.log('🔄 Counter reset requested!'),
             handleCustomEvent: (count, multiplier) => console.log('🎯 Custom event:', { count, multiplier }),
-            
+
             // 🧪 Emit Test Handlers
             handleSimpleClick: () => console.log('✅ SIMPLE CLICK received from child!'),
             handleClickWithData: (count, label, timestamp) => console.log('✅ CLICK WITH DATA:', { count, label, timestamp }),
             handleObjectEvent: (data) => console.log('✅ OBJECT EVENT received:', data),
-            
+
             template: `
                 <div class="page">
                     <h1>{{ title.toUpperCase() }}</h1>
                     <p>This is an SPA built with my own JavaScript custom framework!</p>
                     <p>Made with passion by Sebastian Șomu</p>
-                    
+
                     <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>
+                    <div class="demo-box" f-classList="basicClasses">
+                        Demo Box (hover me!)
+                    </div>
+                    <div style="display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 1rem;">
+                        <button @click="toggleActive" :class="isActive ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isActive ? '✓ Active' : '○ Active' }}
+                        </button>
+                        <button @click="toggleDisabled" :class="isDisabled ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isDisabled ? '✓ Disabled' : '○ Disabled' }}
+                        </button>
+                        <button @click="toggleLarge" :class="isLarge ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isLarge ? '✓ Large' : '○ Large' }}
+                        </button>
+                    </div>
+
                     {{ UserForm }}
                     
                     {{ CounterSection @counter-change="handleCounterChange" @counter-reset="handleCounterReset" @custom-event="handleCustomEvent" :pageTitle="title" }}

package/app/routes/Home.ts

@@ -4,26 +4,72 @@ import { CounterSection } from '../components/CounterSection.js'
 type HomeResult = {
     title: Signal<string>
     changeTitle: () => void
+    isActive: Signal<boolean>
+    isDisabled: Signal<boolean>
+    isLarge: Signal<boolean>
+    basicClasses: Computed<ClassListObject>
+    toggleActive: () => void
+    toggleDisabled: () => void
+    toggleLarge: () => void
     template: string
 }
 
+type ClassListObject = Record<string, boolean>
+
 export const Home = defineComponent({
     components: { UserForm, CounterSection },
     setup(): HomeResult {
         const title = signal<string>('Welcome!')
+
+        const isActive = signal(false)
+        const isDisabled = signal(false)
+        const isLarge = signal(false)
+        const basicClasses = computed(() => ({
+            active: isActive(),
+            disabled: isDisabled(),
+            'is-large': isLarge()
+        }))
+
+        const toggleActive = () => isActive(!isActive())
+        const toggleDisabled = () => isDisabled(!isDisabled())
+        const toggleLarge = () => isLarge(!isLarge())
+
         return {
             title,
             changeTitle: () => title('Changed Title!'),
+            isActive,
+            isDisabled,
+            isLarge,
+            basicClasses,
+            toggleActive,
+            toggleDisabled,
+            toggleLarge,
             template: `
                 <div class="page">
                     <h1>{{ title.toUpperCase() }}</h1>
                     <p>This is an SPA built with my own (TypeScript!) custom framework!</p>
                     <p>Made with passion by Sebastian Șomu</p>
-                    
+
                     <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>
+                    <div class="demo-box" f-classList="basicClasses">
+                        Demo Box (hover me!)
+                    </div>
+                    <div style="display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 1rem;">
+                        <button @click="toggleActive" :class="isActive ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isActive ? '✓ Active' : '○ Active' }}
+                        </button>
+                        <button @click="toggleDisabled" :class="isDisabled ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isDisabled ? '✓ Disabled' : '○ Disabled' }}
+                        </button>
+                        <button @click="toggleLarge" :class="isLarge ? 'btn-on' : 'btn-off'" style="padding: 0.5rem 1rem; border-radius: 6px; cursor: pointer;">
+                            {{ isLarge ? '✓ Large' : '○ Large' }}
+                        </button>
+                    </div>
+
                     {{ UserForm }}
-                    
+
                     {{ CounterSection :pageTitle="title" }}
                 </div>
             `

package/framework/core/directives.js

@@ -1,6 +1,7 @@
 import { signal, effect, batch } from './signal.js'
 import { evaluateExpression } from './evaluator.js'
 import { compileNode } from './compiler.js'
+import { registerDelegatedEvent, createEventHandler, isDelegatedEvent } from './event-delegation.js'
 
 const customDirectives = new Map()
 
@@ -81,6 +82,7 @@ export function processDirectives(root, context, components, effects) {
     processText(root, context, effects)
     processEvents(root, context, effects)
     processCustomDirectives(root, context, effects)
+    processClassList(root, context, effects)
     processCloak(root)
 
     return false
@@ -468,8 +470,9 @@ export function processEvents(el, context, effects) {
     if (el.nodeType !== 1 || !el.attributes) return
 
     for (const attr of [...el.attributes]) {
-        if (attr.name.startsWith('@')) {
-            const fullEventName = attr.name.slice(1)
+        // Handle native events: on:click, on:scroll, on:custom-event
+        if (attr.name.startsWith('on:')) {
+            const fullEventName = attr.name.slice(3) // Remove 'on:' prefix
             const parts = fullEventName.split('.')
             const eventName = parts[0]
             const modifiers = parts.slice(1)
@@ -490,7 +493,7 @@ export function processEvents(el, context, effects) {
                     if (next.endsWith('ms')) return parseInt(next) || 250
                     if (next.endsWith('s')) return (parseFloat(next) || 0.25) * 1000
                 }
-                return 250 
+                return 250
             }
 
             const debounceIdx = modifiers.indexOf('debounce')
@@ -568,6 +571,158 @@ export function processEvents(el, context, effects) {
                     if (throttleTimeoutId) clearTimeout(throttleTimeoutId)
                 })
             }
+            continue
+        }
+
+        // Handle delegated events: @click, @input, etc.
+        if (attr.name.startsWith('@')) {
+            const fullEventName = attr.name.slice(1) // Remove '@' prefix
+            const parts = fullEventName.split('.')
+            const eventName = parts[0]
+            const modifiers = parts.slice(1)
+            const expr = attr.value
+
+            el.removeAttribute(attr.name)
+
+            const targetNode = modifiers.includes('window') ? window : (modifiers.includes('document') ? document : null)
+
+            // Window/document events are always native (can't delegate to window/document from document)
+            if (targetNode) {
+                // Native handler for window/document events
+                const handler = createEventHandler(
+                    typeof context[expr] === 'function' && !context[expr].isSignal
+                        ? context[expr]
+                        : expr,
+                    modifiers,
+                    context,
+                    expr
+                )
+
+                const options = {
+                    once: modifiers.includes('once'),
+                    capture: modifiers.includes('capture') || modifiers.includes('away')
+                }
+
+                targetNode.addEventListener(eventName, handler, options)
+                if (effects) {
+                    effects.push(() => {
+                        targetNode.removeEventListener(eventName, handler, options)
+                    })
+                }
+            } else if (isDelegatedEvent(eventName) && !modifiers.includes('capture') && !modifiers.includes('away')) {
+                // Use event delegation for supported events
+                const potentialFn = context[expr]
+                const isFunction = typeof potentialFn === 'function' && !potentialFn.isSignal
+
+                const wrappedHandler = createEventHandler(
+                    isFunction ? potentialFn : expr,
+                    modifiers,
+                    context,
+                    expr
+                )
+
+                const cleanup = registerDelegatedEvent(el, eventName, wrappedHandler, {
+                    modifiers,
+                    context,
+                    expr
+                })
+
+                if (effects) {
+                    effects.push(cleanup)
+                }
+            } else {
+                // Fallback to native for non-delegated events or when capture/away modifiers are used
+                let timeoutId
+                let lastRun = 0
+                let throttleTimeoutId
+
+                let debounceMs = 0
+                let throttleMs = 0
+
+                const parseDuration = (idx) => {
+                    const next = modifiers[idx + 1]
+                    if (next && /^\d/.test(next)) {
+                        if (next.endsWith('ms')) return parseInt(next) || 250
+                        if (next.endsWith('s')) return (parseFloat(next) || 0.25) * 1000
+                    }
+                    return 250
+                }
+
+                const debounceIdx = modifiers.indexOf('debounce')
+                if (debounceIdx > -1) debounceMs = parseDuration(debounceIdx)
+
+                const throttleIdx = modifiers.indexOf('throttle')
+                if (throttleIdx > -1) throttleMs = parseDuration(throttleIdx)
+
+                const executeLogic = (e) => {
+                    batch(() => {
+                        const potentialFn = context[expr]
+                        if (typeof potentialFn === 'function' && !potentialFn.isSignal) {
+                            potentialFn(e)
+                        } else {
+                            evaluateExpression(expr, context, { $event: e }, false)
+                        }
+                    })
+                }
+
+                const handler = (e) => {
+                    if (modifiers.includes('prevent')) e.preventDefault()
+                    if (modifiers.includes('stop')) e.stopPropagation()
+                    if (modifiers.includes('self') && e.target !== el) return
+
+                    if (e instanceof KeyboardEvent) {
+                        const key = e.key.toLowerCase()
+                        const keyModifiers = modifiers.filter(m => ['enter', 'escape', 'tab', 'space', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright'].includes(m))
+                        if (keyModifiers.length > 0) {
+                            const match = keyModifiers.some(m => {
+                                if (m === 'escape') return key === 'escape' || key === 'esc'
+                                if (m === 'space') return key === ' ' || key === 'spacebar'
+                                return key === m
+                            })
+                            if (!match) return
+                        }
+                    }
+
+                    if (throttleMs > 0) {
+                        const now = Date.now()
+                        const remaining = throttleMs - (now - lastRun)
+
+                        if (remaining <= 0) {
+                            clearTimeout(throttleTimeoutId)
+                            lastRun = now
+                            executeLogic(e)
+                        } else {
+                            clearTimeout(throttleTimeoutId)
+                            throttleTimeoutId = setTimeout(() => {
+                                lastRun = Date.now()
+                                executeLogic(e)
+                            }, remaining)
+                        }
+                        return
+                    }
+
+                    if (debounceMs > 0) {
+                        clearTimeout(timeoutId)
+                        timeoutId = setTimeout(() => executeLogic(e), debounceMs)
+                    } else {
+                        executeLogic(e)
+                    }
+                }
+
+                const options = {
+                    once: modifiers.includes('once'),
+                    capture: modifiers.includes('capture') || modifiers.includes('away')
+                }
+
+                el.addEventListener(eventName, handler, options)
+                if (effects) {
+                    effects.push(() => {
+                        el.removeEventListener(eventName, handler, options)
+                        if (timeoutId) clearTimeout(timeoutId)
+                        if (throttleTimeoutId) clearTimeout(throttleTimeoutId)
+                    })
+                }
+            }
         }
     }
 }
@@ -589,3 +744,43 @@ export function processCloak(el) {
     const els = el.querySelectorAll('[f-cloak]')
     for (const e of els) e.removeAttribute('f-cloak')
 }
+
+export function processClassList(el, context, effects) {
+    if (el.nodeType !== 1 || !el.hasAttribute('f-classList')) return
+
+    const expr = el.getAttribute('f-classList')
+    el.removeAttribute('f-classList')
+
+    const appliedClasses = new Set()
+
+    const e = effect(() => {
+        const result = evaluateExpression(expr, context)
+
+        if (!result || typeof result !== 'object') {
+            console.warn(`[framework] f-classList must evaluate to an object, got: ${typeof result}`)
+            return
+        }
+
+        for (const [className, shouldApply] of Object.entries(result)) {
+            const isApplied = appliedClasses.has(className)
+
+            if (shouldApply && !isApplied) {
+                el.classList.add(className)
+                appliedClasses.add(className)
+            } else if (!shouldApply && isApplied) {
+                el.classList.remove(className)
+                appliedClasses.delete(className)
+            }
+        }
+
+        const currentClasses = new Set(Object.keys(result))
+        for (const className of [...appliedClasses]) {
+            if (!currentClasses.has(className)) {
+                el.classList.remove(className)
+                appliedClasses.delete(className)
+            }
+        }
+    })
+
+    effects.push(e)
+}

package/framework/core/event-delegation.js

@@ -0,0 +1,172 @@
+import { batch } from './signal.js'
+import { evaluateExpression } from './evaluator.js'
+
+export const DELEGATED_EVENTS = new Set([
+    'beforeinput',
+    'click',
+    'dblclick',
+    'contextmenu',
+    'focusin',
+    'focusout',
+    'input',
+    'keydown',
+    'keyup',
+    'mousedown',
+    'mousemove',
+    'mouseout',
+    'mouseover',
+    'mouseup',
+    'pointerdown',
+    'pointermove',
+    'pointerout',
+    'pointerover',
+    'pointerup',
+    'touchend',
+    'touchmove',
+    'touchstart'
+])
+
+const delegatedListeners = new Map()
+const documentListeners = new Map()
+
+export function isDelegatedEvent(eventName) {
+    return DELEGATED_EVENTS.has(eventName.toLowerCase())
+}
+
+function ensureDocumentListener(eventType) {
+    if (documentListeners.has(eventType)) {
+        return
+    }
+
+    const handler = (e) => {
+        const listeners = delegatedListeners.get(eventType)
+        if (!listeners || listeners.size === 0) return
+
+        let target = e.target
+        while (target && target !== document.body && target !== document.documentElement) {
+            for (const entry of listeners) {
+                if (entry.element === target) {
+                    entry.handler(e)
+                }
+            }
+            target = target.parentNode
+        }
+    }
+
+    document.addEventListener(eventType, handler, true)
+    documentListeners.set(eventType, handler)
+}
+
+export function registerDelegatedEvent(element, eventType, handler, options = {}) {
+    const { modifiers = [], context, expr } = options
+    const normalizedEvent = eventType.toLowerCase()
+
+    ensureDocumentListener(normalizedEvent)
+
+    if (!delegatedListeners.has(normalizedEvent))
+        delegatedListeners.set(normalizedEvent, new Set())
+
+    const entry = {
+        element,
+        handler,
+        modifiers,
+        context,
+        expr,
+        cleanup: null
+    }
+
+    delegatedListeners.get(normalizedEvent).add(entry)
+
+    return function cleanup() {
+        const listeners = delegatedListeners.get(normalizedEvent)
+        if (listeners) {
+            listeners.delete(entry)
+            if (listeners.size === 0) {
+                const docHandler = documentListeners.get(normalizedEvent)
+                if (docHandler) {
+                    document.removeEventListener(normalizedEvent, docHandler, true)
+                    documentListeners.delete(normalizedEvent)
+                }
+                delegatedListeners.delete(normalizedEvent)
+            }
+        }
+    }
+}
+
+export function createEventHandler(handler, modifiers, context, expr) {
+    let timeoutId
+    let lastRun = 0
+    let throttleTimeoutId
+
+    let debounceMs = 0
+    let throttleMs = 0
+
+    const parseDuration = (idx) => {
+        const next = modifiers[idx + 1]
+        if (next && /^\d/.test(next)) {
+            if (next.endsWith('ms')) return parseInt(next) || 250
+            if (next.endsWith('s')) return (parseFloat(next) || 0.25) * 1000
+        }
+        return 250
+    }
+
+    const debounceIdx = modifiers.indexOf('debounce')
+    if (debounceIdx > -1) debounceMs = parseDuration(debounceIdx)
+
+    const throttleIdx = modifiers.indexOf('throttle')
+    if (throttleIdx > -1) throttleMs = parseDuration(throttleIdx)
+
+    const executeLogic = (e) => {
+        batch(() => {
+            if (typeof handler === 'function') {
+                handler(e)
+            } else {
+                evaluateExpression(expr, context, { $event: e }, false)
+            }
+        })
+    }
+
+    return (e) => {
+        if (modifiers.includes('prevent')) e.preventDefault()
+        if (modifiers.includes('stop')) e.stopPropagation()
+        if (modifiers.includes('self') && e.target !== e.currentTarget) return
+
+        if (e instanceof KeyboardEvent) {
+            const key = e.key.toLowerCase()
+            const keyModifiers = modifiers.filter(m => ['enter', 'escape', 'tab', 'space', 'arrowup', 'arrowdown', 'arrowleft', 'arrowright'].includes(m))
+            if (keyModifiers.length > 0) {
+                const match = keyModifiers.some(m => {
+                    if (m === 'escape') return key === 'escape' || key === 'esc'
+                    if (m === 'space') return key === ' ' || key === 'spacebar'
+                    return key === m
+                })
+                if (!match) return
+            }
+        }
+
+        if (throttleMs > 0) {
+            const now = Date.now()
+            const remaining = throttleMs - (now - lastRun)
+
+            if (remaining <= 0) {
+                clearTimeout(throttleTimeoutId)
+                lastRun = now
+                executeLogic(e)
+            } else {
+                clearTimeout(throttleTimeoutId)
+                throttleTimeoutId = setTimeout(() => {
+                    lastRun = Date.now()
+                    executeLogic(e)
+                }, remaining)
+            }
+            return
+        }
+
+        if (debounceMs > 0) {
+            clearTimeout(timeoutId)
+            timeoutId = setTimeout(() => executeLogic(e), debounceMs)
+        } else {
+            executeLogic(e)
+        }
+    }
+}

package/framework/core/signal.js

@@ -61,6 +61,7 @@ export function signal(initialValue) {
 export function effect(fn) {
     let active = true
     let running = false
+    const nestedEffects = new Set()
 
     const run = () => {
         if (!active || running) {
@@ -69,14 +70,28 @@ export function effect(fn) {
         }
 
         running = true
+
+        for (const childCleanup of nestedEffects) {
+            childCleanup()
+        }
+        nestedEffects.clear()
+
         for (const dep of run.deps) dep.delete(run)
         run.deps.clear()
 
         const prevEffect = currentEffect
+        const prevOnEffectCreated = onEffectCreated
+
+        onEffectCreated = (childCleanup) => {
+            nestedEffects.add(childCleanup)
+            if (prevOnEffectCreated) prevOnEffectCreated(childCleanup)
+        }
+
         currentEffect = run
         try { fn() }
         finally {
             currentEffect = prevEffect
+            onEffectCreated = prevOnEffectCreated
             running = false
         }
     }
@@ -88,6 +103,11 @@ export function effect(fn) {
         pendingEffects.delete(run)
         for (const dep of run.deps) dep.delete(run)
         run.deps.clear()
+
+        for (const childCleanup of nestedEffects) {
+            childCleanup()
+        }
+        nestedEffects.clear()
     }
 
     if (onEffectCreated) onEffectCreated(cleanup)

package/framework/types/component.d.ts

@@ -1,9 +1,5 @@
-// ─── Component Types ─────────────────────────────────────────────────────────
-
 export type ComponentProps = Record<string, any>
-
 export type EmptyProps = Record<string, never>
-
 export type PropSchema = string[] | Record<string, PropConfig>
 
 export type PropConfig = {

package/framework/types/directives.d.ts

@@ -36,6 +36,7 @@ export function processShow(root: HTMLElement, context: ComponentResult, effects
 export function processHtml(root: HTMLElement, context: ComponentResult, effects: (() => void)[]): void
 export function processText(root: HTMLElement, context: ComponentResult, effects: (() => void)[]): void
 export function processEvents(root: HTMLElement, context: ComponentResult): void
+export function processClassList(root: HTMLElement, context: ComponentResult, effects: (() => void)[]): void
 export function processCloak(root: HTMLElement): void
 
 export interface DirectiveBinding<V = any> {

package/framework/types/event-delegation.d.ts

@@ -0,0 +1,90 @@
+// ─── Event Delegation Types ────────────────────────────────────────────────
+
+/**
+ * Set of standard events that support delegation.
+ * These events bubble and are commonly used in UI interactions.
+ */
+export const DELEGATED_EVENTS: Set<string>
+
+/**
+ * Check if an event type is delegated.
+ * @param eventName - The event name to check (e.g., 'click', 'keydown')
+ * @returns True if the event can be delegated
+ */
+export function isDelegatedEvent(eventName: string): boolean
+
+/**
+ * Options for registering a delegated event.
+ */
+export interface DelegatedEventOptions {
+    /** Event modifiers (e.g., 'prevent', 'stop', 'debounce', 'throttle') */
+    modifiers?: string[]
+    /** Component context for evaluating expressions */
+    context?: Record<string, any>
+    /** Expression string to evaluate */
+    expr?: string
+}
+
+/**
+ * Register a delegated event handler for an element.
+ * Creates a single document-level listener if not already present.
+ *
+ * @param element - The DOM element to register
+ * @param eventType - The event type (e.g., 'click', 'input')
+ * @param handler - The event handler function
+ * @param options - Optional configuration
+ * @returns Cleanup function to remove the handler
+ */
+export function registerDelegatedEvent(
+    element: Element,
+    eventType: string,
+    handler: (event: Event) => void,
+    options?: DelegatedEventOptions
+): () => void
+
+/**
+ * Create a wrapped event handler with modifier support.
+ * Supports: prevent, stop, self, debounce, throttle, keyboard modifiers.
+ *
+ * @param handler - The original handler (function or expression)
+ * @param modifiers - Array of modifier names
+ * @param context - Component context for evaluating expressions
+ * @param expr - Expression string (when handler is a string)
+ * @returns Wrapped handler function
+ */
+export function createEventHandler(
+    handler: Function | string,
+    modifiers: string[],
+    context: Record<string, any>,
+    expr: string
+): (event: Event) => void
+
+/**
+ * Event handler syntax preference.
+ * Use @ prefix for delegated events (optimized, single document listener).
+ * Use on: prefix for native events (individual element listeners, full event control).
+ *
+ * @example
+ * // Delegated - efficient for many elements
+ * <button @click="handleClick">Click</button>
+ *
+ * @example
+ * // Native - full control including stopPropagation
+ * <button on:click="handleClick">Click</button>
+ *
+ * @example
+ * // With modifiers
+ * <form @submit.prevent="handleSubmit">Submit</form>
+ * <input @keydown.enter="handleEnter" />
+ * <input @input.debounce="handleInput" />
+ */
+export interface EventHandlerSyntax {
+    /** Delegated event: @click, @input, @keydown, etc. */
+    delegated: `@${string}`
+    /** Native event: on:click, on:input, on:custom, etc. */
+    native: `on:${string}`
+}
+
+declare global {
+    const isDelegatedEvent: typeof import('./event-delegation').isDelegatedEvent
+}

package/framework/types/index.d.ts

@@ -5,6 +5,7 @@ export * from './router'
 export * from './compiler'
 export * from './directives'
 export * from './store'
+export * from './event-delegation'
 
 declare global {
     type Signal<T = any> = import('./signal').Signal<T>
@@ -13,7 +14,9 @@ declare global {
     type Composable<T extends (...args: any[]) => any> = import('./composable').Composable<T>
     type DirectiveBinding<V = any> = import('./directives').DirectiveBinding<V>
     type DirectiveHooks<V = any> = import('./directives').DirectiveHooks<V>
+    type DelegatedEventOptions = import('./event-delegation').DelegatedEventOptions
     const defineStore: typeof import('./store').defineStore
+    const isDelegatedEvent: typeof import('./event-delegation').isDelegatedEvent
 }
 
 export as namespace Fusee

package/index.html

@@ -293,6 +293,322 @@
     .cmp-input:focus {
       border-color: #8b8bff;
     }
+
+    /* ── f-classList demo styles (Home page) ─────────────────────── */
+    .demo-box {
+      width: 200px;
+      height: 100px;
+      background: #1a1a24;
+      border: 2px solid #3a3a5a;
+      border-radius: 8px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-weight: 600;
+      transition: all 0.3s ease;
+      margin-top: 1rem;
+    }
+
+    .demo-box.active {
+      border-color: #8b8bff;
+      background: rgba(139, 139, 255, 0.1);
+      box-shadow: 0 0 20px rgba(139, 139, 255, 0.3);
+    }
+
+    .demo-box.disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    .demo-box.is-large {
+      width: 300px;
+      height: 150px;
+      font-size: 1.2rem;
+    }
+
+    .btn-on {
+      background: #8b8bff !important;
+      border-color: #8b8bff !important;
+      color: #fff !important;
+    }
+
+    .btn-off {
+      background: #1a1a24 !important;
+      border-color: #555 !important;
+      color: #888 !important;
+    }
+
+    .test-classlist h1 {
+      color: #f59e0b;
+      text-shadow: 0 0 20px rgba(245, 158, 11, 0.3);
+    }
+
+    .test-classlist .subtitle {
+      color: #aaa;
+      font-size: 0.9rem;
+      margin-bottom: 2rem;
+    }
+
+    .demo-section {
+      background: #13131d;
+      border: 1px solid #2a2a3a;
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .demo-section h2 {
+      font-size: 1rem;
+      font-weight: 600;
+      color: #e8e8f0;
+      margin-bottom: 1rem;
+    }
+
+    .demo-box {
+      width: 200px;
+      height: 100px;
+      background: #1a1a24;
+      border: 2px solid #3a3a5a;
+      border-radius: 8px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-weight: 600;
+      transition: all 0.3s ease;
+      margin-bottom: 1rem;
+    }
+
+    .demo-box.active {
+      border-color: #8b8bff;
+      background: rgba(139, 139, 255, 0.1);
+      box-shadow: 0 0 20px rgba(139, 139, 255, 0.3);
+    }
+
+    .demo-box.disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    .demo-box.is-large {
+      width: 300px;
+      height: 150px;
+      font-size: 1.2rem;
+    }
+
+    .controls {
+      display: flex;
+      gap: 0.5rem;
+      flex-wrap: wrap;
+    }
+
+    .controls button {
+      padding: 0.5rem 1rem;
+      border: 1px solid #3a3a5a;
+      background: #0f0f1a;
+      color: #e8e8f0;
+      border-radius: 6px;
+      cursor: pointer;
+      transition: all 0.15s;
+    }
+
+    .controls button:hover {
+      background: #2a2a3a;
+    }
+
+    .controls button.btn-on {
+      background: #8b8bff;
+      border-color: #8b8bff;
+      color: #fff;
+    }
+
+    .controls button.btn-off {
+      background: #1a1a24;
+      border-color: #555;
+      color: #888;
+    }
+
+    .theme-box {
+      padding: 1.5rem;
+      border-radius: 8px;
+      border: 2px solid #3a3a5a;
+      transition: all 0.3s ease;
+      margin-bottom: 1rem;
+    }
+
+    .theme-box.theme-light {
+      background: rgba(245, 158, 11, 0.1);
+      border-color: #f59e0b;
+      color: #f59e0b;
+    }
+
+    .theme-box.theme-dark {
+      background: rgba(139, 139, 255, 0.1);
+      border-color: #8b8bff;
+      color: #8b8bff;
+    }
+
+    .theme-toggle {
+      padding: 0.6rem 1.25rem;
+      background: #f59e0b;
+      color: #000;
+      border: none;
+      border-radius: 6px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: background 0.15s;
+    }
+
+    .theme-toggle:hover {
+      background: #d97706;
+    }
+
+    .action-btn {
+      padding: 0.75rem 1.5rem;
+      border: 2px solid #3a3a5a;
+      background: #1a1a24;
+      color: #e8e8f0;
+      border-radius: 8px;
+      font-weight: 600;
+      cursor: pointer;
+      transition: all 0.3s ease;
+      margin-bottom: 1rem;
+    }
+
+    .action-btn.btn-primary {
+      border-color: #8b8bff;
+      color: #8b8bff;
+    }
+
+    .action-btn.btn-primary:hover {
+      background: rgba(139, 139, 255, 0.1);
+    }
+
+    .action-btn.btn-loading {
+      border-color: #f59e0b;
+      color: #f59e0b;
+      animation: pulse 1.5s infinite;
+    }
+
+    .action-btn.btn-error {
+      border-color: #ff3333;
+      background: rgba(255, 51, 51, 0.1);
+      color: #ff3333;
+    }
+
+    .action-btn.btn-active {
+      transform: scale(0.95);
+    }
+
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+
+    .info-section {
+      background: #0f0f1a;
+      border: 1px solid #2a2a3a;
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-top: 2rem;
+    }
+
+    .info-section h2 {
+      color: #34d399;
+      margin-bottom: 1rem;
+    }
+
+    .info-section ul {
+      margin-left: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .info-section li {
+      color: #aaa;
+      margin-bottom: 0.5rem;
+      line-height: 1.5;
+    }
+
+    .info-section li strong {
+      color: #e8e8f0;
+    }
+
+    .code-example {
+      background: #1a1a24;
+      border: 1px solid #2a2a3a;
+      border-radius: 8px;
+      padding: 1rem;
+    }
+
+    .code-example pre {
+      color: #8b8bff;
+      font-family: 'Courier New', monospace;
+      font-size: 0.85rem;
+      margin: 0;
+      overflow-x: auto;
+    }
+
+    /* ── Event Delegation Demo Styles ───────────────────────────────── */
+    .test-events h1 {
+      color: #ff3333;
+      text-shadow: 0 0 20px rgba(255, 51, 51, 0.4);
+    }
+
+    .test-events .subtitle {
+      color: #aaa;
+      font-size: 0.9rem;
+      margin-bottom: 2rem;
+    }
+
+    .button-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+      gap: 0.75rem;
+      margin-bottom: 1rem;
+    }
+
+    .demo-btn {
+      padding: 0.75rem 1rem;
+      border: 2px solid #3a3a5a;
+      background: #0f0f1a;
+      color: #e8e8f0;
+      border-radius: 8px;
+      cursor: pointer;
+      font-weight: 600;
+      transition: all 0.15s;
+    }
+
+    .demo-btn:hover {
+      background: #2a2a3a;
+      transform: translateY(-2px);
+    }
+
+    .demo-btn.native {
+      border-color: #34d399;
+      color: #34d399;
+    }
+
+    .demo-btn.native:hover {
+      background: rgba(52, 211, 153, 0.1);
+    }
+
+    .counter-display {
+      font-size: 1.1rem;
+      color: #aaa;
+    }
+
+    .counter-display strong {
+      color: #e8e8f0;
+      font-size: 1.3rem;
+    }
+
+    .stop-demo {
+      cursor: pointer;
+      transition: background 0.15s;
+    }
+
+    .stop-demo:hover {
+      background: #252535;
+    }
   </style>
 </head>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fusee-framework",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Fusée - Signals-first JS Framework | Peak Performance",
   "main": "framework/index.js",
   "types": "framework/types/index.d.ts",