@gnggln/ng-ui-system 1.0.0-alpha.0

package/index.d.ts

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

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

@@ -0,0 +1,118 @@
+import { EventEmitter, DoCheck, TemplateRef } from '@angular/core';
+import { UiAccordionDescriptor, UiAccordionToggleEvent, UiAccordionMode } from './accordion.types';
+import * as i0 from "@angular/core";
+/**
+ * Accordion configurabile, data-driven, con supporto multi/single expand,
+ * animazioni CSS, icone Lucide e template personalizzabili.
+ *
+ * Il contenuto dei pannelli viene fornito tramite un `itemTemplate`
+ * che riceve il descriptor del pannello come contesto.
+ *
+ * @selector ui-accordion
+ *
+ * @example
+ * ```html
+ * <ui-accordion
+ *   [items]="sections"
+ *   [itemTemplate]="panelTpl"
+ *   mode="single"
+ * >
+ *   <ng-template #panelTpl let-item>
+ *     @switch (item.id) {
+ *       @case ('info')    { <app-info-panel /> }
+ *       @case ('address') { <app-address-form /> }
+ *     }
+ *   </ng-template>
+ * </ui-accordion>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * sections: UiAccordionDescriptor[] = [
+ *   { id: 'info', title: 'Informazioni', icon: 'info', expanded: true },
+ *   { id: 'address', title: 'Indirizzo', icon: 'map-pin' },
+ * ];
+ * ```
+ */
+export declare class UiAccordionComponent implements DoCheck {
+    private readonly cdr;
+    /**
+     * Fingerprint dell'ultimo stato dei descriptor.
+     * Usato da DoCheck per rilevare mutazioni in-place sulle proprieta
+     * degli item senza richiedere un nuovo riferimento dell'array.
+     */
+    private _lastFingerprint;
+    /**
+     * Array di descriptor dei pannelli.
+     * Pannelli con `hidden: true` vengono filtrati automaticamente.
+     *
+     * Supporta sia aggiornamenti immutabili (nuovo array) sia
+     * mutazioni in-place delle proprieta dei descriptor.
+     */
+    items: UiAccordionDescriptor[];
+    /**
+     * Template per il contenuto di ogni pannello.
+     * Il contesto fornisce il descriptor come `$implicit`.
+     *
+     * @example
+     * ```html
+     * <ng-template #tpl let-item>
+     *   <p>Contenuto per: {{ item.title }}</p>
+     * </ng-template>
+     * ```
+     */
+    itemTemplate: TemplateRef<unknown> | null;
+    /**
+     * Template opzionale per contenuto aggiuntivo nell'header.
+     * Il contesto fornisce il descriptor come `$implicit`.
+     * Viene renderizzato tra il titolo e il chevron.
+     */
+    headerTemplate: TemplateRef<unknown> | null;
+    /**
+     * Modalita di espansione.
+     * - `multi`: piu pannelli aperti contemporaneamente
+     * - `single`: un solo pannello aperto alla volta
+     */
+    mode: UiAccordionMode;
+    /** Label accessibile per il gruppo accordion. */
+    ariaLabel: string;
+    /** Emesso quando un pannello viene aperto o chiuso. */
+    itemToggled: EventEmitter<UiAccordionToggleEvent>;
+    /**
+     * Rileva mutazioni in-place sulle proprieta dei descriptor.
+     * Confronta un fingerprint leggero dello stato corrente con quello
+     * precedente e, se diverso, forza un ciclo di change detection.
+     *
+     * Questo permette al consumatore di fare sia:
+     * - `items[2].hidden = true`  (mutazione in-place)
+     * - `items = [...newItems]`   (nuovo riferimento)
+     */
+    ngDoCheck(): void;
+    /** Pannelli visibili (non hidden). */
+    get visibleItems(): UiAccordionDescriptor[];
+    /** Alterna l'espansione di un pannello. */
+    toggle(item: UiAccordionDescriptor): void;
+    /** Apre un pannello specifico per id. */
+    open(id: string): void;
+    /** Chiude un pannello specifico per id. */
+    close(id: string): void;
+    /** Apre tutti i pannelli (solo in modalita multi). */
+    openAll(): void;
+    /** Chiude tutti i pannelli. */
+    closeAll(): void;
+    /** @internal Classi CSS per il pannello. */
+    getPanelClasses(item: UiAccordionDescriptor): string;
+    /** @internal Sposta il focus al primo header. */
+    focusFirst(event: Event): void;
+    /** @internal Sposta il focus all'ultimo header. */
+    focusLast(event: Event): void;
+    /** @internal Recupera tutti gli header button del DOM. */
+    private getHeaders;
+    /**
+     * @internal Calcola un fingerprint leggero basato sulle proprieta
+     * reattive dei descriptor (quelle che influenzano il rendering).
+     */
+    private computeFingerprint;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiAccordionComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiAccordionComponent, "ui-accordion", never, { "items": { "alias": "items"; "required": false; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; }; "headerTemplate": { "alias": "headerTemplate"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; }; }, { "itemToggled": "itemToggled"; }, never, never, true, never>;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @module ng-ui-system/accordion
+ * Tipi e interfacce per UiAccordion.
+ */
+import { UiIconName } from '../../core/types';
+export { UiIconName };
+/**
+ * Descriptor per un singolo pannello dell'accordion.
+ *
+ * Consente di definire accordion come strutture dati dichiarative,
+ * aggiornabili dinamicamente tramite manipolazione dell'array.
+ *
+ * @usageNotes
+ * ### Utilizzo base
+ * ```typescript
+ * const items: UiAccordionDescriptor[] = [
+ *   { id: 'info', title: 'Informazioni generali', icon: 'info' },
+ *   { id: 'address', title: 'Indirizzo', icon: 'map-pin' },
+ *   { id: 'notes', title: 'Note aggiuntive', expanded: true },
+ * ];
+ * ```
+ *
+ * ### Visibilita condizionale
+ * ```typescript
+ * items[2].hidden = !this.hasNotes;
+ * items[1].disabled = this.isReadonly;
+ * ```
+ */
+export interface UiAccordionDescriptor {
+    /** Identificatore univoco del pannello. */
+    id: string;
+    /** Titolo visualizzato nell'header del pannello. */
+    title: string;
+    /** Icona Lucide opzionale mostrata prima del titolo. @see https://lucide.dev/icons */
+    icon?: UiIconName;
+    /** Stato iniziale di espansione. @default false */
+    expanded?: boolean;
+    /** Disabilita l'interazione con il pannello. @default false */
+    disabled?: boolean;
+    /** Nasconde il pannello dall'interfaccia. @default false */
+    hidden?: boolean;
+    /** Descrizione secondaria mostrata accanto al titolo. */
+    subtitle?: string;
+}
+/**
+ * Evento emesso quando un pannello viene aperto o chiuso.
+ */
+export interface UiAccordionToggleEvent {
+    /** Descriptor del pannello coinvolto. */
+    item: UiAccordionDescriptor;
+    /** `true` se il pannello e stato aperto, `false` se chiuso. */
+    expanded: boolean;
+}
+/**
+ * Modalita di espansione dell'accordion.
+ *
+ * | Modalita | Comportamento                                   |
+ * |---------|------------------------------------------------|
+ * | `multi` | Piu pannelli possono essere aperti contemporaneamente |
+ * | `single`| Un solo pannello aperto alla volta (gli altri si chiudono) |
+ */
+export type UiAccordionMode = 'multi' | 'single';

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

@@ -0,0 +1,2 @@
+export { UiAccordionComponent } from './accordion.component';
+export { UiAccordionDescriptor, UiAccordionToggleEvent, UiAccordionMode, } from './accordion.types';

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

@@ -0,0 +1,83 @@
+import { OnInit } from '@angular/core';
+import { UiButtonDescriptor, UiButtonAreaAlign } from '../button/button.types';
+import { UiBackButtonConfig } from './base-layout.types';
+import * as i0 from "@angular/core";
+/**
+ * Full-page layout component that combines a page header (breadcrumbs + title),
+ * a main content area via `<ng-content>`, and a sticky footer action bar
+ * powered by `UiButtonAreaComponent`.
+ *
+ * Optionally renders an automatic "back" button in the footer, derived from
+ * the breadcrumb trail (navigates to the parent breadcrumb).
+ *
+ * @selector ui-base-layout
+ *
+ * @example
+ * ```html
+ * <ui-base-layout [actions]="pageActions" footerAlign="end">
+ *   <p>Your page content here</p>
+ * </ui-base-layout>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- With back button and custom title -->
+ * <ui-base-layout
+ *   title="Dettaglio utente"
+ *   [showBackButton]="true"
+ *   [actions]="[
+ *     { id: 'save', label: 'Salva', variant: 'primary', icon: 'save', action: save },
+ *   ]"
+ * >
+ *   <app-user-detail />
+ * </ui-base-layout>
+ * ```
+ */
+export declare class UiBaseLayoutComponent implements OnInit {
+    /** Whether to display the page header (breadcrumbs + title). */
+    showHeader: boolean;
+    /** Override the auto-detected page title. Passed through to `ui-page-header`. */
+    title: string;
+    /** Route path for the Home breadcrumb link. */
+    homeRoute: string;
+    /** Whether to display the Home link in the breadcrumb trail. */
+    showHome: boolean;
+    /** When `true`, updates `document.title` on navigation. */
+    updateDocumentTitle: boolean;
+    /** Suffix appended to `document.title`. */
+    titleSuffix: string;
+    /** Whether to show an automatic "back" button based on breadcrumbs. */
+    showBackButton: boolean;
+    /** Configuration overrides for the automatic back button. */
+    backButtonConfig: UiBackButtonConfig;
+    /** Array of button descriptors for the footer action area. */
+    actions: UiButtonDescriptor[];
+    /** Horizontal alignment of the footer button area. */
+    footerAlign: UiButtonAreaAlign;
+    /** Gap size between footer buttons. */
+    footerGap: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    private readonly router;
+    private readonly location;
+    private readonly activatedRoute;
+    private readonly breadcrumbService;
+    private readonly destroyRef;
+    /** @internal Current breadcrumbs, updated on each navigation. */
+    private breadcrumbs;
+    /**
+     * Merged action list (back button + consumer actions).
+     * Computed on every change-detection check so it stays in sync
+     * with both navigation state (breadcrumbs) and input changes.
+     */
+    get mergedActions(): UiButtonDescriptor[];
+    /** Whether the footer should render (at least one non-hidden action exists). */
+    get hasVisibleActions(): boolean;
+    ngOnInit(): void;
+    /** @internal Refreshes breadcrumb state from the current route. */
+    private refreshBreadcrumbs;
+    /** @internal Determines the back navigation target from breadcrumbs. */
+    private getBackTarget;
+    /** @internal Navigates to the parent breadcrumb or falls back to browser history. */
+    private navigateBack;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiBaseLayoutComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiBaseLayoutComponent, "ui-base-layout", never, { "showHeader": { "alias": "showHeader"; "required": false; }; "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; }; "showBackButton": { "alias": "showBackButton"; "required": false; }; "backButtonConfig": { "alias": "backButtonConfig"; "required": false; }; "actions": { "alias": "actions"; "required": false; }; "footerAlign": { "alias": "footerAlign"; "required": false; }; "footerGap": { "alias": "footerGap"; "required": false; }; }, {}, never, ["*"], true, never>;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @module ng-ui-system/base-layout
+ * Types and interfaces for UiBaseLayout component.
+ */
+import { UiButtonDescriptor, UiButtonAreaAlign } from '../button/button.types';
+export { UiButtonDescriptor, UiButtonAreaAlign };
+/**
+ * Configuration for the automatic "back" button rendered in the footer action area.
+ *
+ * @usageNotes
+ * ```typescript
+ * const backConfig: UiBackButtonConfig = {
+ *   label: 'Indietro',
+ *   icon: 'arrow-left',
+ *   variant: 'outline',
+ * };
+ * ```
+ */
+export interface UiBackButtonConfig {
+    /** Label text for the back button. @default 'Indietro' */
+    label?: string;
+    /** Lucide icon name. @default 'arrow-left' */
+    icon?: string;
+    /** Visual variant. @default 'outline' */
+    variant?: string;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * ng-ui-system — Base Layout entry point.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UiBaseLayoutComponent,
+ *   UiBackButtonConfig,
+ * } from 'ng-ui-system';
+ * ```
+ */
+export { UiBaseLayoutComponent } from './base-layout.component';
+export { UiBackButtonConfig } from './base-layout.types';

package/lib/components/button/button-area.component.d.ts

@@ -0,0 +1,88 @@
+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.
+ *
+ * @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;
+    /** 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: calls action 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/lib/components/button/button.component.d.ts

@@ -0,0 +1,55 @@
+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 -->
+ * <ui-button icon="trash-2" variant="warn" ariaLabel="Delete item" (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;
+    /** 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/lib/components/button/button.types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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;
+    /**
+     * 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';

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

@@ -0,0 +1,15 @@
+/**
+ * ng-ui-system — Button entry point.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   UiButtonComponent,
+ *   UiButtonAreaComponent,
+ *   UiButtonDescriptor,
+ * } from 'ng-ui-system';
+ * ```
+ */
+export { UiButtonComponent } from './button.component';
+export { UiButtonAreaComponent } from './button-area.component';
+export { UiButtonDescriptor, UiButtonAreaAlign, UiIconPosition, } from './button.types';