@eternalcodestudio/primeng-table 20.0.12 → 20.0.13

package/index.d.ts

@@ -1,188 +1,35 @@
+import { HttpResponse, HttpHeaders } from '@angular/common/http';
+import { Observable } from 'rxjs';
 import * as i0 from '@angular/core';
 import { OnInit, AfterViewInit, EventEmitter, ElementRef } from '@angular/core';
 import { Table, TableLazyLoadEvent, TableRowSelectEvent, TableRowUnSelectEvent, TablePageEvent } from 'primeng/table';
-import { Observable } from 'rxjs';
-import { HttpResponse, HttpHeaders } from '@angular/common/http';
 import { SortMeta, MenuItem } from 'primeng/api';
 
 /**
- * Abstract service for handling HTTP requests for **ECS Primeng table**.
- *
- * Provides a consistent interface for making GET and POST requests to the backend.
- * Implementations must define how requests are executed, including error handling,
- * headers, and response processing.
- */
-declare abstract class ECSPrimengTableHttpService {
-    /**
-     * Performs a GET request to the specified service endpoint.
-     *
-     * @template T The expected response type.
-     * @param servicePoint The endpoint URL or path for the GET request.
-     * @param responseType Optional. The type of response expected, either `'json'` (default) or `'blob'`.
-     * @returns An Observable of `HttpResponse<T>`, containing the full HTTP response.
-     */
-    abstract handleHttpGetRequest<T>(servicePoint: string, responseType?: 'json' | 'blob'): Observable<HttpResponse<T>>;
-    /**
-     * Performs a POST request to the specified service endpoint.
-     *
-     * @template T The expected response type.
-     * @param servicePoint The endpoint URL or path for the POST request.
-     * @param data The payload to send in the POST request body.
-     * @param httpOptions Optional HTTP headers to include in the request.
-     * @param responseType Optional. The type of response expected, either `'json'` (default) or `'blob'`.
-     * @returns An Observable of `HttpResponse<T>`, containing the full HTTP response.
-     */
-    abstract handleHttpPostRequest<T>(servicePoint: string, data: any, httpOptions?: HttpHeaders | null, responseType?: 'json' | 'blob'): Observable<HttpResponse<T>>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ECSPrimengTableHttpService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<ECSPrimengTableHttpService>;
-}
-
-/**
- * Abstract service for handling notifications in **ECS Primeng table**.
- *
- * Provides a consistent interface for displaying and clearing toast notifications.
- * Implementations must define how the notifications are managed.
- */
-declare abstract class ECSPrimengTableNotificationService {
-    /**
-     * Displays a toast notification.
-     *
-     * @param severity The severity level of the notification (e.g., 'success', 'info', 'warn', 'error').
-     * @param title The title of the toast message.
-     * @param message The detailed message of the toast.
-     */
-    abstract showToast(severity: string, title: string, message: string): void;
-    /**
-     * Clears all currently displayed toast notifications.
-     */
-    abstract clearToasts(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ECSPrimengTableNotificationService, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<ECSPrimengTableNotificationService>;
-}
-
-/**
- * Interface representing a table action button, applicable for both header and row buttons.
- */
-interface ITableButton {
-    /**
-     * Optional. The icon to display on the button.
-     * Should be a valid icon name from PrimeNG, Material Icons, Font Awesome, or similar libraries.
-     */
-    icon?: string;
-    /**
-     * Optional. The position of the icon relative to the button label.
-     * Defaults to "left". Possible values are:
-     * - "left"
-     * - "right"
-     * - "top"
-     * - "bottom"
-     */
-    iconPos?: string;
-    /**
-     * Optional. The text label displayed on the button.
-     */
-    label?: string;
-    /**
-     * Optional. If true, the button will be round. Defaults to false.
-     */
-    rounded?: boolean;
-    /**
-     * Optional. If true, adds a shadow to indicate elevation. Defaults to false.
-     */
-    raised?: boolean;
-    /**
-     * Optional. Specifies the variant of the button.
-     * Can be null (default), "text", or "outlined".
-     */
-    variant?: string;
-    /**
-     * Optional. The CSS class to apply for button styling.
-     * Example: "p-button-success" or "custom-class".
-     */
-    color?: string;
-    /**
-     * Optional. Additional inline CSS styles for the button.
-     */
-    style?: string;
-    /**
-     * Optional. Function that determines whether the button should be visible for a given row.
-     * @param rowData The row data object. Null for header buttons.
-     * @returns True if the button should be visible; false otherwise.
-     */
-    visibleCondition?: (rowData: any) => boolean;
-    /**
-     * Optional. Function that determines whether the button should be displayed for a given row.
-     *
-     * Ignored if `visibleCondition` returns false.
-     * @param rowData The row data object. Null for header buttons.
-     * @returns True if the button should be enabled; false otherwise.
-     */
-    enabledCondition?: (rowData: any) => boolean;
-    /**
-     * Optional. Controls behavior when `enabledCondition` returns false.
-     * - If `true`, the button will be hidden when the 'enabledCondition' is not met.
-     * - If `false` or `undefined`, the button will remain visible but disabled if 'enabledCondition' is not met.
-     *
-     * Ignored if `visibleCondition` returns false.
-     */
-    conditionFailHide?: boolean;
-    /**
-     * Optional. The action to execute when the button is clicked.
-     * @param rowData The row data object of the clicked row. Null for header buttons.
-     */
-    action?: (rowData: any) => void;
-    /**
-     * Optional. Tooltip text to display when the user hovers over the button.
-     */
-    tooltip?: string;
-}
-
-interface ITableQueryRequest {
-    page: number;
-    pageSize: number;
-    sort?: any;
-    filter: any;
-    globalFilter?: string | null;
-    columns?: string[];
-    dateFormat: string;
-    dateTimezone: string;
-    dateCulture: string;
-}
-
-interface IExcelExportRequest extends ITableQueryRequest {
-    filename: string;
-    allColumns: boolean;
-    applyFilters: boolean;
-    applySorts: boolean;
-}
-
-/**
- * Enum representing how content that overflows a table cell should be handled.
+ * Defines how content that overflows a table cell is displayed.
  *
  * @remarks
- * Determines the visual behavior of cell content when it exceeds the cell's width.
+ * This enumeration specifies the visual behavior of cell content when it exceeds the cell’s width.
  */
 declare enum CellOverflowBehaviour {
-    /** Content that exceeds the cell's width is clipped and not visible. */
+    /** The overflowing content is clipped and not visible. */
     Hidden = 0,
-    /** Content wraps onto multiple lines to fit within the cell. */
-    Wrap = 1,
-    /** Content is truncated and an ellipsis (...) is shown at the end. */
-    Ellipsis = 2
+    /** The content wraps onto multiple lines to fit within the cell. */
+    Wrap = 1
 }
 
 /**
- * Enum representing the horizontal alignment of content within a table cell.
+ * Defines the horizontal alignment of content within a table cell.
  *
  * @remarks
- * Determines how the content inside a cell is positioned horizontally relative to the cell's width.
+ * Specifies how the content inside a cell is positioned horizontally relative to the cell's width.
  */
 declare enum DataAlignHorizontal {
-    /** Align content to the left of the cell. */
+    /** Content is aligned to the left side of the cell. */
     Left = 0,
-    /** Align content to the center of the cell. */
+    /** Content is aligned to the center of the cell. */
     Center = 1,
-    /** Align content to the right of the cell. */
+    /** Content is aligned to the right side of the cell. */
     Right = 2
 }
 
@@ -245,7 +92,7 @@ declare enum FrozenColumnAlign {
  * sorting) are persisted.
  */
 declare enum TableViewSaveMode {
-    /** Do not save the table view state. */
+    /** Views are disabled. */
     None = 0,
     /** Save the table view state in the browser's sessionStorage (cleared on tab close). */
     SessionStorage = 1,
@@ -255,33 +102,61 @@ declare enum TableViewSaveMode {
     DatabaseStorage = 3
 }
 
+/**
+ * Represents the metadata for a column in a table.
+ *
+ * @remarks
+ * Provides configuration for column behavior, appearance, and user interactions.
+ */
 interface IColumnMetadata {
+    /** The key or identifier for the column's data field. */
     field: string;
+    /** The display name of the column header. */
     header: string;
+    /** The type of data contained in the column. */
     dataType: DataType;
+    /** The horizontal alignment of the column content. */
     dataAlignHorizontal: DataAlignHorizontal;
+    /** Indicates whether the horizontal alignment can be modified by the user. */
     dataAlignHorizontalAllowUserEdit: boolean;
+    /** The vertical alignment of the column content. */
     dataAlignVertical: DataAlignVertical;
+    /** Indicates whether the vertical alignment can be modified by the user. */
     dataAlignVerticalAllowUserEdit: boolean;
+    /** Determines if the column can be hidden. */
     canBeHidden: boolean;
+    /** Determines if the column should initially be hidden. */
     startHidden: boolean;
+    /** Determines if the column can be resized by the user. */
     canBeResized: boolean;
+    /** Determines if the column can be reordered by the user. */
     canBeReordered: boolean;
+    /** Determines if the column can be sorted. */
     canBeSorted: boolean;
+    /** Determines if the column can be filtered. */
     canBeFiltered: boolean;
+    /** Name of predefined filter values, if any. */
     filterPredefinedValuesName: string;
+    /** Determines if the column can be included in global filtering. */
     canBeGlobalFiltered: boolean;
+    /** Description or tooltip text for the column. */
     columnDescription: string;
+    /** Determines if a tooltip should be shown for the column data. */
     dataTooltipShow: boolean;
+    /** Custom source for the tooltip content, if applicable. */
     dataTooltipCustomColumnSource: string;
+    /** Alignment for frozen columns (left or right). */
     frozenColumnAlign: FrozenColumnAlign;
+    /** Specifies how overflowing content is handled within the cell. */
     cellOverflowBehaviour: CellOverflowBehaviour;
+    /** Indicates whether the cell overflow behavior can be modified by the user. */
     cellOverflowBehaviourAllowUserEdit: boolean;
+    /** Initial width of the column in pixels. */
     initialWidth: number;
 }
 
 /**
- * Represents a predefined filter value for a column in **ECS PrimeNG tables**.
+ * Represents a predefined filter value for a column in **ECS PrimeNG table**.
  *
  * Allows displaying a value as text, tag, icon or image (from URL or blob) with optional styles and colors.
  */
@@ -361,15 +236,206 @@ interface IPredefinedFilter {
     action?: (rowData: any, option: IPredefinedFilter) => void;
 }
 
+/**
+ * Interface representing a table action button, applicable for both header and row buttons.
+ */
+interface ITableButton {
+    /**
+     * Optional. The icon to display on the button.
+     * Should be a valid icon name from PrimeNG, Material Icons, Font Awesome, or similar libraries.
+     */
+    icon?: string;
+    /**
+     * Optional. The position of the icon relative to the button label.
+     * Defaults to "left". Possible values are:
+     * - "left"
+     * - "right"
+     * - "top"
+     * - "bottom"
+     */
+    iconPos?: string;
+    /**
+     * Optional. The text label displayed on the button.
+     */
+    label?: string;
+    /**
+     * Optional. If true, the button will be round. Defaults to false.
+     */
+    rounded?: boolean;
+    /**
+     * Optional. If true, adds a shadow to indicate elevation. Defaults to false.
+     */
+    raised?: boolean;
+    /**
+     * Optional. Specifies the variant of the button.
+     * Can be null (default), "text", or "outlined".
+     */
+    variant?: string;
+    /**
+     * Optional. The CSS class to apply for button styling.
+     * Example: "p-button-success" or "custom-class".
+     */
+    color?: string;
+    /**
+     * Optional. Additional inline CSS styles for the button.
+     */
+    style?: string;
+    /**
+     * Optional. Function that determines whether the button should be visible for a given row.
+     * @param rowData The row data object. Null for header buttons.
+     * @returns True if the button should be visible; false otherwise.
+     */
+    visibleCondition?: (rowData: any) => boolean;
+    /**
+     * Optional. Function that determines whether the button should be displayed for a given row.
+     *
+     * Ignored if `visibleCondition` returns false.
+     * @param rowData The row data object. Null for header buttons.
+     * @returns True if the button should be enabled; false otherwise.
+     */
+    enabledCondition?: (rowData: any) => boolean;
+    /**
+     * Optional. Controls behavior when `enabledCondition` returns false.
+     * - If `true`, the button will be hidden when the 'enabledCondition' is not met.
+     * - If `false` or `undefined`, the button will remain visible but disabled if 'enabledCondition' is not met.
+     *
+     * Ignored if `visibleCondition` returns false.
+     */
+    conditionFailHide?: boolean;
+    /**
+     * Optional. The action to execute when the button is clicked.
+     * @param rowData The row data object of the clicked row. Null for header buttons.
+     */
+    action?: (rowData: any) => void;
+    /**
+     * Optional. Tooltip text to display when the user hovers over the button.
+     */
+    tooltip?: string;
+}
+
+/**
+ * Represents a request for querying table data with pagination, sorting, and filtering.
+ *
+ * @remarks
+ * Includes information about page, page size, sorting, filters, and date formatting options.
+ */
+interface ITableQueryRequest {
+    /** The current page number. */
+    page: number;
+    /** The number of items per page. */
+    pageSize: number;
+    /** Optional sorting configuration. */
+    sort?: any;
+    /** Filter criteria for the query. */
+    filter: any;
+    /** Optional global filter applied across all columns. */
+    globalFilter?: string | null;
+    /** Optional array of column names to include in the query. */
+    columns?: string[];
+    /** The date format used for query parameters. */
+    dateFormat: string;
+    /** The timezone used for formatting date values. */
+    dateTimezone: string;
+    /** The culture/locale used for formatting dates and numbers. */
+    dateCulture: string;
+}
+
+/**
+ * Represents the request parameters for exporting table data to Excel.
+ *
+ * @remarks
+ * Extends `ITableQueryRequest` to include Excel-specific options such as filename,
+ * column selection, and whether to apply current filters and sorts.
+ */
+interface IExcelExportRequest extends ITableQueryRequest {
+    /** The desired name of the exported Excel file. */
+    filename: string;
+    /** Determines whether all columns should be included in the export. */
+    allColumns: boolean;
+    /** Determines whether the current table filters should be applied in the export. */
+    applyFilters: boolean;
+    /** Determines whether the current table sorting should be applied in the export. */
+    applySorts: boolean;
+}
+
+/**
+ * Represents the configuration settings for a table.
+ *
+ * @remarks
+ * Contains column definitions, pagination options, date formatting, and other table-related settings.
+ */
 interface ITableConfiguration {
+    /** Array of metadata objects defining each column in the table. */
     columnsInfo: IColumnMetadata[];
+    /** Allowed options for the number of items displayed per page. */
     allowedItemsPerPage: number[];
+    /** The format used for displaying dates in the table. */
     dateFormat: string;
+    /** The timezone applied when formatting date values. */
     dateTimezone: string;
+    /** The culture/locale used for date and number formatting. */
     dateCulture: string;
+    /** Maximum number of table views that can be saved or tracked. */
     maxViews: number;
 }
 
+/**
+ * Represents a paged response from a table query.
+ *
+ * @remarks
+ * Provides information about the current page, total records, and the data for the page.
+ */
+interface ITablePagedResponse {
+    /** The current page number. */
+    page: number;
+    /** Total number of records after applying any filters. */
+    totalRecords: number;
+    /** Total number of records without applying any filters. */
+    totalRecordsNotFiltered: number;
+    /** The data items for the current page. */
+    data: any;
+}
+
+/**
+ * Represents the current state and configuration of a table view.
+ *
+ * @remarks
+ * Includes information about displayed columns, widths, sorting, filtering, and pagination.
+ */
+interface ITableViewData {
+    /** Array of columns currently visible in the table. */
+    columnsShown: IColumnMetadata[];
+    /** The total width of the table in pixels. */
+    tableWidth: any;
+    /** Widths of individual columns as a formatted string (in pixels). */
+    columnsWidth: string;
+    /** Sorting metadata for multiple columns, if applicable. */
+    multiSortMeta: SortMeta[] | null | undefined;
+    /** Current filter settings applied to the table. */
+    filters: any;
+    /** Text used for global search across all columns, if any. */
+    globalSearchText: string | null;
+    /** The current page number. */
+    currentPage: number;
+    /** The number of rows displayed per page. */
+    currentRowsPerPage: number;
+}
+
+/**
+ * Represents a saved or active view of a table.
+ *
+ * @remarks
+ * Contains information about whether the view is currently active, its alias, and the view data.
+ */
+interface ITableView {
+    /** Indicates if this view is the last active one. */
+    lastActive: boolean;
+    /** Alias or name of the view. */
+    viewAlias: string;
+    /** The detailed data and configuration for this view. */
+    viewData: ITableViewData;
+}
+
 /** Configuration options for ECS Primeng table */
 interface ITableOptions {
     /**
@@ -414,6 +480,66 @@ interface ITableOptions {
      * @default []
      */
     data?: any[];
+    /**
+     * Configuration options for the table description section.
+     */
+    description?: {
+        /**
+         * Icon displayed alongside the table description.
+         * You can use any PrimeIcons class or icons from third-party libraries
+         * such as Material Icons or Font Awesome.
+         *
+         * @default "pi pi-info-circle"
+         */
+        icon?: string;
+        /**
+         * Determines how the description text is displayed.
+         * - `true`, the `text` content is shown as a tooltip when hovering
+         * over the description icon.
+         * - `false`, the `text` is displayed inline to the right of the icon.
+         *
+         * @default true
+         */
+        tooltip?: boolean;
+        /**
+         * The description content to display.
+         * If left undefined or string empty, the table description will not be rendered.
+         * Supports basic HTML for rich text formatting.
+         *
+         * @default undefined
+         */
+        text?: string;
+    };
+    /**
+     * Configuration options for the table legend.
+     */
+    legend?: {
+        /**
+         * The content to be displayed in the popover of the legend. Can be HTML rich.
+         *
+         * @default undefined
+         */
+        content?: string;
+        /**
+         * Configuration options for the button that displays the popover of the table legend.
+         */
+        button?: {
+            /**
+             * Icon displayed alongside the button of the table legend.
+             * You can use any PrimeIcons class or icons from third-party libraries
+             * such as Material Icons or Font Awesome.
+             *
+             * @default "pi pi-bars"
+             */
+            icon?: string;
+            /**
+             * The text shown in the legend button.
+             *
+             * @default "Legend"
+             */
+            text?: string;
+        };
+    };
     /**
      * Configurations related to options that are at the header of the table.
      */
@@ -800,30 +926,67 @@ interface ITableOptions {
      */
     copyToClipboardTime?: number;
 }
+/** Default configuration options for ECS Primeng table */
 declare const DEFAULT_TABLE_OPTIONS: ITableOptions;
 
-interface ITablePagedResponse {
-    page: number;
-    totalRecords: number;
-    totalRecordsNotFiltered: number;
-    data: any;
-}
+/**
+ * Create table options based on defaults, with optional overrides.
+ */
+declare function createTableOptions(overrides?: Partial<ITableOptions>): ITableOptions;
 
-interface ITableViewData {
-    columnsShown: IColumnMetadata[];
-    tableWidth: any;
-    columnsWidth: string;
-    multiSortMeta: SortMeta[] | null | undefined;
-    filters: any;
-    globalSearchText: string | null;
-    currentPage: number;
-    currentRowsPerPage: number;
+/**
+ * Abstract service for handling HTTP requests for **ECS Primeng table**.
+ *
+ * Provides a consistent interface for making GET and POST requests to the backend.
+ * Implementations must define how requests are executed, including error handling,
+ * headers, and response processing.
+ */
+declare abstract class ECSPrimengTableHttpService {
+    /**
+     * Performs a GET request to the specified service endpoint.
+     *
+     * @template T The expected response type.
+     * @param servicePoint The endpoint URL or path for the GET request.
+     * @param responseType Optional. The type of response expected, either `'json'` (default) or `'blob'`.
+     * @returns An Observable of `HttpResponse<T>`, containing the full HTTP response.
+     */
+    abstract handleHttpGetRequest<T>(servicePoint: string, responseType?: 'json' | 'blob'): Observable<HttpResponse<T>>;
+    /**
+     * Performs a POST request to the specified service endpoint.
+     *
+     * @template T The expected response type.
+     * @param servicePoint The endpoint URL or path for the POST request.
+     * @param data The payload to send in the POST request body.
+     * @param httpOptions Optional HTTP headers to include in the request.
+     * @param responseType Optional. The type of response expected, either `'json'` (default) or `'blob'`.
+     * @returns An Observable of `HttpResponse<T>`, containing the full HTTP response.
+     */
+    abstract handleHttpPostRequest<T>(servicePoint: string, data: any, httpOptions?: HttpHeaders | null, responseType?: 'json' | 'blob'): Observable<HttpResponse<T>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ECSPrimengTableHttpService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ECSPrimengTableHttpService>;
 }
 
-interface ITableView {
-    lastActive: boolean;
-    viewAlias: string;
-    viewData: ITableViewData;
+/**
+ * Abstract service for handling notifications in **ECS Primeng table**.
+ *
+ * Provides a consistent interface for displaying and clearing toast notifications.
+ * Implementations must define how the notifications are managed.
+ */
+declare abstract class ECSPrimengTableNotificationService {
+    /**
+     * Displays a toast notification.
+     *
+     * @param severity The severity level of the notification (e.g., 'success', 'info', 'warn', 'error').
+     * @param title The title of the toast message.
+     * @param message The detailed message of the toast.
+     */
+    abstract showToast(severity: string, title: string, message: string): void;
+    /**
+     * Clears all currently displayed toast notifications.
+     */
+    abstract clearToasts(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ECSPrimengTableNotificationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ECSPrimengTableNotificationService>;
 }
 
 declare class ECSPrimengTableService {
@@ -1002,16 +1165,6 @@ declare class ECSPrimengTable implements OnInit, AfterViewInit {
      * @param {IPrimengPredefinedFilter[]} selectedValues - An array of selected predefined filter values.
      */
     onPredefinedFilterChange(filterName: string, selectedValues: IPredefinedFilter[]): void;
-    /**
-     * Retrieves the number of values selected for a predefined filter.
-     *
-     * This function checks the collection of selected values for a specified column key name and returns a string
-     * indicating the number of selected items along with a predefined text.
-     *
-     * @param {string} columnKeyName - The key name of the column for which to retrieve the number of selected values.
-     * @returns {string} A string indicating the number of selected values for the specified column.
-     */
-    predefinedFiltersSelectedValuesText(columnKeyName: string): string;
     /**
      * Checks if the provided column metadata matches a specific style of the predefined filters
      * that need to be applied to an item on a row.
@@ -1040,10 +1193,5 @@ declare class ECSPrimengTable implements OnInit, AfterViewInit {
     static ɵcmp: i0.ɵɵComponentDeclaration<ECSPrimengTable, "ecs-primeng-table", never, { "tableOptions": { "alias": "tableOptions"; "required": false; }; }, { "onRowCheckboxChange": "onRowCheckboxChange"; "onRowSelect": "onRowSelect"; "onRowUnselect": "onRowUnselect"; "onDataEndUpdate": "onDataEndUpdate"; }, never, never, true, never>;
 }
 
-/**
- * Create table options based on defaults, with optional overrides.
- */
-declare function createTableOptions(overrides?: Partial<ITableOptions>): ITableOptions;
-
 export { CellOverflowBehaviour, DEFAULT_TABLE_OPTIONS, DataAlignHorizontal, DataAlignVertical, DataType, ECSPrimengTable, ECSPrimengTableHttpService, ECSPrimengTableNotificationService, ECSPrimengTableService, FrozenColumnAlign, TableViewSaveMode, createTableOptions };
-export type { IColumnMetadata, IExcelExportRequest, IPredefinedFilter, ITableButton, ITableConfiguration, ITableOptions, ITablePagedResponse, ITableQueryRequest, ITableView, ITableViewData };
+export type { IColumnMetadata, IPredefinedFilter, ITableButton, ITableOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eternalcodestudio/primeng-table",
-  "version": "20.0.12",
+  "version": "20.0.13",
   "description": "ECS reusable Angular PrimeNG table component with advanced server-side filters. Designed to offload filtering logic to any backend API.",
   "author": "ECS (Eternal CODE Studio)",
   "license": "MIT",