@one-paragon/angular-utilities 2.8.3 → 2.8.4

package/src/table-builder/documentation/table-builder/TABLE-BUILDER-SETTINGS.md

@@ -0,0 +1,515 @@
+# TableBuilderSettings Documentation
+
+## Overview
+
+`TableBuilderSettings` is the main configuration interface for customizing the appearance and behavior of the Table Builder component. It provides fine-grained control over headers, footers, column behavior, table functionality, and more.
+
+## Main Settings Interface
+
+```typescript
+interface TableBuilderSettings<T = any> {
+  headerSettings?: Partial<TableWrapperHeaderSettings>;
+  footerSettings?: Partial<TableWrapperFooterSettings>;
+  columnHeaderSettings?: Partial<TableColumnHeaderSettings>;
+  columnFooterSettings?: Partial<TableColumnFooterSettings>;
+  tableSettings?: Partial<TableSettings<T>>;
+}
+```
+
+---
+
+## Header Settings
+
+Controls the table's wrapper header (the toolbar area above the table).
+
+### `headerSettings: TableWrapperHeaderSettings`
+
+#### `hideExport`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Hides the export button from the header toolbar.
+
+#### `hideFilter`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Hides the filter button from the header toolbar.
+
+#### `hideColumnSettings`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Hides the column settings button from the header toolbar. Column settings allow users to reorder columns and show/hide columns.
+
+#### `hideSort`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Hides the sort menu button from the header toolbar.
+
+#### `hideHeader`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Completely hides the entire header wrapper.
+
+#### `collapse`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Initially collapses the header toolbar. User can toggle it open.
+
+#### `showTitleWhenCollapsed`
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: When header is collapsed, still shows the title text.
+
+#### `title`
+- **Type**: `TbTitle | undefined`
+- **Default**: `undefined`
+- **Description**: Configuration for the table title.
+- **Properties**:
+  - **`text`**: `string` (required) - The title text to display
+  - **`level`**: `1 | 2 | 3 | 4 | 5 | 6` - HTML heading level (h1-h6)
+  - **`styles`**: `Dictionary<string>` - Custom CSS styles for the title
+- **Example**:
+  ```typescript
+  title: {
+    text: 'User Management',
+    level: 2,
+    styles: { 'color': '#333', 'font-weight': 'bold' }
+  }
+  ```
+
+#### `headerHeight`
+- **Type**: [`TbSize`](#tbsize-type) | `undefined`
+- **Default**: `undefined`
+- **Description**: Sets a specific height for the header. Can be a number (pixels) or a string like `'56px'` or `'3.5rem'`.
+
+**Example**:
+```typescript
+headerSettings: {
+  hideExport: true,
+  collapse: false,
+  title: {
+    text: 'Employee List',
+    level: 3
+  }
+}
+```
+
+---
+
+## Footer Settings
+
+Controls the table's wrapper footer (the area below the table).
+
+### `footerSettings: TableWrapperFooterSettings`
+
+#### `collapse`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Initially collapses the footer section. User can toggle it open.
+
+**Example**:
+```typescript
+footerSettings: {
+  collapse: true
+}
+```
+
+---
+
+## Column Header Settings
+
+Controls the column header row (where column names and filter inputs appear).
+
+### `columnHeaderSettings: TableColumnHeaderSettings`
+
+#### `stickyHeaderRow`
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: Makes the column header row stick to the top when scrolling.
+
+#### `noFilters`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Hides all column filter inputs in the header row.
+
+#### `noHeader`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Completely hides the column header row (both column names and filters).
+
+**Example**:
+```typescript
+columnHeaderSettings: {
+  stickyHeaderRow: true,
+  noFilters: false
+}
+```
+
+---
+
+## Column Footer Settings
+
+Controls the column footer row (where aggregations like sums might appear).
+
+### `columnFooterSettings: TableColumnFooterSettings`
+
+#### `stickyFooterRow`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Makes the column footer row stick to the bottom when scrolling.
+
+**Example**:
+```typescript
+columnFooterSettings: {
+  stickyFooterRow: true
+}
+```
+
+---
+
+## Table Settings
+
+The core configuration for table functionality, rows, pagination, virtualization, and more.
+
+### `tableSettings: TableSettings<T>`
+
+#### `tableId`
+- **Type**: `string | undefined`
+- **Default**: `undefined`
+- **Description**: Unique identifier for the table. Used for persisting user preferences (column visibility, sort order, etc.) across sessions.
+
+#### `trackBy`
+- **Type**: `string | ((item: T) => any) | undefined`
+- **Default**: `undefined`
+- **Description**: Property name or function to track rows by for Angular's change detection optimization. Improves performance when data changes. If no `trackBy` is provided, Table Builder will automatically track by an internally added property (symbol `initIndexSymbol`).
+- **Example**:
+  ```typescript
+  trackBy: 'id'
+  // or
+  trackBy: (item) => item.userId
+  ```
+
+#### `includeIndexColumn`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Adds a column showing the row index/number.
+
+#### `includeSelectionColumn`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Adds a column with checkboxes for row selection.
+
+#### `usePaginator`
+- **Type**: `boolean | undefined`
+- **Default**: `true`
+- **Description**: Enables pagination controls for the table.
+
+#### `useVirtualScroll`
+- **Type**: `boolean | undefined`
+- **Default**: `false`
+- **Description**: Enables virtual scrolling for large datasets (renders only visible rows for performance).
+
+#### `paginatorSettings`
+- **Type**: `Partial<PaginatorOptions> | undefined`
+- **Default**: `undefined`
+- **Description**: Configuration for pagination behavior. See [Paginator Options](#paginator-options) section below.
+
+#### `virtualScrollSettings`
+- **Type**: `Partial<VirtualScrollOptions> | undefined`
+- **Default**: `undefined`
+- **Description**: Configuration for virtual scrolling. See [Virtual Scroll Options](#virtual-scroll-options) section below.
+
+#### `rowHeight`
+- **Type**: [`TbSize`](#tbsize-type) | `undefined`
+- **Default**: `undefined`
+- **Description**: Sets a specific height for table rows. Can be a number (pixels) or a string like `'48px'` or `'3rem'`.
+
+#### `groupHeaderHeight`
+- **Type**: [`TbSize`](#tbsize-type) | `undefined`
+- **Default**: `undefined`
+- **Description**: Sets a specific height for group header rows when using grouping.
+
+#### `minColumnWidth`
+- **Type**: [`TbSize`](#tbsize-type) | `undefined`
+- **Default**: `undefined`
+- **Description**: Sets a minimum width for all columns.
+
+#### `rowClasses`
+- **Type**: `Dictionary<Predicate<T> | true> | undefined`
+- **Default**: `undefined`
+- **Description**: CSS classes to apply to rows. Keys are class names, values are predicates that determine when to apply the class.
+- **Example**:
+  ```typescript
+  rowClasses: {
+    'highlight-row': (row) => row.isPriority,
+    'inactive-row': (row) => !row.isActive,
+    'even-row': true  // applies to all rows
+  }
+  ```
+
+#### `rowStyles`
+- **Type**: [`StylerStyle<T>`](./STYLER-STYLE.md) | `undefined`
+- **Default**: `undefined`
+- **Description**: Dynamic inline styles applied to rows based on row data. See [StylerStyle documentation](./STYLER-STYLE.md) for detailed usage patterns.
+- **Example**:
+  ```typescript
+  rowStyles: (row) => ({
+    'background-color': row.status === 'error' ? '#ffebee' : 'transparent',
+    'font-weight': row.isPriority ? 'bold' : 'normal'
+  })
+  ```
+
+#### `rowClick`
+- **Type**: `((row: T, event?: MouseEvent) => void) | undefined`
+- **Default**: `undefined`
+- **Description**: Click handler for rows.
+- **Example**:
+  ```typescript
+  rowClick: (row, event) => {
+    console.log('Clicked row:', row);
+    this.router.navigate(['/details', row.id]);
+  }
+  ```
+
+#### `exportSettings`
+- **Type**: `TableBuilderExport | undefined`
+- **Default**: `undefined`
+- **Description**: Global export settings for the table. See the [METADATA-DOCUMENTATION.md](./METADATA-DOCUMENTATION.md#export-configuration) for details on export options.
+
+#### `groupBySettings`
+- **Type**: `Array<{ key: Path<T>, expanded?: boolean }>`
+- **Default**: `[]`
+- **Description**: Configures row grouping by one or more columns.
+- **Properties**:
+  - **`key`**: Column key to group by (type-safe property path)
+  - **`expanded`**: Whether groups should be initially expanded (`true`) or collapsed (`false`)
+- **Example**:
+  ```typescript
+  groupBySettings: [
+    { key: 'department', expanded: true },
+    { key: 'status', expanded: false }
+  ]
+  ```
+
+---
+
+## Paginator Options
+
+Configuration for table pagination.
+
+### `paginatorSettings: PaginatorOptions`
+
+#### `pageSize`
+- **Type**: `number | undefined`
+- **Default**: Configured via `TableBuilderConfig` (typically `10`)
+- **Description**: Number of rows to display per page.
+
+#### `defaultAll`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: When `true`, automatically includes "All" option in page size selector, sets `includeAllInOptions` to `true`, and defaults the table to use the virtual scroll view for better performance.
+
+#### `includeAllInOptions`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Adds an "All" option to the page size selector to show all rows on one page.
+
+**Example**:
+```typescript
+paginatorSettings: {
+  pageSize: 25,
+  includeAllInOptions: true
+}
+```
+
+---
+
+## Virtual Scroll Options
+
+Configuration for virtual scrolling (recommended for tables with 100+ rows).
+
+### `virtualScrollSettings: VirtualScrollOptions`
+
+#### `rowHeight`
+- **Type**: [`TbSize`](#tbsize-type)
+- **Default**: `48` (pixels)
+- **Description**: Height of each row. Required for virtual scroll calculations.
+
+#### `enforceRowHeight`
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: When `true`, strictly enforces the specified row height via CSS.
+
+#### `headerHeight`
+- **Type**: [`TbSize`](#tbsize-type)
+- **Default**: `56` (pixels)
+- **Description**: Height of the column header row.
+
+#### `enforceHeaderHeight`
+- **Type**: `boolean`
+- **Default**: `true`
+- **Description**: When `true`, strictly enforces the specified header height via CSS.
+
+#### `amountOfVisibleItems`
+- **Type**: `number`
+- **Default**: `10`
+- **Description**: Number of rows to show in the viewport. Determines the viewport height unless `maxViewPortHeight` is specified.
+
+#### `maxViewPortHeight`
+- **Type**: [`TbSize`](#tbsize-type) | `undefined`
+- **Default**: `undefined`
+- **Description**: Maximum height for the table viewport. Takes precedence over `amountOfVisibleItems`.
+
+#### `dynamicHeight`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: When `true`, attempts to expand the table to fill available space to the bottom of the screen.
+  - If `amountOfVisibleItems` is set, that becomes the minimum number of rows
+  - If `maxViewPortHeight` is set, that becomes the maximum table size
+
+#### `dynamicalHeightBuffer`
+- **Type**: [`TbSize`](#tbsize-type)
+- **Default**: `0`
+- **Description**: When `dynamicHeight` is `true`, leaves this amount of space from the bottom of the viewport.
+
+**Example**:
+```typescript
+virtualScrollSettings: {
+  rowHeight: 60,
+  enforceRowHeight: true,
+  headerHeight: 64,
+  amountOfVisibleItems: 15,
+  dynamicHeight: true,
+  dynamicalHeightBuffer: '2rem'
+}
+```
+
+---
+
+## TbSize Type
+
+`TbSize` is a flexible size type used throughout the settings:
+
+```typescript
+type TbSize = number | `${number}${'px' | 'rem'}`;
+```
+
+**Examples**:
+- `48` - Number interpreted as pixels
+- `'48px'` - Explicit pixel value
+- `'3rem'` - Rem units (relative to root font size)
+
+---
+
+## Complete Example
+
+```typescript
+const tableSettings: TableBuilderSettings<User> = {
+  headerSettings: {
+    hideExport: false,
+    hideFilter: false,
+    collapse: false,
+    title: {
+      text: 'User Management Dashboard',
+      level: 2,
+      styles: { 'color': '#1976d2' }
+    },
+    headerHeight: '64px'
+  },
+  
+  footerSettings: {
+    collapse: false
+  },
+  
+  columnHeaderSettings: {
+    stickyHeaderRow: true,
+    noFilters: false
+  },
+  
+  columnFooterSettings: {
+    stickyFooterRow: true
+  },
+  
+  tableSettings: {
+    tableId: 'user-management-table',
+    trackBy: 'userId',
+    includeIndexColumn: false,
+    includeSelectionColumn: true,
+    
+    usePaginator: false,
+    useVirtualScroll: true,
+    
+    virtualScrollSettings: {
+      rowHeight: 56,
+      enforceRowHeight: true,
+      headerHeight: 64,
+      amountOfVisibleItems: 20,
+      dynamicHeight: true,
+      dynamicalHeightBuffer: '1rem'
+    },
+    
+    rowHeight: 56,
+    groupHeaderHeight: 48,
+    minColumnWidth: '100px',
+    
+    rowClasses: {
+      'highlight-admin': (user) => user.role === 'admin',
+      'inactive-user': (user) => !user.isActive
+    },
+    
+    rowStyles: (user) => ({
+      'opacity': user.isActive ? '1' : '0.6',
+      'font-weight': user.isPremium ? 'bold' : 'normal'
+    }),
+    
+    rowClick: (user, event) => {
+      console.log('User clicked:', user.name);
+      // Navigate or show details
+    },
+    
+    exportSettings: {
+      dateFormat: 'MM/dd/yyyy',
+      dateTimeFormat: 'MM/dd/yyyy HH:mm:ss',
+      mapEnumToString: true,
+      mapLink: 'as view'
+    },
+    
+    groupBySettings: [
+      { key: 'department', expanded: true },
+      { key: 'status', expanded: false }
+    ]
+  }
+};
+```
+
+---
+
+## Usage with TableBuilderConfig
+
+You can set default settings globally using `provideTableBuilder`. See [TableBuilderConfig Documentation](./TABLE-BUILDER-CONFIG.md) for detailed information about global configuration options.
+
+```typescript
+// In your app.config.ts or main.ts
+import { provideTableBuilder } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideTableBuilder({
+      defaultTableSettings: {
+        pageSize: 25,
+        tableSettings: {
+          usePaginator: true,
+          exportSettings: {
+            dateFormat: 'MM/dd/yyyy',
+            mapEnumToString: true
+          }
+        },
+        headerSettings: {
+          showTitleWhenCollapsed: true
+        }
+      }
+    })
+  ]
+};
+```
+
+These defaults will be applied to all tables unless overridden at the component level. For more details, see [TableBuilderConfig Documentation](./TABLE-BUILDER-CONFIG.md).