@saolabs/client 1.3.0 → 1.5.2

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

@@ -26,11 +26,12 @@ const SYSTEM_SERVICE_KEYS = new Set(['Store', 'Storage', 'Event', 'Http', 'View'
  * 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, any>): ServiceProviderInterface[] {
+function servicesFromMap(map: Record<string, any>, strict = false): ServiceProviderInterface[] {
     const appInstance = app<ApplicationInterface>();
     return Object.entries(map)
         .filter(([name]) => {
             if (SYSTEM_SERVICE_KEYS.has(name)) {
+                if (strict) throw new Error(`[Bootstrap] Không được ghi đè service hệ thống "${name}" qua config.services.`);
                 console.warn(`[Bootstrap] Cannot override system service "${name}" via config.services. Ignored.`);
                 return false;
             }
@@ -44,7 +45,9 @@ function servicesFromMap(map: Record<string, any>): ServiceProviderInterface[] {
                 // không phải class — `new` vô điều kiện sẽ ném "is not a
                 // constructor". Chỉ dựng khi thật sự là class.
                 const isClass = typeof value === 'function' && value.prototype;
-                appInstance.set(name, isClass ? new value(appInstance) : value);
+                // Dạng `{ factory }`: mỗi Application dựng instance riêng.
+                const isFactory = !!value && typeof value === 'object' && typeof value.factory === 'function';
+                appInstance.set(name, isClass ? new value(appInstance) : isFactory ? value.factory(appInstance) : value);
             }
         }));
 }
@@ -92,6 +95,8 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
     HelperServiceProvider.config = { i18n: config.i18n };
     ApiServiceProvider.config = config.api || {};
     const App = app<ApplicationInterface>();
+    const strict = !!config.strictBundles;
+    App.strictBundles = strict;
     const defaults: NamedServiceProvider[] = [
         CoreServiceProvider,
         ViewServiceProvider,
@@ -102,7 +107,7 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
 
     // config.services: { Name: Class } → auto-wrap providers
     const serviceProviders = config.services
-        ? servicesFromMap(config.services)
+        ? servicesFromMap(config.services, strict)
         : [];
 
     // config.helpers: { tên: fn } → một provider phụ thuộc `helper`
@@ -118,6 +123,7 @@ export function buildDefaultProviders(config: Record<string, any> = {}): NamedSe
             )
             .filter(p => {
                 if (SYSTEM_PROVIDER_NAMES.has(p.name as any)) {
+                    if (strict) throw new Error(`[Bootstrap] Không được ghi đè provider hệ thống "${p.name}".`);
                     console.warn(`[Bootstrap] Cannot override system provider "${p.name}". Ignored.`);
                     return false;
                 }

package/src/core/contracts/BundleInterface.ts

@@ -22,10 +22,41 @@ export interface SaolaBundle {
     helpers?: Record<string, any>;
     /** { 'dot.path': factory } → View.setViewRegistry(). Nạp sau ĐÈ nạp trước. */
     views?: Record<string, ViewFactory>;
+    /**
+     * Khoá (service/helper/view) bundle này CỐ Ý thay của bundle trước. Chỉ có hiệu
+     * lực ở chế độ strict và chỉ khi khoá nằm trong `overridable` của context.
+     */
+    overrides?: string[];
+    /** `'theme'` = lớp trình bày, bị giới hạn khoá (xem MergeOptions.themeNamespaces). */
+    kind?: 'theme' | 'package';
     /** Chạy sau khi mọi bundle đã merge và App đã init. */
     boot?(app: ApplicationInterface): void;
 }
 
+/**
+ * Dạng khai service có factory: App gọi `factory(app)` khi đăng ký, nên mỗi
+ * Application có instance RIÊNG (không dùng instance tạo ở phạm vi module).
+ */
+export interface ServiceFactory<T = any> {
+    factory: (app: ApplicationInterface) => T;
+}
+
+/** Tuỳ chọn gộp bundle. Mặc định (không truyền) = hành vi cũ: sau đè trước, im lặng. */
+export interface MergeOptions {
+    /** Bật kiểm: trùng khoá, provider trùng tên, giới hạn khoá của theme. */
+    strict?: boolean;
+    /** Khoá được phép `overrides`; mục `A.B` phủ cả `A.B.x`. */
+    overridable?: string[];
+    /** Với bundle `kind: 'theme'`: tiền tố khoá services/helpers được phép. Thiếu = không cho khoá nào. */
+    themeNamespaces?: string[];
+    /** Ép mọi bundle trong lượt gộp là loại này (server quyết, bundle không tự nâng quyền được). */
+    kind?: 'theme' | 'package';
+    /** Trusted server classification by URL; bundle contents cannot promote a theme. */
+    bundleKinds?: Record<string, 'theme' | 'package'>;
+    /** Already registered source services/providers participate in strict collision checks. */
+    initialBundle?: SaolaBundle;
+}
+
 /** Kết quả gộp nhiều bundle, theo đúng thứ tự mảng URL. */
 export interface MergedBundles {
     providers: (ServiceProviderInterface | any)[];

package/src/core/elements/Html.ts

@@ -732,6 +732,13 @@ export class Html implements HtmlInterface {
         if (this.isSingleElement()) {
             return this.element;
         }
+        // Editors own their inner DOM, selection and composition state. Reconcile the
+        // host's attributes/events normally, but leave an explicitly declared island alone.
+        if (this.element.hasAttribute('data-sao-preserve-children')) {
+            this.initMode = InitModes.CREATE;
+            this.maybeRunEnter();
+            return this.element;
+        }
         if (this.config.content) {
             this.renderTextContent();
             return this.element;
@@ -750,6 +757,7 @@ export class Html implements HtmlInterface {
             if (children && children.length > 0) {
                 hydrateElementList(this, children);
             }
+            this.applyOptionSelection();
             this.initMode = InitModes.CREATE;
             return this.element;
         }
@@ -768,11 +776,21 @@ export class Html implements HtmlInterface {
             }
         }
         for (const node of Array.from(this.element.childNodes)) if (!keep.has(node)) node.remove();
+        this.applyOptionSelection();
         if (this.isStarted) for (const child of children as any[]) child.start?.();
         this.maybeRunEnter();
         return this.element;
     }
 
+    private applyOptionSelection(): void {
+        const selected = this.config.props?.selected;
+        if (this.tagName.toLowerCase() !== 'option' || !selected) return;
+        // Insertion into a select may choose an option automatically. Apply the
+        // declared selection again after its DOM and text children are mounted.
+        (this.element as HTMLOptionElement).selected = Boolean(selected.type === 'binding'
+            ? selected.factory?.() : selected.value);
+    }
+
     private renderTextContent(): void {
         this.contentUnsubscribe?.();
         this.contentUnsubscribe = null;

package/src/core/services/HelperService.ts

@@ -78,13 +78,16 @@ export class HelperService implements HelperInterface {
         }
         // Page-data refreshes revisions without resetting the chosen locale.
         this.translations.refresh(config);
+        this.syncHeld();
     }
     text(key: string, replace: Record<string, any> | string | null = {}, defaultValue: string | null = null, locale?: string): string {
         if (typeof replace === 'string' && defaultValue === null) defaultValue = replace;
         return this.translations.text(key, replace && typeof replace === 'object' ? replace : {}, defaultValue, locale);
     }
     installLanguage(locale: string, snapshot: import('./TranslationService.js').LanguageSnapshot): boolean {
-        return this.translations.install(locale, snapshot);
+        const installed = this.translations.install(locale, snapshot);
+        this.syncHeld();
+        return installed;
     }
     async loadLanguage(locale: string, load: (locale: string) => Promise<import('./TranslationService.js').LanguageSnapshot>): Promise<boolean> {
         return this.installLanguage(locale, await load(locale));
@@ -123,6 +126,15 @@ export class HelperService implements HelperInterface {
         if (typeof document !== 'undefined') document.documentElement.lang = locale;
         this.App?.Http?.setHeader?.('Accept-Language', locale);
         this.App?.API?.getHttpService?.()?.setHeader?.('Accept-Language', locale);
+        this.syncHeld();
+    }
+
+    /** Tells the server which dictionaries this app already holds, so page data does not carry them again. */
+    private syncHeld(): void {
+        const held = this.translations.held();
+        if (!held) return;
+        this.App?.Http?.setHeader?.('X-Saola-Language', held);
+        this.App?.API?.getHttpService?.()?.setHeader?.('X-Saola-Language', held);
     }
 
     // ─── Execution ──────────────────────────────────────────────

package/src/core/services/TranslationService.ts

@@ -53,6 +53,12 @@ export class TranslationService {
         return this.interpolate(value, replace);
     }
 
+    /** The catalogs this app holds, as the server reads them back: `<scope>;<locale>=<revision>;…` ('' while none is loaded). */
+    held(): string {
+        const parts = Object.entries(this.catalogs).map(([locale, snapshot]) => `${locale}=${snapshot.revision}`);
+        return this.catalogScope && parts.length ? [this.catalogScope, ...parts].join(';') : '';
+    }
+
     install(locale: string, snapshot: LanguageSnapshot): boolean {
         if (snapshot.scope !== this.catalogScope) throw new Error('Language snapshot scope differs from the active catalog');
         if (!Number.isSafeInteger(snapshot.revision) || snapshot.revision < 0) throw new Error('Invalid language revision');