@messaia/cdk 22.0.1-rc.19 → 22.0.1-rc.21

package/fesm2022/messaia-cdk.mjs

@@ -16982,7 +16982,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
             }] } });
 
 /**
- * A generic datasource for data-table
+ * @class TableDataSource
+ * @description Provides a server-backed data source with filtering, sorting, pagination,
+ * reloading, and row selection for an Angular Material table.
+ * @template TEntity - The entity type displayed by the table.
+ * @template TService - The service type used to retrieve entities.
  */
 class TableDataSource extends DataSource {
     service;
@@ -16990,180 +16994,176 @@ class TableDataSource extends DataSource {
     sorter;
     /**
      * @property _filterChange
-     * @description Represents a value that changes over time.
-     * Observers can subscribe to this BehaviorSubject to receive filter changes.
+     * @description Stores and emits the current free-text filter.
      * @type {BehaviorSubject<string>}
      */
     _filterChange = new BehaviorSubject('');
     /**
      * @property _reloadChange
-     * @description Represents a value that triggers reload actions.
-     * It is used to notify when a reload should occur by emitting a new value.
+     * @description Emits a new token whenever the table data must be reloaded.
      * @type {BehaviorSubject<number>}
      */
     _reloadChange = new BehaviorSubject(0);
     /**
      * @property onDataLoaded
-     * @description Event emitted after the data is loaded.
-     * It is a BehaviorSubject that holds pagination data or a null value if no data is loaded.
+     * @description Emits the latest pagination response after data loads successfully.
+     * The initial value is `null` until the first response is received.
      * @type {BehaviorSubject<Pagination<TEntity> | any>}
      */
     onDataLoaded = new BehaviorSubject(null);
     /**
      * @property selectionModel
-     * @description Used to power selecting one or more options from a list.
+     * @description Tracks the entities selected across the table.
      * @type {SelectionModel<TEntity>}
      */
     selectionModel = new SelectionModel(true, []);
     /**
      * @property filter
-     * @description Gets the current filter applied to the data.
+     * @description Gets the current free-text filter.
      * @type {string}
      */
     get filter() { return this._filterChange.value; }
     /**
      * @property filter
-     * @description Sets the filter and resets the page index if the paginator exists.
-     * @param {string} filter - The filter value to be applied.
+     * @description Sets the free-text filter and returns pagination to the first page.
+     * @param {string} filter - The filter text to apply.
      */
     set filter(filter) {
-        /* If paginator exists, reset the page index */
+        /* Reset the paginator and cached page index before applying the filter. */
         if (this.paginator) {
             this.paginator.pageIndex = 0;
             this.pageIndex = 0;
         }
-        /* Trigger filter change */
+        /* Publish the updated filter to connected table views. */
         this._filterChange.next(filter);
     }
     /**
      * @property onSortChange
-     * @description Sort change event emitter used to notify changes in sorting.
+     * @description Relays changes emitted by the assigned sort controller.
      * @type {EventEmitter<Sort>}
      */
     onSortChange = new EventEmitter();
     /**
      * @property _sort
-     * @description Private instance of MatSort used to control the sorting of the table.
-     * @type {MatSort | null}
+     * @description Stores the sort controller currently assigned to the data source.
+     * @type {MatSort | undefined}
      */
     _sort = new MatSort();
     /**
      * @property sort
-     * @description Gets or sets the MatSort instance used to control the sorting of the table.
-     * Changes in sorting will trigger an update to the table’s rendered data.
+     * @description Gets or sets the sort controller whose changes reload the table data.
      * @type {MatSort | undefined}
      */
     get sort() { return this._sort; }
     set sort(sort) {
-        /* Set the sort and subscribe to sort changes */
+        /* Store the controller and relay its sort changes. */
         this._sort = sort;
         this._sort?.sortChange.subscribe(x => this.onSortChange.emit(x));
     }
     /**
      * @property reloadToken
-     * @description Gets the current reload token, used to trigger reload events.
+     * @description Gets the token emitted by the most recent reload request.
      * @type {number}
      */
     get reloadToken() { return this._reloadChange.value; }
     /**
      * @property isConnected
-     * @description Flag indicating whether the data source is connected.
+     * @description Indicates whether a collection viewer is connected to the data source.
      * @type {boolean}
      */
     isConnected = false;
     /**
      * @property includes
-     * @description The list of navigations to be included in the data query.
+     * @description Lists the related resources to include in each data request.
      * @type {Array<string>}
      */
     includes = [];
     /**
      * @property path
-     * @description The endpoint path for the data source.
+     * @description Specifies the optional service endpoint path used to retrieve data.
      * @type {string | undefined}
      */
     path;
     /**
      * @property projection
-     * @description Defines the fields to be included in the data query projection.
+     * @description Specifies the fields requested from the service, either as a comma-separated
+     * string or an array of field names.
      * @type {string | string[]}
      */
     projection = '';
     /**
      * @property items
-     * @description The list of items to be displayed in the data table.
+     * @description Contains the entities returned for the current page.
      * @type {TEntity[]}
      */
     items = [];
     /**
      * @property parameters
-     * @description The parameters for pagination and sorting.
+     * @description Contains additional parameters returned by the latest data request.
      * @type {any}
      */
     parameters;
     /**
      * @property facets
-     * @description The list of facets for filtering items.
+     * @description Contains the facets returned by the latest data request.
      * @type {Facet[] | undefined}
      */
     facets;
     /**
      * @property fieldFilters
-     * @description A set of field filters applied to the data.
+     * @description Contains mutable field filters applied to data requests.
      * @type {any}
      */
     fieldFilters = {};
     /**
      * @property fieldOperators
-     * @description A set of field operators used for filtering.
+     * @description Contains operators associated with field-based filtering.
      * @type {any}
      */
     fieldOperators = {};
     /**
      * @property staticFieldFilters
-     * @description A set of static field filters applied to the data.
+     * @description Contains persistent field filters applied to every data request.
      * @type {any}
      */
     staticFieldFilters = {};
     /**
      * @property pageIndex
-     * @description The current page index for pagination.
+     * @description Stores the zero-based index of the current page.
      * @type {number}
      */
     pageIndex = 0;
     /**
      * @property total
-     * @description The current total number of items being paged.
+     * @description Stores the total number of entities reported by the service.
      * @type {number}
      */
     total = 0;
     /**
      * @property pageSize
-     * @description The number of items displayed per page in the data-table.
-     * It controls how many records are shown on a single page.
+     * @description Stores the number of entities requested per page.
      * @type {number}
      */
     pageSize = 15;
     /**
      * @property pageCount
-     * @description The total number of pages based on pagination.
+     * @description Stores the total number of pages reported by the service.
      * @type {number}
      */
     pageCount = 0;
     /**
      * @property isLoading
-     * @description Flag to show the loading process when the data is being fetched.
+     * @description Indicates whether a data request is currently in progress.
      * @type {boolean}
      */
     isLoading = false;
     /**
      * @constructor
-     * @description Initializes a new instance of the class and sets up the service, paginator, and sorter.
-     * The paginator and sorter are optional parameters used for handling pagination and sorting logic
-     * for the data displayed in the table.
-     * @param {TService} service - The service used for fetching and managing data.
-     * @param {MatPaginator} [paginator] - The paginator instance used for pagination functionality.
-     * @param {MatSort} [sorter] - The MatSort instance used for sorting functionality.
+     * @description Creates a data source backed by the supplied service and optional Material
+     * pagination and sorting controllers.
+     * @param {TService} service - The service used to retrieve table data.
+     * @param {MatPaginator} [paginator] - The controller used for server-side pagination.
+     * @param {MatSort} [sorter] - The controller used for server-side sorting.
      */
     constructor(service, paginator, sorter) {
         super();
@@ -17173,32 +17173,33 @@ class TableDataSource extends DataSource {
         this.sort = sorter;
     }
     /**
-     * Connects a collection viewer (such as a data-table) to this data source.
-     * @param _ The component that exposes a view over the data provided by this
-     *     data source.
-     * @returns Observable that emits a new value when the data changes.
+     * @method connect
+     * @description Connects a collection viewer and reloads server data when sorting,
+     * pagination, filtering, or the reload token changes.
+     * @param {CollectionViewer} [_] - The viewer that consumes the emitted entities.
+     * @returns {Observable<TEntity[]>} An observable that emits the current page of entities.
      */
     connect(_) {
         this.isConnected = true;
-        /* A list of fields to observe  */
+        /* Collect every source that can trigger a data request. */
         const displayDataChanges = [
             this.onSortChange,
             this.paginator?.page,
             this._filterChange,
             this._reloadChange
         ];
-        /* If the user changes the sort order, reset back to the first page */
+        /* Return to the first page whenever the sort order changes. */
         if (this.paginator) {
             this.onSortChange.subscribe(() => { this.paginator.pageIndex = 0; });
         }
         return merge$1(...displayDataChanges)
             .pipe(skip(1), switchMap$1(() => {
-            /* Flip flag to show that loading has begun */
+            /* Mark the data source as loading before issuing the request. */
             this.isLoading = true;
-            /* Remove empty filters */
+            /* Remove empty values from mutable and persistent field filters. */
             Utils.cleanObject(this.fieldFilters);
             Utils.cleanObject(this.staticFieldFilters);
-            /* Build parameters for the data query */
+            /* Compose the service request from table state and field filters. */
             var params = Object.assign({
                 includes: this.includes,
                 projection: Array.isArray(this.projection) ? this.projection.join(',') : this.projection,
@@ -17208,12 +17209,12 @@ class TableDataSource extends DataSource {
                 sortBy: this.sort?.active,
                 sortOrder: this.sort?.direction
             }, this.fieldFilters ?? {}, this.staticFieldFilters ?? {});
-            /* Load data and return it */
+            /* Retrieve the current page from the configured service endpoint. */
             return this.service.getList(Utils.cleanObject(params), this.path ?? '', { 'CheckOut': 'Yes' });
         }), map$1((result) => {
-            /* Flip flag to show that loading has finished */
+            /* Clear the loading state after receiving a response. */
             this.isLoading = false;
-            /* Update pagination fields */
+            /* Synchronize rows, pagination metadata, facets, and response parameters. */
             this.pageIndex = Math.max(Math.min(result.page - 1, result.pageCount - 1), 0);
             this.total = result.total;
             this.pageSize = result.pageSize;
@@ -17221,28 +17222,29 @@ class TableDataSource extends DataSource {
             this.items = result.items;
             this.facets = result.facets;
             this.parameters = result.parameters;
-            /* Raise onload event */
+            /* Notify subscribers that the response has been applied. */
             this.onDataLoaded.next(result);
             return this.items;
         }), catchError(() => {
-            /* Flip flag to show that loading has finished */
+            /* Clear the loading state and emit an empty page after a request failure. */
             this.isLoading = false;
             return of([]);
         }));
     }
     /**
-     * Disconnects a collection viewer (such as a data-table) from this data source. Can be used
-     * to perform any clean-up or tear-down operations when a view is being destroyed.
-     *
-     * @param _ The component that exposes a view over the data provided by this
-     *     data source.
+     * @method disconnect
+     * @description Marks the data source as disconnected from its collection viewer.
+     * @param {CollectionViewer} _ - The viewer that no longer consumes this data source.
+     * @returns {void}
      */
     disconnect(_) {
         this.isConnected = false;
     }
     /**
-     * Reloads items
-     * @param clearSelection
+     * @method reload
+     * @description Requests fresh data and optionally clears the current row selection.
+     * @param {boolean} [clearSelection=true] - Whether to clear selected entities.
+     * @returns {void}
      */
     reload(clearSelection = true) {
         this._reloadChange.next(Math.random());
@@ -17251,21 +17253,31 @@ class TableDataSource extends DataSource {
         }
     }
     /**
-     * Clears field filters
+     * @method applyFilters
+     * @description Replaces the mutable field filters and requests fresh data.
+     * @param {any} [newFilters={}] - The field filters to apply.
+     * @returns {void}
      */
     applyFilters(newFilters = {}) {
         this.fieldFilters = newFilters || {};
         this.reload();
     }
     /**
-     * Clears field filters
+     * @method clearFilters
+     * @description Resets mutable field filters to the supplied object, or to an empty object
+     * when no replacement is supplied, and requests fresh data.
+     * @param {any} [newFilters={}] - Optional field filters retained after the reset.
+     * @returns {void}
      */
     clearFilters(newFilters = {}) {
         this.fieldFilters = newFilters || {};
         this.reload();
     }
     /**
-     * Checks, whether all items are selected
+     * @method isAllSelected
+     * @description Determines whether the selected entity count matches the total entity count.
+     * An empty selection is never considered complete.
+     * @returns {boolean} `true` when every reported entity is selected; otherwise, `false`.
      */
     isAllSelected() {
         if (this.selectionModel.isEmpty()) {
@@ -17274,9 +17286,13 @@ class TableDataSource extends DataSource {
         return this.selectionModel.selected.length === this.total;
     }
     /**
-     * Toggles selected items
-     * @param checkbox
-     * @param predicate
+     * @method toggleSelect
+     * @description Clears an existing selection or selects each unlocked entity on the current
+     * page that satisfies the optional predicate.
+     * @param {MatCheckboxChange} checkbox - The select-all checkbox change event.
+     * @param {(value: TEntity, index: number, array: TEntity[]) => unknown} [predicate] - Optional
+     * condition used to choose selectable entities.
+     * @returns {void}
      */
     toggleSelect(checkbox, predicate) {
         if (this.selectionModel.hasValue()) {
@@ -17293,11 +17309,23 @@ class TableDataSource extends DataSource {
         }
     }
     /**
-     * Get selected Items
+     * @property getSelected
+     * @description Maps selected entities to the values stored under the specified property key.
+     * @template TType - The expected property value type.
+     * @param {string} key - The entity property key to read.
+     * @returns {TType[]} The selected property values.
      */
     getSelected = (key) => this.selectionModel.selected.map(x => x[key]);
     /**
-     * Get selected Items
+     * @property getSelectedItems
+     * @description Gets all currently selected entities.
+     * @returns {TEntity[]} The selected entities.
+     */
+    getSelectedItems = () => this.selectionModel.selected;
+    /**
+     * @property getSelectedIds
+     * @description Gets the numeric identifiers of all selected entities.
+     * @returns {number[]} The selected entity identifiers.
      */
     getSelectedIds = () => this.getSelected('id');
 }