@saolabs/client 1.0.0

package/src/core/elements/Reactive.ts

@@ -0,0 +1,253 @@
+import { InitMode, InitModes } from "../contracts/common";
+import type { HtmlInterface, OneChildrenFactoryOutput, OneElementChildren } from "../contracts/ElementInterface";
+import type { ReactiveInterface, ReactiveChildrenFactory, ReactiveRenderFn } from "../contracts/ReactiveInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { generateUUID } from "../hellpers/utils";
+import markerRegistry from "../services/MarkerRegistry";
+import type { OneObjectType } from "../types/utils";
+
+/**
+ * Reactive — a region in the DOM bounded by comment markers that 
+ * can re-render its content when reactive dependencies change.
+ * 
+ * Use cases:
+ *   - o-if / o-show conditional rendering
+ *   - o-for list rendering  
+ *   - @useBlock(name) slot mounting
+ *   - Any expression binding that affects DOM structure
+ * 
+ * The open/close comment markers stay in place; only the content
+ * between them is replaced on re-render. This avoids the need to
+ * scan/diff the entire DOM tree.
+ */
+export class Reactive implements ReactiveInterface {
+    static class = 'Reactive';
+    oneType: OneObjectType = 'Reactive';
+    public id: string; // Unique ID for debugging and marker registry
+    public type: string; // Custom type for different reactive behaviors (e.g. 'if', 'list')
+    public openTag: Comment;
+    public closeTag: Comment;
+    public parentElement: HtmlInterface | null;
+    public parentReactive: ReactiveInterface | null;
+    public parent: HtmlInterface | null = null; // Alias for parentReactive to satisfy OneNodeInterface
+
+    public ctx: ViewControllerInterface;
+    public childrenFactory: ReactiveChildrenFactory;
+    public children: OneElementChildren = [];
+    private mounted: boolean = false;
+    public stateKeys: string[];
+    public unsubscribe: () => void = () => {};
+    private _isStarted = false;
+
+
+
+    domChildren: Node[] = []; // For compatibility with HtmlInterface; Reactive itself doesn't have a single root element
+    initMode: InitMode = InitModes.CREATE;
+    constructor({
+        type = 'reactive',
+        id = null,
+        ctx,
+        parentElement = null,
+        parentReactive = null,
+        stateKeys = [],
+        childrenFactory = () => [],
+        initMode = InitModes.CREATE,
+    }: {
+        id?: string | null;
+        type?: string;
+        ctx: ViewControllerInterface;
+        parentElement?: HtmlInterface | null;
+        parentReactive?: ReactiveInterface | null;
+        stateKeys?: string[];
+        childrenFactory: ReactiveChildrenFactory;
+        initMode?: InitMode;
+    }) {
+        this.ctx = ctx;
+        this.parentElement = parentElement;
+        this.parentReactive = parentReactive;
+        this.id = `${ctx.viewId}-${id || generateUUID(5)}`;
+        this.type = type;
+        this.childrenFactory = childrenFactory;
+        this.stateKeys = stateKeys;
+        this.initMode = initMode;
+        markerRegistry.register('reactive', this.id, {
+            type: this.type,
+            stateKeys: this.stateKeys,
+            viewID: this.ctx.viewId,
+        });
+
+        this.openTag = markerRegistry.createMarkerStart('reactive', this.id);
+        this.closeTag = markerRegistry.createMarkerEnd('reactive', this.id);
+    }
+
+    setParentElement(parent: HtmlInterface | null): void {
+        this.parentElement = parent;
+    }
+
+    setChildrenFactory(factory: ReactiveChildrenFactory): void {
+        this.childrenFactory = factory;
+    }
+
+    setStateKeys(stateKeys: string[]): void {
+        this.stateKeys = stateKeys;
+        // If already started, we need to resubscribe with new keys
+        if (this._isStarted) {
+            this.stop();
+            this.start();
+        }
+    }
+
+    /** Mount markers into parent and render content */
+    render(): void {
+        const target = this.getInsertionTarget();
+        if (!target) return;
+
+        if (!this.mounted) {
+            // First render: place markers
+            if (this.parentReactive) {
+                // Insert before the parent's close marker
+                target.insertBefore(this.openTag, this.parentReactive.closeTag);
+                target.insertBefore(this.closeTag, this.parentReactive.closeTag);
+            } else {
+                target.appendChild(this.openTag);
+                target.appendChild(this.closeTag);
+            }
+            this.mounted = true;
+        } else {
+            // Re-render: clear existing content between markers
+            this.clearContent();
+        }
+
+        // Produce children
+        const output: OneChildrenFactoryOutput = this.childrenFactory(this, this.parentElement);
+
+        // Insert children between markers
+        for (const child of output) {
+            if (typeof child === 'string' || typeof child === 'number') {
+                const textNode = document.createTextNode(String(child));
+                this.insertBeforeClose(textNode);
+                this.children.push(textNode);
+            } else if (child && typeof child === 'object') {
+                if ('element' in child) {
+                    // HtmlInterface, TextInterface, FragmentInterface
+                    this.insertBeforeClose(child.element);
+                    this.children.push(child);
+                    child.render();
+                } else if ('openTag' in child) {
+                    // Nested Reactive
+                    this.children.push(child);
+                    child.render();
+                }
+            }
+        }
+    }
+
+    /** Schedule a re-render through the ViewController */
+    update(): void {
+        this.ctx.scheduleUpdate(this);
+    }
+
+    /** Clear all DOM nodes between the open and close markers */
+    private clearContent(): void {
+        // Destroy managed children first
+        for (const child of this.children) {
+            if (child && typeof child === 'object' && 'destroy' in child) {
+                child.destroy();
+            }
+        }
+        this.children = [];
+
+        // Remove DOM nodes between markers
+        let current = this.openTag.nextSibling;
+        while (current && current !== this.closeTag) {
+            const next = current.nextSibling;
+            current.remove();
+            current = next;
+        }
+    }
+
+    /** Insert a node just before the close marker */
+    private insertBeforeClose(node: Node): void {
+        this.closeTag.parentNode?.insertBefore(node, this.closeTag);
+    }
+
+    /** Determine the actual DOM element to insert into */
+    private getInsertionTarget(): HTMLElement | null {
+        if (this.parentElement) {
+            return this.parentElement.element;
+        }
+        return null;
+    }
+
+    /** Start — subscribe to stateKeys and recursively start children.
+     * Called during START phase of view lifecycle. */
+    start(): void {
+        if (this._isStarted) return;
+        this._isStarted = true;
+
+        // Subscribe to state changes → schedule re-render
+        if (this.stateKeys.length > 0) {
+            this.unsubscribe = this.ctx.states.__.subscribe(
+                this.stateKeys,
+                () => this.update()
+            );
+        }
+
+        // Recursively start children
+        for (const child of this.children) {
+            if (child && typeof child === 'object' && 'start' in child && typeof (child as any).start === 'function') {
+                (child as any).start();
+            }
+        }
+    }
+
+    /** Stop — unsubscribe and recursively stop children. */
+    stop(): void {
+        if (!this._isStarted) return;
+        this._isStarted = false;
+
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = () => {};
+        }
+
+        // Recursively stop children
+        for (const child of this.children) {
+            if (child && typeof child === 'object' && 'stop' in child && typeof (child as any).stop === 'function') {
+                (child as any).stop();
+            }
+        }
+    }
+
+    /** Remove content but keep markers (for hide/show scenarios) */
+    hide(): void {
+        this.clearContent();
+    }
+
+    /** Re-render content (for show after hide) */
+    show(): void {
+        this.render();
+    }
+
+    destroy(): void {
+        this.clearContent();
+        this.openTag.remove();
+        this.closeTag.remove();
+        this.mounted = false;
+        this.parentElement = null;
+        this.parentReactive = null;
+    }
+
+    get isOneReactive(): boolean {
+        return true;
+    }
+    set isOneReactive(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for Reactive elements
+    }
+    set isOneElement(value: boolean) {
+        // No-op setter to satisfy the Interface; Reactive is a type of OneElement
+    }
+    get isOneElement(): boolean {
+        return true;
+    }
+}

package/src/core/elements/TextElement.ts

@@ -0,0 +1,110 @@
+import type { HtmlInterface, TextInterface } from "../contracts/ElementInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { escapeHTML } from "../hellpers/utils";
+import { OneObjectType } from "../types/utils";
+
+/**
+ * TextElement — wraps a DOM Text node.
+ * 
+ * Supports reactive text updates without re-creating the node.
+ * When `update(newText)` is called, only the textContent changes — 
+ * no DOM removal/insertion needed.
+ */
+export class TextElement implements TextInterface {
+    oneType: OneObjectType = 'TextElement';
+    public element: Text;
+    public parent: HtmlInterface | null;
+    private ctx: ViewControllerInterface;
+    private statekeys: string[] = [];
+    private unsubscribe: (() => void) | null = null;
+    protected generateText: () => string = () => this._text;
+    public _text: string = '';
+    public shouldEscapeHTML: boolean = true; // Whether to escape HTML in text content
+
+    public isStarted: boolean = false;
+
+
+    domChildren: Node[] = []; // For compatibility with HtmlInterface; Text itself doesn't have a single root element
+    constructor({ ctx, parent = null, stateKeys = [], generateText = () => '', isEscapeHTML = true }: { ctx: ViewControllerInterface, parent?: HtmlInterface | null, stateKeys?: string[], generateText?: () => string, isEscapeHTML?: boolean }) {
+        this.ctx = ctx;
+        this.generateText = generateText;
+        this.parent = parent;
+        this.statekeys = stateKeys;
+        this.shouldEscapeHTML = isEscapeHTML;
+        this._text = this.generateText();
+        if (this.shouldEscapeHTML) {
+            this._text = escapeHTML(this._text);
+        }
+        this.element = document.createTextNode(this._text);
+    }
+
+    /** Start reactive text updates */
+    start(): void {
+        if (this.isStarted) return;
+        this.isStarted = true;
+        if (this.statekeys.length > 0) {
+            this.unsubscribe = this.ctx.states.__.subscribe(this.statekeys, (newText: string) => {
+                this.update(this.generateText());
+            });
+        }
+    }
+    stop(): void {
+        if (!this.isStarted) return;
+        this.isStarted = false;
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+    }
+    setParentElement(parent: HtmlInterface | null): void {
+        
+    }
+
+    /** Update text content in-place */
+    update(newText: string): void {
+        if (this._text !== newText) {
+            this._text = newText;
+            this.element.textContent = this.shouldEscapeHTML ? escapeHTML(newText) : newText;
+        }
+    }
+
+    render(): void {
+        if (this.parent && this.parent.element) {
+            this.parent.element.appendChild(this.element);
+        }
+    }
+
+    remove(): void {
+        this.element.remove();
+    }
+
+    destroy(): void {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+        this.element.remove();
+        this.parent = null;
+    }
+
+    get text(): string {
+        return this._text;
+    }
+
+    set text(newText: string) {
+        this.update(newText);
+    }
+
+    get isOneElement(): boolean {
+        return true;
+    }
+    set isOneElement(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for Text elements
+    }
+    get isOneText(): boolean {
+        return true;
+    }
+    set isOneText(value: boolean) {
+        // No-op setter to satisfy the Interface; this property is always true for Text elements
+    }
+}

package/src/core/elements/Wrapper.ts

@@ -0,0 +1,131 @@
+import { InitMode, InitModes } from "../contracts/common";
+import type { FragmentInterface, HtmlInterface, OneChildrenFactory, OneChildrenFactoryOutput, OneElementChildren, WrapperInterface } from "../contracts/ElementInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { generateUUID } from "../hellpers/utils";
+import type { OneObjectType } from "../types/utils";
+
+/**
+ * Wrapper — 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.
+ * 
+ * Wrapper uses open/close Comment markers to track its region in the DOM,
+ * similar to Reactive but without the reactivity overhead.
+ */
+export class Wrapper implements WrapperInterface {
+    oneType: OneObjectType = 'Wrapper';
+    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; Wrapper itself doesn't have a single root element
+
+    constructor({
+        ctx,
+        initMode = InitModes.CREATE,
+        parentElement = null,
+        childrenFactory
+    }: {
+        ctx: ViewControllerInterface,
+        initMode?: InitMode,
+        parentElement?: HtmlInterface | null,
+        childrenFactory: OneChildrenFactory
+    }) {
+        this.ctx = ctx;
+        this.parent = parentElement;
+        this.childrenFactory = childrenFactory;
+        this.id = ctx.viewId;
+        this.initMode = initMode;
+
+        this.openTag = document.createComment('wrapper-start');
+        this.closeTag = document.createComment('wrapper-end');
+
+    }
+    setParentElement(parent: HtmlInterface | null): void {
+        this.parent = parent;
+    }
+    render(): void {
+        
+    }
+
+    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
+    }
+}

package/src/core/elements/Yield.ts

@@ -0,0 +1,70 @@
+import { InitMode, InitModes } from "../contracts/common";
+import { HtmlInterface, OneChildrenFactoryOutput, YieldInterface } from "../contracts/ElementInterface";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { generateUUID } from "../hellpers/utils";
+import { MarkerModel, OneMarker } from "../services/MarkerService";
+import { OneObjectType } from "../types/utils";
+
+export class YieldElement implements YieldInterface{
+    oneType: OneObjectType = "Yield";
+    ctx: ViewControllerInterface;
+    name: string
+    id: string;
+    contentFactory: () => OneChildrenFactoryOutput = () => [];
+    openTag!: Comment;
+    closeTag!: Comment;
+    initMode: InitMode = InitModes.CREATE
+    domChildren: Node[] = [];
+    parent: HtmlInterface | null = null;
+    defaultValue: string = '';
+    constructor({ctx, name = '', initMode = InitModes.CREATE, id = null, defaultValue = ''} : {ctx: ViewControllerInterface, name: string, initMode?: InitMode, id?: string | null, defaultValue?: string}) {
+        this.ctx = ctx;
+        this.name = name;
+        this.initMode = initMode;
+        this.id = id && id.length > 0 ? id : generateUUID();
+        this.defaultValue = defaultValue;
+        
+        const yeildMarker: MarkerModel | null = (this.initMode === InitModes.HYDRATE) ? OneMarker.first('yield', this.id) : null;
+        if(yeildMarker){
+            this.openTag = yeildMarker.openTag;
+            this.closeTag = yeildMarker.closeTag;
+            this.domChildren = yeildMarker.nodes.map((el: Node) => el);
+        } else {
+            this.createMarkers();
+        }
+        
+    }
+    private createMarkers(){
+        const key = OneMarker.addRegistry('yield', this.id, {name: this.name});
+        this.openTag = OneMarker.createOpenMarker('yield', this.id);
+        this.closeTag = OneMarker.createCloseMarker('yield', this.id);
+    }
+
+    setParentElement(parent: HtmlInterface | null): void {
+        this.parent = parent;
+    }
+
+    setContentFactory(factory: () => OneChildrenFactoryOutput): void {
+        this.contentFactory = factory;
+    }
+
+    render(): void {
+        if (!this.parent?.element) return;
+
+        const parentEl = this.parent.element;
+        parentEl.appendChild(this.openTag);
+        parentEl.appendChild(this.closeTag);
+    }
+
+    destroy(): void {
+        this.openTag?.remove();
+        this.closeTag?.remove();
+        this.domChildren = [];
+        this.parent = null;
+    }
+
+    get isOneElement(): boolean { return true; }
+    set isOneElement(_: boolean) {}
+    get isOneYield(): boolean { return true; }
+    set isOneYield(_: boolean) {}
+}

package/src/core/elements/helpers.ts

@@ -0,0 +1,56 @@
+import { BlockInterface, BlockOutletInterface } from "../contracts/BlockInterface";
+import { FragmentInterface, HtmlInterface, OutputInterface, OneChildrenFactoryOutput, OneElementChildren } from "../contracts/ElementInterface";
+import { ReactiveInterface } from "../contracts/ReactiveInterface";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { OneObjectType } from "../types/utils";
+
+export function getOneObjectType(instance: any): OneObjectType | null {
+    if (instance && typeof instance === 'object' && 'oneType' in instance) {
+        return instance.oneType;
+    }
+    return null;
+}
+
+export function parseElementChildren(
+    oneElement: HtmlInterface | ReactiveInterface | BlockOutletInterface | OutputInterface | FragmentInterface | ViewControllerInterface, 
+    parentElement: HTMLElement,
+    children: OneChildrenFactoryOutput
+): OneElementChildren {
+    const parsedChildren: OneElementChildren = [];
+
+    if(!children || !Array.isArray(children)) {
+        console.warn('Children factory returned invalid output (not an array):', children);
+        return parsedChildren;
+    }
+
+    children.forEach(child => {
+        if (typeof child === 'string' || typeof child === 'number') {
+            const textNode = document.createTextNode(String(child));
+            parsedChildren.push(textNode);
+            return;
+        }
+        if(child instanceof Node) {
+            // Direct DOM node (e.g. from a third-party library) — append as-is
+            parsedChildren.push(child);
+            return;
+        }
+        if (!child || typeof child !== 'object' || child === null) {
+            // Skip invalid child types (null, undefined, non-objects, non-DOM nodes)
+            console.warn('Skipping invalid child:', child);
+            return;
+        } 
+        let childType: OneObjectType = getOneObjectType(child);
+        if(!childType) {
+            return;
+        }
+        switch (childType) {
+            case 'Html':
+
+            
+            break;
+        }
+    });
+
+
+    return parsedChildren;
+}

package/src/core/elements/index.ts

@@ -0,0 +1,26 @@
+import type { BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface";
+import type { HtmlInterface, HtmlElementConfig, OneChildrenFactory } from "../contracts/ElementInterface";
+import type { ReactiveChildrenFactory } from "../contracts/ReactiveInterface";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface";
+import { ViewController } from "../view";
+import { Block } from "./Block";
+import BlockManager from "../services/BlockManager";
+import { BlockOutlet } from "./BlockOutlet";
+import { Fragment } from "./Fragment";
+import { Html } from "./Html";
+import { Output } from "./Output";
+import { Reactive } from "./Reactive";
+import { TextElement } from "./TextElement";
+
+
+export * from "./Block";
+export * from "./BlockOutlet";
+export * from './Component';
+export * from "./ElementManager";
+export * from "./Fragment";
+export * from "./helpers";
+export * from "./Html";
+export * from "./Output";
+export * from './Reactive';
+export * from "./TextElement";
+export * from "./Yield";