@sdcorejs/angular 19.2.0 → 19.2.1

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

@@ -0,0 +1,8 @@
+export * from './src/api-contract.model';
+export * from './src/api-contract.configuration';
+export * from './src/api-contract.expression';
+export * from './src/api-contract.schema';
+export * from './src/api-contract.serializer';
+export * from './src/api-contract.validation';
+export * from './src/api-contract.samples';
+export * from './src/api-contract-builder.component';

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

@@ -0,0 +1,123 @@
+import { type SdApiContract, type SdApiContractDataType, type SdApiContractDiagnostic } from './api-contract.model';
+import { type SdApiContractSchemaField, type SdApiContractStructuralNode } from './api-contract.schema';
+import { SdApiContractNodeDrawer, type SdApiContractNodeCommit, type SdApiContractNodeEditRequest } from './components/api-contract-node-drawer.component';
+import type { SdApiContractSuggestion } from './components/api-contract-suggestion.model';
+import * as i0 from "@angular/core";
+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>
+ * ```
+ */
+export declare class SdApiContractBuilder {
+    #private;
+    model: import("@angular/core").ModelSignal<SdApiContract | null>;
+    mode: import("@angular/core").InputSignal<"edit" | "view">;
+    disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    /** Fires whenever the diagnostics change, including once for the initially seeded contract. */
+    diagnosticsChange: import("@angular/core").OutputEmitterRef<readonly SdApiContractDiagnostic[]>;
+    /** Fires only when validity flips, so a consumer can gate a Save button without debouncing. */
+    validChange: import("@angular/core").OutputEmitterRef<boolean>;
+    protected readonly activeStep: import("@angular/core").WritableSignal<number>;
+    protected readonly contractVersion = 1;
+    protected readonly responseFieldToken: import("@angular/core").WritableSignal<string | null>;
+    protected readonly urlPlaceholder = "${env.baseUrl}/products/{id}";
+    protected readonly draft: import("@angular/core").Signal<SdApiContract | null>;
+    protected readonly readonly: import("@angular/core").Signal<boolean>;
+    protected readonly isView: import("@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: import("@angular/core").Signal<SdApiContractNodeDrawer | undefined>;
+    protected readonly drawerLayer: import("@angular/core").Signal<"schema" | "mapping">;
+    protected readonly drawerAllowsTransform: import("@angular/core").Signal<boolean>;
+    protected readonly drawerSuggestions: import("@angular/core").Signal<readonly SdApiContractSuggestion[]>;
+    protected readonly diagnostics: import("@angular/core").Signal<readonly SdApiContractDiagnostic[]>;
+    protected readonly json: import("@angular/core").Signal<string>;
+    protected readonly requestSuggestions: import("@angular/core").Signal<SdApiContractSuggestion[]>;
+    protected readonly outputSuggestions: import("@angular/core").Signal<SdApiContractSuggestion[]>;
+    /** Response paths offered by the "use a response field as the output" action. */
+    protected readonly responseFieldOptions: import("@angular/core").Signal<SdApiContractOption[]>;
+    /** Leaf fields a dropdown / table consumer will see once this contract runs. */
+    protected readonly outputFields: import("@angular/core").Signal<SdApiContractSchemaField[]>;
+    protected readonly statusText: import("@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: i0.ɵɵFactoryDeclaration<SdApiContractBuilder, never>;
+    static ɵcmp: i0.ɵɵ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 {};

package/components/api-contract-builder/src/api-contract.configuration.d.ts

@@ -0,0 +1,41 @@
+import { InjectionToken, type EnvironmentProviders } from '@angular/core';
+import type { SdApiContractScalarDataType } from './api-contract.model';
+/**
+ * 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.
+ */
+export 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;
+}
+export interface SdApiContractConfiguration {
+    env: Record<string, SdApiContractEnvironmentVariable>;
+}
+/** What the builder falls back to when the host application provides no configuration. */
+export declare const SD_API_CONTRACT_EMPTY_CONFIGURATION: SdApiContractConfiguration;
+export 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 },
+ *   },
+ * });
+ * ```
+ */
+export declare function provideSdApiContract(configuration: SdApiContractConfiguration): EnvironmentProviders;
+/** Normalizes an optionally-injected configuration into one that is always safe to read. */
+export declare function resolveSdApiContractConfiguration(configuration: SdApiContractConfiguration | null | undefined): SdApiContractConfiguration;

package/components/api-contract-builder/src/api-contract.expression.d.ts

@@ -0,0 +1,43 @@
+import { type SdApiContractExpressionRoot } from './api-contract.model';
+/**
+ * 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.
+ */
+export type SdApiContractTemplateKind = 'literal' | 'exact' | 'interpolated';
+export type SdApiContractTemplateErrorCode = 'template.unterminated' | 'template.nested' | 'template.empty' | 'template.invalid-path' | 'template.unknown-root' | 'template.forbidden-segment';
+export interface SdApiContractTemplateError {
+    code: SdApiContractTemplateErrorCode;
+    message: string;
+    /** Offset of the `${` that opened the offending expression. */
+    index: number;
+    raw: string;
+}
+export 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;
+}
+export 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.
+ */
+export declare function parseSdApiContractTemplate(source: unknown): SdApiContractTemplate;
+/** The well-formed references of a template. Malformed expressions are dropped, not thrown. */
+export declare function extractSdApiContractReferences(source: unknown): readonly SdApiContractExpressionReference[];

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

@@ -0,0 +1,167 @@
+import type { SdTemporalValueTransform } from '@sdcorejs/angular/forms/models';
+/**
+ * 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`.
+ */
+export type SdApiContractDataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'object' | 'array';
+/** Every type that carries a single value (no `properties`, no `items`). */
+export type SdApiContractScalarDataType = Exclude<SdApiContractDataType, 'object' | 'array'>;
+/** Types that may appear as a temporal node and therefore accept `transform`. */
+export type SdApiContractTemporalDataType = Extract<SdApiContractDataType, 'date' | 'datetime'>;
+export declare const SD_API_CONTRACT_DATA_TYPES: readonly SdApiContractDataType[];
+export declare const SD_API_CONTRACT_SCALAR_DATA_TYPES: readonly SdApiContractScalarDataType[];
+export declare function sdIsApiContractDataType(value: unknown): value is SdApiContractDataType;
+export declare function sdIsApiContractScalarDataType(value: unknown): value is SdApiContractScalarDataType;
+export 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.
+ */
+export 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`.
+ */
+export 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`).
+ */
+export interface SdApiContractMapping {
+    source?: string;
+    value?: SdApiContractJsonValue;
+}
+export interface SdApiContractFeScalarNode extends SdApiContractNodeBase {
+    type: SdApiContractScalarDataType;
+    /** Only meaningful on `date` / `datetime`; reused verbatim from the temporal form controls. */
+    transform?: SdTemporalValueTransform;
+}
+export interface SdApiContractFeObjectNode extends SdApiContractNodeBase {
+    type: 'object';
+    properties: Record<string, SdApiContractFeSchemaNode>;
+}
+export interface SdApiContractFeArrayNode extends SdApiContractNodeBase {
+    type: 'array';
+    items: SdApiContractFeSchemaNode;
+}
+/** A pure declaration — no `source` / `value`, because `input` is what the caller hands in. */
+export type SdApiContractFeSchemaNode = SdApiContractFeScalarNode | SdApiContractFeObjectNode | SdApiContractFeArrayNode;
+export interface SdApiContractRestScalarNode extends SdApiContractNodeBase {
+    type: SdApiContractScalarDataType;
+}
+export interface SdApiContractRestObjectNode extends SdApiContractNodeBase {
+    type: 'object';
+    properties: Record<string, SdApiContractRestNode>;
+}
+export interface SdApiContractRestArrayNode extends SdApiContractNodeBase {
+    type: 'array';
+    items: SdApiContractRestNode;
+}
+/** Describes what the backend returns. Never carries a mapping — nothing maps *into* a response. */
+export type SdApiContractRestNode = SdApiContractRestScalarNode | SdApiContractRestObjectNode | SdApiContractRestArrayNode;
+export interface SdApiContractMappedRestScalarNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: SdApiContractScalarDataType;
+}
+export interface SdApiContractMappedRestObjectNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'object';
+    /** Omitted when the whole object is mapped through `source` / `value`. */
+    properties?: Record<string, SdApiContractMappedRestNode>;
+}
+export interface SdApiContractMappedRestArrayNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'array';
+    /** Describes the element type. Per-item projection is intentionally out of scope. */
+    items: SdApiContractMappedRestNode;
+}
+export type SdApiContractMappedRestNode = SdApiContractMappedRestScalarNode | SdApiContractMappedRestObjectNode | SdApiContractMappedRestArrayNode;
+export interface SdApiContractMappedFeScalarNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: SdApiContractScalarDataType;
+    transform?: SdTemporalValueTransform;
+}
+export interface SdApiContractMappedFeObjectNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'object';
+    properties?: Record<string, SdApiContractMappedFeSchemaNode>;
+}
+export interface SdApiContractMappedFeArrayNode extends SdApiContractNodeBase, SdApiContractMapping {
+    type: 'array';
+    items: SdApiContractMappedFeSchemaNode;
+}
+export type SdApiContractMappedFeSchemaNode = SdApiContractMappedFeScalarNode | SdApiContractMappedFeObjectNode | SdApiContractMappedFeArrayNode;
+/** Structural union of every node shape, for utilities that traverse any layer. */
+export type SdApiContractAnyNode = SdApiContractFeSchemaNode | SdApiContractRestNode | SdApiContractMappedRestNode | SdApiContractMappedFeSchemaNode;
+export type SdApiContractHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export declare const SD_API_CONTRACT_HTTP_METHODS: readonly SdApiContractHttpMethod[];
+export 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`.
+ */
+export 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;
+}
+export 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. */
+export declare const SD_API_CONTRACT_VERSION = 1;
+export interface SdApiContract {
+    contractVersion: 1;
+    code: string;
+    name: string;
+    description?: string;
+    input: {
+        schema: SdApiContractFeSchemaNode;
+    };
+    req: SdApiContractRequest;
+    res: SdApiContractResponse;
+    output: {
+        schema: SdApiContractMappedFeSchemaNode;
+    };
+}
+export type SdApiContractDiagnosticSeverity = 'error' | 'warning';
+export 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. */
+export type SdApiContractExpressionRoot = 'input' | 'env' | 'res';
+export 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`.
+ */
+export type SdApiContractMappingContext = 'request' | 'output';
+export declare const SD_API_CONTRACT_ALLOWED_ROOTS: Readonly<Record<SdApiContractMappingContext, readonly SdApiContractExpressionRoot[]>>;

package/components/api-contract-builder/src/api-contract.samples.d.ts

@@ -0,0 +1,25 @@
+import type { SdApiContractConfiguration } from './api-contract.configuration';
+import type { SdApiContract } from './api-contract.model';
+/**
+ * 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. */
+export declare const SD_API_CONTRACT_SAMPLE_ENVIRONMENT: SdApiContractConfiguration;
+/** `GET` list endpoint whose output is a root array — the dropdown / table shape. */
+export 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`.
+ */
+export 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.
+ */
+export declare function sdApiContractInvalidSample(): SdApiContract;

package/components/api-contract-builder/src/api-contract.schema.d.ts

@@ -0,0 +1,126 @@
+import type { SdTemporalValueTransform } from '@sdcorejs/angular/forms/models';
+import { type SdApiContractDataType, type SdApiContractExpressionRoot, type SdApiContractJsonValue, type SdApiContractResponse } from './api-contract.model';
+/**
+ * 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.
+ */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}
+export 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;
+}
+export 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;
+}
+export 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. */
+export declare function listSdApiContractSchemaFields(node: SdApiContractStructuralNode, options?: SdApiContractFieldListOptions): readonly SdApiContractSchemaField[];
+/** Every `${res.…}` path the output layer may address, in a stable order. */
+export 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.
+ */
+export declare function resolveSdApiContractSchemaPath(root: SdApiContractStructuralNode, path: readonly string[]): SdApiContractStructuralNode | null;
+/** Resolves `status` / `headers.<name>` / `body.<path>` against a response declaration. */
+export 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. */
+export declare function getSdApiContractNodeAt(root: SdApiContractStructuralNode, pointer: SdApiContractNodePointer): SdApiContractStructuralNode | null;
+/** Replaces the node a pointer addresses, rebuilding only the spine. Never mutates `root`. */
+export 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. */
+export 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. */
+export declare function renameSdApiContractProperty(node: SdApiContractStructuralNode, from: string, to: string): SdApiContractObjectShape;
+export declare function removeSdApiContractProperty(node: SdApiContractStructuralNode, key: string): SdApiContractObjectShape;
+/** A minimal well-formed node of the given type. */
+export 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`.
+ */
+export 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. */
+export 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.
+ */
+export declare function cloneSdApiContract<T>(contract: T): T;
+export declare function sdApiContractRecordSet<T>(record: Record<string, T> | undefined, key: string, value: T): Record<string, T>;
+export 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. */
+export declare function sdApiContractRecordRename<T>(record: Record<string, T>, from: string, to: string): Record<string, T>;
+/** Builds the canonical expression text — the inverse of `parseSdApiContractTemplate`. */
+export declare function formatSdApiContractExpression(root: SdApiContractExpressionRoot, path: readonly string[]): string;
+/** Joins a diagnostic base path with a structural pointer, e.g. `req.body` + `properties.x`. */
+export 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.
+ */
+export declare function parseSdApiContractUrlPlaceholders(url: string): SdApiContractUrlPlaceholders;

package/components/api-contract-builder/src/api-contract.serializer.d.ts

@@ -0,0 +1,17 @@
+import type { SdApiContract } from './api-contract.model';
+/**
+ * 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.
+ */
+export declare function serializeSdApiContract(contract: SdApiContract | null | undefined): string;

package/components/api-contract-builder/src/api-contract.validation.d.ts

@@ -0,0 +1,12 @@
+import { type SdApiContractConfiguration } from './api-contract.configuration';
+import { type SdApiContractDiagnostic } from './api-contract.model';
+/**
+ * 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.
+ */
+export declare function validateSdApiContract(contract: unknown, configuration?: SdApiContractConfiguration): SdApiContractDiagnostic[];

package/components/api-contract-builder/src/components/api-contract-diagnostic-list.component.d.ts

@@ -0,0 +1,18 @@
+import type { SdApiContractDiagnostic } from '../api-contract.model';
+import * as i0 from "@angular/core";
+/**
+ * Validation summary + the diagnostic list.
+ *
+ * Severity is never signalled by colour alone: every row carries an icon, the severity word, the
+ * stable `code` and the structural `path`, so the list stays readable for a colour-blind reader and
+ * usable from a screen reader.
+ */
+export declare class SdApiContractDiagnosticList {
+    diagnostics: import("@angular/core").InputSignal<readonly SdApiContractDiagnostic[]>;
+    autoId: import("@angular/core").InputSignal<string | null | undefined>;
+    navigate: import("@angular/core").OutputEmitterRef<SdApiContractDiagnostic>;
+    protected readonly errorCount: import("@angular/core").Signal<number>;
+    protected readonly warningCount: import("@angular/core").Signal<number>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SdApiContractDiagnosticList, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SdApiContractDiagnosticList, "sd-api-contract-diagnostic-list", never, { "diagnostics": { "alias": "diagnostics"; "required": false; "isSignal": true; }; "autoId": { "alias": "autoId"; "required": false; "isSignal": true; }; }, { "navigate": "navigate"; }, never, never, true, never>;
+}