@one-paragon/angular-utilities 2.8.3 → 2.8.4

package/src/table-builder/documentation/table-builder/CUSTOM-CELL.md

@@ -0,0 +1,568 @@
+# CustomCell Directive Documentation
+
+## Overview
+
+The `customCell` directive allows you to provide custom templates for rendering table cells. This is useful when you need to display formatted data, add interactive elements, or create complex cell layouts that go beyond simple text display.
+
+> **💡 Type Safety Recommendation**: For better TypeScript support and type inference in your templates, it's recommended to use the `tableRef` input parameter. See [customCellTableRef](#customcelltableref) for details.
+
+## Basic Usage
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder, FieldType, CustomCellDirective } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+
+@Component({
+  selector: 'app-users-table',
+  standalone: true,
+  imports: [TableContainerComponent, CustomCellDirective],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- Custom cell template -->
+      <p *customCell="'status'; let row">
+        <span [class]="'status-badge status-' + row.status">
+          {{ row.status }}
+        </span>
+      </p>
+    </tb-table-container>
+  `
+})
+export class UsersTableComponent {
+  users = [
+    { id: 1, name: 'John Doe', status: 'active' },
+    { id: 2, name: 'Jane Smith', status: 'inactive' }
+  ];
+
+  tableBuilder = new TableBuilder(this.users);
+}
+```
+
+## Template Context
+
+The custom cell template receives the following context:
+
+### `$implicit` (default)
+- **Type**: `T` (the row data)
+- **Description**: The entire row object. This is the default context variable.
+
+### `element`
+- **Type**: `T` (the row data)
+- **Description**: Alternative named access to the row object.
+
+**Example:**
+```typescript
+<!-- Using $implicit (default) -->
+<p *customCell="'name'; let row">
+  {{ row.name }}
+</p>
+
+<!-- Using named element -->
+<p *customCell="'name'; let element = element">
+  {{ element.name }}
+</p>
+```
+
+## Directive Inputs
+
+### Required Inputs
+
+#### `customCell`
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: The key/name of the column. This must match either:
+  - A property key in your data objects
+  - A column defined in your metadata
+  - A completely custom column (when used with `customCellNotMapped`)
+
+**Example:**
+```html
+<a *customCell="'email'; let row" [href]="'mailto:' + row.email">
+  {{ row.email }}
+</a>
+```
+
+### Optional Inputs
+
+#### `customCellDisplayName`
+- **Type**: `string | undefined`
+- **Default**: `undefined`
+- **Description**: The display name for the column header. Overrides the `displayName` from metadata if both are provided.
+
+**Example:**
+```html
+<p *customCell="'fullName'; displayName: 'Employee Name'; let row">
+  {{ row.firstName }} {{ row.lastName }}
+</p>
+```
+
+#### `customCellOrder`
+- **Type**: `number | undefined`
+- **Default**: `undefined`
+- **Description**: Controls the column order. Lower numbers appear first. Overrides the `order` from metadata if both are provided.
+
+**Example:**
+```html
+<div *customCell="'actions'; order: 999; let row">
+  <button (click)="edit(row)">Edit</button>
+</div>
+```
+
+#### `customCellWidth`
+- **Type**: `string | undefined`
+- **Default**: `undefined`
+- **Description**: CSS width for the column (e.g., `'150px'`, `'20%'`). Overrides the `width` from metadata if both are provided.
+
+**Example:**
+```html
+<span *customCell="'status'; width: '120px'; let row" class="badge">
+  {{ row.status }}
+</span>
+```
+
+#### `customCellNotMapped`
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Set to `true` when the column is not mapped to a property in the data source. This is useful for computed columns or action columns that don't correspond to actual data properties. When `true`, the column will have `FieldType.NotMapped`.
+
+**Example:**
+```html
+<!-- Action column not in data -->
+<div *customCell="'actions'; notMapped: true; displayName: 'Actions'; let row">
+  <button (click)="edit(row)">Edit</button>
+  <button (click)="delete(row)">Delete</button>
+</div>
+```
+
+#### `preSort`
+- **Type**: `SortDef | undefined`
+- **Default**: `undefined`
+- **Description**: Defines initial sorting for this column. Overrides the `preSort` from metadata if both are provided.
+
+**Example:**
+```typescript
+interface SortDef {
+  direction: 'asc' | 'desc';
+  priority?: number; // For multi-column sort
+}
+```
+
+```html
+<p *customCell="'createdDate'; preSort: sortDef; let row">
+  {{ row.createdDate | date }}
+</p>
+
+<!-- In component -->
+sortDef = { direction: 'desc', priority: 1 };
+```
+
+#### `customCellTableRef`
+- **Type**: `TableBuilder<T> | undefined`
+- **Default**: `undefined`
+- **Description**: Reference to the TableBuilder instance for type safety. This helps TypeScript infer the correct type for the row data in the template.
+
+**Example:**
+```typescript
+@Component({
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <p *customCell="'name'; tableRef: tableBuilder; let row">
+        <!-- TypeScript now knows row is of type User -->
+        {{ row.name }}
+      </p>
+    </tb-table-container>
+  `
+})
+export class UsersTableComponent {
+  tableBuilder = new TableBuilder<User>(this.users);
+}
+```
+
+#### `templateRef`
+- **Type**: `TemplateRef<any> | undefined`
+- **Default**: Auto-injected from `ng-template`
+- **Description**: The template reference. This is typically auto-injected and doesn't need to be set manually.
+
+## Combining MetaData with Custom Cells
+
+You can define a column in your metadata **and** provide a custom cell template. When both are present:
+
+- **The metadata defines** the column's data behavior (field type, sorting, filtering, etc.)
+- **The custom cell template** defines the visual rendering
+- **Custom cell inputs override** matching metadata properties
+
+### Override Priority
+
+When a column is defined in both metadata and has a custom cell directive, the directive inputs take precedence:
+
+- `customCellDisplayName` → overrides `metaData.displayName`
+- `customCellOrder` → overrides `metaData.order`
+- `customCellWidth` → overrides `metaData.width`
+- `preSort` → overrides `metaData.preSort`
+
+### Example: Metadata + Custom Cell
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder, FieldType } from 'angular-utilities';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  salary: number;
+  status: 'active' | 'inactive' | 'pending';
+}
+
+@Component({
+  selector: 'app-users-table',
+  standalone: true,
+  imports: [TableContainerComponent, CustomCellDirective],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- Email column: metadata defines behavior, custom cell defines rendering -->
+      <a *customCell="'email'; let row" 
+         [href]="'mailto:' + row.email" 
+         class="email-link">
+        <mat-icon>email</mat-icon>
+        {{ row.email }}
+      </a>
+
+      <!-- Status column: override display name from metadata -->
+      <span *customCell="'status'; displayName: 'Account Status'; let row"
+            [class]="'status-badge status-' + row.status">
+        {{ row.status | titlecase }}
+      </span>
+
+      <!-- Salary column: metadata provides formatting, custom cell adds styling -->
+      <span *customCell="'salary'; let row" 
+            [class.high-salary]="row.salary > 100000">
+        {{ row.salary | currency }}
+      </span>
+    </tb-table-container>
+  `
+})
+export class UsersTableComponent {
+  users: User[] = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', salary: 95000, status: 'active' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', salary: 120000, status: 'active' }
+  ];
+
+  metaData = [
+    { 
+      key: 'id', 
+      fieldType: FieldType.Number, 
+      displayName: 'ID',
+      width: '80px'
+    },
+    { 
+      key: 'name', 
+      fieldType: FieldType.String, 
+      displayName: 'Name' 
+    },
+    { 
+      key: 'email', 
+      fieldType: FieldType.String, 
+      displayName: 'Email',
+      width: '250px'
+      // Custom cell provides the template, but this metadata defines:
+      // - Field type (enables proper sorting/filtering)
+      // - Default display name (can be overridden by customCellDisplayName)
+      // - Width (can be overridden by customCellWidth)
+    },
+    { 
+      key: 'salary', 
+      fieldType: FieldType.Currency, 
+      displayName: 'Salary',
+      width: '120px'
+      // FieldType.Currency enables currency-aware sorting
+      // Custom cell adds conditional styling
+    },
+    { 
+      key: 'status', 
+      fieldType: FieldType.String, 
+      displayName: 'Status', // Will be overridden by customCellDisplayName
+      order: 50
+    }
+  ];
+
+  tableBuilder = new TableBuilder(this.users, this.metaData);
+}
+```
+
+## Use Cases
+
+### 1. Action Columns
+
+```html
+<div *customCell="'actions'; notMapped: true; displayName: 'Actions'; width: '150px'; order: 999; let row">
+  <button mat-icon-button (click)="edit(row)">
+    <mat-icon>edit</mat-icon>
+  </button>
+  <button mat-icon-button (click)="delete(row)">
+    <mat-icon>delete</mat-icon>
+  </button>
+</div>
+```
+
+### 2. Status Badges
+
+```html
+<span *customCell="'status'; let row" 
+      class="status-badge" 
+      [ngClass]="{
+        'status-active': row.status === 'active',
+        'status-inactive': row.status === 'inactive',
+        'status-pending': row.status === 'pending'
+      }">
+  {{ row.status | titlecase }}
+</span>
+```
+
+### 3. Links
+
+```html
+<a *customCell="'name'; let row" [routerLink]="['/users', row.id]">
+  {{ row.name }}
+</a>
+```
+
+### 4. Images
+
+```html
+<img *customCell="'avatar'; width: '80px'; let row" 
+     [src]="row.avatarUrl" 
+     [alt]="row.name" 
+     class="avatar-img">
+```
+
+### 5. Complex Formatting
+
+```html
+<div *customCell="'address'; let row" class="address-cell">
+  <div>{{ row.street }}</div>
+  <div>{{ row.city }}, {{ row.state }} {{ row.zip }}</div>
+</div>
+```
+
+### 6. Conditional Display
+
+```html
+<span *customCell="'discount'; let row">
+  @if (row.discount > 0) {
+    <span class="discount">{{ row.discount }}% OFF</span>
+  } @else {
+    <span class="no-discount">Regular Price</span>
+  }
+</span>
+```
+
+### 7. Interactive Elements
+
+```html
+<div *customCell="'quantity'; let row">
+  <button (click)="decrement(row)">-</button>
+  <span>{{ row.quantity }}</span>
+  <button (click)="increment(row)">+</button>
+</div>
+```
+
+### 8. Computed Values
+
+```html
+<span *customCell="'fullName'; notMapped: true; displayName: 'Full Name'; let row">
+  {{ row.firstName }} {{ row.lastName }}
+</span>
+```
+
+## Important Notes
+
+### Export Behavior
+Custom cells are automatically excluded from CSV exports (`noExport: true`). The export will use the raw data value if the column is mapped to a data property, or exclude the column entirely if `customCellNotMapped` is true.
+
+### Field Type
+- If `customCellNotMapped` is `true`, the field type is set to `FieldType.NotMapped`
+- Otherwise, it's set to `FieldType.Unknown`
+- When combining with metadata, the metadata's field type takes precedence for sorting/filtering behavior
+
+### Type Safety
+For better TypeScript support in templates, use the `customCellTableRef` input:
+
+```typescript
+<p *customCell="'name'; tableRef: tableBuilder; let row">
+  <!-- TypeScript will infer the correct type for 'row' -->
+  {{ row.name }}
+</p>
+```
+
+## Complete Example
+
+```typescript
+import { Component } from '@angular/core';
+import { TableBuilder, FieldType, CustomCellDirective } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+import { MatIconModule } from '@angular/material/icon';
+import { MatButtonModule } from '@angular/material/button';
+import { RouterLink } from '@angular/router';
+import { DatePipe, CurrencyPipe, TitleCasePipe } from '@angular/common';
+
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+  category: string;
+  stock: number;
+  imageUrl: string;
+  status: 'available' | 'out-of-stock' | 'discontinued';
+  lastUpdated: Date;
+}
+
+@Component({
+  selector: 'app-products-table',
+  standalone: true,
+  imports: [
+    TableContainerComponent, 
+    CustomCellDirective,
+    MatIconModule,
+    MatButtonModule,
+    RouterLink,
+    DatePipe,
+    CurrencyPipe,
+    TitleCasePipe
+  ],
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder">
+      <!-- Image column (not in original data structure) -->
+      <img *customCell="'image'; notMapped: true; displayName: 'Product Image'; width: '100px'; order: 0; let row" 
+           [src]="row.imageUrl" 
+           [alt]="row.name" 
+           class="product-image">
+
+      <!-- Name with link -->
+      <a *customCell="'name'; let row" [routerLink]="['/products', row.id]">
+        {{ row.name }}
+      </a>
+
+      <!-- Status badge (override display name) -->
+      <span *customCell="'status'; displayName: 'Availability'; let row"
+            [class]="'status-badge status-' + row.status">
+        {{ row.status | titlecase }}
+      </span>
+
+      <!-- Stock with warning indicator -->
+      <span *customCell="'stock'; let row" [class.low-stock]="row.stock < 10">
+        {{ row.stock }}
+        @if (row.stock < 10) {
+          <mat-icon class="warning-icon">warning</mat-icon>
+        }
+      </span>
+
+      <!-- Actions (not mapped to data) -->
+      <div *customCell="'actions'; notMapped: true; displayName: 'Actions'; width: '150px'; order: 999; let row">
+        <button mat-icon-button (click)="edit(row)">
+          <mat-icon>edit</mat-icon>
+        </button>
+        <button mat-icon-button (click)="duplicate(row)">
+          <mat-icon>content_copy</mat-icon>
+        </button>
+        <button mat-icon-button (click)="delete(row)" [disabled]="row.status === 'discontinued'">
+          <mat-icon>delete</mat-icon>
+        </button>
+      </div>
+    </tb-table-container>
+  `,
+  styles: [`
+    .product-image {
+      width: 60px;
+      height: 60px;
+      object-fit: cover;
+      border-radius: 4px;
+    }
+
+    .status-badge {
+      padding: 4px 8px;
+      border-radius: 12px;
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .status-available { background: #e8f5e9; color: #2e7d32; }
+    .status-out-of-stock { background: #fff3e0; color: #e65100; }
+    .status-discontinued { background: #ffebee; color: #c62828; }
+
+    .low-stock {
+      color: #e65100;
+      display: flex;
+      align-items: center;
+      gap: 4px;
+    }
+
+    .warning-icon {
+      font-size: 16px;
+      width: 16px;
+      height: 16px;
+    }
+  `]
+})
+export class ProductsTableComponent {
+  products: Product[] = [
+    {
+      id: 1,
+      name: 'Laptop Pro',
+      price: 1299.99,
+      category: 'Electronics',
+      stock: 45,
+      imageUrl: '/assets/laptop.jpg',
+      status: 'available',
+      lastUpdated: new Date('2024-11-15')
+    },
+    {
+      id: 2,
+      name: 'Wireless Mouse',
+      price: 29.99,
+      category: 'Accessories',
+      stock: 5,
+      imageUrl: '/assets/mouse.jpg',
+      status: 'available',
+      lastUpdated: new Date('2024-11-20')
+    }
+  ];
+
+  metaData = [
+    { key: 'id', fieldType: FieldType.Number, displayName: 'ID', width: '80px', order: 1 },
+    { key: 'name', fieldType: FieldType.String, displayName: 'Product Name', order: 2 },
+    { key: 'price', fieldType: FieldType.Currency, displayName: 'Price', width: '120px', order: 3 },
+    { key: 'category', fieldType: FieldType.String, displayName: 'Category', order: 4 },
+    { key: 'stock', fieldType: FieldType.Number, displayName: 'Stock', width: '100px', order: 5 },
+    { key: 'status', fieldType: FieldType.String, displayName: 'Status', order: 6 },
+    { key: 'lastUpdated', fieldType: FieldType.Date, displayName: 'Last Updated', order: 7 }
+  ];
+
+  tableBuilder = new TableBuilder(this.products, this.metaData, {
+    tableSettings: {
+      tableId: 'products-table',
+      trackBy: 'id'
+    }
+  });
+
+  edit(product: Product) {
+    console.log('Edit:', product);
+  }
+
+  duplicate(product: Product) {
+    console.log('Duplicate:', product);
+  }
+
+  delete(product: Product) {
+    console.log('Delete:', product);
+  }
+}
+```
+
+## Related Documentation
+
+- [Table Container Component](TABLE-CONTAINER.md) - How to use custom cells with the table container
+- [MetaData Documentation](METADATA-DOCUMENTATION.md) - Column configuration that works with custom cells
+- [TableBuilder Documentation](TABLE-BUILDER.md) - Setting up the table builder
+- [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) - Table behavior and appearance
+- [CustomGroupRow Directive](CUSTOM-GROUP-ROW.md) - Custom group row templates