@saolabs/client 1.0.0 → 1.1.0

package/src/core/services/TranslationService.ts

@@ -0,0 +1,91 @@
+export interface TranslationConfig {
+    locale?: string;
+    fallbackLocale?: string;
+    messages?: Record<string, { json?: Record<string, string>; groups?: Record<string, any> }>;
+}
+
+/** Synchronous lookup of dictionaries already present in the application bundle. */
+export class TranslationService {
+    locale = 'en';
+    fallbackLocale = 'en';
+    private messages: NonNullable<TranslationConfig['messages']> = {};
+
+    init(config: TranslationConfig): void {
+        this.locale = config.locale || 'en';
+        this.fallbackLocale = config.fallbackLocale || 'en';
+        this.messages = config.messages || {};
+    }
+
+    setLocale(locale: string): boolean {
+        if (!Object.prototype.hasOwnProperty.call(this.messages, locale)) throw new Error(`Locale is not bundled: ${locale}`);
+        if (locale === this.locale) return false;
+        this.locale = locale;
+        return true;
+    }
+
+    trans(key: string, replace: Record<string, any> = {}, locale = this.locale): string {
+        const value = this.lookup(key, locale) ?? this.lookup(key, this.fallbackLocale) ?? key;
+        return this.interpolate(value, replace);
+    }
+
+    choice(key: string, count: number, replace: Record<string, any> = {}, locale = this.locale): string {
+        const local = this.lookup(key, locale);
+        const value = local ?? this.lookup(key, this.fallbackLocale) ?? key;
+        const pluralLocale = local === undefined ? this.fallbackLocale : locale;
+        const options = value.split('|');
+        let selected: string | undefined;
+        for (const option of options) {
+            const exact = option.match(/^\s*\{([^}]+)\}\s*(.*)$/s);
+            if (exact && exact[1].split(',').some(n => Number(n.trim()) === count)) selected = exact[2];
+            const range = option.match(/^\s*\[([^,]+),([^\]]+)\]\s*(.*)$/s);
+            if (range) {
+                const min = range[1].trim() === '*' ? -Infinity : Number(range[1]);
+                const max = range[2].trim() === '*' ? Infinity : Number(range[2]);
+                if (count >= min && count <= max) selected = range[3];
+            }
+            if (selected !== undefined) break;
+        }
+        if (selected === undefined) {
+            const forms = options.filter(option => !/^\s*[\{\[]/.test(option));
+            let index = 0;
+            try {
+                const rule = new Intl.PluralRules(pluralLocale.replace('_', '-'));
+                const category = rule.select(count);
+                const order = ['zero', 'one', 'two', 'few', 'many', 'other'];
+                const categories = rule.resolvedOptions().pluralCategories;
+                index = order.filter(c => categories.includes(c as Intl.LDMLPluralRule)).indexOf(category);
+            } catch { index = count === 1 ? 0 : 1; }
+            selected = forms[Math.min(Math.max(index, 0), forms.length - 1)] ?? options[0];
+        }
+        return this.interpolate(selected.trim(), { ...replace, count });
+    }
+
+    private lookup(key: string, locale: string): string | undefined {
+        const catalog = this.messages[locale];
+        if (!catalog) return undefined;
+        if (catalog.json && Object.prototype.hasOwnProperty.call(catalog.json, key)) return catalog.json[key];
+        const groups = catalog.groups || {};
+        // Longest group match also supports package::group.item and nested group paths.
+        const group = Object.keys(groups).filter(name => key.startsWith(name + '.')).sort((a, b) => b.length - a.length)[0];
+        if (!group) return undefined;
+        let value: any = groups[group];
+        for (const part of key.slice(group.length + 1).split('.')) {
+            if (!value || !Object.prototype.hasOwnProperty.call(value, part)) return undefined;
+            value = value[part];
+        }
+        return typeof value === 'string' ? value : undefined;
+    }
+
+    private interpolate(value: string, replace: Record<string, any>): string {
+        const keys = Object.keys(replace).sort((a, b) => b.length - a.length);
+        for (const key of keys) {
+            const text = String(replace[key]);
+            const variants: Record<string, string> = {
+                [key]: text, [key.toUpperCase()]: text.toUpperCase(),
+                [key.charAt(0).toUpperCase() + key.slice(1)]: text.charAt(0).toUpperCase() + text.slice(1),
+            };
+            for (const [name, content] of Object.entries(variants)) value = value.split(':' + name).join(content);
+        }
+        return value;
+    }
+}

package/src/core/services/index.ts

@@ -1,8 +1,11 @@
-export * from "./BlockManager";
-export * from "./EventService";
-export * from "./LoggerService";
-export * from './HelperService';
-export * from './HttpService';
-export * from './MarkerRegistry';
-export * from "./StoreService";
-export * from "./StorageService";
+export * from "./AssetManager.js";
+export * from "./BlockManager.js";
+export * from "./EventService.js";
+export * from "./HeadService.js";
+export * from "./SectionManager.js";
+export * from "./LoggerService.js";
+export * from './HelperService.js';
+export * from './HttpService.js';
+export * from './MarkerRegistry.js';
+export * from "./StoreService.js";
+export * from "./StorageService.js";

package/src/core/types/utils.ts

@@ -1,4 +1,4 @@
-export type OneObjectType = 'Application' | 'App' | 'ServiceProvider' | 'Html' | 'Reactive' | 'TextElement' | 'Fragment' | 'Wrapper' | 'Block' | 'BlockOutlet' | 'Output' | 'ViewController' | 'View' | 'Service' | 'Router' | 'App' | 'Component' | 'Unknown' | 'Yield' | '' | null; // Extendable for custom types
+export type SaoObjectType = 'Application' | 'App' | 'ServiceProvider' | 'Html' | 'Reactive' | 'TextElement' | 'Fragment' | 'Wrapper' | 'Block' | 'BlockOutlet' | 'Output' | 'ViewController' | 'View' | 'Service' | 'Router' | 'App' | 'Component' | 'Unknown' | 'Yield' | '' | null; // Extendable for custom types
 export enum OOTEnum {
     APPLICATION = 'Application',
     HTML = 'Html',
@@ -21,10 +21,10 @@ export enum OOTEnum {
 }
 // ─── Re-exports from contracts (backward compatibility) ─────────
 
-export type { OneElementConfig, HtmlElementConfig, OneElementEventHandler, OneElementChildren, OneChildrenFactoryOutput, OneChildrenFactory } from "../contracts/ElementInterface";
-export type { ReactiveRenderFn, ReactiveChildrenFactory, ReactiveConfig } from "../contracts/ReactiveInterface";
-export type { BlockRenderFactory } from "../contracts/BlockInterface";
-export type { ViewRenderFactory, ViewConstructor, ViewLifecycleHooks } from "../contracts/ViewInterface";
-export type { StateListener, MultiKeyStateListener, StateItem } from "../contracts/ViewStateInterface";
-export type { ServiceKey, ServiceFactory, ServiceBinding } from "../contracts/ApplicationInterface";
-export type { ViewConfig, ViewRuntimeConfig } from "../contracts/ViewControllerInterface";
+export type { SaoElementConfig, HtmlElementConfig, SaoElementEventHandler, SaoElementChildren, SaoChildrenFactoryOutput, SaoChildrenFactory } from "../contracts/ElementInterface.js";
+export type { ReactiveRenderFn, ReactiveChildrenFactory, ReactiveConfig } from "../contracts/ReactiveInterface.js";
+export type { BlockRenderFactory } from "../contracts/BlockInterface.js";
+export type { ViewRenderFactory, ViewConstructor, ViewLifecycleHooks } from "../contracts/ViewInterface.js";
+export type { StateListener, MultiKeyStateListener, StateItem } from "../contracts/ViewStateInterface.js";
+export type { ServiceKey, ServiceFactory, ServiceBinding } from "../contracts/ApplicationInterface.js";
+export type { ViewConfig, ViewRuntimeConfig } from "../contracts/ViewControllerInterface.js";

package/src/core/view/LoopContext.ts

@@ -1,4 +1,4 @@
-import type { LoopContextInterface } from "../contracts/LoopContextInterface";
+import type { LoopContextInterface } from "../contracts/LoopContextInterface.js";
 
 /**
  * LoopContext — provides loop metadata for @foreach, @for, @while directives.
@@ -73,6 +73,43 @@ export class LoopContext implements LoopContextInterface {
         }
     }
 
+    /**
+     * Bản chụp BẤT BIẾN của trạng thái hiện tại — dùng cho `loop` mà template
+     * nhìn thấy trong `@foreach`.
+     *
+     * Vì sao cần: LoopContext là MỘT object dùng chung, bị mutate qua từng vòng
+     * (`setCurrentTimes`). Trong khi đó element con được tạo bởi
+     * `childrenFactory` — closure chạy MUỘN (lúc Html.renderChildren), SAU khi
+     * vòng lặp đã kết thúc. Closure bắt `loop` theo THAM CHIẾU nên mọi hàng đọc
+     * ra cùng một giá trị: trạng thái CUỐI cùng.
+     * Đo được: list 6 phần tử, `@click(remove(loop.index))` ở mọi hàng đều nhận
+     * index = 5 → bấm hàng nào cũng xoá phần tử cuối, rồi tắc hẳn.
+     * `__loopIndex` không dính vì nó là tham số theo từng lần gọi callback (mỗi
+     * closure một binding riêng), không phải object chia sẻ.
+     *
+     * `parent` cũng chụp đệ quy: loop lồng nhau có cùng vấn đề ở mức ngoài.
+     * Trả về plain object đã freeze — chỉ đọc, không có `next()` (không ai gọi
+     * `next()` trên `loop` của `@foreach`; `@for`/`@while` vẫn nhận context
+     * MUTABLE vì codegen của chúng cần `setCurrentTimes`/`next`).
+     */
+    snapshot(): LoopContextInterface {
+        return Object.freeze({
+            index: this.index,
+            iteration: this.iteration,
+            count: this.count,
+            remaining: this.remaining,
+            first: this.first,
+            last: this.last,
+            odd: this.odd,
+            even: this.even,
+            depth: this.depth,
+            parent: this.parent ? this.parent.snapshot() : null,
+            next(): void {
+                console.warn('[LoopContext] `loop` trong @foreach là bản chụp chỉ đọc — next() không có tác dụng.');
+            },
+        }) as LoopContextInterface;
+    }
+
     reset(): void {
         this.iteration = 0;
         this.index = 0;

package/src/core/view/ResourceScope.ts

@@ -0,0 +1,174 @@
+import type { StateManagerInterface } from '../contracts/ViewStateInterface.js';
+
+export type Cleanup = () => void;
+export interface WatchContext {
+    readonly signal: AbortSignal;
+    /** False after a dependency change, pause, stop, or destroy. */
+    readonly current: boolean;
+    onCleanup(cleanup: Cleanup): void;
+    /** Apply an async result only while this run still owns the scope. */
+    commit(update: () => void): boolean;
+}
+export type WatchCallback = (values: Readonly<Record<string, any>>, context: WatchContext) =>
+    void | Cleanup | Promise<void | Cleanup>;
+export interface WatchOptions {
+    immediate?: boolean;
+    /** dom (default) runs after bindings/regions; state runs before regions. */
+    flush?: 'state' | 'dom';
+}
+type WatchRecord = {
+    keys: string[];
+    callback: WatchCallback;
+    options: WatchOptions;
+    live: boolean;
+    dirty: boolean;
+    cancelQueued?: Cleanup;
+    disposeRun?: Cleanup;
+    off: Cleanup;
+};
+
+/** Explicit dependencies and ownership; no global hook order or implicit tracking. */
+export class ResourceScope {
+    private records = new Set<WatchRecord>();
+    private cleanups = new Set<Cleanup>();
+    private active = false;
+    private destroyed = false;
+
+    constructor(
+        private states: StateManagerInterface,
+        private afterDom: (callback: () => void) => Cleanup,
+        private reportError: (error: unknown) => void = error => console.error('[ResourceScope]', error),
+    ) {}
+
+    watch(keys: readonly string[], callback: WatchCallback, options: WatchOptions = {}): Cleanup {
+        if (this.destroyed) return () => {};
+        const record: WatchRecord = {
+            keys: [...new Set(keys)], callback, options: { ...options },
+            live: true, dirty: options.immediate !== false, off: () => {},
+        };
+        record.off = this.states.subscribe(record.keys, () => {
+            // Abort stale work immediately, even when the next run waits for DOM.
+            this.invalidate(record);
+            record.dirty = true;
+            this.schedule(record);
+        });
+        this.records.add(record);
+        this.schedule(record);
+        return () => {
+            if (!record.live) return;
+            record.live = false;
+            record.off();
+            this.invalidate(record);
+            this.records.delete(record);
+        };
+    }
+
+    /** Own a resource until scope destruction (pause-safe resources only). */
+    defer(cleanup: Cleanup): Cleanup {
+        let live = true;
+        const dispose = () => {
+            if (!live) return;
+            live = false;
+            this.cleanups.delete(dispose);
+            this.safely(cleanup);
+        };
+        if (this.destroyed) dispose();
+        else this.cleanups.add(dispose);
+        return dispose;
+    }
+
+    resume(): void {
+        if (this.destroyed || this.active) return;
+        this.active = true;
+        for (const record of this.records) this.schedule(record);
+    }
+
+    pause(): void {
+        if (!this.active) return;
+        this.active = false;
+        for (const record of this.records) {
+            if (record.disposeRun || record.cancelQueued) record.dirty = true;
+            this.invalidate(record);
+        }
+    }
+
+    destroy(): void {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.active = false;
+        for (const record of this.records) {
+            record.live = false;
+            record.off();
+            this.invalidate(record);
+        }
+        this.records.clear();
+        for (const cleanup of Array.from(this.cleanups).reverse()) cleanup();
+    }
+
+    private invalidate(record: WatchRecord): void {
+        record.cancelQueued?.();
+        record.cancelQueued = undefined;
+        const dispose = record.disposeRun;
+        record.disposeRun = undefined;
+        dispose?.();
+    }
+
+    private schedule(record: WatchRecord): void {
+        if (!this.active || !record.live || !record.dirty || record.cancelQueued) return;
+        if (record.options.flush === 'state') this.run(record);
+        else record.cancelQueued = this.afterDom(() => {
+            record.cancelQueued = undefined;
+            this.run(record);
+        });
+    }
+
+    private run(record: WatchRecord): void {
+        if (!this.active || !record.live || !record.dirty) return;
+        record.dirty = false;
+        const controller = new AbortController();
+        const cleanups: Cleanup[] = [];
+        const versions = record.keys.map(key => this.states.getStateVersion(key));
+        let current = true;
+        const isCurrent = () => current && record.keys.every((key, i) => this.states.getStateVersion(key) === versions[i]);
+        const onCleanup = (cleanup: Cleanup) => {
+            if (isCurrent()) cleanups.push(cleanup);
+            else this.safely(cleanup);
+        };
+        record.disposeRun = () => {
+            if (!current) return;
+            current = false;
+            controller.abort();
+            for (const cleanup of cleanups.splice(0).reverse()) this.safely(cleanup);
+        };
+        const context: WatchContext = {
+            signal: controller.signal,
+            get current() { return isCurrent(); },
+            onCleanup,
+            commit: update => {
+                if (!isCurrent()) return false;
+                update();
+                return true;
+            },
+        };
+        const values: Record<string, any> = {};
+        try {
+            for (const key of record.keys) values[key] = this.states.getStateByKey(key);
+            const result = record.callback(Object.freeze(values), context);
+            if (typeof result === 'function') onCleanup(result);
+            else if (result) Promise.resolve(result).then(cleanup => {
+                if (typeof cleanup === 'function') onCleanup(cleanup);
+            }, error => {
+                if (isCurrent() && !controller.signal.aborted) this.reportError(error);
+            });
+        } catch (error) {
+            const dispose = record.disposeRun;
+            record.disposeRun = undefined;
+            dispose?.();
+            this.reportError(error);
+        }
+    }
+
+    private safely(cleanup: Cleanup): void {
+        try { cleanup(); } catch (error) { this.reportError(error); }
+    }
+}

package/src/core/view/Section.ts

@@ -1,86 +1,39 @@
-import { HtmlInterface } from "../contracts/ElementInterface";
-import { ViewControllerInterface } from "../contracts/ViewControllerInterface";
-import { SectionConstruvtorArgs, SectionContentRenderer, SectionContentType, SectionInterface, SectionItemType } from "../contracts/views";
+import { HtmlInterface } from "../contracts/ElementInterface.js";
+import { ViewControllerInterface } from "../contracts/ViewControllerInterface.js";
+import { SectionConstruvtorArgs, SectionContentRenderer, SectionContentType, SectionInterface, SectionItemType } from "../contracts/SectionInterface.js";
 
+/**
+ * Section — a `@section(name, ...)` declaration.
+ *
+ * A thin data holder: it does NOT render or subscribe itself. Sections are
+ * declared by a page/layout (often before its matching @yield even exists —
+ * same cross-controller ordering as Block/BlockOutlet), so SectionManager
+ * owns evaluation, DOM insertion, and reactive re-apply (mirrors how
+ * BlockManager owns Block/BlockOutlet mounting instead of Block itself).
+ */
 export class Section implements SectionInterface {
     ctx: ViewControllerInterface | undefined | null = null;
+    /** Owning view instance — keys this section as `name + viewId` in SectionManager, same as Block. */
+    viewId: string;
     name: string;
     type: SectionItemType;
     contentType: SectionContentType;
-    stateKeys?: string[];
-    
-    renderFactory: SectionContentRenderer;
-    subscribeFn: (() => void) | null = null;
-    unsubscribeFn: (() => void) | null = null;
-
-    content: any = null; // Can be string or OneElementChildren depending on contentType
-
-    parentElement: HtmlInterface | undefined | null = null; // For dynamic/reactive sections that need a parent element reference
+    stateKeys: string[];
 
-    isStarted: boolean = false; // Flag to indicate if this section is static (renders once) or dynamic/reactive (renders on state change)
+    renderFactory: SectionContentRenderer;
 
     constructor({ ctx, name, type = 'static', contentType = 'text', stateKeys, renderFactory }: SectionConstruvtorArgs) {
         this.ctx = ctx ?? null;
+        this.viewId = ctx?.viewId ?? '';
         this.name = name;
         this.type = type;
         this.contentType = contentType;
-        this.stateKeys = stateKeys;
+        this.stateKeys = stateKeys ?? [];
         this.renderFactory = renderFactory;
-        
-        this.initialize();
-    }
-
-    initialize() {
-        if (this.type === 'static') {
-            this.render();
-        }
-        this.start();
-
-    }
-
-    render(parentElement?: HtmlInterface | null | undefined) {
-        this.parentElement = parentElement ?? null;
-        this.content = this.renderFactory(this.parentElement);
     }
 
-    start() {
-        if(this.isStarted) return; // No need to subscribe for static sections
-        this.isStarted = true;
-        if ((this.type === 'reactive' || this.type === 'dynamic') && this.stateKeys && this.ctx) {
-            this.subscribeFn = () => {
-                this.render(this.parentElement);
-            };
-            this.unsubscribeFn = this.ctx.states.subscribe(this.stateKeys, this.subscribeFn);
-        }
-        
-    }
-
-    stop() {
-        if (!this.isStarted) return;
-        this.isStarted = false;
-        if (this.unsubscribeFn) {
-            this.unsubscribeFn();
-            this.unsubscribeFn = null;
-        }
+    /** Evaluate current content. `parentElement` only meaningful for contentType 'html'. */
+    evaluate(parentElement?: HtmlInterface | null) {
+        return this.renderFactory(parentElement ?? null);
     }
 }
-
-/**
- * Note: The "Section" concept is being phased out in favor of a more flexible Block/BlockOutlet system.
- * Sections are still supported for backward compatibility but may be deprecated in future versions.
- * For new development, consider using Blocks instead of Sections for better flexibility and composability.
- * 
- * --- CHANGELOG ---
- * vX.X.X - Introduced Block/BlockOutlet system as a more flexible alternative to Sections.
- *   - Sections are now considered legacy and may be deprecated in future versions.
- *   - ViewController's section management is being refactored to support Blocks instead of Sections.
- *   - Updated documentation and examples to encourage use of Blocks over Sections.
- * 
- * --- FUTURE PLANS ---
- * - Phase out Sections entirely in favor of Blocks, which offer more composability and dynamic capabilities.
- * - Provide migration guides for existing users to transition from Sections to Blocks.
- * - Enhance Block system with features like nested blocks, dynamic block registration, and improved lifecycle management.
- * 
- * --- CURRENT RECOMMENDATION ---
- * For new views, prefer using Blocks and BlockOutlets for layout composition instead of Sections. Sections will still work but are not recommended for new development.
- */

package/src/core/view/View.ts

@@ -1,10 +1,19 @@
-import type { ViewControllerInterface, ViewType } from "../contracts/ViewControllerInterface";
-import type { ViewInterface, ViewLifecycleHooks } from "../contracts/ViewInterface";
-import type { OneObjectType } from "../types/utils";
-import { ViewController } from "./ViewController";
+import type { ViewControllerInterface, ViewType } from "../contracts/ViewControllerInterface.js";
+import type { ViewInterface, ViewLifecycleHooks } from "../contracts/ViewInterface.js";
+import type { SaoObjectType } from "../types/utils.js";
+import { ViewController } from "./ViewController.js";
+import type { WatchCallback, WatchOptions } from './ResourceScope.js';
+
+/** Declared View API without the legacy catch-all that would hide misspelled members. */
+type ViewMembers = {
+    [K in keyof View as string extends K ? never : number extends K ? never : K]: View[K];
+};
+
+/** The exported object's methods run on the View after its members are merged. */
+export type ViewUserConfig<T extends object> = T & ThisType<T & ViewMembers>;
 
 /**
- * View — the base class for all views in OneView.
+ * View — the base class for all views in SaoView.
  * 
  * A View is the unit that the user writes. It contains:
  *   - User-defined properties (reactive state, computed values)
@@ -59,14 +68,54 @@ export class View implements ViewInterface, ViewLifecycleHooks {
     }
 
     // ─── Lifecycle Hooks ────────────────────────────────────────
-    // Users can override these in their view class
+    // Users can override these in their view class (mẫu examples/sao/app.sao).
+    // Cặp before/after cho mỗi transition:
+    mounting?(): void | Promise<void>;
+    mounted?(): void | Promise<void>;
+    starting?(): void | Promise<void>;
+    started?(): void | Promise<void>;
+    pausing?(): void | Promise<void>;
+    paused?(): void | Promise<void>;
+    resuming?(): void | Promise<void>;
+    resumed?(): void | Promise<void>;
+    stopping?(): void | Promise<void>;
+    stopped?(): void | Promise<void>;
+    unmounting?(): void | Promise<void>;
+    unmounted?(): void | Promise<void>;
+    destroying?(): void | Promise<void>;
+    destroyed?(): void | Promise<void>;
 
+    // Legacy alias (tương thích cũ):
     onInit?(): void | Promise<void>;
     onMounted?(): void | Promise<void>;
     onUpdated?(): void | Promise<void>;
     onDestroy?(): void | Promise<void>;
     onActivated?(): void | Promise<void>;
     onDeactivated?(): void | Promise<void>;
+    onPause?(): void | Promise<void>;
+    onResume?(): void | Promise<void>;
+
+    /**
+     * Phát sự kiện lên cha đã `@include` view này.
+     *
+     * Là method của View (không chỉ hàm trong scope compiled) để template gọi
+     * thẳng được: `@click(emit('edit', card['id']))` biên dịch thành
+     * `{ handler: 'emit' }`, và ViewController.addEventListener tra handler
+     * dạng chuỗi trên chính View.
+     */
+    emit(event: string, ...args: any[]): any {
+        return this.__ctrl__.emit(event, ...args);
+    }
+
+    watch(keys: readonly string[], callback: WatchCallback, options?: WatchOptions): () => void {
+        return this.__ctrl__.scope.watch(keys, callback, options);
+    }
+
+    afterDom(callback: () => void): () => void {
+        return this.__ctrl__.afterDom(callback);
+    }
+
+    get $scope() { return this.__ctrl__.scope; }
 
     // ─── Convenience Accessors ──────────────────────────────────
 
@@ -87,10 +136,10 @@ export class View implements ViewInterface, ViewLifecycleHooks {
     get $state(): any {
         return this.__ctrl__.states;
     }
-    get oneType(): OneObjectType {
+    get saoType(): SaoObjectType {
         return 'View';
     }
-    set oneType(value: OneObjectType) {
+    set saoType(value: SaoObjectType) {
         // No-op setter to satisfy the Interface; this property is always 'View'
     }