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

package/http/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>;
+}

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

@@ -0,0 +1,238 @@
+/**
+ * @module ng-ui-system/blackbox
+ * Types and interfaces for the BlackBox observability service.
+ *
+ * The BlackBox service acts as a "black box recorder" for user sessions,
+ * capturing navigation, UI interactions, form events and HTTP calls
+ * in a compressed, opaque format stored in IndexedDB.
+ */
+/**
+ * Form tracking granularity flags.
+ *
+ * Controls which form events are captured by the BlackBox service.
+ * All flags default to `true` except `trackValues` which defaults to `false`
+ * for privacy reasons.
+ */
+export interface UiBlackboxFormTrackingConfig {
+    /**
+     * When `true`, the actual field values are stored in form events.
+     * When `false`, only the fact that a change occurred is recorded.
+     * @default false
+     */
+    trackValues: boolean;
+    /** Track focus events on form fields. @default true */
+    trackFocus: boolean;
+    /** Track blur events on form fields. @default true */
+    trackBlur: boolean;
+    /** Track value change events on form fields. @default true */
+    trackValueChanges: boolean;
+    /** Track validation error events on form fields. @default true */
+    trackValidation: boolean;
+    /**
+     * Debounce interval (ms) for `valueChanges` subscriptions.
+     * Higher values reduce noise but increase latency.
+     * @default 500
+     */
+    debounceMs: number;
+}
+/**
+ * Root configuration for the BlackBox service.
+ *
+ * All properties are optional — sensible defaults are applied when omitted.
+ *
+ * @example
+ * ```typescript
+ * blackboxService.configure({
+ *   maxStorageMb: 30,
+ *   formTracking: { trackValues: true, debounceMs: 1000 },
+ * });
+ * ```
+ */
+export interface UiBlackboxConfig {
+    /**
+     * Maximum IndexedDB storage quota in megabytes.
+     * Oldest sessions are pruned when the quota is exceeded.
+     * @default 50
+     */
+    maxStorageMb: number;
+    /**
+     * Interval (ms) at which the in-memory buffer is flushed to IndexedDB.
+     * @default 5000
+     */
+    flushIntervalMs: number;
+    /**
+     * Number of buffered events that trigger an immediate flush.
+     * @default 20
+     */
+    flushThreshold: number;
+    /**
+     * Centralised debounce (ms) applied to the event buffer.
+     * @default 500
+     */
+    bufferDebounceMs: number;
+    /** Per-field form tracking configuration. */
+    formTracking: UiBlackboxFormTrackingConfig;
+}
+/**
+ * Stable device/browser fingerprint generated by FingerprintJS (open-source).
+ * Persists across sessions and incognito mode.
+ */
+export type UiBlackboxFingerprint = string;
+/**
+ * A single recording session, corresponding to one browser tab lifecycle.
+ *
+ * Sessions are associated to a stable `fingerprint` so that multiple
+ * sessions from the same device can be grouped together.
+ */
+export interface UiBlackboxSession {
+    /** Unique session identifier (UUID v4). */
+    sessionId: string;
+    /** Stable device/browser fingerprint. */
+    fingerprint: UiBlackboxFingerprint;
+    /** Timestamp (ms since epoch) when the session started. */
+    startedAt: number;
+    /** Timestamp (ms since epoch) when the session ended (tab closed). */
+    endedAt?: number;
+    /** Raw `navigator.userAgent` string captured at session start. */
+    userAgent: string;
+    /**
+     * Ordered list of navigation steps (route changes).
+     * Each step contains the actions performed on that page.
+     */
+    steps: UiBlackboxStep[];
+    /**
+     * Parallel stream of form interaction events.
+     * Ordered by timestamp, correlated to routes via `route` field.
+     */
+    formEvents: UiBlackboxFormEvent[];
+    /**
+     * Intercepted HTTP calls, ordered by timestamp.
+     * Only requests explicitly marked with the `X-Ui-Blackbox` header.
+     */
+    calls: UiBlackboxHttpCall[];
+}
+/**
+ * A single navigation step created on every `NavigationEnd` event.
+ * Contains all UI actions performed during this route.
+ */
+export interface UiBlackboxStep {
+    /** Timestamp (ms) of the navigation event. */
+    timestamp: number;
+    /** The route URL navigated to. */
+    route: string;
+    /** The previous route URL (undefined for the first step). */
+    previousRoute?: string;
+    /**
+     * Ordered list of UI actions (clicks) performed on this page.
+     */
+    actions: UiBlackboxAction[];
+}
+/**
+ * A single tracked UI action, typically a click.
+ */
+export interface UiBlackboxAction {
+    /** Timestamp (ms) of the action. */
+    timestamp: number;
+    /** Type discriminator. Currently only `click` is supported. */
+    type: 'click';
+    /** Information about the clicked element. */
+    target: UiBlackboxActionTarget;
+}
+/**
+ * Minimal information about the element that was interacted with.
+ */
+export interface UiBlackboxActionTarget {
+    /** HTML tag name (lowercase). */
+    tag: string;
+    /** Element `id` attribute, if present. */
+    id?: string;
+    /**
+     * Custom tracking identifier, set via `data-track-id` attribute
+     * or the `[uiTrack]` directive value.
+     */
+    trackId?: string;
+    /** First 50 characters of `innerText` (trimmed). */
+    text?: string;
+}
+/** Discriminator for form event types. */
+export type UiBlackboxFormEventType = 'focus' | 'blur' | 'valueChange' | 'validationError';
+/**
+ * A single form interaction event from the parallel form stream.
+ *
+ * Each event is timestamped and tagged with the current route, allowing
+ * correlation with navigation steps on a shared timeline.
+ */
+export interface UiBlackboxFormEvent {
+    /** Timestamp (ms) of the event. */
+    timestamp: number;
+    /** Route URL where the event occurred. */
+    route: string;
+    /** Schema `id` of the `UiFormBuilderComponent` that owns the field. */
+    formId: string;
+    /** `key` of the field descriptor from the form schema. */
+    fieldKey: string;
+    /** Type of form interaction. */
+    eventType: UiBlackboxFormEventType;
+    /** Optional metadata depending on event type and config. */
+    metadata?: UiBlackboxFormEventMetadata;
+}
+/**
+ * Optional metadata attached to a `UiBlackboxFormEvent`.
+ */
+export interface UiBlackboxFormEventMetadata {
+    /** Field value (only captured when `config.formTracking.trackValues` is `true`). */
+    value?: any;
+    /** Whether the field is currently valid. */
+    valid?: boolean;
+    /** List of active validation error keys. */
+    errors?: string[];
+    /**
+     * Full form values snapshot at the moment of the event.
+     * Only captured when `config.formTracking.trackValues` is `true`.
+     */
+    formValues?: Record<string, any>;
+}
+/**
+ * A single intercepted HTTP call.
+ *
+ * Only requests bearing the `X-Ui-Blackbox` header are captured.
+ */
+export interface UiBlackboxHttpCall {
+    /** Timestamp (ms) when the request was initiated. */
+    timestamp: number;
+    /** HTTP method (GET, POST, PUT, DELETE, …). */
+    method: string;
+    /** Request URL. */
+    url: string;
+    /** HTTP status code of the response (undefined if the request failed). */
+    status?: number;
+    /** Round-trip duration in milliseconds. */
+    durationMs?: number;
+    /** Request body payload (serialisable). */
+    requestPayload?: any;
+    /** Response headers filtered by the `X-Ui-Blackbox-Headers` regex. */
+    responseHeaders?: Record<string, string>;
+    /** The regex pattern used to filter response headers. */
+    headerFilter?: string;
+}
+/**
+ * Union type for all events flowing through the centralised buffer.
+ * @internal
+ */
+export type UiBlackboxBufferEvent = {
+    kind: 'action';
+    payload: UiBlackboxAction & {
+        route: string;
+    };
+} | {
+    kind: 'formEvent';
+    payload: UiBlackboxFormEvent;
+} | {
+    kind: 'httpCall';
+    payload: UiBlackboxHttpCall;
+} | {
+    kind: 'step';
+    payload: UiBlackboxStep;
+};
+/** Default configuration values. */
+export declare const UI_BLACKBOX_DEFAULTS: UiBlackboxConfig;

package/http/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/http/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/http/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/http/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>;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * ng-ui-system — HTTP Orchestration Service entry point.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UiHttpService,
+ *   UiHttpMessageHandler,
+ *   UI_HTTP_CONFIG,
+ *   UI_HEADERS_PROVIDER,
+ * } from '@gnggln/ng-ui-system';
+ * ```
+ */
+export { UiHttpService } from './http.service';
+export { UiHttpMessageHandler } from './http-message.handler';
+export { UI_HTTP_CONFIG, UI_HEADERS_PROVIDER } from './http.tokens';
+export type { UiHttpConfig, UiHeadersProvider } from './http.types';