@sdcorejs/angular 19.0.1 → 19.0.4

package/README.md

@@ -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
@@ -703,11 +722,10 @@ 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.
 
 ---
 

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/src/models/autoid-element.model.d.ts

@@ -17,6 +17,9 @@ export interface SdAutoidElementState {
     minlength?: string;
     pattern?: string;
     errorMessage?: string;
+    type?: string;
+    title?: string;
+    message?: string;
 }
 export interface SdAutoidElement {
     stt: number;
@@ -39,6 +42,14 @@ export 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;
 }
 export interface SdAutoidMissing {
     tag: string;

package/components/autoid-inspector/src/models/autoid-export-format.model.d.ts

@@ -1,6 +1,25 @@
 export type SdAutoidExportFormat = 'csv' | 'json' | 'md-pom' | 'md-table';
 export 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. */
+export interface SdAutoidExportJson {
+    meta: SdAutoidExportMeta;
+    elements: import('./autoid-element.model').SdAutoidElement[];
 }

package/components/autoid-inspector/src/services/autoid-export.service.d.ts

@@ -2,7 +2,13 @@ import { SdAutoidElement } from '../models/autoid-element.model';
 import { SdAutoidExportMeta } from '../models/autoid-export-format.model';
 import * as i0 from "@angular/core";
 export 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;

package/components/autoid-inspector/src/services/autoid-scanner.service.d.ts

@@ -1,8 +1,21 @@
 import { SdAutoidElement } from '../models/autoid-element.model';
 import * as i0 from "@angular/core";
 export 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[]>;
     /**

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

@@ -1,12 +1,11 @@
 import { OnDestroy, OnInit } from '@angular/core';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Color } from '@sdcorejs/utils/models';
 import { MaterialIconFontSet } from '@sdcorejs/angular/utilities/models';
 import * as i0 from "@angular/core";
 export type SdButtonType = 'fill' | 'light' | 'outline' | 'link';
 export type SdButtonSize = 'sm' | 'md' | 'lg';
 export type SdButtonHtmlType = 'button' | 'submit' | 'reset';
-export declare class SdButton extends SdBaseSecureComponent implements OnInit, OnDestroy {
+export declare class SdButton implements OnInit, OnDestroy {
     #private;
     private el;
     autoIdInput: import("@angular/core").InputSignal<string | null | undefined>;

package/components/form-generic/src/components/form-builder/form-builder.component.d.ts

@@ -1,6 +1,5 @@
 import { CdkDragDrop, CdkDragMove } from '@angular/cdk/drag-drop';
 import { FormGroup } from '@angular/forms';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { SdModal } from '@sdcorejs/angular/components/modal';
 import { FormBuilderComponent, FormBuilderComponentGroup, SdFormGenericComponent, SdFormGenericGroup, SdFormGenericVariable } from '../../models';
 import { SdFormGenericValidation } from '../../models/form-generic-validation.model';
@@ -12,7 +11,7 @@ interface DragDropRowItem {
     items: (SdFormGenericComponent | SdFormGenericGroup)[];
     rowIndex?: number;
 }
-export declare class SdFormBuilder extends SdBaseSecureComponent {
+export declare class SdFormBuilder {
     #private;
     readonly popupViewJSON: import("@angular/core").Signal<SdModal | undefined>;
     readonly popupConfigureVariables: import("@angular/core").Signal<SdModal | undefined>;
@@ -39,6 +38,9 @@ export declare class SdFormBuilder extends SdBaseSecureComponent {
     clonedVariables: SdFormGenericVariable[];
     readonly selectedComponent: import("@angular/core").WritableSignal<SdFormGenericComponent | SdFormGenericGroup | undefined>;
     readonly isPreview: import("@angular/core").WritableSignal<boolean>;
+    readonly editingGroupId: import("@angular/core").WritableSignal<string | undefined>;
+    /** Group đang được Detail (tìm ở TOP-LEVEL theo id), undefined = đang ở canvas chính. */
+    readonly editingGroup: import("@angular/core").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: import("@angular/core").WritableSignal<boolean>;
@@ -70,15 +72,17 @@ export 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;
@@ -92,12 +96,6 @@ export 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/form-generic/src/components/form-render/form-render.component.d.ts

@@ -1,13 +1,12 @@
 import { AfterViewInit, ChangeDetectorRef, OnDestroy, QueryList } from '@angular/core';
 import { FormGroup } from '@angular/forms';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { Subject } from 'rxjs';
 import { ISdFormGenericConfiguration } from '../../configurations';
 import { SdFormRenderConfiguration } from '../../models';
 import { SdFormGenericValidation } from '../../models/form-generic-validation.model';
 import { LibItemComponent } from './components';
 import * as i0 from "@angular/core";
-export declare class SdFormRender extends SdBaseSecureComponent implements OnDestroy, AfterViewInit {
+export declare class SdFormRender implements OnDestroy, AfterViewInit {
     #private;
     private ref;
     private formGenericConfiguration;

package/components/form-generic/src/components/sd-feel-expression/sd-feel-expression.component.d.ts

@@ -1,12 +1,11 @@
 import { ChangeDetectorRef, EventEmitter } from '@angular/core';
 import { FormGroup } from '@angular/forms';
-import { SdBaseSecureComponent } from '@sdcorejs/angular/components/base';
 import { SdModal } from '@sdcorejs/angular/components/modal';
 import { Attribute, SdFormGenericComponent, SdFormGenericExpression, SdFormGenericGroup } from '../../models';
 import { ExpressionFeelPipe } from '../../pipes';
 import { FormGenericService } from '../../services';
 import * as i0 from "@angular/core";
-export declare class SdFeelExpression extends SdBaseSecureComponent {
+export declare class SdFeelExpression {
     #private;
     private ref;
     private expressionFeelPipe;

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 @@
+export * from './src/modal-resizable.component';

package/components/modal-resizable/src/modal-resizable.component.d.ts

@@ -0,0 +1,29 @@
+import { CdkPortal } from '@angular/cdk/portal';
+import * as i0 from "@angular/core";
+export declare class SdModalResizable {
+    #private;
+    readonly id: string;
+    readonly portal: import("@angular/core").Signal<CdkPortal>;
+    readonly editable: import("@angular/core").InputSignalWithTransform<boolean, boolean | "">;
+    readonly width: import("@angular/core").InputSignal<string>;
+    readonly editingChanged: import("@angular/core").OutputEmitterRef<boolean>;
+    readonly isEditing: import("@angular/core").WritableSignal<boolean>;
+    readonly isOpened: import("@angular/core").WritableSignal<boolean>;
+    readonly isHover: import("@angular/core").WritableSignal<boolean>;
+    readonly isLoading: import("@angular/core").WritableSignal<boolean>;
+    readonly isMinimum: import("@angular/core").WritableSignal<boolean>;
+    readonly isMaximum: import("@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: i0.ɵɵFactoryDeclaration<SdModalResizable, never>;
+    static ɵcmp: i0.ɵɵ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>;
+}

package/components/query-bar/src/components/inline-chip/inline-chip.component.d.ts

@@ -12,6 +12,11 @@ type Density = 'compact' | 'comfortable';
  * Covers types: boolean, date, datetime, values, lazy-values, plus a fallback else
  * branch. BETWEEN (date / datetime) uses a single `<sd-date-range>` (datetime
  * downgrades to date precision).
+ *
+ * why: `values` / `lazy-values` đã chuyển sang `<sd-select [viewed]="'inline'">` — sd-select
+ * tự quản click→edit + focusout→thoát + bare editor, nên các nhánh đó KHÔNG dùng
+ * `enterEdit` / `onFocusOut` / `#editing` nữa. Các nhánh còn lại (boolean / date / datetime /
+ * BETWEEN) vẫn dùng lifecycle thủ công cho tới khi control tương ứng có inline mode (rollout).
  */
 export declare class SdQueryInlineChip {
     #private;
@@ -43,41 +48,25 @@ export declare class SdQueryInlineChip {
     /** × removal. */
     readonly remove: import("@angular/core").OutputEmitterRef<void>;
     readonly editing: import("@angular/core").Signal<boolean>;
-    /** Active picker reference — auto-opened right after entering edit. */
-    private readonly chipPicker;
     readonly iconName: import("@angular/core").Signal<string>;
     /** Operator code — convenience accessor for template. */
     readonly operator: import("@angular/core").Signal<Operator>;
     /** Data payload — convenience accessor for template. */
     readonly data: import("@angular/core").Signal<unknown>;
-    /** Enter edit mode + auto-open the picker on next render. */
+    /** Enter edit mode (BOOLEAN branch — shows the toggle buttons; exits on toggle commit). */
     enterEdit(): void;
     /**
-     * Exit edit only when focus actually leaves the wrapper subtree.
-     * why: focusout fires for every internal blur — only exit when relatedTarget
-     * is OUTSIDE the wrapper AND không thuộc cdk-overlay (mat-select panel, mat-calendar,
-     * datetime overlay đều render trong document.body). Tick option trong panel multi-
-     * select sẽ chuyển focus sang `<mat-option>` (nằm trong cdk-overlay-container) →
-     * nếu exit ngay sẽ flip viewed → kill panel sớm. Chỉ exit khi panel đã close
-     * (relatedTarget không nằm trong overlay). markForCheck vì overlay focusout
-     * không kéo theo CD cho OnPush parent.
+     * Single-value commit (sd-date, sd-datetime, single sd-select).
+     * why: date/datetime/values render via `viewed='inline'` (self-managed) — the chip only
+     * forwards the value; it no longer toggles `#editing` (that's boolean-only now).
      */
-    onFocusOut(ev: FocusEvent): void;
-    /** Test-only shim — direct call avoids dispatching real FocusEvent in JSDOM. */
-    onFocusOutForTest(ev: FocusEvent): void;
-    /** Single-value commit (sd-date, sd-datetime, single sd-select). */
     emitSingleCommit(v: unknown): void;
-    /**
-     * BETWEEN commit — sd-date-range emits {from, to}.
-     * why: nếu cả from + to đều có giá trị → coi như range đã chọn xong → exit edit
-     * ngay tại commit (đồng bộ với model.set của parent), không chờ focusout. Tránh
-     * race "focusout firing trước sdChange" làm viewed text render với model cũ.
-     */
+    /** BETWEEN commit — sd-date-range (viewed='inline') emits `{from, to}`; chip just forwards it. */
     emitRangeCommit(ev: {
         from: unknown;
         to: unknown;
     } | null): void;
-    /** Multi-select live emit — does NOT exit edit (focusout handles exit). */
+    /** Multi-select live emit (sd-select inline). */
     emitLive(v: unknown): void;
     /** Boolean toggle commit — exits edit. */
     emitBoolean(v: boolean): void;

package/components/query-bar/src/components/inline-value-chip/inline-value-chip.component.d.ts

@@ -49,12 +49,6 @@ export declare class SdQueryInlineValueChip {
     readonly hasValue: import("@angular/core").Signal<boolean>;
     readonly state: import("@angular/core").Signal<ChipState>;
     constructor();
-    /**
-     * Width in chars — hugs the current value; falls back to the placeholder width only when
-     * empty. why: using placeholder.length unconditionally left a long trailing gap before the
-     * × for short values (e.g. a 1-digit number under the 'giá trị' placeholder).
-     */
-    sizeFor(text: string, placeholder: string): number;
     /** Click anywhere in the pill (except × or an input) focuses the first input. */
     focusFromShell(ev: Event): void;
     onFocus(): void;
@@ -63,7 +57,9 @@ export declare class SdQueryInlineValueChip {
     /** Commit a BETWEEN range — both ends parsed, emitted as `{ from, to }`. */
     commitRange(): void;
     /** Esc — revert drafts to the committed value and blur without emitting. */
-    revertAndBlur(input: HTMLInputElement): void;
+    revertAndBlur(ref?: {
+        blur: () => void;
+    }): void;
     onRemove(ev: Event): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdQueryInlineValueChip, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SdQueryInlineValueChip, "sd-query-inline-value-chip", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "operator": { "alias": "operator"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "showOperator": { "alias": "showOperator"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; "autofocus": { "alias": "autofocus"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "remove": "remove"; }, never, never, true, never>;

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

@@ -1 +1,3 @@
 export * from './src/query-builder.component';
+export * from './src/query-builder.model';
+export * from './src/query-builder.serializer';

package/components/query-builder/src/query-builder.component.d.ts

@@ -1,26 +1,102 @@
-import { EventEmitter } from '@angular/core';
+import { Filter, Operator } from '@sdcorejs/utils/models';
+import { isQbGroup, QbDateMode, QbGroup, QbRule, QbToken, SdQueryBuilderField, SdQueryBuilderFieldOption } from './query-builder.model';
 import * as i0 from "@angular/core";
-export interface QueryRule {
-    field: string;
-    operator: string;
-    value: any;
-}
-export interface QueryGroup {
-    condition: 'AND' | 'OR';
-    rules: (QueryRule | QueryGroup)[];
-    isOpen?: boolean;
-}
+/**
+ * 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.
+ */
 export 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;
+    #private;
+    /** Filterable fields — each declares a `type` that drives the operator set + value editor. */
+    readonly fields: import("@angular/core").InputSignal<SdQueryBuilderField[]>;
+    /** `'edit'` (default) = interactive tree · `'view'` = read-only raw-query string. */
+    readonly mode: import("@angular/core").InputSignal<"edit" | "view">;
+    /** Disable all editing controls. */
+    readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    /** Prefix for `data-autoid` on inner controls (E2E selectors). */
+    readonly autoId: import("@angular/core").InputSignal<string | undefined>;
+    /** Canonical output — the root `FilterAndOr` tree, or `null` when empty. `[(value)]`. */
+    readonly value: import("@angular/core").ModelSignal<Filter | null>;
+    /** Convenience mirror — the root group's direct children. `[(filters)]`. */
+    readonly filters: import("@angular/core").ModelSignal<Filter[]>;
+    /** Root group's logical connector. `[(rootLogic)]`. */
+    readonly rootLogic: import("@angular/core").ModelSignal<"AND" | "OR">;
+    readonly tree: import("@angular/core").Signal<QbGroup>;
+    /** `field.key` → field, for fast lookup from a rule. */
+    readonly fieldByKey: import("@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: import("@angular/core").Signal<QbToken[]>;
+    readonly isView: import("@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: i0.ɵɵFactoryDeclaration<SdQueryBuilder, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SdQueryBuilder, "sd-query-builder", never, { "group": { "alias": "group"; "required": false; }; }, { "groupChange": "groupChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵ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>;
 }