@sdcorejs/angular 19.0.0 → 19.0.3

package/components/table/src/models/table-option-tree.model.d.ts

@@ -1,12 +1,100 @@
-export 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. */
+import { NestedKeyOf } from '@sdcorejs/utils/models';
+/**
+ * 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) }
+ * ```
+ */
+export 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.
+ */
+export 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).
+ */
+export 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;
 }

package/components/table/src/services/tree/tree.util.d.ts

@@ -1,10 +1,51 @@
-import { SdTableOptionTree } from '../../models/table-option-tree.model';
+import { SdTableOptionTree, TableOptionTreeLazy } from '../../models/table-option-tree.model';
 import { SdTableItem } from '../../models/table-item.model';
+/**
+ * Type-guard: tree có nạp children lười (lazy) hay không.
+ * Dùng để narrow discriminated union `SdTableOptionTree` một cách an toàn —
+ * thay vì truy cập `option.onExpandChildren` trực tiếp trên union (chỉ tồn tại
+ * ở nhánh lazy).
+ */
+export declare const isLazyTree: <T = any>(option?: SdTableOptionTree<T>) => option is TableOptionTreeLazy<T>;
+/**
+ * Key chứa mảng children trên object row.
+ * - `static`: lấy `childrenKey` đã cấu hình, mặc định `'children'`.
+ * - `lazy`: không có `childrenKey` riêng → luôn dùng `'children'` làm nơi lưu
+ *   kết quả nạp lười.
+ */
 export declare const getChildrenKey: (option?: SdTableOptionTree) => string;
 export declare const getChildrenFromData: <T>(data: T, option?: SdTableOptionTree) => T[];
+/**
+ * Trạng thái bung mặc định cho một cấp.
+ * Chỉ `static` mới có `defaultExpanded`; lazy luôn trả `false` (không thể bung
+ * mặc định nhánh chưa nạp).
+ */
 export declare const resolveDefaultExpanded: (level: number, option?: SdTableOptionTree) => boolean;
-export declare const resolveHasChildren: <T>(row: SdTableItem<T>, option?: SdTableOptionTree) => boolean;
+/**
+ * Row có khả năng có children hay không (để hiện nút bung).
+ * - Có children embedded → true.
+ * - Lazy tree: dùng `hasChildren(row.data)` nếu được cấu hình; không thì luôn
+ *   true (chưa biết cho tới khi nạp).
+ */
+export declare const resolveHasChildren: <T>(row: SdTableItem<T>, option?: SdTableOptionTree<T>) => boolean;
+/** Row cần nạp lười (lazy) khi bung: là lazy tree và chưa có children embedded. */
 export declare const hasLazyChildren: <T>(row: SdTableItem<T>, option?: SdTableOptionTree) => boolean;
+/**
+ * True nếu `data` HOẶC bất kỳ hậu duệ nào (theo `childrenKey`) thoả `predicate`.
+ *
+ * Dùng cho search ở cấp con (static tree, table `type: 'local'`): một nhánh
+ * gốc được giữ lại trong kết quả lọc nếu subtree của nó có ít nhất một node
+ * khớp từ khoá. `visited` chống đệ quy vô hạn khi data có circular reference.
+ */
+export declare const subtreeMatches: <T>(data: T, predicate: (data: T) => boolean, option?: SdTableOptionTree, visited?: Set<unknown>) => boolean;
+/**
+ * Lọc mảng children: chỉ giữ child có subtree khớp `predicate`.
+ *
+ * Trả về MẢNG MỚI nhưng GIỮ NGUYÊN object reference của từng child (không clone)
+ * — nhờ vậy `meta.id` (hash từ data) ổn định, selection / trạng thái bung không
+ * bị mất khi từ khoá search đổi. Đây là bước "prune" của tính năng search-con.
+ */
+export declare const filterMatchingChildren: <T>(children: T[], predicate: (data: T) => boolean, option?: SdTableOptionTree) => T[];
 export declare const flattenTree: <T>(roots: SdTableItem<T>[], option?: SdTableOptionTree, visited?: Set<string>) => SdTableItem<T>[];
 /** Thu thập mọi SdTableItem đã format trong cây (kể cả node đang collapse). */
 export declare const collectFormattedTreeRows: <T>(roots: SdTableItem<T>[]) => SdTableItem<T>[];

package/components/view/src/view.component.d.ts

@@ -1,16 +1,49 @@
 import { TemplateRef } from '@angular/core';
 import * as i0 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.
+ */
 export declare class SdView {
+    /** Optional label rendered above the value (omitted when a parent supplies its own label). */
     label: import("@angular/core").InputSignal<string | null | undefined>;
+    /** Raw selected value — NOT rendered directly; only exposed in the `valueTemplate` context as `value`. */
     value: import("@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: import("@angular/core").InputSignal<string | null | undefined>;
+    /** When set, the value renders as a link (`<a [sdHref]>`) instead of plain text. */
     hyperlink: import("@angular/core").InputSignal<string | null | undefined>;
+    /** Label template handed down by a parent control (wins over `label` + `#sdLabel`). */
     labelTemplate: import("@angular/core").InputSignal<TemplateRef<any> | undefined>;
+    /** Value template handed down by a parent control (wins over `display` + `#sdValue`). */
     valueTemplate: import("@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: import("@angular/core").InputSignal<any[] | undefined>;
+    /** `#sdLabel` template projected directly into `<sd-view>` (fallback when no `[labelTemplate]`). */
     contentLabelTemplate: import("@angular/core").Signal<TemplateRef<any> | undefined>;
+    /** `#sdValue` template projected directly into `<sd-view>` (fallback when no `[valueTemplate]`). */
     contentValueTemplate: import("@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: import("@angular/core").Signal<TemplateRef<any> | undefined>;
+    /** Effective value template: input from parent wins, else the projected `#sdValue`. Cached for the same reason. */
     activeValueTemplate: import("@angular/core").Signal<TemplateRef<any> | undefined>;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdView, never>;
     static ɵcmp: i0.ɵɵ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>;