@saolabs/client 1.0.0

package/src/core/elements/BlockOutlet.ts

@@ -0,0 +1,83 @@
+import type { BlockOutletInterface } from "../contracts/BlockInterface";
+import { InitMode } from "../contracts/common";
+import type { HtmlInterface } from "../contracts/ElementInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { generateUUID } from "../hellpers/utils";
+import markerRegistry  from "../services/MarkerRegistry";
+import type { OneObjectType } from "../types/utils";
+
+export class BlockOutlet implements BlockOutletInterface {
+    oneType: OneObjectType = 'BlockOutlet';
+    id: string;
+    name: string;
+    openTag: Comment;
+    closeTag: Comment;
+    parent: HtmlInterface | null = null;
+    parentElement: HtmlInterface | null = null;
+    ctx: ViewControllerInterface;
+    initMode: InitMode = 'create';
+    constructor({ ctx, parentElement = null, name, id = null, initMode = 'create' }: { ctx: ViewControllerInterface, parentElement?: HtmlInterface | null, name: string, id?: string | null, initMode?: InitMode }) {
+        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        this.ctx = ctx;
+        this.name = name;
+        this.parent = parentElement;
+        this.parentElement = parentElement;
+        this.initMode = initMode;
+
+        markerRegistry.register('blockoutlet', this.id, { name, viewId: ctx.viewId }); // Register this outlet in the MarkerRegistry
+
+        this.openTag = markerRegistry.createMarkerStart('blockoutlet', this.id);
+        this.closeTag = markerRegistry.createMarkerEnd('blockoutlet', this.id);
+    }
+
+    hydrate(): void {
+        // Hydration logic if needed (e.g. reattach event listeners)
+    }
+
+    render(): void {
+        if (!this.parentElement || !this.parentElement.element) return;
+
+        const parentEl = this.parentElement.element;
+
+        // Place markers
+        parentEl.appendChild(this.openTag);
+        // Register this outlet in the MarkerRegistry for block mounting
+        parentEl.appendChild(this.closeTag);
+
+    }
+
+    destroy(): void {
+        // Remove markers from DOM
+        this.openTag.remove();
+        this.closeTag.remove();
+    }
+
+    start(): void {
+        // Placeholder for any setup needed when the outlet becomes active
+    }
+
+    stop(): void {
+        // Placeholder for any cleanup needed when the outlet becomes inactive
+    }
+
+    setParentElement(parentElement: HtmlInterface | null): void {
+        this.parent = parentElement;
+        this.parentElement = parentElement;
+    }
+
+    get isOneElement(): boolean {
+        return true;
+    }
+
+    set isOneElement(value: boolean) {
+        // No-op setter to satisfy OneElement interface
+    }
+
+    get isOneBlockOutlet(): boolean {
+        return true;
+    }
+
+    set isOneBlockOutlet(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for BlockOutlet elements
+    }
+}

package/src/core/elements/Component.ts

@@ -0,0 +1,114 @@
+import { InitMode, InitModes } from "../contracts/common";
+import { ComponentInterface } from "../contracts/ComponentInterface";
+import { HtmlInterface, OneChildrenFactory } from "../contracts/ElementInterface";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { ViewInterface } from "../contracts/ViewInterface";
+import { generateUUID } from "../hellpers/utils";
+import { OneObjectType } from "../types/utils";
+
+export class Component implements ComponentInterface {
+    oneType: OneObjectType = 'Component';
+    ctx: ViewControllerInterface;
+    parent: HtmlInterface | null;
+    domChildren: Node[] = []; // For compatibility with HtmlInterface; Component itself doesn't have a single root element
+    stateKeys: string[];
+    data: Record<string, any>;
+    openTag: Comment;
+    closeTag: Comment;
+    viewRef: ViewInterface | null = null;
+    id: string;
+    path: string | null = null; // For dynamic imports
+    type: 'default' | 'if' | 'when' = 'default';
+    condition: {stateKeys: string[], checker: () => any} | null = null; // For 'when' type components
+    initMode: InitMode = InitModes.CREATE; // Default initialization mode
+    subscribeFn: () => void = () => {};
+    unsubscribeFn: () => void = () => {};
+    dataFactory: ((parentElement: HtmlInterface | null) => Record<string, any>) | null = null; 
+
+    constructor({
+        ctx,
+        parent = null,
+        id = null,
+        stateKeys = [],
+        data = {},
+        dataFactory = null,
+        path = null,
+        type = 'default',
+        condition = null,
+        initMode = InitModes.CREATE,
+    }: {
+        ctx: ViewControllerInterface;
+        parent?: HtmlInterface | null;
+        id?: string | null;
+        stateKeys?: string[];
+        data?: Record<string, any>;
+        dataFactory?: ((parentElement: HtmlInterface | null) => Record<string, any>) | null;
+        path?: string | null;
+        type?: 'default' | 'if' | 'when';
+        condition?: {stateKeys: string[], checker: () => any} | null;
+        initMode?: InitMode;
+    }) {
+        this.ctx = ctx;
+        this.parent = parent;
+        this.stateKeys = stateKeys;
+        this.data = data || {};
+        this.openTag = document.createComment(`component-start`);
+        this.closeTag = document.createComment(`component-end`);
+        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        this.dataFactory = dataFactory;
+        this.path = path;
+        this.type = type;
+        this.condition = condition;
+        this.initMode = initMode ?? InitModes.CREATE;
+    }
+
+    mergeData(newData: Record<string, any>): void {
+        this.data = { ...this.data, ...newData };
+    }
+
+    setDataFactory(factory: (parentElement: HtmlInterface | null) => Record<string, any>) {
+        this.dataFactory = factory;
+    }
+    setCondition(condition: {stateKeys: string[], checker: () => any}) {
+        this.condition = condition;
+    }
+    setStateKeys(stateKeys: string[]) {
+        this.stateKeys = stateKeys;
+    }
+    setParentElement(parent: HtmlInterface | null): void {
+        this.parent = parent;
+    }
+
+    setView(view: ViewInterface) {
+        this.viewRef = view;
+    }
+    setParent(parent: HtmlInterface | null): void {
+        this.parent = parent;
+    }
+
+    start(): void {
+    }
+
+    stop(): void {
+    }
+
+    render(): void {
+        // To be implemented by specific components
+    }
+
+    destroy(): void {
+        // To be implemented by specific components
+    }
+    get isOneElement(): boolean {
+        return true;
+    }
+    set isOneElement(value: boolean) {
+        // No-op, just for type compatibility
+    }
+    get isOneComponent(): boolean {
+        return true;
+    }
+    set isOneComponent(value: boolean) {
+        // No-op, just for type compatibility
+    }
+}

package/src/core/elements/ElementManager.ts

@@ -0,0 +1,48 @@
+import type { BlockRenderFactory } from "../contracts/BlockInterface";
+import type { HtmlInterface, OneElementConfig, OneChildrenFactory } from "../contracts/ElementInterface";
+import type { ReactiveRenderFn } from "../contracts/ReactiveInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { Html } from "./Html";
+import { TextElement } from "./TextElement";
+import { Reactive } from "./Reactive";
+import { Fragment } from "./Fragment";
+import { Block } from "./Block";
+
+/**
+ * OneElementManager — factory/registry for creating One elements.
+ * 
+ * Provides shorthand functions so compiled output stays clean:
+ *   oem.h(ctx, parent, 'div', config, children)  → Html
+ *   oem.t('Hello')                                → TextElement
+ *   oem.r(ctx, parent, renderFn)                  → Reactive
+ *   oem.f(ctx, parent, children)                  → Fragment
+ *   oem.b(ctx, parent, 'content')                 → Block
+ */
+export class ElementManagerService {
+    /** Custom element factories (for user-defined components) */
+    private factories: Map<string, (...args: any[]) => any> = new Map();
+
+    // ─── Element Shorthand Factories ────────────────────────────
+
+
+
+    // ─── Custom Component Registry ─────────────────────────────
+
+    /** Register a custom component factory */
+    set(name: string, factory: (...args: any[]) => any): void {
+        this.factories.set(name, factory);
+    }
+
+    /** Get a custom component factory */
+    get(name: string): ((...args: any[]) => any) | undefined {
+        return this.factories.get(name);
+    }
+
+    /** Check if a custom component is registered */
+    has(name: string): boolean {
+        return this.factories.has(name);
+    }
+}
+
+export const ElementManager = new ElementManagerService();
+export default ElementManager;

package/src/core/elements/Fragment.ts

@@ -0,0 +1,168 @@
+import { InitMode, InitModes } from "../contracts/common";
+import type { FragmentInterface, HtmlInterface, OneChildrenFactory, OneChildrenFactoryOutput, OneElementChildren } from "../contracts/ElementInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { generateUUID } from "../hellpers/utils";
+import type { OneObjectType } from "../types/utils";
+
+/**
+ * Fragment — renders multiple root nodes into a parent without a wrapping tag.
+ * 
+ * Use case: when a ViewController's render() returns multiple sibling elements
+ * (e.g. `<h1>` + `<p>` + `<div>`) without a single root wrapper.
+ * 
+ * Fragment uses open/close Comment markers to track its region in the DOM,
+ * similar to Reactive but without the reactivity overhead.
+ */
+export class Fragment implements FragmentInterface {
+    oneType: OneObjectType = 'Fragment';
+    public parent: HtmlInterface | null;
+    public nodes: Node[] = [];
+    /** Tracked child element wrappers (Html, Output, Reactive, TextElement, etc.) */
+    public children: OneElementChildren = [];
+    private ctx: ViewControllerInterface;
+    private childrenFactory: OneChildrenFactory;
+    public openTag: Comment;
+    public closeTag: Comment;
+    public id: string; // Unique ID for debugging and marker registry
+    public initMode: InitMode = InitModes.CREATE;
+
+    domChildren: Node[] = []; // For compatibility with HtmlInterface; Fragment itself doesn't have a single root element
+
+    constructor({
+        ctx, 
+        id = null, 
+        initMode = InitModes.CREATE, 
+        parentElement = null, 
+        childrenFactory
+    }: {
+        ctx: ViewControllerInterface, 
+        id?: string | null, 
+        initMode?: InitMode, 
+        parentElement?: HtmlInterface | null, 
+        childrenFactory: OneChildrenFactory
+    }) {
+        this.ctx = ctx;
+        this.parent = parentElement;
+        this.childrenFactory = childrenFactory;
+        this.openTag = document.createComment('fragment-start');
+        this.closeTag = document.createComment('fragment-end');
+        this.id = `${ctx.viewId}-${id ?? generateUUID(10)}`; // Unique ID for debugging
+        this.initMode = initMode;
+    }
+    setParentElement(parent: HtmlInterface | null): void {
+        this.parent = parent;
+    }
+    render(): void {
+        if (!this.parent || !this.parent.element) return;
+
+        const parentEl = this.parent.element;
+
+        // Place start marker
+        parentEl.appendChild(this.openTag);
+
+        // Build children — compiled output uses (parentElement) => [...] signature
+        const output: OneChildrenFactoryOutput = this.childrenFactory(this.parent);
+
+        for (const child of output) {
+            if (typeof child === 'string' || typeof child === 'number') {
+                const textNode = document.createTextNode(String(child));
+                parentEl.appendChild(textNode);
+                this.nodes.push(textNode);
+            } else if (child && typeof child === 'object') {
+                if ('element' in child) {
+                    // HtmlInterface, TextInterface — append their DOM element
+                    parentEl.appendChild(child.element);
+                    this.nodes.push(child.element);
+                    this.children.push(child);
+                    child.render();
+                } else if ('openTag' in child) {
+                    // Reactive, nested Fragment, Output — they self-append markers
+                    if ('parent' in child) {
+                        (child as any).parent = this.parent;
+                    }
+                    if ('parentElement' in child) {
+                        (child as any).parentElement = this.parent;
+                    }
+                    this.children.push(child);
+                    child.render();
+                }
+            }
+        }
+
+        // Place end marker
+        parentEl.appendChild(this.closeTag);
+    }
+
+    setChildrenFactory(factory: OneChildrenFactory): void {
+        this.childrenFactory = factory;
+    }
+
+    /** Hydrate lifecycle — reattach event listeners or perform other setup */
+
+    hydrate(): void {
+        for (const child of this.children) {
+            if ('hydrate' in child && typeof (child as any).hydrate === 'function') {
+                (child as any).hydrate();
+            }
+        }
+    }
+
+    /** Start lifecycle — recursively activate children's reactive subscriptions */
+    start(): void {
+        for (const child of this.children) {
+            if ('start' in child && typeof (child as any).start === 'function') {
+                (child as any).start();
+            }
+        }
+    }
+
+    /** Stop lifecycle — recursively deactivate children's reactive subscriptions */
+    stop(): void {
+        for (const child of this.children) {
+            if ('stop' in child && typeof (child as any).stop === 'function') {
+                (child as any).stop();
+            }
+        }
+    }
+
+    /** Remove all nodes between markers from the DOM */
+    clear(): void {
+        // Destroy managed children first
+        for (const child of this.children) {
+            if ('destroy' in child && typeof child.destroy === 'function') {
+                child.destroy();
+            }
+        }
+        this.children = [];
+
+        // Remove remaining DOM nodes between markers
+        let current = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next = current.nextSibling;
+            current.remove();
+            current = next;
+        }
+        this.nodes = [];
+    }
+
+    destroy(): void {
+        this.clear();
+        this.openTag.remove();
+        this.closeTag.remove();
+        this.parent = null;
+    }
+
+    get isOneElement(): boolean {
+        return true;
+    }
+    set isOneElement(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for Fragment elements
+    }
+
+    get isOneFragment(): boolean {
+        return true;
+    }
+    set isOneFragment(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for Fragment elements
+    }
+}