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

package/page-header/lib/components/page-header/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ng-ui-system — Page Header entry point.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UiPageHeaderComponent,
+ *   UiBreadcrumbService,
+ *   UiBreadcrumbItem,
+ *   UI_BREADCRUMB_LABEL_RESOLVER,
+ * } from 'ng-ui-system';
+ * ```
+ */
+export { UiPageHeaderComponent } from './page-header.component';
+export { UiBreadcrumbService } from './breadcrumb.service';
+export { UiBreadcrumbItem, UiBreadcrumbConfig, UiLabelResolverFn, UI_BREADCRUMB_LABEL_RESOLVER, } from './page-header.types';

package/page-header/lib/components/page-header/page-header.component.d.ts

@@ -0,0 +1,59 @@
+import { OnInit } from '@angular/core';
+import { UiBreadcrumbItem } from './page-header.types';
+import * as i0 from "@angular/core";
+/**
+ * Page header component that renders a breadcrumb navigation trail
+ * and a page title. Integrates with `UiBreadcrumbService` to
+ * automatically derive breadcrumbs from Angular route configuration.
+ *
+ * The breadcrumb trail is generated from route `data` properties:
+ * - `data.id` — unique route identifier
+ * - `data.title` — display label
+ * - `data.breadcrumbs` — ordered array of parent route IDs
+ *
+ * @selector ui-page-header
+ *
+ * @example
+ * ```html
+ * <!-- Auto breadcrumbs from route data -->
+ * <ui-page-header />
+ *
+ * <!-- With explicit title override -->
+ * <ui-page-header title="Custom Title" />
+ *
+ * <!-- With document title update -->
+ * <ui-page-header [updateDocumentTitle]="true" titleSuffix=" | My App" />
+ * ```
+ */
+export declare class UiPageHeaderComponent implements OnInit {
+    /** Override the auto-detected page title. When empty, title is derived from the last breadcrumb. */
+    title: string;
+    /** Route path for the Home breadcrumb link. */
+    homeRoute: string;
+    /** Whether to display the Home link at the start of the trail. */
+    showHome: boolean;
+    /** When `true`, updates `document.title` on each navigation. */
+    updateDocumentTitle: boolean;
+    /** Suffix appended to `document.title` (e.g. `' | My App'`). Only used when `updateDocumentTitle` is `true`. */
+    titleSuffix: string;
+    /** @internal */
+    breadcrumbs: UiBreadcrumbItem[];
+    private readonly router;
+    private readonly activatedRoute;
+    private readonly titleService;
+    private readonly breadcrumbService;
+    private readonly destroyRef;
+    private readonly cdr;
+    /** Resolved page title: explicit `title` input wins, otherwise last breadcrumb label. */
+    get displayTitle(): string;
+    ngOnInit(): void;
+    /**
+     * Navigates to the previous breadcrumb (parent route).
+     * @param fallbackUrl - URL to navigate to when no parent exists (default: homeRoute).
+     */
+    navigateBack(fallbackUrl?: string): void;
+    /** @internal */
+    private refresh;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiPageHeaderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiPageHeaderComponent, "ui-page-header", never, { "title": { "alias": "title"; "required": false; }; "homeRoute": { "alias": "homeRoute"; "required": false; }; "showHome": { "alias": "showHome"; "required": false; }; "updateDocumentTitle": { "alias": "updateDocumentTitle"; "required": false; }; "titleSuffix": { "alias": "titleSuffix"; "required": false; }; }, {}, never, never, true, never>;
+}

package/page-header/lib/components/page-header/page-header.types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @module ng-ui-system/page-header
+ * Types and interfaces for UiPageHeader and UiBreadcrumbService.
+ */
+import { InjectionToken } from '@angular/core';
+/**
+ * Single breadcrumb item rendered in the navigation trail.
+ *
+ * @usageNotes
+ * ### Structure
+ * ```typescript
+ * const item: UiBreadcrumbItem = {
+ *   label: 'Dashboard',
+ *   url: '/dashboard',
+ *   isLast: false,
+ * };
+ * ```
+ */
+export interface UiBreadcrumbItem {
+    /** Display text for the breadcrumb link. */
+    label: string;
+    /** Navigation URL (Angular Router path). */
+    url: string;
+    /** Whether this is the last (current) breadcrumb in the trail. */
+    isLast: boolean;
+}
+/**
+ * Internal route configuration stored by UiBreadcrumbService.
+ * Built from Angular route `data` properties.
+ *
+ * @usageNotes
+ * ### Route data convention
+ * ```typescript
+ * {
+ *   path: 'users/:userId',
+ *   data: {
+ *     id: 'user-detail',
+ *     title: 'Dettaglio utente',
+ *     breadcrumbs: ['users-list'],
+ *   },
+ *   component: UserDetailComponent,
+ * }
+ * ```
+ */
+export interface UiBreadcrumbConfig {
+    /** Unique route identifier (from `route.data.id`). */
+    id: string;
+    /** Resolved route path pattern (may contain `:param` placeholders). */
+    path: string;
+    /** Display label (from `route.data.title` or fallback). */
+    label: string;
+    /** Ordered array of parent route IDs for building the breadcrumb chain. */
+    parentIds: string[];
+    /** Fully resolved URL captured at navigation time. */
+    fullPath?: string;
+    /** Raw route data metadata. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Function signature for resolving route parameter values to human-readable labels.
+ *
+ * Consumers can provide a custom implementation via `UI_BREADCRUMB_LABEL_RESOLVER`
+ * to translate cryptic parameter values (e.g. UUIDs, slugs) into user-friendly text.
+ *
+ * @param paramName - The route parameter name (e.g. `'userId'`).
+ * @param paramValue - The raw parameter value from the URL (e.g. `'abc-123'`).
+ * @returns A human-readable label, or the original value if no mapping exists.
+ *
+ * @usageNotes
+ * ### Custom resolver
+ * ```typescript
+ * const myResolver: UiLabelResolverFn = (name, value) => {
+ *   if (name === 'status') {
+ *     return { pending: 'In attesa', active: 'Attivo' }[value] ?? value;
+ *   }
+ *   return value;
+ * };
+ *
+ * providers: [
+ *   { provide: UI_BREADCRUMB_LABEL_RESOLVER, useValue: myResolver },
+ * ]
+ * ```
+ */
+export type UiLabelResolverFn = (paramName: string, paramValue: string) => string;
+/**
+ * Injection token for providing a custom label resolver to UiBreadcrumbService.
+ *
+ * When not provided, parameters are displayed as-is (identity function).
+ *
+ * @example
+ * ```typescript
+ * // In your app.config.ts or module providers:
+ * { provide: UI_BREADCRUMB_LABEL_RESOLVER, useValue: myLabelResolver }
+ * ```
+ */
+export declare const UI_BREADCRUMB_LABEL_RESOLVER: InjectionToken<UiLabelResolverFn>;

package/public-api.d.ts

@@ -1,15 +1,17 @@
 /**
- * ng-ui-system - Public API Surface
+ * ng-ui-system - API pubblica (entry principale).
  *
- * Main entry point that re-exports all secondary entry points.
- * For optimal tree-shaking, prefer importing from specific entry points:
- *   import { UiButtonComponent } from 'ng-ui-system/button';
+ * Re-esporta tutti i moduli della libreria. Gli stessi simboli sono disponibili anche dai
+ * secondary entry point (es. `@gnggln/ng-ui-system/button`) per un tree-shaking più efficace.
  *
- * For convenience, you can also import from the main entry point:
- *   import { UiButtonComponent } from 'ng-ui-system';
+ * Retrocompatibilità: `import { … } from '@gnggln/ng-ui-system'` resta supportato.
+ * Per nuovi progetti o import mirati: `import { … } from '@gnggln/ng-ui-system/<modulo>'`.
+ * Elenco subpath: vedi la guida «Import e entry point» in ng-docs.
  */
+export { NG_UI_SYSTEM_VERSION, ngUiSystemVersionLabel } from './lib/version/ng-ui-system-version';
 export * from './lib/core/types/index';
 export * from './lib/core/utils/index';
+export * from './lib/core/logging/index';
 export * from './lib/components/button/index';
 export * from './lib/components/accordion/index';
 export * from './lib/components/modal/index';
@@ -20,3 +22,6 @@ export * from './lib/components/page-header/index';
 export * from './lib/components/base-layout/index';
 export * from './lib/components/form-builder-editor/index';
 export * from './lib/components/layout-builder/index';
+export * from './lib/components/blackbox/index';
+export * from './lib/components/toast/index';
+export * from './lib/components/http/index';

package/table/entry-table.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Bootstrap del secondary entry `@gnggln/ng-ui-system/table`. Tabella paginata.
+ */
+export * from './lib/components/table/index';

package/table/index.d.ts

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

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

@@ -0,0 +1,2 @@
+export { UiPaginatedTableComponent } from './paginated-table.component';
+export { UiTableColumn, UiTableSortEvent, UiTablePageEvent, } from './table.types';

package/table/lib/components/table/paginated-table.component.d.ts

@@ -0,0 +1,85 @@
+import { EventEmitter, TemplateRef } from '@angular/core';
+import { PageEvent } from '@angular/material/paginator';
+import { UiTableColumn, UiTableSortEvent, UiTablePageEvent } from './table.types';
+import * as i0 from "@angular/core";
+/**
+ * Tabella paginata standalone con ordinamento, colonne sticky,
+ * ellipsis automatica, stato di caricamento e template personalizzabili.
+ *
+ * Progettata per paginazione server-side: emette eventi di cambio pagina
+ * e ordinamento che il componente genitore gestisce per il recupero dati.
+ *
+ * @selector ui-paginated-table
+ *
+ * @example
+ * ```html
+ * <ui-paginated-table
+ *   [data]="users"
+ *   [columns]="columns"
+ *   [totalItems]="totalUsers"
+ *   [pageSize]="10"
+ *   [loading]="isLoading"
+ *   (pageChange)="onPageChange($event)"
+ *   (sortChange)="onSort($event)"
+ *   (rowClick)="onUserClick($event)"
+ * />
+ * ```
+ */
+export declare class UiPaginatedTableComponent {
+    /** @internal Identificatore univoco per l'istanza. */
+    readonly tableId: string;
+    /** Array di righe da visualizzare nella pagina corrente. */
+    data: Record<string, any>[];
+    /** Definizione delle colonne della tabella. */
+    columns: UiTableColumn[];
+    /** Numero totale di elementi (per la paginazione server-side). */
+    totalItems: number;
+    /** Numero di righe per pagina. */
+    pageSize: number;
+    /** Opzioni selezionabili per il numero di righe per pagina. */
+    pageSizeOptions: number[];
+    /** Indice della pagina corrente (0-based). */
+    pageIndex: number;
+    /** Mostra il paginatore sotto la tabella. */
+    showPaginator: boolean;
+    /** Mostra l'overlay di caricamento sopra la tabella. */
+    loading: boolean;
+    /** Messaggio visualizzato quando non ci sono dati. */
+    emptyMessage: string;
+    /** Template personalizzato per lo stato vuoto. */
+    emptyTemplate: TemplateRef<unknown> | null;
+    /** Emesso quando l'utente cambia pagina o numero di righe. */
+    pageChange: EventEmitter<UiTablePageEvent>;
+    /** Emesso quando l'utente ordina una colonna. */
+    sortChange: EventEmitter<UiTableSortEvent>;
+    /** Emesso quando l'utente clicca su una riga. */
+    rowClick: EventEmitter<Record<string, any>>;
+    /** @internal Colonna attualmente ordinata. */
+    currentSortColumn: string | null;
+    /** @internal Direzione ordinamento corrente. */
+    currentSortDirection: 'asc' | 'desc' | null;
+    /** @internal Gestisce il click su un'intestazione di colonna. */
+    onHeaderClick(col: UiTableColumn): void;
+    /** @internal Indica se la colonna e attualmente ordinata. */
+    isColumnSorted(col: UiTableColumn): boolean;
+    /** @internal Attributo aria-sort per accessibilita. */
+    getAriaSort(col: UiTableColumn): string | null;
+    /** @internal Gestisce il cambio pagina dal MatPaginator. */
+    onPageChange(event: PageEvent): void;
+    /** @internal Gestisce il click su una riga. */
+    onRowClick(row: Record<string, any>): void;
+    /** @internal Track function per il loop @for sulle righe. */
+    trackRow(index: number, row: Record<string, any>): unknown;
+    /** @internal Verifica se il testo deve essere troncato. */
+    shouldTruncate(value: unknown, col: UiTableColumn): boolean;
+    /** @internal Tronca il testo con ellipsis. */
+    truncateText(value: unknown, col: UiTableColumn): string;
+    /** @internal Classi CSS per l'header di colonna. */
+    getHeaderClasses(col: UiTableColumn): string;
+    /** @internal Classi CSS per una cella. */
+    getCellClasses(col: UiTableColumn): string;
+    /** @internal Calcola la prossima direzione nel ciclo asc -> desc -> null. */
+    private nextSortDirection;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiPaginatedTableComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiPaginatedTableComponent, "ui-paginated-table", never, { "data": { "alias": "data"; "required": false; }; "columns": { "alias": "columns"; "required": false; }; "totalItems": { "alias": "totalItems"; "required": false; }; "pageSize": { "alias": "pageSize"; "required": false; }; "pageSizeOptions": { "alias": "pageSizeOptions"; "required": false; }; "pageIndex": { "alias": "pageIndex"; "required": false; }; "showPaginator": { "alias": "showPaginator"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; }; "emptyTemplate": { "alias": "emptyTemplate"; "required": false; }; }, { "pageChange": "pageChange"; "sortChange": "sortChange"; "rowClick": "rowClick"; }, never, never, true, never>;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * @module ng-ui-system/table
+ * Tipi e interfacce per UiPaginatedTable.
+ */
+import { TemplateRef } from '@angular/core';
+/**
+ * Definizione di una colonna della tabella.
+ *
+ * @usageNotes
+ * ### Colonna testuale semplice
+ * ```typescript
+ * const col: UiTableColumn = {
+ *   property: 'name',
+ *   header: 'Nome',
+ *   sortable: true,
+ * };
+ * ```
+ *
+ * ### Colonna con template personalizzato
+ * ```typescript
+ * const col: UiTableColumn = {
+ *   property: 'status',
+ *   header: 'Stato',
+ *   template: statusTemplate,
+ * };
+ * ```
+ */
+export interface UiTableColumn {
+    /** Chiave della proprieta nell'oggetto riga. */
+    property: string;
+    /** Testo dell'intestazione della colonna. */
+    header: string;
+    /**
+     * Template personalizzato per la cella.
+     * Il contesto fornisce `$implicit` (riga) e `column` (definizione colonna).
+     *
+     * @example
+     * ```html
+     * <ng-template #statusTpl let-row>
+     *   <span [class]="'badge--' + row.status">{{ row.status }}</span>
+     * </ng-template>
+     * ```
+     */
+    template?: TemplateRef<unknown>;
+    /**
+     * Template personalizzato per l'intestazione.
+     * Il contesto fornisce: `$implicit` (colonna) e `column` (definizione colonna).
+     */
+    headerTemplate?: TemplateRef<unknown>;
+    /** Rende la colonna ordinabile con click sull'header. @default false */
+    sortable?: boolean;
+    /** Tipo di ordinamento per la logica client-side. @default 'text' */
+    sortType?: 'text' | 'number' | 'date';
+    /** Fissa la colonna a destra durante lo scroll orizzontale. @default false */
+    sticky?: boolean;
+    /** Tronca il testo oltre maxLength caratteri con ellipsis e tooltip. @default false */
+    ellipsis?: boolean;
+    /** Lunghezza massima del testo prima dell'ellipsis. @default 50 */
+    maxLength?: number;
+    /** Larghezza CSS personalizzata della colonna (es. '120px', '20%'). */
+    width?: string;
+    /** Allineamento del testo nella colonna. @default 'left' */
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * Evento di ordinamento emesso quando l'utente clicca su un'intestazione ordinabile.
+ */
+export interface UiTableSortEvent {
+    /** Proprieta della colonna ordinata. */
+    column: string;
+    /** Direzione dell'ordinamento. `null` indica ordinamento rimosso. */
+    direction: 'asc' | 'desc' | null;
+    /** Tipo di ordinamento della colonna. */
+    sortType: 'text' | 'number' | 'date';
+}
+/**
+ * Evento di cambio pagina emesso dal paginatore.
+ */
+export interface UiTablePageEvent {
+    /** Indice della pagina corrente (0-based). */
+    pageIndex: number;
+    /** Numero di righe per pagina. */
+    pageSize: number;
+    /** Numero totale di elementi. */
+    length: number;
+}

package/table/lib/core/utils/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared utility functions for ng-ui-system components.
+ */
+/**
+ * Generates a unique ID with an optional prefix.
+ * Uses crypto.randomUUID() when available for better randomness, falls back to crypto.getRandomValues().
+ * Useful for linking labels to form controls, ARIA attributes, etc.
+ *
+ * @param prefix - Optional prefix for the generated ID.
+ * @returns A unique string ID.
+ */
+export declare function uiUniqueId(prefix?: string): string;
+/**
+ * Coerces a value to a boolean.
+ * Useful for handling string boolean attributes in templates.
+ *
+ * @param value - The value to coerce.
+ * @returns The boolean representation.
+ */
+export declare function uiCoerceBoolean(value: unknown): boolean;
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param value - The value to clamp.
+ * @param min - The minimum allowed value.
+ * @param max - The maximum allowed value.
+ * @returns The clamped value.
+ */
+export declare function uiClamp(value: number, min: number, max: number): number;
+/**
+ * Removes all `null` and `undefined` values from an object.
+ * Returns a new object — the original is not mutated.
+ *
+ * @param obj - The source object.
+ * @returns A shallow copy with nullish entries removed.
+ *
+ * @example
+ * ```typescript
+ * uiFilterNullish({ a: 1, b: null, c: 'x', d: undefined });
+ * // → { a: 1, c: 'x' }
+ * ```
+ */
+export declare function uiFilterNullish<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Converts a key-value object into a URL query string.
+ * Nullish values are filtered out automatically.
+ *
+ * @param params - Query parameter object.
+ * @returns A query string like `?key=value&key2=value2`, or an empty string if no params.
+ *
+ * @example
+ * ```typescript
+ * uiQueryParamsToPath({ search: 'test', page: 1, active: true });
+ * // → '?search=test&page=1&active=true'
+ *
+ * uiQueryParamsToPath(undefined);
+ * // → ''
+ * ```
+ */
+export declare function uiQueryParamsToPath(params?: Record<string, unknown>): string;

package/toast/entry-toast.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Bootstrap del secondary entry `@gnggln/ng-ui-system/toast`. Toast / notifiche.
+ */
+export * from './lib/components/toast/index';

package/toast/index.d.ts

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

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

@@ -0,0 +1,17 @@
+/**
+ * ng-ui-system — Toast Notifications entry point.
+ *
+ * @example
+ * ```typescript
+ * import { UiToastService, UiToastConfig } from '@gnggln/ng-ui-system';
+ *
+ * const toast = inject(UiToastService);
+ * toast.success('Salvato!');
+ * ```
+ */
+export { UiToastService } from './toast.service';
+export { UiToastComponent } from './toast.component';
+export { UiToastContainerComponent } from './toast-container.component';
+export type { UiToastConfig, UiToastRef, UiToastData, } from './toast.types';
+export type { UiToastPosition } from './toast.types';
+export { UI_TOAST_DEFAULTS } from './toast.types';

package/toast/lib/components/toast/toast-container.component.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Toast container — manages stacking and positioning of active toasts.
+ *
+ * Dynamically attached to the DOM by `UiToastService` on first use.
+ * Renders one `ui-toast` per active notification.
+ *
+ * @selector ui-toast-container
+ * @internal Not intended for direct use.
+ */
+import { ChangeDetectorRef } from '@angular/core';
+import type { UiToastData } from './toast.types';
+import * as i0 from "@angular/core";
+export declare class UiToastContainerComponent {
+    readonly cdr: ChangeDetectorRef;
+    /** Active toasts — managed by UiToastService. */
+    toasts: UiToastData[];
+    /** Called by UiToastService to add a toast. */
+    addToast(toast: UiToastData): void;
+    /** Called by UiToastService to remove a toast. */
+    removeToast(id: string): void;
+    /** Update a toast's state (e.g. entering → exiting). */
+    updateToastState(id: string, state: UiToastData['state']): void;
+    /** Dismiss handler from the toast component. */
+    onDismiss(toast: UiToastData): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiToastContainerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiToastContainerComponent, "ui-toast-container", never, {}, {}, never, never, true, never>;
+}

package/toast/lib/components/toast/toast.component.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Individual toast notification element.
+ *
+ * Rendered dynamically by `UiToastContainerComponent`.
+ * Handles its own enter/exit CSS animations and auto-dismiss countdown.
+ *
+ * @selector ui-toast
+ * @internal Not intended for direct use — managed by `UiToastService`.
+ */
+import { EventEmitter, OnInit, OnDestroy } from '@angular/core';
+import type { UiToastType } from '../../core/types/index';
+import * as i0 from "@angular/core";
+export declare class UiToastComponent implements OnInit, OnDestroy {
+    /** Toast message text. */
+    message: string;
+    /** Toast type for styling. */
+    type: UiToastType;
+    /** Animation state. */
+    state: 'entering' | 'visible' | 'exiting';
+    /** Whether the close button is shown. */
+    dismissible: boolean;
+    /** Whether HTML rendering is enabled. */
+    enableHtml: boolean;
+    /** Custom Lucide icon override. */
+    icon?: string;
+    /** Additional CSS class. */
+    customClass?: string;
+    /** Emitted when the user clicks the dismiss button. */
+    dismissed: EventEmitter<void>;
+    private enterTimeout?;
+    /** Resolved icon name based on type. */
+    get resolvedIcon(): string;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiToastComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiToastComponent, "ui-toast", never, { "message": { "alias": "message"; "required": false; }; "type": { "alias": "type"; "required": false; }; "state": { "alias": "state"; "required": false; }; "dismissible": { "alias": "dismissible"; "required": false; }; "enableHtml": { "alias": "enableHtml"; "required": false; }; "icon": { "alias": "icon"; "required": false; }; "customClass": { "alias": "customClass"; "required": false; }; }, { "dismissed": "dismissed"; }, never, never, true, never>;
+}

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

@@ -0,0 +1,39 @@
+import type { UiToastType } from '../../core/types/index';
+import { UiToastConfig, UiToastRef } from './toast.types';
+import * as i0 from "@angular/core";
+/**
+ * Central toast notification service.
+ *
+ * Manages a single `UiToastContainerComponent` in the DOM and provides
+ * convenience methods for showing typed notifications.
+ */
+export declare class UiToastService {
+    private readonly appRef;
+    private readonly injector;
+    private readonly document;
+    /** Reference to the singleton container component. */
+    private containerRef;
+    /** Show a **success** toast. */
+    success(message: string, config?: UiToastConfig): UiToastRef;
+    /** Show an **error** toast. */
+    error(message: string, config?: UiToastConfig): UiToastRef;
+    /** Show a **warning** toast. */
+    warning(message: string, config?: UiToastConfig): UiToastRef;
+    /** Show an **info** toast. */
+    info(message: string, config?: UiToastConfig): UiToastRef;
+    /** Show a toast with explicit type. */
+    show(message: string, type?: UiToastType, config?: UiToastConfig): UiToastRef;
+    /** Dismiss a specific toast by ID. */
+    dismiss(id: string): void;
+    /** Dismiss all active toasts. */
+    dismissAll(): void;
+    /**
+     * Ensures the container component exists in the DOM.
+     * Creates it lazily on first toast call.
+     */
+    private ensureContainer;
+    /** Apply CSS position modifier class to the container element. */
+    private applyPositionClass;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiToastService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiToastService>;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * @module ng-ui-system/toast
+ * Types and interfaces for the proprietary toast notification system.
+ */
+import type { UiToastType } from '../../core/types/index';
+/** Position of the toast container on screen. */
+export type UiToastPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';
+/**
+ * Configuration options for a toast notification.
+ *
+ * @usageNotes
+ * ```typescript
+ * toastService.success('Saved!', { duration: 3000, position: 'bottom-right' });
+ * ```
+ */
+export interface UiToastConfig {
+    /** Toast type (overrides the method-level default). */
+    type?: UiToastType;
+    /** Auto-dismiss duration in milliseconds. `0` = persistent. Default: `5000`. */
+    duration?: number;
+    /** Screen position for this toast. Default: `'top-right'`. */
+    position?: UiToastPosition;
+    /** Whether a close button is shown. Default: `true`. */
+    dismissible?: boolean;
+    /** Allow HTML content in the message. Default: `false`. */
+    enableHtml?: boolean;
+    /** Custom Lucide icon name. Defaults to type-specific icon. */
+    icon?: string;
+    /** Additional CSS class appended to the toast element. */
+    customClass?: string;
+}
+/**
+ * Reference to a live toast instance.
+ * Can be used to dismiss the toast programmatically.
+ */
+export interface UiToastRef {
+    /** Unique identifier for this toast instance. */
+    id: string;
+    /** Dismiss this specific toast. */
+    dismiss: () => void;
+}
+/** @internal Data model for a toast managed by the service. */
+export interface UiToastData {
+    id: string;
+    message: string;
+    type: UiToastType;
+    config: Required<Pick<UiToastConfig, 'duration' | 'position' | 'dismissible' | 'enableHtml'>> & UiToastConfig;
+    state: 'entering' | 'visible' | 'exiting';
+    timeoutId?: ReturnType<typeof setTimeout>;
+}
+/** Defaults applied to every toast unless overridden. */
+export declare const UI_TOAST_DEFAULTS: Required<Pick<UiToastConfig, 'duration' | 'position' | 'dismissible' | 'enableHtml'>>;