nuxeo-development-framework 5.3.3 → 5.3.4

package/src/docs/ndf-table.doc.md

@@ -0,0 +1,1433 @@
+---
+ModifiedDate: 2025-05-07 10:53
+CreatedDate: 2025-05-06 11:27
+---
+
+# `NdfTableConfig` 
+Configuration type for the NDF Table component. Extends `TablePaginationOptions` and provides additional properties  for customizing table behavior, appearance, and data handling.
+
+```ts
+type NdfTableConfig = TablePaginationOptions & {  
+  isDataProvided?: boolean;  
+  options?: NdfTableOptions;  
+  scrollbarH?: boolean;  
+  columnMode?: 'flex' | 'fixed' | 'force';  
+  pageProvider: string;  
+  fields: Record<string, string>;  
+  customUrl?: { url: string; method: 'POST' | 'GET'; payload?: Record<string, any>; predicateKey?: string };  
+  quickFilters?: string;  
+  columns: TableColumnConfig[];  
+  columnsWithDynamicVisibiltiy?: string[];  
+  columnsWithDynamicDisplay?: string[];  
+  filtersWithDynamicDisplay?: string[];  
+  responsiveColumns?: TableColumnConfig[];  
+  fullWidth?: string;  
+  prefix?: string;  
+  sortingBy?: TableSortOptions;  
+  defaultSort?: TableDefaultSortModel;  
+  headers?: Record<string, any>;  
+  queryParam?: Record<string, any>;  
+  tableActions?: TableColumnAction[];  
+  highlightSelectedCard?: boolean;  
+  tabs?: TableTab[];  
+  sortingArray?: TableSortingArray[];  
+  skipAggregation?: 'never' | 'onPageChange';  
+  range?: any;  
+  isSearchPage?: any;  
+  multiSelectRows?: boolean;  
+  customFirstRow?: boolean;  
+  showActionsAsMenu?: boolean;  
+  filterParams?: Record<string, any>;  
+  format?: string;  
+  pageSizes?: { label: string; size: number }[];  
+};
+```
+
+---
+
+# Table options : `NdfTableOptions` Interface
+
+The `NdfTableOptions` interface is used to configure table components in the application. Below is a detailed description of its properties along with JSON examples for all possible values.
+
+```ts
+  export type NdfTableOptions = {
+	filters: FiltersConfig;
+	search?: GlobalSearchConfig;
+	sortList?: TranslateKey[];
+	tableMode?: TableModeConfig;
+	export?: TableExportConfig;
+	columns?: {
+		toggle?: boolean;
+		sortable?: TableSortConfig;
+	};
+	
+};
+```
+
+---
+
+## 1 - `search` (optional)
+- **Type**: `GlobalSearchConfig`  
+- **Purpose**: Configures a global search input with behavior, UI labels, filtering logic, and optional contextual dialogs.
+---
+### Type Definition: `GlobalSearchConfig`
+
+
+```ts
+export type GlobalSearchConfig = {
+  fieldKey: string;
+  label?: string;
+  placeholder?: string;
+  operator?: ComparisonOperator; // see COMPARISON_OPERATOR
+  searchMode: 'realTime' | 'triggered';
+  debounceTime?: number;
+  searchButtonLabel?: string;
+  suffix?: {
+    dialog?: HtmlDialogConfig;
+  };
+};
+```
+
+### Property Descriptions
+
+| Property            | Type                          | Required | Description                                                                                                                                                                     |
+|---------------------|-------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `fieldKey`          | `string`                      | ✅        | The target field to apply the search against.                                                                                                                                   |
+| `label`             | `string`                      | ❌        | Display label for the search input (e.g., above or beside it).                                                                                                                  |
+| `placeholder`       | `string`                      | ❌        | Text displayed inside the input field as a prompt.                                                                                                                              |
+| `operator`          | `ComparisonOperator`          | ❌        | Logic for comparison. Supported values include: `=`, `!=`, `<`, `>`, `<=`, `>=`, `IN`, `NOT IN`, `BETWEEN`, `LIKE`, `ILIKE`, `NOT LIKE`, `NOT ILIKE`, `STARTSWITH`, `FULLTEXT`  |
+| `searchMode`        | `'realTime'` \| `'triggered'` | ✅        | Controls how and when the search is executed: • `realTime`: Fires on user input with optional debounce. • `triggered`: Fires only on explicit user action (e.g., button click). |
+| `debounceTime`      | `number`                      | ❌        | Delay in milliseconds for real-time searches. Only applicable when `searchMode` is `'realTime'`.                                                                                |
+| `searchButtonLabel` | `string`                      | ❌        | Custom text for the search button (used in `'triggered'` mode).                                                                                                                 |
+| `suffix.dialog`     | `HtmlDialogConfig`            | ❌        | Adds a supplementary dialog for user guidance or advanced options.                                                                                                              |
+
+---
+###### HtmlDialogConfig
+
+```ts
+type HtmlDialogConfig = {
+  content: string[];
+  title?: string;
+  options?: Partial<MatDialogConfig>;
+};
+
+```
+
+**Property Descriptions**
+
+| Property  | Type                       | Required | Description                                                             |
+|-----------|----------------------------|----------|-------------------------------------------------------------------------|
+| `title`   | `string`                   | ❌        | Dialog title shown at the top of the popup.                             |
+| `content` | `string[]`                 | ✅        | List of ##translate keys## or raw content to display inside the dialog. |
+| `options` | `Partial<MatDialogConfig>` | ❌        | Optional Angular Material dialog configuration overrides.               |
+
+### Examples
+ 
+
+```yaml
+// Real-Time Search with Help Dialog
+// any text between ##..## will be translated
+{
+  "fieldKey": "ecm:fulltext",
+  "label": "Search Name",
+  "placeholder": "Enter a name...",
+  "operator": "ILIKE",
+  "searchMode": "realTime",
+  "debounceTime": 300,
+  "suffix": {
+    "dialog": {
+      "title": "INFO.dialogTitle",
+      "content": [
+	      "not translated text",
+        "##INFO.query_sequence##", 
+        "##INFO.query_and##",
+        "##INFO.query_negation##",
+        "##INFO.query_prefix##",
+        "##INFO.query_historical##",
+        "##INFO.query_or##",
+      ]
+    }
+  }
+}
+
+//Triggered Search with Button
+  {
+      "fieldKey": "ecm:fulltext",
+      "label": "Search",
+      "placeholder": "search ...",
+      "operator": "=",
+      "searchMode": "triggered",
+      "searchButtonLabel": "Find"
+  }
+
+```
+
+ 
+ 
+---
+---
+## 2 -`sortList` (optional)
+
+- **Type**: `TranslateKey[]`
+- **Description**: List of sorting configurations for the table.
+---
+### Type Definition: `TranslateKey`
+
+```ts
+export type TranslateKey = {
+	key: TranslatedKey;
+	value: string;
+	direction: 'asc' | 'desc';
+	selected?: boolean;
+};
+```
+### Property Descriptions
+
+| Property    | Type                | Required | Description                                           |
+|-------------|---------------------|----------|-------------------------------------------------------|
+| `key`       | `TranslatedKey`     | ✅        | The display label key for internationalization.       |
+| `value`     | `string`            | ✅        | The field in the dataset to apply the sorting on.     |
+| `direction` | `'asc'` \| `'desc'` | ✅        | Sort direction: ascending or descending.              |
+| `selected`  | `boolean`           | ❌        | Indicates if this sort option is selected by default. |
+### Example
+
+```json
+[
+  {
+    "key": "SORT.name",
+    "value": "name",
+    "direction": "asc",
+    "selected": true
+  },
+  {
+    "key": "SORT.date",
+    "value": "createdAt",
+    "direction": "desc"
+  }
+]
+```
+
+
+
+---
+---
+
+## 3- `tableMode` (optional)
+
+- **Type**: `TableModeConfig`
+- **Description**: Configuration for handling different `CTS table` display modes. Supports toggling between multiple predefined views such as list, card, dynamicCard, or a custom component view.
+### Type Definition: `TableModeConfig
+`
+```ts
+type TableViewMode = 'dynamicCard' | 'list' | 'card' | 'custom';
+
+type TableToggleItem = {
+  key?: TranslatedKey;
+  value: TableViewMode;
+  icon: string;
+};
+
+type TableModeList = TableToggleItem[];
+
+type BaseTableModel = {
+  toggleMode?: boolean;
+  availableMode?: TableModeList;
+};
+
+type StandardTableMode = BaseTableModel & {
+  mode?: Exclude<TableViewMode, 'custom'>;
+};
+
+type CustomTableMode = BaseTableModel & {
+  mode: 'custom';
+  componentName: string;
+};
+
+type TableModeConfig = StandardTableMode | CustomTableMode;
+
+```
+
+### Property Descriptions
+
+| Property        | Type                                                  | Required                  | Default | Description                                                                                       |
+|-----------------|-------------------------------------------------------|---------------------------|---------|---------------------------------------------------------------------------------------------------|
+| `mode`          | `'list'` \| `'card'` \| `'dynamicCard'` \| `'custom'` | ❌                         |         | Defines the current table view mode. If `mode` is `'custom'`, a `componentName` must be provided. |
+| `toggleMode`    | `boolean`                                             | ❌                         | `false` | Enables or disables toggling between multiple view modes.                                         |
+| `availableMode` | `TableModeList`                                       | ❌                         |         | List of available view modes and their icons for use in toggle controls.                          |
+| `componentName` | `string`                                              | ✅ (if mode is `'custom'`) |         | Name of the custom Angular component to render in custom mode.                                    |
+> [!note] NOTE
+When using `mode: 'custom'`, the specified component in `componentName` **must extend `BaseCustomComponent`** to ensure compatibility with the dynamic rendering system.
+
+
+### Example Toggle Between List and Custom View
+
+```yaml
+{
+  "mode": "list",
+  "componentName": "rms.components.advancedSearchCard", //Required for the custom mode inside availableMode list
+  "toggleMode": true,
+  "availableMode": [
+   {    "key" : "GOLBAL.list",
+	    "value": "list",
+	    "icon": "table_rows"
+   },
+   {    "value": "custom",
+	    "icon": "rectangle"
+   }
+  ]}
+```
+
+*Example* Custom Component Mode
+```json
+{
+  "mode": "custom",
+  "componentName": "rms.components.requestCard"
+}
+```
+
+
+
+## 4- `export` (optional)
+
+- **Type**: `TableExportConfig`
+- **Description**: Configures the functionality for exporting table data. This includes settings for enabling or disabling the export feature, specifying the export formats, defining the fields to be exported, and customizing the request parameters for fetching the data.
+### Type Definition: `TableExportConfig`
+
+```ts
+export type TableExportConfig = {
+	enabled: boolean;
+	request: NdfRequestConfig; //common type
+	docTypeName: 'task' | 'request' | 'record';
+	defaultType: 'excel' | 'docx' | 'pdf';
+	allowedTypes?: LabelValue<string, 'excel' | 'docx' | 'pdf'>[]; //common type
+	fields?: string[];
+	locale?: string;
+};
+```
+
+### Property Descriptions
+
+| Property       | Type                                               | Required | Description                                                                                                                                                    |
+|----------------|----------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`      | `boolean`                                          | ✅        | Enables or disables the export feature.                                                                                                                        |
+| `request`      | `NdfRequestConfig`                                 | ✅        | Configuration for making the export HTTP request.                                                                                                              |
+| `docTypeName`  | `'task'` \| `'request'` \| `'record'`              | ✅        | Specifies the type of document being exported.                                                                                                                 |
+| `defaultType`  | `'excel'` \| `'docx'` \| `'pdf'`                   | ✅        | Sets the default export format.                                                                                                                                |
+| `allowedTypes` | `LabelValue<string, 'excel' \| 'docx' \| 'pdf'>[]` | ❌        | List of allowed export types with labels for UI.                                                                                                               |
+| `fields`       | `string[]`                                         | ❌        | List of fields or columns to include in the export. If not provided, it will be derived from the `headerClass` property of the columns.(e.g., `["dc:title"]` ) |
+| `locale`       | `string`                                           | ❌        | Locale code for language-specific formatting (e.g., `'en'`, `'ar'`).                                                                                           |
+### Example
+
+```yaml
+{
+  "enabled": true,
+  "request": {
+    "method": "post",
+    url: '/custom-search/pp/PP_RPT_Expected_TransferArchive_Records/report',
+  },
+  "docTypeName": "record",
+  "defaultType": "excel",
+  "allowedTypes": [
+   [
+	  {
+	    "value": "pdf",
+	    "label": "TABLE.EXPORT.PDF"
+	  },
+	  {
+	    "value": "excel",
+	    "label": "TABLE.EXPORT.EXCEL"
+	  },
+	  {
+	    "value": "docx",
+	    "label": "TABLE.EXPORT.WORD"
+	  }
+	]
+  ],
+  "locale": "en",
+}
+
+```
+
+
+
+
+
+---
+---
+
+## 5- `columns` (optional)
+
+- **Type**: `{ toggle?: boolean; sortable?: TableSortConfig; }`
+- **Description**: Configuration for controlling the visibility and ordering of table columns. This includes enabling column visibility toggles and defining the column order based on sorting preferences
+
+### Type Definition
+
+```ts
+  type  columns = {
+    toggle?: boolean;
+    sortable?: TableSortConfig; //common type for column ordering configuration
+  };
+```
+
+### Property Descriptions
+
+| Property   | Type              | Required | Description                                                                                          |
+|------------|-------------------|----------|------------------------------------------------------------------------------------------------------|
+| `toggle`   | `boolean`         | ❌        | Enables or disables the toggle visibility functionality for columns.                                 |
+| `sortable` | `TableSortConfig` | ❌        | Configuration for specifying the column order (sorting) and options to control the order of columns. |
+### Example
+
+```yaml
+{
+  "toggle": true,
+  "sortable": {
+   "enabled": true,
+   "frozenColumns": [
+    "OPTIONS"
+   ]
+  }}
+```
+
+
+
+
+---
+---
+
+## 6- `Filters`
+
+- **Type**: `FiltersConfig`
+- **Description**: Configuration for table filters.
+
+### Type Definition: `FiltersConfig`
+
+```ts
+export type FilterMode =
+  | { mode: 'payload' }
+  | {
+    mode: 'params';
+    stringifyParams: boolean;
+    };
+
+export type FilterReloadConfig =
+  | { strategy: 'always' }
+  | { strategy: 'never' }
+  | { strategy: 'onChange'; triggerFields: string[] };
+
+type FiltersConfig = FilterMode & {
+  reload?: FilterReloadConfig;
+  fields: FieldConfigModel[];
+  panel?: {
+   visible?: boolean;
+   toggleButton?: boolean;
+  };
+  };
+```
+
+### Property Descriptions
+
+| Property             | Type                      | Required                  | Default  | Description                                                                                                             |
+|----------------------|---------------------------|---------------------------|----------|-------------------------------------------------------------------------------------------------------------------------|
+| `mode`               | `'payload'` \| `'params'` | ✅                         | `params` | Defines how filter data is sent. `payload` sends data in the request body. `params` sends data as URL query parameters. |
+| `stringifyParams`    | `boolean`                 | ✅ (if mode is `'params'`) | `false`  | If `true`, parameters will be stringified when sent as query parameters. Only used when `mode` is `'params'`.           |
+| `reload`             | `FilterReloadConfig`      | ❌                         |          | Determines when the filters should trigger a fields reload.                                                             |
+| `fields`             | `FieldConfigModel[]`      | ✅                         |          | List of filter fields to render in the filter UI.                                                                       |
+| `panel.visible`      | `boolean`                 | ❌                         | `true`   | Controls whether the filter panel is visible by default.                                                                |
+| `panel.toggleButton` | `boolean`                 | ❌                         | `true`   | If `true`, shows a toggle button to show/hide the filter panel.                                                         |
+|                      |                           |                           |          |                                                                                                                         |
+#### Reload Strategies
+
+| Strategy   | Description                                                                                                                                    |
+|------------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `always`   | The Filters Panel reloads Fields (e.g., aggregations)  **every time** filters are applied or changed, regardless of what fields were modified. |
+| `never`    | Disables automatic reloads filters after initialized. **Reload only if the config is changed**                                                 |
+| `onChange` | Reloads filters **only if specific filter fields** (defined in `triggerFields`) have changed between the previous and current filter states.   |
+
+**Examples**
+
+```json
+{
+  "mode": "params",
+  "stringifyParams": true,
+  "reload": {
+    "strategy": "always"
+  },
+  "panel": {
+    "visible": true,
+    "toggleButton": true
+  }
+}
+```
+
+Example :`onChange` Strategy
+
+ ```yaml
+{
+  "mode": "params",
+  "stringifyParams": true,
+  "reload": {
+    "strategy": "onChange",
+    "triggerFields" : [""]
+  },
+  "panel": {
+    "visible": true,
+    "toggleButton": true
+  }
+}
+
+```
+
+
+ 
+---
+---
+
+## FILTER FIELDS
+- **Type**: `FieldConfigModel`
+- **Description**: Defines the structure and behavior of individual fields used in the table filters. Each field can be one of the following types: `aggregation`, `predicate`, or `custom`.
+### Type Definition: `FieldConfigModel`
+
+```ts
+type FieldConfigModel =
+  | { type: 'aggregation'; config: AggregationFieldConfig; }
+  | { type: 'predicate'; config: PredicateFieldConfig; }
+  | { type: 'custom'; config: CustomFieldConfig; };
+
+```
+
+### Property Descriptions
+
+| Property | Type                                                                      | Required | Applies To | Description                                      |
+|----------|---------------------------------------------------------------------------|----------|------------|--------------------------------------------------|
+| `type`   | `'aggregation'` \| `'predicate'` \| `'custom'`                            | ✅        | All        | Specifies the type of filter field.              |
+| `config` | `AggregationFieldConfig` \| `PredicateFieldConfig` \| `CustomFieldConfig` | ✅        | All        | Configuration object specific to the field type. |
+#### `BaseFieldConfig` *(shared across all configs)*
+
+| Property     | Type                            | Required | Default       | Description                                                           |
+|--------------|---------------------------------|----------|---------------|-----------------------------------------------------------------------|
+| `label`      | `TranslateKey`                  | ✅        |               | Field label used for internationalization.                            |
+| `fieldKey`   | `string`                        | ✅        |               | Unique identifier for the field; used for data binding and filtering. |
+| `values`     | `unknown`                       | ❌        |               | Static values or data set used for the filter, if applicable.         |
+| `prefix`     | `string`                        | ❌        |               | Optional prefix used for values translations                          |
+| `order`      | `number`                        | ❌        | 0             | Determines the field's display order in the filter UI.                |
+| `operator`   | `ComparisonOperator`            | ❌        |               | Operator used for filtering (e.g., `EQ`, `IN`).                       |
+| `valueType`  | `'valueObject'` \| `'property'` | ✅        | `valueObject` | Defines how values are interpreted in the filter context.             |
+| `visible`    | `boolean`                       | ❌        |               | Controls whether the field is visible in the UI.                      |
+| `roles`      | `string[]`                      | ❌        |               | List of roles required to view/use the field.                         |
+| `permission` | `string`                        | ❌        |               | Specific permission required to access the field.                     |
+
+### Predicate Field Config
+
+  ```ts
+type PredicateFieldConfig =
+  BaseFieldConfig & {
+   sendMode: Exclude<FieldSendModeType, 'custom'>;
+   render: InputOptions | DateInputOptions;
+  }
+```
+
+#### Property Descriptions
+
+| Property   | Type                                   | Required | Description                                                                                         |
+|------------|----------------------------------------|----------|-----------------------------------------------------------------------------------------------------|
+| `sendMode` | `Exclude<FieldSendModeType, 'custom'>` | ✅        | Specifies how the field value should be sent (e.g., `payload`, `queryParam`), excluding `'custom'`. |
+| `render`   | `InputOptions` \| `DateInputOptions`   | ✅        | Defines how the input should be displayed and interacted with in the UI.                            |
+#### Example
+
+```yaml
+[
+{
+  "type": "predicate",
+  "config": {
+   "label": "FILTERS.tags",
+   "fieldKey": "ecm:tag",
+   "sendMode": "payload",
+   "valueType": "valueObject",
+   "permission": "hasRoleOnArchiveOrLoan",
+   "render": { 
+   // render config here
+   }
+   }
+},
+{
+  "type": "predicate",
+  "config": {
+   "label": "FILTERS.tags",
+   "fieldKey": "ecm:tag",
+   "order": 0,
+   "sendMode": "queryParam",
+   "valueType": "property",
+   "prefix": "search.buckets.",
+   "render": {
+   // render config here
+   }
+   }
+ }
+]
+
+```
+
+
+---
+---
+
+### Aggregation Field Config
+
+```ts
+type AggregationFieldConfig = BaseFieldConfig & {
+  aggregation: string;
+  propertyPath?: string;
+  bindLabel?: { ar: string; en: string };
+  bindValue?: string;
+  dataTransformer?:  string;
+  sendMode: FieldSendModeType;
+  tooltip?: AggregationTooltipType;
+  render:
+   | CheckboxOptions
+   | SwitchOptions
+   | RadioOptions
+   | DropdownOptions
+   | AutocompleteOptions
+   | CustomOptions
+   | DateListOptions;
+}
+```
+
+#### Property Descriptions
+
+| Property          | Type                                                                                                                             | Required | Description                                                                                              |
+|-------------------|----------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------------|
+| `aggregation`     | `string`                                                                                                                         | ✅        | The name of the aggregation                                                                              |
+| `propertyPath`    | `string`                                                                                                                         | ❌        | Path to the property used in aggregation (if different from `fieldKey`).                                 |
+| `bindLabel`       | `{ ar: string; en: string }`                                                                                                     | ❌        | Property name to use as Label                                                                            |
+| `bindValue`       | `string`                                                                                                                         | ❌        | Property name to use as the value                                                                        |
+| `dataTransformer` | `string`                                                                                                                         | ❌        | Optional name of a transformer function to apply on the aggregation data.                                |
+| `sendMode`        | `FieldSendModeType`                                                                                                              | ✅        | Defines how the selected value should be sent in the request (e.g., `payload`, `queryParam` , `custom`). |
+| `tooltip`         | `AggregationTooltipType`                                                                                                         | ❌        | Tooltip text or configuration to display additional info for the field.                                  |
+| `render`          | `CheckboxOptions \| SwitchOptions \| RadioOptions \| DropdownOptions \| AutocompleteOptions \| CustomOptions \| DateListOptions` | ✅        | Specifies how the field will be rendered in the UI.                                                      |
+|                   |                                                                                                                                  |          |                                                                                                          |
+#### Example
+
+```ts
+[
+{
+  "type": "aggregation",
+  "config": {
+   "label": "FILTERS.priority",
+   "aggregation": "generaldocument_importance_agg",
+   "fieldKey": "gdoc:importance",
+   "prefix": "search.buckets.",
+   "sendMode": "queryParam",
+   "valueType": "property",
+   "render": {
+   // render config here
+   }
+   }
+ },
+]
+
+```
+
+
+#### Aggregation Tooltip  
+**Type**: `AggregationTooltipType`
+
+```ts
+export type AggregationTooltipType = {  
+  properties: Record<string, any>;  
+} & (TooltipPlainText | TooltipLocalizedText | TooltipFormattedDate | TooltipTranslationKey | TooltipTranslatedDate);
+
+```
+
+| Property     | Type                  | Required | Description                                                           |
+|--------------|-----------------------|----------|-----------------------------------------------------------------------|
+| `properties` | `Record<string, any>` | ✅        | Dynamic object used to resolve tooltip content, such as field values. |
+
+1. Variant: `TooltipPlainText`
+```ts
+type TooltipPlainText = {  
+  type: 'text';  
+  separator?: string;  
+};
+```
+
+| Property    | Type     | Required | Description                                      |
+|-------------|----------|----------|--------------------------------------------------|
+| `type`      | `'text'` | ✅        | Defines this variant as plain text.              |
+| `separator` | `string` | ❌        | Optional separator used between multiple values. |
+
+2. Variant: `TooltipLocalizedText`
+```ts
+type TooltipLocalizedText = {  
+  type: 'localizeValue';  
+  translateKey: string;  
+};
+```
+
+| Property       | Type              | Required | Description                                |
+|----------------|-------------------|----------|--------------------------------------------|
+| `type`         | `'localizeValue'` | ✅        | Defines this variant as a localized value. |
+| `translateKey` | `string`          | ✅        | Key used for localization.                 |
+
+3. Variant: `TooltipFormattedDate`
+```ts
+ type TooltipFormattedDate = {  
+  type: 'date';  
+  format: string;  
+  separator?: string;  
+};
+```
+
+| Property    | Type     | Required | Description                                 |
+|-------------|----------|----------|---------------------------------------------|
+| `type`      | `'date'` | ✅        | Defines this variant as a formatted date.   |
+| `format`    | `string` | ✅        | Date format string (e.g., `YYYY-MM-DD`).    |
+| `separator` | `string` | ❌        | Optional separator for multiple date values |
+
+4. Variant: `TooltipTranslationKey`
+```ts
+type TooltipTranslationKey = {  
+  type: 'translate';  
+  prefix: string;  
+  separator?: string;  
+};
+```
+
+| Property    | Type          | Required | Description                                     |
+|-------------|---------------|----------|-------------------------------------------------|
+| `type`      | `'translate'` | ✅        | Indicates translation via a key with prefix.    |
+| `prefix`    | `string`      | ✅        | Prefix to be appended to the value as a key.    |
+| `separator` | `string`      | ❌        | Optional separator used when constructing keys. |
+
+
+5. Variant: `TooltipTranslatedDate`
+```ts
+type TooltipTranslatedDate = {  
+  type: 'translatedDate';  
+  format: string;  
+  translateKey: string;  
+};
+```
+
+| Property       | Type               | Required | Description                                           |
+|----------------|--------------------|----------|-------------------------------------------------------|
+| `type`         | `'translatedDate'` | ✅        | Defines this variant as a translated, formatted date. |
+| `format`       | `string`           | ✅        | Date format string.                                   |
+| `translateKey` | `string`           | ✅        | Key used to lookup the translated string.             |
+
+#### Example `tooltip`
+
+```yaml
+[
+{
+  "type": "aggregation",
+  "config": {
+   "label": "FILTERS.priority",
+   "aggregation": "generaldocument_importance_agg",
+   "fieldKey": "gdoc:importance",
+   "prefix": "search.buckets.",
+   "sendMode": "queryParam",
+   "valueType": "property",
+   "tooltip": {  
+	  "type": "date",  
+	  "properties": {  
+	   "from": "from",  
+	   "to": "to"  
+	  }  
+	},
+   "render": {
+   // render config here
+   }
+   }
+ },
+]
+```
+
+
+---
+---
+
+
+
+
+# FIELDS
+
+## Predicate Field Render
+- **Type**: `InputOptions | DateInputOptions`
+- **Description**: Defines how a predicate filter field is rendered in the UI. The render type determines whether the input is a basic text field, a date input, or other supported formats. This controls the user interface element and its behavior for entering filter values.
+
+###  Supported Types
+####  *Input*
+
+```ts
+type InputOptions = {  
+  type: 'input';  
+  options?: {  
+	hideLabel?: boolean
+    inputType?: 'text' | 'search' | 'url';  
+    placeholder?: string;  
+    debounceTime?: number;  
+    mask?: {  
+     mask: string;  
+     shownMaskExpression?: string;  
+     dropSpecialCharacters?: boolean;  
+     showMaskTyped?: boolean;  
+     validation?: boolean;  
+     allowNegativeNumbers?: boolean;  
+     keepCharacterPositions?: boolean;  
+     leadZero?: boolean;  
+     hiddenInput?: boolean;  
+     clearIfNotMatch?: boolean;  
+     prefix?: string;  
+     suffix?: string;  
+    };    
+    suffix?: {  
+     text?: string;  
+     dropdown?: {  
+      selectedValue?: string;  
+      items: KeyValue<string, string>[];  
+     };     
+     tooltip?: string;  
+     dialog?: HtmlDialogConfig;  
+    };   
+} ;  
+};
+```
+
+| Property                       | Type                              | Description                                                            |
+|--------------------------------|-----------------------------------|------------------------------------------------------------------------|
+| `inputType`                    | `'text'` \| `'search'` \| `'url'` | Specifies the input field type. Defaults to `'text'`.                  |
+| `placeholder`                  | `string`                          | Placeholder text shown in the input field.                             |
+| `debounceTime`                 | `number`                          | Delay in milliseconds before the input is processed (for performance). |
+| `mask`                         | `object` (see below)              | Input mask settings to constrain input format.                         |
+| `suffix`                       | `object` (see below)              | Optional interactive element (text, dropdown, tooltip, or dialog).     |
+| `hideLabel` (from `HideLabel`) | `boolean`                         | Determines whether the field label is hidden.                          |
+
+##### *mask Configuration*
+
+| Property                 | Type      | Description                                                       |
+|--------------------------|-----------|-------------------------------------------------------------------|
+| `mask`                   | `string`  | Mask pattern for formatting input.                                |
+| `shownMaskExpression`    | `string`  | Custom expression to show the mask visually.                      |
+| `dropSpecialCharacters`  | `boolean` | If `true`, removes mask characters from value.                    |
+| `showMaskTyped`          | `boolean` | Shows masked characters while typing.                             |
+| `validation`             | `boolean` | Enables input validation based on mask.                           |
+| `allowNegativeNumbers`   | `boolean` | Allows negative numeric input.                                    |
+| `keepCharacterPositions` | `boolean` | Maintains fixed character positions when editing.                 |
+| `leadZero`               | `boolean` | Allows numbers to start with zero.                                |
+| `hiddenInput`            | `boolean` | Masks the actual input characters (e.g., password-like behavior). |
+| `clearIfNotMatch`        | `boolean` | Clears input if it doesn't match the mask.                        |
+| `prefix`                 | `string`  | Text to show before the input.                                    |
+| `suffix`                 | `string`  | Text to show after the input.                                     |
+
+*`suffix` Configuration*
+
+| Property   | Type                                                                    | Description                                                        |
+|------------|-------------------------------------------------------------------------|--------------------------------------------------------------------|
+| `text`     | `string`                                                                | ##translated## or text displayed after the input.                  |
+| `dropdown` | `{ selectedValue?: string; items: KeyValue<TranslatedKey, string>[]; }` | Dropdown menu attached to the suffix.                              |
+| `tooltip`  | `string`                                                                | Tooltip shown on hover.                                            |
+| `dialog`   | `HtmlDialogConfig`                                                      | Adds a supplementary dialog for user guidance or advanced options. |
+
+*Example* 
+
+```yaml
+[
+//*Example* : Input Field with Dropdown Suffix
+  {  
+    "type": "predicate",  
+    "config": {  
+      "render": {  
+        "type": "input",  
+        "options": {  
+          "delay": 300,  
+          "suffix": {  
+            "dropdown": {  
+              "items": [  
+                {        
+                  "key": "OPERATORS.equals",  
+                  "value": "="  
+                },  
+                {         
+                  "key": "OPERATORS.notEquals",  
+                  "value": "!="  
+                }  
+              ]  
+            }  
+          }  
+        }  
+      }  
+    }  
+  },
+
+// *Example* : Input Field with Mask
+ {  
+    "type": "predicate",  
+    "config": {   
+      "render": {  
+        "type": "input",  
+        "options": {  
+          "debounceTime": 400,  
+          "mask": {  
+            "mask": "00-00-00-00-000",  
+            "dropSpecialCharacters": false,  
+            "showMaskTyped": true  
+          }  
+        }  
+      }  
+    }  
+  }
+  ]
+
+```
+
+
+ 
+#### *Date Input*
+
+```ts
+export type DateInputOptions = {  
+  type: 'date';  
+  options?:  
+     {  
+    placeholder?: string;  
+    debounceTime?: number;  
+    isDateRange?: boolean;  
+    showActions?: boolean;  
+    autoFill?: boolean;  
+    panelClass?: string;  
+    endDatePlaceholder?: string;  
+    startDatePlaceholder?: string;  
+    startView?: 'month' | 'year' | 'multi-year';  
+    max?: Date | string | null;  
+    min?: Date | string | null;  
+    startAt?: Date | string | null;  
+    updateLocalLang?: boolean;  
+    hijriDisplayFormat?: string;  
+    displayFormat?: string;  
+    hideLabel?: boolean
+   }   
+};
+```
+
+| Property                       | Type                                    | Description                                                      |
+|--------------------------------|-----------------------------------------|------------------------------------------------------------------|
+| `placeholder`                  | `string`                                | Placeholder text for the date input.                             |
+| `debounceTime`                 | `number`                                | Delay in milliseconds before emitting value changes.             |
+| `isDateRange`                  | `boolean`                               | Enables range selection between start and end dates.             |
+| `showActions`                  | `boolean`                               | Whether to show action buttons like "Apply" or "Clear".          |
+| `autoFill`                     | `boolean`                               | Automatically fills the date if empty on blur or initialization. |
+| `panelClass`                   | `string`                                | Custom CSS class to apply to the datepicker panel.               |
+| `endDatePlaceholder`           | `string`                                | Placeholder for the end date field in range mode.                |
+| `startDatePlaceholder`         | `string`                                | Placeholder for the start date field in range mode.              |
+| `startView`                    | `'month'` \| `'year'` \| `'multi-year'` | Initial calendar view opened.                                    |
+| `max`                          | `Date` \| `string` \| `null`            | Maximum allowed date.                                            |
+| `min`                          | `Date` \| `string` \| `null`            | Minimum allowed date.                                            |
+| `startAt`                      | `Date` \| `string` \| `null`            | Initial date to open the calendar on.                            |
+| `updateLocalLang`              | `boolean`                               | Whether to automatically apply the current language settings.    |
+| `hijriDisplayFormat`           | `string`                                | Format used for Hijri calendar display.                          |
+| `displayFormat`                | `string`                                | Format used for Gregorian calendar display.                      |
+| `hideLabel` (from `HideLabel`) | `boolean`                               | Whether to hide the field's label.                               |
+*Example* :Date Field
+```json
+{  
+  "type": "predicate",  
+  "config": {
+    "label": "FILTERS.creationDate",
+    "fieldKey": "createdAt",
+    "sendMode": "payload",
+    "render": {  
+      "type": "date",  
+      "options": {  
+        "isDateRange": false,
+        "displayFormat": "DD/MM/YYYY",
+        "startView": "month"
+      }  
+    }  
+  }
+}
+```
+
+
+
+---
+---
+
+## Aggregation Field Render
+- **Type**: `CheckboxOptions` | `SwitchOptions`  | `RadioOptions`  | `DropdownOptions`  | `AutocompleteOptions`  | `CustomOptions`  | `DateListOptions`
+- **Description**: Defines the rendering configuration for an aggregation field. The render type determines how users interact with the filter or input—for example, as checkboxes, a dropdown, or a custom UI.
+
+###  Supported Types
+
+####  *Checkbox*
+
+```ts
+type CheckboxOptions = {
+  type: 'checkbox';
+  options?: ShowTotalConfig & FilterConfig & CollapseConfig & SearchConfig & HideLabel & SortOptions;
+};
+```
+
+| Property  | Type                                                                                       | Required | Description                        |
+|-----------|--------------------------------------------------------------------------------------------|----------|------------------------------------|
+| `type`    | `'checkbox'`                                                                               | ✅        | Specifies the input type.          |
+| `options` | `ShowTotalConfig & FilterConfig & CollapseConfig & SearchConfig & HideLabel & SortOptions` | ❌        | Configurable UI and data features. |
+
+```json
+{
+  "type": "checkbox",
+  "options": {
+    "showTotal": true,
+    "filter": true,
+    "collapse": true,
+    "minVisibleCount": 2,
+    "expandedCount": 5,
+    "hideLabel": false,
+    "sort": true,
+      "search": {
+      "placeholder": "Find switch options...",
+      "query": {
+        "field": "gdoc:categoryHierarchyCode",
+        "method": "post",
+        "url": "/api/switch/search",
+        "operator": "equals",
+        "template": " payload value {{text}}",
+        "params": {
+          "active": 1
+        },
+        "headers": {
+          "X-Custom-Header": "value"
+        }
+      }
+    }
+  }
+}
+
+```
+####  *Switch*
+```ts
+ type SwitchOptions = {
+  type: 'switch';
+  options?: ShowTotalConfig & FilterConfig & CollapseConfig & MultipleConfig & SearchConfig & HideLabel & SortOptions;
+};
+```
+
+
+| Property  | Type                                                                                                        | Required | Description                                    |
+|-----------|-------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------|
+| `type`    | `'switch'`                                                                                                  | ✅        | Specifies the input type.                      |
+| `options` | `ShowTotalConfig & FilterConfig & CollapseConfig & MultipleConfig & SearchConfig & HideLabel & SortOptions` | ❌        | Includes `multiple` for multi-selection logic. |
+```json
+{
+  "type": "switch",
+  "options": {
+    "showTotal": false,
+    "filter": true,
+    "collapse": true,
+    "minVisibleCount": 1,
+    "expandedCount": 3,
+    "multiple": true,
+    "hideLabel": true,
+    "sort": false
+  }
+}
+
+```
+
+####  *Radio*
+```ts
+ type RadioOptions = {
+  type: 'radio';
+  options?: ShowTotalConfig & FilterConfig & CollapseConfig & SearchConfig & HideLabel & SortOptions;
+};
+```
+
+| Property  | Type                                                                                       | Required | Description                                  |
+|-----------|--------------------------------------------------------------------------------------------|----------|----------------------------------------------|
+| `type`    | `'radio'`                                                                                  | ✅        | Specifies the input type.                    |
+| `options` | `ShowTotalConfig & FilterConfig & CollapseConfig & SearchConfig & HideLabel & SortOptions` | ❌        | Similar to `CheckboxOptions`, no `multiple`. |
+####  *Dropdown*
+```ts
+ type DropdownOptions = {
+
+  type: 'dropdown';
+
+  options?: Prettify<ShowTotalConfig & MultipleConfig & HideLabel>;
+
+};
+```
+
+| Property  | Type                                           | Required | Description                                          |
+|-----------|------------------------------------------------|----------|------------------------------------------------------|
+| `type`    | `'dropdown'`                                   | ✅        | Specifies the input type.                            |
+| `options` | `ShowTotalConfig & MultipleConfig & HideLabel` | ❌        | Only includes total, multiple, and label visibility. |
+
+```json
+{
+  "type": "dropdown",
+  "options": {
+    "showTotal": true,
+    "multiple": false,
+    "hideLabel": false
+  }
+}
+```
+
+####  *Autocomplete*
+```ts
+type AutocompleteOptions = {
+  type: 'autocomplete';
+  options?: Prettify<ShowTotalConfig & HideLabel>;
+};
+```
+
+| Property  | Type                          | Required | Description                                    |
+|-----------|-------------------------------|----------|------------------------------------------------|
+| `type`    | `'autocomplete'`              | ✅        | Autocomplete input field.                      |
+| `options` | `ShowTotalConfig & HideLabel` | ❌        | Minimal config: total count and label control. |
+####  *Date List*
+```ts
+type DateListOptions = {
+
+  type: 'dateList';
+  options: Prettify<ShowTotalConfig & HideLabel> & {
+    view: (typeof DATE_LIST_VIEW)[keyof typeof DATE_LIST_VIEW]; //list - dropdown
+    minMax?: boolean;
+  };
+};
+```
+
+| Property    | Type                                                            | Required | Description                                               |
+|-------------|-----------------------------------------------------------------|----------|-----------------------------------------------------------|
+| `type`      | `'dateList'`                                                    | ✅        | Specifies it's a date list input.                         |
+| `options`   | `ShowTotalConfig & HideLabel & { view: ..., minMax?: boolean }` | ✅        | Includes display view and optional min-max toggle.        |
+| └─ `view`   | `DATE_LIST_VIEW[keyof DATE_LIST_VIEW]`                          | ✅        | UI view type (e.g., `'list'` or `'dropdown'`).            |
+| └─ `minMax` | `boolean`                                                       | ❌        | Enables min/max range support (e.g., for date filtering). |
+#### *Custom Options*
+```ts
+type CustomOptions = {
+  type: 'custom';
+  options?: Record<string, any> & HideLabel;
+};
+```
+
+| Property  | Type                              | Required | Description                                       |
+|-----------|-----------------------------------|----------|---------------------------------------------------|
+| `type`    | `'custom'`                        | ✅        | Custom input component.                           |
+| `options` | `Record<string, any> & HideLabel` | ❌        | Arbitrary config props with optional `hideLabel`. |
+
+
+
+---
+---
+
+## Custom Field Render
+- **Type**: `ActiveUserSwitcherOptions` 
+- **Description**: Defines the rendering configuration for a custom field.
+
+###  Supported Types
+#### *Active user options*
+```ts
+type ActiveUserSwitcherOptions = {  
+  type: 'activeUser';  
+  options?: Prettify<  
+   HideLabel & {  
+    bindValue?: string;  
+    text?: string;  
+   }  
+  >;  
+}
+```
+
+| Property  | Type                                                         | Required | Description                                           |
+|-----------|--------------------------------------------------------------|----------|-------------------------------------------------------|
+| `type`    | `'activeUser'`                                               | ✅        | Represents an active user switcher component.         |
+| `options` | `{ hideLabel?: boolean; bindValue?: string; text?: string }` | ❌        | Optional label hiding, bound value, and display text. |
+
+
+
+
+
+---
+---
+# Common Types
+
+These common types are used throughout the `NdfTableOptions` interface.
+
+---
+
+*Field options*
+
+```ts
+type FilterConfig = { filter?: boolean };
+
+type HideLabel = { hideLabel?: boolean };
+
+type CollapseConfig = {
+  collapse?: boolean;
+  minVisibleCount?: number;
+  expandedCount?: number;
+
+};
+
+type MultipleConfig = { multiple?: boolean };
+
+type ShowTotalConfig = { showTotal?: boolean };
+
+type SortOptions = { sort?: boolean };
+ 
+type SearchConfig = {
+
+    search?: {
+        placeholder?: string;
+        query: {
+            field?: string;
+            method?: 'get' | 'post';
+            url: string;
+            operator?: ComparisonOperator;
+            template?: EvaluatedString;
+            params?: Record<StringOrNumber, StringOrNumber>;
+            headers?: Record<StringOrNumber, StringOrNumber>;
+        };
+    };
+};
+```
+
+| Property          | Type                                   | Description                                                |
+|-------------------|----------------------------------------|------------------------------------------------------------|
+| `showTotal`       | `boolean`                              | Whether to display a total count (from `ShowTotalConfig`). |
+| `filter`          | `boolean`                              | Enables filtering for this field (from `FilterConfig`).    |
+| `collapse`        | `boolean`                              | Enables collapsing (from `CollapseConfig`).                |
+| `minVisibleCount` | `number`                               | Minimum items visible before collapsing.                   |
+| `expandedCount`   | `number`                               | Number of items shown when expanded.                       |
+| `multiple`        | `boolean`                              | Allow multiple selections (from `MultipleConfig`).         |
+| `hideLabel`       | `boolean`                              | Hides the label of the field/component (from `HideLabel`). |
+| `sort`            | `boolean`                              | Enables field options sort (from `SortOptions`).           |
+| `search`          | `{ placeholder?: string; query: ... }` | Enables search configuration (from `SearchConfig`).        |
+
+*Label Value*
+
+```ts
+type LabelValue<L, V> = {
+	label: L;
+	value: V;
+};
+```
+
+*Ndf Request Config*
+
+```ts
+type NdfRequestConfig = {
+	method: 'post' | 'get';
+	url: string;
+	payload?: Record<string, any>;
+	params?: Record<string, any>;
+	headers?: Record<string, any>;
+};
+```
+
+*Table Sort Config*
+
+```ts
+type TableSortConfig = {
+	enabled: boolean;
+	frozenColumns?: string[];  // Specifies which columns should remain fixed (frozen) during column ordering
+};
+```
+
+*Comparison Operator*
+
+```ts
+  type ComparisonOperator = | '=' | '!=' | '<' | '>' | '<=' | '>=' | 'IN' | 'NOT IN' | 'BETWEEN' | 'LIKE' | 'ILIKE' | 'NOT LIKE' | 'NOT ILIKE' | 'STARTSWITH' | 'FULLTEXT';
+```
+
+*Translate Key*
+
+```ts
+type TranslateKey = string
+```
+
+
+
+# Full Example
+
+```json
+ {
+			"options": {
+				"columns": {
+					"toggle": true,
+					"sortable": {
+						"enabled": true
+					}
+				},
+				"filters": {
+					"mode": "payload",
+					"reload": {
+						"strategy": "always"
+					},
+					"panel": {
+						"visible": true,
+						"toggleButton": true
+					},
+					"fields": [
+						{
+							"type": "aggregation",
+							"config": {
+								"label": "rmAdvancedSearch.recDefintionSystemName",
+								"aggregation": "RecordDefinition_systemName_agg",
+								"fieldKey": "recdef:systemName",
+								"dataTransformer": "system",
+								"order": 0,
+								"sendMode": "queryParam",
+								"render": {
+									"type": "checkbox",
+									"options": {
+										"showTotal": true
+									}
+								}
+							}
+						},
+						{
+							"type": "predicate",
+							"config": {
+								"label": "FILTERS.gdocDocumentSubject",
+								"fieldKey": "gdoc:documentSubject",
+								"sendMode": "payload",
+								"valueType": "valueObject",
+								"render": {
+									"type": "input",
+									"options": {
+										"debounceTime": 400,
+										"mask": {
+											"mask": "00-00-00-00-000",
+											"dropSpecialCharacters": false,
+											"showMaskTyped": true
+										},
+										"suffix": {
+											"dropdown": {
+												"items": [
+													{
+														"key": "OPERATORS.equals",
+														"value": "="
+													},
+													{
+														"key": "OPERATORS.notEquals",
+														"value": "!="
+													},
+													{
+														"key": "OPERATORS.like",
+														"value": "LIKE"
+													},
+													{
+														"key": "OPERATORS.iLike",
+														"value": "ILIKE"
+													}
+												]
+											}
+										}
+									}
+								}
+							}
+						},
+						{
+							"type": "aggregation",
+							"config": {
+								"label": "rmAdvancedSearch.gdocGDocumentDate",
+								"aggregation": "generaldocument_gDocumentDate_agg",
+								"fieldKey": "gdoc:gDocumentDate",
+								"prefix": "search.buckets.",
+								"sendMode": "custom",
+								"valueType": "valueObject",
+								"render": {
+									"type": "dateList",
+									"view": "list",
+									"options": {
+										"showTotal": true,
+										"minMax": true
+									}
+								}
+							}
+						}
+					]
+				},
+				"search": {
+					"fieldKey": "ecm:fulltext",
+					"searchMode": "triggered",
+					"suffix": {
+						"dialog": {
+							"title": "INFO.dialogTitle",
+							"content": [
+								"##INFO.query_sequence##",
+								"##INFO.query_and##",
+								"##INFO.query_negation##",
+								"##INFO.query_prefix##",
+								"##INFO.query_historical##",
+								"##INFO.query_or##",
+								"##INFO.query_phrase##"
+							]
+						}
+					}
+				},
+				"tableMode": {
+					"mode": "list",
+					"componentName": "rms.components.advancedSearchCard",
+					"toggleMode": true,
+					"availableMode": [
+						{
+							"value": "list",
+							"icon": "table_rows"
+						},
+						{
+							"value": "custom",
+							"icon": "rectangle"
+						}
+					]
+				}
+			},
+			"scrollbarH": true,
+			"pageNumber": 1,
+			"pageSize": 10,
+			"prefix": "LISTING.",
+			"pageProvider": "PP_RM_Record",
+			"customUrl": {
+				"url": "/api/v1/custom-search/pp/PP_RM_Record/execute",
+				"method": "POST"
+			},
+			"headers": {
+				"properties": "dublincore, file"
+			},
+			"quickFilters": "After Archiving",
+			"fields": {
+				"systemName": "recdef:systemName",
+				"title": "dc:title"
+			},
+			"columns": [
+				{
+					"name": "systemName",
+					"prop": "properties.systemName",
+					"display": true,
+					"type": "custom",
+					"template": "common.components.systemName",
+					"translatePrefix": "search.buckets",
+					"isOrginalKey": true,
+					"sortable": false,
+					"headerClass": "recdef:systemName",
+					"defaultVisible": true,
+					"minWidth": 150
+				},
+				{
+					"name": "physicalOriginal",
+					"prop": "properties.physicalOriginal",
+					"display": true,
+					"type": "custom",
+					"template": "rms.components.TranslatedValueColumn",
+					"translatePrefix": "rmDocumentUpload.hasPhysicalOriginal",
+					"isBooleanValue": true,
+					"sortable": false,
+					"headerClass": "recdef:physicalOriginal",
+					"defaultVisible": false,
+					"minWidth": 150
+				}
+			]
+		}
+```