npm - @sdcorejs/angular - Versions diffs - 21.1.5 → 21.2.0 - Mend

@sdcorejs/angular 21.1.5 → 21.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (208) hide show

package/types/sdcorejs-angular-components-modal-resizable.d.ts CHANGED Viewed

@@ -1,12 +1,94 @@
 import * as _angular_core from '@angular/core';
 import { CdkPortal } from '@angular/cdk/portal';
+/**
+ * `<sd-modal-resizable>` — right-docked, non-modal panel that can be minimized, expanded or pushed
+ * fullscreen. Several panels stack side by side along the right edge of the viewport, so the user
+ * can keep multiple records open at once while still working with the page behind them.
+ *
+ * Use it for side-by-side comparison / inspector workflows. Use `<sd-modal>` when the task is
+ * blocking, and `<sd-side-drawer>` when a single overlay with a backdrop is enough.
+ *
+ * NOTE ON DOCS: this component deliberately has **no** sibling `sd-modal-resizable.md`. Every `*.md`
+ * under the library is swept into `published-docs/<version>/index.json` by `scripts/collect-docs.mjs`,
+ * and `scripts/generate-showcase-example-sources.test.mjs` asserts that list is 1:1 with the
+ * `publishedDocId` set in the showcase documentation registry. A published doc with no showcase page
+ * therefore turns that release guard red. Keep the reference here until the component ships a
+ * showcase demo + registry entry; only then add the `.md`.
+ *
+ * ```ts
+ * import { SdModalResizable } from '@sdcorejs/angular/components/modal-resizable';
+ * ```
+ *
+ * ```html
+ * <sd-button title="Open detail" type="fill" color="primary" (click)="panel.open()"></sd-button>
+ *
+ * <sd-modal-resizable #panel width="520px">
+ *   <span sdTitle>Đơn hàng #1024</span>
+ *
+ *   <div sdBody class="panel-body">
+ *     <sd-section icon="receipt" title="Thông tin chung">
+ *       <sd-section-item label="Khách hàng">Nguyen Van An</sd-section-item>
+ *     </sd-section>
+ *   </div>
+ *
+ *   <sd-button sdFooterRight type="text" title="Đóng" (click)="panel.close()"></sd-button>
+ * </sd-modal-resizable>
+ * ```
+ *
+ * ### Slots
+ * | Selector          | Where it renders          |
+ * | ----------------- | ------------------------- |
+ * | `[sdTitle]`       | Header title area.        |
+ * | `[sdBody]`        | Scrollable content area.  |
+ * | `[sdFooterLeft]`  | Footer left action group. |
+ * | `[sdFooterRight]` | Footer right action group.|
+ *
+ * Header, body and footer only render while the panel is open.
+ *
+ * ### Panel stacking
+ * The panel is portalled onto `document.body` (via `CdkPortal` + `DomPortalOutlet`), so laying panels
+ * out is a concern shared by all live instances rather than by a single view. Arrangement is scoped
+ * through the root-provided `SdModalResizableRegistry`: each instance registers its panel id on
+ * construction and unregisters it on destroy. `open`, `close`, `minimize`, `maximize` and
+ * `toggleMaximum` re-run the arrangement and rewrite inline `width` / `right` **only on registered,
+ * still-mounted panels**, in registration order. Consequences worth knowing:
+ * - Markup of your own that happens to carry the `.modal-resizable` class is **not** touched.
+ *   (Earlier builds ran `document.querySelectorAll('.modal-resizable')` and rewrote every match.)
+ * - A destroyed panel immediately stops taking up a slot for the instances that outlive it.
+ * - Panels marked `c-closed`, and expanded panels with no captured `data-width`, are skipped.
+ *
+ * ### Lifecycle / teardown
+ * `open()`, `close()` and the arrangement pass each schedule a short `setTimeout` (100ms / 100ms /
+ * 200ms) that mutates DOM. All of them are tracked and cleared in `DestroyRef.onDestroy`, together
+ * with unregistering from the registry and destroying the portal view. Destroying the component
+ * mid-animation cannot run layout work against a detached panel.
+ *
+ * ### Anti-patterns
+ * - Rendering it inside a scroll container and expecting it to be clipped — it lives on `<body>`.
+ * - Reusing the `.modal-resizable` class on your own elements to "join" the stack; register a real
+ *   component instead.
+ * - Writing inline `width` / `right` on a panel yourself — the next arrangement pass overwrites both.
+ *
+ * ### Tests
+ * `src/modal-resizable.component.spec.ts` — portal attach, open/close/minimize/maximize math,
+ * loading, editing, timer teardown, registry scoping. Run:
+ * `npx ng test sdcorejs-angular --watch=false --browsers=ChromeHeadless --include='projects/sdcorejs-angular/components/modal-resizable/src/modal-resizable.component.spec.ts'`
+ *
+ * ### Related
+ * `<sd-modal>` (blocking dialog / bottom-sheet), `<sd-side-drawer>` (single right-side overlay with
+ * a body scroll lock), `SdLoadingService` (powers `startLoading()` / `stopLoading()`).
+ */
 declare class SdModalResizable {
     #private;
+    /** Generated DOM id of the panel element (`I<uuid>`). */
     readonly id: string;
     readonly portal: _angular_core.Signal<CdkPortal>;
+    /** Marks the panel as editable. Bare attribute = `true`. Default `false`. */
     readonly editable: _angular_core.InputSignalWithTransform<boolean, boolean | "">;
+    /** CSS width used while the panel is expanded (not a minimum). Default `'480px'`. */
     readonly width: _angular_core.InputSignal<string>;
+    /** Emitted by `toggleEditable()` with the new editing state. */
     readonly editingChanged: _angular_core.OutputEmitterRef<boolean>;
     readonly isEditing: _angular_core.WritableSignal<boolean>;
     readonly isOpened: _angular_core.WritableSignal<boolean>;
@@ -15,15 +97,25 @@ declare class SdModalResizable {
     readonly isMinimum: _angular_core.WritableSignal<boolean>;
     readonly isMaximum: _angular_core.WritableSignal<boolean>;
     constructor();
+    /** Opens the panel, captures its rendered width, and expands it. */
     open: () => void;
+    /** Collapses the panel to zero width and stops loading. */
     close: () => void;
+    /** Shrinks the panel to the 300px minimum strip. */
     minimize: () => void;
+    /** Restores the panel to its expanded width. */
     maximize: () => void;
+    /** Toggles fullscreen (`calc(100% - 16px)`). */
     toggleMaximum: () => void;
+    /** Drives the scoped loading overlay through `SdLoadingService`. */
     startLoading: () => void;
+    /** Stops the scoped loading overlay. */
     stopLoading: () => void;
+    /** Flips `isEditing` and emits `editingChanged`. */
     toggleEditable(): void;
+    /** Hover state hook bound in the template. */
     onFocus: () => void;
+    /** Hover state hook bound in the template. */
     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]", "[sdFooterLeft]", "[sdFooterRight]"], true, never>;

package/types/sdcorejs-angular-components-modal.d.ts CHANGED Viewed

@@ -1,9 +1,9 @@
 import * as _angular_core from '@angular/core';
-import { TemplateRef, ElementRef } from '@angular/core';
+import { OnDestroy, TemplateRef, ElementRef } from '@angular/core';
 import { Color } from '@sdcorejs/utils/models';
 type SdModalBeforeClose = () => boolean | Promise<boolean>;
-declare class SdModal {
+declare class SdModal implements OnDestroy {
     #private;
     static index: _angular_core.WritableSignal<number>;
     templateRef: _angular_core.Signal<TemplateRef<any>>;
@@ -27,6 +27,7 @@ declare class SdModal {
     isOpened: _angular_core.WritableSignal<boolean>;
     alreadyOpened: _angular_core.WritableSignal<boolean>;
     constructor();
+    ngOnDestroy(): void;
     open: () => void;
     close: () => void;
     requestClose: () => Promise<boolean>;

package/types/sdcorejs-angular-components-org-chart.d.ts CHANGED Viewed

@@ -54,9 +54,15 @@ declare class SdOrgChart {
     readonly resolvedItemTemplate: _angular_core.Signal<TemplateRef<SdOrgChartItemContext<SdOrgChartItem>> | undefined>;
     readonly trackByItem: (_index: number, item: SdOrgChartItem) => string | number;
     hasChildren: (item: SdOrgChartItem) => boolean;
+    /** why: trả về hằng số dùng chung thay vì `[]` mới, để leaf không cấp phát mỗi lần CD gọi tới. */
     childrenOf: (item: SdOrgChartItem) => SdOrgChartItem[];
     isExpanded: (item: SdOrgChartItem) => boolean;
     toggle: (item: SdOrgChartItem, event?: Event) => void;
+    /**
+     * Template context của một node. Ref ổn định giữa các lần CD nhờ `#contextByItem`.
+     * Item không nằm trong `resolvedItems()` (gọi thủ công từ bên ngoài) thì dựng mới — trường hợp
+     * này không nằm trên đường render nên không gây churn.
+     */
     createContext: (item: SdOrgChartItem, depth: number, parent: SdOrgChartItem | null) => SdOrgChartItemContext;
     nodeAutoId: (item: SdOrgChartItem, part: "node" | "image" | "title" | "description" | "toggle") => string | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdOrgChart, never>;

package/types/sdcorejs-angular-components-preview.d.ts CHANGED Viewed

@@ -61,6 +61,7 @@ declare class SdPreviewImage implements OnDestroy {
     static readonly MAX_ZOOM = 4;
     static readonly ZOOM_STEP = 0.1;
     static readonly SWIPE_THRESHOLD = 40;
+    readonly stageId: string;
     readonly autoIdInput: _angular_core.InputSignal<string | null | undefined>;
     readonly autoId: _angular_core.Signal<string | undefined>;
     readonly autoIdPrev: _angular_core.Signal<string | undefined>;

package/types/sdcorejs-angular-components-query-bar.d.ts CHANGED Viewed

@@ -5,7 +5,7 @@ import { MatMenu } from '@angular/material/menu';
 import { SdSearch } from '@sdcorejs/angular/forms/models';
 type SdQueryFieldType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'values' | 'lazy-values';
-interface SdQueryFieldBase<T = any> {
+interface SdQueryFieldBase<T = unknown> {
     /** Dot-notation field path (matches `Filter.field`). */
     key: NestedKeyOf<T>;
     /** Human-readable label shown on chip + field picker. */
@@ -30,10 +30,10 @@ interface SdQueryFieldBase<T = any> {
     /** Field is offered in picker but not interactive (read-only badge in chip). */
     disabled?: boolean;
 }
-interface SdQueryFieldString<T = any> extends SdQueryFieldBase<T> {
+interface SdQueryFieldString<T = unknown> extends SdQueryFieldBase<T> {
     type: 'string';
 }
-interface SdQueryFieldNumber<T = any> extends SdQueryFieldBase<T> {
+interface SdQueryFieldNumber<T = unknown> extends SdQueryFieldBase<T> {
     type: 'number';
     /** Bounds for the input control inside the chip popover. */
     min?: number;
@@ -41,13 +41,13 @@ interface SdQueryFieldNumber<T = any> extends SdQueryFieldBase<T> {
     /** Step for the number input. */
     step?: number;
 }
-interface SdQueryFieldBoolean<T = any> extends SdQueryFieldBase<T> {
+interface SdQueryFieldBoolean<T = unknown> extends SdQueryFieldBase<T> {
     type: 'boolean';
     /** Labels rendered for the true/false buttons. Default: "Có" / "Không". */
     trueLabel?: string;
     falseLabel?: string;
 }
-interface SdQueryFieldDate<T = any> extends SdQueryFieldBase<T> {
+interface SdQueryFieldDate<T = unknown> extends SdQueryFieldBase<T> {
     type: 'date' | 'datetime';
     /** Restrict the picker calendar to this range. */
     min?: Date | string;
@@ -57,7 +57,7 @@ interface SdQueryFieldDate<T = any> extends SdQueryFieldBase<T> {
  * Statically-known options (sync array, signal, or one-shot promise).
  * Mirrors `SdTableColumnValues.option`.
  */
-interface SdQueryFieldValues<T = any, K = Record<string, any>> extends SdQueryFieldBase<T> {
+interface SdQueryFieldValues<T = unknown, K = Record<string, any>> extends SdQueryFieldBase<T> {
     type: 'values';
     option: {
         items: K[] | Signal<K[]> | (() => Promise<K[]>);
@@ -71,7 +71,7 @@ interface SdQueryFieldValues<T = any, K = Record<string, any>> extends SdQueryFi
  * `{ type: 'SEARCH', searchText }` for live queries and `{ type: 'VALUE', value }` for
  * resolving chip-display labels of already-selected IDs.
  */
-interface SdQueryFieldLazyValues<T = any, K = Record<string, any>> extends SdQueryFieldBase<T> {
+interface SdQueryFieldLazyValues<T = unknown, K = Record<string, any>> extends SdQueryFieldBase<T> {
     type: 'lazy-values';
     option: {
         search: SdSearch<K>;
@@ -79,16 +79,16 @@ interface SdQueryFieldLazyValues<T = any, K = Record<string, any>> extends SdQue
         displayField: NestedKeyOf<K>;
     };
 }
-type SdQueryField<T = any> = SdQueryFieldString<T> | SdQueryFieldNumber<T> | SdQueryFieldBoolean<T> | SdQueryFieldDate<T> | SdQueryFieldValues<T> | SdQueryFieldLazyValues<T>;
+type SdQueryField<T = unknown> = SdQueryFieldString<T> | SdQueryFieldNumber<T> | SdQueryFieldBoolean<T> | SdQueryFieldDate<T> | SdQueryFieldValues<T> | SdQueryFieldLazyValues<T>;
 type SdQueryLogic = 'AND' | 'OR';
-interface SdQuery<T = any> {
+interface SdQuery<T = unknown> {
     filters: Filter<T>[];
     /** Global connector between filters. Defaults to `'AND'`. */
     logic?: SdQueryLogic;
     /** Free-text search box (only present when `showSearch=true`). */
     search?: string;
 }
-interface SdQueryBarOption<T = any> {
+interface SdQueryBarOption<T = unknown> {
     /** Prefix for auto-generated `data-autoid` on inner controls. */
     autoId?: string;
     /** Available fields the user can filter by. */
@@ -111,7 +111,7 @@ interface SdQueryBarOption<T = any> {
     onApply?: (query: SdQuery<T>) => void;
 }
 /** Persisted bookmark of a query (filters + logic + search) — managed by `[savedFiltersKey]`. */
-interface SdSavedFilter<T = any> {
+interface SdSavedFilter<T = unknown> {
     id: string;
     name: string;
     query: SdQuery<T>;
@@ -123,7 +123,7 @@ interface SdSavedFilter<T = any> {
  *   - 'operator' — operator menu open, waiting for the user to pick a condition
  *   - 'value'    — operator locked, value picker / seamless input is the focus
  */
-interface BuildingChip<T = any> {
+interface BuildingChip<T = unknown> {
     field: SdQueryField<T>;
     operator?: Operator;
     step: 'operator' | 'value';
@@ -151,6 +151,9 @@ declare function sdQueryDefaultOperator(field: SdQueryField): Operator;
  * - `operators === true` → full set for the type
  * - `operators` is an array → that array (deduped against the type set is the caller's job)
  * - otherwise (simple mode) → just the single default operator (no real choice)
+ *
+ * The returned array is referentially stable for a given `field` object, so it is safe to call
+ * straight from a template binding.
  */
 declare function sdQueryAllowedOperators(field: SdQueryField): Operator[];
 /**
@@ -175,6 +178,14 @@ declare function sdQueryShowOperatorSelector(field: SdQueryField): boolean;
  */
 declare class SdQueryChipPopover {
     #private;
+    readonly swapFieldTooltip: _angular_core.Signal<string>;
+    readonly fromPlaceholder: _angular_core.Signal<string>;
+    readonly toPlaceholder: _angular_core.Signal<string>;
+    readonly booleanTrueLabel: _angular_core.Signal<string>;
+    readonly booleanFalseLabel: _angular_core.Signal<string>;
+    readonly selectValuePlaceholder: _angular_core.Signal<string>;
+    readonly enterValuePlaceholder: _angular_core.Signal<string>;
+    readonly loadingValuesLabel: _angular_core.Signal<string>;
     /** Resolved field of the currently editing chip — parent passes from `fieldByKey()`. */
     readonly field: _angular_core.InputSignal<SdQueryField | undefined>;
     /** The chip's current Filter — used by `seed()` for initial staging values. */
@@ -271,7 +282,7 @@ declare class SdQueryBar {
     /** The extracted chip popover — owns operator+value staging + commit-on-close. */
     readonly chipPopover: _angular_core.Signal<SdQueryChipPopover | undefined>;
     /** Main option object. Prefer this API for new usage; individual inputs stay as a migration bridge. */
-    readonly option: _angular_core.InputSignal<SdQueryBarOption<any> | undefined>;
+    readonly option: _angular_core.InputSignal<SdQueryBarOption<unknown> | undefined>;
     /** Prefix for auto-generated `data-autoid` on inner controls (chips, operator/value editors, buttons). */
     readonly autoIdInput: _angular_core.InputSignalWithTransform<string | undefined, string | null | undefined>;
     /** Available fields the user can filter by. Required for the field picker. */
@@ -312,7 +323,7 @@ declare class SdQueryBar {
      * Snapshot of the current query — fed into `<sd-query-saved-filters-menu [query]>` so
      * saving a filter captures live filters/logic/search.
      */
-    readonly currentQuery: _angular_core.Signal<SdQuery<any>>;
+    readonly currentQuery: _angular_core.Signal<SdQuery<unknown>>;
     /** Receive an applied filter from the saved-filters menu — re-install bar state + trigger apply. */
     onApplyFilter(saved: SdSavedFilter): void;
     /** Show AND/OR segmented toggle (renders only when there are ≥2 filters). */
@@ -322,9 +333,15 @@ declare class SdQueryBar {
     /** Render the operator label on the chip face (default: hidden — operator only visible in popover). */
     readonly showOperatorOnChip: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Composite payload — emitted whenever filters / logic / search change. */
-    readonly queryChange: _angular_core.OutputEmitterRef<SdQuery<any>>;
+    readonly queryChange: _angular_core.OutputEmitterRef<SdQuery<unknown>>;
     /** Fires when the user presses "Áp dụng" inside a chip popover — host should reload data. */
-    readonly apply: _angular_core.OutputEmitterRef<SdQuery<any>>;
+    readonly apply: _angular_core.OutputEmitterRef<SdQuery<unknown>>;
+    /** Placeholder của ô tìm kiếm tự do bên trái. */
+    readonly searchPlaceholder: _angular_core.Signal<string>;
+    /** Tooltip nút "+" khi consumer chưa khai `fields`. */
+    readonly noFieldsLabel: _angular_core.Signal<string>;
+    /** Tooltip nút "+" ở trạng thái bình thường. */
+    readonly addFilterLabel: _angular_core.Signal<string>;
     /** Map of `field.key` → `SdQueryField` for fast lookup from filters[]. */
     readonly resolvedAutoId: _angular_core.Signal<string | undefined>;
     readonly resolvedFields: _angular_core.Signal<SdQueryField[]>;
@@ -354,13 +371,34 @@ declare class SdQueryBar {
      * popover-mode chips read `multiple()` from the child popover directly.
      */
     multiple(op: Operator): boolean;
+    /**
+     * Stable track key of a filter row. Assigned lazily on first read.
+     *
+     * ⚠️ Hai ràng buộc với `filters`, đều là hợp đồng của consumer:
+     *
+     * 1. KHÔNG được chứa cùng một object `Filter` ở hai vị trí. Khoá theo identity nên hai vị trí sẽ
+     *    cho hai track key trùng nhau và Angular ném NG0955. Đã thử khử trùng bằng hậu tố `$index`
+     *    và HỎNG: Angular đánh giá biểu thức `track` trên CẢ collection cũ khi diff, nên một filter
+     *    vừa bị xoá cho `indexOf === -1`, key đổi, và MỌI chip bị huỷ rồi dựng lại. Để Angular báo
+     *    NG0955 là đúng — thông điệp của nó đã chỉ rõ vấn đề.
+     * 2. Object phải ỔN ĐỊNH giữa các lần change detection. Sinh lại object mới mỗi pass
+     *    (vd `[option]="{ filters: buildFilters() }"`) sẽ khiến mọi chip nhận id mới mỗi pass và bị
+     *    huỷ + dựng lại — tệ hơn cả `track $index` cũ.
+     */
+    rowId(filter: Filter): string;
     readonly iconFor: typeof sdQueryFieldIcon;
     /** Chip is "active" when it has a non-empty value OR a no-data operator (NULL/NOT_NULL). */
     isFilterActive(filter: Filter): boolean;
     /** Rendered value text on a chip. */
     chipValueText(filter: Filter): string;
     isNoDataOperator(op: Operator | string): boolean;
-    readonly building: _angular_core.Signal<BuildingChip<any> | null>;
+    readonly building: _angular_core.Signal<BuildingChip<unknown> | null>;
+    /**
+     * Allowed operators of `field` — safe to call from a template binding: `sdQueryAllowedOperators`
+     * memo hoá theo object field nên ref trả về ổn định giữa các chu kỳ CD.
+     * why: `<sd-query-build-chip [allowedOperators]>` là OnPush; ref mới mỗi CD sẽ dirty child liên
+     * tục (bug class cấp-phát-mỗi-CD).
+     */
     allowedOperatorsFor(field: SdQueryField): Operator[];
     inlineAutoId(index: number, role: string): string;
     /** Entry point from the field picker — start building a chip for `field`. */