@sdcorejs/angular 20.1.5 → 20.2.0

package/forms/models/index.d.ts

@@ -1,7 +1,10 @@
-import { InjectionToken, Signal } from '@angular/core';
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
 import { MatFormFieldAppearance } from '@angular/material/form-field';
 import { FormControl, FormControlState, ValidatorFn, FormControlOptions, AsyncValidatorFn, AbstractControl, FormGroup, NgForm } from '@angular/forms';
 import { Subject } from 'rxjs';
+import { DateFnsAdapter } from '@angular/material-date-fns-adapter';
+import { MatDateFormats } from '@angular/material/core';
 
 interface ISdFormConfiguration {
     appearance?: MatFormFieldAppearance;
@@ -43,7 +46,7 @@ type SdCustomValidator = (value: any) => string | Promise<string>;
 declare const SdInlineErrorValidator: ValidatorFn;
 declare const HandleSdCustomValidator: (func: SdCustomValidator) => AsyncValidatorFn;
 
-interface SdSelectionData<T = any> {
+interface SdSelectionData<T = unknown> {
     multiple?: boolean;
     values: any[];
     selectedItems: T[];
@@ -57,7 +60,7 @@ interface SdSearchReq<TData extends string | number = string> {
     searchFields?: string[];
     value?: TData | TData[];
 }
-type SdSearch<T = any> = (args: SdSearchReq) => Promise<T[]>;
+type SdSearch<T = unknown> = (args: SdSearchReq) => Promise<T[]>;
 
 interface SdFormControlSnapshot<T> {
     value: T | undefined;
@@ -119,6 +122,109 @@ interface SdViewedInlineApi {
  */
 declare function sdViewedInline(viewed: Signal<SdViewed>, open?: () => void, disabled?: Signal<boolean>): SdViewedInlineApi;
 
+/**
+ * Output serialization strategy for the temporal form controls (`<sd-date>`, `<sd-datetime>`,
+ * `<sd-date-range>`).
+ *
+ * This names how a committed value leaves the component — through `model` / `modelChange` /
+ * `sdChange` and the registered `FormGroup` field. It does **not** touch what the field displays,
+ * and it is **not** an Angular input-coercion `transform`.
+ */
+type SdTemporalValueTransform = 'ISOString' | 'UTCString';
+/** Every supported strategy, derived from the strategy map so the two can never drift. */
+declare const SD_TEMPORAL_VALUE_TRANSFORMS: readonly SdTemporalValueTransform[];
+declare function sdIsTemporalValueTransform(value: unknown): value is SdTemporalValueTransform;
+/**
+ * Serializes a committed value with the active strategy.
+ *
+ * Returns `null` for anything that is not a usable `Date`, so an invalid value can never reach a
+ * serializer and produce the string `"Invalid Date"`. Callers treat `null` as "keep the existing
+ * representation".
+ */
+declare function sdSerializeTemporalValue(value: Date | null | undefined, transform: SdTemporalValueTransform | null | undefined): string | null;
+/** Local midnight of the given day. Date-only controls serialize this instant, never the raw value. */
+declare function sdLocalStartOfDay(value: Date): Date;
+/**
+ * Parses the wire formats these transforms emit, so a component can read back its own output.
+ *
+ * Deliberately narrow: only ISO 8601 and the RFC-1123 shape `toUTCString()` produces are accepted.
+ * Handing the whole job to `new Date(text)` would make every loosely date-shaped string parse
+ * differently per browser, and would swallow the legacy canonical formats the components already
+ * parse with their own strict parsers. Returns `null` when the text is not one of these.
+ */
+declare function sdParseTransformedTemporal(value: unknown): Date | null;
+
+interface ɵSdModelFacingControlOptions<TModel> {
+    /** Whether the model-facing control should be the one registered in the parent form. */
+    readonly active: Signal<boolean>;
+    /** The component's public model. */
+    readonly model: Signal<TModel>;
+    /** Applies an external write that arrived through the registered control. */
+    readonly writeModel: (value: TModel) => void;
+    /** The internal UI control whose validity, disabled and interaction state must be mirrored. */
+    readonly source: Signal<AbstractControl>;
+    /** Compares two model values; defaults to `Object.is`. */
+    readonly modelEquals?: (left: TModel, right: TModel) => boolean;
+}
+interface ɵSdModelFacingControl<TModel> {
+    /** The control itself. Holds the public model value, never the editor representation. */
+    readonly control: SdFormControl;
+    /** Feed straight into `ɵsdFormControlConnector`'s `registeredControl`. */
+    readonly registered: Signal<AbstractControl | null>;
+}
+/**
+ * A second control that carries the **public model** so it can be registered in the parent form in
+ * place of the editor-facing control.
+ *
+ * why: `<sd-date>` and friends bind their control directly to the Material editor, so that control
+ * necessarily holds a `Date` or a display string. That is invisible until `transform` is set — at
+ * which point the consumer is told `form.get(name).value` equals `model`, and finding a raw `Date`
+ * there instead makes the promise false. Rather than reshaping the editor binding (which would
+ * change behaviour for every existing consumer), this mirrors the model into a control of its own
+ * and hands *that* one to the form.
+ *
+ * Both directions are wired, and neither can feed back on the other:
+ *  - model changes are pushed in with `emitEvent: false`, so they raise no `valueChanges`;
+ *  - a write that arrives on this control goes to `writeModel`, exactly like a write on the editor
+ *    control would, so `modelChange` / `sdChange` still fire once.
+ *
+ * Validity, disabled and touched/dirty are mirrored from `source`, so registering this control does
+ * not quietly drop the editor's validators (min/max, parse errors, required) from the parent form.
+ *
+ * Must be called from an injection context.
+ */
+declare function ɵsdModelFacingControl<TModel>(options: ɵSdModelFacingControlOptions<TModel>): ɵSdModelFacingControl<TModel>;
+
+/**
+ * @internal Macrotask timers owned by a component/directive injector.
+ *
+ * Every pending handle is cleared when the host is destroyed, so a deferred focus,
+ * panel-open or emit can never run against a torn-down view.
+ */
+interface ɵSdTimerScope {
+    /**
+     * `setTimeout` with the same observable timing, minus the leak: the handle is tracked
+     * and cleared on destroy. Scheduling after destroy is a no-op.
+     */
+    schedule(handler: () => void, delayMs?: number): void;
+    /** Cancels every pending timer without waiting for destroy. */
+    clear(): void;
+    /** Number of timers still pending. Test/diagnostics only. */
+    readonly pending: number;
+}
+/**
+ * @internal Creates a destroy-scoped timer bag. MUST be called from an injection context
+ * (class field initializer or constructor) because it resolves `DestroyRef`.
+ *
+ * why: gần như mọi form control đều hoãn focus / mở panel bằng `setTimeout(..., 100)` để chờ
+ * Material dựng xong DOM. Handle không được giữ lại nên callback vẫn chạy sau khi host view đã
+ * destroy — route đổi nhanh hoặc chip bị gỡ giữa lúc focus là đủ để `detectChanges()` ném
+ * `ViewDestroyedError`, hoặc để một output bắn ra sau khi consumer đã unsubscribe. Gom vào một
+ * scope duy nhất để nơi dùng chỉ cần đổi `setTimeout(fn, ms)` → `#timers.schedule(fn, ms)`,
+ * KHÔNG đổi độ trễ (đây là fix vòng đời, không phải fix hành vi).
+ */
+declare function ɵsdTimerScope(): ɵSdTimerScope;
+
 type ɵSdFormControlParent = FormGroup | NgForm | {
     readonly form: unknown;
 } | null | undefined;
@@ -129,6 +235,18 @@ interface ɵSdFormControlConnectorBaseOptions<TControl> {
     readonly name: Signal<string | null | undefined>;
     /** Canonical control registered in the parent form. */
     readonly control: Signal<AbstractControl<TControl>>;
+    /**
+     * Control to register in the parent form **instead of** `control`, when the two must differ.
+     *
+     * why: `<sd-date>` / `<sd-datetime>` / `<sd-date-range>` bind `control` straight to the Material
+     * editor, so it necessarily holds the editor's own representation (a `Date`, or the display
+     * string) — not the public model. That is fine until `transform` is set, at which point the
+     * consumer is promised that `form.get(name).value` matches `model` and the `sdChange` payload.
+     * Yielding a model-facing control here moves only the *registration*; validators, disabled, state
+     * and the model binding all stay on `control`, so a `null`/absent signal keeps today's behaviour
+     * exactly. The component owning both controls is responsible for mirroring value and validity.
+     */
+    readonly registeredControl?: Signal<AbstractControl | null | undefined>;
     readonly validators?: Signal<ValidatorFn | readonly ValidatorFn[] | null | undefined>;
     readonly asyncValidators?: Signal<AsyncValidatorFn | readonly AsyncValidatorFn[] | null | undefined>;
     /** Adds/removes Validators.required while preserving validators supplied above. */
@@ -202,5 +320,28 @@ declare function ɵsdCoerceFormGroup(value: unknown): FormGroup | undefined;
  */
 declare function ɵsdFormControlConnector<TModel, TControl>(options: ɵSdFormControlConnectorOptions<TModel, TControl>): ɵSdFormControlConnector<TControl>;
 
-export { HandleSdCustomValidator, SD_FORM_CONFIGURATION, SdFormControl, SdInlineErrorValidator, sdFormControlState, sdViewedInline, sdViewedTransform, ɵsdCoerceFormGroup, ɵsdFormControlConnector };
-export type { ISdFormConfiguration, SdCustomValidator, SdFormControlSnapshot, SdSearch, SdSearchReq, SdSelectionData, SdViewed, SdViewedInlineApi, SdViewedInput, ɵSdFormControlConnector, ɵSdFormControlConnectorOptions, ɵSdFormControlConnectorState, ɵSdFormControlParent };
+/**
+ * DateAdapter từ chối mọi chuỗi người dùng chưa gõ xong.
+ *
+ * WHY cần đến mức này: `<input matInput [matDatepicker]>` khiến Material tự
+ * `parse()` lại ô nhập SAU MỖI PHÍM GÕ rồi ghi thẳng kết quả vào form control.
+ * Adapter mặc định quá dễ dãi trên hai đường:
+ *
+ * 1. `date-fns.parse` nhận năm thiếu chữ số → `11/12/2` thành năm 0002,
+ *    `11/12/20` thành năm 0020. Ô nhập vừa gõ dở đã bị coi là hợp lệ (cờ lỗi
+ *    bị xoá) và control ôm một ngày rác.
+ * 2. `parseISO` coi chuỗi 2 chữ số là thế kỷ → xoá lùi còn `11` ra năm 1100.
+ *
+ * Cả hai đường đều bị chặn ở đây: control chỉ nhận giá trị khi người dùng thực
+ * sự gõ xong.
+ */
+declare class SdStrictDateFnsAdapter extends DateFnsAdapter {
+    parse(value: unknown, parseFormat: string | string[]): Date | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdStrictDateFnsAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SdStrictDateFnsAdapter>;
+}
+/** `provideDateFnsAdapter` + ép dùng adapter parse chặt ở trên. */
+declare function provideSdStrictDateFnsAdapter(formats: MatDateFormats): Provider[];
+
+export { HandleSdCustomValidator, SD_FORM_CONFIGURATION, SD_TEMPORAL_VALUE_TRANSFORMS, SdFormControl, SdInlineErrorValidator, SdStrictDateFnsAdapter, provideSdStrictDateFnsAdapter, sdFormControlState, sdIsTemporalValueTransform, sdLocalStartOfDay, sdParseTransformedTemporal, sdSerializeTemporalValue, sdViewedInline, sdViewedTransform, ɵsdCoerceFormGroup, ɵsdFormControlConnector, ɵsdModelFacingControl, ɵsdTimerScope };
+export type { ISdFormConfiguration, SdCustomValidator, SdFormControlSnapshot, SdSearch, SdSearchReq, SdSelectionData, SdTemporalValueTransform, SdViewed, SdViewedInlineApi, SdViewedInput, ɵSdFormControlConnector, ɵSdFormControlConnectorOptions, ɵSdFormControlConnectorState, ɵSdFormControlParent, ɵSdModelFacingControl, ɵSdModelFacingControlOptions, ɵSdTimerScope };

package/forms/select/index.d.ts

@@ -25,6 +25,9 @@ declare class SdSelectFooterActionDirective {
 declare class SdSelect<T extends object | string | number = Record<string, unknown>> implements OnInit {
     #private;
     id: string;
+    /** why: id ổn định của <mat-error> để control trỏ `aria-describedby` sang — thông báo lỗi
+     *  phải đọc được từ chính control, không chỉ hiện ra màn hình. */
+    readonly errorId: string;
     matInputRef: Signal<MatInput | undefined>;
     selectRef: Signal<MatSelect | undefined>;
     sdLabelTemplate: Signal<TemplateRef<any> | undefined>;
@@ -62,8 +65,8 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     label: _angular_core.InputSignal<string | undefined>;
     helperText: _angular_core.InputSignal<string | undefined>;
     placeholder: _angular_core.InputSignal<string | undefined>;
-    valueField: _angular_core.InputSignal<T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string>;
-    displayField: _angular_core.InputSignal<T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string>;
+    valueField: _angular_core.InputSignal<"" | (T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string)>;
+    displayField: _angular_core.InputSignal<"" | (T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string)>;
     disabledField: _angular_core.InputSignal<"" | (T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string)>;
     cacheChecksum: _angular_core.InputSignal<any>;
     limit: _angular_core.InputSignal<number>;
@@ -75,6 +78,11 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     /** Display mode: `false` edit · `true` static view · `'inline'` view + click-to-edit (bare editor). */
     viewed: _angular_core.InputSignalWithTransform<SdViewed, SdViewedInput>;
     multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Hiện option "Tất cả" đầu panel (chỉ multiple + items là mảng tĩnh/Signal — ẩn với
+     * SdSearch lazy vì dataset không xác định). Opt-in, default `false`.
+     */
+    showSelectAll: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /**
      * Whether the `viewed='inline'` text face shows a hover clear-× to empty the value.
      * Default `true`. Set `false` where the HOST owns removal (e.g. `<sd-query-bar>` chips,
@@ -99,7 +107,7 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     items: _angular_core.InputSignal<SdSearch | T[] | Signal<T[]> | null | undefined>;
     valueModel: _angular_core.ModelSignal<string | number | boolean | (string | number)[] | null | undefined>;
     sdChange: _angular_core.OutputEmitterRef<any>;
-    sdSelection: _angular_core.OutputEmitterRef<SdSelectionData<any>>;
+    sdSelection: _angular_core.OutputEmitterRef<SdSelectionData<unknown>>;
     formControl: SdFormControl;
     inputControl: FormControl<string | null>;
     loading: _angular_core.WritableSignal<boolean>;
@@ -120,6 +128,15 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     normalizedValue: Signal<string | number | boolean | (string | number | boolean)[] | null | undefined>;
     filtered: Signal<boolean>;
     delayTime: Signal<0 | 500>;
+    /**
+     * Scope của "Tất cả": item enabled khớp search text hiện tại, tính trên MẢNG NGUỒN
+     * `actualItems()`.
+     */
+    readonly selectAllScope: Signal<T[]>;
+    /** Row "Tất cả" chỉ render khi opt-in + multiple + items tĩnh + scope có item để thao tác. */
+    readonly selectAllVisible: Signal<boolean>;
+    /** Trạng thái checkbox "Tất cả", tính trên items ENABLED trong scope (item disabled bỏ qua). */
+    readonly selectAllState: Signal<"checked" | "indeterminate" | "unchecked">;
     itemValue: (item: T) => unknown;
     itemDisplay: (item: T) => string;
     itemDisabled: (item: T) => boolean;
@@ -130,6 +147,12 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     constructor();
     ngOnInit(): void;
     onSelectionChange: (change: MatSelectChange) => void;
+    /**
+     * Toggle "Tất cả" theo scope hiện tại (items enabled khớp search):
+     * - Đang `checked` → BỎ chọn các value trong scope (giữ value ngoài scope, kể cả item disabled đã chọn).
+     * - Ngược lại → CHỌN THÊM toàn bộ scope, union với selection hiện có (additive khi đang search).
+     */
+    toggleSelectAll: () => void;
     reValidate: () => void;
     clear: ($event?: any) => void;
     onClick: () => void;
@@ -140,7 +163,7 @@ declare class SdSelect<T extends object | string | number = Record<string, unkno
     open: () => void;
     onOpenedChange: (isOpened: boolean) => void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdSelect<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdSelect<any>, "sd-select", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "form": { "alias": "form"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": true; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": true; "isSignal": true; }; "disabledField": { "alias": "disabledField"; "required": false; "isSignal": true; }; "cacheChecksum": { "alias": "cacheChecksum"; "required": false; "isSignal": true; }; "limit": { "alias": "limit"; "required": false; "isSignal": true; }; "hyperlink": { "alias": "hyperlink"; "required": false; "isSignal": true; }; "minWidthPanel": { "alias": "minWidthPanel"; "required": false; "isSignal": true; }; "hideInlineError": { "alias": "hideInlineError"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "viewed": { "alias": "viewed"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "validator": { "alias": "validator"; "required": false; "isSignal": true; }; "inlineError": { "alias": "inlineError"; "required": false; "isSignal": true; }; "appearanceInput": { "alias": "appearance"; "required": false; "isSignal": true; }; "floatLabel": { "alias": "floatLabel"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "valueModel": { "alias": "model"; "required": false; "isSignal": true; }; }, { "valueModel": "modelChange"; "sdChange": "sdChange"; "sdSelection": "sdSelection"; }, ["sdLabelTemplate", "sdValueTemplate", "sdSelectedTemplate", "itemDef", "sdViewDef", "footerActions"], ["[sdLabel]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdSelect<any>, "sd-select", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "form": { "alias": "form"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": false; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": false; "isSignal": true; }; "disabledField": { "alias": "disabledField"; "required": false; "isSignal": true; }; "cacheChecksum": { "alias": "cacheChecksum"; "required": false; "isSignal": true; }; "limit": { "alias": "limit"; "required": false; "isSignal": true; }; "hyperlink": { "alias": "hyperlink"; "required": false; "isSignal": true; }; "minWidthPanel": { "alias": "minWidthPanel"; "required": false; "isSignal": true; }; "hideInlineError": { "alias": "hideInlineError"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "viewed": { "alias": "viewed"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "showSelectAll": { "alias": "showSelectAll"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "validator": { "alias": "validator"; "required": false; "isSignal": true; }; "inlineError": { "alias": "inlineError"; "required": false; "isSignal": true; }; "appearanceInput": { "alias": "appearance"; "required": false; "isSignal": true; }; "floatLabel": { "alias": "floatLabel"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "valueModel": { "alias": "model"; "required": false; "isSignal": true; }; }, { "valueModel": "modelChange"; "sdChange": "sdChange"; "sdSelection": "sdSelection"; }, ["sdLabelTemplate", "sdValueTemplate", "sdSelectedTemplate", "itemDef", "sdViewDef", "footerActions"], ["[sdLabel]"], true, never>;
 }
 
 export { SdSelect, SdSelectFooterActionDirective };

package/forms/switch/index.d.ts

@@ -1,6 +1,7 @@
+import * as _sdcorejs_angular_forms_models from '@sdcorejs/angular/forms/models';
+import { SdFormControl, ɵSdFormControlParent as _SdFormControlParent, SdViewed, SdViewedInput } from '@sdcorejs/angular/forms/models';
 import * as _angular_core from '@angular/core';
 import { OnInit, OnDestroy } from '@angular/core';
-import { SdFormControl, ɵSdFormControlParent as _SdFormControlParent, SdViewed, SdViewedInput } from '@sdcorejs/angular/forms/models';
 import { Color } from '@sdcorejs/utils/models';
 
 declare class SdSwitch implements OnInit, OnDestroy {
@@ -26,6 +27,11 @@ declare class SdSwitch implements OnInit, OnDestroy {
     readonly dataEmpty: _angular_core.Signal<"true" | "false">;
     readonly dataValue: _angular_core.Signal<string>;
     readonly dataRequired: _angular_core.Signal<"true" | "false">;
+    readonly errorMessage: _angular_core.Signal<string | undefined>;
+    /** Shared reactive form policy — `validationError` is already interaction-gated (touched/dirty). */
+    readonly connectorState: _angular_core.Signal<_sdcorejs_angular_forms_models.ɵSdFormControlConnectorState<boolean | null | undefined>>;
+    /** Message to render inline; `undefined` while untouched, or when `hideInlineError` is set. */
+    readonly visibleErrorMessage: _angular_core.Signal<string | undefined>;
     ngOnInit(): void;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdSwitch, never>;

package/forms/textarea/index.d.ts

@@ -1,14 +1,17 @@
 import * as _angular_core from '@angular/core';
-import { OnInit, AfterViewInit, OnDestroy, ElementRef } from '@angular/core';
+import { OnInit, OnDestroy, ElementRef } from '@angular/core';
 import { FormGroup } from '@angular/forms';
 import { MatFormFieldAppearance, FloatLabelType } from '@angular/material/form-field';
 import { SdViewDefDirective, SdLabelDefDirective, SdSuffixDefDirective } from '@sdcorejs/angular/forms/directives';
 import { SdViewed, SdViewedInput, SdCustomValidator, SdFormControl } from '@sdcorejs/angular/forms/models';
 import { Size } from '@sdcorejs/utils/models';
 
-declare class SdTextarea implements OnInit, AfterViewInit, OnDestroy {
+declare class SdTextarea implements OnInit, OnDestroy {
     #private;
     id: string;
+    /** why: id ổn định của <mat-error> để control trỏ `aria-describedby` sang — thông báo lỗi
+     *  phải đọc được từ chính control, không chỉ hiện ra màn hình. */
+    readonly errorId: string;
     textareaRef: _angular_core.Signal<ElementRef<HTMLTextAreaElement> | undefined>;
     sdViewDef: _angular_core.Signal<SdViewDefDirective<any, any> | undefined>;
     sdLabelDef: _angular_core.Signal<SdLabelDefDirective | undefined>;
@@ -59,7 +62,6 @@ declare class SdTextarea implements OnInit, AfterViewInit, OnDestroy {
     isFocused: boolean;
     constructor();
     ngOnInit(): void;
-    ngAfterViewInit(): void;
     ngOnDestroy(): void;
     onFocus: () => void;
     onBlur: () => void;

package/forms/time-range/index.d.ts

@@ -75,8 +75,29 @@ declare class SdTimeRange {
     readonly isReadonly: _angular_core.Signal<boolean>;
     readonly viewTemplate: _angular_core.Signal<TemplateRef<unknown> | undefined>;
     readonly displayValue: _angular_core.Signal<string>;
-    readonly showClear: _angular_core.Signal<boolean>;
+    /**
+     * Endpoint invalid ĐÃ gate theo tương tác — CHỈ dùng cho hiển thị (message, `data-invalid`).
+     * `connectorState().invalid` của `sd-time` là `invalid && (touched || dirty)`.
+     */
     readonly endpointInvalid: _angular_core.Signal<boolean>;
+    /**
+     * Endpoint invalid THÔ — không gate theo tương tác. Dùng cho VALIDATOR của control tổng.
+     * why: endpoint không còn được đăng ký vào FormGroup của consumer, nên validity của chúng chỉ
+     * tới được form cha qua control tổng. Nếu đường đó cũng gate theo `touched || dirty` thì một
+     * endpoint invalid do ghi programmatic (chưa ai chạm vào) sẽ để form cha VALID — sai contract
+     * đã ghi trong `sd-time-range.md`.
+     * `formControl.invalid` là property thường nên tự nó không phát tín hiệu; đọc `connectorState()`
+     * một nhịp để computed có dependency reactive theo `events` của endpoint control.
+     */
+    readonly endpointInvalidRaw: _angular_core.Signal<boolean>;
+    /**
+     * Message đã gate theo tương tác — thứ template được phép hiển thị.
+     * why: `errorMessage()` thô bung lỗi ngay lần paint đầu với `[required]`, khi người dùng chưa
+     * chạm vào ô nào. `connectorState().validationError` gate theo control tổng; range còn có 2
+     * endpoint có thể invalid trong khi control tổng chưa dirty (text sai không tới được model tổng),
+     * nên phải cộng thêm nhánh endpoint — `endpointInvalid` tự nó đã gate theo touched/dirty.
+     */
+    readonly visibleError: _angular_core.Signal<string | undefined>;
     readonly dataDisabled: _angular_core.Signal<"true" | "false">;
     readonly dataInvalid: _angular_core.Signal<"true" | "false">;
     readonly dataEmpty: _angular_core.Signal<"true" | "false">;

package/forms/tree-select/index.d.ts

@@ -2,9 +2,12 @@ import * as _sdcorejs_angular_forms_models from '@sdcorejs/angular/forms/models'
 import { ɵSdFormControlParent as _SdFormControlParent, SdViewed, SdViewedInput, SdFormControl } from '@sdcorejs/angular/forms/models';
 import * as _angular_core from '@angular/core';
 import { ElementRef, TemplateRef } from '@angular/core';
-import { FormGroup } from '@angular/forms';
+import { FormGroup, FormControl } from '@angular/forms';
+import { ErrorStateMatcher } from '@angular/material/core';
+import { MatFormFieldAppearance } from '@angular/material/form-field';
 import { SdModal } from '@sdcorejs/angular/components/modal';
 import { SdTree, SdTreeItemContext, SdTreeDataSource, SdTreeItem, SdTreeOption, SdTreeLoadErrorEvent, SdTreeComponentOption, SdTreeSelectionEvent } from '@sdcorejs/angular/components/tree';
+import { Size } from '@sdcorejs/utils/models';
 
 type SdTreeSelectModel<TKey> = TKey | TKey[] | null | undefined;
 type SdTreeSelectTemplateContext<T> = SdTreeItemContext<T>;
@@ -16,18 +19,24 @@ declare class SdTreeSelectNodeTemplateDirective<T> {
 }
 declare class SdTreeSelect<T = unknown, TKey = string | number> {
     #private;
-    readonly trigger: _angular_core.Signal<ElementRef<HTMLButtonElement> | undefined>;
+    readonly trigger: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
     readonly modal: _angular_core.Signal<SdModal | undefined>;
     readonly treeComponent: _angular_core.Signal<SdTree<T> | undefined>;
     readonly nodeTemplate: _angular_core.Signal<SdTreeSelectNodeTemplateDirective<any> | undefined>;
+    readonly errorId: string;
     readonly autoIdInput: _angular_core.InputSignal<string | null | undefined>;
     readonly autoId: _angular_core.Signal<string | undefined>;
     readonly name: _angular_core.InputSignal<string>;
     readonly form: _angular_core.InputSignalWithTransform<FormGroup<any> | undefined, _SdFormControlParent>;
     readonly label: _angular_core.InputSignal<string | undefined>;
+    readonly helperText: _angular_core.InputSignal<string | undefined>;
     readonly placeholder: _angular_core.InputSignal<string | null | undefined>;
     readonly modalTitle: _angular_core.InputSignal<string | null | undefined>;
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    readonly size: _angular_core.InputSignal<Size>;
+    readonly appearanceInput: _angular_core.InputSignal<MatFormFieldAppearance | undefined>;
+    readonly appearance: _angular_core.Signal<MatFormFieldAppearance>;
+    readonly hideInlineError: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly items: _angular_core.InputSignal<SdTreeDataSource<SdTreeItem<T>>>;
     readonly tree: _angular_core.InputSignal<SdTreeOption<T>>;
     readonly valueField: _angular_core.InputSignal<(T extends object ? { [Key in keyof T & string]: T[Key] extends string | number | boolean | Function | Date | null | undefined ? Key : T[Key] extends any[] ? Key : T[Key] extends object ? Key | `${Key}.${T[Key] extends infer T_1 ? T_1 extends T[Key] ? T_1 extends object ? { [Key_1 in keyof T_1 & string]: T_1[Key_1] extends string | number | boolean | Function | Date | null | undefined ? Key_1 : T_1[Key_1] extends any[] ? Key_1 : T_1[Key_1] extends object ? Key_1 | `${Key_1}.${T_1[Key_1] extends infer T_2 ? T_2 extends T_1[Key_1] ? T_2 extends object ? { [Key_2 in keyof T_2 & string]: T_2[Key_2] extends string | number | boolean | Function | Date | null | undefined ? Key_2 : T_2[Key_2] extends any[] ? Key_2 : T_2[Key_2] extends object ? Key_2 | `${Key_2}.${T_2[Key_2] extends infer T_3 ? T_3 extends T_2[Key_2] ? T_3 extends object ? { [Key_3 in keyof T_3 & string]: T_3[Key_3] extends string | number | boolean | Function | Date | null | undefined ? Key_3 : T_3[Key_3] extends any[] ? Key_3 : T_3[Key_3] extends object ? Key_3 : Key_3; }[keyof T_3 & string] : string : never : never}` : Key_2; }[keyof T_2 & string] : string : never : never}` : Key_1; }[keyof T_1 & string] : string : never : never}` : Key; }[keyof T & string] : string) | undefined>;
@@ -39,15 +48,36 @@ declare class SdTreeSelect<T = unknown, TKey = string | number> {
     readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly cascade: _angular_core.InputSignal<"independent" | "descendants">;
     readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Component-local error text. Set it to force the control invalid and render the message. */
+    readonly inlineError: _angular_core.InputSignal<string | undefined>;
     readonly clearable: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly viewed: _angular_core.InputSignalWithTransform<SdViewed, SdViewedInput>;
     readonly model: _angular_core.ModelSignal<SdTreeSelectModel<TKey>>;
     readonly sdChange: _angular_core.OutputEmitterRef<SdTreeSelectModel<TKey>>;
-    readonly sdLoadError: _angular_core.OutputEmitterRef<SdTreeLoadErrorEvent<T>>;
+    readonly loadError: _angular_core.OutputEmitterRef<SdTreeLoadErrorEvent<T>>;
     readonly formControl: SdFormControl;
+    readonly errorMessage: _angular_core.Signal<string | undefined>;
     readonly connectorState: _angular_core.Signal<_sdcorejs_angular_forms_models.ɵSdFormControlConnectorState<SdTreeSelectModel<TKey>>>;
+    /** Interaction-gated validation message; `undefined` until the control is touched/dirty. */
+    readonly visibleErrorMessage: _angular_core.Signal<string | undefined>;
+    /**
+     * Text-only control backing the readonly trigger; `formControl` above holds the real keys.
+     *
+     * why: phải là một `FormControl` THẬT chứ không phải `[value]`. `MatInput.ngDoCheck` chỉ gọi
+     * `updateErrorState()` khi có `NgControl` — không có nó thì `errorState` đứng yên ở `false`, mà
+     * `<mat-error>`, viền đỏ và `aria-invalid` đều bám vào cờ đó, nên field bắt buộc bỏ trống lại im
+     * lặng y như bug cũ. Trạng thái disabled cũng chảy qua control này (MatInput tự đồng bộ
+     * `disabled` từ `ngControl` mỗi vòng CD, nên bind `[disabled]` trên template sẽ bị ghi đè).
+     */
+    readonly displayControl: FormControl<string>;
+    /**
+     * why: MatInput đã có `NgControl`, nhưng control đó là ô TEXT — nó không biết gì về `required`
+     * hay validator của tree-select. Matcher nối thẳng `errorState` của Material vào message đã gate
+     * theo tương tác của connector.
+     */
+    readonly errorStateMatcher: ErrorStateMatcher;
     readonly draftKeys: _angular_core.WritableSignal<TKey[]>;
     readonly modelKeys: _angular_core.Signal<TKey[]>;
     readonly effectivePlaceholder: _angular_core.Signal<string>;
@@ -57,7 +87,8 @@ declare class SdTreeSelect<T = unknown, TKey = string | number> {
     readonly draftEntities: _angular_core.Signal<T[]>;
     readonly displayText: _angular_core.Signal<string>;
     readonly treeOption: _angular_core.Signal<SdTreeComponentOption<T>>;
-    open(): void;
+    constructor();
+    open(event?: Event): void;
     applySelection(): void;
     cancel(): void;
     clear(event?: Event): void;
@@ -68,7 +99,7 @@ declare class SdTreeSelect<T = unknown, TKey = string | number> {
     keyOf(item: T): TKey;
     displayEntity(item: T): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdTreeSelect<any, any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdTreeSelect<any, any>, "sd-tree-select", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "form": { "alias": "form"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "modalTitle": { "alias": "modalTitle"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "tree": { "alias": "tree"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": false; "isSignal": true; }; "keySelector": { "alias": "keySelector"; "required": false; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "disabledNode": { "alias": "disabledNode"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "cascade": { "alias": "cascade"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "viewed": { "alias": "viewed"; "required": false; "isSignal": true; }; "model": { "alias": "model"; "required": false; "isSignal": true; }; }, { "model": "modelChange"; "sdChange": "sdChange"; "sdLoadError": "sdLoadError"; }, ["nodeTemplate"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdTreeSelect<any, any>, "sd-tree-select", never, { "autoIdInput": { "alias": "autoId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "form": { "alias": "form"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "helperText": { "alias": "helperText"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "modalTitle": { "alias": "modalTitle"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "appearanceInput": { "alias": "appearance"; "required": false; "isSignal": true; }; "hideInlineError": { "alias": "hideInlineError"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "tree": { "alias": "tree"; "required": false; "isSignal": true; }; "valueField": { "alias": "valueField"; "required": false; "isSignal": true; }; "keySelector": { "alias": "keySelector"; "required": false; "isSignal": true; }; "displayField": { "alias": "displayField"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "disabledNode": { "alias": "disabledNode"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "cascade": { "alias": "cascade"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "inlineError": { "alias": "inlineError"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "viewed": { "alias": "viewed"; "required": false; "isSignal": true; }; "model": { "alias": "model"; "required": false; "isSignal": true; }; }, { "model": "modelChange"; "sdChange": "sdChange"; "loadError": "loadError"; }, ["nodeTemplate"], ["[sdLabel]"], true, never>;
 }
 declare function normalizeTreeSelectKeys<TKey>(value: SdTreeSelectModel<TKey>, multiple: boolean): TKey[];