@gnggln/ng-ui-system 1.0.0-alpha.2 → 1.0.0-alpha.21

package/lib/components/form-builder/types/field.types.d.ts

@@ -2,8 +2,10 @@
  * @module ng-ui-system/form-builder
  * Tipi relativi ai campi del form builder.
  */
+import type { FormControl, FormGroup } from '@angular/forms';
 import { Observable } from 'rxjs';
 import { UiIconName } from '../../../core/types';
+import type { UiLocationGeocodedFieldConfig } from './geocoded-location.types';
 export { UiIconName };
 /**
  * Tipi di campo supportati dal form builder.
@@ -29,8 +31,9 @@ export { UiIconName };
  * | `custom`          | Extension point per componenti custom              |
  * | `location`        | Selezione territorio (nazione/provincia/comune/CAP)|
  * | `location-table`  | Tabella CRUD di location multiple                  |
+ * | `location-geocoded` | Indirizzo libero con autocomplete geocodificato   |
  */
-export type UiFieldType = 'text' | 'email' | 'password' | 'number' | 'textarea' | 'select' | 'multiselect' | 'freemultiselect' | 'checkbox' | 'switch' | 'radio' | 'date' | 'datetime' | 'file' | 'divider' | 'flag' | 'custom' | 'location' | 'location-table';
+export type UiFieldType = 'text' | 'email' | 'password' | 'number' | 'textarea' | 'select' | 'multiselect' | 'freemultiselect' | 'checkbox' | 'switch' | 'radio' | 'date' | 'datetime' | 'file' | 'divider' | 'flag' | 'custom' | 'location' | 'location-table' | 'location-geocoded';
 /**
  * Singola opzione per campi select, radio, multiselect.
  */
@@ -167,8 +170,13 @@ export interface UiFileInputConfig {
  * ```
  */
 export interface UiCustomComponentConfig {
-    /** Selettore del componente. */
+    /** Selettore logico o nome del widget (documentazione / tooling). */
     component: string;
+    /**
+     * Chiave per risolvere il template in `customFieldTemplates` sul form builder.
+     * Se assente si usa `component`, poi la chiave del campo (`field.key`).
+     */
+    templateKey?: string;
     /** Input da passare al componente. */
     inputs?: Record<string, any>;
     /** Output da ascoltare dal componente. */
@@ -177,8 +185,33 @@ export interface UiCustomComponentConfig {
     config?: Record<string, any>;
 }
 /**
- * Interfaccia che i componenti custom devono implementare
- * per integrarsi con il form builder.
+ * Contesto passato a `ngTemplateOutlet` per i campi `type: 'custom'`.
+ * Il componente proiettato dovrebbe collegare il valore tramite `control`
+ * (idealmente implementando `ControlValueAccessor` o `[formControl]`).
+ */
+export interface UiCustomFieldTemplateContext {
+    /** Stesso di `field` (valore implicito per `let-field` nel template). */
+    $implicit: UiFormFieldDescriptor;
+    /** Descrittore del campo. */
+    field: UiFormFieldDescriptor;
+    /** FormGroup del contesto (root o istanza repeatable). */
+    formGroup: FormGroup;
+    /** `FormControl` del campo (`formGroup.get(field.key)`). */
+    control: FormControl;
+    /** Configurazione da `customConfig.config`. */
+    config: Record<string, any>;
+    /**
+     * Prefisso per chiavi errore/scroll dei campi interni al CVA
+     * (es. `step9[0].sezioneRepertorioRegionale__`).
+     */
+    nestedErrorKeyPrefix?: string;
+    /** Notifica eventi applicativi (inoltrati come `customEvent` dal form builder). */
+    emitCustomEvent: (event: string, data?: any) => void;
+}
+/**
+ * Interfaccia legacy per integrazione imperativa (callback).
+ * Preferire `ControlValueAccessor` sul controllo del campo e il contesto
+ * `UiCustomFieldTemplateContext` tramite template outlet.
  */
 export interface UiCustomFormComponent {
     /** Valore corrente del componente. */
@@ -245,9 +278,16 @@ export interface UiFormFieldDescriptor {
     searchable?: boolean;
     /** Mostra pulsante "Seleziona tutto" per multiselect. */
     allowSelectAll?: boolean;
-    /** Callback per recupero asincrono di opzioni filtrate per query. */
+    /**
+     * Con `searchable: true` su `select`/`text`, ogni `input` dell'autocomplete
+     * invoca la callback: il risultato sostituisce l'elenco opzioni mostrato.
+     */
     asyncOptions?: (query: string) => Promise<UiFieldOption[]>;
-    /** Callback per recupero asincrono di opzioni per ID (prevalorizzazione). */
+    /**
+     * Contratto per risolvere opzioni da id (es. prefill da API). Il Form Builder
+     * Angular attuale non invoca questa callback; l'app può comporre le opzioni
+     * in `options` o collegarla a logica custom.
+     */
     recoverAsyncValues?: (ids: any[]) => Promise<UiFieldOption[]>;
     /** Generazione dinamica di opzioni. */
     dynamicOptions?: UiDynamicOptionsConfig;
@@ -263,6 +303,8 @@ export interface UiFormFieldDescriptor {
     customConfig?: UiCustomComponentConfig;
     /** Configurazione per il campo file. */
     fileConfig?: UiFileInputConfig;
+    /** Configurazione per il campo `location-geocoded` (Nominatim / proxy). */
+    locationGeocodedConfig?: UiLocationGeocodedFieldConfig;
     /** Configurazione aspetto del campo. */
     appearance?: {
         /** Per checkbox: 'switch' rende il campo come mat-slide-toggle. */

package/lib/components/form-builder/types/geocoded-location.types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi per il campo `location-geocoded` (indirizzo con geocoding).
+ */
+/**
+ * Dettaglio minimo per una sede **italiana** (allineato a comune / provincia / regione).
+ * Popolato solo se {@link UiGeocodedLocationType.territory} è `'italian'`.
+ */
+export interface UiGeocodedItalianDetails {
+    /** Comune (o equivalente censuario). */
+    comune?: string;
+    /**
+     * Provincia: nome o sigla se restituita dal provider (es. da `county` Nominatim).
+     */
+    provincia?: string;
+    /** Regione. */
+    regione?: string;
+}
+/**
+ * Dettaglio minimo per una sede **estera** (struttura generica, indipendente dal paese).
+ * Popolato solo se {@link UiGeocodedLocationType.territory} è `'foreign'`.
+ */
+export interface UiGeocodedForeignDetails {
+    /** Località principale (città, town, ecc.). */
+    locality?: string;
+    /** Area amministrativa (stato federato, Land, contea, ecc.). */
+    adminArea?: string;
+    /** Codice paese ISO 3166-1 alpha-2 (ridondante con il campo radice se già presente). */
+    countryCode?: string;
+}
+/**
+ * Valore atomico restituito dal campo geocodificato.
+ * Struttura indipendente dal provider; la mappatura avviene nel servizio di ricerca.
+ *
+ * Usa {@link territory} e i blocchi `italian` / `foreign` per logiche diverse (es. validazione,
+ * persistenza); i campi piatti (`city`, `province`, …) restano per compatibilità e uso generico.
+ */
+export interface UiGeocodedLocationType {
+    /** Etichetta principale mostrata all'utente. */
+    label: string;
+    /** Latitudine WGS84. */
+    latitude: number;
+    /** Longitudine WGS84. */
+    longitude: number;
+    /** Indirizzo formattato completo. */
+    formattedAddress: string;
+    /**
+     * Ambito territoriale dedotto dal paese (ISO): Italia vs resto del mondo.
+     * Se il provider non fornisce `country_code`, si assume `'foreign'`.
+     */
+    territory: 'italian' | 'foreign';
+    /**
+     * Dettaglio strutturato per sedi italiane. Assente se `territory === 'foreign'`.
+     */
+    italian?: UiGeocodedItalianDetails;
+    /**
+     * Dettaglio strutturato per sedi non italiane. Assente se `territory === 'italian'`.
+     */
+    foreign?: UiGeocodedForeignDetails;
+    street?: string;
+    streetNumber?: string;
+    postalCode?: string;
+    city?: string;
+    municipality?: string;
+    province?: string;
+    region?: string;
+    country?: string;
+    countryCode?: string;
+    placeId?: string;
+    /** Affidabilità stimata del risultato (0–1), se disponibile dal provider. */
+    confidence?: number;
+    boundingBox?: {
+        north: number;
+        south: number;
+        east: number;
+        west: number;
+    };
+    source?: 'nominatim' | 'pelias' | 'mapbox' | 'google' | 'custom';
+    /** Payload grezzo del provider (debug / integrazioni avanzate). */
+    raw?: unknown;
+}
+/**
+ * Valore accettato da `ControlValueAccessor.writeValue` quando i dati persistiti
+ * possono non includere ancora `territory` (versioni precedenti del modello).
+ */
+export type UiGeocodedLocationInput = Omit<UiGeocodedLocationType, 'territory'> & {
+    territory?: 'italian' | 'foreign';
+};
+/**
+ * Configurazione del campo `location-geocoded` nello schema del form.
+ */
+export interface UiLocationGeocodedFieldConfig {
+    /**
+     * Base URL dell'endpoint di ricerca (senza slash finale).
+     * Per Nominatim: `https://nominatim.openstreetmap.org` oppure, in sviluppo,
+     * un proxy same-origin (es. `/nominatim`) per rispettare CORS e User-Agent.
+     * @default 'https://nominatim.openstreetmap.org'
+     */
+    nominatimBaseUrl?: string;
+    /** Numero minimo di caratteri prima di avviare la ricerca. @default 3 */
+    minChars?: number;
+    /** Debounce sulla digitazione in millisecondi. @default 200 */
+    debounceMs?: number;
+    /** Numero massimo di suggerimenti. @default 5 */
+    limit?: number;
+    /**
+     * Codice ISO paese per **limitare** i risultati (parametro Nominatim `countrycodes`).
+     * Se omesso, la ricerca è **mondiale** (nessun filtro paese).
+     */
+    biasCountry?: string;
+    /** Punto di riferimento per ordinare i risultati (`viewbox` Nominatim). */
+    biasProximity?: {
+        lat: number;
+        lng: number;
+    };
+}

package/lib/components/form-builder/types/index.d.ts

@@ -1,5 +1,6 @@
-export { UiFieldType, UiFieldOption, UiDynamicOptionsConfig, UiDependentOptionsConfig, UiIconTooltip, UiFileData, UiFileInputConfig, UiCustomComponentConfig, UiCustomFormComponent, UiFormFieldDescriptor, } from './field.types';
-export { UiCrossFieldOperator, UiCrossFieldConfig, UiDateKeyword, UiDateValidationConfig, UiValidationType, UiValidationRule, UiFormValidationState, UiFormErrorDetail, } from './validation.types';
+export { UiFieldType, UiFieldOption, UiDynamicOptionsConfig, UiDependentOptionsConfig, UiIconTooltip, UiFileData, UiFileInputConfig, UiCustomComponentConfig, UiCustomFieldTemplateContext, UiCustomFormComponent, UiFormFieldDescriptor, } from './field.types';
+export { UiCrossFieldOperator, UiCrossFieldConfig, UiDateKeyword, UiDateValidationConfig, UiValidationType, UiValidationRule, UiFormValidationState, UiFormErrorDetail, UI_FORM_NESTED_FIELD_ERRORS_KEY, } from './validation.types';
 export { UiConditionalOperator, UiFieldCondition, } from './condition.types';
 export { UiLocationFieldConfig, UiLocationConfig, UiLocationLabels, UiLocationValue, UiLocationTableConfig, UiLocationRow, } from './territoriale.types';
-export { UiWizardStepValidation, UiWizardValidationFn, UiWizardStepConfig, UiFormSection, UiFormBuilderConfig, UiWizardConfig, UiWizardState, UiFormSchema, UiFormData, UiFormCustomEvent, UiWizardStepChangeEvent, UiWizardStepCompleteEvent, } from './schema.types';
+export { UiGeocodedLocationType, UiGeocodedLocationInput, UiGeocodedItalianDetails, UiGeocodedForeignDetails, UiLocationGeocodedFieldConfig, } from './geocoded-location.types';
+export { UiRepeatableConfig, UiWizardStepValidation, UiWizardValidationFn, UiWizardStepConfig, UiFormSection, UiFormBuilderConfig, UiWizardConfig, UiWizardState, UiFormSchema, UiFormData, UiFormCustomEvent, UiWizardStepChangeEvent, UiWizardStepCompleteEvent, } from './schema.types';

package/lib/components/form-builder/types/schema.types.d.ts

@@ -4,6 +4,7 @@
  */
 import { UiFormFieldDescriptor } from './field.types';
 import { UiFieldCondition } from './condition.types';
+import { UiIconName } from '../../../core/types';
 /**
  * Configurazione di validazione per un singolo step del wizard.
  */
@@ -12,7 +13,11 @@ export interface UiWizardStepValidation {
     required?: boolean;
     /** Campi specifici da validare in questo step (se omesso, tutti i campi dello step). */
     validateFields?: string[];
-    /** Se validare anche i componenti custom nello step. @default true */
+    /**
+     * Se `false`, nella navigazione wizard i campi `type: 'custom'` non concorrono
+     * alla validità dello step (e i loro errori non bloccano il passaggio).
+     * @default true
+     */
     validateCustomComponents?: boolean;
 }
 /**
@@ -44,10 +49,52 @@ export interface UiWizardStepConfig {
     /** Metadati aggiuntivi per lo step. */
     metadata?: Record<string, any>;
 }
+/**
+ * Configurazione per sezioni ripetibili (dynamic repeater).
+ * Permette di aggiungere/rimuovere/duplicare N istanze di un blocco
+ * di campi, con il modello reattivo gestito tramite FormArray.
+ *
+ * @example
+ * ```typescript
+ * const section: UiFormSection = {
+ *   id: 'obiettivi',
+ *   title: 'Obiettivi formativi',
+ *   repeatable: {
+ *     min: 1,
+ *     max: 10,
+ *     addLabel: 'Aggiungi obiettivo',
+ *     addIcon: 'plus',
+ *     instanceTitle: 'Obiettivo {index}',
+ *   },
+ *   fields: [ ... ],
+ * };
+ * ```
+ */
+export interface UiRepeatableConfig {
+    /**
+     * Numero minimo di istanze obbligatorie.
+     * Se `min > 0`, alla creazione del form vengono pre-create almeno `min` istanze
+     * (vuote o da `initialData[sectionId]`). Se omesso, vale `1`.
+     * Con `min: 0` non si aggiungono righe oltre a quelle già presenti in `initialData`.
+     */
+    min?: number;
+    /** Numero massimo di istanze (undefined = illimitato). */
+    max?: number;
+    /** Label per il pulsante "Aggiungi". @default '+ Aggiungi' */
+    addLabel?: string;
+    /** Icona Lucide per il pulsante "Aggiungi". @default 'plus' */
+    addIcon?: UiIconName;
+    /** Template per il titolo di ogni istanza. `{index}` viene sostituito con l'indice 1-based. */
+    instanceTitle?: string;
+    /** Se richiedere conferma prima della rimozione. @default false */
+    confirmRemove?: boolean;
+    /** Messaggio di conferma rimozione. @default 'Sei sicuro di voler rimuovere questa sezione?' */
+    confirmMessage?: string;
+}
 /**
  * Sezione del form che raggruppa campi correlati.
- * Supporta collapsibilita (accordion), condizioni di visibilita
- * e configurazione wizard opzionale.
+ * Supporta collapsibilita (accordion), condizioni di visibilita,
+ * configurazione wizard opzionale e ripetibilita dinamica.
  *
  * @example
  * ```typescript
@@ -67,6 +114,8 @@ export interface UiFormSection {
     title?: string;
     /** Descrizione della sezione. */
     description?: string;
+    /** Icona Lucide opzionale per la sezione (visibile in modalità collapsible). @see https://lucide.dev/icons */
+    icon?: UiIconName;
     /** Campi contenuti nella sezione. */
     fields: UiFormFieldDescriptor[];
     /** Condizioni per la visibilita della sezione. */
@@ -77,8 +126,16 @@ export interface UiFormSection {
     collapsed?: boolean;
     /** Classi CSS aggiuntive per la sezione. */
     cssClasses?: string[];
-    /** Configurazione wizard per questa sezione. */
+    /**
+     * Configurazione wizard per questa sezione.
+     * Più sezioni possono condividere lo stesso `wizardStep.stepNumber`: formano un unico
+     * passo del wizard (es. più blocchi `collapsible` nello stesso step). Titolo, descrizione
+     * e validazione del passo si intendono dalla **prima** sezione del gruppo in ordine di schema.
+     * Le chiavi dei campi devono restare univoche tra tutte le sezioni dello stesso schema wizard.
+     */
     wizardStep?: UiWizardStepConfig;
+    /** Configurazione per sezione ripetibile. Se definito, la sezione diventa un dynamic repeater. */
+    repeatable?: UiRepeatableConfig;
 }
 /**
  * Configurazione globale del form builder.
@@ -90,8 +147,15 @@ export interface UiFormBuilderConfig {
     columns?: number;
     /** Mostra i pulsanti di azione (submit/reset). @default true */
     showButtons?: boolean;
-    /** Nasconde l'intero footer (pulsanti + error summary). */
+    /** Nasconde solo l'area pulsanti del footer (`ui-button-area`), non il summary errori. */
     hideFooter?: boolean;
+    /**
+     * Nasconde del tutto il blocco `ui-form-error-summary`.
+     * Se assente/falsy il summary è visibile anche senza errori (stato ok prevedibile).
+     */
+    hideErrorSummary?: boolean;
+    /** Messaggio nel summary quando il form non ha errori (stato ok). */
+    errorSummaryValidMessage?: string;
     /** Label personalizzate per i pulsanti. */
     buttonLabels?: {
         submit?: string;
@@ -111,7 +175,7 @@ export interface UiFormBuilderConfig {
  *   showProgress: true,
  *   progressStyle: 'steps',
  *   allowBackNavigation: true,
- *   buttonLabels: { next: 'Avanti', previous: 'Indietro', finish: 'Completa' },
+ *   buttonLabels: { submit: 'Salva e prosegui', previous: 'Indietro', finish: 'Completa' },
  * };
  * ```
  */
@@ -134,10 +198,23 @@ export interface UiWizardConfig {
     onStepSave?: (stepData: Record<string, any>, stepNumber: number) => Promise<void> | void;
     /** Mostra pulsanti di navigazione (precedente/successivo). @default true */
     showNavigationButtons?: boolean;
+    /** Posizione dei pulsanti di navigazione. @default 'bottom' */
+    navigationPosition?: 'top' | 'bottom' | 'both';
+    /**
+     * Consente di saltare a uno step già completato cliccando bullet o titolo step
+     * quando `progressStyle` è `'steps'`. @default true
+     */
+    allowStepIndicatorNavigation?: boolean;
     /** Label personalizzate per i pulsanti del wizard. */
     buttonLabels?: {
         previous?: string;
+        /** Label pulsante avanti; se assente si usa `submit`. */
         next?: string;
+        /**
+         * Alias di convenienza (come `submit` sul form builder) per il pulsante «avanti» / salva e prosegui.
+         * Usato solo se `next` non è valorizzato.
+         */
+        submit?: string;
         finish?: string;
         save?: string;
     };

package/lib/components/form-builder/types/validation.types.d.ts

@@ -161,6 +161,11 @@ export interface UiFormValidationState {
     /** Chiavi dei campi toccati. */
     touched: string[];
 }
+/**
+ * Chiave `ValidationErrors` usata dai CVA custom per esporre errori granulari
+ * sui campi interni (atomici) verso l'error-summary del form-builder.
+ */
+export declare const UI_FORM_NESTED_FIELD_ERRORS_KEY = "uiNestedFieldErrors";
 /**
  * Dettaglio di un errore per l'error summary.
  */

package/lib/components/form-builder-editor/index.d.ts

@@ -13,3 +13,5 @@ export { UiConditionEditorComponent } from './sub-components/condition-editor/co
 export { UiOptionsEditorComponent } from './sub-components/options-editor/options-editor.component';
 export { UiEditorFormValuesPanelComponent } from './sub-components/form-values-panel/form-values-panel.component';
 export * from './types/editor.types';
+export { PRESET_ANAGRAFICA, PRESET_TICKET, PRESET_SURVEY, EDITOR_PRESETS } from './presets/editor-presets';
+export type { EditorPresetInfo } from './presets/editor-presets';

package/lib/components/form-builder-editor/presets/editor-presets.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module ng-ui-system/form-builder-editor
+ * Preset di schemi per l'editor del form builder.
+ *
+ * Raccolta di scenari comuni che dimostrano le capacità del descrittore:
+ * - Validazione avanzata (required, pattern, cross-field)
+ * - Condizioni di visibilità e disabilitazione
+ * - Layout multi-colonna con breakpoints
+ * - Campi select/radio/multiselect con opzioni
+ * - Sezioni multiple organizzate per contesto
+ * - File upload, switch, divider, textarea
+ *
+ * Utilizzabili sia nella variante Material che Bootstrap Italia.
+ */
+import type { UiFormSchema } from '../../form-builder/types/index';
+export declare const PRESET_ANAGRAFICA: UiFormSchema;
+export declare const PRESET_TICKET: UiFormSchema;
+export declare const PRESET_SURVEY: UiFormSchema;
+export interface EditorPresetInfo {
+    key: string;
+    label: string;
+    description: string;
+    schema: UiFormSchema;
+}
+export declare const EDITOR_PRESETS: EditorPresetInfo[];

package/lib/components/http/http-message.handler.d.ts

@@ -0,0 +1,59 @@
+import type { UiEndpoint } from '../../core/types/index';
+import * as i0 from "@angular/core";
+/**
+ * Orchestrates toast notifications and loader state for HTTP requests.
+ *
+ * Features:
+ * - Debounce anti-spam (groups identical messages within 300ms)
+ * - Inline message resolution with placeholder replacements
+ * - `successMessageResolver` / `errorExtractor` for dynamic messages
+ * - Loader integration via `UiLayoutService` (optional)
+ */
+export declare class UiHttpMessageHandler {
+    private readonly toast;
+    private readonly layout;
+    /** Debounce time in milliseconds. */
+    private readonly DEBOUNCE_TIME;
+    /** Active debounce timeouts keyed by message content. */
+    private readonly messageTimeouts;
+    /** Show the global loader (via UiLayoutService if available). */
+    startLoading(): void;
+    /** Hide the global loader. */
+    stopLoading(): void;
+    /**
+     * Show a success toast for the given endpoint.
+     *
+     * Resolution priority:
+     * 1. `successMessageResolver()` if provided and returns non-null
+     * 2. `messages.success` with placeholder replacements
+     * 3. No toast if no message is configured
+     */
+    showSuccess(endpoint: UiEndpoint): void;
+    /**
+     * Show an error toast for the given endpoint.
+     *
+     * Resolution priority:
+     * 1. `errorExtractor(error)` if provided and returns non-null
+     * 2. `messages.error` with placeholder replacements
+     * 3. `fallbackMessage` if everything else is empty
+     */
+    showError(endpoint: UiEndpoint, error?: any, fallbackMessage?: string): void;
+    /** Show a custom success toast (not tied to an endpoint). */
+    showCustomSuccess(message: string): void;
+    /** Show a custom error toast (not tied to an endpoint). */
+    showCustomError(message: string): void;
+    /** Cancel all pending debounce timeouts. */
+    clearAllTimeouts(): void;
+    /**
+     * Debounce mechanism for toast messages.
+     * If the same message is requested within DEBOUNCE_TIME ms,
+     * only the last one is shown.
+     */
+    private debounceToast;
+    /**
+     * Replace `${key}` placeholders in a message string.
+     */
+    private applyReplacements;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiHttpMessageHandler, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiHttpMessageHandler>;
+}

package/lib/components/http/http.service.d.ts

@@ -0,0 +1,98 @@
+import { HttpHeaders } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import type { UiEndpoint } from '../../core/types/index';
+import * as i0 from "@angular/core";
+/**
+ * Central HTTP service with automatic loader, toast, and error handling.
+ *
+ * All toast flags default to `false` — enable them per-endpoint via
+ * `showSuccess: true` and/or `showError: true`.
+ */
+export declare class UiHttpService {
+    private readonly http;
+    private readonly messageHandler;
+    private readonly config;
+    private readonly headersProvider;
+    private readonly blackbox;
+    /** Resolved base URL from config token. */
+    private get baseUrl();
+    /** Execute a **GET** request. */
+    get<T>(endpoint: UiEndpoint, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<T>;
+    /** Execute a **POST** request. */
+    post<T>(endpoint: UiEndpoint, body: unknown, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<T>;
+    /** Execute a **PUT** request. */
+    put<T>(endpoint: UiEndpoint, body: unknown, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<T>;
+    /** Execute a **PATCH** request. */
+    patch<T>(endpoint: UiEndpoint, body: unknown, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<T>;
+    /** Execute a **DELETE** request. */
+    delete<T>(endpoint: UiEndpoint, body?: unknown, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<T>;
+    /**
+     * Download a **binary file** (Blob).
+     *
+     * Applies the same loader / toast pipeline as JSON requests.
+     */
+    download(endpoint: UiEndpoint, options?: {
+        headers?: HttpHeaders;
+        params?: any;
+    }): Observable<Blob>;
+    /** Show a custom success toast (not tied to an endpoint). */
+    showCustomSuccess(message: string): void;
+    /** Show a custom error toast (not tied to an endpoint). */
+    showCustomError(message: string): void;
+    /** Manually control the loader state. */
+    setLoading(loading: boolean): void;
+    /** Show a success toast for a specific endpoint (manual trigger). */
+    showEndpointSuccess(endpoint: UiEndpoint): void;
+    /** Show an error toast for a specific endpoint (manual trigger). */
+    showEndpointError(endpoint: UiEndpoint, error?: any, fallbackMessage?: string): void;
+    /** Cancel all pending debounce timeouts. */
+    clearAllToastTimeouts(): void;
+    /**
+     * Generic JSON request handler.
+     * Builds headers, serialises body, and pipes through the common pipeline.
+     */
+    private _request;
+    /**
+     * Common pipeline applied to every HTTP request:
+     * 1. Start loader
+     * 2. On success → show success toast
+     * 3. On error → show error toast, log, re-throw
+     * 4. Always stop loader
+     * 5. Track in BlackBox (if available and endpoint is trackable)
+     */
+    private _handleRequest;
+    /**
+     * Build the final HttpHeaders by merging:
+     * 1. Default headers from config
+     * 2. Custom headers from UiHeadersProvider
+     * 3. Per-request headers
+     */
+    private buildHeaders;
+    /**
+     * Centralised error handling.
+     * Logs the error and delegates toast display to the message handler.
+     */
+    private handleErrors;
+    /**
+     * Track the HTTP call in BlackBox if the service is available
+     * and the endpoint hasn't opted out.
+     */
+    private trackBlackbox;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiHttpService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiHttpService>;
+}

package/lib/components/http/http.tokens.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module ng-ui-system/http
+ * Injection tokens for the HTTP orchestration service.
+ */
+import { InjectionToken } from '@angular/core';
+import type { UiHttpConfig, UiHeadersProvider } from './http.types';
+/**
+ * Optional global configuration for `UiHttpService`.
+ *
+ * @usageNotes
+ * ```typescript
+ * providers: [
+ *   { provide: UI_HTTP_CONFIG, useValue: { baseUrl: '/api' } },
+ * ]
+ * ```
+ */
+export declare const UI_HTTP_CONFIG: InjectionToken<UiHttpConfig>;
+/**
+ * Optional headers provider for injecting custom headers (auth, correlation, etc.)
+ * into every HTTP request.
+ *
+ * @usageNotes
+ * ```typescript
+ * providers: [
+ *   { provide: UI_HEADERS_PROVIDER, useClass: MyAuthHeadersProvider },
+ * ]
+ * ```
+ */
+export declare const UI_HEADERS_PROVIDER: InjectionToken<UiHeadersProvider>;

package/lib/components/http/http.types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module ng-ui-system/http
+ * Types and interfaces for the HTTP orchestration service.
+ */
+/**
+ * Provider interface for custom HTTP headers.
+ *
+ * Implement this interface and register it with the `UI_HEADERS_PROVIDER`
+ * injection token to automatically inject custom headers (e.g. auth tokens,
+ * correlation IDs) into every request made by `UiHttpService`.
+ *
+ * @usageNotes
+ * ```typescript
+ * @Injectable()
+ * export class MyAuthHeadersProvider implements UiHeadersProvider {
+ *   getHeaders(): Record<string, string> {
+ *     const token = localStorage.getItem('jwt');
+ *     return token ? { Authorization: `Bearer ${token}` } : {};
+ *   }
+ * }
+ *
+ * // app.config.ts
+ * { provide: UI_HEADERS_PROVIDER, useClass: MyAuthHeadersProvider }
+ * ```
+ */
+export interface UiHeadersProvider {
+    /** Returns a plain object of header name → header value. */
+    getHeaders(): Record<string, string>;
+}
+/**
+ * Global configuration for `UiHttpService`.
+ *
+ * @usageNotes
+ * ```typescript
+ * // app.config.ts
+ * { provide: UI_HTTP_CONFIG, useValue: { baseUrl: '/api/v1' } }
+ * ```
+ */
+export interface UiHttpConfig {
+    /**
+     * Base URL prepended to every endpoint URL.
+     * Default: `''` (no prefix).
+     */
+    baseUrl?: string;
+    /**
+     * Default headers applied to every request.
+     * Can be overridden per-request via options.
+     */
+    defaultHeaders?: Record<string, string>;
+}