@saolabs/client 1.0.0 → 1.0.2

package/src/core/elements/ElementManager.ts

@@ -1,12 +1,12 @@
-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";
+import type { BlockRenderFactory } from "../contracts/BlockInterface.js";
+import type { HtmlInterface, SaoElementConfig, SaoChildrenFactory } from "../contracts/ElementInterface.js";
+import type { ReactiveRenderFn } from "../contracts/ReactiveInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { Html } from "./Html.js";
+import { TextElement } from "./TextElement.js";
+import { Reactive } from "./Reactive.js";
+import { Fragment } from "./Fragment.js";
+import { Block } from "./Block.js";
 
 /**
  * OneElementManager — factory/registry for creating One elements.

package/src/core/elements/ForeachSlotCache.ts

@@ -0,0 +1,170 @@
+/**
+ * ForeachSlotCache — keyed slot manager cho @foreach reconciliation.
+ *
+ * # Cơ chế
+ * Mỗi item được identify bằng một cache key:
+ *   - Có @key(expr)   → key = giá trị expr (field keying, vd `item.id`)
+ *   - Không có @key   → key = object reference của item (identity keying)
+ * Duplicate keys (primitive lists `['a','b','a']`, refs lặp) được phân biệt
+ * bằng occurrence index trong pass — key thứ n trùng nhau map vào slot thứ n.
+ *
+ * # Reuse contract
+ * Slot chỉ được REUSE khi cache key khớp VÀ item ref không đổi
+ * (`slot.item === item`). Ref đổi → recreate, vì compiled output đóng gói
+ * `item` trực tiếp vào closure (`() => item.name`) — reuse với ref cũ sẽ
+ * hiển thị data cũ. Field key vì vậy chủ yếu mang lại: bookkeeping đúng cho
+ * duplicate/primitive items + ý định tường minh của developer.
+ *
+ * # Pass protocol (một chu kỳ render)
+ *   1. `beginPass()`  — reset occurrence counters + tập slot touched
+ *   2. `claim(key, item)` mỗi item theo thứ tự list:
+ *        hit  (slot.item === item) → dùng lại, slot được mark touched
+ *        miss → caller tạo elements rồi `store(key, occ, item, elements)`
+ *   3. `prunePass(onRemove)` — slot KHÔNG được touch trong pass = item đã rời
+ *      list → callback destroy + gỡ khỏi cache. (Trước đây bước này là dead
+ *      code — cache không bao giờ gỡ entry → element của item bị xoá leak.)
+ *      Slot bị `store()` GHI ĐÈ (cùng key, ref mới) cũng đi qua đây: nó rơi khỏi
+ *      `_map` ngay lúc ghi đè nên prunePass không còn thấy → phải giữ tạm trong
+ *      `_evicted`. Thiếu bước này thì refresh list từ server (`@key` giữ nguyên,
+ *      ref đổi) KHÔNG destroy elements cũ → view con của @include bị tái dùng
+ *      trong DOM đã detach và biến mất khỏi trang.
+ *
+ * # Quan hệ với Reactive
+ * Reactive type 'foreach' giữ một instance; cửa sổ `_currentForeachCache`
+ * chỉ mở quanh CHÍNH childrenFactory call (không mở trong child.render() —
+ * tránh nested @foreach ghi nhầm vào cache của loop ngoài).
+ *
+ * @see Reactive.renderForeach()
+ * @see ViewController.__foreach()
+ */
+
+/** Một slot tương ứng với một item trong foreach list. */
+export interface ForeachSlot {
+    /** Reference tới item gốc — điều kiện reuse là ref không đổi */
+    item: any;
+    /** Saola elements sinh ra bởi item factory — Html, Output, Reactive, ... */
+    elements: any[];
+    /** Compiler opt-in: closures are refreshed within this occurrence's scope. */
+    registry?: Map<string, any>;
+    identity?: number;
+}
+
+/** Kết quả claim: slot khi reuse được, occ để store khi phải tạo mới. */
+export interface ForeachClaim {
+    slot: ForeachSlot | null;
+    occ: number;
+}
+
+export class ForeachSlotCache {
+    readonly refreshedElements = new Set<any>();
+    private nextIdentity = 0;
+
+    /** Initial SSR indexes, then monotonically allocated identities for new rows. */
+    allocateIdentity(index: number): number {
+        const identity = Math.max(index, this.nextIdentity);
+        this.nextIdentity = identity + 1;
+        return identity;
+    }
+    /** Map key → danh sách slot theo occurrence (duplicate keys) */
+    private _map: Map<any, ForeachSlot[]> = new Map();
+    /** Occurrence counter của pass hiện tại */
+    private _passOcc: Map<any, number> = new Map();
+    /** Slots được claim-hit hoặc store trong pass hiện tại */
+    private _touched: Set<ForeachSlot> = new Set();
+    /** Slots bị store() ghi đè trong pass hiện tại — prunePass destroy rồi clear */
+    private _evicted: ForeachSlot[] = [];
+
+    /** Tổng số slot đang cache (mọi occurrence). */
+    get size(): number {
+        let n = 0;
+        for (const slots of this._map.values()) n += slots.length;
+        return n;
+    }
+
+    /** Bắt đầu một chu kỳ render — reset counters + touched set. */
+    beginPass(): void {
+        this.refreshedElements.clear();
+        this._passOcc = new Map();
+        this._touched = new Set();
+        this._evicted = [];
+    }
+
+    /**
+     * Claim slot cho (key, item) theo thứ tự list.
+     * Trả slot khi reuse được (key khớp + ref không đổi); ngược lại slot=null
+     * và caller phải store(key, occ, ...) sau khi tạo elements.
+     */
+    claim(key: any, item: any, reconcile = false): ForeachClaim {
+        const occ = this._passOcc.get(key) ?? 0;
+        this._passOcc.set(key, occ + 1);
+
+        const slot = this._map.get(key)?.[occ] ?? null;
+        if (slot && (slot.item === item || (reconcile && slot.registry))) {
+            this._touched.add(slot);
+            return { slot, occ };
+        }
+        return { slot: null, occ };
+    }
+
+    /**
+     * Lưu slot mới tại (key, occ) — ghi đè slot cũ nếu ref đã đổi.
+     * Slot bị ghi đè KHÔNG còn nằm trong `_map` nên prunePass duyệt `_map` sẽ
+     * không thấy nó nữa → phải chuyển sang `_evicted` để vẫn được destroy.
+     */
+    store(key: any, occ: number, item: any, elements: any[], registry?: Map<string, any>): ForeachSlot {
+        const slot: ForeachSlot = { item, elements, registry };
+        let slots = this._map.get(key);
+        if (!slots) {
+            slots = [];
+            this._map.set(key, slots);
+        }
+        const evicted = slots[occ];
+        if (evicted && !this._touched.has(evicted)) {
+            this._evicted.push(evicted);
+        }
+        slots[occ] = slot;
+        this._touched.add(slot);
+        return slot;
+    }
+
+    /**
+     * Kết thúc pass: mọi slot không được touch = item đã rời list (hoặc bị
+     * thay bằng ref mới) → gọi onRemove(slot) để destroy elements, gỡ khỏi cache.
+     */
+    prunePass(onRemove: (slot: ForeachSlot) => void): void {
+        // Slot bị ghi đè: đã rời `_map` lúc store() nên chỉ cần destroy.
+        for (const slot of this._evicted) onRemove(slot);
+        this._evicted = [];
+
+        for (const [key, slots] of this._map) {
+            let hasRemoval = false;
+            for (const slot of slots) {
+                if (slot && !this._touched.has(slot)) {
+                    onRemove(slot);
+                    hasRemoval = true;
+                }
+            }
+            if (hasRemoval) {
+                const kept = slots.filter(s => s && this._touched.has(s));
+                if (kept.length) {
+                    this._map.set(key, kept);
+                } else {
+                    this._map.delete(key);
+                }
+            }
+        }
+    }
+
+    /**
+     * Xoá toàn bộ cache — dùng khi Reactive bị destroy.
+     * KHÔNG tự gọi destroy() trên elements — caller phải làm trước.
+     */
+    clear(): void {
+        this.nextIdentity = 0;
+        this.refreshedElements.clear();
+        this._map.clear();
+        this._passOcc = new Map();
+        this._touched = new Set();
+        this._evicted = [];
+    }
+}

package/src/core/elements/Fragment.ts

@@ -1,8 +1,8 @@
-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";
+import { InitMode, InitModes } from "../contracts/common.js";
+import type { FragmentInterface, HtmlInterface, SaoChildrenFactory, SaoChildrenFactoryOutput, SaoElementChildren } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { generateUUID } from "../helpers/utils.js";
+import type { SaoObjectType } from "../types/utils.js";
 
 /**
  * Fragment — renders multiple root nodes into a parent without a wrapping tag.
@@ -14,13 +14,13 @@ import type { OneObjectType } from "../types/utils";
  * similar to Reactive but without the reactivity overhead.
  */
 export class Fragment implements FragmentInterface {
-    oneType: OneObjectType = 'Fragment';
+    saoType: SaoObjectType = 'Fragment';
     public parent: HtmlInterface | null;
     public nodes: Node[] = [];
     /** Tracked child element wrappers (Html, Output, Reactive, TextElement, etc.) */
-    public children: OneElementChildren = [];
+    public children: SaoElementChildren = [];
     private ctx: ViewControllerInterface;
-    private childrenFactory: OneChildrenFactory;
+    private childrenFactory: SaoChildrenFactory;
     public openTag: Comment;
     public closeTag: Comment;
     public id: string; // Unique ID for debugging and marker registry
@@ -39,7 +39,7 @@ export class Fragment implements FragmentInterface {
         id?: string | null, 
         initMode?: InitMode, 
         parentElement?: HtmlInterface | null, 
-        childrenFactory: OneChildrenFactory
+        childrenFactory: SaoChildrenFactory
     }) {
         this.ctx = ctx;
         this.parent = parentElement;
@@ -52,48 +52,64 @@ export class Fragment implements FragmentInterface {
     setParentElement(parent: HtmlInterface | null): void {
         this.parent = parent;
     }
-    render(): void {
-        if (!this.parent || !this.parent.element) return;
-
-        const parentEl = this.parent.element;
+    /** Registry guard — element đã destroy không được reuse */
+    public __destroyed__: boolean = false;
 
-        // Place start marker
-        parentEl.appendChild(this.openTag);
+    /**
+     * Render — idempotent + position-aware (RUNTIME_CONTRACT.md §2),
+     * cùng pattern với Reactive.render().
+     */
+    render(): void {
+        if (this.__destroyed__) return;
+
+        if (!this.openTag.parentNode) {
+            if (!this.parent || !this.parent.element) return;
+            const parentEl = this.parent.element;
+            parentEl.appendChild(this.openTag);
+            parentEl.appendChild(this.closeTag);
+        } else {
+            this.clear(false);
+        }
 
         // Build children — compiled output uses (parentElement) => [...] signature
-        const output: OneChildrenFactoryOutput = this.childrenFactory(this.parent);
+        const output: SaoChildrenFactoryOutput = this.childrenFactory(this.parent);
+        const insertBeforeClose = (node: Node) => {
+            this.closeTag.parentNode?.insertBefore(node, this.closeTag);
+        };
 
         for (const child of output) {
+            if (child === null || child === undefined) continue;
             if (typeof child === 'string' || typeof child === 'number') {
                 const textNode = document.createTextNode(String(child));
-                parentEl.appendChild(textNode);
+                insertBeforeClose(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);
+            } else if (child instanceof Node) {
+                insertBeforeClose(child);
+                this.nodes.push(child);
+            } else if (typeof child === 'object') {
+                if ('element' in child && (child as any).element) {
+                    insertBeforeClose((child as any).element);
+                    this.nodes.push((child as any).element);
                     this.children.push(child);
                     child.render();
                 } else if ('openTag' in child) {
-                    // Reactive, nested Fragment, Output — they self-append markers
+                    // Marker-based: đặt markers đúng vị trí trước, render sau
                     if ('parent' in child) {
                         (child as any).parent = this.parent;
                     }
                     if ('parentElement' in child) {
                         (child as any).parentElement = this.parent;
                     }
+                    insertBeforeClose((child as any).openTag);
+                    insertBeforeClose((child as any).closeTag);
                     this.children.push(child);
                     child.render();
                 }
             }
         }
-
-        // Place end marker
-        parentEl.appendChild(this.closeTag);
     }
 
-    setChildrenFactory(factory: OneChildrenFactory): void {
+    setChildrenFactory(factory: SaoChildrenFactory): void {
         this.childrenFactory = factory;
     }
 
@@ -126,7 +142,7 @@ export class Fragment implements FragmentInterface {
     }
 
     /** Remove all nodes between markers from the DOM */
-    clear(): void {
+    clear(_destroyChildren: boolean = true): void {
         // Destroy managed children first
         for (const child of this.children) {
             if ('destroy' in child && typeof child.destroy === 'function') {
@@ -146,23 +162,25 @@ export class Fragment implements FragmentInterface {
     }
 
     destroy(): void {
+        this.__destroyed__ = true;
+        this.ctx.releaseElement?.(this);
         this.clear();
         this.openTag.remove();
         this.closeTag.remove();
         this.parent = null;
     }
 
-    get isOneElement(): boolean {
+    get isSaoElement(): boolean {
         return true;
     }
-    set isOneElement(value: boolean) {
+    set isSaoElement(value: boolean) {
         // No-op setter to satisfy the Interface; this property is always true for Fragment elements
     }
 
-    get isOneFragment(): boolean {
+    get isSaoFragment(): boolean {
         return true;
     }
-    set isOneFragment(value: boolean) {
+    set isSaoFragment(value: boolean) {
         // No-op setter to satisfy the Interface; this property is always true for Fragment elements
     }
 }