@saolabs/client 1.0.0

package/src/core/routers/index.ts

@@ -0,0 +1,2 @@
+export { Router, ActiveRoute, useRoute, useParams, useQuery } from './Router';
+export type { RouteDefinition, Route, RouteMatch, RouterConfig, NavigationGuard, AfterNavigationHook } from './Router';

package/src/core/services/BlockManager.ts

@@ -0,0 +1,210 @@
+import type { BlockInterface, BlockManagerInterface, BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface";
+import type { HtmlInterface } from "../contracts/ElementInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { Block } from "../elements/Block";
+
+/**
+ * BlockManager — manages all block slots in a layout view.
+ * 
+ * Responsibilities:
+ *   - Register block slots declared by @useBlock(name) in layout
+ *   - Track which blocks exist and their active state
+ *   - Coordinate mounting/unmounting when router navigates
+ *   - Provide block state info (active viewId, cached views, etc.)
+ * 
+ * Lifecycle:
+ *   1. Layout view creates BlockManager
+ *   2. Layout's render() calls manager.register('content', parentEl) for each @useBlock
+ *   3. Router calls manager.mount('content', viewId, factory) on navigation
+ *   4. On browser back/forward, router calls mount with previous viewId
+ *      → Block restores cached DOM instead of re-rendering
+ *   5. When layout deactivates, manager.unmountAll() hides all content
+ */
+export class BlockManagerService implements BlockManagerInterface {
+    blocks: Map<string, BlockInterface> = new Map();
+    blockOutlets: Map<string, BlockOutletInterface> = new Map();
+    activeBlocks: Map<string, BlockInterface> = new Map();
+    listeners: Map<string, ((block: BlockInterface) => void)[]> = new Map();
+    
+    /** Tracks children mounted into each outlet for cleanup */
+    private mountedChildren: Map<string, any[]> = new Map();
+
+    constructor() {}
+
+    add(block: BlockInterface): void {
+        const key = block.name + (block.viewId ?? '');
+        if (!this.blocks.has(key)) {
+            this.blocks.set(key, block);
+        }
+        this.active(block.name, block.viewId ?? '');
+    }
+
+    active(name: string, viewId: string): void {
+        const key = name + viewId;
+        const block = this.blocks.get(key);
+        if (block) {
+            this.activeBlocks.set(name, block);
+            const listeners = this.listeners.get(name);
+            if (listeners) {
+                listeners.forEach(fn => fn(block));
+            }
+        }
+    }
+
+    subscribe(name: string, callback: (block: BlockInterface) => void): () => void {
+        if (!this.listeners.has(name)) {
+            this.listeners.set(name, []);
+        }
+        this.listeners.get(name)!.push(callback);
+        return () => this.unsubscribe(name, callback);
+    }
+
+    unsubscribe(name: string, callback?: (block: BlockInterface) => void): void {
+        if (!this.listeners.has(name)) return;
+        if (!callback) {
+            this.listeners.delete(name);
+            return;
+        }
+        const listeners = this.listeners.get(name);
+        if (listeners) {
+            this.listeners.set(name, listeners.filter(fn => fn !== callback));
+            if (this.listeners.get(name)!.length === 0) {
+                this.listeners.delete(name);
+            }
+        }
+    }
+
+    addOutlet(key: string, outlet: BlockOutletInterface): void {
+        if (!this.blockOutlets.has(key)) {
+            this.blockOutlets.set(key, outlet);
+        }
+    }
+
+    hasOutlet(key: string): boolean {
+        return this.blockOutlets.has(key);
+    }
+
+    getOutlet(key: string): BlockOutletInterface | undefined {
+        return this.blockOutlets.get(key);
+    }
+
+    /**
+     * Mount all registered blocks into their corresponding outlets.
+     * Called by ViewManager after layout + page views are both rendered.
+     * 
+     * Iterates activeBlocks by name, finds matching outlet (keyed by
+     * viewId:blockName), and inserts block content between outlet markers.
+     */
+    mountAll(): void {
+        for (const [name, block] of this.activeBlocks) {
+            // Try to find an outlet that matches this block name
+            for (const [outletKey, outlet] of this.blockOutlets) {
+                if (outletKey.endsWith(`:${name}`) || outlet.name === name) {
+                    if (block.contentRenderFactory) {
+                        this.mountBlockIntoOutlet(block, outlet);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+
+    /**
+     * Mount a single block's content into an outlet.
+     * Content is rendered and inserted between the outlet's open/close markers.
+     */
+    private mountBlockIntoOutlet(block: BlockInterface, outlet: BlockOutletInterface): void {
+        if (!outlet.parentElement?.element) return;
+
+        const parentEl = outlet.parentElement.element;
+        const children: any[] = [];
+
+        // Render block content using the factory
+        const content = block.contentRenderFactory!(block.ctx as any);
+
+        if (!Array.isArray(content)) return;
+
+        // Insert each child between outlet markers
+        for (const child of content) {
+            if (typeof child === 'string' || typeof child === 'number') {
+                const textNode = document.createTextNode(String(child));
+                parentEl.insertBefore(textNode, outlet.closeTag);
+            } else if (child && typeof child === 'object') {
+                if ('element' in child) {
+                    // HtmlInterface, TextInterface
+                    parentEl.insertBefore(child.element, outlet.closeTag);
+                    children.push(child);
+                    child.render();
+                } else if ('openTag' in child) {
+                    // Reactive, Fragment, Output — set parent, render
+                    if ('parent' in child) {
+                        (child as any).parent = outlet.parentElement;
+                    }
+                    if ('parentElement' in child) {
+                        (child as any).parentElement = outlet.parentElement;
+                    }
+                    children.push(child);
+                    child.render();
+                }
+            }
+        }
+
+        // Track mounted children for cleanup
+        this.mountedChildren.set(outlet.name, children);
+    }
+
+    /**
+     * Clear content from a specific outlet (for page swap).
+     * Removes all DOM nodes between a named outlet's markers.
+     */
+    clearOutlet(name: string): void {
+        // Find outlet by name
+        for (const [key, outlet] of this.blockOutlets) {
+            if (outlet.name === name) {
+                // Destroy tracked children first
+                const children = this.mountedChildren.get(name) || [];
+                if (children) {
+                    for (const child of children) {
+                        if ('destroy' in child && typeof child.destroy === 'function') {
+                            child.destroy();
+                        }
+                    }
+                    this.mountedChildren.delete(name);
+                }
+
+                // Remove any remaining DOM nodes between markers
+                let current = outlet.openTag.nextSibling;
+                while (current && current !== outlet.closeTag) {
+                    const next = current.nextSibling;
+                    current.remove();
+                    current = next;
+                }
+                break;
+            }
+        }
+    }
+
+    /**
+     * Clear all outlets (for full layout teardown).
+     */
+    clearAllOutlets(): void {
+        for (const [key, outlet] of this.blockOutlets) {
+            this.clearOutlet(outlet.name);
+        }
+    }
+
+    /**
+     * Full cleanup — destroy all blocks, outlets, listeners.
+     */
+    destroy(): void {
+        this.clearAllOutlets();
+        this.blocks.clear();
+        this.blockOutlets.clear();
+        this.activeBlocks.clear();
+        this.listeners.clear();
+        this.mountedChildren.clear();
+    }
+}
+
+export const BlockManager = new BlockManagerService();
+export default BlockManager;

package/src/core/services/DomService.ts

@@ -0,0 +1,26 @@
+import { app } from "../hellpers/app";
+
+
+export class DomService {
+    private container: HTMLTemplateElement;
+    constructor() {
+        this.container = document.createElement('template');
+    }
+    
+    parse(html: string): Node[]{
+        this.container.innerHTML = html;
+        const content = this.container.content;
+        this.container.innerHTML = ''; // Clear template content to free memory
+        return Array.from(content.childNodes);
+    }
+    create(tagName: string, options?: ElementCreationOptions): HTMLElement {
+        return document.createElement(tagName, options);
+    }
+
+
+}
+
+
+
+export const Dom = app(DomService);
+export default Dom;

package/src/core/services/EventService.ts

@@ -0,0 +1,266 @@
+/**
+ * EventService — Pub/Sub event bus.
+ *
+ * Supports:
+ *   - Single event:       on('click', fn)
+ *   - Multiple events:    on(['click', 'hover'], fn)  — fn called once per emit batch
+ *   - Space-separated:    on('click hover', fn)
+ *   - Object syntax:      on({ click: fn1, hover: fn2 })
+ *   - Once:               once('click', fn)
+ *
+ * Not a singleton — register via DI:
+ *   app.singleton('event', EventService);
+ *   app.make<EventService>('event').on('route:change', fn);
+ */
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export type EventCallback = (...args: any[]) => void;
+
+interface SingleListener {
+    callback: EventCallback;
+    once: boolean;
+}
+
+interface MultiListener {
+    events: Set<string>;
+    callback: EventCallback;
+    once: boolean;
+    called: boolean;
+}
+
+// ─── EventService ───────────────────────────────────────────────
+
+export class EventService {
+
+    static instances: Map<any, EventService> = new Map();
+
+    static getInstance(key: any = 'default'): EventService {
+        if (!EventService.instances.has(key)) {
+            EventService.instances.set(key, new EventService());
+        }
+        return EventService.instances.get(key)!;
+    }
+
+    static instance(key: any = 'default'): EventService {
+        return EventService.getInstance(key);
+    }
+
+    static removeInstance(key: any = 'default'): void {
+        EventService.instances.delete(key);
+    }
+
+
+    private listeners = new Map<string, SingleListener[]>();
+    private multiListeners: MultiListener[] = [];
+
+    // ─── Subscribe ──────────────────────────────────────────────
+
+    /**
+     * Subscribe to events. Returns unsubscribe function.
+     *
+     * @example
+     * event.on('save', (data) => { ... });
+     * event.on(['save', 'update'], (data) => { ... });
+     * event.on('save update', (data) => { ... });
+     * event.on({ save: fn1, update: fn2 });
+     */
+    on(
+        event: string | string[] | Record<string, EventCallback>,
+        callback?: EventCallback | boolean,
+        once: boolean = false,
+    ): () => void {
+        // Object syntax: on({ click: fn1, hover: fn2 })
+        if (typeof event === 'object' && !Array.isArray(event)) {
+            const unsubs: Array<() => void> = [];
+            for (const [name, fn] of Object.entries(event)) {
+                if (typeof fn === 'function') {
+                    unsubs.push(this.on(name, fn, callback === true));
+                }
+            }
+            return () => unsubs.forEach((u) => u());
+        }
+
+        // Space-separated → array
+        if (typeof event === 'string' && event.includes(' ')) {
+            event = event.split(/\s+/).filter(Boolean);
+        }
+
+        // Array of events — multi-listener (fires once per emit batch)
+        if (Array.isArray(event)) {
+            const events = new Set(event.filter((e) => typeof e === 'string'));
+            if (events.size === 0) return () => { };
+
+            const listener: MultiListener = {
+                events,
+                callback: callback as EventCallback,
+                once,
+                called: false,
+            };
+            this.multiListeners.push(listener);
+
+            return () => {
+                const idx = this.multiListeners.indexOf(listener);
+                if (idx !== -1) this.multiListeners.splice(idx, 1);
+            };
+        }
+
+        // Single event
+        if (typeof event !== 'string' || typeof callback !== 'function') return () => { };
+
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+
+        const listener: SingleListener = { callback, once };
+        this.listeners.get(event)!.push(listener);
+
+        return () => this.off(event as string, callback as EventCallback);
+    }
+
+    /** Subscribe once — auto-unsubscribe after first call */
+    once(
+        event: string | string[] | Record<string, EventCallback>,
+        callback?: EventCallback,
+    ): () => void {
+        return this.on(event, callback, true);
+    }
+
+    // ─── Unsubscribe ────────────────────────────────────────────
+
+    /**
+     * Unsubscribe from events.
+     *
+     * @example
+     * event.off('save');         // remove all listeners for 'save'
+     * event.off('save', fn);    // remove specific listener
+     * event.off(['save', 'update']);
+     * event.off({ save: fn1 });
+     */
+    off(
+        event: string | string[] | Record<string, EventCallback>,
+        callback?: EventCallback,
+    ): void {
+        // Object syntax
+        if (typeof event === 'object' && !Array.isArray(event)) {
+            for (const [name, fn] of Object.entries(event)) {
+                this.off(name, fn);
+            }
+            return;
+        }
+
+        // Space-separated
+        if (typeof event === 'string' && event.includes(' ')) {
+            event = event.split(/\s+/).filter(Boolean);
+        }
+
+        // Array
+        if (Array.isArray(event)) {
+            const eventSet = new Set(event);
+            this.multiListeners = this.multiListeners.filter((l) => {
+                if (callback && l.callback !== callback) return true;
+                return ![...l.events].some((e) => eventSet.has(e));
+            });
+            event.forEach((e) => this.off(e, callback));
+            return;
+        }
+
+        // Single event
+        if (typeof event !== 'string') return;
+
+        if (!callback) {
+            this.listeners.delete(event);
+        } else {
+            const list = this.listeners.get(event);
+            if (list) {
+                const filtered = list.filter((l) => l.callback !== callback);
+                filtered.length > 0
+                    ? this.listeners.set(event, filtered)
+                    : this.listeners.delete(event);
+            }
+        }
+    }
+
+    // ─── Emit ───────────────────────────────────────────────────
+
+    /** Emit event with arguments */
+    emit(event: string, ...args: any[]): void {
+        // Reset multi-listener flags
+        this.multiListeners.forEach((l) => (l.called = false));
+
+        // Single listeners
+        const list = this.listeners.get(event);
+        if (list) {
+            const snapshot = [...list];
+            const toRemove: SingleListener[] = [];
+
+            for (const listener of snapshot) {
+                try {
+                    listener.callback(...args);
+                } catch (err) {
+                    console.error(`[EventService] Error in listener for "${event}":`, err);
+                }
+                if (listener.once) toRemove.push(listener);
+            }
+
+            if (toRemove.length) {
+                this.listeners.set(
+                    event,
+                    list.filter((l) => !toRemove.includes(l)),
+                );
+            }
+        }
+
+        // Multi listeners
+        const multiToRemove: MultiListener[] = [];
+        for (const listener of this.multiListeners) {
+            if (listener.events.has(event) && !listener.called) {
+                listener.called = true;
+                try {
+                    listener.callback(...args);
+                } catch (err) {
+                    console.error(`[EventService] Error in multi-event listener:`, err);
+                }
+                if (listener.once) multiToRemove.push(listener);
+            }
+        }
+
+        if (multiToRemove.length) {
+            this.multiListeners = this.multiListeners.filter((l) => !multiToRemove.includes(l));
+        }
+    }
+
+    // ─── Utility ────────────────────────────────────────────────
+
+    /** Remove all listeners */
+    clear(): void {
+        this.listeners.clear();
+        this.multiListeners = [];
+    }
+
+    /** Listener count for a specific event */
+    listenerCount(event: string): number {
+        const single = this.listeners.get(event)?.length ?? 0;
+        const multi = this.multiListeners.filter((l) => l.events.has(event)).length;
+        return single + multi;
+    }
+
+    /** Check if event has listeners */
+    hasListeners(event: string): boolean {
+        return this.listenerCount(event) > 0;
+    }
+
+    /** Get all registered event names */
+    eventNames(): string[] {
+        const names = new Set<string>(this.listeners.keys());
+        for (const l of this.multiListeners) {
+            l.events.forEach((e) => names.add(e));
+        }
+        return [...names];
+    }
+
+    /** Destroy — alias for clear */
+    destroy(): void {
+        this.clear();
+    }
+}