@one-paragon/angular-utilities 2.8.3 → 2.8.4

package/src/table-builder/documentation/table-builder/CUSTOM-GROUP-ROW.md

@@ -0,0 +1,356 @@
+# CustomGroupRow Directive Documentation
+
+## Overview
+
+The `customGroupRow` directive allows you to provide custom templates for rendering group header rows when data is grouped. This is useful when you want to display group headers in a specific way, add custom styling, or include interactive elements like expand/collapse buttons or group actions.
+
+> **💡 Type Safety Recommendation**: For better TypeScript support and type inference in your templates, it's recommended to use the `tableRef` input parameter. See [customGroupRowTableRef](#customgrouprowtableref) for details.
+
+## Basic Usage
+
+### Global Custom Group Row (applies to all groupings)
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder, CustomGroupRowDirective } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+
+@Component({
+  selector: 'app-products-table',
+  standalone: true,
+  imports: [TableContainerComponent, CustomGroupRowDirective],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- This custom row will be used for all group headers -->
+      <div *customGroupRow="let group" style="background: lightblue; padding: 8px;">
+        📁 Group: <strong>{{group.groupHeaderDisplay}}</strong> 
+        ({{group.length}} items)
+      </div>
+    </tb-table-container>
+  `
+})
+export class ProductsTableComponent {
+  products = [
+    { category: 'Electronics', name: 'Laptop', price: 999 },
+    { category: 'Electronics', name: 'Phone', price: 699 },
+    { category: 'Clothing', name: 'Shirt', price: 29 }
+  ];
+
+  tableBuilder = new TableBuilder(this.products, undefined, {
+    tableSettings: {
+      groupBySettings: [{ key: 'category', expanded: true }]
+    }
+  });
+}
+```
+
+### Key-Specific Custom Group Row
+
+```typescript
+@Component({
+  selector: 'app-products-table',
+  standalone: true,
+  imports: [TableContainerComponent, CustomGroupRowDirective],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- This custom row only applies when grouping by 'category' -->
+      <div *customGroupRow="'category'; let group" style="background: lightgreen; padding: 8px;">
+        🏷️ Category: <strong>{{group.groupHeaderDisplay}}</strong> 
+        ({{group.length}} products)
+      </div>
+      
+      <!-- This custom row only applies when grouping by 'status' -->
+      <div *customGroupRow="'status'; let group" style="background: lightyellow; padding: 8px;">
+        ⭐ Status: <strong>{{group.groupHeaderDisplay}}</strong> 
+        ({{group.length}} items)
+      </div>
+      
+      <!-- This custom row applies to all other groupings -->
+      <div *customGroupRow="let group" style="background: lightgray; padding: 8px;">
+        📋 Default Group: <strong>{{group.groupHeaderDisplay}}</strong> 
+        ({{group.length}} items)
+      </div>
+    </tb-table-container>
+  `
+})
+export class ProductsTableComponent {
+  // ... component logic
+}
+```
+
+### Multiple Keys
+
+You can apply a single custom group row template to multiple grouping keys:
+
+```typescript
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- This applies to both 'category' and 'department' groupings -->
+      <div *customGroupRow="['category', 'department']; let group" 
+           style="background: lightcoral; padding: 8px;">
+        📊 {{group.groupHeaderDisplay}} ({{group.length}} items)
+      </div>
+    </tb-table-container>
+  `
+})
+export class MyComponent {
+  // ... component logic
+}
+```
+
+## Template Context
+
+The custom group row template receives a context object with the following properties:
+
+### `$implicit` (default)
+- **Type**: `Group<T>`
+- **Description**: The group row data. This is the default context variable.
+
+### `element`
+- **Type**: `T`
+- **Description**: Alternative named access to the group row data.
+
+### `expanded`
+- **Type**: `boolean`
+- **Description**: Whether the group is currently expanded.
+
+### `level`
+- **Type**: `number`
+- **Description**: The nesting level of the group (0 for top-level groups, 1 for nested, etc.).
+
+### `key`
+- **Type**: `string`
+- **Description**: The grouping key that created this group (e.g., 'category', 'status').
+
+### `uniqueName`
+- **Type**: `string`
+- **Description**: Unique identifier for this specific group instance.
+
+### `groupHeaderDisplay`
+- **Type**: `string`
+- **Description**: The display text for the group header (e.g., the value of the grouped property).
+
+### `length`
+- **Type**: `number`
+- **Description**: Number of items in the group.
+
+### `padding`
+- **Type**: `number`
+- **Description**: Calculated padding in pixels for visual nesting indication.
+
+**Example using context properties:**
+```html
+<div *customGroupRow="let group">
+  <div [style.padding-left.px]="group.padding">
+    <span>{{group.expanded ? '▼' : '▶'}}</span>
+    <strong>{{group.groupHeaderDisplay}}</strong>
+    <span>({{group.length}} items, Level {{group.level}})</span>
+  </div>
+</div>
+```
+
+## Priority System
+
+When multiple custom group row directives could apply to the same grouping, they are prioritized as follows:
+
+1. **Key-specific matches** (e.g., `*customGroupRow="'category'"`) automatically have higher priority than global matches (`*customGroupRow="let group"`)
+2. **Explicit priority** - Use the `customGroupRowPriority` input to set explicit priorities
+3. **Higher numbers win** - When comparing priorities, higher numbers take precedence
+
+**Example:**
+```typescript
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- Priority: 0 (default), key-specific -->
+      <div *customGroupRow="'category'; let group">
+        Default category template
+      </div>
+      
+      <!-- Priority: 10, key-specific - THIS ONE WINS -->
+      <div *customGroupRow="'category'; priority: 10; let group">
+        Special category template with higher priority
+      </div>
+      
+      <!-- Priority: 0 (default), global -->
+      <div *customGroupRow="let group">
+        Global fallback template
+      </div>
+    </tb-table-container>
+  `
+})
+export class MyComponent {
+  // ... component logic
+}
+```
+
+## Advanced Example with Interaction
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder, CustomGroupRowDirective } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+
+@Component({
+  selector: 'app-interactive-table',
+  standalone: true,
+  imports: [TableContainerComponent, CustomGroupRowDirective],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder" #tableContainer>
+      <div *customGroupRow="let group" 
+           style="background: #f0f8ff; padding: 12px; border-left: 4px solid #007acc; 
+                  margin: 4px 0; border-radius: 4px;">
+        <div style="display: flex; align-items: center; justify-content: space-between;">
+          <div style="display: flex; align-items: center; gap: 8px;">
+            <button (click)="toggleGroup(tableContainer, group)" 
+                    style="background: none; border: none; font-size: 16px; cursor: pointer;">
+              {{group.expanded ? '📂' : '📁'}}
+            </button>
+            <strong>{{group.groupHeaderDisplay}}</strong>
+            <span style="color: #666; font-size: 0.9em;">({{group.length}} items)</span>
+            <span style="background: #007acc; color: white; padding: 2px 6px; 
+                         border-radius: 12px; font-size: 0.8em;">
+              Level {{group.level}}
+            </span>
+          </div>
+          <div>
+            <button (click)="selectAllInGroup(group)" 
+                    style="font-size: 0.8em; padding: 4px 8px;">
+              Select All
+            </button>
+          </div>
+        </div>
+      </div>
+    </tb-table-container>
+  `
+})
+export class InteractiveTableComponent {
+  data = [
+    { category: 'Electronics', name: 'Laptop', price: 999 },
+    { category: 'Electronics', name: 'Phone', price: 699 },
+    { category: 'Clothing', name: 'Shirt', price: 29 }
+  ];
+
+  tableBuilder = new TableBuilder(this.data, undefined, {
+    tableSettings: {
+      groupBySettings: [{ key: 'category', expanded: false }]
+    }
+  });
+  
+  toggleGroup(tableContainer: TableContainerComponent, group: any) {
+    // Access the generic table to toggle expansion
+    const genericTable = tableContainer.$genericTable();
+    if (genericTable) {
+      genericTable.setExpanded(group.key, group.uniqueName, !group.expanded);
+    }
+  }
+  
+  selectAllInGroup(group: any) {
+    // Custom logic to select all items in the group
+    console.log('Selecting all items in group:', group.uniqueName);
+  }
+}
+```
+
+## Directive Inputs
+
+### `customGroupRow`
+- **Type**: `string | string[] | null`
+- **Default**: `null` (applies to all groupings)
+- **Description**: The grouping key(s) this directive applies to. Can be:
+  - `null` or omitted: Applies to all groupings (global default)
+  - A string: Applies only when grouped by that specific key
+  - An array of strings: Applies when grouped by any of the specified keys
+
+**Examples:**
+```html
+<!-- Global: applies to all groupings -->
+<div *customGroupRow="let group">
+  {{group.groupHeaderDisplay}}
+</div>
+
+<!-- Key-specific: only for 'category' -->
+<div *customGroupRow="'category'; let group">
+  Category: {{group.groupHeaderDisplay}}
+</div>
+
+<!-- Multiple keys: for 'category' or 'status' -->
+<div *customGroupRow="['category', 'status']; let group">
+  {{group.groupHeaderDisplay}}
+</div>
+```
+
+### `customGroupRowPriority`
+- **Type**: `number`
+- **Default**: `0`
+- **Description**: Priority for this directive when multiple directives could apply to the same grouping. Higher numbers have higher priority. Key-specific directives automatically get higher priority than global directives.
+
+**Example:**
+```html
+<!-- Lower priority (will be overridden) -->
+<div *customGroupRow="'category'; let group">
+  Default category template
+</div>
+
+<!-- Higher priority (this one wins) -->
+<div *customGroupRow="'category'; priority: 10; let group">
+  Special category template
+</div>
+```
+
+### `customGroupRowTableRef`
+- **Type**: `TableBuilder<T> | undefined`
+- **Default**: `undefined`
+- **Description**: Reference to the TableBuilder instance for type safety. This helps TypeScript infer the correct type for the group data in the template.
+
+**Example:**
+```typescript
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <div *customGroupRow="tableRef: tableBuilder; let group">
+        <!-- TypeScript now knows the correct type for group -->
+        {{group.groupHeaderDisplay}}
+      </div>
+    </tb-table-container>
+  `
+})
+export class MyComponent {
+  tableBuilder = new TableBuilder<Product>(this.products);
+}
+```
+
+## Grouping Configuration
+
+To use custom group rows, you first need to configure grouping in your table settings. See [TableBuilder Settings - groupBySettings](TABLE-BUILDER-SETTINGS.md#groupbysettings) for detailed configuration options.
+
+**Example:**
+```typescript
+const settings = {
+  tableSettings: {
+    groupBySettings: [
+      { key: 'category', expanded: true },
+      { key: 'status', expanded: false }
+    ]
+  }
+};
+
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+## Important Notes
+
+- The directive selector is `[customGroupRow]`
+- Multiple custom group row directives can be defined in the same component
+- Key-specific directives automatically have higher priority than global ones
+- The template receives the full group data including expansion state and nesting information
+- Custom group rows completely replace the default group header rendering when matched
+- For type safety, always provide the `tableRef` input in TypeScript strict mode
+
+## Related Documentation
+
+- [Table Container Component](TABLE-CONTAINER.md) - Main table component documentation
+- [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) - Configuring grouping behavior
+- [CustomCell Directive](CUSTOM-CELL.md) - Custom cell templates
+- [TableBuilder Documentation](TABLE-BUILDER.md) - Setting up the table builder