@saolabs/client 1.0.0 → 1.1.0

package/src/core/bootstrap/providers/index.ts

@@ -1,9 +1,9 @@
-export { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from './provider-order';
-export type { ProviderName } from './provider-order';
-export { ServiceProvider } from './ServiceProvider';
-export { buildDefaultProviders } from './default-providers';
-export { CoreServiceProvider } from './CoreServiceProvider';
-export { ViewServiceProvider } from './ViewServiceProvider';
-export { RouteServiceProvider } from './RouteServiceProvider';
-export { HelperServiceProvider } from './HelperServiceProvider';
-export { ApiServiceProvider } from './ApiServiceProvider';
+export { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from './provider-order.js';
+export type { ProviderName } from './provider-order.js';
+export { ServiceProvider } from './ServiceProvider.js';
+export { buildDefaultProviders } from './default-providers.js';
+export { CoreServiceProvider } from './CoreServiceProvider.js';
+export { ViewServiceProvider } from './ViewServiceProvider.js';
+export { RouteServiceProvider } from './RouteServiceProvider.js';
+export { HelperServiceProvider } from './HelperServiceProvider.js';
+export { ApiServiceProvider } from './ApiServiceProvider.js';

package/src/core/bootstrap/providers/provider-order.test.ts

@@ -1,14 +1,11 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it, expect } from "vitest";
 import { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from "./provider-order";
 
 function provider(name: string, dependsOn: string[] = []): NamedServiceProvider {
     return {
         name,
         dependsOn,
-        register() {
-            // noop for ordering test
-        }
+        register() {},
     };
 }
 
@@ -22,7 +19,7 @@ describe("resolveProviderOrder", () => {
         ]);
 
         const names = ordered.map((item) => item.name);
-        assert.deepEqual(names, ["core", "view", "router", "api"]);
+        expect(names).toEqual(["core", "view", "router", "api"]);
     });
 
     it("works with PROVIDER_NAMES constants", () => {
@@ -33,35 +30,27 @@ describe("resolveProviderOrder", () => {
         ]);
 
         const names = ordered.map((p) => p.name);
-        assert.equal(names.indexOf(PROVIDER_NAMES.CORE), 0);
-        assert.ok(names.indexOf(PROVIDER_NAMES.VIEW) < names.indexOf(PROVIDER_NAMES.ROUTER));
+        expect(names.indexOf(PROVIDER_NAMES.CORE)).toBe(0);
+        expect(names.indexOf(PROVIDER_NAMES.VIEW)).toBeLessThan(names.indexOf(PROVIDER_NAMES.ROUTER));
     });
 
     it("throws for missing dependency", () => {
-        assert.throws(
-            () => resolveProviderOrder([provider("view", ["core"])]),
-            /Missing provider dependency/
-        );
+        expect(() => resolveProviderOrder([provider("view", ["core"])]))
+            .toThrow(/Missing provider dependency/);
     });
 
     it("throws for circular dependency", () => {
-        assert.throws(
-            () => resolveProviderOrder([
-                provider("a", ["b"]),
-                provider("b", ["c"]),
-                provider("c", ["a"])
-            ]),
-            /Circular service provider dependency/
-        );
+        expect(() => resolveProviderOrder([
+            provider("a", ["b"]),
+            provider("b", ["c"]),
+            provider("c", ["a"])
+        ])).toThrow(/Circular service provider dependency/);
     });
 
     it("throws for duplicate provider names", () => {
-        assert.throws(
-            () => resolveProviderOrder([
-                provider("core"),
-                provider("core")
-            ]),
-            /Duplicate provider name/
-        );
+        expect(() => resolveProviderOrder([
+            provider("core"),
+            provider("core")
+        ])).toThrow(/Duplicate provider name/);
     });
 });

package/src/core/bootstrap/providers/provider-order.ts

@@ -1,4 +1,4 @@
-import type { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface";
+import type { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface.js";
 
 /**
  * Tên các provider mặc định — dùng constant thay vì magic string.

package/src/core/bootstrap/ssr.ts

@@ -0,0 +1,141 @@
+/**
+ * SSR boot detection — đọc thông tin server nhúng để hydrate route đầu tiên.
+ * Tham chiếu: RUNTIME_CONTRACT.md §6 (Hydration boot).
+ */
+
+/** Thông tin boot server nhúng cho trang server-rendered. */
+export interface SSRBootInfo {
+    /** Registry path của page entry (vd 'web.modules.home'). */
+    view: string;
+    /** viewId server đã dùng prefix markers/classes của page. */
+    viewId: string;
+    /** CSS selector container chứa SSR HTML (mặc định '#app-root'). */
+    container?: string;
+}
+
+/**
+ * Đọc SSR boot info từ DOM:
+ *
+ *   <script type="application/json" data-ref="saola-ssr">
+ *     { "container": "#app-root", "view": "web.modules.home", "viewId": "v_abc" }
+ *   </script>
+ *
+ * viewId của layout chain được đọc từ APP_CONFIGS.view.ssrData khi server có
+ * cung cấp; DOM marker chỉ là fallback tương thích cho output cũ.
+ * Trả null nếu không phải trang server-rendered → CSR boot bình thường.
+ */
+export function readSSRBoot(): SSRBootInfo | null {
+    if (typeof document === 'undefined') return null;
+    const el = document.querySelector('script[type="application/json"][data-ref="saola-ssr"]');
+    if (!el || !el.textContent) return null;
+    try {
+        const info = JSON.parse(el.textContent);
+        if (info && typeof info.view === 'string' && typeof info.viewId === 'string') {
+            return {
+                view: info.view,
+                viewId: info.viewId,
+                container: typeof info.container === 'string' ? info.container : undefined,
+            };
+        }
+    } catch (e) {
+        console.warn('[Bootstrap] SSR boot JSON không hợp lệ:', e);
+    }
+    return null;
+}
+
+/**
+ * Đọc boot config server nhúng qua `window.APP_CONFIGS` (contract server hiện tại)
+ * và map về shape config của client (`{ view, router, api }`).
+ *
+ * Server (`_system/page/end.blade.php`) đã emit:
+ *   window.APP_CONFIGS = {
+ *     container: '#app-root',
+ *     router: { mode, base, allRoutes: [{name,path,params,component}], ... },
+ *     ...
+ *   }
+ * `allRoutes` đã đúng shape `Router.addRoutes` cần ({path, component}).
+ *
+ * Trả null nếu không có APP_CONFIGS (→ app tự truyền config cho App.start).
+ */
+export function readBootConfig(): Record<string, any> | null {
+    if (typeof window === 'undefined') return null;
+    const cfg = (window as any).APP_CONFIGS;
+    if (!cfg || typeof cfg !== 'object') return null;
+
+    const out: Record<string, any> = {};
+    if (cfg.i18n && typeof cfg.i18n === "object") out.i18n = cfg.i18n;
+
+    // view.systemData (server: __layout__/__base__/__page__/...) PHẢI tới được
+    // ViewManager: compiled factory destructure `__layout__` từ systemData để
+    // resolve superView (`${__layout__+"base"}`). Thiếu → 'undefinedbase' →
+    // "View not found in registry" + page render() trả rỗng.
+    const view: Record<string, any> = {};
+    if (typeof cfg.container === 'string') {
+        view.container = cfg.container;
+    }
+    if (typeof cfg.view?.dataEndpoint === 'string') view.dataEndpoint = cfg.view.dataEndpoint;
+    if (cfg.view?.fetchOptions && typeof cfg.view.fetchOptions === 'object') view.fetchOptions = cfg.view.fetchOptions;
+    if (cfg.api && typeof cfg.api === 'object') out.api = cfg.api;
+
+    if (cfg.view?.systemData && typeof cfg.view.systemData === 'object') {
+        view.systemData = cfg.view.systemData;
+    }
+    if (typeof cfg.view?.revision === 'string') {
+        view.revision = cfg.view.revision;
+    }
+    if (typeof cfg.view?.contextViews === 'string') {
+        view.contextViews = cfg.view.contextViews;
+    }
+    if (cfg.view?.ssrData && typeof cfg.view.ssrData === 'object') {
+        view.ssrData = cfg.view.ssrData;
+    }
+    if (Object.keys(view).length > 0) {
+        out.view = view;
+    }
+
+    // Danh sách bundle nạp rời (theme…) — server là chỗ DUY NHẤT biết theme nào
+    // đang bật, nên client không đoán đường dẫn. Xem EXTENSION_ARCHITECTURE §8.
+    // Dữ liệu package chia sẻ cho client (Saola::share phía PHP), đọc qua App.shared().
+    if (cfg.shared && typeof cfg.shared === 'object' && !Array.isArray(cfg.shared)) {
+        out.shared = cfg.shared;
+    }
+
+    if (Array.isArray(cfg.bundles)) {
+        out.bundles = cfg.bundles.filter((u: unknown) => typeof u === 'string' && u !== '');
+    }
+
+    const routes = cfg.router?.allRoutes ?? cfg.router?.routes;
+    if (Array.isArray(routes)) {
+        out.router = {
+            mode: cfg.router?.mode ?? 'history',
+            base: cfg.router?.base,
+            defaultRoute: cfg.router?.defaultRoute,
+            routes,
+        };
+    }
+
+    return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Merge nông 2 tầng config boot (base) với config app truyền (override).
+ * Per top-level key (view/router/api): nếu cả hai là object thì merge nông,
+ * ngược lại override thắng. Dùng để config app truyền có ưu tiên hơn boot.
+ */
+export function mergeBootConfig(
+    base: Record<string, any>,
+    override: Record<string, any>
+): Record<string, any> {
+    const out: Record<string, any> = { ...base };
+    for (const key of Object.keys(override)) {
+        const b = out[key];
+        const o = override[key];
+        if (b && o && typeof b === 'object' && typeof o === 'object'
+            && !Array.isArray(b) && !Array.isArray(o)) {
+            out[key] = { ...b, ...o };
+        } else {
+            out[key] = o;
+        }
+    }
+    return out;
+}

package/src/core/cache/ViewCache.ts

@@ -1,4 +1,4 @@
-import type { ViewCacheInterface } from "../contracts/ViewCacheInterface";
+import type { ViewCacheInterface } from "../contracts/ViewCacheInterface.js";
 
 /**
  * ViewCache — stores rendered view DOM for instant restore on navigation.

package/src/core/cache/index.ts

@@ -1 +1 @@
-export { ViewCache } from './ViewCache';
+export { ViewCache } from './ViewCache.js';

package/src/core/contracts/ApplicationInterface.ts

@@ -1,15 +1,16 @@
 // ─── Application Interface ───────────────────────────────────────
 
-import { RouterInterface, ViewManagerInterface } from "./utils";
-import type { HelperInterface } from "./HelperInterface";
-import type { EventServiceInterface } from "./EventServiceInterface";
-import type { HttpServiceInterface } from "./HttpServiceInterface";
-import type { StoreServiceInterface } from "./StoreServiceInterface";
-import type { StorageServiceInterface } from "./StorageServiceInterface";
-import type { LoggerServiceInterface } from "./LoggerServiceInterface";
-import { APIClientInterface } from "./ApiInterface";
-import type { ServiceProviderInterface } from "./ServiceProviderInterface";
-import { OneObjectType } from "../types/utils";
+import { RouterInterface, ViewManagerInterface } from "./utils.js";
+import type { HelperInterface } from "./HelperInterface.js";
+import type { EventServiceInterface } from "./EventServiceInterface.js";
+import type { HttpServiceInterface } from "./HttpServiceInterface.js";
+import type { StoreServiceInterface } from "./StoreServiceInterface.js";
+import type { StorageServiceInterface } from "./StorageServiceInterface.js";
+import type { LoggerServiceInterface } from "./LoggerServiceInterface.js";
+import type { HeadServiceInterface } from "./HeadServiceInterface.js";
+import { APIClientInterface } from "./ApiInterface.js";
+import type { ServiceProviderInterface } from "./ServiceProviderInterface.js";
+import { SaoObjectType } from "../types/utils.js";
 
 export interface ApplicationInterface {
     [key: string]: any;
@@ -29,8 +30,10 @@ export interface ApplicationInterface {
     set<T = any>(name: string, method: T, isOne?: boolean): void;
     setMethod(name: string, method: Function, isOne?: boolean): void;
     get<T = any>(name: string): T;
+    /** Dữ liệu package PHP chia sẻ (`APP_CONFIGS.shared`); không có khoá thì trả `fallback`. */
+    shared<T = any>(key?: string, fallback?: T): T;
 
-    oneType?: OneObjectType;
+    saoType?: SaoObjectType;
 
     // Service properties — set during bootstrap via App.set()
     isInitialized: boolean;
@@ -44,6 +47,7 @@ export interface ApplicationInterface {
     Store: StoreServiceInterface;
     Storage: StorageServiceInterface;
     Logger: LoggerServiceInterface;
+    Head: HeadServiceInterface;
 }
 
 // ─── App Factory (helper function type) ─────────────────────────

package/src/core/contracts/BlockInterface.ts

@@ -1,7 +1,7 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { HtmlInterface, FragmentInterface, OneChildrenFactoryOutput, OneNodeInterface } from "./ElementInterface";
-import { InitMode } from "./common";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { HtmlInterface, FragmentInterface, SaoChildrenFactoryOutput, SaoNodeInterface } from "./ElementInterface.js";
+import { InitMode } from "./common.js";
 
 // ─── Block / Layout Interfaces ───────────────────────────────────
 export type BlockConstructorParams = {
@@ -13,7 +13,7 @@ export type BlockConstructorParams = {
     initMode?: InitMode;
 };
 export interface BlockInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     /** Unique block slot name (e.g. 'content', 'sidebar') */
     name: string;
     id: string;
@@ -24,30 +24,30 @@ export interface BlockInterface {
     fragment: FragmentInterface | null;
     parentElement: HtmlInterface | null;
     domChildren: Node[];
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneBlock: boolean;
     initMode?: InitMode;
-     /** Initialize the block (e.g. during hydration) */
+    /** Initialize the block (e.g. during hydration) */
     init(): void;
-     /** Render the block's content into the parent element */
+    /** Render the block's content into the parent element */
     render(): void;
-     /** Mount the block's content into the DOM, finding matching outlets */
+    /** Mount the block's content into the DOM, finding matching outlets */
     mount(mountCtx: ViewControllerInterface, parentElement: HtmlInterface): any;
-     /** Unmount the block's content from the DOM */
+    /** Unmount the block's content from the DOM */
     unmount(): void;
-     /** Destroy the block and clean up resources */
+    /** Destroy the block and clean up resources */
     destroy(): void;
-     /** Update the block's content (e.g. on state change) */
+    /** Update the block's content (e.g. on state change) */
     update(): void;
-     /** Set the block's parent element (used for mounting) */
+    /** Set the block's parent element (used for mounting) */
     setParentElement(parentElement: HtmlInterface | null): void;
 
     contentRenderFactory: BlockRenderFactory | null;
     // new(params: BlockConstructorParams, ...args: any[]): BlockInterface;
 }
 
-export interface BlockOutletInterface extends OneNodeInterface {
-    oneType: OneObjectType;
+export interface BlockOutletInterface extends SaoNodeInterface {
+    saoType: SaoObjectType;
     id: string;
     name: string;
     parent: HtmlInterface | null;
@@ -56,9 +56,9 @@ export interface BlockOutletInterface extends OneNodeInterface {
     parentElement: HtmlInterface | null;
     ctx: ViewControllerInterface;
     initMode: InitMode;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneBlockOutlet: boolean;
-     /** Render the outlet's markers into the parent element */
+    /** Render the outlet's markers into the parent element */
     render(): any;
     hydrate(): any;
     destroy(): any;
@@ -73,4 +73,4 @@ export interface BlockManagerInterface {
 
 // ─── Block Types ────────────────────────────────────────────────
 
-export type BlockRenderFactory = (parentElement: HtmlInterface) => OneChildrenFactoryOutput;
+export type BlockRenderFactory = (parentElement: HtmlInterface) => SaoChildrenFactoryOutput;

package/src/core/contracts/BundleInterface.ts

@@ -0,0 +1,40 @@
+import type { ApplicationInterface } from "./ApplicationInterface.js";
+import type { ServiceProviderInterface } from "./ServiceProviderInterface.js";
+
+/** Factory view mà registry nhận: đồng bộ, hoặc lazy trả Promise<module>. */
+export type ViewFactory = ((...args: any[]) => any) | (() => Promise<any>);
+
+/**
+ * Manifest của một bundle nạp rời (theme, gói mở rộng).
+ *
+ * Cùng MỘT hình dạng cho mọi loại bundle: file chỉ có view thì điền `views`,
+ * file chỉ có code thì điền `providers`/`services`. Hai shape khác nhau = hai
+ * nhánh loader = hai chỗ để lệch.
+ */
+export interface SaolaBundle {
+    /** Định danh, dùng để báo lỗi và bắt trùng tên. */
+    name?: string;
+    /** Provider của bundle — class hoặc instance, đưa thẳng vào resolveProviderOrder. */
+    providers?: any[];
+    /** { Tên: Class | instance | object } → App.set(tên, …). */
+    services?: Record<string, any>;
+    /** { tên: fn } → gộp vào App.Helper. */
+    helpers?: Record<string, any>;
+    /** { 'dot.path': factory } → View.setViewRegistry(). Nạp sau ĐÈ nạp trước. */
+    views?: Record<string, ViewFactory>;
+    /** Chạy sau khi mọi bundle đã merge và App đã init. */
+    boot?(app: ApplicationInterface): void;
+}
+
+/** Kết quả gộp nhiều bundle, theo đúng thứ tự mảng URL. */
+export interface MergedBundles {
+    providers: (ServiceProviderInterface | any)[];
+    services: Record<string, any>;
+    helpers: Record<string, any>;
+    views: Record<string, ViewFactory>;
+    boots: Array<(app: ApplicationInterface) => void>;
+    /** Tên (hoặc URL) của bundle đã nạp được. */
+    loaded: string[];
+    /** [url, thông điệp lỗi] — nạp hỏng thì bỏ qua, KHÔNG làm sập boot. */
+    failed: Array<[string, string]>;
+}

package/src/core/contracts/ComponentInterface.ts

@@ -1,12 +1,12 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { ViewInterface } from "./ViewInterface";
-import type { HtmlInterface } from "./ElementInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { ViewInterface } from "./ViewInterface.js";
+import type { HtmlInterface } from "./ElementInterface.js";
 
 // ─── Component Interface ─────────────────────────────────────────
 
 export interface ComponentInterface {
-    oneType: OneObjectType;
+    saoType: SaoObjectType;
     id: string;
     ctx: ViewControllerInterface;
     viewRef: ViewInterface | null;
@@ -15,12 +15,13 @@ export interface ComponentInterface {
     openTag: Comment;
     closeTag: Comment;
     stateKeys: string[];
+    listeners: Record<string, (...args: any[]) => any>;
     subscribeFn: () => void;
     unsubscribeFn: () => void;
     render(): void;
     destroy(): void;
     setParent(parent: HtmlInterface | null): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneComponent: boolean;
     [key: string]: any;
 }