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

package/base-layout/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/base-layout/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/base-layout/lib/components/button/button-area.component.d.ts

@@ -0,0 +1,93 @@
+import { UiSize } from '../../core/types';
+import { UiButtonDescriptor, UiButtonAreaAlign } from './button.types';
+import * as i0 from "@angular/core";
+/**
+ * Standalone button-group component driven by a `UiButtonDescriptor[]` configuration.
+ *
+ * Renders a group of `UiButton` instances from declarative descriptors.
+ * Supports per-button loading/disabled states, dynamic visibility,
+ * alignment control, and optional navigation via Angular Router.
+ *
+ * When the `UiBlackboxService` is provided, button clicks are
+ * automatically tracked in the active session.
+ *
+ * @selector ui-button-area
+ *
+ * @example
+ * ```html
+ * <ui-button-area
+ *   [buttons]="actions"
+ *   align="end"
+ *   gap="sm"
+ *   [loadingIds]="currentlyLoading"
+ * />
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dynamic configuration
+ * actions: UiButtonDescriptor[] = [
+ *   { id: 'export', label: 'Export Excel', icon: 'file-spreadsheet', variant: 'primary',
+ *     action: () => this.exportExcel() },
+ *   { id: 'delete', label: 'Delete', icon: 'trash-2', variant: 'warn',
+ *     action: () => this.deleteSelected(), hidden: !this.hasSelection },
+ * ];
+ *
+ * // Set loading state from outside:
+ * currentlyLoading: string | string[] | null = 'export';
+ * ```
+ */
+export declare class UiButtonAreaComponent {
+    /**
+     * Array of button descriptors to render.
+     * Buttons with `hidden: true` are filtered out.
+     */
+    buttons: UiButtonDescriptor[];
+    /** Horizontal alignment of the button group. */
+    align: UiButtonAreaAlign;
+    /** Accessible group label for screen readers. */
+    ariaLabel: string;
+    /** Gap between buttons (maps to design token spacing). */
+    gap: UiSize;
+    /** Stack buttons vertically on mobile viewports (<600px). */
+    stackOnMobile: boolean;
+    /**
+     * When `true`, all buttons are disabled while any button is in a loading state.
+     * Useful to prevent double-actions during async operations.
+     */
+    disableWhileLoading: boolean;
+    /**
+     * Set one or more buttons to a loading state by their `id`.
+     * Accepts a single string, an array of strings, or `null` to clear.
+     *
+     * @example
+     * ```html
+     * <!-- Single -->
+     * <ui-button-area [loadingIds]="'save'" />
+     *
+     * <!-- Multiple -->
+     * <ui-button-area [loadingIds]="['save', 'export']" />
+     * ```
+     */
+    set loadingIds(value: string | string[] | null | undefined);
+    /** @internal */
+    private _loadingIds;
+    /** @internal Optional router for href navigation. */
+    private router;
+    /** @internal Optional BlackBox service — auto-tracks button clicks when available. */
+    private blackbox;
+    /** Buttons filtered to visible (non-hidden) entries. */
+    get visibleButtons(): UiButtonDescriptor[];
+    /** Assembled CSS class string for the button area container. */
+    get areaClasses(): string;
+    /** @internal Track function for @for loop. */
+    trackButton(index: number, button: UiButtonDescriptor): string;
+    /** Whether a specific button is in a loading state. */
+    isButtonLoading(button: UiButtonDescriptor): boolean;
+    /** Whether a specific button is disabled (includes loading logic). */
+    isButtonDisabled(button: UiButtonDescriptor): boolean;
+    /** @internal Handles button click: tracks action, calls callback and/or navigates. */
+    handleButtonClick(button: UiButtonDescriptor, event: MouseEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiButtonAreaComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiButtonAreaComponent, "ui-button-area", never, { "buttons": { "alias": "buttons"; "required": false; }; "align": { "alias": "align"; "required": false; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; }; "gap": { "alias": "gap"; "required": false; }; "stackOnMobile": { "alias": "stackOnMobile"; "required": false; }; "disableWhileLoading": { "alias": "disableWhileLoading"; "required": false; }; "loadingIds": { "alias": "loadingIds"; "required": false; }; }, {}, never, never, true, never>;
+}

package/base-layout/lib/components/button/button.component.d.ts

@@ -0,0 +1,61 @@
+import { UiVariant, UiSize, UiIconName } from '../../core/types';
+import { UiIconPosition } from './button.types';
+import * as i0 from "@angular/core";
+/**
+ * Standalone button component with design-token-driven theming,
+ * variant/size system, Lucide icon support, loading states, and WCAG 2.1 AA accessibility.
+ *
+ * Uses native `<button>` click events — listen with `(click)` on the host element.
+ *
+ * @selector ui-button
+ *
+ * @example
+ * ```html
+ * <!-- Basic -->
+ * <ui-button label="Save" variant="primary" icon="save" (click)="save()" />
+ *
+ * <!-- Loading -->
+ * <ui-button label="Submitting..." variant="primary" [loading]="true" />
+ *
+ * <!-- Icon-only: tooltip o ariaLabel forniscono il nome accessibile -->
+ * <ui-button icon="trash-2" variant="warn" tooltip="Elimina" (click)="delete()" />
+ * ```
+ */
+export declare class UiButtonComponent {
+    /** Button label text. */
+    label: string;
+    /** Tooltip text shown on hover (uses Angular Material tooltip). */
+    tooltip: string;
+    /** Visual style variant. */
+    variant: UiVariant;
+    /** Size variant. */
+    size: UiSize;
+    /** Lucide icon name. @see https://lucide.dev/icons */
+    icon?: UiIconName;
+    /** Icon position relative to the label. */
+    iconPosition: UiIconPosition;
+    /** Whether the button is in a loading state. Disables interaction and shows spinner. */
+    loading: boolean;
+    /** Whether the button is disabled. */
+    disabled: boolean;
+    /** Expand button to full container width. */
+    fullWidth: boolean;
+    /** HTML button type attribute. */
+    type: 'button' | 'submit' | 'reset';
+    /** Accessible label override (required for icon-only buttons). */
+    ariaLabel?: string;
+    /** Additional CSS class for edge cases. */
+    customClass?: string;
+    /**
+     * Nome accessibile risolto per il pulsante nativo.
+     * Usa `ariaLabel` se impostato; per pulsanti solo icona senza testo visibile
+     * ricade sul `tooltip` (il tooltip Material non sostituisce il nome accessibile).
+     */
+    get effectiveAriaLabel(): string | undefined;
+    /** Computed icon pixel size based on button size. */
+    get iconSize(): number;
+    /** Assembled CSS class string for the native button element. */
+    get buttonClasses(): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiButtonComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiButtonComponent, "ui-button", never, { "label": { "alias": "label"; "required": false; }; "tooltip": { "alias": "tooltip"; "required": false; }; "variant": { "alias": "variant"; "required": false; }; "size": { "alias": "size"; "required": false; }; "icon": { "alias": "icon"; "required": false; }; "iconPosition": { "alias": "iconPosition"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "fullWidth": { "alias": "fullWidth"; "required": false; }; "type": { "alias": "type"; "required": false; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; }; "customClass": { "alias": "customClass"; "required": false; }; }, {}, never, ["*"], true, never>;
+}

package/base-layout/lib/components/button/button.types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module ng-ui-system/button
+ * Types and interfaces for UiButton and UiButtonArea components.
+ */
+import { UiVariant, UiSize, UiIconName } from '../../core/types';
+export { UiVariant, UiSize, UiIconName };
+/**
+ * Position of the icon relative to the button label.
+ */
+export type UiIconPosition = 'leading' | 'trailing';
+/**
+ * Descriptor for declarative button configuration in UiButtonArea.
+ *
+ * Allows defining button groups as data structures, enabling
+ * dynamic UI updates through configuration manipulation.
+ *
+ * @usageNotes
+ *
+ * ### Basic usage
+ * ```typescript
+ * const actions: UiButtonDescriptor[] = [
+ *   { id: 'save', label: 'Save', variant: 'primary', icon: 'save', action: () => this.save() },
+ *   { id: 'cancel', label: 'Cancel', variant: 'outline', action: () => this.cancel() },
+ * ];
+ * ```
+ *
+ * ### Dynamic loading state
+ * ```typescript
+ * // Toggle loading on a specific button by mutating the descriptor:
+ * this.actions[0].loading = true;
+ *
+ * // Or use loadingIds on the button area:
+ * this.currentLoadingIds = ['save'];
+ * ```
+ */
+export interface UiButtonDescriptor {
+    /** Unique identifier for programmatic state control (loading, disabled). */
+    id?: string;
+    /** Button label text. */
+    label: string;
+    /** Tooltip text shown on hover. */
+    tooltip?: string;
+    /**
+     * Nome accessibile esplicito (override).
+     * Per pulsanti solo icona senza `label`, se omesso si usa `tooltip` come `aria-label`.
+     */
+    ariaLabel?: string;
+    /**
+     * Click handler. Supports both sync and async callbacks.
+     * Receives the native MouseEvent as argument.
+     */
+    action?: (event?: MouseEvent) => void | Promise<void>;
+    /** Lucide icon name. @see https://lucide.dev/icons */
+    icon?: UiIconName;
+    /** Icon position relative to the label. @default 'trailing' */
+    iconPosition?: UiIconPosition;
+    /** Visual variant. @default 'primary' */
+    variant?: UiVariant;
+    /** Size variant. @default 'md' */
+    size?: UiSize;
+    /** Navigation URL (Angular Router navigateByUrl). */
+    href?: string;
+    /** Whether this button is in a loading state. */
+    loading?: boolean;
+    /** Whether this button is disabled. */
+    disabled?: boolean;
+    /** Whether this button is hidden from the UI. */
+    hidden?: boolean;
+    /** Additional CSS class for edge cases. */
+    customClass?: string;
+}
+/**
+ * Alignment options for UiButtonArea.
+ */
+export type UiButtonAreaAlign = 'start' | 'center' | 'end' | 'between';