@saolabs/client 1.0.0 → 1.1.0

package/src/core/services/BlockManager.ts

@@ -1,7 +1,7 @@
-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";
+import type { BlockInterface, BlockManagerInterface, BlockOutletInterface, BlockRenderFactory } from "../contracts/BlockInterface.js";
+import type { HtmlInterface } from "../contracts/ElementInterface.js";
+import type { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { Block } from "../elements/Block.js";
 
 /**
  * BlockManager — manages all block slots in a layout view.
@@ -96,91 +96,313 @@ export class BlockManagerService implements BlockManagerInterface {
      * 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 block content vào outlet cùng tên; outlet không có block active → clear về rỗng
+        for (const [, outlet] of this.blockOutlets) {
+            const block = this.activeBlocks.get(outlet.name);
+            if (block && block.contentRenderFactory) {
+                this.mountBlockIntoOutlet(block, outlet);
+            } else {
+                this.clearOutletInstance(outlet);
             }
         }
     }
 
+    /**
+     * Mount only blocks owned by one Page/Layout controller. Nested layout
+     * chains call this from outer to inner, so an inner outlet exists before
+     * the next owner is mounted and retained layouts are not rebuilt.
+     */
+    mountViewBlocks(viewId: string): void {
+        for (const [, block] of this.blocks) {
+            if (block.viewId !== viewId || !block.contentRenderFactory) continue;
+            const outlet = this.findOutletByName(block.name);
+            if (!outlet) continue;
+            this.activeBlocks.set(block.name, block);
+            this.mountBlockIntoOutlet(block, outlet);
+        }
+    }
+
+    /** Hydration counterpart of mountViewBlocks(). */
+    hydrateViewBlocks(viewId: string): void {
+        for (const [, block] of this.blocks) {
+            if (block.viewId !== viewId || !block.contentRenderFactory) continue;
+            const outlet = this.findOutletByName(block.name);
+            if (!outlet) continue;
+            this.activeBlocks.set(block.name, block);
+            this.hydrateBlockIntoOutlet(block, outlet);
+        }
+    }
+
     /**
      * Mount a single block's content into an outlet.
-     * Content is rendered and inserted between the outlet's open/close markers.
+     * Clear nội dung cũ trước, render content mới GIỮA outlet markers
+     * (cùng insertion model với Reactive — RUNTIME_CONTRACT.md §2).
      */
     private mountBlockIntoOutlet(block: BlockInterface, outlet: BlockOutletInterface): void {
-        if (!outlet.parentElement?.element) return;
+        if (!outlet.openTag.parentNode) return; // outlet chưa nằm trong DOM
+
+        // Clear nội dung cũ (page trước) trước khi mount page mới
+        this.clearOutletInstance(outlet);
 
-        const parentEl = outlet.parentElement.element;
         const children: any[] = [];
+        const insertBeforeClose = (node: Node) => {
+            outlet.closeTag.parentNode?.insertBefore(node, outlet.closeTag);
+        };
 
-        // Render block content using the factory
-        const content = block.contentRenderFactory!(block.ctx as any);
+        // Render block content using the factory — elements thuộc về PAGE ctrl
+        const content = block.contentRenderFactory!(outlet.parentElement as any);
 
-        if (!Array.isArray(content)) return;
+        // Marker `s:b:` của chính block phải bao quanh content — Blade emit cặp này
+        // trong @block (ViewStorageManager::getMarkerOpenTag), nên thiếu nó ở đây là
+        // DOM sau SPA nav khác DOM từ server: hydrate lần sau không tìm ra block để
+        // claim, và cổng tests/e2e/ssr-csr-parity thấy marker lệch một phía.
+        // Block dựng sẵn openTag/closeTag trong constructor; chỗ chèn là ở đây, cùng
+        // insertion model với content (RUNTIME_CONTRACT.md §2).
+        insertBeforeClose(block.openTag);
 
-        // Insert each child between outlet markers
-        for (const child of content) {
+        // Content không phải mảng vẫn phải đóng marker — block rỗng ở server là cặp
+        // marker liền nhau, không phải không có marker.
+        for (const child of Array.isArray(content) ? content : []) {
+            if (child === null || child === undefined) continue;
             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);
+                insertBeforeClose(document.createTextNode(String(child)));
+            } else if (child instanceof Node) {
+                insertBeforeClose(child);
+            } else if (typeof child === 'object') {
+                if ('element' in child && (child as any).element) {
+                    insertBeforeClose((child as any).element);
                     children.push(child);
                     child.render();
                 } else if ('openTag' in child) {
-                    // Reactive, Fragment, Output — set parent, render
+                    // Marker-based: đặt markers đúng vị trí trước, render sau (idempotent)
                     if ('parent' in child) {
                         (child as any).parent = outlet.parentElement;
                     }
                     if ('parentElement' in child) {
                         (child as any).parentElement = outlet.parentElement;
                     }
+                    insertBeforeClose((child as any).openTag);
+                    insertBeforeClose((child as any).closeTag);
                     children.push(child);
                     child.render();
                 }
             }
         }
 
-        // Track mounted children for cleanup
-        this.mountedChildren.set(outlet.name, children);
+        insertBeforeClose(block.closeTag);
+
+        // Track mounted children for lifecycle (start/stop/destroy)
+        this.mountedChildren.set(this.outletKey(outlet), children);
     }
 
     /**
-     * Clear content from a specific outlet (for page swap).
-     * Removes all DOM nodes between a named outlet's markers.
+     * Hydrate version của mountAll — dùng khi SSR.
+     * KHÁC mountAll: KHÔNG clearOutlet (giữ DOM server), KHÔNG insertBefore.
+     * Chạy block factory ở HYDRATE mode → Html/Output/Reactive con CLAIM
+     * DOM server đã render sẵn giữa cặp marker của outlet.
+     *
+     * Tiền đề: page ctrl.initMode === HYDRATE khi gọi (để this.html() trong
+     * factory tạo element claim DOM thay vì tạo mới).
      */
-    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);
+    mountAllHydrate(): void {
+        for (const [, outlet] of this.blockOutlets) {
+            const block = this.activeBlocks.get(outlet.name);
+            if (block && block.contentRenderFactory) {
+                this.hydrateBlockIntoOutlet(block, outlet);
+            }
+            // outlet không có block active → để nguyên DOM server (thường rỗng)
+        }
+    }
+
+    /**
+     * Claim block content vào outlet (hydrate). Chạy factory, gọi render() đệ quy
+     * trên children để claim DOM, KHÔNG chèn node mới. Track children cho lifecycle.
+     */
+    private hydrateBlockIntoOutlet(block: BlockInterface, outlet: BlockOutletInterface): void {
+        const children: any[] = [];
+        const content = block.contentRenderFactory!(outlet.parentElement as any);
+        if (!Array.isArray(content)) return;
+
+        for (const child of content) {
+            if (child === null || child === undefined) continue;
+            if (typeof child === 'string' || typeof child === 'number') continue; // text: giữ server
+            if (child instanceof Node) continue;
+            if (typeof child === 'object') {
+                if ('element' in child && (child as any).element) {
+                    children.push(child);
+                    (child as any).render(); // HYDRATE: Html claim DOM, không chèn
+                } else if ('openTag' in child) {
+                    if ('parent' in child) (child as any).parent = outlet.parentElement;
+                    if ('parentElement' in child) (child as any).parentElement = outlet.parentElement;
+                    children.push(child);
+                    (child as any).render(); // HYDRATE: Output/Reactive claim markers
                 }
+            }
+        }
+
+        this.mountedChildren.set(this.outletKey(outlet), children);
+    }
 
-                // Remove any remaining DOM nodes between markers
+    /** Tìm outlet theo tên (outlet key = `${layoutViewId}-ob-${name}`) */
+    private findOutletByName(name: string): BlockOutletInterface | null {
+        let found: BlockOutletInterface | null = null;
+        for (const [, outlet] of this.blockOutlets) {
+            if (outlet.name === name) found = outlet;
+        }
+        // Nearest/deepest outlet is registered last while mounting a nested chain.
+        return found;
+    }
+
+    /**
+     * Detach block content của một page (rời trang, vào PageCache):
+     * gỡ DOM giữa markers của từng outlet vào DocumentFragment, lấy children
+     * đang track ra khỏi manager (KHÔNG destroy — instance sống trong cache).
+     *
+     * Trả Map<outletName, {fragment, children}> để restore sau này.
+     */
+    detachPageContent(viewId: string): Map<string, { fragment: DocumentFragment; children: any[] }> {
+        const result = new Map<string, { fragment: DocumentFragment; children: any[] }>();
+        for (const [name, block] of Array.from(this.activeBlocks)) {
+            if (block.viewId !== viewId) continue;
+
+            const fragment = document.createDocumentFragment();
+            const outlet = this.findOutletByName(name);
+            if (outlet && outlet.openTag.parentNode) {
                 let current = outlet.openTag.nextSibling;
                 while (current && current !== outlet.closeTag) {
                     const next = current.nextSibling;
-                    current.remove();
+                    fragment.appendChild(current); // appendChild tự remove khỏi DOM
                     current = next;
                 }
-                break;
             }
+
+            const outletKey = outlet ? this.outletKey(outlet) : name;
+            const children = this.mountedChildren.get(outletKey) ?? [];
+            this.mountedChildren.delete(outletKey);
+            this.activeBlocks.delete(name); // page rời đi — không còn active ở outlet này
+            result.set(name, { fragment, children });
+        }
+        return result;
+    }
+
+    /**
+     * Restore block content của một page từ PageCache vào outlets hiện tại.
+     * Tiền đề: layout đang mount trùng với layout lúc detach (ViewManager guard).
+     */
+    restorePageContent(viewId: string, contents: Map<string, { fragment: DocumentFragment; children: any[] }>): void {
+        for (const [name, { fragment, children }] of contents) {
+            const outlet = this.findOutletByName(name);
+            if (outlet && outlet.closeTag.parentNode) {
+                outlet.closeTag.parentNode.insertBefore(fragment, outlet.closeTag);
+            }
+            if (outlet) this.mountedChildren.set(this.outletKey(outlet), children);
+            // Re-activate block của page này (blocks map còn giữ — pause không xoá)
+            const block = this.blocks.get(name + viewId);
+            if (block) {
+                this.activeBlocks.set(name, block);
+            }
+        }
+    }
+
+    /** Start toàn bộ block content đang mounted (gọi sau mountAll) */
+    startAll(): void {
+        for (const [, children] of this.mountedChildren) {
+            for (const child of children) {
+                if (child && typeof child.start === 'function') child.start();
+            }
+        }
+    }
+
+    /** Stop toàn bộ block content (trước khi swap page) */
+    stopAll(): void {
+        for (const [, children] of this.mountedChildren) {
+            for (const child of children) {
+                if (child && typeof child.stop === 'function') child.stop();
+            }
+        }
+    }
+
+    /**
+     * Gỡ mọi dấu vết của một view (page bị destroy):
+     * clear outlet đang chứa content của nó + xoá block đăng ký.
+     */
+    unmountView(viewId: string): void {
+        for (const [name, block] of this.activeBlocks) {
+            if (block.viewId === viewId) {
+                this.clearOutlet(name);
+                this.activeBlocks.delete(name);
+            }
+        }
+        for (const [key, block] of this.blocks) {
+            if (block.viewId === viewId) {
+                // destroy TRƯỚC khi rời Map. Block KHÔNG nằm trong ctrl.elements
+                // nên teardown cây element không bao giờ chạm tới nó — đây là chỗ
+                // DUY NHẤT gỡ được record marker toàn cục của nó. Thiếu dòng này
+                // thì MarkerRegistry (singleton, sống qua navigate) tăng đúng 1
+                // record mỗi lần điều hướng, vĩnh viễn.
+                block.destroy?.();
+                this.blocks.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Gỡ outlets của một layout khỏi registry mà KHÔNG destroy — layout pause
+     * vào PageCache. Nếu để lại, mountAll/findOutletByName có thể đụng outlet
+     * (trùng tên) của layout đang detached. Re-register khi resume qua
+     * addOutlet (ViewManager.reregisterLayoutOutlets).
+     */
+    detachOutletsOfView(viewId: string): void {
+        for (const [key, outlet] of this.blockOutlets) {
+            if ((outlet as any).ctx?.viewId === viewId) {
+                this.blockOutlets.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Gỡ outlets của một layout bị destroy — XOÁ THẬT, khác hẳn
+     * `detachOutletsOfView` ở ngay trên (layout chỉ pause vào PageCache và sẽ
+     * được re-register, nên KHÔNG được destroy ở đó).
+     * `destroy()` idempotent nên gọi ở đây an toàn kể cả khi teardown cây
+     * element đã destroy outlet trước đó.
+     */
+    removeOutletsOfView(viewId: string): void {
+        for (const [key, outlet] of this.blockOutlets) {
+            if ((outlet as any).ctx?.viewId === viewId) {
+                this.mountedChildren.delete(this.outletKey(outlet));
+                (outlet as any).destroy?.();
+                this.blockOutlets.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Clear content from a specific outlet (for page swap).
+     * Removes all DOM nodes between a named outlet's markers.
+     */
+    clearOutlet(name: string): void {
+        const outlet = this.findOutletByName(name);
+        if (outlet) this.clearOutletInstance(outlet);
+    }
+
+    private outletKey(outlet: BlockOutletInterface): string {
+        return String((outlet as any).id ?? `${(outlet as any).ctx?.viewId ?? ''}:${outlet.name}`);
+    }
+
+    private clearOutletInstance(outlet: BlockOutletInterface): void {
+        const key = this.outletKey(outlet);
+        const children = this.mountedChildren.get(key) ?? [];
+        for (const child of children) {
+            if ('destroy' in child && typeof child.destroy === 'function') child.destroy();
+        }
+        this.mountedChildren.delete(key);
+
+        let current = outlet.openTag.nextSibling;
+        while (current && current !== outlet.closeTag) {
+            const next = current.nextSibling;
+            current.remove();
+            current = next;
         }
     }
 
@@ -188,8 +410,8 @@ export class BlockManagerService implements BlockManagerInterface {
      * Clear all outlets (for full layout teardown).
      */
     clearAllOutlets(): void {
-        for (const [key, outlet] of this.blockOutlets) {
-            this.clearOutlet(outlet.name);
+        for (const [, outlet] of this.blockOutlets) {
+            this.clearOutletInstance(outlet);
         }
     }
 

package/src/core/services/DomService.ts

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

package/src/core/services/HeadService.ts

@@ -0,0 +1,124 @@
+import type { HeadLinkOptions, HeadServiceInterface, HeadTagOptions, HeadTagScope } from "../contracts/HeadServiceInterface.js";
+
+interface ManagedHeadEntry {
+    scope: HeadTagScope;
+    /** Undo exactly this entry's DOM change — restore the pre-managed value, or remove the element this service created. */
+    revert: () => void;
+}
+
+/**
+ * HeadService — the single place that writes to `<head>` (title, meta, link,
+ * JSON-LD). Independent of any View: callable from anywhere via `app('Head')`
+ * / `App.Head`. Reuses whatever the server already rendered there (SSR's
+ * `<title>`, `<meta name="description">`, ...) instead of creating
+ * duplicates, and snapshots the pre-managed value so `resetPage()` can put it
+ * back — the fix for tags leaking from one SPA-navigated page into the next.
+ */
+export class HeadServiceImpl implements HeadServiceInterface {
+    private managed: Map<string, ManagedHeadEntry> = new Map();
+
+    setTitle(title: string, options: HeadTagOptions = {}): void {
+        if (typeof document === 'undefined') return;
+        const key = '__title__';
+        if (!this.managed.has(key)) {
+            const original = document.title;
+            this.managed.set(key, {
+                scope: options.scope ?? 'page',
+                revert: () => { document.title = original; },
+            });
+        }
+        document.title = title;
+    }
+
+    setMeta(name: string, content: string, options: HeadTagOptions = {}): void {
+        this.setAttrTag(`meta:name:${name}`, 'meta', { name }, 'content', content, options.scope ?? 'page');
+    }
+
+    setMetaProperty(property: string, content: string, options: HeadTagOptions = {}): void {
+        this.setAttrTag(`meta:property:${property}`, 'meta', { property }, 'content', content, options.scope ?? 'page');
+    }
+
+    setLink(rel: string, href: string, options: HeadLinkOptions = {}): void {
+        const extra = options.attrs ?? {};
+        const key = `link:${rel}` + Object.entries(extra).map(([k, v]) => `:${k}=${v}`).join('');
+        this.setAttrTag(key, 'link', { rel, ...extra }, 'href', href, options.scope ?? 'page');
+    }
+
+    setJsonLd(id: string, data: Record<string, any>, options: HeadTagOptions = {}): void {
+        if (typeof document === 'undefined') return;
+        const key = `jsonld:${id}`;
+        const selector = `script[data-head-id="${id}"]`;
+        if (!this.managed.has(key)) {
+            let el = document.head.querySelector<HTMLScriptElement>(selector);
+            const created = !el;
+            if (!el) {
+                el = document.createElement('script');
+                el.type = 'application/ld+json';
+                el.setAttribute('data-head-id', id);
+                document.head.appendChild(el);
+            }
+            // Page-owned SSR schema belongs to the initial route; remove it on navigation.
+            const originalText = created || el.getAttribute('data-head-scope') === 'page' ? null : el.textContent;
+            this.managed.set(key, {
+                scope: options.scope ?? 'page',
+                revert: () => {
+                    const target = document.head.querySelector<HTMLScriptElement>(selector);
+                    if (!target) return;
+                    if (originalText === null) target.remove();
+                    else target.textContent = originalText;
+                },
+            });
+        }
+        const el = document.head.querySelector<HTMLScriptElement>(selector);
+        if (el) el.textContent = JSON.stringify(data);
+    }
+
+    unset(key: string): void {
+        const entry = this.managed.get(key);
+        if (!entry) return;
+        entry.revert();
+        this.managed.delete(key);
+    }
+
+    resetPage(): void {
+        for (const [key, entry] of Array.from(this.managed)) {
+            if (entry.scope !== 'page') continue;
+            entry.revert();
+            this.managed.delete(key);
+        }
+    }
+
+    /** Find-or-create an element by `identAttrs`, snapshot `valueAttr` once, then apply the new value. */
+    private setAttrTag(
+        key: string, tagName: string, identAttrs: Record<string, string>,
+        valueAttr: string, value: string, scope: HeadTagScope,
+    ): void {
+        if (typeof document === 'undefined') return;
+        const selector = tagName + Object.entries(identAttrs).map(([k, v]) => `[${k}="${v}"]`).join('');
+
+        if (!this.managed.has(key)) {
+            let el = document.head.querySelector<HTMLElement>(selector);
+            const created = !el;
+            if (!el) {
+                el = document.createElement(tagName);
+                for (const [k, v] of Object.entries(identAttrs)) el.setAttribute(k, v);
+                document.head.appendChild(el);
+            }
+            const originalValue = created ? null : el.getAttribute(valueAttr);
+            this.managed.set(key, {
+                scope,
+                revert: () => {
+                    const target = document.head.querySelector<HTMLElement>(selector);
+                    if (!target) return;
+                    if (created) target.remove();
+                    else if (originalValue === null) target.removeAttribute(valueAttr);
+                    else target.setAttribute(valueAttr, originalValue);
+                },
+            });
+        }
+        document.head.querySelector<HTMLElement>(selector)?.setAttribute(valueAttr, value);
+    }
+}
+
+export const HeadService = new HeadServiceImpl();
+export default HeadService;

package/src/core/services/HelperService.ts

@@ -1,9 +1,10 @@
-import { CollectionProxyInterface, HelperInterface } from "../contracts/HelperInterface";
-import { ApplicationInterface } from "../contracts/ApplicationInterface";
-import { app } from "../hellpers/app";
+import { TranslationService, type TranslationConfig } from './TranslationService.js';
+import { CollectionProxyInterface, HelperInterface } from "../contracts/HelperInterface.js";
+import { ApplicationInterface } from "../contracts/ApplicationInterface.js";
+import { app } from "../helpers/app.js";
 
 /**
- * HelperService — PHP-compatible helper functions for OneView runtime.
+ * HelperService — PHP-compatible helper functions for SaoView runtime.
  *
  * The compiler converts PHP function calls → `App.Helper.xxx()`.
  * This class provides JavaScript implementations of those PHP functions
@@ -37,6 +38,7 @@ import { app } from "../hellpers/app";
  */
 export class HelperService implements HelperInterface {
     public App: any = null;
+    private translations = new TranslationService();
     private config: Record<string, any> = {};
 
     constructor(App?: any) {
@@ -60,6 +62,34 @@ export class HelperService implements HelperInterface {
         this.config = { ...this.config, ...config };
     }
 
+    initTranslations(config: TranslationConfig): void {
+        this.translations.init(config);
+        this.syncLocale();
+    }
+
+    getLocale(): string { return this.translations.locale; }
+    __(key: string, replace: Record<string, any> = {}, locale?: string): string { return this.translations.trans(key, replace, locale); }
+    trans(key: string, replace: Record<string, any> = {}, locale?: string): string { return this.__(key, replace, locale); }
+    lang(key: string, replace: Record<string, any> = {}, locale?: string): string { return this.__(key, replace, locale); }
+    choice(key: string, count: number, replace: Record<string, any> = {}, locale?: string): string { return this.translations.choice(key, count, replace, locale); }
+    trans_choice(key: string, count: number, replace: Record<string, any> = {}, locale?: string): string { return this.choice(key, count, replace, locale); }
+
+    setLocale(locale: string): void {
+        if (!this.translations.setLocale(locale)) return;
+        this.syncLocale();
+        this.App?.View?.invalidateLocale?.();
+        const route = this.App?.Router?.getCurrentRoute?.();
+        if (route) this.App.Router.replace(route.$uri + (route.$fragment ? '#' + route.$fragment : ''));
+        if (typeof document !== 'undefined') document.dispatchEvent(new CustomEvent('saola:locale-change', { detail: { locale } }));
+    }
+
+    private syncLocale(): void {
+        const locale = this.getLocale();
+        if (typeof document !== 'undefined') document.documentElement.lang = locale;
+        this.App?.Http?.setHeader?.('Accept-Language', locale);
+        this.App?.API?.getHttpService?.()?.setHeader?.('Accept-Language', locale);
+    }
+
     // ─── Execution ──────────────────────────────────────────────
 
     /** Execute a function safely, return result or empty string on error */