@one-paragon/angular-utilities 2.8.2 → 2.8.4

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

@@ -0,0 +1,430 @@
+# TableBuilder Class Documentation
+
+## Overview
+
+`TableBuilder` is the core class that configures and manages data for the Table Builder component. It accepts data, metadata (column definitions), and settings to create a fully-configured table that can be passed to the `tb-table-container` component.
+
+## Basic Usage
+
+```typescript
+import { TableBuilder, FieldType } from 'angular-utilities';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const data: User[] = [
+  { id: 1, name: 'John Doe', email: 'john@example.com' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+];
+
+// Simple usage with just data (auto-generates metadata)
+const tableBuilder = new TableBuilder(data);
+
+// With metadata
+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);
+
+// With settings
+const settings = {
+  tableSettings: {
+    tableId: 'users-table',
+    trackBy: 'id',
+    usePaginator: true
+  }
+};
+const tableBuilder = new TableBuilder(data, metaData, settings);
+```
+
+## Constructor
+
+```typescript
+constructor(
+  data: T[] | Observable<T[]> | Signal<T[]>,
+  metaData?: MetaData<T>[] | Observable<MetaData<T>[]> | Signal<MetaData<T>[]>,
+  settings?: TableBuilderSettings<T> | Observable<TableBuilderSettings<T>> | Signal<TableBuilderSettings<T>>
+)
+```
+
+### Parameters
+
+#### `data` (required)
+- **Type**: `T[]` | `Observable<T[]>` | `Signal<T[]>`
+- **Description**: The data to display in the table. Can be provided as:
+  - **Array**: Static data
+  - **Observable**: Reactive data that updates automatically
+  - **Signal**: Angular signal for reactive data
+
+**Examples:**
+```typescript
+// Static array
+const data = [{ id: 1, name: 'John' }];
+const tableBuilder = new TableBuilder(data);
+
+// Observable
+const data$ = this.userService.getUsers();
+const tableBuilder = new TableBuilder(data$);
+
+// Signal
+const data = signal([{ id: 1, name: 'John' }]);
+const tableBuilder = new TableBuilder(data);
+```
+
+#### `metaData` (optional)
+- **Type**: `MetaData<T>[]` | `Observable<MetaData<T>[]>` | `Signal<MetaData<T>[]>` | `undefined`
+- **Default**: Auto-generated from first data item
+- **Description**: Column definitions that specify how each property should be displayed, sorted, and filtered. If not provided, metadata is automatically generated from the keys of the first data item with `FieldType.Unknown`.
+- **Related Documentation**: See [MetaData Documentation](METADATA-DOCUMENTATION.md) for detailed column configuration options.
+
+**Examples:**
+```typescript
+// Static metadata
+const metaData = [
+  { key: 'id', fieldType: FieldType.Number, displayName: 'ID', width: '80px' },
+  { key: 'name', fieldType: FieldType.String, displayName: 'Name' },
+  { key: 'createdAt', fieldType: FieldType.Date, displayName: 'Created' }
+];
+
+// Observable metadata (useful for dynamic columns)
+const metaData$ = this.configService.getColumnConfig();
+
+// Signal metadata
+const metaData = signal([...]);
+```
+
+#### `settings` (optional)
+- **Type**: `TableBuilderSettings<T>` | `Observable<TableBuilderSettings<T>>` | `Signal<TableBuilderSettings<T>>`
+- **Default**: `new GeneralTableSettings()`
+- **Description**: Configuration object that controls table appearance and behavior including headers, footers, pagination, virtual scrolling, and more.
+- **Related Documentation**: See [TableBuilder Settings](TABLE-BUILDER-SETTINGS.md) for all available settings.
+
+**Examples:**
+```typescript
+// Static settings
+const settings = {
+  headerSettings: {
+    hideExport: false,
+    title: { text: 'Users Table', level: 2 }
+  },
+  tableSettings: {
+    tableId: 'users-table',
+    trackBy: 'id',
+    usePaginator: true,
+    paginatorSettings: {
+      pageSize: 25
+    }
+  }
+};
+
+// Observable settings
+const settings$ = this.configService.getTableSettings();
+
+// Signal settings
+const settings = signal({ ... });
+```
+
+## Properties
+
+### `container` (readonly)
+- **Type**: `Signal<TableContainerComponent | undefined>`
+- **Description**: Provides access to the `TableContainerComponent` instance once the TableBuilder is bound to a table. This is set automatically when the TableBuilder is passed to a `tb-table-container` component. Use this to programmatically control the table.
+
+**Example:**
+```typescript
+@Component({
+  selector: 'app-users',
+  template: `
+    <tb-table-container [tableBuilder]="tableBuilder" />
+    <button (click)="exportData()">Export</button>
+  `
+})
+export class UsersComponent {
+  tableBuilder = new TableBuilder(this.data, this.metaData);
+
+  exportData() {
+    const container = this.tableBuilder.container();
+    if (container) {
+      container.exportToCsv();
+    }
+  }
+
+  expandAllGroups() {
+    this.tableBuilder.container()?.expandAllGroups();
+  }
+
+  clearSelections() {
+    this.tableBuilder.container()?.clearSelections();
+  }
+}
+```
+
+## Reactive Data Patterns
+
+The TableBuilder supports reactive data patterns through Observables and Signals:
+
+### Observable Pattern
+
+```typescript
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: 'app-users',
+  template: `<tb-table-container [tableBuilder]="tableBuilder" />`
+})
+export class UsersComponent {
+  // Data from HTTP service
+  users$ = this.userService.getUsers();
+  
+  // Metadata from config service
+  metaData$ = this.configService.getColumnConfig();
+  
+  tableBuilder = new TableBuilder(this.users$, this.metaData$);
+  
+  constructor(
+    private userService: UserService,
+    private configService: ConfigService
+  ) {}
+}
+```
+
+### Signal Pattern
+
+```typescript
+import { signal, computed } from '@angular/core';
+
+@Component({
+  selector: 'app-users',
+  template: `<tb-table-container [tableBuilder]="tableBuilder" />`
+})
+export class UsersComponent {
+  users = signal<User[]>([]);
+  
+  metaData = signal([
+    { key: 'id', fieldType: FieldType.Number, displayName: 'ID' },
+    { key: 'name', fieldType: FieldType.String, displayName: 'Name' }
+  ]);
+  
+  tableBuilder = new TableBuilder(this.users, this.metaData);
+  
+  ngOnInit() {
+    // Update data dynamically
+    this.userService.getUsers().subscribe(users => {
+      this.users.set(users);
+    });
+  }
+}
+```
+
+### Computed Signal Pattern
+
+```typescript
+@Component({
+  selector: 'app-filtered-users',
+  template: `<tb-table-container [tableBuilder]="tableBuilder" />`
+})
+export class FilteredUsersComponent {
+  allUsers = signal<User[]>([]);
+  activeFilter = signal<boolean>(true);
+  
+  // Computed data based on filter
+  filteredUsers = computed(() => 
+    this.allUsers().filter(user => 
+      !this.activeFilter() || user.isActive
+    )
+  );
+  
+  tableBuilder = new TableBuilder(this.filteredUsers);
+}
+```
+
+## Auto-Generated Metadata
+
+When metadata is not provided, TableBuilder automatically generates basic metadata from the first data item:
+
+```typescript
+const data = [
+  { id: 1, name: 'John', age: 30 }
+];
+
+const tableBuilder = new TableBuilder(data);
+
+// Internally generates:
+// [
+//   { key: 'id', fieldType: FieldType.Unknown, order: -1 },
+//   { key: 'name', fieldType: FieldType.Unknown, order: -1 },
+//   { key: 'age', fieldType: FieldType.Unknown, order: -1 }
+// ]
+```
+
+**Note**: While auto-generation is convenient for quick prototyping, it's recommended to provide explicit metadata for production use to ensure proper typing, sorting, and filtering behavior.
+
+## Complete Example
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { TableBuilder, FieldType } from 'angular-utilities';
+import { TableContainerComponent } from 'angular-utilities';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  salary: number;
+  hireDate: Date;
+  isActive: boolean;
+}
+
+@Component({
+  selector: 'app-users-table',
+  standalone: true,
+  imports: [TableContainerComponent],
+  template: `
+    <div class="controls">
+      <button (click)="exportData()">Export to CSV</button>
+      <button (click)="expandGroups()">Expand All Groups</button>
+      <button (click)="collapseGroups()">Collapse All Groups</button>
+    </div>
+    
+    <tb-table-container [tableBuilder]="tableBuilder" />
+  `
+})
+export class UsersTableComponent {
+  users = signal<User[]>([
+    {
+      id: 1,
+      name: 'John Doe',
+      email: 'john@example.com',
+      department: 'Engineering',
+      salary: 95000,
+      hireDate: new Date('2020-01-15'),
+      isActive: true
+    },
+    {
+      id: 2,
+      name: 'Jane Smith',
+      email: 'jane@example.com',
+      department: 'Marketing',
+      salary: 85000,
+      hireDate: new Date('2021-03-20'),
+      isActive: true
+    }
+  ]);
+
+  metaData = [
+    {
+      key: 'id',
+      fieldType: FieldType.Number,
+      displayName: 'ID',
+      width: '80px'
+    },
+    {
+      key: 'name',
+      fieldType: FieldType.String,
+      displayName: 'Full Name',
+      width: '200px'
+    },
+    {
+      key: 'email',
+      fieldType: FieldType.String,
+      displayName: 'Email Address'
+    },
+    {
+      key: 'department',
+      fieldType: FieldType.String,
+      displayName: 'Department',
+      width: '150px'
+    },
+    {
+      key: 'salary',
+      fieldType: FieldType.Currency,
+      displayName: 'Annual Salary',
+      width: '120px'
+    },
+    {
+      key: 'hireDate',
+      fieldType: FieldType.Date,
+      displayName: 'Hire Date',
+      width: '120px'
+    },
+    {
+      key: 'isActive',
+      fieldType: FieldType.Boolean,
+      displayName: 'Active',
+      width: '100px'
+    }
+  ];
+
+  settings = {
+    headerSettings: {
+      title: { text: 'Employee Directory', level: 2 },
+      hideExport: false
+    },
+    tableSettings: {
+      tableId: 'users-table',
+      trackBy: 'id',
+      usePaginator: true,
+      includeIndexColumn: true,
+      includeSelectionColumn: true,
+      paginatorSettings: {
+        pageSize: 25,
+        includeAllInOptions: true
+      },
+      groupBySettings: [
+        { key: 'department', expanded: true }
+      ]
+    },
+    columnHeaderSettings: {
+      stickyHeaderRow: true
+    }
+  };
+
+  tableBuilder = new TableBuilder(this.users, this.metaData, this.settings);
+
+  exportData() {
+    this.tableBuilder.container()?.exportToCsv();
+  }
+
+  expandGroups() {
+    this.tableBuilder.container()?.expandAllGroups();
+  }
+
+  collapseGroups() {
+    this.tableBuilder.container()?.collapseAllGroups();
+  }
+}
+```
+
+## Helper Function: CreateTableBuilder
+
+For working with observables that emit `ReportDef` objects (which contain both data and metadata):
+
+```typescript
+import { Observable } from 'rxjs';
+import { CreateTableBuilder } from 'angular-utilities';
+
+interface ReportDef {
+  data: any[];
+  metaData: MetaData[];
+}
+
+const reportDef$: Observable<ReportDef> = this.reportService.getReport();
+const tableBuilder = CreateTableBuilder(reportDef$);
+```
+
+This helper automatically splits the observable into separate data and metadata streams.
+
+## Related Documentation
+
+- [Table Container Component](TABLE-CONTAINER.md) - How to use TableBuilder with the table component
+- [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
+- [CustomCell Directive](CUSTOM-CELL.md) - Custom cell templates
+- [CustomGroupRow Directive](CUSTOM-GROUP-ROW.md) - Custom group row templates