fusee-framework 1.5.3 → 1.6.0

package/README.md

@@ -1,5 +1,5 @@
 # Fusée Framework 🚀
-**v1.5.3 — 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/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()
 
@@ -469,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)
@@ -491,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')
@@ -569,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)
+                    })
+                }
+            }
         }
     }
 }

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

@@ -104,7 +104,6 @@ export function effect(fn) {
         for (const dep of run.deps) dep.delete(run)
         run.deps.clear()
 
-        // Cleanup all nested effects when parent stops
         for (const childCleanup of nestedEffects) {
             childCleanup()
         }

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/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

@@ -546,6 +546,69 @@
       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.3",
+  "version": "1.6.0",
   "description": "Fusée - Signals-first JS Framework | Peak Performance",
   "main": "framework/index.js",
   "types": "framework/types/index.d.ts",