@sdcorejs/angular 20.2.0 → 20.2.1

package/components/api-contract-builder/index.d.ts

@@ -0,0 +1,694 @@
+import { SdTemporalValueTransform } from '@sdcorejs/angular/forms/models';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { SdSideDrawer } from '@sdcorejs/angular/components/side-drawer';
+
+/**
+ * Data-type vocabulary of an API contract.
+ *
+ * Deliberately NOT reusing `SdQueryBuilderFieldType`: that union describes *filterable* fields in a
+ * query UI, this one describes the *shape of transported data*. They drift for different reasons.
+ *
+ * `date` / `datetime` are **logical** types — in the persisted JSON they are transported as strings,
+ * never as a JavaScript `Date`.
+ */
+type SdApiContractDataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'object' | 'array';
+/** Every type that carries a single value (no `properties`, no `items`). */
+type SdApiContractScalarDataType = Exclude<SdApiContractDataType, 'object' | 'array'>;
+/** Types that may appear as a temporal node and therefore accept `transform`. */
+type SdApiContractTemporalDataType = Extract<SdApiContractDataType, 'date' | 'datetime'>;
+declare const SD_API_CONTRACT_DATA_TYPES: readonly SdApiContractDataType[];
+declare const SD_API_CONTRACT_SCALAR_DATA_TYPES: readonly SdApiContractScalarDataType[];
+declare function sdIsApiContractDataType(value: unknown): value is SdApiContractDataType;
+declare function sdIsApiContractScalarDataType(value: unknown): value is SdApiContractScalarDataType;
+declare function sdIsApiContractTemporalDataType(value: unknown): value is SdApiContractTemporalDataType;
+/**
+ * Anything a static literal may be. Mirrors what `JSON.parse` can produce, so a contract always
+ * round-trips through `JSON.stringify` without losing information.
+ */
+type SdApiContractJsonValue = string | number | boolean | null | SdApiContractJsonValue[] | {
+    [key: string]: SdApiContractJsonValue;
+};
+/**
+ * Shared by every node in every layer.
+ *
+ * `required` is a **tri-state** and lives next to `type` (never a `required: string[]` array on the
+ * parent object, the way JSON Schema does it): `undefined` = not declared, `true` = mandatory,
+ * `false` = explicitly optional. The serializer omits `undefined` and keeps `false`.
+ */
+interface SdApiContractNodeBase {
+    required?: boolean;
+    label?: string;
+    description?: string;
+}
+/**
+ * The two mutually exclusive ways a mapped node receives a value.
+ *
+ * - `source` — a template referencing `${input.*}` / `${env.*}` / `${res.*}`.
+ * - `value` — a static JSON literal.
+ *
+ * A node carrying both is invalid (`mapping.source-and-value`).
+ */
+interface SdApiContractMapping {
+    source?: string;
+    value?: SdApiContractJsonValue;
+}
+interface SdApiContractFeScalarNode extends SdApiContractNodeBase {
+    type: SdApiContractScalarDataType;
+    /** Only meaningful on `date` / `datetime`; reused verbatim from the temporal form controls. */
+    transform?: SdTemporalValueTransform;
+}
+interface SdApiContractFeObjectNode extends SdApiContractNodeBase {
+    type: 'object';
+    properties: Record<string, SdApiContractFeSchemaNode>;
+}
+interface SdApiContractFeArrayNode extends SdApiContractNodeBase {
+    type: 'array';
+    items: SdApiContractFeSchemaNode;
+}
+/** A pure declaration — no `source` / `value`, because `input` is what the caller hands in. */
+type SdApiContractFeSchemaNode = SdApiContractFeScalarNode | SdApiContractFeObjectNode | SdApiContractFeArrayNode;
+interface SdApiContractRestScalarNode extends SdApiContractNodeBase {
+    type: SdApiContractScalarDataType;
+}
+interface SdApiContractRestObjectNode extends SdApiContractNodeBase {
+    type: 'object';
+    properties: Record<string, SdApiContractRestNode>;
+}
+interface SdApiContractRestArrayNode extends SdApiContractNodeBase {
+    type: 'array';
+    items: SdApiContractRestNode;
+}
+/** Describes what the backend returns. Never carries a mapping — nothing maps *into* a response. */
+type SdApiContractRestNode = SdApiContractRestScalarNode | SdApiContractRestObjectNode | SdApiContractRestArrayNode;
+interface SdApiContractMappedRestScalarNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: SdApiContractScalarDataType;
+}
+interface SdApiContractMappedRestObjectNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'object';
+    /** Omitted when the whole object is mapped through `source` / `value`. */
+    properties?: Record<string, SdApiContractMappedRestNode>;
+}
+interface SdApiContractMappedRestArrayNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'array';
+    /** Describes the element type. Per-item projection is intentionally out of scope. */
+    items: SdApiContractMappedRestNode;
+}
+type SdApiContractMappedRestNode = SdApiContractMappedRestScalarNode | SdApiContractMappedRestObjectNode | SdApiContractMappedRestArrayNode;
+interface SdApiContractMappedFeScalarNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: SdApiContractScalarDataType;
+    transform?: SdTemporalValueTransform;
+}
+interface SdApiContractMappedFeObjectNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'object';
+    properties?: Record<string, SdApiContractMappedFeSchemaNode>;
+}
+interface SdApiContractMappedFeArrayNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'array';
+    items: SdApiContractMappedFeSchemaNode;
+}
+type SdApiContractMappedFeSchemaNode = SdApiContractMappedFeScalarNode | SdApiContractMappedFeObjectNode | SdApiContractMappedFeArrayNode;
+/** Structural union of every node shape, for utilities that traverse any layer. */
+type SdApiContractAnyNode = SdApiContractFeSchemaNode | SdApiContractRestNode | SdApiContractMappedRestNode | SdApiContractMappedFeSchemaNode;
+type SdApiContractHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+declare const SD_API_CONTRACT_HTTP_METHODS: readonly SdApiContractHttpMethod[];
+declare function sdIsApiContractHttpMethod(value: unknown): value is SdApiContractHttpMethod;
+/**
+ * The real HTTP request. No `.schema` wrapper on purpose — `req` *is* REST, so it exposes REST
+ * structure directly, while `input` / `output` are frontend contracts and keep their `.schema`.
+ */
+interface SdApiContractRequest {
+    method: SdApiContractHttpMethod;
+    /** May interpolate `${env.*}` and carry REST placeholders such as `{id}`. */
+    url: string;
+    path?: Record<string, SdApiContractMappedRestNode>;
+    query?: Record<string, SdApiContractMappedRestNode>;
+    headers?: Record<string, SdApiContractMappedRestNode>;
+    body?: SdApiContractMappedRestNode;
+}
+interface SdApiContractResponse {
+    /** One success status, or several. Each must be an integer in `100..599`. */
+    status: number | number[];
+    headers?: Record<string, SdApiContractRestNode>;
+    body?: SdApiContractRestNode;
+}
+/** The only `contractVersion` this release understands. */
+declare const SD_API_CONTRACT_VERSION = 1;
+interface SdApiContract {
+    contractVersion: 1;
+    code: string;
+    name: string;
+    description?: string;
+    input: {
+        schema: SdApiContractFeSchemaNode;
+    };
+    req: SdApiContractRequest;
+    res: SdApiContractResponse;
+    output: {
+        schema: SdApiContractMappedFeSchemaNode;
+    };
+}
+type SdApiContractDiagnosticSeverity = 'error' | 'warning';
+interface SdApiContractDiagnostic {
+    /** Stable machine-readable identifier, e.g. `mapping.env.unknown`. Safe to switch on. */
+    code: string;
+    severity: SdApiContractDiagnosticSeverity;
+    /** Structural path into the contract, e.g. `req.body.properties.x`. Never localized. */
+    path: string;
+    /** Human-readable, English. The UI localizes by `code` when it wants a translated string. */
+    message: string;
+}
+/** Roots an expression may address. `output` is never a root — nothing reads from the output. */
+type SdApiContractExpressionRoot = 'input' | 'env' | 'res';
+declare const SD_API_CONTRACT_EXPRESSION_ROOTS: readonly SdApiContractExpressionRoot[];
+/**
+ * Where a mapping lives, which decides the roots it may read.
+ *
+ * - `request` (`req.url` / `path` / `query` / `headers` / `body`) → `input`, `env`.
+ * - `output` (`output.schema`) → `res`, `input`, `env`.
+ */
+type SdApiContractMappingContext = 'request' | 'output';
+declare const SD_API_CONTRACT_ALLOWED_ROOTS: Readonly<Record<SdApiContractMappingContext, readonly SdApiContractExpressionRoot[]>>;
+
+/**
+ * Declaration of one global variable a contract may reference as `${env.<key>}`.
+ *
+ * Definition only — **never a value**. The builder is a design-time tool: it must be able to
+ * autocomplete and validate `${env.token}` without the token itself ever entering the app, the
+ * component, or the persisted JSON.
+ */
+interface SdApiContractEnvironmentVariable {
+    /** Composite env variables are not supported — a global is always a single scalar. */
+    type: SdApiContractScalarDataType;
+    label?: string;
+    description?: string;
+    /**
+     * Marks a secret (token, api key). The UI badges it and never previews a value — there is no
+     * value to preview, so this is purely an authoring signal.
+     */
+    sensitive?: boolean;
+}
+interface SdApiContractConfiguration {
+    env: Record<string, SdApiContractEnvironmentVariable>;
+}
+/** What the builder falls back to when the host application provides no configuration. */
+declare const SD_API_CONTRACT_EMPTY_CONFIGURATION: SdApiContractConfiguration;
+declare const SD_API_CONTRACT_CONFIGURATION: InjectionToken<SdApiContractConfiguration>;
+/**
+ * Registers the env catalog available to every `<sd-api-contract-builder>` in the injector.
+ *
+ * ```ts
+ * provideSdApiContract({
+ *   env: {
+ *     baseUrl: { type: 'string', label: 'Backend base URL' },
+ *     token: { type: 'string', label: 'Access token', sensitive: true },
+ *   },
+ * });
+ * ```
+ */
+declare function provideSdApiContract(configuration: SdApiContractConfiguration): EnvironmentProviders;
+/** Normalizes an optionally-injected configuration into one that is always safe to read. */
+declare function resolveSdApiContractConfiguration(configuration: SdApiContractConfiguration | null | undefined): SdApiContractConfiguration;
+
+/**
+ * How a `source` string relates to the expression grammar.
+ *
+ * - `literal` — no `${…}` at all.
+ * - `exact` — the whole string is one expression, so the referenced value keeps its own type.
+ * - `interpolated` — expressions embedded in surrounding text, so the result is always a string.
+ */
+type SdApiContractTemplateKind = 'literal' | 'exact' | 'interpolated';
+type SdApiContractTemplateErrorCode = 'template.unterminated' | 'template.nested' | 'template.empty' | 'template.invalid-path' | 'template.unknown-root' | 'template.forbidden-segment';
+interface SdApiContractTemplateError {
+    code: SdApiContractTemplateErrorCode;
+    message: string;
+    /** Offset of the `${` that opened the offending expression. */
+    index: number;
+    raw: string;
+}
+interface SdApiContractExpressionReference {
+    root: SdApiContractExpressionRoot;
+    /** Segments *after* the root. `${input.customer.id}` → `['customer', 'id']`. */
+    path: readonly string[];
+    /** The inner text, e.g. `input.customer.id`. */
+    expression: string;
+    /** The full match including delimiters, e.g. `${input.customer.id}`. */
+    raw: string;
+    start: number;
+    end: number;
+}
+interface SdApiContractTemplate {
+    kind: SdApiContractTemplateKind;
+    valid: boolean;
+    references: readonly SdApiContractExpressionReference[];
+    errors: readonly SdApiContractTemplateError[];
+}
+/**
+ * Parses a `source` / URL template into references and errors.
+ *
+ * Pure string scanning — no `eval`, no `new Function`, no expression evaluation of any kind. The
+ * grammar accepts exactly `${<root>.<identifier>(.<identifier>)*}` and nothing else.
+ */
+declare function parseSdApiContractTemplate(source: unknown): SdApiContractTemplate;
+/** The well-formed references of a template. Malformed expressions are dropped, not thrown. */
+declare function extractSdApiContractReferences(source: unknown): readonly SdApiContractExpressionReference[];
+
+/**
+ * Structural view of a node from any layer (`input.schema`, `req.*`, `res.*`, `output.schema`).
+ *
+ * The traversal utilities are deliberately layer-agnostic: the four public node unions differ only
+ * in which members they *allow*, and every one of them is structurally assignable to this shape.
+ * Whether a member is legal where it appears is the validator's job, not the traversal's.
+ */
+interface SdApiContractStructuralNode {
+    type: SdApiContractDataType;
+    required?: boolean;
+    label?: string;
+    description?: string;
+    transform?: SdTemporalValueTransform;
+    source?: string;
+    value?: SdApiContractJsonValue;
+    properties?: Record<string, SdApiContractStructuralNode>;
+    items?: SdApiContractStructuralNode;
+}
+/** A node narrowed to the object shape, so `properties` is safe to read. */
+interface SdApiContractObjectShape extends SdApiContractStructuralNode {
+    type: 'object';
+    properties: Record<string, SdApiContractStructuralNode>;
+}
+/**
+ * Structural pointer into a node tree: alternating `'properties', <key>` and `'items'` segments.
+ * The same shape the diagnostics use, so a diagnostic path can drive navigation in the UI.
+ */
+type SdApiContractNodePointer = readonly string[];
+/**
+ * One addressable field discovered by traversal.
+ *
+ * **Path convention:** dot-joined property names. Array items are *flattened under the array's own
+ * path* (`items.id`, and for a root array simply `id`), which is what a dropdown / table consumer
+ * wants. Set `arrays: 'stop'` to instead get exactly the set of paths an `${…}` expression can
+ * address — expressions never index into an array.
+ */
+interface SdApiContractSchemaField {
+    path: string;
+    segments: readonly string[];
+    type: SdApiContractDataType;
+    required?: boolean;
+    label?: string;
+    description?: string;
+    /** `true` when traversal did not descend any further from this field. */
+    leaf: boolean;
+    /** `true` when the field was reached by descending through an array's `items`. */
+    arrayItem: boolean;
+}
+interface SdApiContractFieldListOptions {
+    /** `'flatten'` (default) descends into array items; `'stop'` treats an array as a leaf. */
+    arrays?: 'flatten' | 'stop';
+    /** Dotted prefix prepended to every emitted path, e.g. `'body'`. */
+    basePath?: string;
+}
+interface SdApiContractResolvedReference {
+    type: SdApiContractDataType;
+    required?: boolean;
+    label?: string;
+    description?: string;
+    /** `null` for synthetic references such as `res.status`, which have no declared node. */
+    node: SdApiContractStructuralNode | null;
+}
+interface SdApiContractUrlPlaceholders {
+    /** Unique placeholder names, in first-appearance order. */
+    names: readonly string[];
+    duplicates: readonly string[];
+    /** Raw fragments that look like a placeholder but are not one, e.g. `{}` or `{first name}`. */
+    malformed: readonly string[];
+}
+/** Flattens a node tree into addressable fields. See `SdApiContractSchemaField` for the convention. */
+declare function listSdApiContractSchemaFields(node: SdApiContractStructuralNode, options?: SdApiContractFieldListOptions): readonly SdApiContractSchemaField[];
+/** Every `${res.…}` path the output layer may address, in a stable order. */
+declare function listSdApiContractResponseFields(response: SdApiContractResponse): readonly SdApiContractSchemaField[];
+/**
+ * Resolves a *logical* reference path (`customer.id`) against a schema.
+ *
+ * Arrays are terminal: `${res.body.items}` addresses the whole array, `${res.body.items.id}` does
+ * not exist because there is no element to address. Per-item projection is out of scope.
+ */
+declare function resolveSdApiContractSchemaPath(root: SdApiContractStructuralNode, path: readonly string[]): SdApiContractStructuralNode | null;
+/** Resolves `status` / `headers.<name>` / `body.<path>` against a response declaration. */
+declare function resolveSdApiContractResponsePath(response: SdApiContractResponse, path: readonly string[]): SdApiContractResolvedReference | null;
+/** Reads the node a structural pointer addresses, or `null` when the pointer does not resolve. */
+declare function getSdApiContractNodeAt(root: SdApiContractStructuralNode, pointer: SdApiContractNodePointer): SdApiContractStructuralNode | null;
+/** Replaces the node a pointer addresses, rebuilding only the spine. Never mutates `root`. */
+declare function setSdApiContractNodeAt<T extends SdApiContractStructuralNode>(root: T, pointer: SdApiContractNodePointer, node: SdApiContractStructuralNode): T;
+/** Appends a property. A key that already exists is left untouched — the caller must dedupe first. */
+declare function addSdApiContractProperty(node: SdApiContractStructuralNode, key: string, child: SdApiContractStructuralNode): SdApiContractObjectShape;
+/** Renames a property **in place in the key order**, so the JSON diff stays readable. */
+declare function renameSdApiContractProperty(node: SdApiContractStructuralNode, from: string, to: string): SdApiContractObjectShape;
+declare function removeSdApiContractProperty(node: SdApiContractStructuralNode, key: string): SdApiContractObjectShape;
+/** A minimal well-formed node of the given type. */
+declare function createSdApiContractNode(type: SdApiContractDataType): SdApiContractStructuralNode;
+/**
+ * Retypes a node, dropping the members the new type cannot carry.
+ *
+ * Returns the same reference when the type is unchanged, so an idempotent UI write never produces a
+ * spurious `modelChange`.
+ */
+declare function changeSdApiContractNodeType(node: SdApiContractStructuralNode, type: SdApiContractDataType): SdApiContractStructuralNode;
+/** Deep copy of a node subtree. Used when a response subtree is adopted as the output schema. */
+declare function cloneSdApiContractNode<T extends SdApiContractStructuralNode>(node: T): T;
+/**
+ * Deep copy of a whole contract.
+ *
+ * The builder clones on the way in so the object a parent owns is never reachable from an edit, and
+ * a consumer can do the same before handing a contract to anything that might mutate it.
+ */
+declare function cloneSdApiContract<T>(contract: T): T;
+declare function sdApiContractRecordSet<T>(record: Record<string, T> | undefined, key: string, value: T): Record<string, T>;
+declare function sdApiContractRecordRemove<T>(record: Record<string, T>, key: string): Record<string, T>;
+/** Renames a key in place. A collision or an empty target is a no-op — the caller reports it. */
+declare function sdApiContractRecordRename<T>(record: Record<string, T>, from: string, to: string): Record<string, T>;
+/** Builds the canonical expression text — the inverse of `parseSdApiContractTemplate`. */
+declare function formatSdApiContractExpression(root: SdApiContractExpressionRoot, path: readonly string[]): string;
+/** Joins a diagnostic base path with a structural pointer, e.g. `req.body` + `properties.x`. */
+declare function formatSdApiContractPointer(base: string, pointer: SdApiContractNodePointer): string;
+/**
+ * Reads REST placeholders out of a URL template.
+ *
+ * `${…}` interpolation is masked out first, so `${env.baseUrl}` is never mistaken for a `{…}`
+ * path placeholder.
+ */
+declare function parseSdApiContractUrlPlaceholders(url: string): SdApiContractUrlPlaceholders;
+
+/**
+ * Deterministic JSON for an API contract.
+ *
+ * Three guarantees the persisted file depends on:
+ *
+ * 1. **System keys are ordered**, so two authors editing the same contract produce the same bytes
+ *    and a `git diff` shows the semantic change instead of a reshuffle.
+ * 2. **User-declared keys keep their order** (`properties`, `query`, `headers`, …) — that order is
+ *    authored information, and sorting it would churn every diff.
+ * 3. **Only contract vocabulary survives.** The builder's transient UI state (expansion, selection,
+ *    internal ids) is dropped by construction: the serializer copies a fixed key whitelist rather
+ *    than the object it was handed, so a new piece of UI state can never leak into the file.
+ *
+ * `undefined` members are omitted; declared `false`, `0`, `null` and `""` are kept.
+ */
+declare function serializeSdApiContract(contract: SdApiContract | null | undefined): string;
+
+/**
+ * Validates a contract against the grammar, the schema rules, the REST rules and the injected env
+ * catalog.
+ *
+ * Pure and UI-free: it takes `unknown` because an externally supplied contract may be malformed,
+ * and it **never repairs anything** — a silent fix would hide the very mistake the author needs to
+ * see. Diagnostics come back in a fixed traversal order (metadata → `input` → `req` → `res` →
+ * `output`, declaration order within each), so the same contract always yields the same list.
+ */
+declare function validateSdApiContract(contract: unknown, configuration?: SdApiContractConfiguration): SdApiContractDiagnostic[];
+
+/**
+ * Reference contracts, shared by the docs, the showcase and the test-suite so the canonical example
+ * can never drift between them.
+ *
+ * Each is a **factory**, not a constant: the builder takes a two-way `[(model)]`, and handing two
+ * demos the same object would let one seed the other.
+ */
+/** The env catalog the samples reference. Definitions only — no secret ever has a value here. */
+declare const SD_API_CONTRACT_SAMPLE_ENVIRONMENT: SdApiContractConfiguration;
+/** `GET` list endpoint whose output is a root array — the dropdown / table shape. */
+declare function sdApiContractSearchSample(): SdApiContract;
+/**
+ * `POST` endpoint showing every mapping flavour at once:
+ * `input.a → req.body.x`, `input.b → req.body.y`, `input.c → req.body.z`,
+ * `env.userId → req.body.u`, and a static literal in `req.body.v`.
+ */
+declare function sdApiContractCreateSample(): SdApiContract;
+/**
+ * Deliberately broken contract used to demonstrate the diagnostics: an undeclared env variable, a
+ * `{id}` placeholder with no `req.path` entry, a `${input.page}` that does not exist, and an output
+ * source pointing at a scalar while the output declares an array.
+ */
+declare function sdApiContractInvalidSample(): SdApiContract;
+
+/**
+ * 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.
+ */
+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;
+}
+
+/** What the drawer hands back when the author closes the books on one node. */
+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.
+ */
+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$1 {
+    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.
+ */
+declare class SdApiContractNodeDrawer {
+    #private;
+    /** `mapping` shows the value editor; `schema` is a plain declaration with no mapping. */
+    layer: _angular_core.InputSignal<"schema" | "mapping">;
+    allowTransform: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    suggestions: _angular_core.InputSignal<readonly SdApiContractSuggestion[]>;
+    autoId: _angular_core.InputSignal<string | null | undefined>;
+    nodeCommit: _angular_core.OutputEmitterRef<SdApiContractNodeCommit>;
+    protected readonly drawerRef: _angular_core.Signal<SdSideDrawer>;
+    protected readonly draftName: _angular_core.Signal<string>;
+    protected readonly discardPrompt: _angular_core.Signal<boolean>;
+    /** The node the author is looking at right now — the draft root, or a descendant of it. */
+    protected readonly current: _angular_core.Signal<SdApiContractStructuralNode | null>;
+    /** Every key on the breadcrumb. The pointer alternates `properties`/key, so keys sit on odd slots. */
+    protected readonly breadcrumb: _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: _angular_core.Signal<string>;
+    protected readonly children: _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: _angular_core.Signal<readonly string[]>;
+    protected readonly typeOptions: SdApiContractOption$1[];
+    protected readonly requiredOptions: SdApiContractOption$1[];
+    protected readonly transformOptions: SdApiContractOption$1[];
+    protected readonly title: _angular_core.Signal<string>;
+    protected readonly dirty: _angular_core.Signal<boolean>;
+    protected readonly nameError: _angular_core.Signal<string | null>;
+    protected readonly canSave: _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: _angular_core.ɵɵFactoryDeclaration<SdApiContractNodeDrawer, never>;
+    static ɵcmp: _angular_core.ɵɵ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>;
+}
+
+interface SdApiContractOption {
+    value: string;
+    label: string;
+}
+interface SdApiContractStep {
+    index: number;
+    key: string;
+    label: string;
+}
+type SdApiContractNodeRecord = Record<string, SdApiContractStructuralNode>;
+/** Every place a node can live. The builder needs it to route a commit back to its owner. */
+type SdApiContractDrawerSection = 'input.schema' | 'req.path' | 'req.query' | 'req.headers' | 'req.body' | 'res.headers' | 'res.body' | 'output.schema';
+/**
+ * Visual builder for an `SdApiContract`.
+ *
+ * The component is a **design-time** tool: it never performs a request, never resolves an
+ * expression and never holds a secret. It edits, validates and serializes the contract; executing
+ * it is a separate concern for a future `form-builder` / `form-render` integration.
+ *
+ * @example
+ * ```html
+ * <sd-api-contract-builder [(model)]="contract" autoId="product-search"></sd-api-contract-builder>
+ * ```
+ */
+declare class SdApiContractBuilder {
+    #private;
+    model: _angular_core.ModelSignal<SdApiContract | null>;
+    mode: _angular_core.InputSignal<"edit" | "view">;
+    disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    autoId: _angular_core.InputSignal<string | null | undefined>;
+    /** Fires whenever the diagnostics change, including once for the initially seeded contract. */
+    diagnosticsChange: _angular_core.OutputEmitterRef<readonly SdApiContractDiagnostic[]>;
+    /** Fires only when validity flips, so a consumer can gate a Save button without debouncing. */
+    validChange: _angular_core.OutputEmitterRef<boolean>;
+    protected readonly activeStep: _angular_core.WritableSignal<number>;
+    protected readonly contractVersion = 1;
+    protected readonly responseFieldToken: _angular_core.WritableSignal<string | null>;
+    protected readonly urlPlaceholder = "${env.baseUrl}/products/{id}";
+    protected readonly draft: _angular_core.Signal<SdApiContract | null>;
+    protected readonly readonly: _angular_core.Signal<boolean>;
+    protected readonly isView: _angular_core.Signal<boolean>;
+    protected readonly steps: SdApiContractStep[];
+    protected readonly methodOptions: SdApiContractOption[];
+    protected readonly allTypes: readonly SdApiContractDataType[];
+    protected readonly scalarTypes: readonly SdApiContractDataType[];
+    protected readonly queryTypes: readonly SdApiContractDataType[];
+    protected readonly nodeDrawer: _angular_core.Signal<SdApiContractNodeDrawer | undefined>;
+    protected readonly drawerLayer: _angular_core.Signal<"schema" | "mapping">;
+    protected readonly drawerAllowsTransform: _angular_core.Signal<boolean>;
+    protected readonly drawerSuggestions: _angular_core.Signal<readonly SdApiContractSuggestion[]>;
+    protected readonly diagnostics: _angular_core.Signal<readonly SdApiContractDiagnostic[]>;
+    protected readonly json: _angular_core.Signal<string>;
+    protected readonly requestSuggestions: _angular_core.Signal<SdApiContractSuggestion[]>;
+    protected readonly outputSuggestions: _angular_core.Signal<SdApiContractSuggestion[]>;
+    /** Response paths offered by the "use a response field as the output" action. */
+    protected readonly responseFieldOptions: _angular_core.Signal<SdApiContractOption[]>;
+    /** Leaf fields a dropdown / table consumer will see once this contract runs. */
+    protected readonly outputFields: _angular_core.Signal<SdApiContractSchemaField[]>;
+    protected readonly statusText: _angular_core.Signal<string>;
+    get autoIdAttr(): string | null;
+    constructor();
+    protected goToStep(index: number): void;
+    protected goToDiagnostic(diagnostic: SdApiContractDiagnostic): void;
+    protected createContract(): void;
+    protected setText(key: 'code' | 'name' | 'description', value: unknown): void;
+    protected setInputSchema(node: SdApiContractStructuralNode): void;
+    protected setMethod(value: unknown): void;
+    protected setUrl(value: unknown): void;
+    /**
+     * Opens the one drawer for whichever list asked.
+     *
+     * why gác `readonly` ở đây nữa: hàng thu gọn đã tự chặn khi read-only, nhưng builder là nơi duy nhất
+     * biết `mode`/`disabled` thật. Hai lớp gác rẻ hơn một đường mở drawer lọt trong chế độ xem.
+     */
+    protected openNodeDrawer(section: SdApiContractDrawerSection, request: SdApiContractNodeEditRequest): void;
+    /**
+     * Writes a committed node back where it came from — one `modelChange`, at Save time.
+     *
+     * A rename goes through `sdApiContractRecordRename` first so the entry keeps its position in the
+     * JSON instead of jumping to the end. The drawer has already refused a duplicate name, so the
+     * rename cannot collide by the time it reaches here.
+     */
+    protected applyNodeCommit(commit: SdApiContractNodeCommit): void;
+    protected setRequestRecord(section: 'path' | 'query' | 'headers', record: SdApiContractNodeRecord): void;
+    protected setRequestBody(node: SdApiContractStructuralNode): void;
+    protected addRequestBody(): void;
+    protected removeRequestBody(): void;
+    protected setStatus(value: unknown): void;
+    protected setResponseHeaders(record: SdApiContractNodeRecord): void;
+    protected setResponseBody(node: SdApiContractStructuralNode): void;
+    protected addResponseBody(): void;
+    protected removeResponseBody(): void;
+    protected setOutputSchema(node: SdApiContractStructuralNode): void;
+    /**
+     * Adopts a response subtree as the output schema.
+     *
+     * The subtree is **deep-copied**, never referenced: editing the output afterwards must not reach
+     * back into the response declaration. An array or scalar target takes a whole-node `source`; an
+     * object target keeps its shape and each branch gets its own `source`, because an object with both
+     * a whole-node source and child mappings is invalid by design.
+     */
+    protected useResponseFieldAsOutput(value: unknown): void;
+    /**
+     * Adopts a contract pasted into the review editor.
+     *
+     * `<sd-code-editor language="json">` emits the PARSED value when the text is valid JSON and the
+     * raw STRING while it is still half-typed. A string therefore means "not parseable yet": keep the
+     * current draft and report it, because replacing a contract with a fragment of text would destroy
+     * the author's work on a keystroke.
+     *
+     * A parseable object is adopted VERBATIM — no field is added, removed or repaired. Whatever is
+     * wrong with it surfaces through `validateSdApiContract`, which is the whole point of pasting.
+     */
+    protected applyPastedJson(value: unknown): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SdApiContractBuilder, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SdApiContractBuilder, "sd-api-contract-builder", never, { "model": { "alias": "model"; "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; }; }, { "model": "modelChange"; "diagnosticsChange": "diagnosticsChange"; "validChange": "validChange"; }, never, never, true, never>;
+}
+
+export { SD_API_CONTRACT_ALLOWED_ROOTS, SD_API_CONTRACT_CONFIGURATION, SD_API_CONTRACT_DATA_TYPES, SD_API_CONTRACT_EMPTY_CONFIGURATION, SD_API_CONTRACT_EXPRESSION_ROOTS, SD_API_CONTRACT_HTTP_METHODS, SD_API_CONTRACT_SAMPLE_ENVIRONMENT, SD_API_CONTRACT_SCALAR_DATA_TYPES, SD_API_CONTRACT_VERSION, SdApiContractBuilder, addSdApiContractProperty, changeSdApiContractNodeType, cloneSdApiContract, cloneSdApiContractNode, createSdApiContractNode, extractSdApiContractReferences, formatSdApiContractExpression, formatSdApiContractPointer, getSdApiContractNodeAt, listSdApiContractResponseFields, listSdApiContractSchemaFields, parseSdApiContractTemplate, parseSdApiContractUrlPlaceholders, provideSdApiContract, removeSdApiContractProperty, renameSdApiContractProperty, resolveSdApiContractConfiguration, resolveSdApiContractResponsePath, resolveSdApiContractSchemaPath, sdApiContractCreateSample, sdApiContractInvalidSample, sdApiContractRecordRemove, sdApiContractRecordRename, sdApiContractRecordSet, sdApiContractSearchSample, sdIsApiContractDataType, sdIsApiContractHttpMethod, sdIsApiContractScalarDataType, sdIsApiContractTemporalDataType, serializeSdApiContract, setSdApiContractNodeAt, validateSdApiContract };
+export type { SdApiContract, SdApiContractAnyNode, SdApiContractConfiguration, SdApiContractDataType, SdApiContractDiagnostic, SdApiContractDiagnosticSeverity, SdApiContractEnvironmentVariable, SdApiContractExpressionReference, SdApiContractExpressionRoot, SdApiContractFeArrayNode, SdApiContractFeObjectNode, SdApiContractFeScalarNode, SdApiContractFeSchemaNode, SdApiContractFieldListOptions, SdApiContractHttpMethod, SdApiContractJsonValue, SdApiContractMappedFeArrayNode, SdApiContractMappedFeObjectNode, SdApiContractMappedFeScalarNode, SdApiContractMappedFeSchemaNode, SdApiContractMappedRestArrayNode, SdApiContractMappedRestNode, SdApiContractMappedRestObjectNode, SdApiContractMappedRestScalarNode, SdApiContractMapping, SdApiContractMappingContext, SdApiContractNodeBase, SdApiContractNodePointer, SdApiContractObjectShape, SdApiContractRequest, SdApiContractResolvedReference, SdApiContractResponse, SdApiContractRestArrayNode, SdApiContractRestNode, SdApiContractRestObjectNode, SdApiContractRestScalarNode, SdApiContractScalarDataType, SdApiContractSchemaField, SdApiContractStructuralNode, SdApiContractTemplate, SdApiContractTemplateError, SdApiContractTemplateErrorCode, SdApiContractTemplateKind, SdApiContractTemporalDataType, SdApiContractUrlPlaceholders };