@sdcorejs/angular 20.0.0 → 20.0.3

package/README.md

@@ -1,12 +1,12 @@
 # @sdcorejs/angular
 
-> **VI** — Thư viện UI nội bộ xây dựng trên Angular Material, hỗ trợ Angular 19+  
-> **EN** — Internal UI component library built on Angular Material, supporting Angular 19+
+> Angular UI library built on Angular Material - supports Angular 19 / 20 / 21.
 
-[![Version](https://img.shields.io/badge/version-19.0.0--beta.47-blue)](./package.json)
 [![Angular](https://img.shields.io/badge/Angular-19%2B-red)](https://angular.dev)
 [![Angular Material](https://img.shields.io/badge/Angular_Material-19%2B-purple)](https://material.angular.io)
 
+**🚀 [Showcase](https://sdcorejs.github.io/sdcorejs-angular)** · **📖 [Storybook — code samples, props & API](https://sdcorejs.github.io/portal-template)**
+
 ---
 
 ## Table of Contents / Mục lục
@@ -380,6 +380,25 @@ option: SdTableOption<Product> = {
 <sd-table #sdTable [option]="option" />
 ```
 
+**Tree rows / Dòng cây:**
+
+`tree` là discriminated union theo `loadType`. Icon expand (`chevron_right` / `expand_more`) nằm ở **cột đầu** — cột STT khi bật `index`, ngược lại cột data đầu tiên — thụt lề theo cấp.
+
+```typescript
+// loadType: 'static' — children embedded sẵn trong mỗi row
+tree: { loadType: 'static', childrenKey: 'children', defaultExpanded: 1 }
+
+// loadType: 'lazy' — nạp con khi bung (Promise); hasChildren gate icon expand
+tree: {
+  loadType: 'lazy',
+  hasChildren: (row) => row.type === 'Folder',     // chỉ Folder mới có icon expand
+  onExpandChildren: (row) => api.getChildren(row.id),  // () => Promise<T[]>
+}
+```
+
+- **Child-level search** (`type: 'local'` + `loadType: 'static'`): lọc inline tìm cả **cấp con** — giữ nhánh cha của node khớp, ẩn sibling không khớp, tự bung tới node khớp. Clear filter khôi phục cây.
+- **Lazy loading**: spinner hiện trong ô chevron khi `onExpandChildren` đang chạy; `hasChildren` quyết định dòng nào hiện icon (không truyền = mọi node đều hiện).
+
 ---
 
 ### SdAvatar
@@ -423,19 +442,18 @@ import {
   SdSelect,       // Dropdown
   SdAutocomplete, // Autocomplete
   SdDate,         // Date picker
-  SdSearch,       // Search với debounce
 } from '@sdcorejs/angular/forms';
 ```
 
 ```html
-<sd-input [(ngModel)]="form.name" label="Họ tên" [required]="true" />
+<sd-input [(model)]="form.name" label="Họ tên" [required]="true" />
 
-<sd-input-number [(ngModel)]="form.price" label="Đơn giá" [min]="0" suffix="VNĐ" />
+<sd-input-number [(model)]="form.price" label="Đơn giá" [min]="0" suffix="VNĐ" />
 
-<sd-select [(ngModel)]="form.status" label="Trạng thái"
+<sd-select [(model)]="form.status" label="Trạng thái"
   [items]="statusList" valueField="value" displayField="label" />
 
-<sd-date [(ngModel)]="form.birthday" label="Ngày sinh" />
+<sd-date [(model)]="form.birthday" label="Ngày sinh" />
 ```
 
 ---
@@ -560,17 +578,17 @@ export class ProductListComponent implements OnInit {
       <sd-section title="Thông tin sản phẩm" icon="inventory">
         <div class="row">
           <div class="col-6">
-            <sd-input [(ngModel)]="formData.code" label="Mã" [required]="true" />
+            <sd-input [(model)]="formData.code" label="Mã" [required]="true" />
           </div>
           <div class="col-6">
-            <sd-select [(ngModel)]="formData.status" label="Trạng thái"
+            <sd-select [(model)]="formData.status" label="Trạng thái"
               [items]="STATUS_LIST" valueField="value" displayField="label" />
           </div>
           <div class="col-12">
-            <sd-input [(ngModel)]="formData.name" label="Tên sản phẩm" [required]="true" />
+            <sd-input [(model)]="formData.name" label="Tên sản phẩm" [required]="true" />
           </div>
           <div class="col-6">
-            <sd-input-number [(ngModel)]="formData.price" label="Đơn giá" suffix="VNĐ" />
+            <sd-input-number [(model)]="formData.price" label="Đơn giá" suffix="VNĐ" />
           </div>
         </div>
       </sd-section>
@@ -591,7 +609,7 @@ export class ProductListComponent implements OnInit {
 ### Cấu trúc thư viện / Project structure
 
 ```
-sd-angular/
+sdcorejs-angular/
 ├── src/
 │   └── public-api.ts           # Entry point chính
 ├── assets/
@@ -704,20 +722,19 @@ ng-packagr -p ng-package.json --watch
 
 ### Versioning
 
-Thư viện tuân theo [Semantic Versioning](https://semver.org):
+Scheme: `<angular-major>.0.<release>`. Major digit **khoá theo Angular line** (19.x = Angular 19, 20.x = Angular 20, 21.x = Angular 21) — **KHÔNG** dùng để báo breaking. Mỗi release publish đồng thời 3 major cùng nội dung feature, chỉ khác Angular shim.
 
-- `MAJOR` — Breaking changes (thay đổi API không tương thích)
-- `MINOR` — Tính năng mới (tương thích ngược)
-- `PATCH` — Bug fixes
+- Luôn pin theo Angular line của bạn: `npm i @sdcorejs/angular@^19` (hoặc `@^20` / `@^21`).
+- Breaking change được ghi rõ ở `CHANGELOG.md`, mục **Changed (BREAKING for consumers)**, kèm migration.
 
 ---
 
 ## QA / E2E
 
-Core UI components expose runtime state via lowercase `data-*` attributes. See [`docs/E2E-ATTRIBUTES.md`](docs/E2E-ATTRIBUTES.md) for the full catalog, component matrix, selector cookbook, and YAML schema for AI agents.
+Core UI components expose runtime state via lowercase `data-*` attributes for e2e selectors. The full catalog, component matrix, selector cookbook, and YAML schema for AI agents live in `docs/E2E-ATTRIBUTES.md` in the source repository.
 
 ---
 
 ## License
 
-Internal use only — © SD Team
+MIT - see the LICENSE file.

package/assets/scss/core/_inline-edit.scss

@@ -0,0 +1,105 @@
+// Shared `viewed='inline'` styles for sd-form-controls.
+// why: 1 nguồn cho text-face + editor ẩn (panel control) và input borderless, tránh lặp ~40 dòng/control.
+// Bare-flatten (mat-* internals) KHÔNG nằm ở đây — khác nhau theo control, giữ trong scss riêng.
+
+// Clear-× — hover-gated, đặt cuối "mặt". Include BÊN TRONG rule của phần tử hover (face/input).
+@mixin _inline-clear {
+  .sd-inline-clear {
+    display: none;
+    align-items: center;
+    margin-left: 4px;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    line-height: 0;
+    color: var(--sd-text-secondary, #6b7280);
+    transition: color 0.15s ease;
+
+    mat-icon {
+      font-size: 16px;
+      width: 16px;
+      height: 16px;
+    }
+
+    &:hover {
+      color: var(--sd-error, #b32626);
+    }
+  }
+
+  &:hover .sd-inline-clear {
+    display: inline-flex;
+  }
+}
+
+// Panel-based controls (select / date / datetime / date-range / autocomplete):
+// `<sd-view>` text là "mặt" + trigger; editor render ẩn (overlay) chỉ để neo + mở panel.
+@mixin sd-inline-panel {
+  // Neo cho .sd-inline-editor (absolute). Bare flatten + display nằm ở :host(.sd-bare) riêng của control.
+  :host(.sd-bare) {
+    position: relative;
+  }
+
+  .sd-inline-view {
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    width: 100%;
+    // why: nền nhẹ + đậm hơn khi hover → tín hiệu "viewed có thể bấm để sửa".
+    padding: 1px 6px;
+    border-radius: 4px;
+    background-color: rgba(0, 0, 0, 0.04);
+    transition: background-color 0.15s ease;
+
+    &:hover {
+      background-color: rgba(0, 0, 0, 0.08);
+    }
+
+    @include _inline-clear;
+  }
+
+  // why: editor vô hình phủ lên face. Tắt pointer-events CẢ cây con (mat-* tự bật lại ở trigger)
+  // để hover/click rơi xuống .sd-inline-view ở mọi chỗ. Panel mở qua enterInlineEdit() → open().
+  .sd-inline-editor {
+    position: absolute;
+    inset: 0;
+    opacity: 0;
+    pointer-events: none;
+
+    ::ng-deep * {
+      pointer-events: none !important;
+    }
+  }
+}
+
+// NOTE: the former `sd-inline-input` mixin (mat-form-field flatten for the input/input-number
+// inline variant) was removed when those controls moved to the <sd-inline-text> primitive
+// (forms/inline-text), which owns its own borderless styling. The panel mixin above stays.
+
+// Multiline input (textarea): no panel, no single-line `<sd-inline-text>` — flatten the
+// mat-form-field so the `<textarea>` reads like text, transparent with a hover/focus affordance.
+@mixin sd-inline-textarea {
+  .sd-inline-textarea {
+    cursor: text;
+    border-radius: 4px;
+    background-color: rgba(0, 0, 0, 0.04);
+    transition: background-color 0.15s ease;
+
+    &:hover {
+      background-color: rgba(0, 0, 0, 0.08);
+    }
+
+    &:focus-within {
+      background-color: rgba(0, 0, 0, 0.06);
+      box-shadow: inset 0 0 0 1px var(--sd-primary, #1f6feb);
+    }
+
+    ::ng-deep {
+      .mat-mdc-text-field-wrapper { padding: 0 6px; background: transparent; }
+      .mat-mdc-form-field-flex { padding: 0; }
+      .mdc-notched-outline { display: none; }
+      .mat-mdc-form-field-subscript-wrapper { display: none; }
+      .mat-mdc-form-field-infix { padding: 4px 0; min-height: 0; border: 0; }
+    }
+  }
+}

package/assets/scss/core/form.scss

@@ -296,6 +296,21 @@ mat-checkbox {
   }
 }
 
+// why: selector radio của <sd-table> (.c-selection, single mode) hiện một dấu chấm tối thừa
+// nằm cạnh vòng radio. Nguồn gốc THẬT là state-layer padding của Material trên `.mdc-radio`
+// (`padding: calc((var(--mdc-radio-state-layer-size) - 20px) / 2)`): trong cột selector, .c-selection
+// bị scale(0.85) (xem table.component.scss) còn `.mdc-radio` có `will-change: transform` nên lên
+// compositing layer riêng → phần `.mdc-radio__inner-circle` (transform: scale(0), border 10px màu
+// tối) bị render rớt lại ~1px artifact trong dải padding đó, đọc thành "dấu chấm". Bỏ state-layer
+// padding cho radio selector compact là khử sạch (vòng 20px + scale 0.85 vẫn căn giữa). Scope theo
+// `.c-selection` nên KHÔNG ảnh hưởng radio ở nơi khác (giữ nguyên vùng hover/state-layer của chúng).
+//
+// LƯU Ý: cách trước (`label.mdc-label:empty { display:none }`) KHÔNG khử được dot — nó chỉ TÁCH dot
+// thành 2 dấu chấm (label rỗng vốn đang phủ chồng lên artifact). Đã thay bằng fix dưới đây.
+.c-selection.mat-mdc-radio-button .mdc-radio {
+  padding: 0;
+}
+
 // Placeholder mặc định 1rem (16px), mong muốn nên là 14px
 .mat-mdc-floating-label {
   font-size: 14px !important;

package/components/autoid-inspector/index.d.ts

@@ -20,6 +20,9 @@ interface SdAutoidElementState {
     minlength?: string;
     pattern?: string;
     errorMessage?: string;
+    type?: string;
+    title?: string;
+    message?: string;
 }
 interface SdAutoidElement {
     stt: number;
@@ -42,6 +45,14 @@ interface SdAutoidElement {
      * Used by the UI to group table-scoped elements into a separate section.
      */
     tableScope?: string;
+    /**
+     * `true` when the element matched a required selector (sd-button, sd-input, …) but
+     * had NO `data-autoid` — the scanner still emits it with `autoid: ''` and a positional
+     * `xpath` fallback so the export stays usable. The dev should backfill an autoid.
+     */
+    missingAutoid?: boolean;
+    /** Human-readable warning attached to a fallback element (only set when `missingAutoid`). */
+    warning?: string;
 }
 interface SdAutoidMissing {
     tag: string;
@@ -119,14 +130,46 @@ declare class SdAutoidInspector implements OnDestroy {
 
 type SdAutoidExportFormat = 'csv' | 'json' | 'md-pom' | 'md-table';
 interface SdAutoidExportMeta {
+    /** `location.pathname + location.search` — kept for back-compat with MD exports. */
     pageUrl: string;
     pageTitle: string;
     timestamp: string;
+    /** Full `location.href`. */
+    url: string;
+    /** `location.pathname` only. */
+    pathname: string;
+    /** Raw `location.search` (incl. leading `?`), or `''`. */
+    search: string;
+    /** Parsed query string → key/value map (last value wins on repeats). */
+    queryParams: Record<string, string>;
+    /**
+     * Angular route path params (`:id`, …) merged across the activated-route tree.
+     * Only present when an Angular `Router` is available at scan time; omitted otherwise.
+     */
+    params?: Record<string, string>;
+}
+/** JSON export envelope: page meta + the scanned elements. */
+interface SdAutoidExportJson {
+    meta: SdAutoidExportMeta;
+    elements: SdAutoidElement[];
 }
 
 declare class SdAutoidScannerService {
-    /** Quét toàn bộ element có [data-autoid] trong root, gắn thông tin name/tag/value/xpath. */
-    scan(root?: HTMLElement): SdAutoidElement[];
+    /**
+     * Quét element có [data-autoid] trong root, gắn name/tag/value/xpath.
+     * Khi truyền `requireSelectors` (vd các sd-* form/button), những node khớp selector
+     * mà KHÔNG có data-autoid (self lẫn con) sẽ được thêm vào dưới dạng phần tử fallback
+     * (`autoid: ''`, xpath theo vị trí thẻ + cờ `missingAutoid` + warning) — để JSON xuất ra
+     * vẫn dùng được và dev biết chỗ cần bổ sung autoid.
+     */
+    scan(root?: HTMLElement, requireSelectors?: ReadonlyArray<string>): SdAutoidElement[];
+    /**
+     * Tìm các node khớp `requireSelectors` nhưng thiếu data-autoid (self + mọi descendant),
+     * thêm vào `result` dưới dạng phần tử fallback. Trả về `stt` kế tiếp.
+     */
+    private appendMissing;
+    /** XPath theo vị trí thẻ trong document, vd `(//sd-button)[2]`, khi không có autoid. */
+    private fallbackXpath;
     /** Group element theo autoid để consumer lấy duplicate map. */
     groupByAutoid(elements: SdAutoidElement[]): Record<string, SdAutoidElement[]>;
     /**
@@ -177,7 +220,13 @@ declare class SdAutoidHighlightService {
 }
 
 declare class SdAutoidExportService {
-    toJson(elements: SdAutoidElement[]): string;
+    /**
+     * Có `meta` → bọc `{ meta, elements }` (kèm url/queryParams) để consumer biết trang/route.
+     * Không `meta` → giữ mảng thuần (back-compat cho caller cũ chỉ cần elements).
+     */
+    toJson(elements: SdAutoidElement[], meta?: SdAutoidExportMeta): string;
+    /** Parse a `location.search` string into a flat key/value map (last value wins). */
+    parseQueryParams(search: string): Record<string, string>;
     toCsv(elements: SdAutoidElement[]): string;
     /** POM TypeScript skeleton — copy ngay vào file Playwright/Cypress. */
     toMarkdownPom(elements: SdAutoidElement[], meta: SdAutoidExportMeta): string;
@@ -196,4 +245,4 @@ declare class SdAutoidExportService {
 }
 
 export { SD_AUTOID_DEFAULT_REQUIRE_SELECTORS, SdAutoidAuditService, SdAutoidExportService, SdAutoidHighlightService, SdAutoidInspector, SdAutoidScannerService };
-export type { SdAutoidAuditResult, SdAutoidElement, SdAutoidElementState, SdAutoidExportFormat, SdAutoidExportMeta, SdAutoidInspectorConfig, SdAutoidMissing };
+export type { SdAutoidAuditResult, SdAutoidElement, SdAutoidElementState, SdAutoidExportFormat, SdAutoidExportJson, SdAutoidExportMeta, SdAutoidInspectorConfig, SdAutoidMissing };

package/components/form-generic/index.d.ts

@@ -776,6 +776,9 @@ declare class SdFormBuilder extends SdBaseSecureComponent {
     clonedVariables: SdFormGenericVariable[];
     readonly selectedComponent: i0.WritableSignal<SdFormGenericComponent | SdFormGenericGroup | undefined>;
     readonly isPreview: i0.WritableSignal<boolean>;
+    readonly editingGroupId: i0.WritableSignal<string | undefined>;
+    /** Group đang được Detail (tìm ở TOP-LEVEL theo id), undefined = đang ở canvas chính. */
+    readonly editingGroup: i0.Signal<SdFormGenericGroup | undefined>;
     /** Signal toàn cục: TRUE khi BẤT KỲ cdkDrag nào đang active (palette, canvas, group, resize).
      *  Trigger class `.fb-shell--dragging` để ẩn hover/actions/resize toàn diện, không phụ thuộc :has(). */
     readonly isAnyDragging: i0.WritableSignal<boolean>;
@@ -807,15 +810,17 @@ declare class SdFormBuilder extends SdBaseSecureComponent {
     };
     /** Segmented Design/Preview toggle (replaces play_circle/stop_circle). */
     setMode: (preview: boolean) => void;
-    /** Nested drop handler — when dragging a palette item or canvas item INTO a group body. */
-    dropInGroup: (event: CdkDragDrop<any[]>, group: SdFormGenericGroup) => void;
-    /** Quick-add break sau row chỉ định.
-     *  Tính component index cuối cùng của row đó trong this.components, splice break vào sau.
-     *  Không qua palette — chỉ là utility action bám theo row trên canvas.
+    /** Mở canvas thiết kế riêng cho 1 group (chỉ children của nó). Snapshot để Cancel revert. */
+    enterGroupEdit: (group: SdFormGenericGroup) => void;
+    /** OK: giữ thay đổi children, quay về canvas chính. */
+    confirmGroupEdit: () => void;
+    /** Cancel: revert children về snapshot lúc vào Detail, rồi quay về canvas chính. */
+    cancelGroupEdit: () => void;
+    /** Quick-add break sau row chỉ định (theo scope hiện tại — top-level hoặc group).
+     *  Tính component index cuối cùng của row đó trong scope, splice break vào sau.
      */
     insertBreakAfter: (row: DragDropRowItem) => void;
-    /** Remove a child component from a group's nested list. */
-    removeFromGroup: (group: SdFormGenericGroup, id: string) => void;
+    /** Xoá component theo scope hiện tại (top-level hoặc children của group đang Detail). */
     removeComponent: (id: string) => void;
     selectComponent: (item?: SdFormGenericComponent | SdFormGenericGroup) => void;
     onClickedOutside: (e: any) => void;
@@ -829,12 +834,6 @@ declare class SdFormBuilder extends SdBaseSecureComponent {
     noReturnPredicate: () => boolean;
     changeSizeControl: (event: CdkDragMove<SdFormGenericComponent | SdFormGenericGroup>, item: SdFormGenericComponent | SdFormGenericGroup, items: (SdFormGenericComponent | SdFormGenericGroup)[], currentIndex: number) => Promise<void>;
     dragEndChangeSizeControl: (event: any) => void;
-    /** Resize a child item INSIDE a group.
-     *  Math: lấy bounding của chính item, tính (mouse.x - item.left) / colWidth = newCols.
-     *  Cách này đúng cho cả flex-wrap (item ở wrap row 2+) vì dùng item-relative,
-     *  không phải sum-of-all-preceding-cols (sai khi item wrap xuống row mới).
-     */
-    changeSizeChildInGroup: (event: CdkDragMove<SdFormGenericComponent>, child: SdFormGenericComponent, group: SdFormGenericGroup) => void;
     onChangeViewed: (component: SdFormGenericComponent) => void;
     onChangeHidden: (component: SdFormGenericComponent | SdFormGenericGroup) => void;
     onDuplicate: (component: SdFormGenericComponent | SdFormGenericGroup) => void;

package/components/index.d.ts

@@ -3,6 +3,7 @@ export * from '@sdcorejs/angular/components/button';
 export * from '@sdcorejs/angular/components/badge';
 export * from '@sdcorejs/angular/components/tab-router';
 export * from '@sdcorejs/angular/components/side-drawer';
+export * from '@sdcorejs/angular/components/modal-resizable';
 export * from '@sdcorejs/angular/components/modal';
 export * from '@sdcorejs/angular/components/table';
 export * from '@sdcorejs/angular/components/quick-action';

package/components/modal-resizable/index.d.ts

@@ -0,0 +1,32 @@
+import * as _angular_core from '@angular/core';
+import { CdkPortal } from '@angular/cdk/portal';
+
+declare class SdModalResizable {
+    #private;
+    readonly id: string;
+    readonly portal: _angular_core.Signal<CdkPortal>;
+    readonly editable: _angular_core.InputSignalWithTransform<boolean, boolean | "">;
+    readonly width: _angular_core.InputSignal<string>;
+    readonly editingChanged: _angular_core.OutputEmitterRef<boolean>;
+    readonly isEditing: _angular_core.WritableSignal<boolean>;
+    readonly isOpened: _angular_core.WritableSignal<boolean>;
+    readonly isHover: _angular_core.WritableSignal<boolean>;
+    readonly isLoading: _angular_core.WritableSignal<boolean>;
+    readonly isMinimum: _angular_core.WritableSignal<boolean>;
+    readonly isMaximum: _angular_core.WritableSignal<boolean>;
+    constructor();
+    open: () => void;
+    close: () => void;
+    minimize: () => void;
+    maximize: () => void;
+    toggleMaximum: () => void;
+    startLoading: () => void;
+    stopLoading: () => void;
+    toggleEditable(): void;
+    onFocus: () => void;
+    onBlur: () => void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdModalResizable, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdModalResizable, "sd-modal-resizable", never, { "editable": { "alias": "editable"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; }, { "editingChanged": "editingChanged"; }, never, ["[sdTitle]", "[sdBody]", "[sdFooter]"], true, never>;
+}
+
+export { SdModalResizable };

package/components/table/index.d.ts

@@ -710,16 +710,103 @@ interface SdTableOptionStyle<T = any> {
     rowCss?: (rowData: T, index?: number, ctx?: SdTableRowCssContext) => Record<string, string>;
 }
 
-interface SdTableOptionTree<T = any> {
-    /** Key trên object row chứa mảng children. Mặc định: 'children' */
-    childrenKey?: string;
-    /** Giới hạn độ sâu cây. undefined = không giới hạn. */
+/**
+ * Cấu hình tree-rows cho `<sd-table>` — render dòng con inline dưới dòng cha
+ * kèm expand/collapse.
+ *
+ * Đây là discriminated union theo `loadType`:
+ * - `'static'` ({@link TableOptionTreeStatic}) — children đã nằm sẵn trong data
+ *   (embedded array tại `childrenKey`). Không gọi API khi bung.
+ * - `'lazy'`  ({@link TableOptionTreeLazy})  — children nạp theo yêu cầu qua
+ *   `onExpandChildren` khi người dùng bung dòng lần đầu.
+ *
+ * `loadType` là discriminant: TypeScript dựa vào nó để narrow union (vd chỉ
+ * `static` mới có `childrenKey`/`defaultExpanded`, chỉ `lazy` mới có
+ * `onExpandChildren`). Dùng type-guard `isLazyTree()` trong `tree.util.ts` để
+ * narrow an toàn thay vì truy cập field trực tiếp trên union.
+ *
+ * @example Static (children embedded)
+ * ```ts
+ * tree: { loadType: 'static', childrenKey: 'children', defaultExpanded: 1 }
+ * ```
+ * @example Lazy (nạp theo yêu cầu)
+ * ```ts
+ * tree: { loadType: 'lazy', onExpandChildren: row => api.getChildren(row.id) }
+ * ```
+ */
+type SdTableOptionTree<T = any> = TableOptionTreeStatic<T> | TableOptionTreeLazy<T>;
+/**
+ * Tree với dữ liệu children **embedded** sẵn trong mỗi row.
+ *
+ * Table đọc mảng con tại `childrenKey` ngay trên object data; không có lời gọi
+ * bất đồng bộ nào khi bung dòng. Đây cũng là chế độ hỗ trợ **search ở cấp con**
+ * cho table `type: 'local'` (xem `tree.util.ts#subtreeMatches` /
+ * `filterMatchingChildren`): khi lọc, một nhánh được giữ lại nếu chính nó hoặc
+ * bất kỳ hậu duệ nào khớp từ khoá, và nhánh khớp sẽ tự bung.
+ */
+interface TableOptionTreeStatic<T = any> {
+    /** Chế độ nạp children: dữ liệu đã embedded sẵn trong row. */
+    loadType: 'static';
+    /**
+     * Key trên object row chứa mảng children.
+     * Mặc định: `'children'`.
+     */
+    childrenKey?: NestedKeyOf<T> | 'children';
+    /**
+     * Giới hạn độ sâu cây (level gốc = 0).
+     * `undefined` = không giới hạn.
+     */
     maxDepth?: number;
-    /** false | true | number (mở tới cấp N) */
+    /**
+     * Trạng thái bung mặc định khi load:
+     * - `false` — thu gọn hết (mặc định)
+     * - `true`  — bung toàn bộ
+     * - `number N` — bung tới cấp `N` (row có `level < N` được bung)
+     */
     defaultExpanded?: boolean | number;
-    /** Lazy load khi row chưa có children embedded */
-    onExpandChildren?: (rowData: T) => Promise<T[]> | T[];
-    /** Pixel indent mỗi cấp. Mặc định: 20 */
+    /**
+     * Số pixel thụt lề (indent) cho mỗi cấp sâu.
+     * Mặc định: `20`.
+     */
+    indentSize?: number;
+}
+/**
+ * Tree với children **nạp lười (lazy)** theo yêu cầu.
+ *
+ * Khi người dùng bung một dòng lần đầu mà dòng đó chưa có children embedded,
+ * table gọi `onExpandChildren(row)` để nạp; kết quả được cache lại trên row
+ * (ghi vào key `'children'`) nên các lần bung sau không gọi lại.
+ *
+ * Lazy tree **không hỗ trợ** `childrenKey` tuỳ biến (luôn dùng `'children'` làm
+ * nơi lưu kết quả) và **không hỗ trợ** `defaultExpanded` (không thể bung mặc
+ * định nhánh chưa nạp).
+ */
+interface TableOptionTreeLazy<T = any> {
+    /** Chế độ nạp children: nạp lười theo yêu cầu khi bung. */
+    loadType: 'lazy';
+    /**
+     * Giới hạn độ sâu cây (level gốc = 0).
+     * `undefined` = không giới hạn.
+     */
+    maxDepth?: number;
+    /**
+     * Hàm nạp children khi bung dòng chưa có children embedded.
+     * Trả về `Promise<T[]>`; kết quả được ghi vào key `'children'` của row data
+     * và cache cho các lần bung sau.
+     */
+    onExpandChildren: (rowData: T) => Promise<T[]>;
+    /**
+     * Xác định một row có con hay không — để quyết định có hiển thị icon expand.
+     * - Không truyền: MỌI lazy node đều hiện icon expand (không biết trước được).
+     * - Truyền: chỉ hiện icon khi trả `true`; trả `false` ⇒ row là lá (ẩn icon,
+     *   không gọi `onExpandChildren`).
+     * Lưu ý: nếu row đã có children embedded sẵn thì luôn coi là có con (bỏ qua hàm này).
+     */
+    hasChildren?: (rowData: T) => boolean;
+    /**
+     * Số pixel thụt lề (indent) cho mỗi cấp sâu.
+     * Mặc định: `20`.
+     */
     indentSize?: number;
 }
 
@@ -954,8 +1041,10 @@ declare class MobileFilterComponent {
 
 declare class ConfigComponent {
     #private;
+    autoIdInput: _angular_core.InputSignal<string | null | undefined>;
     tableOption: _angular_core.InputSignal<SdTableOption | undefined>;
     changes: _angular_core.OutputEmitterRef<ConfiguredTableResult>;
+    autoId: _angular_core.Signal<string>;
     modal: _angular_core.Signal<SdModal | undefined>;
     table: _angular_core.Signal<MatTable<SdTableColumn>>;
     configuration: _angular_core.WritableSignal<ConfiguredTable | undefined>;
@@ -969,7 +1058,7 @@ declare class ConfigComponent {
     handleMouseDown(): void;
     handleMouseUp(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ConfigComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ConfigComponent, "config", never, { "tableOption": { "alias": "tableOption"; "required": false; "isSignal": true; }; }, { "changes": "changes"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ConfigComponent, "config", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "tableOption": { "alias": "tableOption"; "required": false; "isSignal": true; }; }, { "changes": "changes"; }, never, never, true, never>;
 }
 
 declare class SdPopupExport {
@@ -1158,4 +1247,4 @@ declare class SdTable<T = unknown> extends SdBaseSecureComponent implements OnIn
 }
 
 export { MatPaginatorIntlCro, SD_TABLE_CONFIGURATION, SdConvertToPagingReq, SdMaterialFooterDefDirective, SdTable, SdTableCellDefDirective, SdTableExpandDefDirective, SdTableFilterDefDirective, SdTableGroupDefDirective, SdTableTitleDefDirective };
-export type { ISdTableConfiguration, SdTableColumn, SdTableColumnChildren, SdTableColumnLazyValues, SdTableColumnNormal, SdTableColumnTransformFunc, SdTableColumnValues, SdTableCommand, SdTableCommandChildren, SdTableCommandNormal, SdTableCommandOption, SdTableDisplay, SdTableExternalFilter, SdTableFilterRequest, SdTableGroupDefContext, SdTableItem, SdTableMeta, SdTableOption, SdTableOptionFilter, SdTableOptionTree, SdTableQuickFilter, TableFilterConfiguration, TableFilterRegister, TableFilterValue };
+export type { ISdTableConfiguration, SdTableColumn, SdTableColumnChildren, SdTableColumnLazyValues, SdTableColumnNormal, SdTableColumnTransformFunc, SdTableColumnValues, SdTableCommand, SdTableCommandChildren, SdTableCommandNormal, SdTableCommandOption, SdTableDisplay, SdTableExternalFilter, SdTableFilterRequest, SdTableGroupDefContext, SdTableItem, SdTableMeta, SdTableOption, SdTableOptionFilter, SdTableOptionTree, SdTableQuickFilter, TableFilterConfiguration, TableFilterRegister, TableFilterValue, TableOptionTreeLazy, TableOptionTreeStatic };

package/components/view/index.d.ts

@@ -1,17 +1,50 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 
+/**
+ * `<sd-view>` — pure read-only display of a value (text, hyperlink, or a custom template).
+ *
+ * Presentational proxy with no state of its own: the parent form control (`<sd-select>`,
+ * `<sd-input>`, …) computes the display string + resolved selection and passes them in;
+ * `<sd-view>` only decides WHICH template renders. It is the single rendering path for every
+ * "viewed" state across the form controls (DETAIL `viewed=true` and the `viewed='inline'`
+ * text face), so a custom `valueTemplate` (e.g. `sdViewDef` / `#sdValue`) looks identical in
+ * both. OnPush — re-renders only when an input signal changes.
+ */
 declare class SdView {
+    /** Optional label rendered above the value (omitted when a parent supplies its own label). */
     label: _angular_core.InputSignal<string | null | undefined>;
+    /** Raw selected value — NOT rendered directly; only exposed in the `valueTemplate` context as `value`. */
     value: _angular_core.InputSignal<any>;
+    /**
+     * Display string — what shows when no custom value template is bound.
+     * why: `input.required()` forces the parent to bind `[display]` (compile error otherwise),
+     * so the component never has to guess a fallback string from `value`.
+     */
     display: _angular_core.InputSignal<string | null | undefined>;
+    /** When set, the value renders as a link (`<a [sdHref]>`) instead of plain text. */
     hyperlink: _angular_core.InputSignal<string | null | undefined>;
+    /** Label template handed down by a parent control (wins over `label` + `#sdLabel`). */
     labelTemplate: _angular_core.InputSignal<TemplateRef<any> | undefined>;
+    /** Value template handed down by a parent control (wins over `display` + `#sdValue`). */
     valueTemplate: _angular_core.InputSignal<TemplateRef<any> | undefined>;
+    /**
+     * Resolved selected-item objects passed by the parent (e.g. `<sd-select>`).
+     * why: the parent owns option/lazy resolution — `<sd-view>` is a proxy and must NOT rebuild
+     * the list. Exposed in the value-template context so a "head +N" template can read `displayField`.
+     */
     selectedItems: _angular_core.InputSignal<any[] | undefined>;
+    /** `#sdLabel` template projected directly into `<sd-view>` (fallback when no `[labelTemplate]`). */
     contentLabelTemplate: _angular_core.Signal<TemplateRef<any> | undefined>;
+    /** `#sdValue` template projected directly into `<sd-view>` (fallback when no `[valueTemplate]`). */
     contentValueTemplate: _angular_core.Signal<TemplateRef<any> | undefined>;
+    /**
+     * Effective label template: input from parent wins, else the projected `#sdLabel`.
+     * why: `computed` caches the choice so the template's `@if (activeLabelTemplate())` doesn't
+     * re-evaluate two content-child reads on every change-detection pass.
+     */
     activeLabelTemplate: _angular_core.Signal<TemplateRef<any> | undefined>;
+    /** Effective value template: input from parent wins, else the projected `#sdValue`. Cached for the same reason. */
     activeValueTemplate: _angular_core.Signal<TemplateRef<any> | undefined>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdView, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdView, "sd-view", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "display": { "alias": "display"; "required": true; "isSignal": true; }; "hyperlink": { "alias": "hyperlink"; "required": false; "isSignal": true; }; "labelTemplate": { "alias": "labelTemplate"; "required": false; "isSignal": true; }; "valueTemplate": { "alias": "valueTemplate"; "required": false; "isSignal": true; }; "selectedItems": { "alias": "selectedItems"; "required": false; "isSignal": true; }; }, {}, ["contentLabelTemplate", "contentValueTemplate"], never, true, never>;