@sdcorejs/angular 19.2.0 → 19.2.2

package/components/api-contract-builder/src/components/api-contract-node-drawer.component.d.ts

@@ -0,0 +1,130 @@
+import { SdSideDrawer } from '@sdcorejs/angular/components/side-drawer';
+import { type SdApiContractDataType } from '../api-contract.model';
+import { type SdApiContractStructuralNode } from '../api-contract.schema';
+import type { SdApiContractSuggestion } from './api-contract-suggestion.model';
+import * as i0 from "@angular/core";
+/** What the drawer hands back when the author closes the books on one node. */
+export interface SdApiContractNodeCommit {
+    name: string;
+    node: SdApiContractStructuralNode;
+}
+/**
+ * A layer list asking for the drawer to be opened.
+ *
+ * The list does not own the drawer — the builder does, so there is exactly one drawer and one staged
+ * draft on the page. The list only says which node the author reached for; the builder knows which
+ * section that list was wired into and applies the commit there.
+ */
+export interface SdApiContractNodeEditRequest {
+    /** `null` means "add a new node to this collection". */
+    name: string | null;
+    node: SdApiContractStructuralNode | null;
+    /** Names already taken at this level, so the drawer can refuse a duplicate. */
+    siblingNames: readonly string[];
+    /**
+     * Where the listed collection sits inside its layer root — `[]` for an object layer, `['items']`
+     * for an array layer whose fields belong to the element.
+     *
+     * why cần: drawer không dùng field này, nhưng builder thì có. Một tầng `array` (vd `output.schema`
+     * nhận `${res.body.items}`) khai field ở `items.properties`, còn tầng `object` khai ở `properties`.
+     * Danh sách đã biết mình đang đọc chỗ nào, nên nó nói ra thay vì để builder đoán lại.
+     */
+    pointer?: readonly string[];
+}
+interface SdApiContractOption {
+    value: string;
+    label: string;
+}
+/**
+ * Editing surface for exactly one node, staged and committed in one go.
+ *
+ * The layer lists outside are read-only, so this drawer is the only place a node changes. It holds a
+ * DEEP COPY of the node it was seeded from and emits `nodeCommit` once, when the author saves — that
+ * is what makes "Huỷ" able to actually cancel, and what keeps the tree from changing under the
+ * author's cursor on every keystroke.
+ *
+ * Save is blocked only for the two problems that stop a node from existing at all: no name, or a name
+ * a sibling already holds. Everything else — a reference to a field that does not exist yet, a type
+ * that will not fit — saves and is reported by `validateSdApiContract`, because inventing rules here
+ * would stop an author declaring one end of a mapping before the other exists.
+ */
+export declare class SdApiContractNodeDrawer {
+    #private;
+    /** `mapping` shows the value editor; `schema` is a plain declaration with no mapping. */
+    layer: import("@angular/core").InputSignal<"schema" | "mapping">;
+    allowTransform: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    suggestions: import("@angular/core").InputSignal<readonly SdApiContractSuggestion[]>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    nodeCommit: import("@angular/core").OutputEmitterRef<SdApiContractNodeCommit>;
+    protected readonly drawerRef: import("@angular/core").Signal<SdSideDrawer>;
+    protected readonly draftName: import("@angular/core").Signal<string>;
+    protected readonly discardPrompt: import("@angular/core").Signal<boolean>;
+    /** The node the author is looking at right now — the draft root, or a descendant of it. */
+    protected readonly current: import("@angular/core").Signal<SdApiContractStructuralNode | null>;
+    /** Every key on the breadcrumb. The pointer alternates `properties`/key, so keys sit on odd slots. */
+    protected readonly breadcrumb: import("@angular/core").Signal<string[]>;
+    /**
+     * What the name field shows.
+     *
+     * why một signal riêng chứ không đọc thẳng từ draft: một tên KHÔNG áp được — rỗng, hoặc trùng
+     * sibling — vẫn phải hiện ra để người dùng thấy mình vừa gõ gì và đọc được lý do bị chặn. Đọc
+     * thẳng từ draft thì ô input nhảy về tên cũ ngay khi gõ, tức là từ chối im lặng.
+     */
+    protected readonly currentName: import("@angular/core").Signal<string>;
+    protected readonly children: import("@angular/core").Signal<{
+        key: string;
+        node: SdApiContractStructuralNode;
+    }[]>;
+    /** Siblings on the level the author is on — the root list, or the parent object's keys. */
+    protected readonly siblingNames: import("@angular/core").Signal<readonly string[]>;
+    protected readonly typeOptions: SdApiContractOption[];
+    protected readonly requiredOptions: SdApiContractOption[];
+    protected readonly transformOptions: SdApiContractOption[];
+    protected readonly title: import("@angular/core").Signal<string>;
+    protected readonly dirty: import("@angular/core").Signal<boolean>;
+    protected readonly nameError: import("@angular/core").Signal<string | null>;
+    protected readonly canSave: import("@angular/core").Signal<boolean>;
+    /**
+     * `beforeClose` guard for `<sd-side-drawer>`.
+     *
+     * why an arrow field, not a method: the drawer takes it as an input value, so it must keep `this`
+     * without the template having to bind it.
+     */
+    protected readonly closeGuard: () => boolean;
+    openForAdd(siblingNames?: readonly string[], type?: SdApiContractDataType): void;
+    openForEdit(name: string, node: SdApiContractStructuralNode, siblingNames?: readonly string[]): void;
+    /**
+     * Types into the name field.
+     *
+     * The typed text is ALWAYS kept, then applied to the draft only when it can be. A name that cannot
+     * be applied — empty, or already taken by a sibling — stays visible and `nameError()` explains it,
+     * which is what blocks Save. Refusing the keystroke instead would leave the field showing one name
+     * while the contract holds another.
+     */
+    protected setName(value: unknown): void;
+    protected setType(value: unknown): void;
+    protected setRequired(value: unknown): void;
+    protected setText(key: 'label' | 'description', value: unknown): void;
+    protected setTransform(value: unknown): void;
+    protected applyCurrent(node: SdApiContractStructuralNode): void;
+    protected enter(key: string): void;
+    /** `depth` counts breadcrumb entries, so 0 is the draft root. */
+    protected backTo(depth: number): void;
+    protected addChild(): void;
+    protected removeChild(key: string): void;
+    protected save(): void;
+    protected requestCancel(): void;
+    protected confirmDiscard(): void;
+    protected cancelDiscard(): void;
+    /**
+     * Blocks the close while the draft is dirty and raises an inline prompt instead.
+     *
+     * why inline chứ không `window.confirm`: một component thư viện không được dựng dialog của browser
+     * — nó không style được, không test được, và chặn cả tab.
+     */
+    protected guardClose(): boolean;
+    protected onClosed(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractNodeDrawer, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractNodeDrawer, "sd-api-contract-node-drawer", never, { "layer": { "alias": "layer"; "required": false; "isSignal": true; }; "allowTransform": { "alias": "allowTransform"; "required": false; "isSignal": true; }; "suggestions": { "alias": "suggestions"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "nodeCommit": "nodeCommit"; }, never, never, true, never>;
+}
+export {};

package/components/api-contract-builder/src/components/api-contract-node-editor.component.d.ts

@@ -0,0 +1,35 @@
+import { type SdApiContractStructuralNode } from '../api-contract.schema';
+import type { SdApiContractNodeEditRequest } from './api-contract-node-drawer.component';
+import * as i0 from "@angular/core";
+interface SdApiContractPropertyEntry {
+    key: string;
+    node: SdApiContractStructuralNode;
+}
+/**
+ * One schema layer — `input.schema`, `req.body`, `res.body`, `output.schema` — rendered as a flat list
+ * of the fields it declares.
+ *
+ * It used to be a recursive tree of editable seven-column rows. It is now a list you read: adding and
+ * editing ask the builder to open its drawer, and only removal is applied straight away. The list is
+ * deliberately FLAT — an `object` field shows how many fields it holds and the author drills into it
+ * inside the drawer, so a deeply nested node is edited with a drawer's worth of room instead of a
+ * 100px cell.
+ */
+export declare class SdApiContractNodeEditor {
+    #private;
+    /** The layer's root node. */
+    node: import("@angular/core").InputSignal<SdApiContractStructuralNode>;
+    /** Diagnostic path of the layer itself, e.g. `input.schema`. */
+    basePath: import("@angular/core").InputSignal<string>;
+    disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    nodeChange: import("@angular/core").OutputEmitterRef<SdApiContractStructuralNode>;
+    editRequest: import("@angular/core").OutputEmitterRef<SdApiContractNodeEditRequest>;
+    protected readonly entries: import("@angular/core").Signal<SdApiContractPropertyEntry[]>;
+    protected requestAdd(): void;
+    protected requestEdit(key: string, node: SdApiContractStructuralNode): void;
+    protected removeProperty(key: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractNodeEditor, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractNodeEditor, "sd-api-contract-node-editor", never, { "node": { "alias": "node"; "required": true; "isSignal": true; }; "basePath": { "alias": "basePath"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "nodeChange": "nodeChange"; "editRequest": "editRequest"; }, never, never, true, never>;
+}
+export {};

package/components/api-contract-builder/src/components/api-contract-node-summary.component.d.ts

@@ -0,0 +1,41 @@
+import type { SdApiContractStructuralNode } from '../api-contract.schema';
+import * as i0 from "@angular/core";
+/**
+ * One collapsed, read-only row for a node in a layer list.
+ *
+ * The whole point is that it holds NO editable control. Editing a node happens in the drawer, so the
+ * list can stay a thing you scan rather than a wall of inputs — and so a node never has two editors
+ * writing it at once.
+ *
+ * The row shows what an author needs to spot a mistake without opening anything: the name, the
+ * declared type, whether it is required, and where its value comes from.
+ */
+export declare class SdApiContractNodeSummary {
+    #private;
+    name: import("@angular/core").InputSignal<string>;
+    node: import("@angular/core").InputSignal<SdApiContractStructuralNode>;
+    /** `view` mode and `disabled` both land here: the row becomes text, with no action at all. */
+    readonly: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    edit: import("@angular/core").OutputEmitterRef<void>;
+    remove: import("@angular/core").OutputEmitterRef<void>;
+    protected readonly requiredLabel: string;
+    protected readonly removeLabel: string;
+    protected readonly unmapped: import("@angular/core").Signal<boolean>;
+    /**
+     * One line describing where the value comes from.
+     *
+     * why bốn dạng khác nhau: `${input.keyword}` rút về `input.keyword` vì dấu `${}` là cú pháp chứ
+     * không phải thông tin; còn template ghép giữ NGUYÊN VĂN vì rút gọn nó sẽ sai. Literal hiện giá trị
+     * để thấy ngay, object hiện số trường để biết còn bao nhiêu phải mở ra xem.
+     */
+    protected readonly mappingSummary: import("@angular/core").Signal<string>;
+    protected requestEdit(): void;
+    /**
+     * why stopPropagation: nút xoá nằm TRONG hàng có `(click)`, nên không chặn thì bấm xoá cũng mở
+     * drawer — người dùng bấm xoá lại thấy form hiện ra.
+     */
+    protected requestRemove(event: Event): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractNodeSummary, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractNodeSummary, "sd-api-contract-node-summary", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "node": { "alias": "node"; "required": true; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "edit": "edit"; "remove": "remove"; }, never, never, true, never>;
+}

package/components/api-contract-builder/src/components/api-contract-record-editor.component.d.ts

@@ -0,0 +1,36 @@
+import { type SdApiContractStructuralNode } from '../api-contract.schema';
+import type { SdApiContractNodeEditRequest } from './api-contract-node-drawer.component';
+import * as i0 from "@angular/core";
+type SdApiContractNodeRecord = Record<string, SdApiContractStructuralNode>;
+interface SdApiContractRecordEntry {
+    key: string;
+    node: SdApiContractStructuralNode;
+    path: string;
+}
+/**
+ * One keyed collection of nodes — `req.path` / `req.query` / `req.headers` / `res.headers` — rendered
+ * as a list you read, not a list you type into.
+ *
+ * Every entry is a collapsed row. Adding and editing both ask the builder to open its drawer; only
+ * removal is applied straight away, because there is nothing to stage about deleting a row. That is
+ * why `add()` emits an edit request rather than an entry: a half-declared field must never reach the
+ * contract just because someone clicked the add button and changed their mind.
+ */
+export declare class SdApiContractRecordEditor {
+    #private;
+    record: import("@angular/core").InputSignal<SdApiContractNodeRecord | undefined>;
+    /** Diagnostic path of the collection itself, e.g. `req.query`. */
+    basePath: import("@angular/core").InputSignal<string>;
+    disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    emptyLabel: import("@angular/core").InputSignal<string>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    recordChange: import("@angular/core").OutputEmitterRef<SdApiContractNodeRecord>;
+    editRequest: import("@angular/core").OutputEmitterRef<SdApiContractNodeEditRequest>;
+    protected readonly entries: import("@angular/core").Signal<SdApiContractRecordEntry[]>;
+    protected requestAdd(): void;
+    protected requestEdit(entry: SdApiContractRecordEntry): void;
+    protected remove(key: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractRecordEditor, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractRecordEditor, "sd-api-contract-record-editor", never, { "record": { "alias": "record"; "required": false; "isSignal": true; }; "basePath": { "alias": "basePath"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "emptyLabel": { "alias": "emptyLabel"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "recordChange": "recordChange"; "editRequest": "editRequest"; }, never, never, true, never>;
+}
+export {};

package/components/api-contract-builder/src/components/api-contract-source-editor.component.d.ts

@@ -0,0 +1,86 @@
+import type { SdApiContractStructuralNode } from '../api-contract.schema';
+import type { SdApiContractSuggestion } from './api-contract-suggestion.model';
+import * as i0 from "@angular/core";
+/**
+ * How a mapped node receives its value.
+ *
+ * - `source` — one whole-value reference, picked from a dropdown.
+ * - `advanced` — a raw template the dropdown cannot express, e.g. `Bearer ${env.token}`.
+ * - `static` — a literal typed in a control that matches the declared type.
+ * - `nested` — an object mapped field by field.
+ * - `none` — CHƯA GÁN. Không phải một lựa chọn trong picker: picker để trống + `required`, nên node
+ *   chưa gán là lỗi thấy ngay trên hàng thay vì một giá trị trông như đã chọn.
+ */
+export type SdApiContractValueMode = 'source' | 'advanced' | 'static' | 'nested' | 'none';
+interface SdApiContractOption {
+    value: string;
+    label: string;
+}
+/**
+ * Value editor for one mapped node: a mode picker plus one control chosen by the mode.
+ *
+ * `source` shows a single dropdown of the references the surrounding schemas and the injected env
+ * catalog make available — the author never types `${…}` for the common case. `advanced` keeps a raw
+ * expression field for what a dropdown cannot express (`Bearer ${env.token}`). `static` renders a
+ * control matching the declared type, including a JSON editor for `object` / `array` literals.
+ *
+ * The JSON editor for a composite literal only writes when the text parses. While it is half-typed it
+ * emits the raw string, and that string is dropped — otherwise one keystroke would turn a literal
+ * object into a garbage string in the contract.
+ */
+export declare class SdApiContractSourceEditor {
+    #private;
+    node: import("@angular/core").InputSignal<SdApiContractStructuralNode>;
+    suggestions: import("@angular/core").InputSignal<readonly SdApiContractSuggestion[]>;
+    disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    nodeChange: import("@angular/core").OutputEmitterRef<SdApiContractStructuralNode>;
+    protected readonly advancedPlaceholder = "Bearer ${env.token}";
+    protected readonly booleanOptions: SdApiContractOption[];
+    protected readonly mode: import("@angular/core").WritableSignal<SdApiContractValueMode>;
+    /**
+     * Giá trị hiển thị của picker.
+     *
+     * why: `none` không còn là một option, nên bind nó vào `[model]` sẽ ra một ô trống mà người dùng
+     * không hiểu tại sao. Trả `null` để picker rỗng THẬT — cộng `required`, một node chưa gán trở thành
+     * lỗi thấy được ngay trên hàng, khớp với diagnostic `mapping.node.unmapped` mà validation đã báo.
+     */
+    protected readonly modeValue: import("@angular/core").Signal<SdApiContractValueMode | null>;
+    protected readonly modeOptions: import("@angular/core").Signal<SdApiContractOption[]>;
+    protected readonly suggestionOptions: import("@angular/core").Signal<SdApiContractSuggestion[]>;
+    /**
+     * Options for the source dropdown.
+     *
+     * why: một `source` đang lưu có thể trỏ vào trường đã bị xoá hoặc đổi tên — nó KHÔNG còn trong
+     * danh sách gợi ý. `sd-select` không tìm thấy value sẽ hiện ô rỗng, và giá trị vẫn nằm trong
+     * contract mà người dùng không thấy để sửa. Thêm một option dựng từ chính giá trị đó để nó luôn
+     * hiển thị; validation lo phần báo `mapping.reference.missing`.
+     */
+    protected readonly sourceOptions: import("@angular/core").Signal<SdApiContractSuggestion[]>;
+    protected readonly staticText: import("@angular/core").Signal<string>;
+    protected readonly staticNumber: import("@angular/core").Signal<number | null>;
+    protected setMode(mode: unknown): void;
+    protected setSource(value: unknown): void;
+    protected setStaticScalar(value: unknown): void;
+    protected setStaticNumber(value: unknown): void;
+    /**
+     * Stores a `date` / `datetime` literal.
+     *
+     * why: `<sd-date>` / `<sd-datetime>` có thể bắn ra một `Date`. `String(new Date())` ra
+     * `Mon Aug 17 2026 …` — không parse lại được và đổi theo locale của máy tác giả, nên contract sẽ
+     * mang một giá trị không portable. Chuẩn hoá về ISO.
+     */
+    protected setStaticTemporal(value: unknown): void;
+    /**
+     * Stores an `object` / `array` literal from the JSON editor.
+     *
+     * why: `<sd-code-editor language="json">` bắn ra STRING khi cú pháp còn dở (`{"a":`). Ghi chuỗi đó
+     * vào contract sẽ biến một literal object thành rác, nên bỏ qua và giữ giá trị hợp lệ cuối cùng —
+     * người dùng vẫn thấy nguyên văn mình đang gõ trong editor.
+     */
+    protected setStaticJson(value: unknown): void;
+    protected setStaticBoolean(value: unknown): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractSourceEditor, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractSourceEditor, "sd-api-contract-source-editor", never, { "node": { "alias": "node"; "required": true; "isSignal": true; }; "suggestions": { "alias": "suggestions"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "nodeChange": "nodeChange"; }, never, never, true, never>;
+}
+export {};

package/components/api-contract-builder/src/components/api-contract-suggestion.model.d.ts

@@ -0,0 +1,17 @@
+import type { SdApiContractDataType, SdApiContractExpressionRoot } from '../api-contract.model';
+/**
+ * One `${…}` reference the source editor can offer.
+ *
+ * Internal to the builder UI — it is derived from the contract and the injected env catalog on every
+ * edit, so it is never persisted and never part of the public surface.
+ */
+export interface SdApiContractSuggestion {
+    /** Ready-to-insert text, e.g. `${input.customer.id}`. */
+    expression: string;
+    /** Dotted path without the delimiters, e.g. `input.customer.id`. */
+    path: string;
+    root: SdApiContractExpressionRoot;
+    type: SdApiContractDataType;
+    /** What the picker shows. Never contains a value — a sensitive variable only shows its name. */
+    display: string;
+}

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

@@ -23,6 +23,7 @@ export declare class SdBadge {
     onClick: (event: Event) => void;
     onActivateKey: (event: Event) => void;
     effectiveColor: import("@angular/core").Signal<Color>;
+    accessibleName: import("@angular/core").Signal<string>;
     baseColorClasses: import("@angular/core").Signal<{
         'c-primary': boolean;
         'c-secondary': boolean;

package/components/index.d.ts

@@ -13,6 +13,7 @@ export * from '@sdcorejs/angular/components/section';
 export * from '@sdcorejs/angular/components/inform';
 export * from '@sdcorejs/angular/components/form-generic';
 export * from '@sdcorejs/angular/components/anchor';
+export * from '@sdcorejs/angular/components/api-contract-builder';
 export * from '@sdcorejs/angular/components/query-builder';
 export * from '@sdcorejs/angular/components/org-chart';
 export * from '@sdcorejs/angular/components/tree';

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

@@ -13,6 +13,8 @@ export declare class SdSection {
     readonly bodyId: string;
     constructor();
     toggleCollapse: () => void;
+    protected onHeaderClick: (event: MouseEvent) => void;
+    protected onCollapseButtonClick: (event: MouseEvent) => void;
     onHeaderKeydown: (event: KeyboardEvent) => void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdSection, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<SdSection, "sd-section", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "subTitle": { "alias": "subTitle"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "iconColor": { "alias": "iconColor"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "hideHeader": { "alias": "hideHeader"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; }, never, ["[sdHeaderLeft]", "[sdHeaderRight]", "*", "[sdFooterLeft]", "[sdFooterRight]"], true, never>;