@saolabs/client 1.0.0 → 1.1.0

package/src/core/contracts/ElementInterface.ts

@@ -1,39 +1,45 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { ReactiveInterface } from "./ReactiveInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { ReactiveInterface } from "./ReactiveInterface.js";
 
 // ─── Element Interfaces ──────────────────────────────────────────
 
 /** Base for any renderable node in the tree */
-export interface OneNodeInterface {
-    oneType: OneObjectType;
+export interface SaoNodeInterface {
+    saoType: SaoObjectType;
     parent: HtmlInterface | null;
     render(): void;
     destroy(): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     setParentElement(parent: HtmlInterface | null): void;
     [key: string]: any;
 
 }
 
 /** Native HTML element wrapper */
-export interface HtmlInterface extends OneNodeInterface {
+export interface HtmlInterface extends SaoNodeInterface {
     element: HTMLElement;
     domChildren: Node[];
     [key: string]: any;
+    clearHTML(): void;
+    appendElement(element: HTMLElement | Comment | Text): void;
+    getElement(): HTMLElement;
+    renderChildren(): SaoElementChildren;
+    render(): HTMLElement;
 }
 
 /** Text node wrapper */
-export interface TextInterface extends OneNodeInterface {
+export interface TextInterface extends SaoNodeInterface {
     element: Text;
     text: string;
 
 
     domChildren: Node[];
     update(newText: string): void;
+    render(): HTMLElement | Text | Comment;
 }
 
-export interface OutputInterface extends OneNodeInterface {
+export interface OutputInterface extends SaoNodeInterface {
     ctx: ViewControllerInterface;
     parent: HtmlInterface | null;
     stateKeys: string[];
@@ -43,12 +49,11 @@ export interface OutputInterface extends OneNodeInterface {
     [key: string]: any;
 }
 
-export interface YieldInterface extends OneNodeInterface {
+export interface YieldInterface extends SaoNodeInterface {
     ctx: ViewControllerInterface;
     parent: HtmlInterface | null;
     name: string;
-    contentFactory: () => OneChildrenFactoryOutput;
-    setContentFactory(factory: () => OneChildrenFactoryOutput): void;
+    defaultValue: string;
     openTag: Comment;
     closeTag: Comment;
     domChildren: Node[];
@@ -56,40 +61,84 @@ export interface YieldInterface extends OneNodeInterface {
 }
 
 /** Fragment — renders multiple root nodes into a parent without a wrapping tag */
-export interface FragmentInterface extends OneNodeInterface {
+export interface FragmentInterface extends SaoNodeInterface {
     nodes: Node[];
     domChildren: Node[];
     [key: string]: any;
 
 }
 /** Wrapper — renders multiple root nodes into a parent without a wrapping tag */
-export interface WrapperInterface extends OneNodeInterface {
+export interface WrapperInterface extends SaoNodeInterface {
     nodes: Node[];
     domChildren: Node[];
     [key: string]: any;
+    /** Render — chạy childrenFactory, trả về danh sách children đã tạo. */
+    render(): SaoElementChildren;
+    appendTo(parent: HtmlInterface): void;
+    mountTo(parent: HtmlInterface): void;
+    clear(): void;
+    setChildrenFactory(factory: SaoChildrenFactory): void;
+    children: SaoElementChildren;
+    openTag: Comment;
+    closeTag: Comment;
+
 }
 
 // ─── Element Config Types ────────────────────────────────────────
 
-export type OneElementConfig = {
+/**
+ * Contract chuẩn (RUNTIME_CONTRACT.md §1.1): type = 'static' | 'binding'.
+ * 'value' giữ làm legacy alias của 'static' đến v0.2.
+ */
+export type BindingConfigType = 'static' | 'binding' | 'value';
+
+export type SaoElementConfig = {
+    /** Marker-free content for HTML RCDATA elements (textarea/title). */
+    content?: {
+        factory: () => any;
+        stateKeys?: string[];
+    },
     attrs?: {
         [key: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: any;
             stateKeys?: string[];
             factory?: () => any;
+            /** `@yield(name, ...)` used as the whole attribute value — no static stateKeys
+             *  (the section it resolves to is only known at runtime), so Html subscribes to
+             *  SectionManager by name instead. */
+            yieldName?: string;
         }
     },
     props?: {
         [key: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: any;
             stateKeys?: string[];
             factory?: () => any;
         }
     },
     events?: {
-        [key: string]: OneElementEventHandler;
+        [key: string]: SaoElementEventHandler;
+    },
+    /**
+     * `@click.prevent.stop(...)` — bucket RIÊNG cạnh `events` để shape
+     * `events: {click: [...]}` (contract sẵn có) không đổi; view compile trước
+     * khi có modifier không có key này và chạy y nguyên.
+     */
+    eventModifiers?: {
+        [key: string]: EventModifier[];
+    },
+    /** `@bind(key)`/`@val(key)` — two-way binding, own bucket (sibling of attrs/props/events). */
+    bind?: {
+        key: string;
+    },
+    /**
+     * `@transition('fade')` — tiền tố class enter/leave (`fade-enter-from`, ...).
+     * Bucket riêng như `bind`/`eventModifiers`; vắng mặt = hành vi cũ y nguyên.
+     */
+    transition?: {
+        name: string;
     },
     classes?: {
         [className: string]: {
@@ -99,14 +148,15 @@ export type OneElementConfig = {
             factory?: () => boolean;
         }
     } | Array<{
-        type: 'static' | 'binding';
+        /** 'dynamic' = factory trả về TÊN class (`class="language-{{ lang }}"`), không có `value`. */
+        type: 'static' | 'binding' | 'dynamic';
         value?: string;
         stateKeys?: string[];
-        factory?: () => boolean;
+        factory?: () => boolean | string;
     }>,
     styles?: {
         [prop: string]: {
-            type: 'value' | 'binding';
+            type: BindingConfigType;
             value?: string;
             stateKeys?: string[];
             factory?: () => string;
@@ -115,7 +165,7 @@ export type OneElementConfig = {
     [key: string]: any;
 }
 
-export type HtmlElementConfig = OneElementConfig & {
+export type HtmlElementConfig = SaoElementConfig & {
     ctx: ViewControllerInterface;
     parentElement?: HtmlInterface | null;
     parent?: HtmlInterface | null;
@@ -123,18 +173,36 @@ export type HtmlElementConfig = OneElementConfig & {
 
 // ─── Event Handler ──────────────────────────────────────────────
 
-export type OneElementEventHandler = Array<{
+/**
+ * Modifier của `@click.prevent.stop(...)`. Phải khớp `EVENT_MODIFIERS` trong
+ * `compiler/src/sao2js/template_ast.py` — compiler chỉ emit tên trong tập đó.
+ */
+export type EventModifier = 'prevent' | 'stop' | 'self' | 'once';
+
+export type SaoElementEventHandler = Array<{
     handler: string | ((event: Event) => any);
     params?: (any | ((event: Event) => any[]))[];
 } | ((event: Event) => any)>;
 
+export type SaoElement = WrapperInterface | HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface;
+export type DOMElement = HTMLElement | SVGElement | DocumentFragment | Text | Comment;
 // ─── Children Types ─────────────────────────────────────────────
 
 /** All possible rendered child node types */
-export type OneElementChildren = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+export type SaoElementChildren = Array<SaoElement | SaoNodeInterface | DOMElement>;
 
-/** What a children factory can return (before mounting) */
-export type OneChildrenFactoryOutput = Array<HtmlInterface | ReactiveInterface | TextInterface | FragmentInterface | string | number | HTMLElement | SVGElement | DocumentFragment | Text | Comment>;
+/** What a children factory can return (before mounting).
+ *  SaoNodeInterface bao phủ các marker-based element (Output, Component, Block...)
+ *  mà compiled output vẫn trả về trong children factories. */
+export type SaoChildrenFactoryOutput = Array<SaoElement | SaoNodeInterface | DOMElement | string | number | null | undefined>;
 
 /** Factory function that produces children given parent element */
-export type OneChildrenFactory = (parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type SaoChildrenFactory = (parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
+
+/**
+ * Lazy payload passed from a parent component to one ChildrenNode placeholder.
+ * A factory is deliberately not executed while component data is resolved; the
+ * child view invokes it only when its render traversal reaches the placeholder.
+ */
+export type SaoChildrenSlotFactory = SaoChildrenFactory;
+export type SaoChildrenSlotContent = SaoChildrenSlotFactory | string | number | null | undefined;

package/src/core/contracts/HeadServiceInterface.ts

@@ -0,0 +1,41 @@
+// ─── Head Service Interface ───────────────────────────────────────
+
+/**
+ * `'page'` (default) — reverts to whatever was there before on the next
+ * `resetPage()` (called once per SPA navigation), so a tag set by page A
+ * never leaks into page B.
+ * `'persistent'` — survives navigation (site-wide defaults, e.g. a global
+ * robots directive or a fixed title suffix set once at boot).
+ */
+export type HeadTagScope = 'page' | 'persistent';
+
+export interface HeadTagOptions {
+    scope?: HeadTagScope;
+}
+
+export interface HeadLinkOptions extends HeadTagOptions {
+    /** Extra attributes beyond rel/href — e.g. { hreflang: 'vi' } for alternate links. */
+    attrs?: Record<string, string>;
+}
+
+/**
+ * HeadService — manages `<head>` tags (title, meta, link, JSON-LD) directly
+ * against `document`, independent of any View/ViewController. Registered in
+ * the DI container as `App.Head` / `app('Head')` so any code — a view's
+ * render, a route guard, an async data callback, app bootstrap — can call it.
+ */
+export interface HeadServiceInterface {
+    setTitle(title: string, options?: HeadTagOptions): void;
+    /** `<meta name="{name}" content="{content}">` — description, keywords, robots, viewport... */
+    setMeta(name: string, content: string, options?: HeadTagOptions): void;
+    /** `<meta property="{property}" content="{content}">` — Open Graph / Twitter card tags. */
+    setMetaProperty(property: string, content: string, options?: HeadTagOptions): void;
+    /** `<link rel="{rel}" href="{href}" ...attrs>` — canonical, alternate/hreflang, etc. */
+    setLink(rel: string, href: string, options?: HeadLinkOptions): void;
+    /** `<script type="application/ld+json">` — structured data, keyed by `id` (multiple blocks allowed). */
+    setJsonLd(id: string, data: Record<string, any>, options?: HeadTagOptions): void;
+    /** Revert one managed key immediately, regardless of its scope. */
+    unset(key: string): void;
+    /** Revert every `'page'`-scoped tag to its pre-managed state. Called once per navigation. */
+    resetPage(): void;
+}

package/src/core/contracts/HelperInterface.ts

@@ -1,6 +1,6 @@
 // ─── Collection Proxy Interface ─────────────────────────────────
 
-import { ApplicationInterface } from "./ApplicationInterface";
+import { ApplicationInterface } from "./ApplicationInterface.js";
 
 export interface CollectionProxyInterface {
     all(): any[];
@@ -52,6 +52,14 @@ export interface CollectionProxyInterface {
 // ─── Helper Interface ───────────────────────────────────────────
 
 export interface HelperInterface {
+    initTranslations(config: import('../services/TranslationService.js').TranslationConfig): void;
+    getLocale(): string;
+    setLocale(locale: string): void;
+    __(key: string, replace?: Record<string, any>, locale?: string): string;
+    trans(key: string, replace?: Record<string, any>, locale?: string): string;
+    lang(key: string, replace?: Record<string, any>, locale?: string): string;
+    choice(key: string, count: number, replace?: Record<string, any>, locale?: string): string;
+    trans_choice(key: string, count: number, replace?: Record<string, any>, locale?: string): string;
     [key: string]: any;
 
      // ─── App / Service Container ─────────────────────────────────

package/src/core/contracts/HttpServiceInterface.ts

@@ -3,6 +3,8 @@
 export interface HttpRequestConfig extends RequestInit {
     headers?: Record<string, string>;
     timeout?: number;
+    dedupe?: 'cancel-previous' | 'parallel';
+    requestKey?: string;
     [key: string]: any;
 }
 
@@ -45,6 +47,7 @@ export interface HttpServiceInterface {
     cancelAll(): void;
     /** Cancel a specific pending request */
     cancel(url: string, method?: string): void;
+    cancelKey(identity: string, method?: string): void;
 
     /** Destroy — cancel all + clear interceptors */
     destroy(): void;

package/src/core/contracts/MarkerInterface.ts

@@ -24,54 +24,27 @@ export type MarkerTagName =
 // ─── MarkerRegistry Service ─────────────────────────────────────
 
 
-export type MarkerFilter = string | Record<string, any>;
-export interface MarkerRecord {
-    name: string;
-    tagName: string;
-    registryID?: string | null;
-    attributes: Record<string, any>;
-    openTag: Comment;
-    closeTag: Comment;
-    children: Array<Node>;
-    [key: string]: any;
-}
-export interface MarkupAttributes {
-    [key: string]: string;
-}
-
-export interface MarkupQueryOptions {
-    multiple?: boolean;
-    recursive?: boolean;
-}
-
-export interface MarkupQuery {
-    pattern: string;
-    attributes?: MarkupAttributes;
-    options?: MarkupQueryOptions;
-    index?: number;
-}
-
-/**
- * RegistryTag Query Options
- */
-export interface RegistryTagQueryOptions {
-    tag?: string;
-    id?: string;
-    attributes?: Record<string, any>;
-    multiple?: boolean;
-}
+export interface MarkerRegistryInterface {
+    shortcut(tag: string): string;
+    fullTag(shortcut: string): string;
+    registerShortcut(tag: string, short: string): void;
+    register(tag: string, id?: string, attributes?: Record<string, any>): string;
+    createMarkerStart(tag: string, id?: string): Comment;
+    createMarkerEnd(tag: string, id?: string): Comment;
+    get(key: string): MarkerRegistryRecord | null;
+    getByTagAndId(tag: string, id: string): MarkerRegistryRecord | null;
+    has(key: string): boolean;
+    remove(key: string): boolean;
+    getByTag(tag: string): MarkerRegistryRecord[];
+    all(): Map<string, MarkerRegistryRecord>;
+    clear(): void;
+    size: number;
+    openComment(tag: string, id?: string): string;
+    closeComment(tag: string, id?: string): string;
+    parseComment(text: string): { tag: string; id: string; isClose: boolean } | null
+    /** Claim cặp marker SSR theo O(1) qua index (null = server không render vùng này) */
+    claim(tag: string, id: string, scope?: Element | null): { open: Comment; close: Comment } | null;
+    /** Bỏ index marker — gọi đầu mỗi lượt hydrate */
+    invalidateIndex(): void;
 
-/**
- * RegistryTagData
- */
-export interface RegistryTagData {
-    systemPrefix: string;
-    tag: string;
-    id: string;
-    key: string;
-    attributes?: Record<string, any>;
-    nodes: Array<Node>;
 }
-
-
-export type RegistryIDOrAttributes = string | Record<string, any> | undefined;

package/src/core/contracts/ReactiveInterface.ts

@@ -1,12 +1,12 @@
-import type { OneObjectType } from "../types/utils";
-import type { ViewControllerInterface } from "./ViewControllerInterface";
-import type { HtmlInterface, OneChildrenFactoryOutput, OneElementChildren, OneNodeInterface } from "./ElementInterface";
+import type { SaoObjectType } from "../types/utils.js";
+import type { ViewControllerInterface } from "./ViewControllerInterface.js";
+import type { HtmlInterface, SaoChildrenFactoryOutput, SaoElementChildren, SaoNodeInterface } from "./ElementInterface.js";
 
 // ─── Reactive Interface ──────────────────────────────────────────
 
 /** Reactive region bounded by comment markers — re-renders when deps change */
-export interface ReactiveInterface extends OneNodeInterface {
-    oneType: OneObjectType;
+export interface ReactiveInterface extends SaoNodeInterface {
+    saoType: SaoObjectType;
     id: string;
     type: string;
     ctx: ViewControllerInterface;
@@ -15,24 +15,24 @@ export interface ReactiveInterface extends OneNodeInterface {
     parentReactive: ReactiveInterface | null;
     openTag: Comment;
     closeTag: Comment;
-    children: OneElementChildren;
+    children: SaoElementChildren;
     unsubscribe: () => void;
     childrenFactory: ReactiveChildrenFactory;
     setChildrenFactory(factory: ReactiveChildrenFactory): void;
     setStateKeys(stateKeys: string[]): void;
     render(): void;
     destroy(): void;
-    isOneElement: boolean;
+    isSaoElement: boolean;
     isOneReactive: boolean;
 }
 
 // ─── Reactive Types ──────────────────────────────────────────────
 
 /** Function called by Reactive to produce DOM content between markers */
-export type ReactiveRenderFn = (ctx: ViewControllerInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type ReactiveRenderFn = (ctx: ViewControllerInterface, parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
 
 /** Factory function for reactive children rendering */
-export type ReactiveChildrenFactory = (parentReactive: ReactiveInterface, parentElement: HtmlInterface | null) => OneChildrenFactoryOutput;
+export type ReactiveChildrenFactory = (parentReactive: ReactiveInterface, parentElement: HtmlInterface | null) => SaoChildrenFactoryOutput;
 
 /** Reactive configuration */
 export type ReactiveConfig = {

package/src/core/contracts/RouterInterface.ts

@@ -1,4 +1,4 @@
-import type { ViewManagerInterface } from "./ViewManagerInterface";
+import type { ViewManagerInterface } from "./ViewManagerInterface.js";
 
 // ─── Router Interface ────────────────────────────────────────────
 
@@ -18,6 +18,8 @@ export interface ActiveRouteInterface {
     $query: Record<string, any>;
     $params: Record<string, any>;
     $urlPath: string;
+    /** Request URI = path + query (không gồm hash) — cache key phía ViewManager */
+    $uri?: string;
     $fragment: string;
     new(route: RouteInterface, urlPath: string, fragment: string): ActiveRouteInterface;
     setQuery(query: Record<string, any>): void;
@@ -52,7 +54,8 @@ export interface RouterInterface {
     getCurrentRoute(): ActiveRouteInterface | null;
     /** Navigation guards */
     beforeEach(guard: (to: ActiveRouteInterface, from: ActiveRouteInterface, urlPath: string) => boolean | Promise<boolean>): this;
-    afterEach(hook: (to: ActiveRouteInterface, from: ActiveRouteInterface) => void): this;
+    /** Đăng ký hook sau điều hướng; trả về hàm huỷ đăng ký. Nhiều hook cùng sống được. */
+    afterEach(hook: (to: ActiveRouteInterface, from: ActiveRouteInterface) => void): () => void;
     /** Start listening to URL changes */
     start(skipInitial?: boolean): void;
     /** Stop listening */

package/src/core/contracts/SectionInterface.ts

@@ -0,0 +1,49 @@
+import type { SaoElementChildren, 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";
+
+export type SectionItemType = 'static' | 'dynamic' | 'async' | 'reactive';
+export type SectionContentType = 'text' | 'html'
+export type SectionContentRenderer = (parentElement?: HtmlInterface | null | undefined) => string | SaoElementChildren;
+export type SectionConstruvtorArgs = {
+    ctx?: ViewControllerInterface | null;
+    name: string;
+    type: SectionItemType;
+    contentType?: SectionContentType;
+    stateKeys?: string[];
+    renderFactory: SectionContentRenderer;
+    [key: string]: any;
+}
+export interface SectionInterface {
+    ctx? : ViewControllerInterface | null;
+    /** Owning view instance — mirrors Block/BlockOutlet keying (`name` + `viewId`). */
+    viewId?: string | null;
+    name: string;
+    type: SectionItemType;
+    contentType?: SectionContentType;
+    stateKeys?: string[];
+    renderFactory?: SectionContentRenderer;
+}
+export interface SectionManagerInterface {
+    sections: Map<string, SectionInterface>;
+    subscribers: Map<string, ((section: SectionInterface) => void)[]>;
+    add(section: SectionInterface): void;
+    subscribe(name: string, callback: (section: SectionInterface) => void): () => void;
+    unsubscribe(name: string, callback?: (section: SectionInterface) => void): void;
+    /** Register a @yield(...) marker so mountViewSections() can find it by name. */
+    addYield(id: string, yieldEl: any): void;
+    /** Resolve the current value of a named section synchronously — used by `this.yieldContent()` in attribute/prop bindings. */
+    resolve(name: string, defaultValue?: any): any;
+    /** Mount sections owned by one controller (page or layout) into their matching yields. Mirrors BlockManagerService.mountViewBlocks(). */
+    mountViewSections(viewId: string): void;
+    /** Hydrate counterpart — claim SSR content, no DOM insertion, only (re)subscribe. */
+    hydrateViewSections(viewId: string): void;
+    startAll(): void;
+    stopAll(): void;
+    unmountView(viewId: string): void;
+    removeYieldsOfView(viewId: string): void;
+    /** Revert every page-scoped head tag (title/meta) before mounting a new page's chain. */
+    resetPageHead(): void;
+    destroy(): void;
+}

package/src/core/contracts/ServiceProviderInterface.ts

@@ -1,9 +1,9 @@
-import { OneObjectType } from "../types/utils";
-import type { ApplicationInterface } from "./ApplicationInterface";
+import { SaoObjectType } from "../types/utils.js";
+import type { ApplicationInterface } from "./ApplicationInterface.js";
 
 /** Service Provider — register() đăng ký, boot() khởi động */
 export interface ServiceProviderInterface {
-    oneType?: OneObjectType;
+    saoType?: SaoObjectType;
     name: string;
     dependsOn?: string[];
     initApplication?(App?: ApplicationInterface): void;