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

package/layout-builder/lib/components/layout-builder/layout-builder.types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * @module ng-ui-system/layout-builder
+ * Types and interfaces for the UiLayoutBuilder shell component.
+ *
+ * The layout builder uses a schema-driven approach (similar to UiFormBuilder)
+ * to materialize a full responsive application shell from a single descriptor.
+ */
+import { UiIconName, UiVariant } from '../../core/types/index';
+/** Layout mode controlling the overall navigation strategy. */
+export type UiLayoutMode = 'sidebar' | 'topbar' | 'slotted';
+/** Content area sizing strategy. */
+export type UiContentType = 'fluid' | 'boxed' | 'fullscreen';
+/** Single breadcrumb entry derived from the navigation schema. */
+export interface UiLayoutBreadcrumb {
+    /** Display label. */
+    label: string;
+    /** Route URL (omitted for the current/last crumb). */
+    url?: string;
+    /** Whether this is the last (current) breadcrumb in the trail. */
+    isLast: boolean;
+}
+/** Discriminator for navigation item behaviour. */
+export type UiNavItemType = 'route' | 'external' | 'divider';
+/**
+ * Single navigation item descriptor.
+ *
+ * @usageNotes
+ * ### Internal route
+ * ```typescript
+ * { id: 'users', label: 'Utenti', icon: 'users', route: '/users' }
+ * ```
+ *
+ * ### External link
+ * ```typescript
+ * { id: 'docs', label: 'Docs', icon: 'external-link', type: 'external',
+ *   href: 'https://docs.example.com', target: '_blank' }
+ * ```
+ *
+ * ### Expandable with children
+ * ```typescript
+ * {
+ *   id: 'form-builder', label: 'Form Builder', icon: 'file-text',
+ *   route: '/form-builder',
+ *   children: [
+ *     { label: 'Panoramica', items: [
+ *       { id: 'fb-all', label: 'Tutti i campi', route: '/form-builder/all-fields' }
+ *     ]}
+ *   ]
+ * }
+ * ```
+ */
+export interface UiNavItem {
+    /** Unique item identifier. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Lucide icon name. */
+    icon?: UiIconName;
+    /** Item behaviour type. @default 'route' */
+    type?: UiNavItemType;
+    /** Angular router path (for `type: 'route'`). */
+    route?: string;
+    /** Whether to use exact matching for active state. @default false */
+    routeActiveExact?: boolean;
+    /** External URL (for `type: 'external'`). */
+    href?: string;
+    /** Link target for external links. @default '_blank' */
+    target?: '_blank' | '_self';
+    /** Nested child groups for expandable navigation. */
+    children?: UiNavGroup[];
+    /** Whether this item is hidden. @default false */
+    hidden?: boolean;
+    /** Badge text or count displayed next to the label. */
+    badge?: string | number;
+    /** Whether to include this item in the mobile bottom navigation bar. @default false */
+    bottomNav?: boolean;
+    /** Sort order in the bottom navigation bar (lower = first). */
+    bottomNavOrder?: number;
+}
+/**
+ * Labelled group of navigation items (nested under a parent `UiNavItem`).
+ *
+ * @usageNotes
+ * ```typescript
+ * const group: UiNavGroup = {
+ *   label: 'Validazioni',
+ *   items: [
+ *     { id: 'v-std', label: 'Standard', route: '/form-builder/validations-standard' },
+ *     { id: 'v-cross', label: 'Cross-field', route: '/form-builder/validations-crossfield' },
+ *   ]
+ * };
+ * ```
+ */
+export interface UiNavGroup {
+    /** Group heading displayed above the items. */
+    label: string;
+    /** Items belonging to this group. */
+    items: UiNavItem[];
+}
+/**
+ * Top-level grouping used to partition `UiNavItem[]` into labelled sections
+ * in the sidebar (e.g. "Overview", "Components").
+ */
+export interface UiNavSection {
+    /** Unique section identifier. */
+    id: string;
+    /** Section heading displayed in the sidebar. */
+    label: string;
+    /** IDs of `UiNavItem`s belonging to this section (order preserved). */
+    itemIds: string[];
+}
+/**
+ * Auto-discovery configuration for generating navigation items from Angular routes.
+ *
+ * When enabled, the layout builder scans the route tree and creates
+ * `UiNavItem` entries from routes that declare `data.id` and `data.title`.
+ */
+export interface UiNavAutoDiscoveryConfig {
+    /** Whether auto-discovery is enabled. */
+    enabled: boolean;
+    /** Route paths to exclude from discovery (exact match). */
+    excludePaths?: string[];
+    /** How to merge discovered items with manually defined items. @default 'append' */
+    mergeStrategy?: 'prepend' | 'append' | 'replace';
+}
+/** Navigation configuration block within `UiLayoutSchema`. */
+export interface UiLayoutNavigationConfig {
+    /** Flat list of all navigation items. */
+    items: UiNavItem[];
+    /** Optional grouping into labelled sidebar sections. */
+    sections?: UiNavSection[];
+    /** Whether the desktop sidebar can collapse to icon-only mode. @default true */
+    collapsible?: boolean;
+    /** Mobile navigation behaviour. @default 'both' */
+    mobileMode?: 'drawer' | 'bottom-nav' | 'both';
+    /** Auto-discovery settings for route-driven navigation. */
+    autoDiscovery?: UiNavAutoDiscoveryConfig;
+}
+/** Logo configuration for the layout header. */
+export interface UiLayoutLogo {
+    /** Short text rendered inside a styled badge (e.g. "UI"). Mutually exclusive with `src`. */
+    text?: string;
+    /** Image URL for the logo. Mutually exclusive with `text`. */
+    src?: string;
+    /** Alt text for the logo image. */
+    alt?: string;
+}
+/** Header / top-bar configuration. */
+export interface UiLayoutHeaderConfig {
+    /** Logo displayed in the sidebar header and mobile top-bar. */
+    logo?: UiLayoutLogo;
+    /** Application title. */
+    title: string;
+    /** Optional subtitle or tagline. */
+    subtitle?: string;
+}
+/** Single link rendered in the layout footer. */
+export interface UiFooterLink {
+    /** Display label. */
+    label: string;
+    /** External URL. */
+    href?: string;
+    /** Angular router path (alternative to `href`). */
+    route?: string;
+    /** Lucide icon name. */
+    icon?: UiIconName;
+    /** Link target for external links. @default '_self' */
+    target?: '_blank' | '_self';
+}
+/** Footer configuration. */
+export interface UiLayoutFooterConfig {
+    /** Links rendered in the footer. */
+    links?: UiFooterLink[];
+    /** Static text (e.g. copyright, version). */
+    text?: string;
+}
+/**
+ * Single action within the speed-dial FAB.
+ *
+ * @usageNotes
+ * ```typescript
+ * const action: UiFabAction = {
+ *   id: 'new-user',
+ *   label: 'Nuovo utente',
+ *   icon: 'user',
+ *   variant: 'primary',
+ *   action: () => router.navigate(['/users/new']),
+ * };
+ * ```
+ */
+export interface UiFabAction {
+    /** Unique action identifier. */
+    id: string;
+    /** Tooltip / label text. */
+    label: string;
+    /** Lucide icon name. */
+    icon: UiIconName;
+    /** Callback invoked on click. */
+    action?: () => void;
+    /** Visual variant for the button. @default 'primary' */
+    variant?: UiVariant;
+    /** Accessible label (falls back to `label` if omitted). */
+    ariaLabel?: string;
+}
+/** Speed-dial FAB configuration. */
+export interface UiLayoutFabConfig {
+    /** Primary FAB action (always visible). */
+    mainAction: UiFabAction;
+    /** Secondary actions revealed on expand. */
+    secondaryActions?: UiFabAction[];
+    /** Screen corner position. @default 'bottom-right' */
+    position?: 'bottom-right' | 'bottom-left';
+}
+/** Default page-header settings applied to every route unless overridden. */
+export interface UiLayoutPageHeaderConfig {
+    /** Whether to show the page header (breadcrumbs + title). @default true */
+    show?: boolean;
+    /** Home breadcrumb route path. @default '/' */
+    homeRoute?: string;
+    /** Whether to show the Home link in breadcrumbs. @default true */
+    showHome?: boolean;
+    /** Whether to sync `document.title` with the current page. @default false */
+    updateDocumentTitle?: boolean;
+    /** Suffix appended to `document.title`. */
+    titleSuffix?: string;
+}
+/** Overlay loader configuration. */
+export interface UiLayoutLoaderConfig {
+    /** Show the loader when the layout mounts (hides on first NavigationEnd). @default false */
+    showOnInit?: boolean;
+    /** Minimum display duration in milliseconds (prevents flicker). @default 0 */
+    minDuration?: number;
+}
+/** Discriminator for topbar bar type. */
+export type UiBarType = 'notification' | 'brand' | 'navigation' | 'links';
+/**
+ * Notification bar displayed at the top of the page.
+ *
+ * @usageNotes
+ * ```typescript
+ * { text: 'Manutenzione prevista alle 22:00', variant: 'warn', dismissible: true }
+ * ```
+ */
+export interface UiNotificationBarConfig {
+    /** Notification message text. */
+    text: string;
+    /** Visual variant. @default 'primary' */
+    variant?: UiVariant;
+    /** Whether the user can dismiss this bar. @default true */
+    dismissible?: boolean;
+    /** Lucide icon shown before the text. */
+    icon?: UiIconName;
+}
+/**
+ * Brand bar with logo, title, and optional user dropdown.
+ *
+ * @usageNotes
+ * ```typescript
+ * {
+ *   logo: { src: '/assets/logo.svg', alt: 'My App' },
+ *   title: 'My App',
+ *   userDropdown: {
+ *     label: 'Mario Rossi',
+ *     avatar: { src: '/avatar.jpg' },
+ *     items: [
+ *       { id: 'profile', label: 'Profilo', icon: 'user', route: '/profile' },
+ *       { id: 'logout', label: 'Logout', icon: 'log-out', action: () => auth.logout() },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+export interface UiBrandBarConfig {
+    /** Logo displayed on the left. */
+    logo?: UiLayoutLogo;
+    /** Application title. */
+    title?: string;
+    /** User dropdown aligned to the right. */
+    userDropdown?: UiUserDropdownConfig;
+}
+/** User dropdown menu configuration for the brand bar. */
+export interface UiUserDropdownConfig {
+    /** Display label (e.g. user's name). */
+    label: string;
+    /** Lucide icon name (fallback when no avatar). */
+    icon?: UiIconName;
+    /** User avatar image. */
+    avatar?: {
+        src: string;
+        alt?: string;
+    };
+    /** Dropdown menu items. */
+    items: UiDropdownItem[];
+}
+/** Single item in a dropdown menu. */
+export interface UiDropdownItem {
+    /** Unique item identifier. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Lucide icon name. */
+    icon?: UiIconName;
+    /** Angular router path. */
+    route?: string;
+    /** Callback invoked on click. */
+    action?: () => void;
+    /** Render a divider above this item. */
+    divider?: boolean;
+}
+/** Navigation bar (used in topbar mode to render horizontal nav links). */
+export interface UiNavigationBarConfig {
+    /** Override items for this bar (defaults to `schema.navigation.items`). */
+    items?: UiNavItem[];
+}
+/**
+ * Links bar with icon links (e.g. social media, external resources).
+ *
+ * @usageNotes
+ * ```typescript
+ * {
+ *   align: 'end',
+ *   items: [
+ *     { icon: 'github', href: 'https://github.com/...', ariaLabel: 'GitHub' },
+ *     { label: 'Docs', icon: 'book-open', href: 'https://docs.example.com' },
+ *   ],
+ * }
+ * ```
+ */
+export interface UiLinksBarConfig {
+    /** Horizontal alignment of items. @default 'end' */
+    align?: 'start' | 'center' | 'end' | 'space-between';
+    /** Link items. */
+    items: UiBarLinkItem[];
+}
+/** Single link item in a links bar. */
+export interface UiBarLinkItem {
+    /** Display label (optional, icon-only if omitted). */
+    label?: string;
+    /** Lucide icon name. */
+    icon?: UiIconName;
+    /** External URL. */
+    href?: string;
+    /** Angular router path. */
+    route?: string;
+    /** Link target. @default '_self' */
+    target?: '_blank' | '_self';
+    /** Accessible label for icon-only items. */
+    ariaLabel?: string;
+}
+/**
+ * Single bar descriptor in the topbar bar stack.
+ *
+ * @usageNotes
+ * ```typescript
+ * const bars: UiBarConfig[] = [
+ *   { id: 'promo', type: 'notification', notification: { text: 'Promo attiva!', dismissible: true } },
+ *   { id: 'main', type: 'brand', brand: { logo: { text: 'UI' }, title: 'My App' } },
+ *   { id: 'nav', type: 'navigation' },
+ *   { id: 'social', type: 'links', links: { align: 'end', items: [...] } },
+ * ];
+ * ```
+ */
+export interface UiBarConfig {
+    /** Unique bar identifier. */
+    id: string;
+    /** Bar type discriminator. */
+    type: UiBarType;
+    /** Whether the bar is initially visible. @default true */
+    visible?: boolean;
+    /** Configuration when `type === 'notification'`. */
+    notification?: UiNotificationBarConfig;
+    /** Configuration when `type === 'brand'`. */
+    brand?: UiBrandBarConfig;
+    /** Configuration when `type === 'navigation'`. */
+    navigation?: UiNavigationBarConfig;
+    /** Configuration when `type === 'links'`. */
+    links?: UiLinksBarConfig;
+}
+/** Topbar configuration (bar stack). */
+export interface UiTopbarConfig {
+    /** Ordered list of bars rendered top-to-bottom. */
+    bars: UiBarConfig[];
+}
+/**
+ * Root descriptor for the `ui-layout-builder` component.
+ *
+ * @usageNotes
+ * ### Minimal sidebar example
+ * ```typescript
+ * const schema: UiLayoutSchema = {
+ *   header: { title: 'My App' },
+ *   navigation: {
+ *     items: [
+ *       { id: 'home', label: 'Home', icon: 'home', route: '/', routeActiveExact: true },
+ *       { id: 'users', label: 'Utenti', icon: 'users', route: '/users' },
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * ### Topbar mode example
+ * ```typescript
+ * const schema: UiLayoutSchema = {
+ *   mode: 'topbar',
+ *   header: { logo: { text: 'UI' }, title: 'My App' },
+ *   navigation: { items: [...] },
+ *   topbar: {
+ *     bars: [
+ *       { id: 'alert', type: 'notification', notification: { text: 'Beta!', dismissible: true } },
+ *       { id: 'main', type: 'brand', brand: { logo: { text: 'UI' }, title: 'My App' } },
+ *       { id: 'nav', type: 'navigation' },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export interface UiLayoutSchema {
+    /** Layout mode. @default 'sidebar' */
+    mode?: UiLayoutMode;
+    /** Header / top-bar branding. Required for sidebar/topbar modes, ignored in slotted mode. */
+    header?: UiLayoutHeaderConfig;
+    /** Navigation structure and behaviour. Required for sidebar/topbar modes, ignored in slotted mode. */
+    navigation?: UiLayoutNavigationConfig;
+    /** Footer content (optional). In slotted mode use `[uiLayoutFooter]` content projection instead. */
+    footer?: UiLayoutFooterConfig;
+    /** Floating action button / speed dial (optional). */
+    fab?: UiLayoutFabConfig;
+    /** Page header defaults applied to every page (optional). */
+    pageHeader?: UiLayoutPageHeaderConfig;
+    /** Overlay loader configuration (optional). */
+    loader?: UiLayoutLoaderConfig;
+    /** Content area sizing strategy. @default 'fluid' */
+    contentType?: UiContentType;
+    /** Topbar configuration (only used when `mode === 'topbar'`). */
+    topbar?: UiTopbarConfig;
+}

package/layout-builder/lib/components/layout-builder/layout.service.d.ts

@@ -0,0 +1,100 @@
+import { Observable } from 'rxjs';
+import { UiFabAction, UiLayoutFabConfig, UiLayoutMode, UiContentType } from './layout-builder.types';
+import * as i0 from "@angular/core";
+export declare class UiLayoutService {
+    private readonly platformId;
+    private readonly _loading$;
+    /** Whether the overlay loader is currently visible. */
+    readonly loading$: Observable<boolean>;
+    /** Show the full-screen overlay loader and block body scroll. */
+    showLoader(): void;
+    /** Hide the overlay loader and restore body scroll. */
+    hideLoader(): void;
+    /** Toggle the overlay loader. */
+    toggleLoader(): void;
+    /** Synchronous snapshot of the loading state. */
+    isLoading(): boolean;
+    private readonly _layoutMode$;
+    /** Current layout mode (sidebar or topbar). */
+    readonly layoutMode$: Observable<UiLayoutMode>;
+    /**
+     * Switch layout mode with loader masking the transition.
+     * Shows the loader, applies the mode change, then hides the loader
+     * after a short delay to prevent visible layout shift.
+     */
+    setLayoutMode(mode: UiLayoutMode, transitionMs?: number): void;
+    /** Synchronous snapshot of the current layout mode. */
+    getLayoutMode(): UiLayoutMode;
+    /**
+     * @internal Called by the layout-builder component to set the initial mode
+     * from the schema without triggering the loader transition.
+     */
+    _setInitialLayoutMode(mode: UiLayoutMode): void;
+    private readonly _contentType$;
+    /** Current content type (fluid, boxed, fullscreen). */
+    readonly contentType$: Observable<UiContentType>;
+    /** Set the content type per-route or globally. */
+    setContentType(type: UiContentType): void;
+    /** Synchronous snapshot of the current content type. */
+    getContentType(): UiContentType;
+    /** @internal */
+    _setInitialContentType(type: UiContentType): void;
+    private readonly _sidebarOpen$;
+    /** Whether the mobile sidebar drawer is open. */
+    readonly sidebarOpen$: Observable<boolean>;
+    private readonly _sidebarCollapsed$;
+    /** Whether the desktop sidebar is in collapsed (icon-only) mode. */
+    readonly sidebarCollapsed$: Observable<boolean>;
+    /** Toggle the desktop sidebar between expanded and collapsed. */
+    toggleSidebar(): void;
+    /** Set the desktop sidebar collapsed state explicitly. */
+    collapseSidebar(collapsed?: boolean): void;
+    /** Open the mobile sidebar drawer. */
+    openMobileSidebar(): void;
+    /** Close the mobile sidebar drawer. */
+    closeMobileSidebar(): void;
+    /** Synchronous snapshot: is the mobile sidebar open? */
+    isSidebarOpen(): boolean;
+    /** Synchronous snapshot: is the desktop sidebar collapsed? */
+    isSidebarCollapsed(): boolean;
+    private _defaultFabConfig;
+    private readonly _fabConfig$;
+    /** Current FAB configuration (schema default merged with page overrides). */
+    readonly fabConfig$: Observable<UiLayoutFabConfig | null>;
+    /**
+     * Called internally by the layout-builder component to register the
+     * schema-level default FAB config.
+     * @internal
+     */
+    _setDefaultFabConfig(config: UiLayoutFabConfig | null): void;
+    /** Override the FAB main action for the current page context. */
+    setMainFabAction(action: UiFabAction): void;
+    /** Override all FAB actions for the current page context. */
+    setFabActions(main: UiFabAction, secondary?: UiFabAction[]): void;
+    /** Reset FAB to the schema-level default configuration. */
+    clearFabActions(): void;
+    private readonly _navBadges$;
+    /** Observable map of nav-item badges keyed by item ID. */
+    readonly navBadges$: Observable<Map<string, string | number | null>>;
+    private readonly _navVisibility$;
+    /** Observable map of nav-item visibility overrides keyed by item ID. */
+    readonly navVisibility$: Observable<Map<string, boolean>>;
+    /** Set or clear a badge on a navigation item. Pass `null` to remove. */
+    setNavBadge(itemId: string, badge: string | number | null): void;
+    /** Override visibility of a navigation item. */
+    setNavItemVisibility(itemId: string, visible: boolean): void;
+    private readonly _barVisibility$;
+    /** Observable map of topbar bar visibility keyed by bar ID. */
+    readonly barVisibility$: Observable<Map<string, boolean>>;
+    /** Show a topbar bar by ID. */
+    showBar(barId: string): void;
+    /** Hide a topbar bar by ID. */
+    hideBar(barId: string): void;
+    /** Toggle visibility of a topbar bar by ID. */
+    toggleBar(barId: string): void;
+    /** Synchronous check of bar visibility (schema `visible` fallback). */
+    isBarVisible(barId: string, schemaVisible?: boolean): boolean;
+    private setBodyOverflow;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiLayoutService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<UiLayoutService>;
+}

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