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

package/blackbox/lib/components/modal/confirm-dialog.component.d.ts

@@ -0,0 +1,46 @@
+import { UiConfirmDialogData, UiConfirmVariant, UiIconName, UiVariant } from './modal.types';
+import * as i0 from "@angular/core";
+/**
+ * Dialogo di conferma leggero per azioni condizionali.
+ *
+ * Non va utilizzato direttamente nel template: viene aperto
+ * programmaticamente tramite `UiModalService.confirm()` e i suoi
+ * metodi scorciatoia (`confirmDelete`, `confirmDiscard`, `confirmSave`).
+ *
+ * Supporta quattro varianti semantiche — confirm, delete, warn, info —
+ * ciascuna con icona e colore preconfigurati.
+ *
+ * @selector ui-confirm-dialog
+ *
+ * @example
+ * ```typescript
+ * // Apertura tramite servizio
+ * this.modalService.confirm({
+ *   title: 'Conferma eliminazione',
+ *   message: 'Questa azione non puo essere annullata.',
+ *   variant: 'delete',
+ * }).subscribe(confirmed => {
+ *   if (confirmed) this.deleteItem();
+ * });
+ * ```
+ */
+export declare class UiConfirmDialogComponent {
+    /** @internal Dati iniettati dal servizio modale. */
+    readonly data: UiConfirmDialogData;
+    /** @internal Riferimento al dialogo per la chiusura. */
+    private readonly dialogRef;
+    /** Variante semantica corrente. */
+    get variant(): UiConfirmVariant;
+    /** Nome icona Lucide da visualizzare. */
+    get iconName(): UiIconName;
+    /** Variante del pulsante di conferma. */
+    get confirmButtonVariant(): UiVariant;
+    /** Classi CSS per il contenitore icona. */
+    get iconClasses(): string;
+    /** Conferma e chiude il dialogo con `true`. */
+    confirm(): void;
+    /** Annulla e chiude il dialogo con `false`. */
+    cancel(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiConfirmDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiConfirmDialogComponent, "ui-confirm-dialog", never, {}, {}, never, never, true, never>;
+}

package/blackbox/lib/components/modal/index.d.ts

@@ -0,0 +1,4 @@
+export { UiModalComponent } from './modal.component';
+export { UiConfirmDialogComponent } from './confirm-dialog.component';
+export { UiModalService } from './modal.service';
+export { UiModalConfig, UiModalOpenConfig, UiModalSize, UiConfirmDialogData, UiConfirmVariant, } from './modal.types';

package/blackbox/lib/components/modal/modal.component.d.ts

@@ -0,0 +1,44 @@
+import { EventEmitter } from '@angular/core';
+import { UiModalConfig } from './modal.types';
+import * as i0 from "@angular/core";
+/**
+ * Componente modale standalone con struttura header/body/footer.
+ *
+ * Da utilizzare come wrapper all'interno di componenti aperti
+ * tramite `UiModalService.open()`. Fornisce la struttura visuale
+ * e gestisce la chiusura programmatica.
+ *
+ * **Content projection:**
+ * - Contenuto di default: va nel body
+ * - `[uiModalHeader]`: sostituisce il titolo nell'header
+ * - `[uiModalFooter]`: azioni nel footer
+ *
+ * @selector ui-modal
+ *
+ * @example
+ * ```html
+ * <ui-modal [config]="{ title: 'Dettagli', size: 'md' }">
+ *   <p>Contenuto del body della modale.</p>
+ *   <div uiModalFooter>
+ *     <ui-button label="Chiudi" variant="ghost" (click)="close()" />
+ *     <ui-button label="Salva" variant="primary" (click)="save()" />
+ *   </div>
+ * </ui-modal>
+ * ```
+ */
+export declare class UiModalComponent {
+    /** Configurazione strutturale della modale. */
+    config: UiModalConfig;
+    /**
+     * Emesso quando la modale viene chiusa.
+     * Utile se il componente e usato direttamente nel template
+     * senza UiModalService.
+     */
+    closed: EventEmitter<unknown>;
+    /** @internal Riferimento al dialogo Material per la chiusura. */
+    private dialogRef;
+    /** Chiude la modale con un risultato opzionale. */
+    close(result?: unknown): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiModalComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiModalComponent, "ui-modal", never, { "config": { "alias": "config"; "required": false; }; }, { "closed": "closed"; }, never, ["[uiModalHeader]", "*", "[uiModalFooter]"], true, never>;
+}

package/blackbox/lib/components/modal/modal.service.d.ts

@@ -0,0 +1,93 @@
+import { Type } from '@angular/core';
+import { MatDialogRef } from '@angular/material/dialog';
+import { Observable } from 'rxjs';
+import { UiConfirmDialogData, UiModalOpenConfig } from './modal.types';
+import * as i0 from "@angular/core";
+/**
+ * Servizio per aprire modali e dialoghi di conferma.
+ *
+ * Gestisce lo stacking intelligente: una modale regolare puo
+ * ospitare al massimo un dialogo di conferma sopra di se.
+ * Non e possibile stackare due modali regolari.
+ *
+ * @usageNotes
+ *
+ * ### Aprire una modale personalizzata
+ * ```typescript
+ * const ref = this.modalService.open(MyDialogComponent, {
+ *   size: 'lg',
+ *   data: { userId: 123 },
+ * });
+ *
+ * ref.afterClosed().subscribe(result => {
+ *   console.log('Risultato:', result);
+ * });
+ * ```
+ *
+ * ### Conferma rapida
+ * ```typescript
+ * this.modalService.confirm('Confermi questa azione?')
+ *   .subscribe(ok => { if (ok) this.procedi(); });
+ * ```
+ *
+ * ### Preset di conferma
+ * ```typescript
+ * this.modalService.confirmDelete('Progetto Alpha')
+ *   .subscribe(ok => { if (ok) this.elimina(); });
+ * ```
+ */
+export declare class UiModalService {
+    /** @internal Istanza MatDialog per la gestione overlay. */
+    private readonly dialog;
+    /** @internal Stack delle modali regolari aperte. */
+    private _modalStack;
+    /** @internal Traccia se un dialogo di conferma e attualmente aperto. */
+    private _confirmOpen;
+    /**
+     * Apre una modale con un componente personalizzato.
+     *
+     * Il componente aperto puo iniettare `MAT_DIALOG_DATA` per accedere
+     * ai dati e `MatDialogRef` per chiudere la modale.
+     *
+     * @param component - Componente standalone da renderizzare nella modale
+     * @param config - Configurazione (dimensione, dati, comportamento)
+     * @returns Riferimento alla modale aperta
+     */
+    open<T, D = unknown, R = unknown>(component: Type<T>, config?: UiModalOpenConfig<D>): MatDialogRef<T, R>;
+    /**
+     * Apre un dialogo di conferma.
+     *
+     * Accetta una stringa semplice (messaggio) o un oggetto di
+     * configurazione completo. Puo essere aperto sopra una modale
+     * esistente (stacking consentito).
+     *
+     * @param messageOrConfig - Messaggio o configurazione completa
+     * @returns Observable che emette `true` se confermato, `false` se annullato
+     */
+    confirm(messageOrConfig: string | UiConfirmDialogData): Observable<boolean>;
+    /**
+     * Scorciatoia: conferma eliminazione.
+     * Variante `delete` con icona cestino e pulsante warn.
+     *
+     * @param itemName - Nome opzionale dell'elemento da eliminare
+     */
+    confirmDelete(itemName?: string): Observable<boolean>;
+    /**
+     * Scorciatoia: conferma abbandono modifiche.
+     * Variante `warn` con icona avviso.
+     */
+    confirmDiscard(): Observable<boolean>;
+    /**
+     * Scorciatoia: conferma salvataggio.
+     * Variante `confirm` con icona check.
+     */
+    confirmSave(): Observable<boolean>;
+    /** Chiude tutte le modali e dialoghi aperti. */
+    closeAll(): void;
+    /** Indica se ci sono modali o dialoghi attualmente aperti. */
+    get hasOpenDialogs(): boolean;
+    /** Numero di modali regolari attualmente aperte. */
+    get openModalCount(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiModalService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiModalService>;
+}

package/blackbox/lib/components/modal/modal.types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @module ng-ui-system/modal
+ * Tipi e interfacce per UiModal, UiConfirmDialog e UiModalService.
+ */
+import { UiVariant, UiIconName } from '../../core/types';
+export { UiVariant, UiIconName };
+/**
+ * Dimensioni predefinite della modale.
+ *
+ * | Valore        | Larghezza | Caso d'uso                        |
+ * |--------------|-----------|-----------------------------------|
+ * | `sm`         | 400px     | Confirm, messaggi brevi           |
+ * | `md`         | 560px     | Form semplici, dettagli           |
+ * | `lg`         | 720px     | Form complessi, tabelle interne   |
+ * | `xl`         | 900px     | Dashboard modali, preview         |
+ * | `fullscreen` | 95vw      | Operazioni a schermo intero       |
+ */
+export type UiModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+/**
+ * Configurazione strutturale della modale.
+ * Passata come `@Input()` al componente `UiModalComponent`.
+ *
+ * @usageNotes
+ * ### Utilizzo base
+ * ```typescript
+ * const config: UiModalConfig = {
+ *   title: 'Modifica utente',
+ *   size: 'md',
+ * };
+ * ```
+ */
+export interface UiModalConfig {
+    /** Titolo visualizzato nell'header della modale. */
+    title?: string;
+    /** Dimensione della modale. @default 'md' */
+    size?: UiModalSize;
+    /** Mostra il pulsante di chiusura nell'header. @default true */
+    showCloseButton?: boolean;
+    /** Impedisce la chiusura tramite backdrop click o tasto Escape. @default false */
+    disableClose?: boolean;
+    /** Nasconde l'area footer della modale. @default false */
+    hideFooter?: boolean;
+}
+/**
+ * Configurazione per aprire una modale tramite `UiModalService.open()`.
+ *
+ * @usageNotes
+ * ```typescript
+ * this.modalService.open(MyComponent, {
+ *   size: 'lg',
+ *   data: { userId: 123 },
+ *   disableClose: true,
+ * });
+ * ```
+ */
+export interface UiModalOpenConfig<D = unknown> {
+    /** Dimensione della modale. @default 'md' */
+    size?: UiModalSize;
+    /** Dati da iniettare nel componente aperto tramite MAT_DIALOG_DATA. */
+    data?: D;
+    /** Impedisce la chiusura tramite backdrop click o tasto Escape. @default false */
+    disableClose?: boolean;
+    /** Classe CSS aggiuntiva per il pannello overlay. */
+    panelClass?: string;
+}
+/**
+ * Varianti semantiche del dialogo di conferma.
+ *
+ * | Variante   | Icona default      | Colore pulsante | Caso d'uso                |
+ * |-----------|-------------------|----------------|---------------------------|
+ * | `confirm` | `check-circle`     | `primary`       | Conferma azione positiva   |
+ * | `delete`  | `trash-2`          | `warn`          | Eliminazione irreversibile |
+ * | `warn`    | `alert-triangle`   | `warn`          | Avviso con conferma        |
+ * | `info`    | `info`             | `primary`       | Informazione con azione    |
+ */
+export type UiConfirmVariant = 'confirm' | 'delete' | 'warn' | 'info';
+/**
+ * Configurazione per il dialogo di conferma.
+ * Passata a `UiModalService.confirm()`.
+ *
+ * @usageNotes
+ * ### Conferma semplice (solo stringa)
+ * ```typescript
+ * this.modalService.confirm('Sei sicuro di voler procedere?');
+ * ```
+ *
+ * ### Conferma configurata
+ * ```typescript
+ * this.modalService.confirm({
+ *   title: 'Elimina elemento',
+ *   message: 'Questa azione non puo essere annullata.',
+ *   variant: 'delete',
+ *   confirmText: 'Elimina',
+ * });
+ * ```
+ */
+export interface UiConfirmDialogData {
+    /** Titolo del dialogo. */
+    title?: string;
+    /** Messaggio principale del dialogo. */
+    message: string;
+    /** Testo del pulsante di conferma. @default 'Conferma' */
+    confirmText?: string;
+    /** Testo del pulsante di annullamento. @default 'Annulla' */
+    cancelText?: string;
+    /** Variante semantica che determina icona e colore. @default 'confirm' */
+    variant?: UiConfirmVariant;
+    /** Icona personalizzata (sovrascrive quella della variante). */
+    icon?: UiIconName;
+}

package/blackbox/lib/core/types/index.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared types for ng-ui-system components.
+ * These types are used across multiple components to ensure consistency.
+ */
+/** Standard size variants used across components. */
+export type UiSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Visual style variants for components. */
+export type UiVariant = 'primary' | 'accent' | 'warn' | 'neutral' | 'ghost' | 'outline';
+/** Semantic color palette tokens. */
+export type UiColor = 'primary' | 'accent' | 'warn' | 'success' | 'info' | 'neutral';
+/** Layout direction. */
+export type UiDirection = 'horizontal' | 'vertical';
+/** Horizontal alignment. */
+export type UiAlign = 'start' | 'center' | 'end' | 'stretch';
+/** Component density options for compact or spacious layouts. */
+export type UiDensity = 'compact' | 'default' | 'comfortable';
+/**
+ * Common Lucide icon names with autocomplete support.
+ * Accepts any valid Lucide icon name as a string.
+ *
+ * Provides IntelliSense for the most frequently used enterprise icons.
+ * For the full icon catalogue, visit https://lucide.dev/icons
+ *
+ * @example
+ * ```typescript
+ * const myIcon: UiIconName = 'arrow-right';  // autocomplete ✓
+ * const custom: UiIconName = 'my-custom-icon'; // still valid
+ * ```
+ */
+export type UiIconName = 'arrow-right' | 'arrow-left' | 'arrow-up' | 'arrow-down' | 'chevron-right' | 'chevron-left' | 'chevron-up' | 'chevron-down' | 'external-link' | 'corner-down-left' | 'corner-down-right' | 'check' | 'x' | 'plus' | 'minus' | 'search' | 'refresh-cw' | 'download' | 'upload' | 'save' | 'trash-2' | 'pencil' | 'copy' | 'clipboard' | 'share-2' | 'send' | 'log-in' | 'log-out' | 'mail' | 'message-circle' | 'phone' | 'bell' | 'user' | 'users' | 'lock' | 'unlock' | 'key' | 'shield' | 'file' | 'file-text' | 'file-spreadsheet' | 'file-archive' | 'folder' | 'image' | 'camera' | 'paperclip' | 'info' | 'alert-triangle' | 'alert-circle' | 'check-circle' | 'x-circle' | 'help-circle' | 'loader-2' | 'menu' | 'more-horizontal' | 'more-vertical' | 'grid' | 'list' | 'filter' | 'sliders' | 'columns' | 'maximize-2' | 'minimize-2' | 'home' | 'settings' | 'star' | 'heart' | 'bookmark' | 'calendar' | 'clock' | 'map-pin' | 'eye' | 'eye-off' | 'sun' | 'moon' | 'monitor' | (string & Record<never, never>);
+/** Status values used for feedback components (badges, alerts, indicators). */
+export type UiStatus = 'idle' | 'loading' | 'success' | 'error' | 'warning' | 'info';
+/**
+ * Generic key-value pair used in select options, dropdowns, etc.
+ * @template T - The type of the value.
+ */
+export interface UiOption<T = string> {
+    /** The display label. */
+    label: string;
+    /** The underlying value. */
+    value: T;
+    /** Whether this option is disabled. */
+    disabled?: boolean;
+    /** Optional icon name (Lucide icon). */
+    icon?: UiIconName;
+    /** Optional grouping key for grouped selects. */
+    group?: string;
+}
+/**
+ * Result wrapper for async operations.
+ * @template T - The type of the data payload.
+ */
+export interface UiAsyncState<T = unknown> {
+    status: UiStatus;
+    data: T | null;
+    error: string | null;
+}
+/** Toast notification type. */
+export type UiToastType = 'success' | 'error' | 'warning' | 'info';
+/** Messages configuration for an endpoint (inline, no label archive). */
+export interface UiEndpointMessages {
+    /** Success toast message. Supports `${key}` placeholders replaced at runtime. */
+    success?: string;
+    /** Error toast message. Supports `${key}` placeholders replaced at runtime. */
+    error?: string;
+}
+/**
+ * Extracts a custom error message from the HTTP error response.
+ * Return `null` to fall back to the default message.
+ */
+export type UiErrorExtractor = (error: any) => string | null;
+/**
+ * Dynamically resolves a success message at runtime.
+ * Return `null` to fall back to the default message.
+ */
+export type UiSuccessResolver = () => string | null;
+/**
+ * Query parameters for URL building.
+ * Keys map to query param names; values are auto-converted to strings.
+ */
+export type UiQueryParameters = Record<string, string | string[] | number | number[] | boolean>;
+/**
+ * Endpoint configuration for `UiHttpService`.
+ *
+ * Each endpoint defines its URL, optional inline messages, and
+ * toast/error behaviour. All toast flags default to `false` (opt-in).
+ *
+ * @usageNotes
+ * ### Basic endpoint factory
+ * ```typescript
+ * const SAVE_USER = (): UiEndpoint => ({
+ *   url: '/api/users',
+ *   id: 'user_save',
+ *   showSuccess: true,
+ *   messages: { success: 'Utente salvato!' },
+ * });
+ * ```
+ *
+ * ### Dynamic endpoint with replacements
+ * ```typescript
+ * const UPDATE_ITEM = (id: number): UiEndpoint => ({
+ *   url: `/api/items/${id}`,
+ *   id: 'item_update',
+ *   showSuccess: true,
+ *   showError: true,
+ *   messages: {
+ *     success: 'Elemento ${name} aggiornato',
+ *     error: 'Errore aggiornamento elemento',
+ *   },
+ *   replacements: { name: 'Widget' },
+ * });
+ * ```
+ */
+export interface UiEndpoint {
+    /** Relative or absolute URL for the API call. */
+    url: string;
+    /** Unique identifier for the endpoint (used for debounce keying). */
+    id: string;
+    /** Whether to show a success toast on completion. Default: `false`. */
+    showSuccess?: boolean;
+    /** Whether to show an error toast on failure. Default: `false`. */
+    showError?: boolean;
+    /** Inline messages for success/error toasts. */
+    messages?: UiEndpointMessages;
+    /** Placeholder replacements for message strings (`${key}` → value). */
+    replacements?: Record<string, string | number>;
+    /** Custom error message extractor from the HTTP error response. */
+    errorExtractor?: UiErrorExtractor;
+    /** Custom success message resolver (overrides inline message). */
+    successMessageResolver?: UiSuccessResolver;
+    /** Whether this endpoint should be tracked by BlackBox. Default: `true`. */
+    trackable?: boolean;
+}

package/button/entry-button.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Bootstrap del secondary entry `@gnggln/ng-ui-system/button`. Button e Button Area.
+ */
+export * from './lib/components/button/index';

package/button/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@gnggln/ng-ui-system/button" />
+export * from './entry-button';

package/button/lib/components/blackbox/blackbox-fingerprint.service.d.ts

@@ -0,0 +1,36 @@
+import type { UiBlackboxFingerprint } from './blackbox.types';
+import * as i0 from "@angular/core";
+/**
+ * Generates and caches a stable browser/device fingerprint.
+ *
+ * Uses `@fingerprintjs/fingerprintjs` (open-source, MIT) which analyses
+ * canvas rendering, WebGL, audio context, screen properties, timezone,
+ * user-agent, and other browser signals to produce a stable hash.
+ *
+ * @usageNotes
+ * ```typescript
+ * const fp = inject(UiBlackboxFingerprintService);
+ * const hash = await fp.getFingerprint();
+ * // => "a1b2c3d4e5f6..." (stable across sessions)
+ * ```
+ */
+export declare class UiBlackboxFingerprintService {
+    private readonly platformId;
+    private cached;
+    /**
+     * Returns the stable fingerprint for this device/browser.
+     *
+     * On first call, loads FingerprintJS dynamically, computes the hash,
+     * and caches it in both memory and `localStorage`.
+     * Subsequent calls return the cached value immediately.
+     */
+    getFingerprint(): Promise<UiBlackboxFingerprint>;
+    /**
+     * Fallback fingerprint when FingerprintJS is unavailable.
+     * Combines basic browser signals into a hash.
+     * @internal
+     */
+    private generateFallbackFingerprint;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiBlackboxFingerprintService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiBlackboxFingerprintService>;
+}

package/button/lib/components/blackbox/blackbox-storage.service.d.ts

@@ -0,0 +1,55 @@
+import type { UiBlackboxSession } from './blackbox.types';
+import * as i0 from "@angular/core";
+/**
+ * Low-level IndexedDB adapter for reading/writing compressed BlackBox sessions.
+ *
+ * @usageNotes
+ * This service is used internally by `UiBlackboxService`.
+ * Consumers should interact with the higher-level `UiBlackboxService` API.
+ */
+export declare class UiBlackboxStorageService {
+    private readonly platformId;
+    private db;
+    private maxStorageMb;
+    /** Update the storage quota from the parent service config. */
+    setMaxStorageMb(mb: number): void;
+    /** Open (or create) the IndexedDB database. */
+    private openDb;
+    /** Compress a string to a gzip Uint8Array using native CompressionStream. */
+    private compress;
+    /** Decompress a gzip Uint8Array back to a string. */
+    private decompress;
+    /**
+     * Persist a session to IndexedDB (gzip-compressed).
+     * Enforces quota after saving.
+     */
+    saveSession(session: UiBlackboxSession): Promise<void>;
+    /**
+     * Read and decompress a single session by ID.
+     */
+    getSession(sessionId: string): Promise<UiBlackboxSession | null>;
+    /**
+     * Get all stored sessions (decompressed).
+     */
+    getAllSessions(): Promise<UiBlackboxSession[]>;
+    /**
+     * Get all sessions for a given fingerprint.
+     */
+    getSessionsByFingerprint(fingerprint: string): Promise<UiBlackboxSession[]>;
+    /**
+     * Generate a downloadable JSONL Blob of all sessions.
+     * Each line is one JSON-serialised session (decompressed).
+     */
+    exportDump(): Promise<Blob>;
+    /**
+     * Delete all stored sessions.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Prune oldest sessions until total stored size is under `maxStorageMb`.
+     * @internal
+     */
+    enforceQuota(): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiBlackboxStorageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiBlackboxStorageService>;
+}

package/button/lib/components/blackbox/blackbox.service.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @module ng-ui-system/blackbox
+ * Core BlackBox observability service — the main entry point for session
+ * recording, event buffering, and export.
+ *
+ * Architecture:
+ * - Root singleton (`providedIn: 'root'`)
+ * - On first inject: generates fingerprint, creates session, subscribes to Router events
+ * - Centralised in-memory buffer with periodic/threshold-based flush to IndexedDB
+ * - `window:beforeunload` triggers a final best-effort async flush
+ */
+import { OnDestroy } from '@angular/core';
+import { UiBlackboxConfig, UiBlackboxFormTrackingConfig, UiBlackboxSession, UiBlackboxFormEvent, UiBlackboxHttpCall } from './blackbox.types';
+import * as i0 from "@angular/core";
+/**
+ * Central BlackBox observability service.
+ *
+ * Records navigation, UI interactions, form events, and HTTP calls
+ * into compressed sessions stored in IndexedDB.
+ *
+ * @usageNotes
+ * The service activates automatically when injected. Provide it at root level
+ * and it will start recording immediately.
+ *
+ * ```typescript
+ * // app.config.ts — just importing the service is enough
+ * import { UiBlackboxService } from '@gnggln/ng-ui-system';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     // The service is providedIn: 'root', so it's auto-provided.
+ *     // To force eager initialisation:
+ *     { provide: APP_INITIALIZER, useFactory: () => () => inject(UiBlackboxService), multi: true },
+ *   ],
+ * };
+ * ```
+ */
+export declare class UiBlackboxService implements OnDestroy {
+    private readonly platformId;
+    private readonly router;
+    private readonly zone;
+    private readonly fingerprint;
+    private readonly storage;
+    private readonly destroy$;
+    private config;
+    private session;
+    private currentStep;
+    private initialised;
+    private buffer;
+    private flushTimerId;
+    private beforeUnloadHandler;
+    constructor();
+    private init;
+    /**
+     * Update the BlackBox configuration.
+     * Can be called at any time; changes take effect immediately.
+     */
+    configure(config: Partial<Omit<UiBlackboxConfig, 'formTracking'>> & {
+        formTracking?: Partial<UiBlackboxFormTrackingConfig>;
+    }): void;
+    /** Returns the current configuration (readonly snapshot). */
+    getConfig(): Readonly<UiBlackboxConfig>;
+    /**
+     * Manually track a UI action (click).
+     *
+     * Called automatically by `UiButtonAreaComponent` and the `[uiTrack]` directive.
+     * Can also be called programmatically for custom interactions.
+     *
+     * @param trackId - Identifier for the action (e.g. button id, link name).
+     * @param meta - Optional metadata: `tag`, `text`, `id` of the element.
+     */
+    trackAction(trackId: string, meta?: {
+        tag?: string;
+        text?: string;
+        id?: string;
+    }): void;
+    /**
+     * Track a form interaction event.
+     *
+     * Called automatically by `UiFormBuilderComponent` when the BlackBox
+     * service is available.
+     */
+    trackFormEvent(event: UiBlackboxFormEvent): void;
+    /**
+     * Track an intercepted HTTP call.
+     * Called by `UiBlackboxInterceptor`.
+     * @internal
+     */
+    trackHttpCall(call: UiBlackboxHttpCall): void;
+    /**
+     * Returns the current in-memory session (live, not yet flushed).
+     * Useful for debugging or real-time inspection.
+     */
+    getCurrentSession(): UiBlackboxSession;
+    /**
+     * Retrieve all sessions stored in IndexedDB (decompressed).
+     */
+    getSessionHistory(): Promise<UiBlackboxSession[]>;
+    /**
+     * Retrieve sessions for the current device fingerprint.
+     */
+    getSessionsForDevice(): Promise<UiBlackboxSession[]>;
+    /**
+     * Export all sessions as a downloadable JSONL Blob.
+     *
+     * @returns A Blob containing JSONL data (one session per line).
+     *
+     * @example
+     * ```typescript
+     * const blob = await blackbox.exportSessions();
+     * const url = URL.createObjectURL(blob);
+     * const a = document.createElement('a');
+     * a.href = url;
+     * a.download = 'blackbox-sessions.jsonl';
+     * a.click();
+     * ```
+     */
+    exportSessions(): Promise<Blob>;
+    /**
+     * Explicitly end the current session.
+     * Flushes all buffered events and marks the session as ended.
+     */
+    endSession(): Promise<void>;
+    /**
+     * Clear all stored sessions from IndexedDB.
+     */
+    clearHistory(): Promise<void>;
+    /**
+     * Push an event into the centralised buffer.
+     * Triggers an immediate flush if the buffer exceeds the threshold.
+     * @internal
+     */
+    private pushBufferEvent;
+    /**
+     * Flush buffered events to IndexedDB asynchronously.
+     * @internal
+     */
+    private flush;
+    /** Generate a UUID v4. */
+    private generateUuid;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiBlackboxService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiBlackboxService>;
+}