@one-paragon/angular-utilities 2.8.2 → 2.8.4

package/src/table-builder/documentation/table-builder/TABLE-CONTAINER.md

@@ -0,0 +1,628 @@
+# Table Container Component Documentation
+
+## Overview
+
+`tb-table-container` is the main component for rendering data tables with the Table Builder system. It provides a feature-rich table with built-in support for sorting, filtering, grouping, pagination, column customization, virtual scrolling, row selection, and CSV export.
+
+## Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+
+@Component({
+  selector: 'app-my-table',
+  standalone: true,
+  imports: [TableContainerComponent],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder" />
+  `
+})
+export class MyTableComponent {
+  data = [
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+  ];
+
+  tableBuilder = new TableBuilder(this.data);
+}
+```
+
+## Inputs
+
+### Required Inputs
+
+#### `tableBuilder`
+- **Type**: `TableBuilder<T>`
+- **Required**: Yes
+- **Description**: The TableBuilder instance that defines the data, columns, and settings for the table.
+- **Related Documentation**: See [MetaData Documentation](METADATA-DOCUMENTATION.md) for column configuration and [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) for table behavior configuration.
+
+**Example:**
+```typescript
+import { TableBuilder } from 'angular-utilities';
+import { FieldType } from 'angular-utilities';
+
+const metaData = [
+  { key: 'id', fieldType: FieldType.Number, displayName: 'ID' },
+  { key: 'name', fieldType: FieldType.String, displayName: 'Name' },
+  { key: 'email', fieldType: FieldType.String, displayName: 'Email' }
+];
+
+const tableBuilder = new TableBuilder(data, metaData);
+```
+
+### Optional Inputs
+
+#### `tableId`
+- **Type**: `string | undefined`
+- **Default**: `undefined`
+- **Description**: Unique identifier for the table. When provided, the table state (sorting, filtering, column order, etc.) is automatically persisted to local storage and restored on component initialization. Can also be configured via `TableBuilderSettings.tableSettings.tableId` in the TableBuilder constructor. See [TableBuilder Settings - tableId](TABLE-BUILDER-SETTINGS.md#tableid).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  tableId="users-table" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  tableSettings: {
+    tableId: 'users-table'
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `trackBy`
+- **Type**: `string | undefined`
+- **Default**: `undefined`
+- **Description**: Property name to use for Angular's trackBy function in the table rows. Improves performance by helping Angular identify which items have changed. Can also be configured via `TableBuilderSettings.tableSettings.trackBy` in the TableBuilder constructor. See [TableBuilder Settings - trackBy](TABLE-BUILDER-SETTINGS.md#trackby).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  trackBy="id" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  tableSettings: {
+    trackBy: 'id'
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `inputFilters`
+- **Type**: `(Predicate<T> | CustomFilter<T> | FilterInfo<any, T>)[]`
+- **Default**: `[]`
+- **Description**: Array of filters to apply to the table data. Supports three types:
+  - **Predicate**: Simple function `(row: T) => boolean`
+  - **CustomFilter**: Object with `{ filterId: string, predicate: (row: T) => boolean }` - saved to state when `filterId` is provided
+  - **FilterInfo**: Full filter configuration object with UI and persistence support
+
+**Example:**
+```typescript
+// Simple predicate filter
+const activeOnly = (user: User) => user.isActive;
+
+// Custom filter with ID (persisted)
+const customFilter = {
+  filterId: 'active-filter',
+  predicate: (user: User) => user.isActive
+};
+
+// FilterInfo with full configuration
+const filterInfo = {
+  filterId: 'status-filter',
+  key: 'status',
+  type: FilterType.Equals,
+  value: 'active'
+};
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [inputFilters]="[activeOnly, customFilter]" />
+```
+
+#### `indexColumn`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Adds an index column as the first column, displaying row numbers starting from 1. Can also be configured via `TableBuilderSettings.tableSettings.includeIndexColumn` in the TableBuilder constructor. See [TableBuilder Settings - includeIndexColumn](TABLE-BUILDER-SETTINGS.md#includeindexcolumn).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [indexColumn]="true" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  tableSettings: {
+    includeIndexColumn: true
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `selectionColumn`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Adds a checkbox column for row selection. Listen to the `selection` output to receive selection changes. Can also be configured via `TableBuilderSettings.tableSettings.includeSelectionColumn` in the TableBuilder constructor. See [TableBuilder Settings - includeSelectionColumn](TABLE-BUILDER-SETTINGS.md#includeselectioncolumn).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [selectionColumn]="true"
+  (selection)="onSelectionChange($event)" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  tableSettings: {
+    includeSelectionColumn: true
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `stickyHeader`
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: Makes the table header sticky (fixed at the top when scrolling). Can also be configured via `TableBuilderSettings.columnHeaderSettings.stickyHeaderRow` in the TableBuilder constructor. See [TableBuilder Settings - stickyHeaderRow](TABLE-BUILDER-SETTINGS.md#stickyheaderrow).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [stickyHeader]="false" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  columnHeaderSettings: {
+    stickyHeaderRow: false
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `stickyFooter`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Makes the table footer sticky (fixed at the bottom when scrolling). Can also be configured via `TableBuilderSettings.columnFooterSettings.stickyFooterRow` in the TableBuilder constructor. See [TableBuilder Settings - stickyFooterRow](TABLE-BUILDER-SETTINGS.md#stickyfooterrow).
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [stickyFooter]="true" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  columnFooterSettings: {
+    stickyFooterRow: true
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+#### `groupHeaderTemplate`
+- **Type**: `TemplateRef<any> | undefined`
+- **Default**: `undefined`
+- **Description**: Custom template for rendering group headers when data is grouped. The template receives the group context with information about the group.
+
+**Example:**
+```typescript
+@Component({
+  template: `
+    <tb-table-container 
+      [tableBuilder]="tableBuilder"
+      [groupHeaderTemplate]="customGroupHeader" />
+    
+    <ng-template #customGroupHeader let-group>
+      <div class="custom-group-header">
+        {{ group.key }}: {{ group.count }} items
+      </div>
+    </ng-template>
+  `
+})
+```
+
+#### `groupHeaderHeight`
+- **Type**: `number | undefined`
+- **Default**: `undefined`
+- **Description**: Height in pixels for group header rows. Used for virtual scrolling calculations when grouping is enabled.
+
+**Example:**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [groupHeaderHeight]="48" />
+```
+
+#### `pageSize`
+- **Type**: `number | undefined`
+- **Default**: `undefined`
+- **Description**: Initial page size for pagination. This will be overridden if the user has already set a page size (which is persisted in state). Can also be configured via `TableBuilderSettings.tableSettings.paginatorSettings.pageSize` in the TableBuilder constructor. See [TableBuilder Settings - paginatorSettings](TABLE-BUILDER-SETTINGS.md#paginatorsettings) for configuring pagination behavior.
+
+**Example (via input):**
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  [pageSize]="25" />
+```
+
+**Example (via TableBuilder settings):**
+```typescript
+const settings = {
+  tableSettings: {
+    paginatorSettings: {
+      pageSize: 25
+    }
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+## Outputs
+
+#### `selection`
+- **Type**: `SelectionChange<T>`
+- **Description**: Emits when row selection changes. Only emits when `selectionColumn` is enabled. The event contains `added` and `removed` arrays of selected rows.
+
+**Example:**
+```typescript
+onSelectionChange(event: SelectionChange<User>) {
+  console.log('Added:', event.added);
+  console.log('Removed:', event.removed);
+  console.log('Current selection:', event.source.selected);
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  [selectionColumn]="true"
+  (selection)="onSelectionChange($event)" />
+```
+
+#### `onStateReset`
+- **Type**: `null`
+- **Description**: Emits when the table state is reset to defaults. This happens when the user clicks the reset button in the table header menu.
+
+**Example:**
+```typescript
+onStateReset() {
+  console.log('Table state has been reset');
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  (onStateReset)="onStateReset()" />
+```
+
+#### `onSaveState`
+- **Type**: `null`
+- **Description**: Emits when the table state is manually saved. This happens when the user clicks the save button in the table header menu.
+
+**Example:**
+```typescript
+onSaveState() {
+  console.log('Table state has been saved');
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  (onSaveState)="onSaveState()" />
+```
+
+#### `state`
+- **Type**: `PersistedTableState`
+- **Description**: Emits whenever the savable table state changes. The state includes sorting, filtering, column visibility, column order, grouping, and pagination settings. Useful for manually persisting state to a backend.
+
+**Example:**
+```typescript
+onStateChange(state: PersistedTableState) {
+  // Save to backend
+  this.tableService.saveTableState(state);
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  (state)="onStateChange($event)" />
+```
+
+#### `data`
+- **Type**: `T[]`
+- **Description**: Emits the current sorted and filtered data (without grouping applied). Updates whenever sorting or filtering changes.
+
+**Example:**
+```typescript
+onDataChange(data: User[]) {
+  console.log('Filtered/sorted data:', data);
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  (data)="onDataChange($event)" />
+```
+
+#### `sortedAndFilteredAndGroupedData`
+- **Type**: `(T | GroupHeader)[]`
+- **Description**: Emits the current sorted, filtered, and grouped data including group header rows. This is the actual data displayed in the table. Updates whenever sorting, filtering, or grouping changes.
+
+**Example:**
+```typescript
+onDisplayDataChange(data: (User | GroupHeader)[]) {
+  console.log('Display data with groups:', data);
+}
+```
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder"
+  (sortedAndFilteredAndGroupedData)="onDisplayDataChange($event)" />
+```
+
+## Public Methods
+
+The component exposes several public methods that can be called via template reference or ViewChild:
+
+### `clearSelections()`
+Clears all selected rows.
+
+**Example:**
+```typescript
+@ViewChild(TableContainerComponent) table!: TableContainerComponent;
+
+clearAll() {
+  this.table.clearSelections();
+}
+```
+
+### `firstPage()`
+Navigates to the first page of the table.
+
+### `lastPage()`
+Navigates to the last page of the table.
+
+### `expandAllGroups()`
+Expands all group headers when grouping is applied.
+
+### `expandAllOfGroup(groupKey: string)`
+Expands all headers for a specific group key.
+
+**Example:**
+```typescript
+expandDepartmentGroups() {
+  this.table.expandAllOfGroup('department');
+}
+```
+
+### `collapseAllGroups()`
+Collapses all group headers.
+
+### `exportToCsv()`
+Exports the current filtered and sorted data to CSV format and triggers a download.
+
+**Example:**
+```typescript
+@Component({
+  template: `
+    <tb-table-container 
+      #table
+      [tableBuilder]="tableBuilder" />
+    
+    <button (click)="table.exportToCsv()">
+      Export to CSV
+    </button>
+  `
+})
+```
+
+## Content Projection
+
+The component supports content projection for advanced customization:
+
+### Custom Cell Templates
+
+Use `CustomCellDirective` to provide custom rendering for specific columns:
+
+```typescript
+import { CustomCellDirective } from 'angular-utilities';
+
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <ng-template customCell="status" let-row>
+        <span [class]="'status-' + row.status">
+          {{ row.status }}
+        </span>
+      </ng-template>
+    </tb-table-container>
+  `
+})
+```
+
+### Custom Filter Directives
+
+Use `TableFilterDirective` or `TableCustomFilterDirective` for custom filtering UI:
+
+```typescript
+import { TableFilterDirective } from 'angular-utilities';
+
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <input 
+        tbFilter
+        filterId="search"
+        [key]="'name'"
+        [type]="FilterType.Contains"
+        placeholder="Search by name" />
+    </tb-table-container>
+  `
+})
+```
+
+### Custom Row Definitions
+
+Use `MatRowDef` to define custom row rendering:
+
+```typescript
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <tr *matRowDef="let row; columns: displayedColumns" 
+          [class.highlighted]="row.isImportant">
+      </tr>
+    </tb-table-container>
+  `
+})
+```
+
+## Complete Example
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { TableBuilder, TableContainerComponent, FieldType } from 'angular-utilities';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  isActive: boolean;
+}
+
+@Component({
+  selector: 'app-users-table',
+  standalone: true,
+  imports: [TableContainerComponent],
+  template: `
+    <tb-table-container 
+      #table
+      [tableBuilder]="tableBuilder"
+      tableId="users-table"
+      trackBy="id"
+      [selectionColumn]="true"
+      [indexColumn]="true"
+      [pageSize]="25"
+      [inputFilters]="filters"
+      (selection)="onSelectionChange($event)"
+      (data)="onDataChange($event)" />
+  `
+})
+export class UsersTableComponent {
+  @ViewChild('table') table!: TableContainerComponent<User>;
+
+  users: User[] = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', department: 'Engineering', isActive: true },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', department: 'Marketing', isActive: true }
+  ];
+
+  metaData = [
+    { key: 'id', fieldType: FieldType.Number, displayName: 'ID', width: '80px' },
+    { key: 'name', fieldType: FieldType.String, displayName: 'Name' },
+    { key: 'email', fieldType: FieldType.String, displayName: 'Email' },
+    { key: 'department', fieldType: FieldType.String, displayName: 'Department' },
+    { key: 'isActive', fieldType: FieldType.Boolean, displayName: 'Active' }
+  ];
+
+  tableBuilder = new TableBuilder(this.users, this.metaData);
+
+  filters = [
+    (user: User) => user.isActive // Only show active users
+  ];
+
+  onSelectionChange(event: any) {
+    console.log('Selected users:', event.source.selected);
+  }
+
+  onDataChange(data: User[]) {
+    console.log('Current data:', data);
+  }
+
+  exportData() {
+    this.table.exportToCsv();
+  }
+}
+```
+
+## State Persistence
+
+When a `tableId` is provided, the following state is automatically persisted to local storage:
+
+- Column visibility and order
+- Sort configuration
+- Applied filters (with `filterId`)
+- Group by settings
+- Page size
+- Expanded/collapsed group headers
+- Header/footer collapsed state
+
+The state is restored automatically when the component initializes with the same `tableId`.
+
+## Performance Considerations
+
+### Virtual Scrolling
+
+The table automatically enables virtual scrolling for large datasets. This is controlled by the `TableBuilderSettings`:
+
+```typescript
+const settings = {
+  tableSettings: {
+    useVirtual: true, // Enable virtual scrolling
+    virtualSettings: {
+      itemSize: 48, // Height of each row in pixels
+      bufferSize: 10 // Number of items to render outside viewport
+    }
+  }
+};
+```
+
+See [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) for more details.
+
+### TrackBy
+
+Always provide a `trackBy` property for optimal performance, especially with large datasets or frequent updates:
+
+```html
+<tb-table-container 
+  [tableBuilder]="tableBuilder" 
+  trackBy="id" />
+```
+
+## Related Documentation
+
+- [MetaData Documentation](METADATA-DOCUMENTATION.md) - Column configuration
+- [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) - Table behavior and appearance
+- [TableBuilder Config](TABLE-BUILDER-CONFIG.md) - Global configuration
+- [Styler Style Documentation](STYLER-STYLE.md) - Cell styling
+- [TableBuilder Documentation](TABLE-BUILDER.md) - Setting up the table builder
+- [CustomCell Directive](CUSTOM-CELL.md) - Custom cell templates
+- [CustomGroupRow Directive](CUSTOM-GROUP-ROW.md) - Custom group row templates

package/src/table-builder/enums/filterTypes.ts

@@ -0,0 +1,39 @@
+
+export const FilterType = {
+  NumberEquals: 'Equals',
+  NumberNotEqual: 'Does Not Equal',
+  NumberGreaterThan: 'Greater Than',
+  NumberLessThan: 'Less Than',
+  NumberBetween: 'Between',
+  StringEquals: 'Equals',
+  StringContains: 'Contains',
+  StringDoesNotContain: 'Does Not Contain',
+  StringStartWith: 'Start With',
+  StringEndsWith: 'Ends With',
+  DateIsOn: 'Is on',
+  DateIsNotOn: 'Is Not On',
+  DateOnOrAfter: 'On or After',
+  DateOnOrBefore: 'On or Before',
+  DateBetween: 'Between',
+  DateTimeIsAt: 'Is At',
+  DateTimeIsNotAt: 'Is Not At',
+  DateTimeAtOrAfter: 'At or After',
+  DateTimeAtOrBefore: 'At or Before',
+  DateTimeBetween: 'Between',
+  BooleanEquals: 'Is',
+  IsNull: 'Is Blank',
+  And: 'And',
+  In: 'In',
+  Custom: 'Custom',
+} as const;
+
+export type FilterType = typeof FilterType[keyof typeof FilterType];
+
+export type SubFilterTypes<T extends typeof FilterType[keyof typeof FilterType]> = T;
+
+export type StringFilterTypes = SubFilterTypes<'Equals' | 'Contains' | 'Does Not Contain' | 'Start With' | 'Ends With' | 'Is Blank' | 'In'>;
+export type NumberFilterTypes = SubFilterTypes<'Equals' | 'Does Not Equal' | 'Greater Than' | 'Less Than' | 'Between' | 'Is Blank' | 'In'>;
+export type DateFilterTypes = SubFilterTypes<'Is on' | 'Is Not On' | 'On or After' | 'On or Before' | 'Between' | 'Is Blank' | 'In'>;
+export type DateTimeFilterTypes = SubFilterTypes<'Is At' | 'Is Not At' | 'At or After' | 'At or Before' | 'Between' | DateFilterTypes>;
+export type BooleanFilterTypes = SubFilterTypes<'Is' | 'Is Blank'>;
+export type EnumFilterTypes = SubFilterTypes<'In' | 'Is Blank'>;

package/src/table-builder/functions/boolean-filter-function.ts

@@ -0,0 +1,12 @@
+import { FilterFunc, FilterFuncs, FilterInfo } from '../classes/filter-info';
+import { BooleanFilterTypes, FilterType } from '../enums/filterTypes';
+import { isNull } from './null-filter-function';
+
+const booleanEqualsFunc : FilterFunc<boolean> = (filterInfo:FilterInfo) => (val): boolean => {
+  return filterInfo.filterValue === val;
+}
+
+export const BooleanFilterFuncs: FilterFuncs<BooleanFilterTypes> = {
+  [FilterType.BooleanEquals]: booleanEqualsFunc,
+  [FilterType.IsNull]: isNull,
+};