@sdcorejs/angular 20.0.1 → 20.0.4

package/components/query-builder/index.d.ts

@@ -1,30 +1,254 @@
-import * as i0 from '@angular/core';
-import { EventEmitter } from '@angular/core';
+import * as _angular_core from '@angular/core';
+import { Operator, Filter } from '@sdcorejs/utils/models';
 
-interface QueryRule {
-    field: string;
-    operator: string;
+/** Field kinds the builder understands. Drives the operator set + value editor. */
+type SdQueryBuilderFieldType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'values';
+/** One option for a `values`-type field (enum / lookup). */
+interface SdQueryBuilderFieldOption {
+    /** Stored value (sent inside the `Filter`). */
     value: any;
+    /** Human-readable label shown in the select + view-mode string. */
+    display: string;
 }
-interface QueryGroup {
-    condition: 'AND' | 'OR';
-    rules: (QueryRule | QueryGroup)[];
-    isOpen?: boolean;
+/**
+ * One filterable field. `key` matches `Filter.field` (dot-notation allowed);
+ * `label` is what the view-mode raw string renders (field token = label).
+ */
+interface SdQueryBuilderField {
+    /** Dot-notation field path — written to `Filter.field`. */
+    key: string;
+    /** Human label — shown in the field picker AND as the view-mode field token. */
+    label: string;
+    /** Field type — picks the default operator set + value editor control. */
+    type: SdQueryBuilderFieldType;
+    /** Override the allowed operator set (otherwise `QB_OPERATORS_BY_TYPE[type]`). */
+    operators?: Operator[];
+    /** Override the starting operator (otherwise `QB_DEFAULT_OPERATOR_BY_TYPE[type]`). */
+    defaultOperator?: Operator;
+    /** Options for `type: 'values'` — the select list + display-label lookup. */
+    values?: SdQueryBuilderFieldOption[];
+    /** Label for the `true` branch of a boolean field (default `'Có'`). */
+    trueLabel?: string;
+    /** Label for the `false` branch of a boolean field (default `'Không'`). */
+    falseLabel?: string;
+    /** Lower bound for number / date value editors. */
+    min?: number | string;
+    /** Upper bound for number / date value editors. */
+    max?: number | string;
 }
+type QbNode = QbGroup | QbRule;
+/** A logical group of nodes joined by AND / OR. Maps to `FilterAndOr`. */
+interface QbGroup {
+    id: string;
+    kind: 'group';
+    logic: 'AND' | 'OR';
+    children: QbNode[];
+    /** UI-only: whether this group's "+" dropdown is open. */
+    open?: boolean;
+}
+/** A single `field operator value` condition. Maps to a leaf `Filter`. */
+interface QbRule {
+    id: string;
+    kind: 'rule';
+    field?: string;
+    operator?: Operator;
+    /** Single value, `{ from, to }` for BETWEEN, or an array for IN / NOT_IN. */
+    value?: any;
+}
+/** Type guard — narrows a `QbNode` to a `QbGroup`. */
+declare function isQbGroup(node: QbNode): node is QbGroup;
+type QbTokenKind = 'field' | 'op' | 'value' | 'logic' | 'paren' | 'plain';
+/** One piece of the rendered raw query string, tagged for highlight styling. */
+interface QbToken {
+    text: string;
+    kind: QbTokenKind;
+}
+/** Allowed operators per field type — used when `field.operators` is not set. */
+declare const QB_OPERATORS_BY_TYPE: Record<SdQueryBuilderFieldType, Operator[]>;
+/** Default operator when a rule is first created for a field. */
+declare const QB_DEFAULT_OPERATOR_BY_TYPE: Record<SdQueryBuilderFieldType, Operator>;
+/** Operators with no value payload — the value editor is hidden for these. */
+declare const QB_NO_DATA_OPERATORS: Operator[];
+/** Operators whose value is an array — the value editor offers multi-select. */
+declare const QB_MULTI_OPERATORS: Operator[];
+/** Operators allowed for `field` — explicit override wins, else the per-type set. */
+declare function qbAllowedOperators(field: SdQueryBuilderField | undefined): Operator[];
+/** Starting operator for a new rule on `field` — falls back to the per-type default. */
+declare function qbDefaultOperator(field: SdQueryBuilderField | undefined): Operator | undefined;
+/** True when `op` is NULL / NOT_NULL (no value editor). */
+declare function qbIsNoDataOperator(op: Operator | undefined): boolean;
+/** True when `op` is IN / NOT_IN (array value). */
+declare function qbIsMultiOperator(op: Operator | undefined): boolean;
+/** Next stable node id with the given prefix. */
+declare function qbId(prefix?: string): string;
+/** Build a fresh rule node (optionally pre-filled). */
+declare function qbNewRule(field?: string, operator?: Operator, value?: any): QbRule;
+/** Build a fresh group node. */
+declare function qbNewGroup(logic?: 'AND' | 'OR', children?: QbNode[]): QbGroup;
+/** Offset unit for a relative date. */
+type SdQbRelativeUnit = 'day' | 'week' | 'month';
+/** Offset direction for a relative date. */
+type SdQbRelativeDirection = 'previous' | 'next';
+/** A relative (resolved-at-query-time) date value stored in `Filter.data`. */
+interface SdQbRelativeDate {
+    /** `'now'` = current moment / today · `'offset'` = now ± amount × unit. */
+    rel: 'now' | 'offset';
+    /** Offset unit — only for `rel: 'offset'`. */
+    unit?: SdQbRelativeUnit;
+    /** Offset magnitude (>= 1) — only for `rel: 'offset'`. */
+    amount?: number;
+    /** Offset direction — only for `rel: 'offset'`. */
+    direction?: SdQbRelativeDirection;
+}
+/** Date value editor mode for a date/datetime rule (derived from the rule value). */
+type QbDateMode = 'absolute' | 'now' | 'relative';
+/** Type guard — narrows an arbitrary value to a relative-date spec. */
+declare function qbIsRelativeDate(v: any): v is SdQbRelativeDate;
+/** Starting relative value when a rule first switches to "relative" mode. */
+declare function qbDefaultRelative(): SdQbRelativeDate;
+/** Stable option list for the date-mode select (module ref — never reallocated). */
+declare const QB_DATE_MODES: ReadonlyArray<{
+    value: QbDateMode;
+    display: string;
+}>;
+/** Stable combined direction×unit option list (token `'unit:direction'`). */
+declare const QB_RELATIVE_UNIT_OPTIONS: ReadonlyArray<{
+    value: string;
+    display: string;
+}>;
+/** Shared empty option array — stable ref for fallbacks (avoids per-call allocation). */
+declare const QB_EMPTY_OPTIONS: SdQueryBuilderFieldOption[];
+
+/**
+ * Visual filter / rule builder. Compose nested AND / OR groups of
+ * `field operator value` conditions; emits the canonical `Filter` (root is a
+ * `FilterAndOr` tree) via `[(value)]`, plus a flat `[(filters)]` mirror of the
+ * root group's direct children. `mode="view"` renders a read-only SQL-ish raw
+ * string with highlighted operators + values.
+ */
 declare class SdQueryBuilder {
-    group: QueryGroup;
-    groupChange: EventEmitter<QueryGroup>;
-    isGroup(item: any): item is QueryGroup;
-    toggleCondition(group: QueryGroup, condition: 'AND' | 'OR'): void;
-    toggleDropdown(group: QueryGroup, event: Event): void;
-    closeAll(): void;
-    closeAllDropdowns(group: QueryGroup): void;
-    addRule(group: QueryGroup): void;
-    addGroup(group: QueryGroup): void;
-    removeItem(parentGroup: QueryGroup, index: number): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<SdQueryBuilder, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SdQueryBuilder, "sd-query-builder", never, { "group": { "alias": "group"; "required": false; }; }, { "groupChange": "groupChange"; }, never, never, true, never>;
+    #private;
+    /** Filterable fields — each declares a `type` that drives the operator set + value editor. */
+    readonly fields: _angular_core.InputSignal<SdQueryBuilderField[]>;
+    /** `'edit'` (default) = interactive tree · `'view'` = read-only raw-query string. */
+    readonly mode: _angular_core.InputSignal<"edit" | "view">;
+    /** Disable all editing controls. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Prefix for `data-autoid` on inner controls (E2E selectors). */
+    readonly autoId: _angular_core.InputSignal<string | undefined>;
+    /** Canonical output — the root `FilterAndOr` tree, or `null` when empty. `[(value)]`. */
+    readonly value: _angular_core.ModelSignal<Filter | null>;
+    /** Convenience mirror — the root group's direct children. `[(filters)]`. */
+    readonly filters: _angular_core.ModelSignal<Filter[]>;
+    /** Root group's logical connector. `[(rootLogic)]`. */
+    readonly rootLogic: _angular_core.ModelSignal<"AND" | "OR">;
+    readonly tree: _angular_core.Signal<QbGroup>;
+    /** `field.key` → field, for fast lookup from a rule. */
+    readonly fieldByKey: _angular_core.Signal<Record<string, SdQueryBuilderField>>;
+    /** Stable option list for the date-mode select. */
+    readonly dateModes: readonly {
+        value: QbDateMode;
+        display: string;
+    }[];
+    /** Stable combined unit×direction option list for the relative select. */
+    readonly relativeUnitOptions: readonly {
+        value: string;
+        display: string;
+    }[];
+    /** View-mode token stream — recomputed from the emitted value. */
+    readonly tokens: _angular_core.Signal<QbToken[]>;
+    readonly isView: _angular_core.Signal<boolean>;
+    /** Expose the type-guard to the template. */
+    readonly isGroup: typeof isQbGroup;
+    constructor();
+    /** Switch a group's AND/OR connector and re-emit. No-op when disabled or unchanged. */
+    setGroupLogic(group: QbGroup, logic: 'AND' | 'OR'): void;
+    /** Open this group's "+" menu (closing any other open one). UI-only — does not emit. */
+    toggleDropdown(group: QbGroup, event: Event): void;
+    closeAllDropdowns(): void;
+    /** Append a blank rule to `group`. */
+    addRule(group: QbGroup): void;
+    /** Append a nested sub-group (seeded with one blank rule) to `group`. */
+    addGroup(group: QbGroup): void;
+    /** Remove the child at `index` from `parent` (a rule or a whole sub-group). */
+    removeNode(parent: QbGroup, index: number): void;
+    /**
+     * Point `rule` at a new field. Resets operator to the field's default and the value
+     * to that operator's empty shape — the old operator/value rarely fit the new type.
+     *
+     * @param rule - the rule being edited.
+     * @param key - the chosen field key (from the field picker). Swap-only: a null / undefined
+     *   key is a no-op — the field can be changed but never cleared (issue #2).
+     */
+    setField(rule: QbRule, key: any): void;
+    /** Change `rule`'s operator and reshape its value to fit the new operator (array / range / none). */
+    setOperator(rule: QbRule, op: Operator | undefined): void;
+    /** Set a single-value rule's value (coercing numeric fields to `number`). */
+    setScalar(rule: QbRule, raw: any): void;
+    /** Set the lower bound of a BETWEEN rule's `{ from, to }` value. */
+    setBetweenFrom(rule: QbRule, raw: any): void;
+    /** Set the upper bound of a BETWEEN rule's `{ from, to }` value. */
+    setBetweenTo(rule: QbRule, raw: any): void;
+    /** The field metadata for a rule's current `field` key (or undefined if unset). */
+    fieldOf(rule: QbRule): SdQueryBuilderField | undefined;
+    /** Operators allowed for a rule, derived from its field's type / override. */
+    allowedOperators(rule: QbRule): Operator[];
+    /** Whether to render the operator picker — hidden when only one operator is allowed. */
+    showOperatorSelector(rule: QbRule): boolean;
+    /** True for NULL / NOT_NULL — the template then renders no value editor. */
+    isNoData(op: Operator | undefined): boolean;
+    /** True for IN / NOT_IN — the template then renders a multi-select value editor. */
+    isMulti(op: Operator | undefined): boolean;
+    /** `[true/false]` option list for a boolean field's value select (stable reference). */
+    booleanItems(field: SdQueryBuilderField): SdQueryBuilderFieldOption[];
+    /** Current date-value mode of a rule, derived from its value (no separate state). */
+    dateMode(rule: QbRule): QbDateMode;
+    /** Switch a date/datetime rule's value mode, reseeding the value for the new mode. */
+    setDateMode(rule: QbRule, mode: QbDateMode): void;
+    /** Read the offset amount of a relative rule (default 1). */
+    relativeAmount(rule: QbRule): number;
+    /** Set the offset amount (clamped to an integer >= 1). */
+    setRelativeAmount(rule: QbRule, raw: any): void;
+    /** Read the `'unit:direction'` token of a relative rule (default `'day:previous'`). */
+    relativeUnitDirValue(rule: QbRule): string;
+    /** Set the offset unit + direction from a `'unit:direction'` token. */
+    setRelativeUnitDir(rule: QbRule, token: string): void;
+    /** Build a `data-autoid` for an inner control under this builder's `autoId` prefix. */
+    autoIdFor(suffix: string): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdQueryBuilder, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdQueryBuilder, "sd-query-builder", never, { "fields": { "alias": "fields"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "filters": { "alias": "filters"; "required": false; "isSignal": true; }; "rootLogic": { "alias": "rootLogic"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "filters": "filtersChange"; "rootLogic": "rootLogicChange"; }, never, never, true, never>;
 }
 
-export { SdQueryBuilder };
-export type { QueryGroup, QueryRule };
+/**
+ * Map the internal builder tree to the public `Filter` (the root is always a
+ * `FilterAndOr`). Rules missing field / operator / value — and empty nested
+ * groups — are dropped so the result is always a valid `Filter`.
+ *
+ * @param group - the editable tree's root group.
+ * @returns the canonical nested `Filter`, or `null` when no complete rule survives.
+ */
+declare function treeToFilter(group: QbGroup): Filter | null;
+/**
+ * Inverse of {@link treeToFilter} — rebuild the editable tree from a `Filter` so a
+ * consumer can seed `[value]`. A non-group (bare) filter is wrapped in an AND root;
+ * `null` yields an empty AND root.
+ *
+ * @param filter - a `Filter` (group or leaf), or `null` / `undefined` for an empty tree.
+ * @returns a fresh root `QbGroup` mirroring the filter's structure.
+ */
+declare function filterToTree(filter: Filter | null | undefined): QbGroup;
+/**
+ * Render a `Filter` to a SQL-ish token stream for view mode. Field tokens use the
+ * matching field's `label`; operators map to SQL syntax (`= != like between is null …`);
+ * `and` / `or` are lowercase; nested multi-child groups are wrapped in parentheses.
+ * Returns a token stream (not a string) so the template can wrap each piece in a
+ * highlight `<span>` keyed by `QbToken.kind`.
+ *
+ * @param filter - the `Filter` to render, or `null` / `undefined`.
+ * @param fields - field metadata, used to resolve each field key to its display label + value formatting.
+ * @returns the ordered tokens, or `[]` when `filter` is empty.
+ */
+declare function filterToTokens(filter: Filter | null | undefined, fields: SdQueryBuilderField[]): QbToken[];
+
+export { QB_DATE_MODES, QB_DEFAULT_OPERATOR_BY_TYPE, QB_EMPTY_OPTIONS, QB_MULTI_OPERATORS, QB_NO_DATA_OPERATORS, QB_OPERATORS_BY_TYPE, QB_RELATIVE_UNIT_OPTIONS, SdQueryBuilder, filterToTokens, filterToTree, isQbGroup, qbAllowedOperators, qbDefaultOperator, qbDefaultRelative, qbId, qbIsMultiOperator, qbIsNoDataOperator, qbIsRelativeDate, qbNewGroup, qbNewRule, treeToFilter };
+export type { QbDateMode, QbGroup, QbNode, QbRule, QbToken, QbTokenKind, SdQbRelativeDate, SdQbRelativeDirection, SdQbRelativeUnit, SdQueryBuilderField, SdQueryBuilderFieldOption, SdQueryBuilderFieldType };

package/components/section/index.d.ts

@@ -1,8 +1,7 @@
 import * as _angular_core from '@angular/core';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Color } from '@sdcorejs/utils/models';
 
-declare class SdSection extends SdBaseSecureComponent {
+declare class SdSection {
     #private;
     title: _angular_core.InputSignal<string | null | undefined>;
     subTitle: _angular_core.InputSignal<string | null | undefined>;

package/components/side-drawer/index.d.ts

@@ -1,9 +1,8 @@
 import * as _angular_core from '@angular/core';
 import { CdkPortal } from '@angular/cdk/portal';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Observable } from 'rxjs';
 
-declare class SdSideDrawer extends SdBaseSecureComponent {
+declare class SdSideDrawer {
     #private;
     id: string;
     portal: _angular_core.Signal<CdkPortal>;

package/components/stepper/index.d.ts

@@ -3,7 +3,6 @@ import { TemplateRef } from '@angular/core';
 import { AbstractControl } from '@angular/forms';
 import { StepperSelectionEvent } from '@angular/cdk/stepper';
 import { MatStepper } from '@angular/material/stepper';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Color } from '@sdcorejs/utils/models';
 
 type SdStepState = 'pending' | 'active' | 'completed' | 'error' | string;
@@ -21,7 +20,7 @@ declare class SdStep {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdStep, "sd-step", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "optional": { "alias": "optional"; "required": false; "isSignal": true; }; "editable": { "alias": "editable"; "required": false; "isSignal": true; }; "stepControl": { "alias": "stepControl"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; }, { "selectChange": "selectChange"; }, never, ["*"], true, never>;
 }
 
-declare class SdStepper extends SdBaseSecureComponent {
+declare class SdStepper {
     steps: _angular_core.Signal<readonly SdStep[]>;
     selectedIndex: _angular_core.ModelSignal<number>;
     linear: _angular_core.InputSignalWithTransform<boolean, unknown>;

package/components/tab/index.d.ts

@@ -1,7 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { MatTabGroup } from '@angular/material/tabs';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Color } from '@sdcorejs/utils/models';
 
 declare class SdTab {
@@ -20,7 +19,7 @@ interface SdTabClosedEvent {
     index: number;
     tab: SdTab;
 }
-declare class SdTabGroup extends SdBaseSecureComponent {
+declare class SdTabGroup {
     tabs: _angular_core.Signal<readonly SdTab[]>;
     selectedIndex: _angular_core.ModelSignal<number>;
     variant: _angular_core.InputSignal<"line" | "pills" | "segmented">;

package/components/table/index.d.ts

@@ -11,7 +11,6 @@ import { SdExcelColumn, SdLoadingService, SdExcelService, SdNotifyService, SdCon
 import { Observable } from 'rxjs';
 import { SdButton } from '@sdcorejs/angular/components/button';
 import { CdkDrag, CdkDropList, CdkDragDrop } from '@angular/cdk/drag-drop';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { SdQuickAction } from '@sdcorejs/angular/components/quick-action';
 import { SdScrollDirective } from '@sdcorejs/angular/directives';
 import { FormGroup } from '@angular/forms';
@@ -710,16 +709,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 +1040,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 +1057,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 {
@@ -1056,7 +1144,7 @@ declare class MatPaginatorIntlCro extends MatPaginatorIntl {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MatPaginatorIntlCro, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<MatPaginatorIntlCro>;
 }
-declare class SdTable<T = unknown> extends SdBaseSecureComponent implements OnInit, AfterViewInit, OnDestroy {
+declare class SdTable<T = unknown> implements OnInit, AfterViewInit, OnDestroy {
     #private;
     autoIdInput: _angular_core.InputSignal<string | null | undefined>;
     autoId: _angular_core.Signal<string | undefined>;
@@ -1158,4 +1246,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/upload-file/index.d.ts

@@ -92,6 +92,8 @@ declare class SdUploadFile<TArgs = any> {
     #private;
     readonly id: string;
     readonly formControl: SdFormControl;
+    /** Hiển thị message "vui lòng upload": không disabled + đã touched + còn lỗi required. */
+    readonly showRequiredError: _angular_core.Signal<boolean>;
     readonly previewFiles: _angular_core.WritableSignal<PreviewFile[]>;
     readonly selectedFile: _angular_core.WritableSignal<PreviewFile | null | undefined>;
     readonly previewFileComponent: _angular_core.Signal<PreviewComponent | undefined>;

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>;