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

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

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

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

package/http/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/layout-builder/entry-layout-builder.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Bootstrap del secondary entry `@gnggln/ng-ui-system/layout-builder`. Layout Builder.
+ */
+export * from './lib/components/layout-builder/index';

package/layout-builder/index.d.ts

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

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

@@ -0,0 +1,16 @@
+/**
+ * ng-ui-system — Layout Builder entry point.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UiLayoutBuilderComponent,
+ *   UiLayoutService,
+ *   UiLayoutSchema,
+ *   UiNavItem,
+ * } from 'ng-ui-system';
+ * ```
+ */
+export { UiLayoutBuilderComponent } from './layout-builder.component';
+export { UiLayoutService } from './layout.service';
+export { UiLayoutMode, UiContentType, UiLayoutBreadcrumb, UiLayoutSchema, UiNavItem, UiNavItemType, UiNavGroup, UiNavSection, UiNavAutoDiscoveryConfig, UiLayoutNavigationConfig, UiLayoutLogo, UiLayoutHeaderConfig, UiFooterLink, UiLayoutFooterConfig, UiFabAction, UiLayoutFabConfig, UiLayoutPageHeaderConfig, UiLayoutLoaderConfig, UiBarType, UiBarConfig, UiTopbarConfig, UiNotificationBarConfig, UiBrandBarConfig, UiUserDropdownConfig, UiDropdownItem, UiNavigationBarConfig, UiLinksBarConfig, UiBarLinkItem, } from './layout-builder.types';

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

@@ -0,0 +1,85 @@
+/**
+ * Schema-driven application shell that materializes a full responsive layout
+ * from a single `UiLayoutSchema` descriptor.
+ *
+ * Features:
+ * - Two layout modes: sidebar (collapsible) and topbar (multi-bar stack)
+ * - Programmatic mode switching with loader masking
+ * - Content type: fluid, boxed, fullscreen
+ * - Speed-dial FAB with context-sensitive actions
+ * - Overlay loader with body-scroll locking
+ * - Auto-derived breadcrumbs from navigation schema
+ * - Skip-to-content link and full keyboard navigation
+ *
+ * @selector ui-layout-builder
+ *
+ * @example
+ * ```html
+ * <ui-layout-builder [schema]="layoutSchema" />
+ * ```
+ */
+import { OnInit, OnDestroy } from '@angular/core';
+import { UiLayoutService } from './layout.service';
+import { UiLayoutSchema, UiLayoutMode, UiContentType, UiLayoutBreadcrumb, UiNavItem, UiNavSection, UiLayoutFabConfig, UiFabAction, UiBarConfig } from './layout-builder.types';
+import * as i0 from "@angular/core";
+export declare class UiLayoutBuilderComponent implements OnInit, OnDestroy {
+    /** Full layout descriptor. */
+    schema: UiLayoutSchema;
+    readonly layoutService: UiLayoutService;
+    private readonly router;
+    private readonly cdr;
+    private subs;
+    currentUrl: string;
+    expandedIds: Set<string>;
+    fabOpen: boolean;
+    currentFabConfig: UiLayoutFabConfig | null;
+    loading: boolean;
+    sidebarOpen: boolean;
+    sidebarCollapsed: boolean;
+    layoutMode: UiLayoutMode;
+    contentType: UiContentType;
+    contentTransitioning: boolean;
+    breadcrumbs: UiLayoutBreadcrumb[];
+    userDropdownOpen: boolean;
+    hnavDropdownId: string | null;
+    private navBadges;
+    private navVisibility;
+    private barVisibility;
+    /** Resolved page title from the last breadcrumb. */
+    get pageTitle(): string;
+    /** Items flagged for the mobile bottom navigation bar (max 5). */
+    get bottomNavItems(): UiNavItem[];
+    get mobileMode(): string;
+    /** Topbar bars filtered by visibility (schema default + service overrides). */
+    get visibleBars(): UiBarConfig[];
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    onEscape(): void;
+    onDocumentClick(event: MouseEvent): void;
+    getItemsForSection(section: UiNavSection): UiNavItem[];
+    isItemHidden(item: UiNavItem): boolean;
+    getItemBadge(item: UiNavItem): string | number | null;
+    isParentActive(item: UiNavItem): boolean;
+    isRouteActive(item: UiNavItem): boolean;
+    toggleExpand(item: UiNavItem): void;
+    onNavClick(): void;
+    onFabMainClick(): void;
+    onFabAction(action: UiFabAction): void;
+    getTopbarNavItems(bar: UiBarConfig): UiNavItem[];
+    toggleHnavDropdown(itemId: string): void;
+    dismissBar(barId: string): void;
+    onDropdownAction(item: {
+        action?: () => void;
+    }): void;
+    /**
+     * Derives breadcrumbs by matching the current URL against the
+     * navigation schema. Walks top-level items, sections, and children
+     * to build a trail from root to current page.
+     */
+    private computeBreadcrumbs;
+    private urlMatches;
+    private findSectionLabel;
+    private autoExpandFromUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiLayoutBuilderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiLayoutBuilderComponent, "ui-layout-builder", never, { "schema": { "alias": "schema"; "required": true; }; }, {}, never, ["[uiLayoutHeader]", "[uiLayoutFooter]"], true, never>;
+}