fusee-framework 1.2.1 → 1.4.0

package/framework/core/directives.js

@@ -2,9 +2,77 @@ import { signal, effect, batch } from './signal.js'
 import { evaluateExpression } from './evaluator.js'
 import { compileNode } from './compiler.js'
 
+const customDirectives = new Map()
+
+export function directive(name, definition) {
+    if (typeof name !== 'string' || !name.trim()) {
+        console.error('[framework] directive() requires a non-empty name')
+        return
+    }
+    if (!definition || typeof definition !== 'object') {
+        console.error(`[framework] directive("${name}") requires a definition object`)
+        return
+    }
+    customDirectives.set(name, definition)
+}
+
+export function processCustomDirectives(el, context, effects) {
+    if (el.nodeType !== 1 || !el.hasAttribute || !el.attributes) return
+
+    for (const attr of [...el.attributes]) {
+        const match = attr.name.match(/^f-([a-zA-Z0-9-]+)(?::([a-zA-Z0-9-]+))?(?:\.(.+))?$/)
+
+        if (!match) continue
+
+        const directiveName = match[1]
+        const arg = match[2] || null
+        const modifiersStr = match[3]
+        const modifiers = modifiersStr ? modifiersStr.split('.') : []
+
+        const definition = customDirectives.get(directiveName)
+        if (!definition) {
+            continue
+        }
+
+        el.removeAttribute(attr.name)
+
+        const value = evaluateExpression(attr.value, context)
+        const expression = attr.value
+
+        const binding = {
+            value,
+            expression,
+            arg,
+            modifiers
+        }
+
+        if (typeof definition.mounted === 'function') {
+            definition.mounted(el, binding)
+        }
+
+        if (typeof definition.updated === 'function') {
+            effects.push(effect(() => {
+                const newValue = evaluateExpression(expression, context)
+
+                if (!Object.is(binding.value, newValue)) {
+                    binding.value = newValue
+                    definition.updated(el, binding)
+                }
+            }))
+        }
+
+        if (typeof definition.unmounted === 'function') {
+            effects.push(() => {
+                definition.unmounted(el, binding)
+            })
+        }
+    }
+}
+
 export function processDirectives(root, context, components, effects) {
     if (processFor(root, context, components, effects)) return true
     if (processIf(root, context, components, effects)) return true
+    if (processIs(root, context, components, effects)) return true
 
     processShow(root, context, effects)
     processModel(root, context, effects)
@@ -12,6 +80,7 @@ export function processDirectives(root, context, components, effects) {
     processHtml(root, context, effects)
     processText(root, context, effects)
     processEvents(root, context, effects)
+    processCustomDirectives(root, context, effects)
     processCloak(root)
 
     return false
@@ -275,6 +344,110 @@ export function processIf(el, context, components, effects) {
     return true
 }
 
+export function processIs(el, context, components, effects) {
+    if (el.nodeType !== 1 || !el.hasAttribute('f-is')) return false
+
+    // 1. Prepare directive state
+    const expr = el.getAttribute('f-is')
+    const keepAlive = processKeepAlive(el)
+
+    el.removeAttribute('f-is')
+
+    const anchor = document.createComment('f-keepAlive-anchor')
+    el.parentNode.insertBefore(anchor, el)
+
+    // Keep a clone to reuse attributes (props/@events) for every dynamic instance
+    const templateNode = el.cloneNode(true)
+    el.remove()
+
+    const cache = new Map()
+    let activeKey = null
+    let activeCleanup = []
+
+    // 2. Reactive loop
+    effects.push(effect(() => {
+        const rawValue = evaluateExpression(expr, context)
+
+        // Skip if same component is already active
+        if (rawValue === activeKey) return
+
+        // 3. Handle exiting component
+        if (activeKey !== null) {
+            const currentEntry = cache.get(activeKey)
+            if (currentEntry) {
+                if (keepAlive) {
+                    currentEntry.node.remove()
+                } else {
+                    for (const cleanup of activeCleanup) if (typeof cleanup === 'function') cleanup()
+                    currentEntry.node.remove()
+                    cache.delete(activeKey)
+                    activeCleanup = []
+                }
+            }
+        }
+
+        if (!rawValue) {
+            activeKey = null
+            return
+        }
+
+        // 4. Handle entering component
+        let entry = cache.get(rawValue)
+
+        if (entry && keepAlive) {
+            // Restore from cache
+            anchor.parentNode.insertBefore(entry.node, anchor.nextSibling)
+            activeCleanup = entry.cleanup
+        } else {
+            // Create new instance
+            let ComponentFn = typeof rawValue === 'string' ? components[rawValue] : rawValue
+
+            if (typeof ComponentFn !== 'function') {
+                console.warn(`[framework] f-is: Component "${rawValue}" not found or invalid.`)
+                return
+            }
+
+            const compEl = templateNode.cloneNode(true)
+            compEl._isDynamicComponent = true
+
+            const tempName = '__dynamic_component__'
+            compEl.setAttribute('data-component', tempName)
+
+            anchor.parentNode.insertBefore(compEl, anchor.nextSibling)
+
+            const childCleanup = []
+            const dynamicComponents = { ...components, [tempName]: ComponentFn }
+
+            // Trigger the internal compiler to bind props and events
+            compileNode(compEl, context, dynamicComponents, childCleanup)
+
+            entry = { node: compEl, cleanup: childCleanup }
+            cache.set(rawValue, entry)
+            activeCleanup = childCleanup
+        }
+
+        activeKey = rawValue
+    }))
+
+    // Cleanup all cached components when this directive is destroyed
+    effects.push(() => {
+        for (const entry of cache.values()) {
+            for (const c of entry.cleanup) if (typeof c === 'function') c()
+            entry.node.remove()
+        }
+        cache.clear()
+    })
+
+    return true
+}
+
+function processKeepAlive(el) {
+    if (el.nodeType !== 1) return false
+    const hasKeepAlive = el.hasAttribute('f-keepAlive')
+    if (hasKeepAlive) el.removeAttribute('f-keepAlive')
+    return hasKeepAlive
+}
+
 export function processShow(el, context, effects) {
     if (el.nodeType !== 1 || !el.hasAttribute('f-show')) return
 
@@ -304,6 +477,7 @@ export function processHtml(el, context, effects) {
         el.innerHTML = String(val ?? '')
     }))
 }
+
 export function processEvents(el, context, effects) {
     if (el.nodeType !== 1 || !el.attributes) return
 
@@ -317,6 +491,39 @@ export function processEvents(el, context, effects) {
 
             el.removeAttribute(attr.name)
 
+            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 // Default
+            }
+
+            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()
@@ -336,14 +543,33 @@ export function processEvents(el, context, effects) {
                     }
                 }
 
-                batch(() => {
-                    const potentialFn = context[expr]
-                    if (typeof potentialFn === 'function' && !potentialFn.isSignal) {
-                        potentialFn(e)
+                // Throttle logic (ensures execution at most once every X ms)
+                if (throttleMs > 0) {
+                    const now = Date.now()
+                    const remaining = throttleMs - (now - lastRun)
+
+                    if (remaining <= 0) {
+                        clearTimeout(throttleTimeoutId)
+                        lastRun = now
+                        executeLogic(e)
                     } else {
-                        evaluateExpression(expr, context, { $event: e }, false)
+                        // Standard throttle with trailing edge support
+                        clearTimeout(throttleTimeoutId)
+                        throttleTimeoutId = setTimeout(() => {
+                            lastRun = Date.now()
+                            executeLogic(e)
+                        }, remaining)
                     }
-                })
+                    return
+                }
+
+                // Debounce logic (waits for X ms of inactivity)
+                if (debounceMs > 0) {
+                    clearTimeout(timeoutId)
+                    timeoutId = setTimeout(() => executeLogic(e), debounceMs)
+                } else {
+                    executeLogic(e)
+                }
             }
 
             const targetNode = modifiers.includes('window') ? window : (modifiers.includes('document') ? document : el)
@@ -356,6 +582,8 @@ export function processEvents(el, context, effects) {
             if (effects) {
                 effects.push(() => {
                     targetNode.removeEventListener(eventName, handler, options)
+                    if (timeoutId) clearTimeout(timeoutId)
+                    if (throttleTimeoutId) clearTimeout(throttleTimeoutId)
                 })
             }
         }

package/framework/core/signal.js

@@ -51,6 +51,64 @@ export function signal(initialValue) {
     }
 
     accessor.isSignal = true
+
+    if (Array.isArray(initialValue)) {
+        accessor.push = (...items) => {
+            const next = [...accessor(), ...items]
+            accessor(next)
+            return next.length
+        }
+
+        accessor.pop = () => {
+            const arr = accessor()
+            if (arr.length === 0) return undefined
+            const item = arr[arr.length - 1]
+            accessor(arr.slice(0, -1))
+            return item
+        }
+
+        accessor.shift = () => {
+            const arr = accessor()
+            if (arr.length === 0) return undefined
+            const item = arr[0]
+            accessor(arr.slice(1))
+            return item
+        }
+
+        accessor.unshift = (...items) => {
+            const next = [...items, ...accessor()]
+            accessor(next)
+            return next.length
+        }
+
+        accessor.splice = (start, deleteCount, ...items) => {
+            const arr = [...accessor()]
+            const removed = arr.splice(start, deleteCount, ...items)
+            accessor(arr)
+            return removed
+        }
+
+        accessor.remove = (predicate) => {
+            accessor(accessor().filter((item, i) => !predicate(item, i)))
+        }
+
+        accessor.clear = () => {
+            accessor([])
+        }
+
+        accessor.sort = (compareFn) => {
+            const next = [...accessor()].sort(compareFn)
+            accessor(next)
+            return accessor
+        }
+
+        accessor.reverse = () => {
+            const next = [...accessor()].reverse()
+            accessor(next)
+            return accessor
+        }
+    }
+
     return accessor
 }
 

package/framework/index.js

@@ -1,8 +1,10 @@
 // ─── Framework Public API ─────────────────────────────────────────────────────
 export { signal, computed, effect, batch, untrack, inspect } from './core/signal.js'
-export { defineComponent, onMount, onUnmount, parseSlots, provide, inject } from './core/component.js'
+export { defineComponent, defineAsyncComponent, onMount, onUnmount, parseSlots, provide, inject, getCurrentInstance } from './core/component.js'
 export { createRouter, navigate, mountOutlet } from './router/router.js'
 export { mountTemplate } from './core/compiler.js'
 
-// Emit is a placeholder - actual emit function is created per component
+export { defineComposable, assertSetupContext } from './core/composable.js'
+export { directive } from './core/directives.js'
+
 export const emit = () => console.warn('[framework] emit() can only be used inside component setup()')

package/framework/types/component.d.ts

@@ -70,3 +70,14 @@ export declare function inject<T>(key: string): T | null
 export declare function defineComponent<TProps = EmptyProps>(
     options: ComponentOptions<TProps>
 ): ComponentFactory<TProps>
+
+export type AsyncComponentLoader<TProps = ComponentProps> = () => Promise<ComponentFactory<TProps> | { default: ComponentFactory<TProps> } | Record<string, any>>
+
+export type AsyncComponentOptions<TProps = ComponentProps> = {
+    loader: AsyncComponentLoader<TProps>
+    loadingComponent?: ComponentFactory<any>
+}
+
+export declare function defineAsyncComponent<TProps = ComponentProps>(
+    loaderOrOptions: AsyncComponentLoader<TProps> | AsyncComponentOptions<TProps>
+): ComponentFactory<TProps>

package/framework/types/composable.d.ts

@@ -0,0 +1,14 @@
+export interface Composable<T = any> {
+    (...args: any[]): T
+    readonly _isComposable: true
+}
+
+declare global {
+    interface Composable<T = any> {
+        (...args: any[]): T
+        readonly _isComposable: true
+    }
+}
+
+export function defineComposable<T>(fn: (...args: any[]) => T): Composable<T>
+export function assertSetupContext(name?: string): any

package/framework/types/directives.d.ts

@@ -25,8 +25,30 @@ export function processIf(
     effects: (() => void)[]
 ): void
 
+export function processIs(
+    root: HTMLElement,
+    context: ComponentResult,
+    components: Record<string, ComponentFactory>,
+    effects: (() => void)[]
+): void
+
 export function processShow(root: HTMLElement, context: ComponentResult, effects: (() => void)[]): void
 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 processCloak(root: HTMLElement): void
+
+export interface DirectiveBinding<V = any> {
+    value: V
+    expression: string
+    arg: string | null
+    modifiers: string[]
+}
+
+export interface DirectiveHooks<V = any> {
+    mounted?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+    updated?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+    unmounted?: (el: HTMLElement, binding: DirectiveBinding<V>) => void
+}
+
+export function directive<V = any>(name: string, hooks: DirectiveHooks<V>): void

package/framework/types/index.d.ts

@@ -1,16 +1,17 @@
-// ─── Fusée Framework Types ───────────────────────────────────────────────────
-
-// Public API
 export * from './signal'
 export * from './component'
+export * from './composable'
 export * from './router'
 export * from './compiler'
+export * from './directives'
 
 declare global {
     type Signal<T = any> = import('./signal').Signal<T>
     type Computed<T = any> = import('./signal').Computed<T>
     type SignalAccessor<T> = import('./signal').SignalAccessor<T>
+    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>
 }
 
-// Re-export as namespace for convenience
 export as namespace Fusee

package/framework/types/signal.d.ts

@@ -6,13 +6,25 @@ export type SignalAccessor<T> = {
     isSignal: boolean;
 }
 
+export type ArraySignalAccessor<T extends any[]> = SignalAccessor<T> & {
+    push(...items: T[number][]): number;
+    pop(): T[number] | undefined;
+    shift(): T[number] | undefined;
+    unshift(...items: T[number][]): number;
+    splice(start: number, deleteCount: number, ...items: T[number][]): T[number][];
+    remove(predicate: (item: T[number], index: number) => boolean): void;
+    clear(): void;
+    sort(compareFn?: (a: T[number], b: T[number]) => number): ArraySignalAccessor<T>;
+    reverse(): ArraySignalAccessor<T>;
+}
+
 export type ComputedAccessor<T> = {
     (): T;
     isSignal: boolean;
     readonly: true;
 }
 
-export type Signal<T = any> = SignalAccessor<T>
+export type Signal<T = any> = T extends any[] ? ArraySignalAccessor<T> : SignalAccessor<T>
 export type Computed<T = any> = ComputedAccessor<T>
 
 type EffectRunner = {
@@ -20,7 +32,8 @@ type EffectRunner = {
     deps: Set<Set<EffectRunner>>;
 }
 
-export declare function signal<T>(initialValue: T): Signal<T>
+export declare function signal<T extends any[]>(initialValue: T): ArraySignalAccessor<T>
+export declare function signal<T>(initialValue: T): SignalAccessor<T>
 export declare function effect(fn: () => void): () => void
 export declare function computed<T>(fn: () => T): Computed<T>
 export declare function batch<T>(fn: () => T): T

package/index.html

@@ -160,6 +160,139 @@
       opacity: 0.3;
       cursor: not-allowed;
     }
+
+    /* ── Composables demo ──────────────────────────────────────────── */
+    .demo-card {
+      background: #13131d;
+      border: 1px solid #2a2a3a;
+      border-radius: 12px;
+      padding: 1.5rem;
+      margin-bottom: 1.5rem;
+    }
+
+    .demo-card h2 {
+      font-size: 1rem;
+      font-weight: 600;
+      color: #e8e8f0;
+      margin-bottom: 0.35rem;
+    }
+
+    .demo-desc {
+      font-size: 0.8rem;
+      color: #555 !important;
+      margin-bottom: 1rem !important;
+    }
+
+    .counter-display {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      margin-bottom: 1rem;
+    }
+
+    .big-num {
+      font-size: 3.5rem;
+      font-weight: 700;
+      line-height: 1;
+      transition: color 0.2s;
+    }
+
+    .big-num.even {
+      color: #8b8bff;
+    }
+
+    .big-num.odd {
+      color: #ff3333;
+    }
+
+    .derived-label {
+      font-size: 0.8rem;
+      color: #555;
+      margin-top: 0.25rem;
+    }
+
+    .btn-row {
+      display: flex;
+      gap: 0.5rem;
+      justify-content: center;
+      margin-bottom: 0.75rem;
+    }
+
+    .cmp-btn {
+      padding: 0.45rem 1.1rem;
+      border-radius: 6px;
+      border: 1px solid #2a2a3a;
+      background: #0f0f1a;
+      color: #e8e8f0;
+      cursor: pointer;
+      font-size: 1rem;
+      transition: background 0.15s;
+    }
+
+    .cmp-btn:hover {
+      background: #1f1f30;
+    }
+
+    .cmp-btn.plus {
+      border-color: #8b8bff;
+      color: #8b8bff;
+    }
+
+    .cmp-btn.minus {
+      border-color: #ff3333;
+      color: #ff3333;
+    }
+
+    .cmp-btn.reset {
+      border-color: #555;
+      color: #888;
+    }
+
+    .badge {
+      display: inline-block;
+      padding: 0.2rem 0.65rem;
+      border-radius: 999px;
+      font-size: 0.75rem;
+      font-weight: 600;
+    }
+
+    .badge-blue {
+      background: rgba(139, 139, 255, 0.15);
+      color: #8b8bff;
+    }
+
+    .badge-red {
+      background: rgba(255, 51, 51, 0.12);
+      color: #ff3333;
+    }
+
+    .mouse-display {
+      display: flex;
+      gap: 2rem;
+      font-size: 1.1rem;
+      color: #aaa;
+      margin-bottom: 0.5rem;
+    }
+
+    .mouse-display strong {
+      color: #e8e8f0;
+    }
+
+    .cmp-input {
+      width: 100%;
+      padding: 0.5rem 0.75rem;
+      background: #0f0f1a;
+      border: 1px solid #2a2a3a;
+      border-radius: 6px;
+      color: #e8e8f0;
+      font-size: 0.95rem;
+      outline: none;
+      transition: border-color 0.15s;
+    }
+
+    .cmp-input:focus {
+      border-color: #8b8bff;
+    }
   </style>
 </head>
 
@@ -167,10 +300,12 @@
   <nav>
     <a href="#/">Home</a>
     <a href="#/about">About</a>
-    <a href="#/test-for">Test f-for</a>
+    <a href="#/test-for">Loops Test</a>
+    <a href="#/dynamic" style="color: #ec4899;">Dynamic Components</a>
+    <a href="#/composables" style="color: #34d399;">Composables</a>
   </nav>
   <div id="app"></div>
-  <script type="module" src="./app/main.js"></script>
+  <script type="module" src="./app/main.ts"></script>
 </body>
 
 </html>

package/package.json

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