@saolabs/client 1.0.0

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

@@ -0,0 +1,51 @@
+import { ApplicationInterface } from "../../contracts/ApplicationInterface";
+import { ServiceProviderInterface } from "../../contracts/utils";
+import { app } from "../../hellpers/app";
+import { OneObjectType, OOTEnum } from "../../types/utils";
+import { NamedServiceProvider } from "./provider-order";
+
+/**
+ * Base class cho Service Provider — API giống Laravel.
+ *
+ * Subclass chỉ cần:
+ * - Khai báo `name` và `dependsOn`
+ * - Override `register()` để bind services (dùng `this.app`)
+ * - Override `boot()` để init services sau khi tất cả đã register
+ *
+ * @example
+ * class AuthServiceProvider extends ServiceProvider {
+ *     readonly name = 'auth';
+ *     readonly dependsOn = ['core', 'api'];
+ *
+ *     register() {
+ *         this.app.set('Auth', new AuthService(this.app));
+ *     }
+ *
+ *     boot() {
+ *         this.app.get('Auth').loadUser();
+ *     }
+ * }
+ */
+export abstract class ServiceProvider implements ServiceProviderInterface {
+    readonly oneType: OneObjectType = OOTEnum.SERVICE_PROVIDER;
+    abstract readonly name: string;
+    readonly dependsOn?: string[];
+    protected app: ApplicationInterface;
+
+    constructor(application?: ApplicationInterface) {
+        this.app = application ?? app<ApplicationInterface>();
+        this.initApplication();
+    }
+
+    initApplication(App?: ApplicationInterface): void {
+        if (!this.app || typeof this.app !== 'object' || this.app.oneType !== OOTEnum.APPLICATION) {
+            this.app = (App && App.oneType === OOTEnum.APPLICATION) ? App : app<ApplicationInterface>();
+        }
+    }
+
+    /** Override để đăng ký services vào container */
+    register(): void {}
+
+    /** Override để init services sau khi tất cả providers đã register */
+    boot(): void {}
+}

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

@@ -0,0 +1,17 @@
+import { ViewManager } from "../../view";
+import { PROVIDER_NAMES } from "./provider-order";
+import { ServiceProvider } from "./ServiceProvider";
+
+export class ViewServiceProvider extends ServiceProvider {
+    readonly name = PROVIDER_NAMES.VIEW;
+    readonly dependsOn = [PROVIDER_NAMES.CORE];
+    static config: Record<string, any> = {};
+
+    register(): void {
+        this.app.set<ViewManager>("View", new ViewManager(this.app), true);
+    }
+
+    boot(): void {
+        this.app.get<ViewManager>("View").init(ViewServiceProvider.config);
+    }
+}

package/src/core/bootstrap/providers/default-providers.ts

@@ -0,0 +1,94 @@
+import { ApplicationInterface } from "../../contracts/ApplicationInterface";
+import { app } from "../../hellpers/app";
+import { NamedServiceProvider, PROVIDER_NAMES } from "./provider-order";
+import { ApiServiceProvider } from "./ApiServiceProvider";
+import { CoreServiceProvider } from "./CoreServiceProvider";
+import { HelperServiceProvider } from "./HelperServiceProvider";
+import { RouteServiceProvider } from "./RouteServiceProvider";
+import { ServiceProvider } from "./ServiceProvider";
+import { ViewServiceProvider } from "./ViewServiceProvider";
+import { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface";
+import { OOTEnum } from "../../types/utils";
+
+/** Provider class type — constructor nhận optional app */
+type ProviderClass = new (app?: ApplicationInterface) => ServiceProvider;
+
+/** Tên system providers — không cho phép override */
+const SYSTEM_PROVIDER_NAMES = new Set(Object.values(PROVIDER_NAMES));
+
+/** Tên system services — không cho phép ghi đè qua config.services */
+const SYSTEM_SERVICE_KEYS = new Set(['Marker', 'Store', 'Storage', 'Event', 'Http', 'View', 'Router', 'Helper', 'API']);
+
+/**
+ * Chuyển `config.services` dạng { name: Class } thành NamedServiceProvider[].
+ *
+ * @example
+ * services: { Auth: AuthService, Toast: ToastService }
+ * → 2 providers, mỗi cái dependsOn ['core'], register = app.set(name, new Class(app))
+ */
+function servicesFromMap(map: Record<string, new (app: ApplicationInterface) => any>): ServiceProviderInterface[] {
+    const appInstance = app<ApplicationInterface>();
+    return Object.entries(map)
+        .filter(([name]) => {
+            if (SYSTEM_SERVICE_KEYS.has(name)) {
+                console.warn(`[Bootstrap] Cannot override system service "${name}" via config.services. Ignored.`);
+                return false;
+            }
+            return true;
+        })
+        .map(([name, ServiceClass]) => ({
+            name,
+            dependsOn: [PROVIDER_NAMES.CORE],
+            register() {
+                appInstance.set(name, new ServiceClass(appInstance));
+            }
+        }));
+}
+
+/**
+ * Tạo danh sách providers mặc định.
+ *
+ * Hỗ trợ:
+ * - Config cho service mặc định: `config.view`, `config.router`, `config.api`
+ * - Liệt kê provider class: `config.providers = [AuthServiceProvider, NotificationProvider]`
+ * - Liệt kê provider instance: `config.providers = [new AuthServiceProvider()]`
+ * - Đăng ký service đơn giản: `config.services = { Auth: AuthService, Toast: ToastService }`
+ *
+ * System providers (core, view, router, helper, api) luôn chạy trước và không thể bị ghi đè.
+ */
+export function buildDefaultProviders(config: Record<string, any> = {}): NamedServiceProvider[] {
+    // Set static config cho default providers trước khi tạo instance
+    ViewServiceProvider.config = config.view || {};
+    RouteServiceProvider.config = config.router || {};
+    ApiServiceProvider.config = config.api || {};
+    const App = app<ApplicationInterface>();
+    const defaults: NamedServiceProvider[] = [
+        CoreServiceProvider,
+        ViewServiceProvider,
+        RouteServiceProvider,
+        HelperServiceProvider,
+        ApiServiceProvider,
+    ].map(Cls => new Cls(App));
+
+    // config.services: { Name: Class } → auto-wrap providers
+    const serviceProviders = config.services
+        ? servicesFromMap(config.services)
+        : [];
+
+    // config.providers: (ProviderClass | NamedServiceProvider)[] → instantiate classes
+    const customProviders: NamedServiceProvider[] = Array.isArray(config.providers)
+        ? config.providers
+            .map((p: ProviderClass | NamedServiceProvider) =>
+                typeof p === 'function' ? new p(App) : p
+            )
+            .filter(p => {
+                if (SYSTEM_PROVIDER_NAMES.has(p.name as any)) {
+                    console.warn(`[Bootstrap] Cannot override system provider "${p.name}". Ignored.`);
+                    return false;
+                }
+                return true;
+            })
+        : [];
+
+    return [...defaults, ...serviceProviders, ...customProviders];
+}

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

@@ -0,0 +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';

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

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { NamedServiceProvider, resolveProviderOrder, PROVIDER_NAMES } from "./provider-order";
+
+function provider(name: string, dependsOn: string[] = []): NamedServiceProvider {
+    return {
+        name,
+        dependsOn,
+        register() {
+            // noop for ordering test
+        }
+    };
+}
+
+describe("resolveProviderOrder", () => {
+    it("orders providers by dependency graph", () => {
+        const ordered = resolveProviderOrder([
+            provider("router", ["view"]),
+            provider("api", ["core"]),
+            provider("view", ["core"]),
+            provider("core")
+        ]);
+
+        const names = ordered.map((item) => item.name);
+        assert.deepEqual(names, ["core", "view", "router", "api"]);
+    });
+
+    it("works with PROVIDER_NAMES constants", () => {
+        const ordered = resolveProviderOrder([
+            provider(PROVIDER_NAMES.ROUTER, [PROVIDER_NAMES.VIEW]),
+            provider(PROVIDER_NAMES.VIEW, [PROVIDER_NAMES.CORE]),
+            provider(PROVIDER_NAMES.CORE),
+        ]);
+
+        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));
+    });
+
+    it("throws for missing dependency", () => {
+        assert.throws(
+            () => resolveProviderOrder([provider("view", ["core"])]),
+            /Missing provider dependency/
+        );
+    });
+
+    it("throws for circular dependency", () => {
+        assert.throws(
+            () => resolveProviderOrder([
+                provider("a", ["b"]),
+                provider("b", ["c"]),
+                provider("c", ["a"])
+            ]),
+            /Circular service provider dependency/
+        );
+    });
+
+    it("throws for duplicate provider names", () => {
+        assert.throws(
+            () => resolveProviderOrder([
+                provider("core"),
+                provider("core")
+            ]),
+            /Duplicate provider name/
+        );
+    });
+});

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

@@ -0,0 +1,66 @@
+import type { ServiceProviderInterface } from "../../contracts/ServiceProviderInterface";
+
+/**
+ * Tên các provider mặc định — dùng constant thay vì magic string.
+ * Custom providers có thể dùng tên khác hoặc override tên mặc định.
+ */
+export const PROVIDER_NAMES = {
+    CORE: 'core',
+    VIEW: 'view',
+    ROUTER: 'router',
+    HELPER: 'helper',
+    API: 'api',
+} as const;
+
+export type ProviderName = typeof PROVIDER_NAMES[keyof typeof PROVIDER_NAMES];
+
+export type NamedServiceProvider = ServiceProviderInterface & {
+    name: string;
+    dependsOn?: string[];
+};
+
+export function resolveProviderOrder(providers: ServiceProviderInterface[]): ServiceProviderInterface[] {
+    const providerMap = new Map<string, ServiceProviderInterface>();
+    for (const provider of providers) {
+        if (!provider.name) {
+            throw new Error(`[Bootstrap] Provider name is required.`);
+        }
+        if (providerMap.has(provider.name)) {
+            throw new Error(`[Bootstrap] Duplicate provider name detected: "${provider.name}".`);
+        }
+        providerMap.set(provider.name, provider);
+    }
+
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const ordered: ServiceProviderInterface[] = [];
+
+    const visit = (name: string): void => {
+        if (visited.has(name)) return;
+        if (inStack.has(name)) {
+            throw new Error(`[Bootstrap] Circular service provider dependency detected at "${name}".`);
+        }
+
+        const provider = providerMap.get(name);
+        if (!provider) {
+            throw new Error(`[Bootstrap] Missing provider dependency: "${name}".`);
+        }
+
+        inStack.add(name);
+        for (const dep of provider.dependsOn ?? []) {
+            visit(dep);
+        }
+        inStack.delete(name);
+
+        visited.add(name);
+        ordered.push(provider);
+    };
+
+    for (const provider of providers) {
+        if (provider.name) {
+            visit(provider.name);
+        }
+    }
+
+    return ordered;
+}

package/src/core/cache/ViewCache.ts

@@ -0,0 +1,102 @@
+import type { ViewCacheInterface } from "../contracts/ViewCacheInterface";
+
+/**
+ * ViewCache — stores rendered view DOM for instant restore on navigation.
+ * 
+ * When a user navigates away from a page, the view's DOM is detached and
+ * stored in a DocumentFragment. When navigating back, the DOM is
+ * re-attached instead of re-rendered — preserving form inputs, scroll
+ * positions, and in-progress user work.
+ * 
+ * Used by the router/BlockManager to implement "keep-alive" behavior.
+ * 
+ * @example
+ * // Router navigates away from 'home'
+ * cache.store('home', homeRootElement);
+ * 
+ * // Router navigates back to 'home'
+ * const cached = cache.retrieve('home');
+ * if (cached) container.appendChild(cached); // instant restore!
+ */
+export class ViewCache implements ViewCacheInterface {
+    private cache: Map<string, HTMLElement | DocumentFragment> = new Map();
+
+    /** Maximum cached views (LRU eviction when exceeded) */
+    private maxSize: number;
+
+    /** Access order tracking for LRU */
+    private accessOrder: string[] = [];
+
+    constructor(maxSize: number = 10) {
+        this.maxSize = maxSize;
+    }
+
+    /** Store a view's DOM state */
+    store(viewId: string, element: HTMLElement | DocumentFragment): void {
+        // If already cached, update
+        if (this.cache.has(viewId)) {
+            this.cache.set(viewId, element);
+            this.touchAccess(viewId);
+            return;
+        }
+
+        // Evict oldest if at capacity
+        if (this.cache.size >= this.maxSize) {
+            this.evictOldest();
+        }
+
+        this.cache.set(viewId, element);
+        this.accessOrder.push(viewId);
+    }
+
+    /** Retrieve cached DOM — returns null if not cached */
+    retrieve(viewId: string): HTMLElement | DocumentFragment | null {
+        const cached = this.cache.get(viewId) ?? null;
+        if (cached) {
+            this.touchAccess(viewId);
+        }
+        return cached;
+    }
+
+    /** Check if a view is cached */
+    has(viewId: string): boolean {
+        return this.cache.has(viewId);
+    }
+
+    /** Remove a specific view from cache */
+    remove(viewId: string): void {
+        this.cache.delete(viewId);
+        this.accessOrder = this.accessOrder.filter(id => id !== viewId);
+    }
+
+    /** Clear all cached views */
+    clear(): void {
+        this.cache.clear();
+        this.accessOrder = [];
+    }
+
+    /** Get number of cached views */
+    get size(): number {
+        return this.cache.size;
+    }
+
+    /** Get all cached view IDs */
+    keys(): string[] {
+        return [...this.cache.keys()];
+    }
+
+    // ─── Private ────────────────────────────────────────────────
+
+    /** Move viewId to end of access order (most recently used) */
+    private touchAccess(viewId: string): void {
+        this.accessOrder = this.accessOrder.filter(id => id !== viewId);
+        this.accessOrder.push(viewId);
+    }
+
+    /** Remove the least recently used cached view */
+    private evictOldest(): void {
+        if (this.accessOrder.length === 0) return;
+        const oldest = this.accessOrder.shift()!;
+        this.cache.delete(oldest);
+    }
+}

package/src/core/cache/index.ts

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

package/src/core/contracts/ApiInterface.ts

@@ -0,0 +1,11 @@
+import { HttpService } from '../services/HttpService.js';
+
+export interface APIClientInterface {
+    init(config: Record<string, any>): void;
+    getViewData<T = any>(uri: string): Promise<T>;
+    getSystemConfig<T = any>(): Promise<T>;
+    getSystemData<T = any>(): Promise<T>;
+    getURIData<T = any>(): Promise<T>;
+    setEndpoint(key: string, value: string): void;
+    getHttpService(): HttpService;
+}

package/src/core/contracts/ApplicationInterface.ts

@@ -0,0 +1,79 @@
+// ─── 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";
+
+export interface ApplicationInterface {
+    [key: string]: any;
+    transient<T>(key: ServiceKey, value: any): this;
+    bind<T>(key: ServiceKey, value: any): this;
+    singleton<T>(key: ServiceKey, value?: any): this;
+    instance<T>(key: ServiceKey, value: T): this;
+    alias(alias: string | symbol, key: ServiceKey): this;
+    make<T>(key: ServiceKey, defaultValue?: T): T;
+    resolve<T>(key: ServiceKey, defaultValue?: T): T;
+    has(key: ServiceKey): boolean;
+    bound(key: ServiceKey): boolean;
+    register(provider: ServiceProviderInterface): this;
+    boot(): void;
+    flush(): void;
+    destroy(): void;
+    set<T = any>(name: string, method: T, isOne?: boolean): void;
+    setMethod(name: string, method: Function, isOne?: boolean): void;
+    get<T = any>(name: string): T;
+
+    oneType?: OneObjectType;
+
+    // Service properties — set during bootstrap via App.set()
+    isInitialized: boolean;
+    isStarted: boolean;
+    View: ViewManagerInterface;
+    Router: RouterInterface;
+    Helper: HelperInterface;
+    Events: EventServiceInterface;
+    Http: HttpServiceInterface;
+    API: APIClientInterface;
+    Store: StoreServiceInterface;
+    Storage: StorageServiceInterface;
+    Logger: LoggerServiceInterface;
+}
+
+// ─── App Factory (helper function type) ─────────────────────────
+
+/** Type cho helper function app() — callable + có methods */
+export interface AppFactory {
+    <T>(): T;
+    (): ApplicationInterface;
+    <T>(key: ServiceKey): T;
+    (key: ServiceKey, value: any): ApplicationInterface;
+    make<T>(name: ServiceKey): T;
+    make<T>(name: ServiceKey, defaultValue: T): T;
+    instance<T>(name: ServiceKey, value: T): ApplicationInterface;
+    resolve<T>(name: ServiceKey): T;
+    resolve<T>(name: ServiceKey, defaultValue: T): T;
+    register<T>(name: ServiceKey, factory: () => T): ApplicationInterface;
+    bind<T>(name: ServiceKey, factory: () => T): ApplicationInterface;
+    singleton<T>(name: ServiceKey, factory: () => T): ApplicationInterface;
+    has(name: ServiceKey): boolean;
+    flush(): void;
+    destroy(): void;
+}
+
+// ─── Application / DI Types ─────────────────────────────────────
+
+/** Định danh duy nhất cho service: string, symbol, hoặc class constructor */
+export type ServiceKey<T = any> = string | symbol | (new (...args: any[]) => T);
+
+/** Factory function nhận app (container) để resolve dependencies */
+export type ServiceFactory<T> = (app: ApplicationInterface) => T;
+
+/** Giá trị có thể bind: factory function hoặc class constructor */
+export type ServiceBinding<T = any> = ServiceFactory<T> | (new (...args: any[]) => T);

package/src/core/contracts/BlockInterface.ts

@@ -0,0 +1,76 @@
+import type { OneObjectType } from "../types/utils";
+import type { ViewControllerInterface } from "./ViewControllerInterface";
+import type { HtmlInterface, FragmentInterface, OneChildrenFactoryOutput, OneNodeInterface } from "./ElementInterface";
+import { InitMode } from "./common";
+
+// ─── Block / Layout Interfaces ───────────────────────────────────
+export type BlockConstructorParams = {
+    ctx: ViewControllerInterface;
+    name: string;
+    viewId?: string | null;
+    contentRenderFactory?: BlockRenderFactory;
+    id?: string | null;
+    initMode?: InitMode;
+};
+export interface BlockInterface {
+    oneType: OneObjectType;
+    /** Unique block slot name (e.g. 'content', 'sidebar') */
+    name: string;
+    id: string;
+    ctx: ViewControllerInterface;
+    viewId: string | null;
+    openTag: Comment;
+    closeTag: Comment;
+    fragment: FragmentInterface | null;
+    parentElement: HtmlInterface | null;
+    domChildren: Node[];
+    isOneElement: boolean;
+    isOneBlock: boolean;
+    initMode?: InitMode;
+     /** Initialize the block (e.g. during hydration) */
+    init(): void;
+     /** Render the block's content into the parent element */
+    render(): void;
+     /** 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(): void;
+     /** Destroy the block and clean up resources */
+    destroy(): void;
+     /** Update the block's content (e.g. on state change) */
+    update(): void;
+     /** 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;
+    id: string;
+    name: string;
+    parent: HtmlInterface | null;
+    openTag: Comment;
+    closeTag: Comment;
+    parentElement: HtmlInterface | null;
+    ctx: ViewControllerInterface;
+    initMode: InitMode;
+    isOneElement: boolean;
+    isOneBlockOutlet: boolean;
+     /** Render the outlet's markers into the parent element */
+    render(): any;
+    hydrate(): any;
+    destroy(): any;
+    start(): any;
+    stop(): any;
+    setParentElement(parentElement: HtmlInterface | null): any;
+}
+
+export interface BlockManagerInterface {
+
+}
+
+// ─── Block Types ────────────────────────────────────────────────
+
+export type BlockRenderFactory = (parentElement: HtmlInterface) => OneChildrenFactoryOutput;

package/src/core/contracts/ComponentInterface.ts

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