nuxeo-development-framework 0.0.2 → 0.0.3-bos

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

@@ -0,0 +1,1332 @@
+
+ # 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
+- 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;
+  reload?: NdfReportsFiltersReloadConfig;
+};
+```
+
+### 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          |
+| reload      | `NdfReportsFiltersReloadConfig` | ❌        | When to reload field data after filter changes |
+
+### Reload
+```ts
+type NdfReportsFiltersReloadConfig =
+  | { strategy: 'always' }
+  | { strategy: 'never' }
+  | { strategy: 'onChange'; triggerFields: string[] }
+```
+
+| Strategy   | Description                                       |
+| ---------- | ------------------------------------------------- |
+| `always`   | Reload field data every time filters are applied  |
+| `never`    | Only reload on programmatic configuration changes |
+| `onChange` | Reload only when specific fields changed          |
+
+### Example Usage
+
+```json
+{
+  "filters": {
+    "mode": "payload",
+    "visible": true,
+    "togglePanel": true,
+     "reload": {
+    "strategy": "onChange",
+    "triggerFields": ["dc:title", "dc:category"]
+  },
+    "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 Defaults Configuration
+The `ChartDefaultsOptions` type defines optional global defaults applied to all charts in your application. These settings can control fonts, colors, bar dimensions, and globally registered Chart.js plugins. The `CHART_DEFAULTS_OPTIONS` injection token allows you to provide these defaults via Angular’s dependency injection system.
+
+ ```ts
+   type ChartDefaultsOptions = {
+  globalPlugins?: Plugin[];
+  fontFamily?: string;
+  fontSize?: number;
+  color?: string;
+  borderColor?: string;
+  backgroundColor?: string;
+  maxBarThickness?: number;
+  minBarLength?: number;
+};
+
+  const CHART_DEFAULTS_OPTIONS = new InjectionToken<ChartDefaultsOptions>(
+  'CHART_DEFAULTS_OPTIONS'
+);
+```
+
+| Property          | Type       | Required | Description                                                         |
+| ----------------- | ---------- | -------- | ------------------------------------------------------------------- |
+| `globalPlugins`   | `Plugin[]` | ❌        | List of globally applied Chart.js plugins                           |
+| `fontFamily`      | `string`   | ❌        | Default font family for all chart text                              |
+| `fontSize`        | `number`   | ❌        | Default font size for chart labels, titles, and ticks               |
+| `color`           | `string`   | ❌        | Default text color used in chart labels and legends                 |
+| `borderColor`     | `string`   | ❌        | Default border color for bars, lines, and other chart elements      |
+| `backgroundColor` | `string`   | ❌        | Default background color for chart elements                         |
+| `maxBarThickness` | `number`   | ❌        | Maximum thickness (in pixels) for bars in bar charts                |
+| `minBarLength`    | `number`   | ❌        | Minimum pixel length for bars—useful for visibility of small values |
+
+> [!note] Note
+> 💡 Use CHART_DEFAULTS_OPTIONS to configure consistent styling and behavior across all your charts.
+
+#### Example
+```ts
+
+const logPlugin: Plugin = {
+  id: 'logPlugin',
+  beforeDraw: (chart) => {
+    console.log('Rendering chart:', chart.config.type);
+  }
+};
+
+
+const chartDefaults: ChartDefaultsOptions = {
+  fontFamily: 'Arial, sans-serif',
+  fontSize: 12,
+  color: '#333',
+  borderColor: '#ccc',
+  backgroundColor: '#f5f5f5',
+  maxBarThickness: 30,
+  minBarLength: 5,
+  globalPlugins: [logPlugin] // Register the plugin globally
+};
+
+@NgModule({
+  providers: [
+    {
+      provide: CHART_DEFAULTS_OPTIONS,
+      useValue: chartDefaults
+    }
+  ]
+})
+export class AppModule {}
+```
+
+## 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;
+    minContentHeight?: 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                                                      |
+| └─ minContentHeight | `string`              | ❌        | Defines the minimum height of the content area (supports px, rem, etc.) |
+
+### 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';
+  callbacks?: Array<CallbackDefinition>;
+};
+```
+
+| 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)         |
+| callbacks | `Array<CallbackDefinition>`           | ❌        | List of dynamic charts.js callback bindings |
+|           |                                       |          |                                             |
+
+##### CallbackDefinition
+```ts
+type CallbackDefinition = {
+  path: string;                             // Location of the callback in Chart.js options
+  callback: EvaluatedString<'callback'>;    // Function body to be evaluated and attached
+};
+```
+
+| Property   | Type                          | Required | Description                                                                                        |
+| ---------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
+| `path`     | `string`                      | ✅        | Dot-notated path to the Chart.js callback option (e.g., `options.plugins.tooltip.callbacks.label`) |
+| `callback` | `EvaluatedString<'callback'>` | ✅        | A stringified function that is evaluated and assigned at runtime                                   |
+
+#### Example
+```json
+{
+  "chart": {
+    "type": "bar",
+    "direction": "vertical",
+    "plugins": ["scrollableLegends", "doughnutEmptyState"],
+    "callbacks": [
+      {
+        "path": "tooltip.callbacks.label",
+        "callback": "callback=register.get('convertDecimalHoursToString')"
+      },
+      //Example 2
+      {
+        "path": "tooltip.callbacks.label",
+        "callback": "callback= (context) => context.raw"
+      }
+    ]
+  }
+}
+```
+
+#### Data Source Configuration
+
+```typescript
+type ReportDataSource = {
+  propertyPath: string;
+  bindLabel?: {ar:string;en:string};
+  bindValue?: string;
+  dataFormat?: string;
+  transformer?: string;
+};
+```
+
+| Property     | Type        | Required                     | Description                                                                                 |
+| ------------ | ----------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
+| propertyPath | `string`    | ✅                            | Path to data in response                                                                    |
+| bindLabel    | `bindLabel` | `{ ar: string; en: string }` | Localized property mappings defining bucket properties containing Arabic and English 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",
+      "bindLabel": {
+		  "ar": "fetchedKey.properties.arTitle",
+		  "en": "fetchedKey.properties.enTitle"
+		},
+    }
+  ],
+  "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",
+		    "isOrginalKey": 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'
+        }
+      }
+    },
+    "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"
+  }
+}
+```