ngx-st-tables 18.0.19 → 18.0.21

package/README.md

@@ -1,153 +1,1240 @@
-# NgxStTables
+# Material Table Component - Complete Input/Output Reference
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.0.
+## Table of Contents
+- [Overview](#overview)
+- [Basic Inputs](#basic-inputs)
+- [Display & Layout Inputs](#display--layout-inputs)
+- [Data Management Inputs](#data-management-inputs)
+- [Row Selection Inputs](#row-selection-inputs)
+- [Row Editing Inputs](#row-editing-inputs)
+- [Row Actions Inputs](#row-actions-inputs)
+- [Column Configuration](#column-configuration)
+- [Outputs (Events)](#outputs-events)
+- [Usage Examples](#usage-examples)
 
-## Usage
+---
 
-### Immutable Data Pattern
+## Overview
 
-The table library follows an immutable data pattern where:
-- The parent component owns and controls the data
-- The table works on a copy of the data
-- Changes are communicated back to the parent through events
-- The parent decides whether to accept/reject changes
+The `ngx-st-material-table` component is a powerful Angular Material table with features including:
+- Pagination, sorting, and filtering
+- Lazy loading support
+- Row editing (inline editing or auto-save)
+- Row selection (single or multiple)
+- Custom column templates
+- Expandable rows
+- Local storage persistence
+- Create, update, and delete operations
 
-### Example: Using Add/Edit Row Features
+---
 
-```typescript
-// Parent Component
-@Component({
-  selector: 'app-example',
-  template: `
-    <ngx-st-material-table
-      [data]="tableData"
-      [initColumns]="columns"
-      [allowEditRow]="true"
-      [createButtonUseAddRow]="true"
-      (saveNewCreatedRow)="onSaveNewCreatedRow($event)"
-      (saveNewRow)="onSaveEditedRow($event)"
-    />
-  `
-})
-export class ExampleComponent {
-  tableData: any[] = [];
-  
-  columns: StMaterialTableColumnModel[] = [
-    { field: 'name', header: 'Name', allowEditColumn: true, editColumnRequired: true },
-    { field: 'email', header: 'Email', allowEditColumn: true },
-  ];
+## Basic Inputs
 
-  // Handle new row creation
-  onSaveNewCreatedRow(row: any) {
-    // The library generated an ID and validated the row
-    // Parent decides how to handle it (e.g., API call)
-    this.apiService.createRow(row).subscribe(response => {
-      // Update parent's data with server response
-      this.tableData = [...this.tableData, response];
-    });
+### `tableTitle`
+- **Type:** `string`
+- **Default:** `''`
+- **Description:** Title displayed at the top of the table in the caption area.
+- **Example:**
+  ```typescript
+  tableTitle="Users List"
+  ```
+
+### `pageSize`
+- **Type:** `number`
+- **Default:** `10`
+- **Description:** Number of rows to display per page.
+- **Example:**
+  ```typescript
+  [pageSize]="25"
+  ```
+
+### `dataLength`
+- **Type:** `number`
+- **Default:** `0`
+- **Description:** Total number of records (used for lazy loading pagination). Only needed when `lazyLoading` is true.
+- **Example:**
+  ```typescript
+  [dataLength]="totalRecords"
+  ```
+
+### `data`
+- **Type:** `any[]`
+- **Default:** `[]`
+- **Description:** Array of data objects to display in the table. Each object represents one row.
+- **Important:** Uses immutable data pattern. Always pass a new array reference when updating data.
+- **Example:**
+  ```typescript
+  [data]="users"
+  ```
+
+### `initColumns`
+- **Type:** `StMaterialTableColumnModel[]`
+- **Default:** `[]`
+- **Description:** Array of column definitions that configure how each column is displayed and behaves.
+- **See:** [Column Configuration](#column-configuration) section for details.
+- **Example:**
+  ```typescript
+  [initColumns]="columnDefs"
+  ```
+
+---
+
+## Display & Layout Inputs
+
+### `showGlobalSearch`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows a global search input that searches across all visible columns.
+- **Example:**
+  ```typescript
+  [showGlobalSearch]="true"
+  ```
+
+### `allowPickColumns`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Allows users to show/hide columns via a column picker dialog.
+- **Example:**
+  ```typescript
+  [allowPickColumns]="true"
+  ```
+
+### `allowReorderColumns`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Allows users to reorder columns by dragging them.
+- **Example:**
+  ```typescript
+  [allowReorderColumns]="true"
+  ```
+
+### `localStorageName`
+- **Type:** `string`
+- **Default:** `''`
+- **Description:** Key name for storing table state (pagination, sorting, filters, column order) in localStorage. If empty, state is not persisted.
+- **Example:**
+  ```typescript
+  localStorageName="users-table-state"
+  ```
+
+### `isLoading`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows a loading spinner overlay on the table.
+- **Example:**
+  ```typescript
+  [isLoading]="loading"
+  ```
+
+### `extraCustomFilter`
+- **Type:** `TemplateRef<any>`
+- **Default:** `undefined`
+- **Description:** Custom template for additional filter controls displayed in the table caption area.
+- **Example:**
+  ```html
+  <ng-template #customFilters>
+    <mat-form-field>
+      <mat-select placeholder="Status">
+        <mat-option value="active">Active</mat-option>
+        <mat-option value="inactive">Inactive</mat-option>
+      </mat-select>
+    </mat-form-field>
+  </ng-template>
+  
+  [extraCustomFilter]="customFilters"
+  ```
+
+---
+
+## Data Management Inputs
+
+### `lazyLoading`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enables server-side pagination, sorting, and filtering. When true, table emits `loadData` events instead of handling data locally.
+- **Required with:** `dataLength` input must be provided
+- **Example:**
+  ```typescript
+  [lazyLoading]="true"
+  [dataLength]="totalRecords"
+  (loadData)="onLoadData($event)"
+  ```
+
+### `setNewDataWithoutRefresh`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** When true and data array length hasn't changed, updates existing row objects in place without recreating table rows. This preserves focus state during editing and prevents UI flickering.
+- **Use case:** Ideal for real-time updates or auto-save scenarios where you frequently update data.
+- **Example:**
+  ```typescript
+  [setNewDataWithoutRefresh]="true"
+  ```
+
+---
+
+## Row Selection Inputs
+
+### `allowSelectRow`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enables row selection with checkboxes. Adds a selection column to the left of the table.
+- **Example:**
+  ```typescript
+  [allowSelectRow]="true"
+  (selectRowChange)="onSelectionChange($event)"
+  ```
+
+### `selectionFieldLabel`
+- **Type:** `string`
+- **Default:** `''`
+- **Description:** Property name from the row object to use as the display label for selected rows (shown in chips).
+- **Example:**
+  ```typescript
+  selectionFieldLabel="name"
+  ```
+
+### `selectRowOnlyOne`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** When true, only one row can be selected at a time (radio button behavior instead of checkboxes).
+- **Example:**
+  ```typescript
+  [selectRowOnlyOne]="true"
+  ```
+
+### `selectRowValueDisplay`
+- **Type:** `(row: any) => string`
+- **Default:** `undefined`
+- **Description:** Custom formatter function to generate the display value for selected rows. Takes precedence over `selectionFieldLabel`.
+- **Use case:** When you need to display multiple fields or apply custom formatting.
+- **Example:**
+  ```typescript
+  [selectRowValueDisplay]="formatSelectedRow"
+  
+  formatSelectedRow(row: any): string {
+    return `${row.firstName} ${row.lastName} (${row.email})`;
+  }
+  ```
+
+### `initSelectedRow`
+- **Type:** `any` or `any[]`
+- **Default:** `undefined`
+- **Description:** Pre-selected row(s) when the table initializes.
+- **Example:**
+  ```typescript
+  [initSelectedRow]="preSelectedUsers"
+  ```
+
+---
+
+## Row Editing Inputs
+
+### `allowEditRow`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enables inline row editing. Adds edit/delete action buttons to each row (unless `autoSaveOnChange` is true).
+- **Note:** Columns must have `allowEditColumn: true` to be editable.
+- **Example:**
+  ```typescript
+  [allowEditRow]="true"
+  (saveEditedRow)="onRowSaved($event)"
+  ```
+
+### `allowEditInEditRow`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Shows the edit button in the actions column. Set to false to hide it while still allowing editing functionality.
+- **Example:**
+  ```typescript
+  [allowEditInEditRow]="false"
+  ```
+
+### `allowDeleteInEditRow`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Shows the delete button in the actions column.
+- **Example:**
+  ```typescript
+  [allowDeleteInEditRow]="false"
+  ```
+
+### `showEditAllRows`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows a button in the table caption that toggles edit mode for all rows simultaneously.
+- **Example:**
+  ```typescript
+  [showEditAllRows]="true"
+  ```
+
+### `autoSaveOnChange`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** When true, field changes are saved immediately without requiring save/cancel buttons. Perfect for quantity inputs, toggles, or selection tables where instant updates are needed.
+- **Behavior:**
+  - Removes save/cancel buttons from the table
+  - Emits `fieldValueChanged` event on every field change
+  - Parent should update their data source immediately
+- **Example:**
+  ```typescript
+  [autoSaveOnChange]="true"
+  (fieldValueChanged)="onFieldChanged($event)"
+  
+  onFieldChanged(event: { row: any; field: string; value: any; index: number }) {
+    // Update your data source
+    this.users[event.index][event.field] = event.value;
+    // Optionally call API to persist
+    this.updateUser(event.row);
+  }
+  ```
+
+### `canEditRowValidator`
+- **Type:** `(row: any) => boolean`
+- **Default:** `() => true`
+- **Description:** Function to determine if a specific row can be edited. Return false to disable editing for that row.
+- **Example:**
+  ```typescript
+  [canEditRowValidator]="canEditUser"
+  
+  canEditUser(row: any): boolean {
+    return row.status !== 'archived' && row.isEditable;
+  }
+  ```
+
+### `canDeleteRowValidator`
+- **Type:** `(row: any) => boolean`
+- **Default:** `() => true`
+- **Description:** Function to determine if a specific row can be deleted. Return false to disable delete button for that row.
+- **Example:**
+  ```typescript
+  [canDeleteRowValidator]="canDeleteUser"
+  
+  canDeleteUser(row: any): boolean {
+    return row.status !== 'system' && !row.hasRelatedRecords;
+  }
+  ```
+
+---
+
+## Row Actions Inputs
+
+### `rowClickAction`
+- **Type:** `(row: any) => void`
+- **Default:** `undefined`
+- **Description:** Function called when a row is clicked (only if `allowSelectRow` and `allowExtendRow` are false).
+- **Example:**
+  ```typescript
+  [rowClickAction]="onRowClick"
+  
+  onRowClick(row: any): void {
+    this.router.navigate(['/users', row.id]);
+  }
+  ```
+
+### `allowCreateRow`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows an "Add New Row" button below the table that adds a new editable row.
+- **Example:**
+  ```typescript
+  [allowCreateRow]="true"
+  (saveCreatedRow)="onRowCreated($event)"
+  ```
+
+### `showCreateButton`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows a custom create button in the table caption (separate from `allowCreateRow`).
+- **Example:**
+  ```typescript
+  [showCreateButton]="true"
+  [createButtonLabel]="'Add User'"
+  [createButtonAction]="openCreateDialog"
+  ```
+
+### `createButtonLabel`
+- **Type:** `string`
+- **Default:** `'Create'`
+- **Description:** Label text for the create button (when `showCreateButton` is true).
+- **Example:**
+  ```typescript
+  createButtonLabel="Add New User"
+  ```
+
+### `createButtonAction`
+- **Type:** `() => void`
+- **Default:** `() => {}`
+- **Description:** Function called when the create button is clicked.
+- **Example:**
+  ```typescript
+  [createButtonAction]="openCreateDialog"
+  
+  openCreateDialog(): void {
+    // Open a dialog or navigate to create page
   }
+  ```
+
+### `disableCreateButton`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Disables the create button.
+- **Example:**
+  ```typescript
+  [disableCreateButton]="!hasPermission"
+  ```
+
+---
 
-  // Handle row editing
-  onSaveEditedRow(row: any) {
-    this.apiService.updateRow(row).subscribe(response => {
-      const index = this.tableData.findIndex(r => r.id === row.id);
-      if (index !== -1) {
-        this.tableData[index] = response;
-        this.tableData = [...this.tableData];
+## Row Expansion Inputs
+
+### `allowExtendRow`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enables expandable rows with a toggle button. Clicking a row expands/collapses its detail view.
+- **Required with:** `extendedRowTemplate` must be provided.
+- **Example:**
+  ```typescript
+  [allowExtendRow]="true"
+  [extendedRowTemplate]="detailTemplate"
+  ```
+
+### `extendedRowTemplate`
+- **Type:** `TemplateRef<{ data: any }>`
+- **Default:** `undefined`
+- **Description:** Template for the expanded row content. Receives the row data via context.
+- **Example:**
+  ```html
+  <ng-template #detailTemplate let-data="data">
+    <div class="row-details">
+      <h3>User Details</h3>
+      <p><strong>Email:</strong> {{ data.email }}</p>
+      <p><strong>Phone:</strong> {{ data.phone }}</p>
+      <p><strong>Address:</strong> {{ data.address }}</p>
+    </div>
+  </ng-template>
+  
+  [extendedRowTemplate]="detailTemplate"
+  ```
+
+---
+
+## Column Configuration
+
+Columns are configured via the `initColumns` input using the `StMaterialTableColumnModel` interface.
+
+### Column Model Properties
+
+#### Basic Properties
+
+##### `field`
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Property name from the data object to display in this column.
+- **Example:** `field: 'firstName'`
+
+##### `header`
+- **Type:** `string`
+- **Required:** Yes
+- **Description:** Column header text displayed in the table header.
+- **Example:** `header: 'First Name'`
+
+##### `type`
+- **Type:** `StMaterialColumnType`
+- **Options:** `'string'` | `'number'` | `'boolean'` | `'date'` | `'custom-template'` | `'actions'`
+- **Default:** `'string'`
+- **Description:** Data type of the column, affects display formatting and default filter/edit types.
+- **Example:** `type: 'date'`
+
+##### `width`
+- **Type:** `string`
+- **Default:** Auto
+- **Description:** CSS width value for the column.
+- **Example:** `width: '150px'` or `width: '20%'`
+
+##### `flexRight`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Aligns column content to the right.
+- **Example:** `flexRight: true`
+
+#### Sorting & Filtering
+
+##### `sort`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Enables sorting for this column.
+- **Example:** `sort: false`
+
+##### `filter`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Enables filtering for this column.
+- **Example:** `filter: true`
+
+##### `filterType`
+- **Type:** `StMaterialColumnFilterType`
+- **Options:** `'string'` | `'number'` | `'boolean'` | `'date'` | `'custom'`
+- **Default:** Auto-detected from `type`
+- **Description:** Type of filter input to show for this column.
+- **Example:** `filterType: 'date'`
+
+##### `customFilterOptions`
+- **Type:** `{ value: string; label: string }[]`
+- **Default:** `undefined`
+- **Description:** Options for a dropdown filter (when filterType is 'custom').
+- **Example:**
+  ```typescript
+  customFilterOptions: [
+    { value: 'active', label: 'Active' },
+    { value: 'inactive', label: 'Inactive' }
+  ]
+  ```
+
+#### Display Customization
+
+##### `customTemplate`
+- **Type:** `TemplateRef<any>`
+- **Default:** `undefined`
+- **Description:** Custom template for rendering cell content (use with `type: 'custom-template'`).
+- **Example:**
+  ```html
+  <ng-template #statusTemplate let-row="row">
+    <span [class]="'status-' + row.status">{{ row.status }}</span>
+  </ng-template>
+  
+  {
+    field: 'status',
+    header: 'Status',
+    type: 'custom-template',
+    customTemplate: statusTemplate
+  }
+  ```
+
+##### `customValueDisplay`
+- **Type:** `(row: any) => string`
+- **Default:** `undefined`
+- **Description:** Function to transform the cell value for display.
+- **Example:**
+  ```typescript
+  {
+    field: 'price',
+    header: 'Price',
+    customValueDisplay: (row) => `$${row.price.toFixed(2)}`
+  }
+  ```
+
+##### `translateValue`
+- **Type:** `{ [value: string]: string }`
+- **Default:** `undefined`
+- **Description:** Map of values to translated/display values.
+- **Example:**
+  ```typescript
+  {
+    field: 'status',
+    header: 'Status',
+    translateValue: {
+      'A': 'Active',
+      'I': 'Inactive',
+      'P': 'Pending'
+    }
+  }
+  ```
+
+#### Row Editing Configuration
+
+##### `allowEditColumn`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Makes this column editable when row is in edit mode.
+- **Example:** `allowEditColumn: true`
+
+##### `rowEditType`
+- **Type:** `StMaterialRowEditType`
+- **Options:** `'string'` | `'number'` | `'boolean'` | `'date'` | `'custom'` | `'custom-dynamic-select'`
+- **Default:** Auto-detected from `type`
+- **Description:** Type of input to show when editing this column.
+- **Example:** `rowEditType: 'number'`
+
+##### `customRowEditOptions`
+- **Type:** `{ value: any; label: string }[]`
+- **Default:** `undefined`
+- **Description:** Static options for a dropdown editor (when rowEditType is 'custom').
+- **Example:**
+  ```typescript
+  customRowEditOptions: [
+    { value: 'admin', label: 'Administrator' },
+    { value: 'user', label: 'Regular User' },
+    { value: 'guest', label: 'Guest' }
+  ]
+  ```
+
+##### `dynamicRowEditOptions`
+- **Type:** `(row: any) => { value: any; label: string }[]`
+- **Default:** `undefined`
+- **Description:** Dynamic function to generate dropdown options based on the current row (when rowEditType is 'custom-dynamic-select').
+- **Use case:** When options depend on other field values in the row.
+- **Example:**
+  ```typescript
+  dynamicRowEditOptions: (row) => {
+    if (row.country === 'USA') {
+      return [
+        { value: 'NY', label: 'New York' },
+        { value: 'CA', label: 'California' }
+      ];
+    } else {
+      return [
+        { value: 'LON', label: 'London' },
+        { value: 'MAN', label: 'Manchester' }
+      ];
+    }
+  }
+  ```
+
+##### `editColumnRequired`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Makes this column required when editing. Shows error if empty on save.
+- **Example:** `editColumnRequired: true`
+
+##### `disableEdit`
+- **Type:** `(row: any) => boolean`
+- **Default:** `undefined`
+- **Description:** Function to determine if this specific column should be disabled for editing in a particular row.
+- **Example:**
+  ```typescript
+  disableEdit: (row) => row.status === 'locked'
+  ```
+
+##### `customEditRowValidator`
+- **Type:** `(oldValue: any, newValue: any, row: any) => { isValid: boolean; errorMessage: string }`
+- **Default:** `undefined`
+- **Description:** Custom validation function for this column during editing.
+- **Example:**
+  ```typescript
+  customEditRowValidator: (oldValue, newValue, row) => {
+    if (newValue < 0) {
+      return { isValid: false, errorMessage: 'Value cannot be negative' };
+    }
+    if (newValue > row.maxValue) {
+      return { isValid: false, errorMessage: 'Value exceeds maximum' };
+    }
+    return { isValid: true, errorMessage: '' };
+  }
+  ```
+
+#### Actions Column Configuration
+
+##### `actions`
+- **Type:** `StMaterialTableActionColumnModel[]`
+- **Default:** `undefined`
+- **Description:** Array of action buttons to show in this column (use with `type: 'actions'`).
+- **Example:**
+  ```typescript
+  {
+    field: 'actions',
+    header: 'Actions',
+    type: 'actions',
+    sort: false,
+    filter: false,
+    actions: [
+      {
+        iconName: 'edit',
+        tooltipName: 'Edit User',
+        iconColor: 'primary',
+        action: (row) => this.editUser(row),
+        show: (row) => row.canEdit
+      },
+      {
+        iconName: 'delete',
+        tooltipName: 'Delete User',
+        iconColor: 'warn',
+        action: (row) => this.deleteUser(row),
+        show: (row) => row.canDelete
       }
+    ]
+  }
+  ```
+
+##### `actionsInMenu`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows actions in a dropdown menu instead of as individual buttons.
+- **Example:** `actionsInMenu: true`
+
+#### Action Button Model
+
+Each action in the `actions` array has the following properties:
+
+- **`iconName`** (string, required): Material icon name
+- **`tooltipName`** (string, optional): Tooltip text
+- **`iconColor`** ('primary' | 'warn' | 'accent', optional): Icon color
+- **`action`** ((row: any, index?: number) => void, optional): Function called when clicked
+- **`show`** ((row: any) => boolean, optional): Function to conditionally show/hide the action
+- **`url`** (string[], optional): Router navigation path (alternative to `action`)
+
+#### Other Properties
+
+##### `notShowInColumnPick`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Hides this column from the column picker dialog.
+- **Example:** `notShowInColumnPick: true`
+
+##### `selectColumnLabel`
+- **Type:** `string`
+- **Default:** `undefined`
+- **Description:** Used for special columns like selection, editing, extending. Sets the aria-label.
+
+---
+
+## Outputs (Events)
+
+### `loadData`
+- **Type:** `StMaterialTableLoadData`
+- **When emitted:** When lazy loading is enabled and data needs to be loaded (pagination, sorting, filtering changes).
+- **Payload:**
+  ```typescript
+  {
+    first: number;           // Starting index
+    rows: number;            // Number of rows to load
+    globalFilter: string;    // Global search text
+    globalFilterColumns: string[]; // Columns to search
+    sortField: string;       // Field to sort by
+    sortOrder: SortDirection; // 'asc' | 'desc'
+    filters: { [key: string]: StMaterialTableFilter }; // Column filters
+  }
+  ```
+- **Example:**
+  ```typescript
+  (loadData)="onLoadData($event)"
+  
+  onLoadData(event: StMaterialTableLoadData): void {
+    this.loading = true;
+    this.userService.getUsers(event).subscribe(response => {
+      this.users = response.data;
+      this.totalRecords = response.total;
+      this.loading = false;
     });
   }
+  ```
+
+### `saveEditedRow`
+- **Type:** `{ row: any; index: number }`
+- **When emitted:** When user saves an edited existing row.
+- **Payload:** The modified row object and its index.
+- **Example:**
+  ```typescript
+  (saveEditedRow)="onRowEdited($event)"
+  
+  onRowEdited(event: { row: any; index: number }): void {
+    this.userService.updateUser(event.row).subscribe(
+      () => {
+        // Update your data array
+        this.users[event.index] = event.row;
+        this.snackbar.success('User updated successfully');
+      },
+      error => {
+        this.snackbar.error('Failed to update user');
+      }
+    );
+  }
+  ```
+
+### `saveCreatedRow`
+- **Type:** `any`
+- **When emitted:** When user saves a newly created row (via `allowCreateRow`).
+- **Payload:** The new row object.
+- **Example:**
+  ```typescript
+  (saveCreatedRow)="onRowCreated($event)"
+  
+  onRowCreated(row: any): void {
+    this.userService.createUser(row).subscribe(
+      (createdUser) => {
+        // Add to your data array
+        this.users = [...this.users, createdUser];
+        this.snackbar.success('User created successfully');
+      },
+      error => {
+        this.snackbar.error('Failed to create user');
+      }
+    );
+  }
+  ```
+
+### `rowDeleted`
+- **Type:** `{ row: any; index: number }`
+- **When emitted:** When user deletes a row.
+- **Payload:** The deleted row object and its index.
+- **Example:**
+  ```typescript
+  (rowDeleted)="onRowDeleted($event)"
+  
+  onRowDeleted(event: { row: any; index: number }): void {
+    this.userService.deleteUser(event.row.id).subscribe(
+      () => {
+        // Remove from your data array
+        this.users = this.users.filter(u => u.id !== event.row.id);
+        this.snackbar.success('User deleted successfully');
+      },
+      error => {
+        this.snackbar.error('Failed to delete user');
+      }
+    );
+  }
+  ```
+
+### `selectRowChange`
+- **Type:** `any[]`
+- **When emitted:** When row selection changes.
+- **Payload:** Array of selected row objects.
+- **Example:**
+  ```typescript
+  (selectRowChange)="onSelectionChange($event)"
+  
+  onSelectionChange(selectedRows: any[]): void {
+    this.selectedUsers = selectedRows;
+    console.log(`${selectedRows.length} users selected`);
+  }
+  ```
+
+### `fieldValueChanged`
+- **Type:** `{ row: any; field: string; value: any; index: number }`
+- **When emitted:** When `autoSaveOnChange` is enabled and a field value changes.
+- **Payload:** The row, field name, new value, and row index.
+- **Important:** You must update your data source immediately when receiving this event.
+- **Example:**
+  ```typescript
+  (fieldValueChanged)="onFieldChanged($event)"
+  
+  onFieldChanged(event: { row: any; field: string; value: any; index: number }): void {
+    // Update local data
+    this.users[event.index][event.field] = event.value;
+    
+    // Optionally persist to server
+    this.userService.updateUser(event.row).subscribe();
+  }
+  ```
+
+---
+
+## Usage Examples
+
+### Example 1: Basic Table with Sorting and Filtering
+
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'id', header: 'ID', width: '80px' },
+  { field: 'firstName', header: 'First Name', filter: true },
+  { field: 'lastName', header: 'Last Name', filter: true },
+  { field: 'email', header: 'Email', filter: true },
+  { field: 'age', header: 'Age', type: 'number' }
+];
+
+users: any[] = [
+  { id: 1, firstName: 'John', lastName: 'Doe', email: 'john@example.com', age: 30 },
+  { id: 2, firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com', age: 25 }
+];
+```
+
+```html
+<!-- Template -->
+<ngx-st-material-table
+  tableTitle="Users"
+  [pageSize]="10"
+  [data]="users"
+  [initColumns]="columns"
+  [showGlobalSearch]="true"
+  [allowPickColumns]="true"
+  localStorageName="users-table">
+</ngx-st-material-table>
+```
+
+### Example 2: Lazy Loading Table
+
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'name', header: 'Name', filter: true },
+  { field: 'status', header: 'Status', filter: true, filterType: 'custom',
+    customFilterOptions: [
+      { value: 'active', label: 'Active' },
+      { value: 'inactive', label: 'Inactive' }
+    ]
+  }
+];
+
+users: any[] = [];
+totalRecords = 0;
+loading = false;
+
+onLoadData(event: StMaterialTableLoadData): void {
+  this.loading = true;
+  this.userService.getUsers(event).subscribe(response => {
+    this.users = response.data;
+    this.totalRecords = response.total;
+    this.loading = false;
+  });
 }
 ```
 
-### Benefits
-- **Single source of truth**: Parent's data is never mutated
-- **No ID conflicts**: IDs are generated once in the library
-- **Clear responsibility**: Library manages UI state, parent manages data
-- **Flexibility**: Parent can reject/modify changes before updating
+```html
+<!-- Template -->
+<ngx-st-material-table
+  [lazyLoading]="true"
+  [isLoading]="loading"
+  [dataLength]="totalRecords"
+  [data]="users"
+  [initColumns]="columns"
+  (loadData)="onLoadData($event)">
+</ngx-st-material-table>
+```
+
+### Example 3: Editable Table with Validation
+
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { 
+    field: 'name', 
+    header: 'Name', 
+    allowEditColumn: true,
+    editColumnRequired: true
+  },
+  { 
+    field: 'quantity', 
+    header: 'Quantity', 
+    type: 'number',
+    allowEditColumn: true,
+    rowEditType: 'number',
+    editColumnRequired: true,
+    customEditRowValidator: (oldValue, newValue, row) => {
+      if (newValue < 0) {
+        return { isValid: false, errorMessage: 'Quantity cannot be negative' };
+      }
+      if (newValue > 100) {
+        return { isValid: false, errorMessage: 'Quantity cannot exceed 100' };
+      }
+      return { isValid: true, errorMessage: '' };
+    }
+  },
+  { 
+    field: 'status', 
+    header: 'Status',
+    allowEditColumn: true,
+    rowEditType: 'custom',
+    customRowEditOptions: [
+      { value: 'draft', label: 'Draft' },
+      { value: 'published', label: 'Published' }
+    ]
+  }
+];
+
+onRowEdited(event: { row: any; index: number }): void {
+  this.updateItem(event.row);
+}
 
-### Auto-Save Mode (No Save/Cancel Buttons)
+canEditItem(row: any): boolean {
+  return row.status !== 'archived';
+}
+```
 
-For tables where you want immediate updates without save/cancel buttons (e.g., quantity inputs in selection tables):
+```html
+<!-- Template -->
+<ngx-st-material-table
+  [data]="items"
+  [initColumns]="columns"
+  [allowEditRow]="true"
+  [allowCreateRow]="true"
+  [canEditRowValidator]="canEditItem"
+  (saveEditedRow)="onRowEdited($event)"
+  (saveCreatedRow)="onRowCreated($event)"
+  (rowDeleted)="onRowDeleted($event)">
+</ngx-st-material-table>
+```
+
+### Example 4: Auto-Save Table (Instant Updates)
 
 ```typescript
-// Parent Component
-@Component({
-  selector: 'app-selection-table',
-  template: `
-    <ngx-st-material-table
-      [data]="tableData"
-      [initColumns]="columns"
-      [allowEditRow]="true"
-      [allowSelectRow]="true"
-      [autoSaveOnChange]="true"
-      (fieldValueChanged)="onFieldValueChanged($event)"
-      (selectRowChange)="onSelectionChanged($event)"
-    />
-  `
-})
-export class SelectionTableComponent {
-  tableData: any[] = [
-    { id: 1, name: 'Product A', qty: 0 },
-    { id: 2, name: 'Product B', qty: 0 },
-  ];
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'product', header: 'Product' },
+  { 
+    field: 'quantity', 
+    header: 'Quantity', 
+    type: 'number',
+    allowEditColumn: true,
+    rowEditType: 'number'
+  },
+  { 
+    field: 'active', 
+    header: 'Active', 
+    type: 'boolean',
+    allowEditColumn: true
+  }
+];
+
+onFieldChanged(event: { row: any; field: string; value: any; index: number }): void {
+  // Update local data immediately
+  this.items[event.index][event.field] = event.value;
   
-  columns: StMaterialTableColumnModel[] = [
-    { field: 'name', header: 'Name', type: 'string' },
+  // Persist to server
+  this.itemService.updateItem(event.row).subscribe();
+}
+```
+
+```html
+<!-- Template -->
+<ngx-st-material-table
+  [data]="items"
+  [initColumns]="columns"
+  [allowEditRow]="true"
+  [autoSaveOnChange]="true"
+  [setNewDataWithoutRefresh]="true"
+  (fieldValueChanged)="onFieldChanged($event)">
+</ngx-st-material-table>
+```
+
+### Example 5: Selection Table
+
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'id', header: 'ID' },
+  { field: 'name', header: 'Name' },
+  { field: 'email', header: 'Email' }
+];
+
+selectedUsers: any[] = [];
+
+onSelectionChange(selected: any[]): void {
+  this.selectedUsers = selected;
+}
+
+formatSelectedUser(row: any): string {
+  return `${row.name} (${row.email})`;
+}
+```
+
+```html
+<!-- Template -->
+<ngx-st-material-table
+  [data]="users"
+  [initColumns]="columns"
+  [allowSelectRow]="true"
+  selectionFieldLabel="name"
+  [selectRowValueDisplay]="formatSelectedUser"
+  (selectRowChange)="onSelectionChange($event)">
+</ngx-st-material-table>
+```
+
+### Example 6: Expandable Rows
+
+```html
+<!-- Template -->
+<ng-template #detailTemplate let-data="data">
+  <div class="row-detail">
+    <h4>Additional Details</h4>
+    <p><strong>Address:</strong> {{ data.address }}</p>
+    <p><strong>Phone:</strong> {{ data.phone }}</p>
+    <p><strong>Notes:</strong> {{ data.notes }}</p>
+  </div>
+</ng-template>
+
+<ngx-st-material-table
+  [data]="users"
+  [initColumns]="columns"
+  [allowExtendRow]="true"
+  [extendedRowTemplate]="detailTemplate">
+</ngx-st-material-table>
+```
+
+### Example 7: Custom Column Template
+
+```html
+<!-- Template -->
+<ng-template #statusBadgeTemplate let-row="row">
+  <span class="badge" [ngClass]="{
+    'badge-success': row.status === 'active',
+    'badge-danger': row.status === 'inactive',
+    'badge-warning': row.status === 'pending'
+  }">
+    {{ row.status | uppercase }}
+  </span>
+</ng-template>
+```
+
+```typescript
+// Component
+@ViewChild('statusBadgeTemplate') statusBadgeTemplate!: TemplateRef<any>;
+
+ngAfterViewInit() {
+  this.columns = [
+    { field: 'name', header: 'Name' },
     { 
-      field: 'qty', 
-      header: 'Quantity', 
-      type: 'number',
-      allowEditColumn: true // Field will be editable without save buttons
-    },
+      field: 'status', 
+      header: 'Status',
+      type: 'custom-template',
+      customTemplate: this.statusBadgeTemplate
+    }
   ];
+}
+```
 
-  // Handle immediate field changes
-  onFieldValueChanged(event: { row: any; field: string; value: any }) {
-    const index = this.tableData.findIndex(r => r.id === event.row.id);
-    if (index !== -1) {
-      this.tableData[index][event.field] = event.value;
-      
-      // Optional: Send to API immediately or batch updates
-      console.log('Updated:', event.row.name, event.field, event.value);
-    }
-  }
+### Example 8: Actions Column
 
-  onSelectionChanged(selectedRows: any[]) {
-    console.log('Selected rows with quantities:', selectedRows);
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'name', header: 'Name' },
+  { field: 'email', header: 'Email' },
+  {
+    field: 'actions',
+    header: 'Actions',
+    type: 'actions',
+    sort: false,
+    filter: false,
+    width: '120px',
+    actions: [
+      {
+        iconName: 'visibility',
+        tooltipName: 'View Details',
+        action: (row) => this.viewUser(row)
+      },
+      {
+        iconName: 'edit',
+        tooltipName: 'Edit User',
+        iconColor: 'primary',
+        action: (row) => this.editUser(row),
+        show: (row) => row.canEdit
+      },
+      {
+        iconName: 'delete',
+        tooltipName: 'Delete User',
+        iconColor: 'warn',
+        action: (row, index) => this.deleteUser(row, index),
+        show: (row) => row.canDelete
+      }
+    ]
   }
+];
+
+viewUser(row: any): void {
+  this.router.navigate(['/users', row.id]);
 }
+
+editUser(row: any): void {
+  // Open edit dialog
+}
+
+deleteUser(row: any, index: number): void {
+  // Delete logic
+}
+```
+
+### Example 9: Dynamic Select Options Based on Row
+
+```typescript
+// Component
+columns: StMaterialTableColumnModel[] = [
+  { field: 'country', header: 'Country', allowEditColumn: true },
+  { 
+    field: 'state', 
+    header: 'State',
+    allowEditColumn: true,
+    rowEditType: 'custom-dynamic-select',
+    dynamicRowEditOptions: (row) => {
+      if (row.country === 'USA') {
+        return [
+          { value: 'NY', label: 'New York' },
+          { value: 'CA', label: 'California' },
+          { value: 'TX', label: 'Texas' }
+        ];
+      } else if (row.country === 'UK') {
+        return [
+          { value: 'ENG', label: 'England' },
+          { value: 'SCT', label: 'Scotland' },
+          { value: 'WLS', label: 'Wales' }
+        ];
+      }
+      return [];
+    }
+  }
+];
 ```
 
-**When to use autoSaveOnChange:**
-- Selection tables with quantity inputs
-- Toggle/checkbox columns that should update immediately
-- Simple data entry without complex validation
-- Better UX when users don't want to click save buttons
+---
+
+## Best Practices
+
+1. **Use `localStorageName`** to persist user preferences (column order, filters, sorting)
+
+2. **Enable `lazyLoading`** for large datasets (1000+ records)
+
+3. **Use `autoSaveOnChange`** for simple quantity/selection tables where immediate updates are desired
+
+4. **Use `setNewDataWithoutRefresh`** when frequently updating data to prevent UI flickering
+
+5. **Provide validators** (`canEditRowValidator`, `customEditRowValidator`) to enforce business rules
+
+6. **Use custom templates** for complex cell rendering instead of trying to format with `customValueDisplay`
+
+7. **Set appropriate column widths** to prevent layout shifts
+
+8. **Use `notShowInColumnPick`** for action columns or columns that should always be visible
+
+9. **Implement proper error handling** in your event handlers (saveEditedRow, rowDeleted, etc.)
+
+10. **Use `selectRowValueDisplay`** when simple field labels aren't enough for selected row display
+
+---
+
+## Common Patterns
+
+### Pattern 1: Master-Detail Table
+Use `allowExtendRow` with `extendedRowTemplate` to show additional details without navigation.
+
+### Pattern 2: Quick Edit Grid
+Use `autoSaveOnChange` with `setNewDataWithoutRefresh` for spreadsheet-like editing.
+
+### Pattern 3: Selection List
+Use `allowSelectRow` with `selectRowOnlyOne` for choosing a single item (like a lookup).
+
+### Pattern 4: CRUD Table
+Combine `allowEditRow`, `allowCreateRow`, and action handlers for full CRUD operations.
 
-**Benefits:**
-- ✅ No save/cancel buttons (cleaner UI)
-- ✅ Immediate feedback
-- ✅ Works perfectly with row selection
-- ✅ Parent receives updates in real-time
+### Pattern 5: Filtered Report
+Use `showGlobalSearch`, column filters, and `localStorageName` for a searchable report with saved preferences.
 
-## Code scaffolding
+---
 
-Run `ng generate component component-name --project ngx-st-tables` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-st-tables`.
-> Note: Don't forget to add `--project ngx-st-tables` or else it will be added to the default project in your `angular.json` file. 
+## Troubleshooting
 
-## Build
+### Table doesn't update when data changes
+- Ensure you're passing a new array reference: `this.data = [...updatedData]`
+- Or use `setNewDataWithoutRefresh` if you want in-place updates
 
-Run `ng build ngx-st-tables` to build the project. The build artifacts will be stored in the `dist/` directory.
+### Focus lost during editing
+- Enable `setNewDataWithoutRefresh` for frequent updates
+- Ensure data array length doesn't change during edits
 
-## Publishing
+### Filters not working
+- Check that columns have `filter: true`
+- Verify `filterType` is set correctly
+- For custom filters, provide `customFilterOptions`
 
-After building your library with `ng build ngx-st-tables`, go to the dist folder `cd dist/ngx-st-tables` and run `npm publish`.
+### Lazy loading not triggered
+- Ensure `lazyLoading` is true
+- Check that `loadData` event handler is connected
+- Verify you're setting `dataLength` with total record count
 
-## Running unit tests
+### Row editing disabled
+- Check `allowEditRow` is true
+- Verify columns have `allowEditColumn: true`
+- Check `canEditRowValidator` isn't returning false
 
-Run `ng test ngx-st-tables` to execute the unit tests via [Karma](https://karma-runner.github.io).
+---
 
-## Further help
+This documentation covers all inputs, outputs, and configuration options for the Material Table component. For additional help, refer to the component source code or contact the development team.
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.