@eternalcodestudio/primeng-table 20.0.8 → 20.0.10

package/index.d.ts

@@ -5,15 +5,56 @@ 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>;
@@ -86,21 +127,12 @@ interface ITableButton {
     tooltip?: string;
 }
 
-/**
- * Interface representing the request structure for PrimeNG post requests.
- */
 interface ITableQueryRequest {
-    /** Gets or sets the current page number.*/
     page: number;
-    /** Gets or sets the number of items to display per page.*/
     pageSize: number;
-    /** Gets or sets a list of sorting configurations for the table.*/
     sort?: any;
-    /** Gets or sets a dictionary containing filter configurations for each column.*/
     filter: any;
-    /** Gets or sets a global filter string applied to all columns.*/
     globalFilter?: string | null;
-    /** Gets or sets a list of columns to be included in the response.*/
     columns?: string[];
     dateFormat: string;
     dateTimezone: string;
@@ -311,6 +343,12 @@ interface IPredefinedFilter {
      * **_Do not modify this property manually._**
      */
     imageBlobFetchError?: boolean;
+    /**
+     * Optional. The action to execute when the predefined filter is clicked.
+     * @param rowData The row data object of the clicked row.
+     * @param option The IPredefinedFilter data of the predefined element clicked.
+     */
+    action?: (rowData: any, option: IPredefinedFilter) => void;
 }
 
 interface ITableConfiguration {
@@ -366,11 +404,39 @@ interface ITableOptions {
      * @default []
      */
     data?: any[];
+    /**
+     * Configurations related to options that are at the header of the table.
+     */
     header?: {
+        /**
+         * A collection of `ITableButton` to be shown in the table header.
+         *
+         * @default []
+         */
         buttons?: ITableButton[];
+        /**
+         * When set to `false`, the **clear sorts** button will be hidden.
+         *
+         * @default true
+         */
         clearSortsEnabled?: boolean;
+        /**
+         * Allows customization of the **clear sorts** button icon. You may use any other icons from PrimeNG or third-party providers such as Material Icons or Font Awesome.
+         *
+         * @default "pi pi-sort-alt-slash"
+         */
         clearSortsIcon?: string;
+        /**
+         * When set to `false`, the **clear filters** button will be hidden.
+         *
+         * @default true
+         */
         clearFiltersEnabled?: boolean;
+        /**
+         * Allows customization of the **clear filters** button icon. Other icons from PrimeNG or third-party libraries (e.g., Material Icons, Font Awesome) may also be used.
+         *
+         * @default "pi pi-filter-slash"
+         */
         clearFiltersIcon?: string;
     };
     /**
@@ -391,6 +457,12 @@ interface ITableOptions {
          * @default true
          */
         selectorEnabled?: boolean;
+        /**
+         * Can be used to specifiy a different icon to be used by the column selector.
+         * You can replace it with any icon from PrimeNG or other libraries such as Font Awesome or Material Icons.
+         *
+         * @default "pi pi-pen-to-square"
+         */
         selectorIcon?: string;
         /**
          * The combination of non-selectable columns and user-selected columns
@@ -404,30 +476,151 @@ interface ITableOptions {
      * Configurations related to the rows of the table.
      */
     rows?: {
+        /**
+         * Function to dynamically assign CSS classes to a row.
+         *
+         * Receives the `rowData` object for the current row and returns:
+         * - A string with a single CSS class name
+         * - An array of class names
+         * - A Set of class names
+         * - An object with class keys and truthy/falsy values
+         *
+         * The returned classes are applied to the row in addition to any global or default styles.
+         * Useful for changing appearance of a row based on column values.
+         *
+         * Example:
+         * ```ts
+         * class: (rowData) => {
+         *   const classes = [];
+         *   if (rowData.status === "Unemployed") classes.push("unemployedRow");
+         *   return classes;
+         * }
+         * ```
+         */
         class?: (rowData: any) => string | string[] | Set<string> | {
             [klass: string]: any;
         };
+        /**
+         * Function to dynamically assign inline styles to a row.
+         *
+         * Receives the `rowData` object for the current row and returns an object
+         * with CSS properties to apply inline. This allows dynamic styling based
+         * on the row's content or values.
+         *
+         * If not provided, no dynamic styles are applied.
+         *
+         * Example:
+         * ```ts
+         * style: (rowData) => {
+         *   if (rowData.status === "Full-time") {
+         *     return { fontWeight: "bold", fontStyle: "italic" };
+         *   }
+         *   return {};
+         * }
+         * ```
+         */
         style?: (rowData: any) => {
             [klass: string]: any;
         };
+        /**
+         * Configurations related to the action column for the rows.
+         */
         action?: {
+            /**
+             * A collection of `ITableButton` to be shown by this column to perform actions over rows. At least one button needs to be enable the row actions column.
+             *
+             * @default []
+             */
             buttons?: ITableButton[];
+            /**
+             * The header label for the row actions column.
+             *
+             * @default "Actions"
+             */
             header?: string;
+            /**
+             * If `true`, the column will appear on the right side of the table. Otherwise, it will appear on the left.
+             *
+             * @default true
+             */
             alignmentRight?: boolean;
+            /**
+             * The fixed column width in pixels.
+             *
+             * @default 150
+             */
             width?: number;
+            /**
+             * If `true`, the column remains visible when horizontally scrolling the table.
+             *
+             * @default true
+             */
             frozen?: boolean;
+            /**
+             * If `true`, users can resize the column.
+             *
+             * @default false
+             */
             resizable?: boolean;
         };
+        /**
+         * Configurations related to the row checkbox selector.
+         */
         checkboxSelector?: {
+            /**
+             * If `true`, a new column with checkboxes will be displayed. Users can select or unselect rows using these checkboxes. Additionally an option to filter by this column will be enabled.
+             *
+             * @default false
+             */
             enabled?: boolean;
+            /**
+             * The header label for the checkbox selection column.
+             *
+             * @default "Selected"
+             */
             header?: string;
+            /**
+             * If `true`, the column will appear on the right side of the table. Otherwise, it will appear on the left.
+             *
+             * @default false
+             */
             alignmentRight?: boolean;
+            /**
+             * The fixed column width in pixels.
+             *
+             * @default 150
+             */
             width?: number;
+            /**
+             * If `true`, the column remains visible when horizontally scrolling the table.
+             *
+             * @default true
+             */
             frozen?: boolean;
+            /**
+             * If `true`, users can resize the column.
+             *
+             * @default false
+             */
             resizable?: boolean;
         };
+        /**
+         * Configurations related to the single row selector.
+         */
         singleSelector?: {
+            /**
+             * If set to `true`, users can click a row to select it. You can then subscribe to selection events to execute custom actions.
+             *
+             * @default false
+             */
             enabled?: boolean;
+            /**
+             * When `true`, users must hold **CTRL** and click on a selected row to unselect it. When `false`, users can unselect a row simply by clicking it again.
+             *
+             * On mobile devices (phones or tablets), the **CTRL** key configuration is ignored. Users can unselect a previously selected row by simply clicking it, as mobile devices do not have a **CTRL** key.
+             *
+             * @default true
+             */
             metakey?: boolean;
         };
     };
@@ -439,14 +632,17 @@ interface ITableOptions {
          * When set to `true`, the table will calculate the maximum height dynamically
          * so that it exactly fits its container. This takes precedence over the `height` property.
          *
+         * Ignored if a `cssFormula` has been provided.
+         *
          * @default true
          */
         fitToContainer?: boolean;
         /**
          * Fixed vertical height for the table when `fitToContainer` is `false`.
          *
+         * - If a `cssFormula` has been provided, this property is ignored.
          * - If `fitToContainer` from `verticalScroll` is `true`, this property is ignored.
-         * - If set to a value `<= 0`, this is ignored and there will be only verticall scroll enabled if `fitToContainer` from `verticalScroll` is `true`.
+         * - If set to a value `<= 0`, this is ignored.
          *
          * Use this property to enable vertical scrolling with a fixed height when you do not want
          * the table to dynamically fit its container.
@@ -454,6 +650,15 @@ interface ITableOptions {
          * @default 0
          */
         height?: number;
+        /**
+         * A CSS string used to define the table's vertical height.
+         *
+         * Can be a fixed value (e.g., `"500px"`) or a CSS formula (e.g., `"calc(100vh - 200px)"`).
+         * When provided, this value **overrides** both `fitToContainer` and `height`.
+         *
+         * @default undefined
+         */
+        cssFormula?: string;
     };
     /** Configurations related to the global filter functionality of the table. */
     globalFilter?: {
@@ -475,6 +680,15 @@ interface ITableOptions {
          */
         maxLength?: number;
     };
+    /**
+     * Predefined filters for table columns.
+     *
+     * Restricts filter options to a known set of values for a column.
+     * Suitable for columns with a limited number of distinct values.
+     * Supports plain text, tags, icons, and images. Works with `list` data types.
+     *
+     * @default {}
+     */
     predefinedFilters?: {
         [key: string]: IPredefinedFilter[];
     };
@@ -561,21 +775,19 @@ interface ITableOptions {
          */
         titleAllowUserEdit?: boolean;
     };
+    /**
+     * Defines the number of seconds the user must hold the mouse button on a cell before its content is copied to the clipboard. Set to a value <= 0 to turn off this feature entirely
+     *
+     * @default 0.5
+     */
     copyToClipboardTime?: number;
 }
 declare const DEFAULT_TABLE_OPTIONS: ITableOptions;
 
-/**
- * Interface representing the return structure for PrimeNG post requests when gathering data to represent in a table.
- */
 interface ITablePagedResponse {
-    /** The current page number.*/
     page: number;
-    /** Total number of records available from filter.*/
     totalRecords: number;
-    /** Total number of records available (without filters).*/
     totalRecordsNotFiltered: number;
-    /** Dynamic data representing the response content of data for the table.*/
     data: any;
 }
 
@@ -625,6 +837,7 @@ declare class ECSPrimengTableService {
      * handleButtonsClick(deleteAction, { rowID: 1, name: 'John Doe' });
      */
     handleButtonsClick(action: (rowData: any) => void, rowData?: any): void;
+    handlePredefinedFilterClick(action: (rowData: any, option: IPredefinedFilter) => void, rowData: any | undefined, option: IPredefinedFilter): void;
     getColumnStyle(col: any, headerCols?: boolean): Record<string, string>;
     fetchTableViews(tableViewSaveAs: TableViewSaveMode, recoverListEndpoint: string, tableViewSaveKey: string): ITableView[] | Observable<HttpResponse<ITableView[]>>;
     sortViews(tableSaveViewList: ITableView[]): void;
@@ -770,7 +983,6 @@ declare class ECSPrimengTable implements OnInit, AfterViewInit {
      * @returns {string} A string indicating the number of selected values for the specified column.
      */
     predefinedFiltersSelectedValuesText(columnKeyName: string): string;
-    handleButtonsClick(action: (rowData: any) => void, rowData?: any): void;
     /**
      * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eternalcodestudio/primeng-table",
-  "version": "20.0.8",
+  "version": "20.0.10",
   "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",