nuxeo-development-framework 5.6.0 → 5.6.2

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

@@ -0,0 +1,1213 @@
+
+# NDF Reports Component (`app-ndf-reports`) - Documentation
+
+
+## Overview
+
+The `app-ndf-reports` is a highly configurable and extensible Angular component for rendering dynamic reports with Chart.js integration. It supports multiple chart types, advanced filtering, data transformation, and responsive layouts.
+
+### Key Features
+
+- Server-side configuration loading via report keys
+- Direct configuration injection for programmatic usage
+- Built-in JSON configuration editor with navigation
+- Dynamic report rendering with multiple chart types
+- Query change event emission for external integration
+- Navigation integration for seamless user experience
+
+### Input Properties
+
+```typescript
+@Component({
+  selector: 'app-ndf-reports'
+})
+export class NdfReportsComponent {
+  @Input() jsonEditorEnabled: boolean = false;
+  @Input() reportsKey: string;
+  @Input() navigateRoute: string[] = [];
+  @Input() config: NdfReportsConfig;
+  
+  @Output() onQueryChange = new EventEmitter();
+}
+```
+
+#### Property Specifications
+
+| Property           | Type                | Required | Default | Description                                          |
+| ------------------ | ------------------- | -------- | ------- | ---------------------------------------------------- |
+| jsonEditorEnabled  | `boolean`           | ❌        | `false` | Enable navigation to configuration editor interface  |
+| reportsKey         | `string`            | ⚠️        | -       | Server-side configuration identifier                 |
+| navigateRoute      | `string[]`          | ❌        | `[]`    | Angular route array for navigation purposes          |
+| config             | `NdfReportsConfig`  | ⚠️        | -       | Direct configuration object for report definitions   |
+
+> **⚠️ Configuration Requirement**: Either `reportsKey` OR `config` must be provided. These inputs are mutually exclusive.
+
+#### Output Events
+
+| Event          | Type                    | Description                                        |
+| -------------- | ----------------------- | -------------------------------------------------- |
+| onQueryChange  | `EventEmitter<any>`     | Emitted when report query parameters are modified |
+
+## Configuration Loading Strategy
+
+The component supports two distinct configuration loading approaches:
+
+### Server-Side Configuration Loading
+
+Use `reportsKey` to fetch configuration from server-side storage:
+
+```html
+<!-- Template usage -->
+<app-ndf-reports 
+  [reportsKey]="'ARCHIVE_REPORTS_CONFIG'"
+  [jsonEditorEnabled]="true"
+  [navigateRoute]="['/reports', 'editor']"
+  (onQueryChange)="handleQueryChange($event)">
+</app-ndf-reports>
+```
+
+```typescript
+// Component usage
+export class DashboardComponent {
+  handleQueryChange(queryData: any): void {
+    console.log('Report query changed:', queryData);
+  }
+}
+```
+
+### Direct Configuration Injection
+
+Use `config` for programmatic configuration management:
+
+```html
+<!-- Template usage -->
+<app-ndf-reports 
+  [config]="reportsConfiguration"
+  [jsonEditorEnabled]="false"
+  (onQueryChange)="handleQueryChange($event)">
+</app-ndf-reports>
+```
+
+## Quick Start Guide
+
+### Basic Setup
+
+```typescript
+const basicConfig: NdfReportsConfig = {
+  request: {
+    pageProvider: 'PP_SALES_DATA'
+  },
+  reports: {
+    items: [
+      {
+        id: 'sales-total',
+        label: 'Total Sales',
+        mode: 'digit',
+        datasource: {
+          propertyPath: 'totalSales'
+        }
+      }
+    ]
+  }
+};
+```
+
+### With Filters
+
+```typescript
+const configWithFilters: NdfReportsConfig = {
+  request: {
+    pageProvider: 'PP_SALES_DATA'
+  },
+  filters: {
+    mode: 'payload',
+    visible: true,
+    fields: [
+	    {
+		  type: 'predicate',
+		  config: {
+		    label: 'FILTERS.requestNumber',
+		    fieldKey: 'requestcase:requestNumber',
+		    sendMode: 'payload',
+		    valueType: 'valueObject',
+		    render: {
+		      type: 'input',
+		      options: {
+		        debounceTime: 300,
+		      },
+		    },
+		  },
+		},
+      {  
+		  type: 'aggregation',  
+		  config: {  
+		   label: 'LISTING.Last_Contributors',  
+		   aggregation: 'dublincore_lastContributor_agg',  
+		   fieldKey: 'dc:lastContributor',  
+		   order: 0,  
+		   sendMode: 'queryParam',  
+		   valueType: 'property',  
+		   condition: `show = values && values['ecm:currentLifeCycleState']?.includes('ended');`,  
+		   render: {  
+		    type: 'checkbox',  
+		    options: {  
+		     showTotal: true  
+		    }  
+		   }  
+		  }  
+		}
+    ]
+  },
+  reports: {
+    items: [/* report definitions */]
+  }
+};
+```
+
+## Core Configuration
+
+### `NdfReportsConfig` Interface
+
+The main configuration interface that defines all aspects of the reports component.
+
+```typescript
+export type NdfReportsConfig = {
+  request: NdfReportsRequest;
+  filters?: NdfReportsFilters;
+  options?: {
+    print?: boolean;
+  };
+  activeQuery?: Record<string, any>;
+  reports: ReportsDefinition;
+};
+```
+
+### Properties
+
+| Property    | Type                  | Required | Description                                |
+| ----------- | --------------------- | -------- | ------------------------------------------ |
+| request     | `NdfReportsRequest`   | ✅        | Core request parameters for data fetching  |
+| filters     | `NdfReportsFilters`   | ❌        | Optional filtering configuration           |
+| options     | `object`              | ❌        | Additional component options               |
+| activeQuery | `Record<string, any>` | ❌        | Initial query parameters for first request |
+| reports     | `ReportsDefinition`   | ✅        | Container for all report definitions       |
+
+#### Options Object
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|print|`boolean`|❌|Enable print functionality for all reports|
+
+## Request Configuration
+
+Defines how data is fetched from backend services or APIs.
+
+### `NdfReportsRequest` Type
+
+```typescript
+type NdfReportsRequest = {
+  pageProvider: string;
+  customUrl?: { url: string; method: 'post' | 'get' };
+  payload?: Record<string, any>;
+  params?: Record<string, any>;
+  headers?: Record<string, any>;
+  transformer?: string;
+};
+```
+
+### Properties
+
+| Property     | Type                                       | Required | Description                                                 |
+| ------------ | ------------------------------------------ | -------- | ----------------------------------------------------------- |
+| pageProvider | `string`                                   | ✅        | Identifier for the data source provider                     |
+| customUrl    | `{ url: string; method: 'post' \| 'get' }` | ❌        | Custom endpoint configuration                               |
+| payload      | `Record<string, any>`                      | ❌        | Request body for POST requests                              |
+| params       | `Record<string, any>`                      | ❌        | Query parameters                                            |
+| headers      | `Record<string, any>`                      | ❌        | HTTP headers                                                |
+| transformer  | `string`                                   | ❌        | Name of registered transformer in `ReportsDataTransformers` |
+
+### Example Usage
+
+```json
+{
+  "request": {
+    "pageProvider": "PP_RPT_Location",
+    "customUrl": {
+      "url": "/custom-search/admin/pp/PP_RPT_Location/execute",
+      "method": "post"
+    },
+    "params": {
+      "pageSize": 100
+    },
+    "headers": {
+      "properties": "*"
+    },
+    "transformer": "locationDataTransform"
+  }
+}
+```
+
+## Filters Configuration
+
+Optional filtering system that allows users to refine report data.
+
+### `NdfReportsFilters` Type
+
+```typescript
+type NdfReportsFilters = {
+  mode: 'payload' | 'params';
+  payload?: Record<string, any>;
+  params?: Record<string, any>;
+  fields: FieldConfigModel[];
+  visible?: boolean;
+  togglePanel?: boolean;
+  reloadStrategy?: 'always' | 'never';
+};
+```
+
+### Properties
+
+| Property       | Type                    | Required | Description                                    |
+| -------------- | ----------------------- | -------- | ---------------------------------------------- |
+| mode           | `'payload' \| 'params'` | ✅        | Where to apply filter values                   |
+| payload        | `Record<string, any>`   | ❌        | Default payload values                         |
+| params         | `Record<string, any>`   | ❌        | Default query parameters                       |
+| fields         | `FieldConfigModel[]`    | ✅        | Filter field configurations                    |
+| visible        | `boolean`               | ❌        | Initial visibility of filter UI                |
+| togglePanel    | `boolean`               | ❌        | Allow users to show/hide filter panel          |
+| reloadStrategy | `'always' \| 'never'`   | ❌        | When to reload field data after filter changes |
+
+### Reload Strategy
+
+|Strategy|Description|
+|---|---|
+|`always`|Reload field data every time filters are applied|
+|`never`|Only reload on programmatic configuration changes|
+
+### Example Usage
+
+```json
+{
+  "filters": {
+    "mode": "payload",
+    "visible": true,
+    "togglePanel": true,
+    "reloadStrategy": "never",
+    "fields": [
+      {
+        "type": "predicate",
+        "config": {
+          "label": "FILTERS.title",
+          "fieldKey": "dc:title",
+          "sendMode": "payload",
+          "valueType": "valueObject",
+          "render": {
+            "type": "input",
+            "options": {
+              "debounceTime": 300
+            }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Report Definitions
+
+### `ReportsDefinition` Type
+
+Container for all report configurations.
+
+```typescript
+type ReportsDefinition = {
+  items: ReportDefinitionModel[];
+};
+```
+
+### `ReportDefinitionModel` Union Type
+
+```typescript
+export type ReportDefinitionModel =
+  | DigitChartDefinition
+  | GraphChartDefinition
+  | DynamicLineChartDefinition  
+  | CustomChartDefinition;      
+```
+
+## Chart Types
+
+### Base Configuration
+
+All chart types extend `BaseReportConfig`:
+
+```typescript
+export interface BaseReportConfig {
+  id: string | number;
+  label: string;
+  mode: ReportMode;
+  navigate?: {
+    enabled?: boolean;
+    route: any[];
+    includeParams?: boolean;
+  };
+  details?: ReportDetailsConfig;
+  layout?: {
+    width?: GridWidth;
+    columnPosition?: GridWidth;
+    height?: number | 'auto';
+    rowPosition?: number | 'auto';
+    styleClass?: string;
+  };
+}
+```
+
+#### Base Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|id|`string \| number`|✅|Unique identifier|
+|label|`string`|✅|Display name (supports i18n keys)|
+|mode|`ReportMode`|✅|Chart type identifier|
+|navigate|`object`|❌|Click navigation configuration|
+|└─ enabled|`boolean`|❌|Enable click-to-navigate|
+|└─ route|`any[]`|✅|Angular route array|
+|└─ includeParams|`boolean`|❌|Include current filters in navigation|
+|details|`ReportDetailsConfig`|❌|Detailed view configuration|
+|layout|`object`|❌|Grid layout configuration|
+|└─ width|`GridWidth`|❌|Column span (1-12 or 'auto')|
+|└─ columnPosition|`GridWidth`|❌|Starting column|
+|└─ height|`number \| 'auto'`|❌|Row span or auto-size|
+|└─ rowPosition|`number \| 'auto'`|❌|Starting row|
+|└─ styleClass|`string`|❌|Custom CSS classes|
+
+### Digit Charts
+
+For displaying key performance indicators (KPIs) as large numbers.
+
+#### `DigitChartDefinition` Type
+
+```typescript
+type DigitChartDefinition = BaseReportConfig & {
+  mode: 'digit';
+  datasource: {
+    propertyPath: string;
+    transformer?: string;
+    bindValue?: string;
+  };
+};
+```
+
+#### Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|mode|`'digit'`|✅|Chart type identifier|
+|datasource|`object`|✅|Data source configuration|
+|└─ propertyPath|`string`|✅|Path to data property in response|
+|└─ transformer|`string`|❌|Transformer name (registered in `ChartDataTransformers`)|
+|└─ bindValue|`string`|❌|Property to extract from data object/array|
+
+#### Example
+
+```json
+{
+  "id": "resultsCount",
+  "label": "REPORTS.resultsCount",
+  "mode": "digit",
+  "datasource": {
+    "propertyPath": "resultsCount"
+  },
+  "layout": {
+    "width": 2,
+    "height": 1
+  }
+}
+```
+
+### Graph Charts
+
+For Chart.js-powered visualizations with full customization support.
+
+#### `GraphChartDefinition` Type
+
+```typescript
+type GraphChartDefinition<TType extends ChartType = ChartType> = BaseReportConfig & {
+  mode: 'graph';
+  datasource: ReportDataSource[];
+  chart: GraphChartOptionsDefinition<TType>;
+  prefix?: string;
+  print?: boolean;
+  typeConfig?: ChartTypeConfig;
+  dialog?: GraphDialogConfig;
+};
+```
+
+#### Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|mode|`'graph'`|✅|Chart type identifier|
+|datasource|`ReportDataSource[]`|✅|Data source configurations|
+|chart|`GraphChartOptionsDefinition<TType>`|✅|Chart.js configuration|
+|prefix|`string`|❌|Translation key prefix|
+|print|`boolean`|❌|Enable print support for this chart|
+|typeConfig|`ChartTypeConfig`|❌|Chart type switching configuration|
+|dialog|`GraphDialogConfig`|❌|Modal dialog configuration|
+
+#### Chart Configuration
+
+```typescript
+type GraphChartOptionsDefinition<TType extends ChartType = ChartType> = {
+  type: TType;
+  options?: CustomChartOptions<TType>;
+  datasets?: Omit<ChartDataset<TType>, 'data'>[];
+  overrides?: ChartOptionsByType;
+  plugins?: string[];
+  colors?: string[];
+  direction?: 'horizontal' | 'vertical';
+};
+```
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|type|`TType`|✅|Chart.js chart type|
+|options|`CustomChartOptions<TType>`|❌|Chart.js options with extensions|
+|datasets|`Omit<ChartDataset<TType>, 'data'>[]`|❌|Dataset configurations|
+|overrides|`ChartOptionsByType`|❌|Type-specific overrides|
+|plugins|`string[]`|❌|Plugin names (must be pre-registered)|
+|colors|`string[]`|❌|Color palette (CSS colors/variables)|
+|direction|`'horizontal' \| 'vertical'`|❌|Chart orientation (bar charts only)|
+
+#### Data Source Configuration
+
+```typescript
+type ReportDataSource = {
+  propertyPath: string;
+  bindLabel?: string;
+  bindValue?: string;
+  dataFormat?: string;
+  transformer?: string;
+};
+```
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|propertyPath|`string`|✅|Path to data in response|
+|bindLabel|`string`|❌|Property for chart labels|
+|bindValue|`string`|❌|Property for chart values|
+|dataFormat|`string`|❌|Format string for data transformation|
+|transformer|`string`|❌|Transformer name (registered in `ChartDataTransformers`)|
+
+#### Example
+```json
+{
+  "id": "future__generaldocument_secrecyLevel_agg",
+  "label": "REPORTS.gdocSecrecyLevel",
+  "mode": "graph",
+  "print": true,
+  "dialog": {
+    "active": true
+  },
+  "typeConfig": {
+    "enabled": true,
+    "allowedTypes": ["line", "bar", "pie"]
+  },
+  "prefix": "search.buckets.",
+  "details": {
+    "enabled": true,
+    "source": "secrecyLevel_aggDetailsConfig"
+  },
+  "datasource": [
+    {
+      "propertyPath": "aggregations.generaldocument_secrecyLevel_agg.buckets",
+      "transformer": "reduceData"
+    }
+  ],
+  "chart": {
+    "type": "bar",
+    "options": {
+      "indexAxis": "y",
+      "responsive": true,
+      "maintainAspectRatio": false,
+      "scales": {
+        "x": {
+          "ticks": {
+            "stepSize": 1,
+            "color": "var(--chart-ticks-x-color)"
+          },
+          "grid": {
+            "color": "var(--chart-grid-x-color)"
+          }
+        }
+      },
+      "plugins": {
+        "legend": {
+          "display": false
+        }
+      }
+    },
+    "plugins": ["chartDataLabels", "scrollableLegends", "doughnutEmptyState"]
+  }
+}
+
+```
+
+#### Chart Type Configuration
+
+```typescript
+interface ChartTypeConfig {
+  enabled: boolean;
+  allowedTypes?: AllowedChartType[];
+}
+```
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|enabled|`boolean`|✅|Allow users to switch chart types|
+|allowedTypes|`AllowedChartType[]`|❌|Restrict available chart types|
+
+#### Dialog Configuration
+
+```typescript
+type GraphDialogConfig = {
+  active: boolean;
+  panelClass?: string | string[];
+  width?: string;
+  height?: string;
+  minWidth?: number | string;
+  minHeight?: number | string;
+  maxWidth?: number | string;
+  maxHeight?: number | string;
+  position?: DialogPosition;
+};
+```
+
+
+### Graph Charts
+
+
+### Report Details Configuration
+
+Provides detailed tabular views of report data.
+
+#### `ReportDetailsConfig` Type
+
+```typescript
+export type ReportDetailsConfig = {
+  enabled: boolean;
+  source: ReportDetailsKey | ReportConfigOptions;
+};
+```
+
+#### Simple Configuration (String Key)
+
+```typescript
+type ReportDetailsKey = string;
+```
+
+Use a predefined report configuration from the server:
+
+```json
+{
+  "details": {
+    "enabled": true,
+    "source": "DETAIL_REPORT"
+  }
+}
+```
+
+#### Advanced Configuration (Full Options)
+
+```typescript
+export type ReportConfigOptions = {
+  request?: Partial<NdfReportsRequest> & {
+    actions?: {
+      beforeSubmit?: EvaluatedString<'payload'>;
+    };
+  };
+  columns?: TableColumnConfig[];
+  fields?: Record<string, string>;
+  prefix?: string;
+  quickFilters?: string;
+  columnsOptions?: {
+    toggle?: boolean;
+    sortable?: TableSortConfig;
+  };
+  sortingBy?: TableSortOptions;
+  export?: TableExportConfig;
+};
+```
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|request|`Partial<NdfReportsRequest> & ...`|❌|Request configuration with pre-submit actions|
+|columns|`TableColumnConfig[]`|❌|Table column definitions|
+|fields|`Record<string, string>`|❌|Field name mapping (response → display)|
+|prefix|`string`|❌|Translation key prefix|
+|quickFilters|`string`|❌|Quick filter configuration|
+|columnsOptions|`object`|❌|Global column behavior settings|
+|sortingBy|`TableSortOptions`|❌|Default sorting configuration|
+|export|`TableExportConfig`|❌|Export functionality configuration|
+
+#### Complete Example
+
+```json
+{
+  "details": {
+    "enabled": true,
+    "source": {
+      "prefix": "REPORTS.",
+      "quickFilters": "After Archiving",
+      "columnsOptions": {
+        "toggle": true,
+        "sortable": {
+          "enabled": true
+        }
+      },
+      "request": {
+        "headers": {
+          "properties": "*"
+        },
+        "actions": {
+          "beforeSubmit": "payload.userId = 'getCurrentUser'"
+        }
+      },
+      "fields": {
+        "created": "dc:created",  
+		"deptEnName": "padep:englishName",  
+		"deptArName": "padep:arabicName"
+      },
+      "columns": [
+		  {
+		    "name": "Doc_Name",
+		    "prop": "properties.title",
+		    "display": true,
+		    "type": "custom",
+		    "template": "common.components.titleWithIcon",
+		    "sortable": true,
+		    "headerClass": "dc:title",
+		    "defaultVisible": true
+		  },
+		  {
+		    "name": "systemName",
+		    "prop": "properties.systemName",
+		    "display": true,
+		    "type": "custom",
+		    "template": "common.components.systemName",
+		    "translatePrefix": "search.buckets",
+		    "isOriginalKey": true,
+		    "sortable": false,
+		    "headerClass": "recdef:systemName",
+		    "defaultVisible": true
+		  }
+		]
+    }
+  }
+}
+```
+
+
+### Dynamic Line Charts
+
+For time-based data visualization with dynamic grouping capabilities and temporal aggregation features.
+
+#### `DynamicLineChartDefinition` Type
+
+```typescript
+export type DynamicLineChartDefinition = ReportChartConfig & {
+  mode: 'dynamicLine';
+  prefix?: string;
+  colors?: string[];
+  print?: boolean;
+  request: NdfReportsRequest & {
+    actions?: {
+      beforeSubmit?: EvaluatedString<'payload'>;
+    };
+  };
+  datasource: ({ aggregation: string } & ReportDataSource)[];
+  group?: {
+    active: boolean;
+    selected?: TimeGroups;
+  };
+  chart: DynamicLineChartOptionsDefinition;
+};
+```
+
+#### Core Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|mode|`'dynamicLine'`|✅|Chart type identifier|
+|prefix|`string`|❌|Translation key prefix for labels|
+|colors|`string[]`|❌|Custom color palette (CSS colors/variables)|
+|print|`boolean`|❌|Enable print functionality for this chart|
+|request|`NdfReportsRequest & { actions? }`|✅|Enhanced request configuration with pre-submit actions|
+|datasource|`({ aggregation: string } & ReportDataSource)[]`|✅|Data source configurations with aggregation identifiers|
+|group|`TimeGroupConfig`|❌|Time grouping configuration for dynamic period selection|
+|chart|`DynamicLineChartOptionsDefinition`|✅|Chart.js line chart specific configuration|
+
+#### Enhanced Request Configuration
+
+The `request` property extends the base `NdfReportsRequest` with action capabilities:
+
+```typescript
+request: NdfReportsRequest & {
+  actions?: {
+    beforeSubmit?: EvaluatedString<'payload'>;
+  };
+};
+```
+
+**Actions Configuration**
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|beforeSubmit|`EvaluatedString<'payload'>`|❌|Script executed before request submission for dynamic payload modification|
+
+#### Data Source Configuration
+
+Each data source combines standard `ReportDataSource` properties with aggregation-specific configuration:
+
+```typescript
+datasource: ({ aggregation: string } & ReportDataSource)[];
+```
+
+**Enhanced Properties**
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|aggregation|`string`|✅|Aggregation identifier for time-based queries|
+|propertyPath|`string`|✅|Path to data in API response|
+|bindLabel|`string`|❌|Property for chart labels (typically time values)|
+|bindValue|`string`|❌|Property for chart values (typically counts/metrics)|
+|dataFormat|`string`|❌|Format string for data transformation|
+|transformer|`string`|❌|Transformer name for data processing|
+
+#### Time Grouping Configuration
+
+```typescript
+const TIME_GROUPS = {
+  day: 'day',
+  week: 'week',
+  month: 'month',
+  year: 'year'
+} as const;
+
+export type TimeGroups = (typeof TIME_GROUPS)[keyof typeof TIME_GROUPS];
+
+group?: {
+  active: boolean;
+  selected?: TimeGroups;
+};
+```
+
+**Time Group Properties**
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|active|`boolean`|✅|Enable time grouping controls in UI|
+|selected|`TimeGroups`|❌|Default selected time aggregation period|
+
+**Available Time Groups**
+
+|Value|Description|Use Case|
+|---|---|---|
+|`day`|Daily aggregation|Detailed short-term analysis|
+|`week`|Weekly aggregation|Medium-term trend analysis|
+|`month`|Monthly aggregation|Long-term trend visualization|
+|`year`|Yearly aggregation|Historical data overview|
+
+#### Chart Configuration
+
+```typescript
+type DynamicLineChartOptionsDefinition = {
+  type: 'line';
+  options?: CustomChartOptions<'line'>;
+  datasets?: Omit<ChartDataset<'line'>, 'data'>[];
+  plugins?: string[];
+  colors?: string[];
+};
+```
+
+**Chart Properties**
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|type|`'line'`|✅|Fixed chart type for dynamic line charts|
+|options|`CustomChartOptions<'line'>`|❌|Chart.js line chart options with time scale support|
+|datasets|`Omit<ChartDataset<'line'>, 'data'>[]`|❌|Dataset configurations excluding data property|
+|plugins|`string[]`|❌|Plugin names (must be pre-registered in ChartPluginsRegistry)|
+|colors|`string[]`|❌|Color palette override for chart elements|
+
+#### Complete Example
+```json
+{
+  "mode": "dynamicLine",
+  "id": "late_RetentionInfo_activeRetentionExpireDate_agg",
+  "label": "REPORTS.expectedTransferDate",
+  "print": true,
+  "dialog": {
+    "active": true,
+    "width": "80vw",
+    "height": "60vh"
+  },
+  "layout": {
+    "width": 12,
+    "height": 6
+  },
+  "group": {
+    "active": true,
+    "selected": "month"
+  },
+
+  "details": {
+    "enabled": true,
+    "source": "DETAILS_CONFIG"
+  },
+  "request": {
+    "pageProvider": "PP_RPT_Records",
+    "customUrl": {
+      "url": "/custom-search/admin/pp/PP_RPT_Records/execute",
+      "method": "post"
+    }
+  },
+  "datasource": [
+    {
+      "aggregation": "RetentionInfo_activeRetentionExpireDate_agg",
+      "propertyPath": "aggregations.RetentionInfo_activeRetentionExpireDate_agg.buckets",
+      "bindLabel": "key_as_string",
+      "bindValue": "doc_count",
+      "transformer": "timeFormat"
+    }
+  ],
+  "chart": {
+    "type": "line",
+    "options": {
+      "responsive": true,
+      "maintainAspectRatio": false,
+      "layout": {
+        "padding": {
+          "right": 40,
+          "left": 40
+        }
+      }
+    },
+    "plugins": ["singlePointCenter"],
+    "datasets": [
+      {
+        "borderWidth": 2,
+        "borderColor": "var(--chart-color-0)",
+        "pointBorderWidth": 0,
+        "pointBackgroundColor": "var(--chart-color-0)"
+      }
+    ]
+  }
+}
+```
+
+
+### Custom Charts
+
+For highly specialized visualizations using custom Angular components that extend the base report functionality with complete control over rendering and behavior.
+
+#### `CustomChartDefinition` Type
+
+```typescript
+export interface CustomChartDefinition extends BaseReportConfig {
+  mode: 'custom';
+  type: string;
+  prefix?: string;
+  print?: boolean;
+  datasource?: ReportDataSource[];
+  options?: Record<string, any>;
+  dialog?: GraphDialogConfig;
+}
+```
+
+#### Core Properties
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|mode|`'custom'`|✅|Chart type identifier for custom components|
+|type|`string`|✅|Unique identifier for component registration in `CustomReportsRegistry`|
+|prefix|`string`|❌|Translation key prefix for component labels|
+|print|`boolean`|❌|Enable print functionality for this component|
+|datasource|`ReportDataSource[]`|❌|Optional data source configurations for component|
+|options|`Record<string, any>`|❌|Custom configuration object passed to component|
+|dialog|`GraphDialogConfig`|❌|Modal dialog configuration for detailed views|
+
+#### Component Registration
+
+Custom chart components must be registered with the `CustomReportsRegistry` before use:
+
+```typescript
+export interface CustomReportRegistryDefinition {
+  type: string;
+  component: ComponentType<any>;
+  category?: string;
+  name?: string;
+  description?: string;
+}
+```
+
+**Registry Properties**
+
+|Property|Type|Required|Description|
+|---|---|---|---|
+|type|`string`|✅|Unique identifier matching `CustomChartDefinition.type`|
+|component|`ComponentType<any>`|✅|Angular component class extending `BaseCustomReport`|
+|category|`string`|❌|Component categorization for organization|
+|name|`string`|❌|Human-readable component name|
+|description|`string`|❌|Component description and usage information|
+
+#### Base Custom Report Class
+
+All custom chart components must extend `BaseCustomReport`:
+
+```typescript
+abstract class BaseCustomReport extends DestroySubject {
+  abstract print(): void;
+  @Input() direction: Direction = 'rtl';
+  @Input() definition: CustomChartDefinition;
+  @Input() data: ReportResponseModel;
+  @Input() criteria: CriteriaModel;
+  @Input() config : CustomChart ;
+  // ...
+}
+```
+
+**Base Class Properties**
+
+|Property|Type|Description|
+|---|---|---|
+|chart|`Chart`|Chart.js instance when available|
+|direction|`Direction`|Text direction for RTL/LTR support|
+|definition|`CustomChartDefinition`|Complete chart configuration|
+|data|`ReportResponseModel`|Current report data with reactive updates|
+|criteria|`CriteriaModel`|Filter criteria with change notifications|
+|config|`CustomChart`|Component-specific configuration|
+
+**Required Implementation**
+
+|Method|Return Type|Description|
+|---|---|---|
+|print()|`void`|Custom print functionality implementation|
+
+#### Component Implementation Example
+```typescript
+@Component({
+  selector: 'app-capacity-chart',
+  template: `
+    <div class="Heatmap-container" [class.rtl]="direction === 'rtl'">
+      <app-chart
+
+        type="doughnut"
+        [data]="chartData"
+        [options]="options"
+        [responsive]="true"
+        [plugins]="plugins"
+        (onReady)="chartReady($event)"
+      >
+      </app-chart>
+    </div>
+  `,
+})
+export class HeatmapChartComponent
+  extends BaseCustomReport
+  implements OnInit, OnDestroy
+{
+	// Optional: Used to register the component in the system
+	static registerInfo(): CustomReportRegistryDefinition {  
+	  return {  
+	    type: 'heatmap-chart',
+	    component: HeatmapChartComponent,
+	    category: 'visualization',
+	    name: 'Heatmap Chart',
+	    description: 'Advanced heatmap visualization for correlation data'
+	  };  
+	}
+// ... 
+  print(): void {
+    this._chartHelperService.printChart(
+      this.chart.id,
+      this._translateService.instant(this.config.label),
+      this.options,
+      [
+        circleLabel({
+          shadowBlur: 0,
+          font: 'bold 32px sans-serif',
+          value: `15%`,
+        }),
+      ]
+    )
+  }
+}
+```
+
+#### Registration and Configuration
+
+**Step 1: Register Component**
+
+```typescript
+// In your module or service
+constructor(private customReportsRegistry: CustomReportsRegistry) {
+  this.customReportsRegistry.registerComponent({
+    type: 'heatmap-chart',
+	component: HeatmapChartComponent,
+	category: 'visualization',
+	name: 'Heatmap Chart',
+	description: 'Advanced heatmap visualization for correlation data'
+  } // or use HeatmapChartComponent.registerInfo() 
+  );  
+}
+```
+
+**Step 2: Configure in Reports**
+
+```json
+{
+  "id": "correlation-heatmap",
+  "label": "REPORTS.correlationHeatmap",
+  "mode": "custom",
+  "type": "heatmap-chart",
+  "prefix": "HEATMAP.",
+  "print": true,
+  "layout": {
+    "width": 8,
+    "height": 6
+  },
+  "datasource": [
+    {
+      "propertyPath": "aggregations.correlation_matrix.buckets",
+      "transformer": "matrixDataProcessor"
+    }
+  ],
+  "options": {
+    "chartOptions": {
+      "scales": {
+        "x": {
+          "type": 'linear',
+          "position": 'bottom'
+        },
+        "y": {
+          "type": 'linear'
+        }
+      }
+    },
+    "colorScheme": "viridis",
+    "showValues": true,
+    "gridLines": true
+  },
+  "dialog": {
+    "active": true,
+    "width": "90vw",
+    "height": "80vh",
+    "panelClass": "heatmap-dialog"
+  }
+}
+```
+
+#### Development Best Practices
+
+**Memory Management**
+```typescript
+ngOnDestroy() {
+  // Always clean up Chart.js instances
+  if (this.customChart) {
+    this.customChart.destroy();
+  }
+  
+  // Call parent cleanup
+  super.ngOnDestroy();
+}
+```
+
+
+## Related Types Reference
+
+### Core Types
+
+#### `REPORT_MODE` Constants
+
+```typescript
+export const REPORT_MODE = {
+  graph: 'graph',
+  digit: 'digit',
+  dynamicLine: 'dynamicLine',
+  custom: 'custom',
+} as const;
+
+export type ReportMode = (typeof REPORT_MODE)[keyof typeof REPORT_MODE];
+```
+
+#### `GridWidth` Type
+
+```typescript
+export type GridWidth = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 'auto';
+```
+
+#### Chart Types
+
+```typescript
+const CHARTS_TYPES = {
+  verticalBar: 'verticalBar',
+  horizontalBar: 'horizontalBar',
+  doughnut: 'doughnut',
+  line: 'line',
+  pie: 'pie'
+} as const;
+
+type AllowedChartType = (typeof CHARTS_TYPES)[keyof Omit<typeof CHARTS_TYPES, 'line'>];
+```
+
+
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Transformer Not Found
+
+**Error**: `Transformer 'myTransformer' not registered` **Solution**: Register the transformer using the appropriate service method:
+
+```typescript
+// For digit charts
+chartDataTransformers.registerDigitsTransformer('myTransformer', transformFunction);
+
+// For graph charts  
+chartDataTransformers.registerGraphTransformers('myTransformer', transformFunction);
+```
+
+#### 2. Plugin Not Available
+
+**Error**: `Plugin with key 'myPlugin' not found.` **Solution**: Register the plugin in `ChartPluginsRegistry` before using:
+
+```typescript
+chartPluginsRegistry.register('myPlugin', myPluginImplementation);
+```
+
+#### 3. Data Path Not Found
+
+**Error**: Chart shows no data **Solution**: Verify the `propertyPath` matches your API response structure:
+
+```typescript
+// If API returns: { data: { aggregation: { total: 1000 } } }
+// Use propertyPath: "data.aggregation.total"
+```
+
+#### 4. Layout Issues
+
+**Problem**: Charts overlapping or not displaying properly **Solution**: Check grid layout configuration:
+
+```json
+{
+  "layout": {
+    "width": 6,        // Must be 1-12
+    "height": "auto",  // Use "auto" for dynamic sizing
+    "columnPosition": 1,
+    "rowPosition": "auto"
+  }
+}
+```