@one-paragon/angular-utilities 2.8.4 → 2.8.5

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

@@ -1,430 +0,0 @@
-# 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