platformcommons-web-lib 1.0.0

package/documentation/smart-table.md

@@ -0,0 +1,1198 @@
+# Smart Table Component Documentation
+
+The `SmartTableComponent` is a powerful, configuration-driven data table that supports sorting, filtering, searching, pagination, and row actions. It is designed to be highly customizable via a JSON configuration object and CSS variables.
+
+## Features
+
+- **Configuration Driven**: Entire table structure and behavior defined by a single config object.
+- **Data Handling**: Built-in support for server-side pagination, sorting, and filtering.
+- **Search**: Integrated global search.
+- **Filters**: Configurable dropdown filters.
+- **Actions**: Row-level actions (Edit, Delete, Custom) and Top-bar actions (Create New, Export).
+- **Selection**: Optional checkbox selection for rows.
+- **Inline Row Editing & Addition**: Support for inline row editing and creation directly in the table.
+- **Responsive**: Adapts to different screen sizes.
+- **Theming**: Externalized theming support using CSS variables.
+- **Badges**: Built-in support for status badges with configurable colors.
+
+## Installation
+
+To install the latest version of the `commons-shared-web-ui` library, run the following command:
+
+```bash
+npm install commons-shared-web-ui@latest
+```
+
+Import the `SmartTableModule` into your feature module.
+
+```typescript
+import { SmartTableModule } from "commons-shared-web-ui";
+
+@NgModule({
+  imports: [
+    SmartTableModule,
+    // ...
+  ],
+})
+export class MyFeatureModule {}
+```
+
+## Basic Usage
+
+### Standard Mode (Internal API Fetch)
+
+1.  **Define Configuration**: In your component, create a `TableConfig` object pointing to your API.
+2.  **Pass to Component**: Use `<lib-smart-table [config]="config"></lib-smart-table>`.
+
+### External Data Mode (Parent Driven)
+
+1.  **Define Configuration**: Create a `TableConfig` object (no `apiUrl` needed).
+2.  **Pass Data**: Bind your data array to `[tableData]` and count to `[totalItemsCount]`.
+3.  **Listen to Events**: Bind to `(sortChange)`, `(pageChange)`, and `(searchChange)` to fetch data manually when the user interacts with the table.
+
+### Example
+
+```typescript
+import { TableConfig } from "@campus-cloud/shared-ui";
+
+export class MyComponent {
+  tableConfig: TableConfig = {
+    apiUrl: "https://api.example.com/users",
+    columns: [
+      { key: "id", label: "ID", type: "number", sortable: true },
+      { key: "name", label: "Name", type: "text", sortable: true },
+      {
+        key: "status",
+        label: "Status",
+        type: "badge",
+        badgeConfig: {
+          active: "success",
+          draft: "neutral",
+          deleted: "danger",
+        },
+      },
+    ],
+    pagination: {
+      enabled: true,
+      pageSize: 10,
+      pageSizeOptions: [5, 10, 25],
+    },
+    actions: [
+      {
+        label: "Edit",
+        type: "callback",
+        icon: "fa fa-edit",
+        btnVariant: "outline",
+        callback: (row) => this.onEdit(row),
+      },
+    ],
+  };
+
+  onEdit(row: any) {
+    console.log("Edit", row);
+  }
+}
+```
+
+```html
+<lib-smart-table
+  [config]="tableConfig"
+  (action)="onTableAction($event)"
+></lib-smart-table>
+```
+
+## Configuration Reference
+
+### TableConfig
+
+| Property            | Type                | Description                                                                                           |
+| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
+| `apiUrl`            | `string`            | (Optional in External Mode) Base URL for fetching data.                                               |
+| `apiMethod`         | `'GET' \\| 'POST'`  | (Optional) HTTP method for fetching data (default: `GET`).                                            |
+| `apiPayload`        | `any`               | (Optional) Body payload to send if `apiMethod` is `POST`.                                             |
+| `columns`           | `TableColumn[]`     | Array of column definitions.                                                                          |
+| `filters`           | `TableFilter[]`     | Array of filter definitions (dropdowns).                                                              |
+| `pagination`        | `PaginationConfig`  | Pagination settings.                                                                                  |
+| `actions`           | `TableAction[]`     | Row-level actions.                                                                                    |
+| `topBarButtons`     | `TableAction[]`     | Buttons to display above the table.                                                                   |
+| `selectable`        | `boolean`           | Enable row checkbox selection.                                                                        |
+| `sortBy`            | `string`            | Default sort column key.                                                                              |
+| `orderBy`           | `'ASC' \| 'DESC'`   | Default sort order.                                                                                   |
+| `searchConfig`      | `SearchConfig`      | Global search configuration (replaces `searchEnabled`).                                               |
+| `queryParamsConfig` | `QueryParamsConfig` | (Optional) Advanced configuration for query parameter serialization.                                  |
+| `dataResponsePath`  | `string`            | (Optional) Path to data array in API response (e.g. `data` or `response.list`). Empty for root array. |
+| `labels`            | `TableLabels`       | (Optional) Override default text labels.                                                              |
+| `editingRowClass`   | `string`            | (Optional) CSS class to apply to rows currently being edited or added.                                |
+
+### TableColumn
+
+| Property      | Type                                                | Description                                                                              |
+| ------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `key`         | `string`                                            | Property key in the data object.                                                         |
+| `label`       | `string`                                            | Header display text.                                                                     |
+| `type`        | `'text' \| 'number' \| 'date' \| 'html' \| 'badge'` | Data type for display formatting.                                                        |
+| `sortable`    | `boolean`                                           | Enable sorting for this column.                                                          |
+| `editable`    | `boolean`                                           | Enables inline editing/adding for this column.                                           |
+| `dataType`    | `'text' \| 'number' \| 'date' \| 'email' \| 'select'`| (Optional) Input type for inline editing (uses `mat-datepicker` for `'date'`).            |
+| `options`     | `TableOption[]`                                     | (Optional) Dropdown select options when `dataType` is `'select'`.                        |
+| `subFields`   | `TableColumnSubField[]`                             | (Optional) Configures stacked inputs within a single cell for display/edit.              |
+| `editConfig`  | `object`                                            | (Optional) Configures defaults (`defaultValue`) and disabled state (`disabled`) in edit. |
+| `badgeConfig` | `object`                                            | Map values to badge variants (`success`, `warning`, `danger`, `info`, `neutral`).        |
+| `labelPath`   | `string`                                            | (Optional) Path to nested data (e.g., `user.address.city`). Overrides `key` for display. |
+| `dateFormat`  | `string`                                            | (Optional) Date format string (e.g., `short`, `dd/MM/yyyy`) for `type: 'date'`.          |
+| `clickAction` | `'route' \| 'callback'`                             | (Optional) Action to perform on cell click.                                              |
+| `clickRoute`  | `string`                                            | (Optional) Route pattern for redirection (e.g. `/users/:id`) if action is `route`.       |
+
+### TableFilter
+
+| Property             | Type                            | Description                                                    |
+| -------------------- | ------------------------------- | -------------------------------------------------------------- |
+| `key`                | `string`                        | Key to use for the filter query param.                         |
+| `label`              | `string`                        | Display label for the filter dropdown.                         |
+| `type`               | `'select'`                      | Filter type.                                                   |
+| `options`            | `array`                         | (Optional) Static array of `{label, value}` objects.           |
+| `apiUrl`             | `string`                        | (Optional) API URL to fetch filter options.                    |
+| `apiMethod`          | `'GET' \\| 'POST'`              | (Optional) HTTP method for fetching filter options (default: `GET`). |
+| `apiPayload`         | `any`                           | (Optional) Body payload to send if `apiMethod` is `POST`.      |
+| `dataPath`           | `string`                        | (Optional) Path to array in filter API response.               |
+| `labelPath`          | `string`                        | (Optional) Path to label property in API object.               |
+| `valuePath`          | `string`                        | (Optional) Path to value property in API object.               |
+| `requestKey`         | `string`                        | (Optional) Query param key if different from `key`.            |
+| `handling`           | `'standard' \| 'nested_string'` | Strategy for filter APIs. Appends to `paramName` if nested.    |
+| `nestedStringConfig` | `NestedStringConfig`            | Configuration for nested string serialization for filter APIs. |
+
+### SearchConfig
+
+| Property       | Type                            | Description                                                                       |
+| -------------- | ------------------------------- | --------------------------------------------------------------------------------- |
+| `enabled`      | `boolean`                       | Enable search input.                                                              |
+| `searchKey`    | `string`                        | Query param key to use (default: `search`).                                       |
+| `debounceTime` | `number`                        | Debounce time in ms (default: `300`).                                             |
+| `handling`     | `'standard' \| 'nested_string'` | Strategy. `nested_string` appends `SEARCH_TERM=value` to the nested param string. |
+
+### PaginationConfig
+
+| Property           | Type       | Description                                       |
+| ------------------ | ---------- | ------------------------------------------------- |
+| `enabled`          | `boolean`  | Enable pagination.                                |
+| `pageSize`         | `number`   | Default number of items per page.                 |
+| `pageSizeOptions`  | `number[]` | Array of page size options (e.g. `[10, 25, 50]`). |
+| `totalCountConfig` | `object`   | Config for total items count (see below).         |
+
+#### TotalCountConfig
+
+| Property       | Type                   | Description                                                                          |
+| -------------- | ---------------------- | ------------------------------------------------------------------------------------ |
+| `source`       | `'same' \| 'separate'` | `'same'` (default) if count is in data response, `'separate'` for separate API call. |
+| `responsePath` | `string`               | Path to total count property (e.g. `total` or `meta.count`).                         |
+| `apiUrl`       | `string`               | (Required if source='separate') URL for count API.                                   |
+
+SAMPLE:
+
+labels: {
+searchPlaceholder: "Search Users...", //fetch from i18ne
+actionColumnHeader: "Manage",
+noDataMessage: "No users found.",
+defaultConfirmationMessage: "Do you really want to proceed?"
+} |
+
+### QueryParamsConfig
+
+| Property             | Type                            | Description                                                                           |
+| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
+| `pageKey`            | `string`                        | Query param for page number (default: `page`).                                        |
+| `sizeKey`            | `string`                        | Query param for page size (default: `pageSize`).                                      |
+| `pageIndexOffset`    | `number`                        | Offset for page index (e.g. `-1` to convert 1-based UI to 0-based API).               |
+| `filterHandling`     | `'standard' \| 'nested_string'` | implementation strategy. `nested_string` serializes filters into typically one param. |
+| `nestedStringConfig` | `NestedStringConfig`            | Configuration for nested string serialization.                                        |
+
+### NestedStringConfig
+
+| Property     | Type     | Description                                             |
+| ------------ | -------- | ------------------------------------------------------- |
+| `paramName`  | `string` | The query param key hosting the string (e.g. `params`). |
+| `baseValue`  | `string` | Initial value/prefix (e.g. `MARKET_ID=5`).              |
+| `separator`  | `string` | Separator between key-values (e.g. `--` or `;`).        |
+| `assignment` | `string` | Assignment operator (e.g. `=` or `:`).                  |
+
+### TableLabels
+
+| Property                     | Type     | Description                                        |
+| ---------------------------- | -------- | -------------------------------------------------- |
+| `searchPlaceholder`          | `string` | Placeholder text for the search input.             |
+| `actionColumnHeader`         | `string` | Header text for the actions column.                |
+| `noDataMessage`              | `string` | Message displayed when no data is found.           |
+| `itemsPerPageLabel`          | `string` | Label for items per page selector (if applicable). |
+| `defaultConfirmationMessage` | `string` | Default message for action confirmation dialogs.   |
+
+### TableAction
+
+| Property             | Type                                                     | Description                                |
+| -------------------- | -------------------------------------------------------- | ------------------------------------------ |
+| `label`              | `string`                                                 | Button text.                               |
+| `type`               | `'api' \| 'route' \| 'callback' \| 'edit' \| 'dropdown'` | Action type.                               |
+| `btnVariant`         | `ButtonVariant`                                          | Style variant of the button.               |
+| `icon`               | `string`                                                 | Icon class (e.g. `fa fa-edit`).            |
+| `route`              | `string`                                                 | Internal route path (e.g. `/users/:id`).   |
+| `apiUrl`             | `string`                                                 | API endpoint for 'api' type.               |
+| `apiMethod`          | `'POST' \| ...`                                          | HTTP method for 'api' type.                |
+| `callback`           | `(row: any) => void`                                     | Function to execute on click.              |
+| `confirmationNeeded` | `boolean`                                                | Show confirmation dialog before executing. |
+| `items`              | `TableActionItem[]`                                      | Children items for 'dropdown' action.      |
+
+## Action Examples
+
+### 1. Callback (Opening a Modal)
+
+Use `type: 'callback'` to execute a function, such as opening a dialog.
+
+```typescript
+// Component
+actions: [
+  {
+    label: 'Edit User',
+    type: 'callback',
+    icon: 'fa fa-edit',
+    callback: (row) => this.openEditModal(row)
+  }
+]
+
+openEditModal(row: any) {
+  this.dialogService.open(EditUserComponent, { data: row });
+}
+```
+
+### 2. Route Navigation
+
+Use `type: 'route'` for internal navigation. Parameters like `:id` are automatically replaced by row values.
+
+```typescript
+actions: [
+  {
+    label: "View Details",
+    type: "route",
+    route: "/users/:id/details", // :id will be replaced by row.id
+    btnVariant: "primary",
+  },
+];
+```
+
+### 3. API Action
+
+Use `type: 'api'` to emit an event or trigger an HTTP request directly. Use `confirmationNeeded` for critical actions.
+
+#### Direct HTTP Execution (New)
+
+If `apiUrl` is specified in the configuration, the Smart Table will **automatically execute the HTTP request** (e.g., POST, DELETE) for you. Variable substitution works the same as routing (`:id` gets replaced by `row.id`). Upon success, the table will reload its data automatically.
+
+#### Event Emission Strategy
+
+If no `apiUrl` is specified, it merely emits the `(action)` or `(topAction)` event to the parent component, allowing you to handle the API call process manually.
+
+```typescript
+actions: [
+  {
+    label: "Delete",
+    type: "api",
+    btnVariant: "danger",
+    apiUrl: "https://api.example.com/users/:id", // Auto-executes DELETE request
+    apiMethod: "DELETE",
+    confirmationNeeded: true,
+    confirmationMessage: "Are you sure you want to delete this user?",
+  },
+];
+```
+
+### 4. Dropdown Action Menu
+
+Use `type: 'dropdown'` with the `items` array to render a 3-dots action menu with multiple choices.
+
+```typescript
+actions: [
+  {
+    label: "",
+    type: "dropdown",
+    icon: "fa fa-ellipsis-v", // or ellipsis-h, etc.
+    items: [
+      {
+        label: "Send Email",
+        type: "callback",
+        callback: (row) => this.sendEmail(row),
+      },
+      {
+        label: "Assign Badges",
+        type: "callback",
+        callback: (row) => this.assignBadges(row),
+      },
+      {
+        label: "Convert to Alumni",
+        type: "api",
+        apiUrl: "...",
+        confirmationNeeded: true,
+      },
+    ],
+  },
+];
+```
+
+### 5. Native Delete Action (Built-in Confirmation Modal + API)
+
+Use `type: 'delete'` inside a dropdown `items` array to get a fully self-contained delete flow without any parent-side code:
+
+- Smart table opens the `cc-confirmation-modal` from the shared UI library.
+- On confirm, it calls `DELETE /:id` with the ID dynamically resolved from the row.
+- On success, the table reloads automatically.
+- All modal labels are configurable via `deleteConfig` (pass i18n-resolved strings from your component or JSON config).
+
+#### `deleteConfig` Properties
+
+| Property       | Type     | Default                             | Description                                             |
+| -------------- | -------- | ----------------------------------- | ------------------------------------------------------- |
+| `apiUrl`       | `string` | *required*                          | DELETE endpoint. Use `:id` (or any field name) as token.|
+| `idField`      | `string` | `'id'`                              | Row field used to replace the URL token.                |
+| `modalTitle`   | `string` | `'Confirm Delete'`                  | Title shown in the confirmation modal header.           |
+| `modalMessage` | `string` | `'Are you sure...'`                 | Body message inside the modal.                          |
+| `confirmLabel` | `string` | `'Delete'`                          | Label for the confirm (danger) button.                  |
+| `cancelLabel`  | `string` | `'Cancel'`                          | Label for the cancel button.                            |
+
+#### Typescript Example
+
+```typescript
+// In your component or JSON config (after i18n translation is applied)
+actions: [
+  {
+    label: '',
+    type: 'dropdown',
+    icon: 'fa fa-ellipsis-h',
+    btnVariant: 'text',
+    items: [
+      {
+        label: 'Edit',
+        icon: 'fa fa-edit',
+        type: 'edit'
+      },
+      {
+        label: 'Delete',
+        icon: 'fa fa-trash',
+        type: 'delete',
+        deleteConfig: {
+          apiUrl: 'gateway/my-service/api/v1/items/:id',  // :id replaced by row.id
+          idField: 'id',                                  // default; can use any row field
+          modalTitle: 'Delete Item?',
+          modalMessage: 'Are you sure you want to delete this item? This action cannot be undone.',
+          confirmLabel: 'Yes, Delete',
+          cancelLabel: 'Cancel'
+        }
+      }
+    ]
+  }
+]
+```
+
+#### JSON Config Example (with i18n keys — resolved by MFE before passing to table)
+
+```json
+{
+  "actions": [
+    {
+      "label": "",
+      "type": "dropdown",
+      "icon": "fa fa-ellipsis-h",
+      "btnVariant": "text",
+      "items": [
+        { "label": "Edit", "icon": "fa fa-edit", "type": "edit" },
+        {
+          "label": "DELETE_LABEL_I18N_KEY",
+          "icon": "fa fa-trash",
+          "type": "delete",
+          "deleteConfig": {
+            "apiUrl": "gateway/commons-learning-center-service/api/v1/learning-center-type-masters/:id",
+            "idField": "id",
+            "modalTitle": "DELETE_MODAL_TITLE_I18N_KEY",
+            "modalMessage": "DELETE_MODAL_MESSAGE_I18N_KEY",
+            "confirmLabel": "DELETE_MODAL_CONFIRM_I18N_KEY",
+            "cancelLabel": "DELETE_MODAL_CANCEL_I18N_KEY"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+> **Note**: The `deleteConfig.apiUrl` supports the same `:fieldName` interpolation as `route` and `action.apiUrl`. For a row with `{ id: 42, ... }`, the URL `…/items/:id` becomes `…/items/42` at runtime.
+
+### 6. Advanced Configuration (Query Params & Filters)
+
+
+Supported advanced features:
+
+- Nested string query parameters (e.g. `params=MARKET_ID=5--STATUS=ACTIVE`)
+- Separate API for total count
+- Response path mapping
+- **Externalized Labels**
+
+```typescript
+tableConfig: TableConfig = {
+  apiUrl: "https://api.example.com/solutions/execute",
+
+  // Custom Labels
+  labels: {
+    searchPlaceholder: "Search Solutions...",
+    actionColumnHeader: "Manage",
+    noDataMessage: "No solutions found.",
+    defaultConfirmationMessage: "Do you really want to proceed?"
+  },
+
+  // ... rest of config
+
+  // Map data from a nested property in response
+  dataResponsePath: "data.elements",
+
+  columns: [
+    { key: "id", label: "ID", type: "number", sortable: true },
+    { key: "status", label: "Status", type: "text", sortable: true }
+  ],
+
+  // Dynamic Filters from API
+  filters: [
+    {
+      key: "status",
+      label: "Status",
+      type: "select",
+      apiUrl: "https://api.example.com/ref-data/status",
+      // Map options from API response
+      dataPath: "elements",
+      labelPath: "name",
+      valuePath: "code",
+      // Example nested string support for filter APIs
+      handling: "nested_string",
+      nestedStringConfig: {
+        paramName: "params",
+        baseValue: "TYPE=STATUS" // Append `params=TYPE=STATUS` to fetch call
+      }
+    }
+  ],
+
+  pagination: {
+    enabled: true,
+    pageSize: 10,
+    pageSizeOptions: [10, 50],
+    // Fetch total count from a different API
+    totalCountConfig: {
+      source: "separate",
+      apiUrl: "https://api.example.com/solutions/count/execute",
+      responsePath: "0.totalCount"
+    }
+  },
+
+  // Enhanced Search Configuration
+  searchConfig: {
+    enabled: true,
+    searchKey: "SEARCH_TERM",
+    debounceTime: 500, // 500ms debounce
+    handling: "nested_string" // Appends to params=... string
+  },
+
+  // Custom Query Param Serialization
+  queryParamsConfig: {
+    pageKey: "page",
+    sizeKey: "size",
+    pageIndexOffset: -1, // UI uses 1-based, API uses 0-based
+    filterHandling: "nested_string",
+    nestedStringConfig: {
+      paramName: "params",
+      baseValue: "MARKET_ID=5", // Initial value
+      separator: "--",          // Separator between filters
+      assignment: "="           // Assignment operator
+    }
+  }
+};
+};
+```
+
+### 5. Nested Data & Date Formatting
+
+You can fetch data from deep nested objects using `labelPath` and format dates using `dateFormat`.
+
+#### Example: Nested Data
+
+Access properties like `user.profile.name` or `names[0].text`.
+
+```typescript
+columns: [
+  {
+    key: "curriculumName", // Unique key
+    label: "Curriculum Name",
+    // Fetch data from names[0].text
+    labelPath: "names[0].text",
+  },
+  {
+    key: "category",
+    label: "Category",
+    // Fetch data from nested object
+    labelPath: "meta.category.name",
+  },
+];
+```
+
+#### Example: Date Formatting
+
+Use `type: 'date'` and provide a `dateFormat`. Supports Angular's `formatDate` patterns.
+
+```typescript
+columns: [
+  {
+    key: "startDate",
+    label: "Start Date",
+    type: "date",
+    // Short format: 2/17/26, 9:42 PM
+    dateFormat: "short",
+  },
+  {
+    key: "endDate",
+    label: "End Date",
+    type: "date",
+    // Custom format: 17-Feb-2026
+    dateFormat: "dd-MMM-yyyy",
+  },
+  {
+    key: "createdAt",
+    label: "Created At",
+    type: "date",
+    // Combine labelPath and dateFormat for nested dates
+    labelPath: "meta.audit.createdDate",
+    dateFormat: "medium",
+  },
+];
+```
+
+## Outputs (Events)
+
+### 6. Column Click Actions
+
+You can make specific columns clickable, triggering either a route navigation or a callback event.
+
+#### Route Navigation
+
+Redirects to an internal route. The `:param` syntax is supported.
+
+```typescript
+{
+  key: "name",
+  label: "Name",
+  type: "text",
+  clickAction: "route",
+  clickRoute: "/users/:id/profile" // :id replaced by row.id
+}
+```
+
+#### Callback Event
+
+Emits a `(columnClick)` event which you can handle in your component.
+
+```typescript
+// Component Config
+{
+  key: "status",
+  label: "Status",
+  type: "badge",
+  clickAction: "callback"
+}
+
+// Template
+<lib-smart-table
+    [config]="config"
+    (columnClick)="onColumnClick($event)">
+</lib-smart-table>
+
+// Component Method
+onColumnClick(event: { row: any, column: string }) {
+    if (event.column === 'status') {
+        console.log('Status clicked for:', event.row);
+    }
+}
+```
+
+## Inputs / Outputs
+
+### Inputs
+
+| Input               | Type            | Description                                                                                   |
+| ------------------- | --------------- | --------------------------------------------------------------------------------------------- |
+| `[config]`          | `TableConfig`   | (Required) The main configuration object.                                                     |
+| `[tableData]`       | `any[]`         | (Optional) Bypasses internal API calls and renders explicitly provided row data.              |
+| `[totalItemsCount]` | `number`        | (Optional) The total count of all items, used for pagination when `[tableData]` is activated. |
+
+### Outputs (Events)
+
+| Output           | Description                                                      | Payload                             |
+| ---------------- | ---------------------------------------------------------------- | ----------------------------------- |
+| `(action)`       | Emitted when any row action is clicked.                          | `{ action: TableAction, row: any }` |
+| `(topAction)`    | Emitted when a top-bar button is clicked.                        | `TableAction`                       |
+| `(filterChange)` | Emitted when a filter value changes.                             | `{ key: string, value: any }`       |
+| `(rowSelect)`    | Emitted when row selection changes.                              | `any[]` (Array of selected rows)    |
+| `(columnClick)`  | Emitted when a column with `clickAction: 'callback'` is clicked. | `{ row: any, column: string }`      |
+| `(sortChange)`   | **(External Mode)** Emitted when sort column/direction changes.  | `TableDataChangeEvent`              |
+| `(pageChange)`   | **(External Mode)** Emitted when page index/size changes.        | `TableDataChangeEvent`              |
+| `(searchChange)` | **(External Mode)** Emitted when global search term changes.     | `TableDataChangeEvent`              |
+
+### TableDataChangeEvent
+When the table operates in **External Data Mode** (by passing `[tableData]`), it emits the `TableDataChangeEvent` interface when sort, pagination, or search changes:
+```typescript
+interface TableDataChangeEvent {
+    page: number;
+    pageSize: number;
+    sortBy?: string;
+    orderBy?: 'ASC' | 'DESC';
+    searchTerm?: string;
+    filters?: { [key: string]: any };
+}
+```
+
+---
+
+## Theming & Styling
+
+The Smart Table uses CSS custom properties for all visual styling. Every colour, size, shadow, and border is exposed as a variable so you can theme the component without overriding any internal styles.
+
+There are two ways to apply a theme:
+
+1. **Direct CSS variables** — set them anywhere in your stylesheet (`:root`, a wrapper class, or inline).
+2. **SCSS mixin** — use `smart-table-theme()` from `smart-table.theme.scss`, which maps human-readable Sass keys to the CSS variables in one call.
+
+---
+
+### CSS Variable Reference
+
+#### General
+
+| Variable           | Default                | Description                              |
+| ------------------ | ---------------------- | ---------------------------------------- |
+| `--st-font-family` | `'Roboto', sans-serif` | Font family for the entire table         |
+| `--st-font-size`   | `14px`                 | Base font size for cells and toolbar     |
+| `--st-text-color`  | `#333`                 | Primary text colour                      |
+| `--st-border-radius` | `8px`                | Corner radius of the table card          |
+| `--st-box-shadow`  | `0 2px 8px rgba(0,0,0,0.08)` | Shadow of the table card          |
+| `--st-table-bg`    | `#fff`                 | Background of the table card             |
+
+#### Table Layout
+
+| Variable            | Default             | Description                        |
+| ------------------- | ------------------- | ---------------------------------- |
+| `--st-table-padding` | `1rem`             | Padding around the table container |
+| `--st-cell-padding` | `1rem`              | Padding inside each body cell      |
+| `--st-table-border` | `1px solid #e0e0e0` | Outer border of the table wrapper  |
+| `--st-row-border`   | `1px solid #eee`    | Bottom border between rows         |
+
+#### Header
+
+| Variable               | Default    | Description                              |
+| ---------------------- | ---------- | ---------------------------------------- |
+| `--st-header-bg`       | `#f5f5f5`  | Background of the `<thead>` row          |
+| `--st-header-color`    | `#333`     | Text colour of header cells              |
+| `--st-header-weight`   | `500`      | Font weight of header cells              |
+| `--st-header-size`     | `14px`     | Font size of header cells                |
+| `--st-header-transform`| `none`     | `text-transform` value (`uppercase` etc.)|
+| `--st-header-border`   | `1px solid #e0e0e0` | Border applied to the header  |
+
+#### Rows
+
+| Variable               | Default    | Description                                |
+| ---------------------- | ---------- | ------------------------------------------ |
+| `--st-row-bg`          | `#fff`     | Default row background                     |
+| `--st-row-hover-bg`    | `#f5f5f5`  | Row background on mouse hover              |
+| `--st-row-selected-bg` | `#f3e5f5`  | Row background when checkbox is checked    |
+| `--st-first-col-color` | `#E84646`  | Text colour of the first column on hover   |
+
+#### Frozen Columns
+
+Frozen columns include the checkbox column, the first data column (when sticky), and the pinned Actions column.
+
+| Variable                | Default    | Description                                       |
+| ----------------------- | ---------- | ------------------------------------------------- |
+| `--st-frozen-col-bg`    | `#f9f9f9`  | Background of all frozen/pinned columns           |
+| `--st-actions-col-shadow` | `-4px 0 8px rgba(0,0,0,0.06)` | Shadow on the right-pinned Actions column |
+
+#### Toolbar
+
+| Variable                  | Default                          | Description                           |
+| ------------------------- | -------------------------------- | ------------------------------------- |
+| `--st-toolbar-bg`         | `#fff`                           | Background of the toolbar bar         |
+| `--st-toolbar-padding`    | `1.2rem 0rem`                    | Padding inside the toolbar            |
+| `--st-toolbar-border-bottom` | `1px solid rgba(0,0,0,0.08)` | Separator line below the toolbar      |
+| `--st-toolbar-gap`        | `1rem`                           | Gap between search, filters, buttons  |
+
+#### Search
+
+| Variable                      | Default       | Description                                  |
+| ----------------------------- | ------------- | -------------------------------------------- |
+| `--st-search-bg`              | `#f5f5f5`     | Background of the search wrapper pill        |
+| `--st-search-radius`          | `8px`         | Border radius of the search wrapper          |
+| `--st-search-wrapper-padding` | `0 0.875rem`  | Horizontal padding inside the search wrapper |
+| `--st-search-height`          | `36px`        | Height of the search input area              |
+| `--st-search-min-width`       | `200px`       | Minimum width of the search input            |
+| `--st-search-width`           | `auto`        | Width of the search input (overrides min)    |
+| `--st-search-icon-color`      | `#888`        | Colour of the search magnifier icon          |
+| `--st-search-placeholder-color` | `#999`      | Placeholder text colour                      |
+
+#### Filters (Trigger Button)
+
+Each filter renders as a styled button. These variables control the trigger appearance.
+
+| Variable                        | Default             | Description                                      |
+| ------------------------------- | ------------------- | ------------------------------------------------ |
+| `--st-filter-bg`                | `#fff`              | Background of the filter trigger                 |
+| `--st-filter-border`            | `1px solid #e0e0e0` | Border of the filter trigger                     |
+| `--st-filter-radius`            | `8px`               | Border radius of the filter trigger              |
+| `--st-filter-height`            | `36px`              | Height of the filter trigger                     |
+| `--st-filter-trigger-padding`   | `0 0.75rem`         | Horizontal padding inside the filter trigger     |
+| `--st-filter-font-size`         | `14px`              | Font size of the filter label                    |
+| `--st-filter-color`             | `#555`              | Default text colour of the filter label          |
+| `--st-filter-hover-bg`          | `#fafafa`           | Background when hovering or open                 |
+| `--st-filter-hover-border-color`| `#bbb`              | Border colour on hover                           |
+| `--st-filter-active-border-color`| `#999`             | Border colour when the dropdown is open          |
+| `--st-filter-selected-color`    | `#222`              | Text colour when a value is selected             |
+| `--st-filter-selected-border-color` | `#333`          | Border colour when a value is selected           |
+| `--st-filter-chevron-color`     | `#999`              | Colour of the chevron/arrow icon                 |
+
+#### Filter Dropdown Panel
+
+These variables style the dropdown drawer that appears when a filter is opened.
+
+| Variable                        | Default                                           | Description                                   |
+| ------------------------------- | ------------------------------------------------- | --------------------------------------------- |
+| `--st-filter-panel-bg`          | `#fff`                                            | Background of the dropdown panel              |
+| `--st-filter-panel-border`      | `1px solid #ebebeb`                               | Border of the dropdown panel                  |
+| `--st-filter-panel-radius`      | `12px`                                            | Corner radius of the dropdown panel           |
+| `--st-filter-panel-shadow`      | `0 8px 28px rgba(0,0,0,0.12), 0 2px 8px rgba(0,0,0,0.06)` | Shadow of the dropdown panel |
+| `--st-filter-panel-min-width`   | `180px`                                           | Minimum width of the dropdown panel           |
+| `--st-filter-panel-padding`     | `6px`                                             | Inner padding of the dropdown panel           |
+| `--st-filter-option-padding`    | `8px 12px`                                        | Padding of each option row                    |
+| `--st-filter-option-radius`     | `7px`                                             | Corner radius of each option row              |
+| `--st-filter-option-hover-bg`   | `#f5f5f5`                                         | Background of an option on hover              |
+| `--st-filter-option-selected-bg`| `#f0f0f0`                                         | Background of the currently selected option   |
+| `--st-filter-option-selected-color` | `#111`                                        | Text colour of the currently selected option  |
+
+#### Selection Strip
+
+Shown above the table header when `config.selectable` is `true`. Displays "X of Y selected".
+
+| Variable                         | Default                          | Description                               |
+| -------------------------------- | -------------------------------- | ----------------------------------------- |
+| `--st-selection-strip-bg`        | `#fafafa`                        | Background of the selection count bar     |
+| `--st-selection-strip-border`    | `1px solid rgba(0,0,0,0.08)`     | Bottom border of the selection bar        |
+| `--st-selection-strip-padding`   | `0.45rem 1rem`                   | Padding inside the selection bar          |
+| `--st-selection-count-color`     | `#444`                           | Text colour of the count label            |
+| `--st-selection-count-font-size` | `13px`                           | Font size of the count label              |
+| `--st-selection-count-font-weight`| `500`                           | Font weight of the count label            |
+
+#### Checkboxes
+
+| Variable            | Default   | Description                          |
+| ------------------- | --------- | ------------------------------------ |
+| `--st-checkbox-color` | `#e63e30` | Accent colour for checkboxes        |
+| `--st-checkbox-size`  | `16px`    | Width and height of checkboxes      |
+
+#### Row Action Dropdown
+
+Styles the three-dot (ellipsis) action menu that appears in the Actions column.
+
+| Variable                      | Default                        | Description                                  |
+| ----------------------------- | ------------------------------ | -------------------------------------------- |
+| `--st-action-circle-size`     | `32px`                         | Diameter of the three-dot trigger circle     |
+| `--st-dropdown-min-width`     | `150px`                        | Minimum width of the dropdown menu           |
+| `--st-dropdown-bg`            | `#fff`                         | Background of the dropdown menu              |
+| `--st-dropdown-border`        | `1px solid #e0e0e0`            | Border of the dropdown menu                  |
+| `--st-dropdown-radius`        | `8px`                          | Corner radius of the dropdown menu           |
+| `--st-dropdown-shadow`        | `0 8px 24px rgba(0,0,0,0.12)` | Shadow of the dropdown menu                  |
+| `--st-dropdown-padding`       | `4px`                          | Inner padding of the dropdown menu container |
+| `--st-dropdown-item-padding`  | `8px 12px`                     | Padding of each menu item                    |
+| `--st-dropdown-item-radius`   | `6px`                          | Corner radius of each menu item              |
+| `--st-dropdown-item-hover-bg` | `#f5f5f5`                      | Background of a menu item on hover           |
+
+#### Badges
+
+| Variable                  | Default     | Description                          |
+| ------------------------- | ----------- | ------------------------------------ |
+| `--st-badge-radius`       | `12px`      | Border radius of badge pills         |
+| `--st-badge-padding`      | `4px 12px`  | Padding inside badge pills           |
+| `--st-badge-font-size`    | `12px`      | Font size of badge text              |
+| `--st-badge-font-weight`  | `500`       | Font weight of badge text            |
+| `--st-badge-success-bg`   | `#e8f5e9`   | Background — `success` variant       |
+| `--st-badge-success-color`| `#2e7d32`   | Text colour — `success` variant      |
+| `--st-badge-warning-bg`   | `#fff3e0`   | Background — `warning` variant       |
+| `--st-badge-warning-color`| `#ef6c00`   | Text colour — `warning` variant      |
+| `--st-badge-danger-bg`    | `#ffebee`   | Background — `danger` variant        |
+| `--st-badge-danger-color` | `#c62828`   | Text colour — `danger` variant       |
+| `--st-badge-info-bg`      | `#e3f2fd`   | Background — `info` variant          |
+| `--st-badge-info-color`   | `#1565c0`   | Text colour — `info` variant         |
+| `--st-badge-neutral-bg`   | `#f5f5f5`   | Background — `neutral` variant       |
+| `--st-badge-neutral-color`| `#616161`   | Text colour — `neutral` variant      |
+
+#### Scrollbar
+
+| Variable                        | Default   | Description                            |
+| ------------------------------- | --------- | -------------------------------------- |
+| `--st-scrollbar-width`          | `8px`     | Width of the horizontal scrollbar      |
+| `--st-scrollbar-height`         | `8px`     | Height of the horizontal scrollbar     |
+| `--st-scrollbar-track-bg`       | `#f1f1f1` | Scrollbar track background             |
+| `--st-scrollbar-track-radius`   | `4px`     | Scrollbar track corner radius          |
+| `--st-scrollbar-thumb-bg`       | `#c1c1c1` | Scrollbar thumb colour                 |
+| `--st-scrollbar-thumb-radius`   | `4px`     | Scrollbar thumb corner radius          |
+| `--st-scrollbar-thumb-hover-bg` | `#a8a8a8` | Scrollbar thumb colour on hover        |
+
+#### Sticky Columns
+
+| Variable                 | Default                       | Description                          |
+| ------------------------ | ----------------------------- | ------------------------------------ |
+| `--st-sticky-shadow`     | `2px 0 5px -2px rgba(0,0,0,0.1)` | Shadow cast by sticky columns    |
+| `--st-sticky-border-right` | `1px solid rgba(0,0,0,0.05)` | Right border of sticky columns      |
+
+#### Loader & Misc
+
+| Variable                   | Default                    | Description                        |
+| -------------------------- | -------------------------- | ---------------------------------- |
+| `--st-loader-color`        | `#6200EE`                  | Spinner border colour              |
+| `--st-spinner-border-color`| `rgba(0,0,0,0.1)`          | Spinner track colour               |
+| `--st-no-data-color`       | `#888`                     | Colour of the "No data" message    |
+| `--st-sort-icon-size`      | `0.8em`                    | Size of the column sort icon       |
+| `--st-pagination-padding`  | `0.75rem 0`                | Padding around the pagination bar  |
+
+---
+
+### Using the Theme Mixin
+
+The SCSS mixin in `smart-table.theme.scss` is the recommended way to set multiple variables at once. Pass a map of keys to override — unspecified keys fall back to the defaults above.
+
+```scss
+@use "commons-shared-web-ui/src/lib/modules/smart-table/smart-table.theme" as smart-table;
+@use "commons-shared-web-ui/src/lib/modules/pagination/pagination.theme" as pagination;
+@use "commons-shared-web-ui/src/lib/modules/button/button.theme" as button;
+
+:root {
+  // Required peer themes
+  @include pagination.pagination-theme();
+  @include button.button-theme();
+
+  // Smart Table — only override what you need
+  @include smart-table.smart-table-theme((
+    header-bg:        #1a1a2e,
+    header-color:     #ffffff,
+    row-hover-bg:     #f0f4ff,
+    search-bg:        #ececec,
+    filter-panel-radius: 16px,
+    loader-color:     #0d6efd,
+    checkbox-color:   #0d6efd,
+  ));
+}
+```
+
+#### Full Mixin Key Reference
+
+All keys accepted by `smart-table-theme()` and their default values:
+
+| Mixin Key                      | Default                          | CSS Variable Emitted                      |
+| ------------------------------ | -------------------------------- | ----------------------------------------- |
+| `font-family`                  | `('Roboto', sans-serif)`         | `--st-font-family`                        |
+| `font-size`                    | `14px`                           | `--st-font-size`                          |
+| `text-color`                   | `#333333`                        | `--st-text-color`                         |
+| `border-radius`                | `8px`                            | `--st-border-radius`                      |
+| `box-shadow`                   | `0 2px 8px rgba(0,0,0,0.08)`     | `--st-box-shadow`                         |
+| `table-bg`                     | `#ffffff`                        | `--st-table-bg`                           |
+| `table-padding`                | `1rem`                           | `--st-table-padding`                      |
+| `cell-padding`                 | `1rem`                           | `--st-cell-padding`                       |
+| `table-border`                 | `1px solid #e0e0e0`              | `--st-table-border`                       |
+| `row-border`                   | `1px solid #f0f0f0`              | `--st-row-border`                         |
+| `row-bg`                       | `#ffffff`                        | `--st-row-bg`                             |
+| `row-hover-bg`                 | `#f9f9f9`                        | `--st-row-hover-bg`                       |
+| `row-selected-bg`              | `#f3e5f5`                        | `--st-row-selected-bg`                    |
+| `header-bg`                    | `#f5f5f5`                        | `--st-header-bg`                          |
+| `header-color`                 | `#333333`                        | `--st-header-color`                       |
+| `header-font-weight`           | `500`                            | `--st-header-weight`                      |
+| `header-font-size`             | `14px`                           | `--st-header-size`                        |
+| `header-transform`             | `none`                           | `--st-header-transform`                   |
+| `toolbar-bg`                   | `#ffffff`                        | `--st-toolbar-bg`                         |
+| `toolbar-padding`              | `1.2rem 0rem`                    | `--st-toolbar-padding`                    |
+| `toolbar-border-bottom`        | `1px solid rgba(0,0,0,0.08)`     | `--st-toolbar-border-bottom`              |
+| `toolbar-gap`                  | `1rem`                           | `--st-toolbar-gap`                        |
+| `search-bg`                    | `#f5f5f5`                        | `--st-search-bg`                          |
+| `search-radius`                | `8px`                            | `--st-search-radius`                      |
+| `search-wrapper-padding`       | `0 0.875rem`                     | `--st-search-wrapper-padding`             |
+| `search-height`                | `36px`                           | `--st-search-height`                      |
+| `search-min-width`             | `200px`                          | `--st-search-min-width`                   |
+| `search-width`                 | `auto`                           | `--st-search-width`                       |
+| `search-icon-color`            | `#888`                           | `--st-search-icon-color`                  |
+| `search-placeholder-color`     | `#999`                           | `--st-search-placeholder-color`           |
+| `filter-bg`                    | `#ffffff`                        | `--st-filter-bg`                          |
+| `filter-border`                | `1px solid #e0e0e0`              | `--st-filter-border`                      |
+| `filter-radius`                | `8px`                            | `--st-filter-radius`                      |
+| `filter-height`                | `36px`                           | `--st-filter-height`                      |
+| `filter-trigger-padding`       | `0 0.75rem`                      | `--st-filter-trigger-padding`             |
+| `filter-font-size`             | `14px`                           | `--st-filter-font-size`                   |
+| `filter-color`                 | `#555`                           | `--st-filter-color`                       |
+| `filter-hover-bg`              | `#fafafa`                        | `--st-filter-hover-bg`                    |
+| `filter-hover-border-color`    | `#bbb`                           | `--st-filter-hover-border-color`          |
+| `filter-active-border-color`   | `#999`                           | `--st-filter-active-border-color`         |
+| `filter-selected-color`        | `#222`                           | `--st-filter-selected-color`              |
+| `filter-selected-border-color` | `#333`                           | `--st-filter-selected-border-color`       |
+| `filter-chevron-color`         | `#999`                           | `--st-filter-chevron-color`               |
+| `filter-panel-bg`              | `#ffffff`                        | `--st-filter-panel-bg`                    |
+| `filter-panel-border`          | `1px solid #ebebeb`              | `--st-filter-panel-border`                |
+| `filter-panel-radius`          | `12px`                           | `--st-filter-panel-radius`                |
+| `filter-panel-shadow`          | `0 8px 28px rgba(0,0,0,0.12)...` | `--st-filter-panel-shadow`                |
+| `filter-panel-min-width`       | `180px`                          | `--st-filter-panel-min-width`             |
+| `filter-panel-padding`         | `6px`                            | `--st-filter-panel-padding`               |
+| `filter-option-padding`        | `8px 12px`                       | `--st-filter-option-padding`              |
+| `filter-option-radius`         | `7px`                            | `--st-filter-option-radius`               |
+| `filter-option-hover-bg`       | `#f5f5f5`                        | `--st-filter-option-hover-bg`             |
+| `filter-option-selected-bg`    | `#f0f0f0`                        | `--st-filter-option-selected-bg`          |
+| `filter-option-selected-color` | `#111`                           | `--st-filter-option-selected-color`       |
+| `frozen-col-bg`                | `#f9f9f9`                        | `--st-frozen-col-bg`                      |
+| `actions-col-shadow`           | `-4px 0 8px rgba(0,0,0,0.06)`    | `--st-actions-col-shadow`                 |
+| `action-circle-size`           | `32px`                           | `--st-action-circle-size`                 |
+| `dropdown-min-width`           | `150px`                          | `--st-dropdown-min-width`                 |
+| `dropdown-bg`                  | `#ffffff`                        | `--st-dropdown-bg`                        |
+| `dropdown-border`              | `1px solid #e0e0e0`              | `--st-dropdown-border`                    |
+| `dropdown-radius`              | `8px`                            | `--st-dropdown-radius`                    |
+| `dropdown-shadow`              | `0 8px 24px rgba(0,0,0,0.12)`    | `--st-dropdown-shadow`                    |
+| `dropdown-padding`             | `4px`                            | `--st-dropdown-padding`                   |
+| `dropdown-item-padding`        | `8px 12px`                       | `--st-dropdown-item-padding`              |
+| `dropdown-item-radius`         | `6px`                            | `--st-dropdown-item-radius`               |
+| `dropdown-item-hover-bg`       | `#f5f5f5`                        | `--st-dropdown-item-hover-bg`             |
+| `selection-strip-bg`           | `#fafafa`                        | `--st-selection-strip-bg`                 |
+| `selection-strip-border`       | `1px solid rgba(0,0,0,0.08)`     | `--st-selection-strip-border`             |
+| `selection-strip-padding`      | `0.45rem 1rem`                   | `--st-selection-strip-padding`            |
+| `selection-count-color`        | `#444`                           | `--st-selection-count-color`              |
+| `selection-count-font-size`    | `13px`                           | `--st-selection-count-font-size`          |
+| `selection-count-font-weight`  | `500`                            | `--st-selection-count-font-weight`        |
+| `checkbox-color`               | `#e63e30`                        | `--st-checkbox-color`                     |
+| `checkbox-size`                | `16px`                           | `--st-checkbox-size`                      |
+| `badge-radius`                 | `12px`                           | `--st-badge-radius`                       |
+| `badge-padding`                | `4px 12px`                       | `--st-badge-padding`                      |
+| `badge-font-size`              | `12px`                           | `--st-badge-font-size`                    |
+| `badge-font-weight`            | `500`                            | `--st-badge-font-weight`                  |
+| `badge-success-bg`             | `#e8f5e9`                        | `--st-badge-success-bg`                   |
+| `badge-success-color`          | `#2e7d32`                        | `--st-badge-success-color`                |
+| `badge-warning-bg`             | `#fff3e0`                        | `--st-badge-warning-bg`                   |
+| `badge-warning-color`          | `#ef6c00`                        | `--st-badge-warning-color`                |
+| `badge-danger-bg`              | `#ffebee`                        | `--st-badge-danger-bg`                    |
+| `badge-danger-color`           | `#c62828`                        | `--st-badge-danger-color`                 |
+| `badge-info-bg`                | `#e3f2fd`                        | `--st-badge-info-bg`                      |
+| `badge-info-color`             | `#1565c0`                        | `--st-badge-info-color`                   |
+| `badge-neutral-bg`             | `#f5f5f5`                        | `--st-badge-neutral-bg`                   |
+| `badge-neutral-color`          | `#616161`                        | `--st-badge-neutral-color`                |
+| `scrollbar-width`              | `8px`                            | `--st-scrollbar-width`                    |
+| `scrollbar-height`             | `8px`                            | `--st-scrollbar-height`                   |
+| `scrollbar-track-bg`           | `#f1f1f1`                        | `--st-scrollbar-track-bg`                 |
+| `scrollbar-track-radius`       | `4px`                            | `--st-scrollbar-track-radius`             |
+| `scrollbar-thumb-bg`           | `#c1c1c1`                        | `--st-scrollbar-thumb-bg`                 |
+| `scrollbar-thumb-radius`       | `4px`                            | `--st-scrollbar-thumb-radius`             |
+| `scrollbar-thumb-hover-bg`     | `#a8a8a8`                        | `--st-scrollbar-thumb-hover-bg`           |
+| `sticky-shadow`                | `2px 0 5px -2px rgba(0,0,0,0.1)`| `--st-sticky-shadow`                      |
+| `sticky-border-right`          | `1px solid rgba(0,0,0,0.05)`     | `--st-sticky-border-right`                |
+| `loader-color`                 | `#6200EE`                        | `--st-loader-color`                       |
+| `spinner-border-color`         | `rgba(0,0,0,0.1)`                | `--st-spinner-border-color`               |
+| `no-data-color`                | `#888888`                        | `--st-no-data-color`                      |
+| `sort-icon-size`               | `0.8em`                          | `--st-sort-icon-size`                     |
+## Inline Row Editing & Addition
+
+The `SmartTableComponent` supports **inline row editing** and **inline row creation**. This allows developers to let users edit cells or add new items directly inside the table row interface rather than using full-page forms or modals. 
+
+This feature is completely opt-in and backward-compatible.
+
+### 1. Column Configuration (`TableColumn`)
+
+To make a column editable, configure the following properties in its `TableColumn` definition:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `editable` | `boolean` | Determines if the column input is enabled or disabled when the row enters edit mode. |
+| `dataType` | `'text' \| 'number' \| 'date' \| 'email' \| 'select'` | The input type to render when the row is in edit mode. Note: `'date'` renders Angular Material's `mat-datepicker`. |
+| `options` | `TableOption[]` | Options array used if `dataType` is `'select'`. |
+| `subFields` | `TableColumnSubField[]` | Configures multiple stacked inputs inside a single cell (e.g. combined Phone & Email in a `CONTACT` column). |
+| `editConfig` | `{ disabled?: boolean; defaultValue?: any }` | Configures default patched values and disable states for inputs in editing rows. |
+
+#### `TableColumnSubField` Schema
+```typescript
+export interface TableColumnSubField {
+    key: string;
+    label?: string;
+    dataType: 'text' | 'number' | 'email' | 'select' | 'date';
+    placeholder?: string;
+    editable?: boolean;
+    options?: TableOption[];
+    editConfig?: {
+        disabled?: boolean;
+        defaultValue?: any;
+    };
+}
+```
+
+### 2. Table Configurations (`TableConfig`)
+
+We can configure inline edit row styling using the optional `editingRowClass` property:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `editingRowClass` | `string` | An optional CSS class name to apply to rows currently being edited or added. |
+
+### 3. Row Actions & Top Bar Actions
+
+To trigger row addition or editing, use the following action types:
+
+*   **`add-row`** (typically in `topBarButtons`): Prepends a new blank row with `id` / `rowIdField` set to `0` and populates any `defaultValue` rules.
+*   **`edit-row`** (typically in `actions`): Caches the row's values and switches it to editing state.
+
+When a row enters edit mode, the component automatically displays **Cancel** and **Save** (or **Add Student** for new rows) buttons instead of the standard dropdown kebab menu.
+
+### 4. Integration Modes
+
+#### A. Internal API Mode (Self-Managed)
+If your table is configured with an `apiUrl`, saving operations are handled automatically:
+*   **Adding a Row**: Submits a `POST` request to `config.apiUrl` with the row values.
+*   **Editing a Row**: Submits a `PUT` request (or configured `apiMethod`) to `config.apiUrl/:id`.
+*   **Cancel**: Discards the new row or restores the original values from local cache.
+*   The component automatically cleans helper properties (`isEditing`, `isNew`, `selected`) before submitting payloads.
+
+#### B. External Data Mode (Parent-Managed)
+If you supply data via `[tableData]`, listen to the `(rowSave)` emitter in the parent template.
+
+##### HTML Template
+```html
+<lib-smart-table
+  [config]="tableConfig"
+  [tableData]="studentsList"
+  [totalItemsCount]="totalStudents"
+  (rowSave)="onSaveStudent($event)">
+</lib-smart-table>
+```
+
+##### TypeScript Controller
+```typescript
+import { TableRowSaveEvent } from 'commons-shared-web-ui';
+
+onSaveStudent(event: TableRowSaveEvent): void {
+  const { row, isNew } = event;
+  
+  if (isNew) {
+    this.apiService.create(row).subscribe(() => this.reloadList());
+  } else {
+    this.apiService.update(row.id, row).subscribe(() => this.reloadList());
+  }
+}
+```
+
+### 5. CSS Theming Variables
+
+The inline inputs and selectors are themed via CSS custom variables. You can override these variables globally in `global.scss` or inside `@mixin smart-table-theme`:
+
+```scss
+:root {
+  /* Mirror variable overrides */
+  --st-cell-input-border: 1px solid #dee2e6;
+  --st-cell-input-focus-outline-color: #c21e25;
+  --st-cell-input-bg: #fcfcfc;
+  --st-cell-select-bg: #fcfcfc;
+}
+```
+
+### 6. Date Field Handling (`mat-datepicker`)
+
+When a column or subfield has `dataType` configured as `'date'`:
+*   **Component Rendering**: Instead of a native HTML input, the table renders an input with Angular Material's `mat-datepicker` along with a calendar toggle icon.
+*   **User Interaction**: Users can select a date using the calendar picker popup or enter/edit it manually.
+*   **Automatic Date Conversions**:
+    *   **On Edit Mode**: When a row transitions to edit mode, the component parses the date value (ISO string or timestamp) to a native JavaScript `Date` object to bind it correctly to the datepicker.
+    *   **On Save Mode**: When saving/submitting, the component automatically converts the native `Date` object back to an ISO 8601 string (`.toISOString()`) to keep backend communication clean and standard.
+
+---
+
+## Utility Functions
+
+### `appendBaseUrlRecursively`
+
+The `appendBaseUrlRecursively(obj: any, baseURL: string)` utility function allows you to recursively append a base URL to any `apiUrl` property found within a configuration object (or any object). This is particularly useful when you have a complex `TableConfig` (with nested actions, filters, pagination counts, etc.) and you want to define relative API paths in your config, but prepend a common environment base URL before passing the configuration to the Smart Table.
+
+#### Usage Example
+
+```typescript
+import { TableConfig, appendBaseUrlRecursively } from "commons-shared-web-ui";
+
+export class MyComponent {
+  tableConfig: TableConfig = {
+    apiUrl: "/users", // Relative path
+    columns: [
+      { key: "id", label: "ID", type: "number", sortable: true },
+      { key: "name", label: "Name", type: "text", sortable: true },
+    ],
+    filters: [
+      {
+        key: "status",
+        label: "Status",
+        type: "select",
+        apiUrl: "/ref-data/status" // Relative path
+      }
+    ],
+    actions: [
+      {
+        label: "Delete",
+        type: "api",
+        apiUrl: "/users/:id", // Relative path
+        apiMethod: "DELETE"
+      }
+    ]
+  };
+
+  constructor() {
+    const environmentBaseUrl = "https://api.example.com";
+
+    // This will recursively update all `apiUrl` properties in the config
+    // - config.apiUrl becomes "https://api.example.com/users"
+    // - config.filters[0].apiUrl becomes "https://api.example.com/ref-data/status"
+    // - config.actions[0].apiUrl becomes "https://api.example.com/users/:id"
+    appendBaseUrlRecursively(this.tableConfig, environmentBaseUrl);
+  }
+}
+```
+
+## Authentication & Interceptors
+
+The `SmartTableComponent` makes HTTP requests using Angular's `HttpClient`. It does **not** provide its own `HttpClient` instance. Instead, it relies on the `HttpClient` provided by the consuming application (e.g., your Shell or Remote MFE).
+
+This means that any interceptors configured in your application's root module (using `provideHttpClient(withInterceptors([...]))` or `HTTP_INTERCEPTORS`) will **automatically** intercept and handle requests made by the table.
+
+To add authentication tokens:
+1.  Ensure your Shell/Host app provides `HttpClient` with your auth interceptor.
+2.  Ensure `@angular/common/http` is shared as a singleton in your Module Federation config (`federation.config.js`).
+
+The table will then automatically use your authenticated `HttpClient`.
+
+### Example Interceptor Setup (in App Module)
+
+```typescript
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideHttpClient(
+      withInterceptors([authInterceptor])
+    )
+  ]
+});
+````
+
+### Manual Token Configuration
+
+If you need to bypass default interceptors or provide a specific token for the table's API calls, you can pass a `token` and optionally a `tokenHeader` in the `TableConfig`.
+
+```typescript
+tableConfig: TableConfig = {
+  apiUrl: "...",
+  // Pass the FULL token string including prefix (e.g. Bearer)
+  token: "Bearer eyJhbGc...",
+  // Optional: Custom header key (defaults to 'Authorization' if omitted)
+  tokenHeader: "X-Custom-Auth",
+  // ...
+};
+```
+
+This token will be added to the request headers exactly as provided. If `tokenHeader` is not specified, it defaults to `Authorization`.