nuxeo-development-framework 5.6.3 → 5.6.5

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

@@ -0,0 +1,1026 @@
+# Filters Panel Component Documentation (`app-filters-panel`)
+
+## Overview
+
+The `app-filters-panel` component provides a comprehensive filtering interface for data tables and search results. It supports multiple field types, aggregation-based filtering, and customizable rendering options with real-time data updates and flexible configuration management.
+
+### Key Features
+
+- Dynamic field rendering with multiple input types
+- Aggregation-based filtering with bucket management
+- Real-time query synchronization and state management
+- Custom template integration for specialized components
+- Internationalization support with role-based access control
+
+## Quick Start Guide
+
+### Basic Implementation
+
+```typescript
+import { Component } from '@angular/core';
+import { FieldConfigModel, AggregationResponse, FormQueryModel } from './types';
+
+@Component({
+  template: `
+    <app-filters-panel
+      [aggregations]="aggregations"
+      [fields]="filterFields"
+      [activeQuery]="currentQuery"
+      (filterChanged)="onFilterChange($event)">
+    </app-filters-panel>
+  `
+})
+export class MyComponent {
+  aggregations: Record<string, AggregationResponse> = {
+    'priority_agg': {
+      id: 'priority_agg',
+      field: 'priority',
+      buckets: [
+        { key: 'high', docCount: 25 },
+        { key: 'medium', docCount: 48 },
+        { key: 'low', docCount: 12 }
+      ],
+      properties: {}
+    }
+  };
+
+  filterFields: FieldConfigModel[] = [
+    {
+      type: 'aggregation',
+      config: {
+        label: 'FILTERS.priority',
+        fieldKey: 'priority',
+        aggregation: 'priority_agg',
+        sendMode: 'queryParam',
+        render: {
+          type: 'checkbox',
+          options: { showTotal: true }
+        }
+      }
+    }
+  ];
+
+  currentQuery: FormQueryModel = {};
+
+  onFilterChange(filters: Record<string, any>) {
+    console.log('Filter changed:', filters);
+    // Handle filter updates
+  }
+}
+```
+
+
+---
+
+## Component Interface
+
+### Input Properties
+
+```typescript
+@Component({
+  selector: 'app-filters-panel',
+  // ...
+})
+export class FiltersPanel {
+  @Input() aggregations: Record<string, AggregationResponse>;
+  @Input() fields: FieldConfigModel[];
+  @Input() activeQuery: FormQueryModel;
+  @Input() customTemplateRef: TemplateRef<any>;
+
+  @Output() filterChanged = new EventEmitter<Record<string, any>>();
+}
+```
+
+#### Property Specifications
+
+| Property            | Type                                  | Required | Description                                                   |
+| ------------------- | ------------------------------------- | -------- | ------------------------------------------------------------- |
+| `aggregations`      | `Record<string, AggregationResponse>` | ✅        | Collection of aggregation data indexed by aggregation ID      |
+| `fields`            | `FieldConfigModel[]`                  | ✅        | Array of filter field configurations defining UI and behavior |
+| `activeQuery`       | `FormQueryModel`                      | ✅        | Current query state for synchronizing filter values           |
+| `customTemplateRef` | `TemplateRef<any>`                    | ❌        | Template reference for aggregation field custom rendering     |
+
+#### Event Emissions
+
+|Event|Type|Description|
+|---|---|---|
+|`filterChanged`|`EventEmitter<Record<string, any>>`|Emitted when filter values change, containing updated filter state|
+
+---
+
+## Data Models
+
+### `AggregationResponse` Interface
+
+```typescript
+export interface AggregationResponse {
+  'entity-type'?: string;
+  id: string;
+  field?: string;
+  properties: Record<string, any>;
+  ranges?: any[];
+  selection?: any[];
+  type?: string;
+  buckets: AggregationBucket[];
+  extendedBuckets?: AggregationBucket[];
+}
+```
+
+#### Property Descriptions
+
+| Property          | Type                  | Required | Description                                               |
+| ----------------- | --------------------- | -------- | --------------------------------------------------------- |
+| `entity-type`     | `string`              | ❌        | Entity classification for the aggregation                 |
+| `id`              | `string`              | ✅        | Unique identifier                                         |
+| `field`           | `string`              | ❌        | Source field key used for aggregation                     |
+| `properties`      | `Record<string, any>` | ✅        | Additional metadata and configuration properties          |
+| `ranges`          | `any[]`               | ❌        | Predefined ranges for range-based aggregations            |
+| `selection`       | `any[]`               | ❌        | Currently selected values for the aggregation             |
+| `type`            | `string`              | ❌        | Aggregation type identifier                               |
+| `buckets`         | `AggregationBucket[]` | ✅        | Primary aggregation results containing filterable options |
+| `extendedBuckets` | `AggregationBucket[]` | ❌        | Additional bucket data for extended functionality         |
+
+### `AggregationBucket` Interface
+
+```typescript
+export interface AggregationBucket {
+  key: string;
+  docCount: number;
+  fetchedKey?: Record<string, any>;
+  from?: number;
+  to?: number;
+  fromAsDate?: Record<string, any>;
+  toAsDate?: Record<string, any>;
+}
+```
+
+#### Property Descriptions
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|`key`|`string`|✅|Unique identifier for the bucket value|
+|`docCount`|`number`|✅|Number of documents matching this bucket|
+|`fetchedKey`|`Record<string, any>`|❌|Additional key metadata from data source|
+|`from`|`number`|❌|Range start value for numeric range buckets|
+|`to`|`number`|❌|Range end value for numeric range buckets|
+|`fromAsDate`|`Record<string, any>`|❌|Range start as date object for date range buckets|
+|`toAsDate`|`Record<string, any>`|❌|Range end as date object for date range buckets|
+
+---
+
+## Field Configuration
+
+### `FieldConfigModel` Types
+
+```typescript
+type FieldConfigModel =
+  | { type: 'aggregation'; config: AggregationFieldConfig; }
+  | { type: 'predicate'; config: PredicateFieldConfig; }
+  | { type: 'custom'; config: CustomFieldConfig; };
+```
+
+### Base Field Configuration
+
+```typescript
+interface BaseFieldConfig {  
+	label: TranslateKey;  
+	fieldKey: string;  
+	values?: unknown;  
+	prefix?: string;  
+	order?: number;  
+	operator?: ComparisonOperator;  
+	valueType: 'valueObject' | 'property';  
+	visible?: boolean;  
+	roles?: string[];  
+	permission?: string;  
+	condition?: EvaluatedString;
+}
+```
+
+#### Core Properties
+
+| Property     | Type                            | Required | Default       | Description                                                                                                                                                                                                                                                                 |
+| ------------ | ------------------------------- | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `TranslateKey`                  | ✅        | -             | Internationalization key for field display label                                                                                                                                                                                                                            |
+| `fieldKey`   | `string`                        | ✅        | -             | Unique identifier used for data binding and query construction                                                                                                                                                                                                              |
+| `values`     | `unknown`                       | ❌        | -             | Static data source for field options                                                                                                                                                                                                                                        |
+| `prefix`     | `string`                        | ❌        | -             | Translation key prefix for localized option values                                                                                                                                                                                                                          |
+| `order`      | `number`                        | ❌        | `0`           | Display order priority in filter panel                                                                                                                                                                                                                                      |
+| `operator`   | `ComparisonOperator`            | ❌        | -             | Comparison operator for filter logic                                                                                                                                                                                                                                        |
+| `valueType`  | `'valueObject'` \| `'property'` | ❌        | `valueObject` | Value interpretation method for filtering                                                                                                                                                                                                                                   |
+| `visible`    | `boolean`                       | ❌        | `true`        | Runtime visibility control                                                                                                                                                                                                                                                  |
+| `roles`      | `string[]`                      | ❌        | -             | Required user roles for field access                                                                                                                                                                                                                                        |
+| `permission` | `string`                        | ❌        | -             | Specific permission requirement                                                                                                                                                                                                                                             |
+| condition    | EvaluatedString                 | ❌        |               | **Logical expression** evaluated at runtime to determine field visibility. Supports access to other filter values or context variables (e.g., `show = filters.status === 'active'`). Use this to implement dynamic field inclusion based on filter state or external inputs |
+
+---
+
+## **Field Types**
+
+## 1. Aggregation Fields
+
+### `AggregationFieldConfig` interface
+
+```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;
+}
+```
+
+### Properties
+
+| Property       | Type     | Required | Default | Description |
+|----------------|----------|----------|---------|-------------|
+| `aggregation`  | `string` | ✅        | -       | **Aggregation identifier** that must match a key in the parent component's aggregations input for data binding |
+| `sendMode`     | `FieldSendModeType` | ✅ | - | **Filter transmission mode** determining how selected values are sent to the backend |
+| `propertyPath` | `string` | ❌        | `fieldKey` | **Alternative property path** for nested object property access when aggregation field differs from fieldKey |
+| `bindLabel`    | `{ ar: string; en: string }` | ❌ | - | **Localized property mappings** defining bucket properties containing Arabic and English labels |
+| `bindValue`    | `string` | ❌        | `'key'` | **Value extraction property** specifying which bucket property serves as the filter value |
+| `dataTransformer` | `string` | ❌        | -       | **Transformer function name** registered in `NdfTransformService` for custom bucket data processing |
+| `tooltip`         | `AggregationTooltipType` | ❌ | - | **Tooltip configuration** for displaying additional information about filter options |
+| `render` | `RenderOptions` | ✅ | - | **UI rendering configuration** defining component type and display options |
+
+### `FieldSendModeType` Options
+
+```typescript
+const FIELD_SEND_MODE = {  
+  payload: 'payload',  
+  queryParam: 'queryParam',  
+  custom: 'custom'  
+} as const ;
+
+type FieldSendModeType = (typeof FIELD_SEND_MODE)[keyof typeof FIELD_SEND_MODE]; //'queryParam' | 'payload' | 'custom'
+```
+
+### Properties
+| Mode         | Description                                        | Use Case                           |
+| ------------ | -------------------------------------------------- | ---------------------------------- |
+| `queryParam` | Sends filter values as URL query parameters        | RESTful APIs, bookmarkable filters |
+| `payload`    | Includes filter values in request body             | Complex queries, large filter sets |
+| `custom`     | Delegates filter handling to custom implementation | Specialized filtering logic        |
+
+
+```ts
+/*
+	Basic Aggregation Field Setup
+*/
+import { AggregationFieldConfig, FieldSendModeType } from './types';
+
+// Simple checkbox aggregation field
+const priorityFilter: AggregationFieldConfig = {
+  // Base field properties
+  label: 'FILTERS.priority',
+  fieldKey: 'priority',
+  valueType: 'valueObject',
+  
+  // Aggregation-specific properties
+  aggregation: 'priority_agg',
+  sendMode: 'queryParam',
+  
+  // Rendering configuration
+  render: {
+    type: 'checkbox',
+    options: {
+      showTotal: true,
+      filter: true,
+      collapse: true
+    }
+  }
+};
+
+/* 
+	Advanced Configuration with Localization
+*/
+
+const statusFilter: AggregationFieldConfig = {
+  label: 'FILTERS.documentStatus',
+  fieldKey: 'doc:status',
+  propertyPath: 'document.status',
+  aggregation: 'status_aggregation',
+  
+  // Localized label binding
+  bindLabel: {
+    ar: 'statusAr',
+    en: 'statusEn'
+  },
+  bindValue: 'statusCode',
+  
+  // Custom data processing
+  dataTransformer: 'statusTransformer',
+  
+  sendMode: 'payload',
+  
+  // Tooltip configuration
+  tooltip: {
+    type: 'localizeValue',
+    content: 'TOOLTIPS.statusFilter'
+  },
+  
+  render: {
+    type: 'dropdown',
+    options: {
+      multiple: true,
+      showTotal: true
+    }
+  }
+};
+
+```
+
+## Render Options
+### Available Render Types
+
+The `render` property accepts one of several specialized option types:
+
+#### `CheckboxOptions`
+```ts
+type CheckboxOptions = {
+  type: 'checkbox';
+  options?: {
+    showTotal?: boolean;        // Display document count
+    filter?: boolean;           // Enable search within options
+    collapse?: boolean;         // Collapsible option list
+    minVisibleCount?: number;   // Items shown before collapse
+    expandedCount?: number;     // Items shown when expanded
+    hideLabel?: boolean;        // Hide field label
+    sort?: boolean;            // Sort options alphabetically
+    search?: SearchConfig;     // Advanced search configuration
+  };
+};
+```
+
+
+#### `SwitchOptions`
+```typescript
+type SwitchOptions = {
+  type: 'switch';
+  options?: {
+    showTotal?: boolean;       // Display document count
+    filter?: boolean;          // Enable search within options
+    collapse?: boolean;        // Collapsible option list
+    multiple?: boolean;        // Allow multiple selections
+    hideLabel?: boolean;       // Hide field label
+    sort?: boolean;           // Sort options alphabetically
+    search?: SearchConfig;    // Advanced search configuration
+  };
+};
+```
+
+#### `RadioOptions`
+```typescript
+type RadioOptions = {
+  type: 'radio';
+  options?: {
+    showTotal?: boolean;       // Display document count
+    hideLabel?: boolean;       // Hide field label
+    sort?: boolean;           // Sort options alphabetically
+  };
+};
+```
+#### `DropdownOptions`
+```typescript
+type DropdownOptions = {
+  type: 'dropdown';
+  options?: {
+    showTotal?: boolean;       // Display document count in options
+    multiple?: boolean;        // Allow multiple selections
+    hideLabel?: boolean;       // Hide field label
+  };
+};
+```
+
+#### `AutocompleteOptions`
+```typescript
+type AutocompleteOptions = {
+  type: 'autocomplete';
+  options?: {
+    showTotal?: boolean;       // Display document count
+    multiple?: boolean;        // Allow multiple selections
+    hideLabel?: boolean;       // Hide field label
+    minChars?: number;        // Minimum characters for search
+    debounceTime?: number;    // Search delay in milliseconds
+  };
+};
+```
+
+#### `DateListOptions`
+```typescript
+type DateListOptions = {
+  type: 'dateList';
+  options?: {
+    showTotal?: boolean;       // Display document count
+    format?: string;          // Date display format
+    groupBy?: 'year' | 'month' | 'day'; // Date grouping
+    hideLabel?: boolean;       // Hide field label
+  };
+};
+```
+
+#### `CustomOptions`
+```typescript
+type CustomOptions = {
+  type: 'custom';
+  options?: Record<string, any>; // Custom component configuration
+};
+```
+
+
+## Tooltip Configuration
+
+### `AggregationTooltipType` Interface
+
+```typescript
+ type AggregationTooltipType = {  
+  properties: Record<string, any>;  
+} & (TooltipPlainText | TooltipLocalizedText | TooltipFormattedDate | TooltipTranslationKey | TooltipTranslatedDate);  
+  
+ type TooltipPlainText = {  
+  type: 'text';  // Defines this variant as plain text.
+  separator?: string;   //Optional separator used between multiple values.
+};  
+  
+ type TooltipLocalizedText = {  
+  type: 'localizeValue';  
+  translateKey: string;  //Key used for localization.
+};  
+  
+ type TooltipFormattedDate = {  
+  type: 'date';  
+  format: string;  //Date format string (e.g., `YYYY-MM-DD`).
+  separator?: string;  
+};  
+  
+ type TooltipTranslationKey = {  
+  type: 'translate';  
+  prefix: string;  //Prefix to be appended to the value as a key.
+  separator?: string;  
+};  
+  
+type TooltipTranslatedDate = {  
+  type: 'translatedDate';  
+  format: string;  
+  translateKey: string;  
+};
+```
+
+### Example Usage
+
+```typescript
+ 
+const fieldWithHelp: AggregationFieldConfig = {
+  // ... other properties
+  tooltip: {
+    type: 'localizeValue',
+    translateKey: 'HELP.filterUsage',
+  },
+}
+
+const fieldWithDateHelp: AggregationFieldConfig = {
+  // ... other properties
+  tooltip: {
+    type: 'date',
+    properties: {
+      from: 'from',
+      to: 'to',
+    },
+  },
+}
+```
+
+
+## Field Search Configuration
+### `SearchConfig` Interface
+The `SearchConfig` type enables dynamic search functionality within filter fields, providing configurable search endpoints with template-based query generation.
+
+```ts
+type SearchConfig = {
+  /**
+   * Placeholder text for the search input.
+   */
+  placeholder?: string;
+
+  /**
+   * Query configuration for the search.
+   */
+  query: {
+    /**
+     * The field to be queried.
+     */
+    field?: string;
+
+    /**
+     * HTTP method to use for the query.
+     * Can be either 'get' or 'post'.
+     */
+    method?: 'get' | 'post';
+
+    /**
+     * The URL endpoint for the query.
+     */
+    url: string;
+
+    /**
+     * Operator to use for comparison in the query.
+     */
+    operator?: ComparisonOperator;
+
+    /**
+     * Template string for dynamic query generation.
+     * Variables enclosed in double braces will be replaced with search values.
+     * Example: "dc:title {{searchText}} AND status:active"
+     */
+    template?: InterpolateString;
+
+    /**
+     * Query parameters as key-value pairs.
+     */
+    params?: Record<string | number, string | number>;
+
+    /**
+     * HTTP headers as key-value pairs.
+     */
+    headers?: Record<string | number, string | number>;
+  };
+};
+```
+
+#### Template String Interpolation
+The `template` property supports dynamic value replacement using double brace syntax `{{variableName}}`. The most common variable is `searchText`, which represents the user's input.
+
+**Template Examples**
+
+```typescript
+// Basic title search
+"dc:title ILIKE '{{searchText}}%'"
+
+// Complex multi-field search
+"(dc:title LIKE '%{{searchText}}%' OR dc:description LIKE '%{{searchText}}%') AND ecm:currentLifeCycleState = 'active'"
+
+// Date-based search with user input
+"dc:created >= '{{startDate}}' AND dc:created <= '{{endDate}}' AND dc:title LIKE '%{{search
+```
+
+**Basic Search with Template**
+```json
+{
+  "search": {
+    "placeholder": "Search documents...",
+    "query": {
+      "url": "/api/v1/search/documents",
+      "method": "post",
+      "field": "dc:title",
+      "operator": "ILIKE",
+      "template": "'%{{searchText}}%'",
+      "headers": {
+        "Content-Type": "application/json"
+      }
+    }
+  }
+}
+```
+
+## 2. Predicate Fields
+### `PredicateFieldConfig` interface
+```ts
+type PredicateFieldConfig = BaseFieldConfig & {  
+   sendMode: Exclude<FieldSendModeType, 'custom'>;  
+   render: InputOptions | DateInputOptions;  
+  }  
+```
+
+## Render Options
+### Available Render Types
+
+The `render` property accepts one of several specialized option types:
+
+#### `InputOptions`
+```typescript
+type InputOptions = {  
+  type: 'input';  
+  options?:  {  
+	hideLabel?: boolean
+    inputType?: 'text' | 'search' | 'url';  
+    placeholder?: string;  
+    debounceTime?: number;  
+    mask?: InputMaskConfig;  
+    suffix?: InputSuffixConfig;  
+   }  
+};
+```
+
+### Properties
+
+| Property               | Type                              | Required | Description                                 |
+| ---------------------- | --------------------------------- | -------- | ------------------------------------------- |
+| `type`                 | `'input'`                         | ✅        | Field type identifier (always `'input'`)    |
+| `options.hideLabel`    | `boolean`                         | ❌        | If true, hides the field label              |
+| `options.inputType`    | `'text'` \| `'search'` \| `'url'` | ❌        | Specifies the HTML input type               |
+| `options.placeholder`  | `string`                          | ❌        | Placeholder text displayed inside the input |
+| `options.debounceTime` | `number`                          | ❌        | Debounce time (ms) for emitting changes     |
+
+### `InputMaskConfig` Type
+```ts
+type InputMaskConfig = {
+  mask: string;
+  shownMaskExpression?: string;
+  dropSpecialCharacters?: boolean;
+  showMaskTyped?: boolean;
+  validation?: boolean;
+  allowNegativeNumbers?: boolean;
+  keepCharacterPositions?: boolean;
+  leadZero?: boolean;
+  hiddenInput?: boolean;
+  clearIfNotMatch?: boolean;
+  prefix?: string;
+  suffix?: string;
+};
+```
+
+### Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|`mask`|`string`|✅|Pattern for text masking|
+|`shownMaskExpression`|`string`|❌|Visible mask guide|
+|`dropSpecialCharacters`|`boolean`|❌|Remove non-alphanumeric chars|
+|`showMaskTyped`|`boolean`|❌|Display mask during typing|
+|`validation`|`boolean`|❌|Enable input validation|
+|`allowNegativeNumbers`|`boolean`|❌|Allow negative numeric values|
+|`keepCharacterPositions`|`boolean`|❌|Maintain cursor position|
+|`leadZero`|`boolean`|❌|Keep leading zeros|
+|`hiddenInput`|`boolean`|❌|Hide raw input value|
+|`clearIfNotMatch`|`boolean`|❌|Clear invalid input|
+|`prefix`|`string`|❌|Fixed prefix text|
+|`suffix`|`string`|❌|Fixed suffix text|
+
+### `InputSuffixConfig` Type
+
+```ts
+type InputSuffixConfig = {
+  text?: string;
+  dropdown?: {
+    selectedValue?: string;
+    items: KeyValue<TranslateKey, string>[];
+  };
+  tooltip?: string;
+  dialog?: HtmlDialogConfig;
+};
+```
+
+### Properties
+
+| Property           | Type                                                                   | Required | Description                        |
+| ------------------ | ---------------------------------------------------------------------- | -------- | ---------------------------------- |
+| `text`             | `string`                                                               | ❌        | Static text displayed as suffix    |
+| `dropdown`         | `{ selectedValue?: string; items: KeyValue<TranslateKey, string>[]; }` | ❌        | Adds a dropdown menu to the suffix |
+| └─ `selectedValue` | `string`                                                               | ❌        | Currently selected value           |
+| └─ `items`         | `KeyValue<TranslateKey, string>[]`                                     | ✅        | Dropdown list items                |
+| `tooltip`          | `string`                                                               | ❌        | Tooltip displayed on hover         |
+| `dialog`           | `HtmlDialogConfig`                                                     | ❌        | Configuration for a modal dialog   |
+
+### `HtmlDialogConfig` Interface
+```ts
+export type HtmlDialogConfig = {
+  content: string[];
+  title?: string;
+  options?: Partial<MatDialogConfig>;
+};
+```
+
+### Properties
+
+| Property  | Type                       | Required | Description                                                  |
+| --------- | -------------------------- | -------- | ------------------------------------------------------------ |
+| `content` | `string[]`                 | ✅        | ##translate keys## or content lines to display in the dialog |
+| `title`   | `string`                   | ❌        | Dialog title text                                            |
+| `options` | `Partial<MatDialogConfig>` | ❌        | Angular Material dialog configuration overrides              |
+### Example Usage
+
+```json
+{
+  "type": "predicate",
+  "config": {
+    "label": "FILTERS.searchTerm",
+    "fieldKey": "searchQuery",
+    "sendMode": "payload",
+    "render": {
+      "type": "input",
+      "options": {
+        "placeholder": "Enter your query...",
+        "debounceTime": 400,
+        "inputType": "text",
+        "mask": {
+          "mask": "000-000",
+          "dropSpecialCharacters": true
+        },
+        "suffix": {
+          "text": "?",
+          "tooltip": "Search by reference number"
+        }
+      }
+    }
+  }
+}
+
+```
+
+
+## 2. Custom Fields
+### `CustomFieldConfig` interface
+```ts
+type CustomFieldConfig = BaseFieldConfig & {
+    sendMode: Exclude<FieldSendModeType, 'custom'>;
+    render: ActiveUserSwitcherOptions | AggregationGroupOptions;
+}
+```
+
+## Render Options
+### Available Render Types
+
+The `render` property accepts one of `ActiveUserSwitcherOptions` and `AggregationGroupOptions` :
+
+### `ActiveUserSwitcherOptions` Type
+
+```ts
+type ActiveUserSwitcherOptions = {
+  type: 'activeUser';
+  options?: HideLabel & {
+      bindValue?: string;
+      text?: string;
+    }
+};
+```
+### Properties
+| Property            | Type           | Required | Description                                 |
+| ------------------- | -------------- | -------- | ------------------------------------------- |
+| `type`              | `'activeUser'` | ✅        | Identifier for active user switch rendering |
+| `options.bindValue` | `string`       | ❌        | Key to bind user value (e.g., user ID)      |
+| `options.text`      | `string`       | ❌        | translated key                              |
+| `options.hideLabel` | `boolean`      | ❌        | If true, hides the label in the UI          |
+
+### `AggregationGroupOptions` Type
+
+Enables rendering of a grouped set of aggregation-based filters as a single field. Each item behaves like a standard aggregation input field.
+```ts
+export type AggregationGroupOptions = {
+  type: 'aggregationGroup';
+  options?: {
+    aggregations: AggregationGroupItem[];
+  };
+};
+
+/* 
+`AggregationGroupItem` Type
+*/
+
+interface AggregationGroupItem
+  extends Omit<AggregationFieldConfig, 'render' | 'valueType' | 'sendMode'> {
+  render: CheckboxOptions | SwitchOptions | RadioOptions | DropdownOptions;
+}
+
+```
+
+### Properties
+|Property|Type|Required|Description|
+|---|---|---|---|
+|`type`|`'aggregationGroup'`|✅|Field type identifier|
+|`options.aggregations`|`AggregationGroupItem[]`|✅|List of aggregation-based fields rendered as a group|
+|└─ `render`|`CheckboxOptions` \| `SwitchOptions` \| `RadioOptions` \| `DropdownOptions`|✅|Rendering configuration for each sub-field|
+
+### Example Usage
+
+```json
+{
+  "type": "custom",
+  "config": {
+    "label": "",
+    "fieldKey": "gdoc:categoryHierarchyCode",
+    "sendMode": "payload",
+    "valueType": "valueObject",
+    "render": {
+      "type": "aggregationGroup",
+      "options": {
+        "aggregations": [
+          {
+            "label": "rmAdvancedSearch.gdocCategoryHierarchyCode",
+            "aggregation": "generaldocument_categoryHierarchyCode_agg",
+            "fieldKey": "categoryHierarchyCode",
+            "dataTransformer": "subject",
+            "order": 0,
+            "render": {
+              "type": "checkbox",
+              "options": {
+                "showTotal": true
+              }
+            }
+          },
+          {
+            "label": "rmAdvancedSearch.gdocCategoryHierarchyCode1",
+            "aggregation": "generaldocument_categoryHierarchyCode_1_agg",
+            "fieldKey": "categoryHierarchyCode_1_agg",
+            "order": 0,
+            "dataTransformer": "subject",
+            "render": {
+              "type": "checkbox",
+              "options": {
+                "showTotal": true,
+                "collapse": true
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+
+```
+
+
+---
+# Utilities & Advanced Features
+## Query Encoding & Decoding
+
+The `FilterQueryService` provides utility methods to **serialize and deserialize filter states** between object-based formats and compact, URL-safe strings. This enables sharing and persisting filter configurations via query parameters or external storage.
+
+It uses a **short key mapping system** to reduce payload size, especially for deeply nested predicate filters.
+
+> **Note:** Before encoding or decoding custom filters, you must call `registerKeys()` in your `CoreModule` || 'AppModule' to define how long property names map to short ones. This is essential for consistency between encoded and decoded queries.
+
+### Service: `FilterQueryService`
+
+```ts
+@Injectable({ providedIn: 'root' })
+export class FilterQueryService {
+  // Registers a set of key mappings
+  registerKeys(keys: Record<string, string>): void;
+
+  // Registers a single key mapping
+  registerKey(longKey: string, shortKey: string): void;
+
+  // Encodes a query object into a URL-safe string
+  encodeQuery(query: Record<string, any>): string;
+
+  // Decodes an encoded query string back into its original object structure
+  decodeQuery(encodedQuery: string): Record<string, any> | null;
+}
+```
+
+
+### Example: Registering Field Keys
+
+```ts
+//file : core.module.ts
+this.filterQueryService.registerKeys({
+  'ecm:primaryType': 'EPT',
+  'requestcase:requestNumber': 'RRN',
+  'ecm:currentLifeCycleState': 'ECL',
+  'dublincore_created_agg': 'DCA',
+  'requestcase_dueDate_agg': 'RDA',
+  'requestcase_dueDate_1_agg': 'RD1'
+});
+```
+
+This ensures that a query like:
+```ts
+{
+  'ecm:primaryType': ['Case'],
+  'requestcase:requestNumber': {
+    value: '12345',
+    operator: 'EQUALS'
+  }
+}
+```
+…is encoded as:
+```json
+{
+  "EPT": ["Case"],
+  "RRN": { "v": "12345", "o": "EQUALS" }
+}
+```
+…and will decode back into the original format using the same mappings.
+
+### Encoding Example
+```ts
+const filters = {
+  'ecm:primaryType': ['Case'],
+  'requestcase:requestNumber': {
+    value: '12345',
+    operator: 'EQUALS'
+  }
+};
+
+const encoded = this.filterQueryService.encodeQuery(filters);
+// Output: "%7BEPT%3A%5B%22Case%22%5D%2CRRN%3A%7Bv%3A%2212345%22%2Co%3A%22EQUALS%22%7D%7D"
+```
+
+### Decoding Example
+```ts
+const encoded = '%7BEPT%3A%5B%22Case%22%5D%2CRRN%3A%7Bv%3A%2212345%22%2Co%3A%22EQUALS%22%7D%7D';
+const decoded = this.filterQueryService.decodeQuery(encoded);
+// Output:
+{
+  'ecm:primaryType': ['Case'],
+  'requestcase:requestNumber': {
+    value: '12345',
+    operator: 'EQUALS'
+  }
+}
+```
+
+### Best Practices
+1. **Register all custom keys** during application initialization
+2. **Pre-process special characters** in values
+3. **Maintain mapping consistency** across environments
+4. **Test round-trip encoding** for complex queries
+5. **Handle null returns** in decoding operations
+
+```ts
+// Safe decoding pattern
+const decoded = this.filterQueryService.decodeQuery(params) || {};
+```
+
+
+## Evaluator Sandbox
+
+The `condition` parameter allows developers to define dynamic logical expressions that determine visibility, execution, or behavior within applications—without compromising security. These expressions are evaluated within a tightly controlled sandbox to prevent access to unsafe or unintended resources.
+### Current Secure Context Implementation
+
+The Evaluator function Structure with Conditional Execution
+```ts
+(function anonymous(aggregations, language, user, values, sandbox) {
+	// Securely exposed globals
+    const console = sandbox.console;
+    const Math = sandbox.Math;
+    const Date = sandbox.Date;
+    const Number = sandbox.Number;
+    const String = sandbox.String;
+    const Boolean = sandbox.Boolean;
+    const Array = sandbox.Array;
+    const Object = sandbox.Object;
+    const JSON = sandbox.JSON;
+    const window = sandbox.window;
+    const self = sandbox.self;
+    const globalThis = sandbox.globalThis;
+    const _ = sandbox._; // Lodash
+    var show;
+     // your conditional logic here
+     // Example:
+     // show = user.role === 'admin' && values.status === 'active'; console.log('Access granted');
+    return show
+}
+)
+
+```
+
+>**Note:**
+- **`show` is always the expected return variable** — the condition must assign to it.
+- **Function parameters are dynamic in most cases**, **but in the context of a field config**, the function signature is **fixed**.
+### Writing a Condition
+```json
+{
+	"condition": "show = user.role === 'admin' && values.status === 'active'; console.log('Access granted');"
+}
+```
+
+
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Transformer Not Found
+
+**Error**: `No transformer defined for type 'subject'` **Solution**: Register the transformer using the appropriate service method:
+
+```typescript
+ 
+ndfTransformService.register('subject', (keys) =>  {});
+ 
+```
+
+#### 2. Query not encoding
+
+**Error**: `Query key mapping not found for 'SOME KEY'.` **Solution**: Register the key in `FilterQueryService` before using:
+
+```typescript
+FilterQueryService.registerKey('long Key', 'short Key');
+```
+
+#### 3. Field Condition not applied
+
+**Error**: `condition not working or drop a warrnig message`  **Solution**: Check and the evaluated string and make sure append value to declared variable 'show' :
+
+```ts
+	//example
+	show = values && values['any']?.includes('some');
+```