@one-paragon/angular-utilities 2.8.4 → 2.8.6

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

@@ -1,515 +0,0 @@
-# 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).