@eqproject/eqp-dynamic-module 2.10.100 → 2.10.102

package/README.md

@@ -1,880 +1,891 @@
-# @eqproject/eqp-dynamic-module
-
-[![npm version](https://img.shields.io/npm/v/@eqproject/eqp-dynamic-module.svg)](https://www.npmjs.com/package/@eqproject/eqp-dynamic-module)
-[![Angular](https://img.shields.io/badge/Angular-15-red.svg)](https://angular.io/)
-
-> Libreria Angular 15 per la creazione, visualizzazione e gestione di form dinamiche con configuratore no-code.  
-> Angular 15 library for building, rendering and managing dynamic forms with a no-code configurator.
-
-📖 **[Guida utente / User Guide →](./USERGUIDE.md)**
-
----
-
-## Changelog
-
-### v2.10.100
-- **Cleanup — rimossi import morti di `@eqproject/eqp-datetimepicker` e `@eqproject/eqp-img-drawing`:** entrambi erano registrati nell'`NgModule` (`EqpDatetimepickerModule`, `EqpImgDrawingModule`) e in `trigger-creator.component.ts` (`PickerModeEnum`) ma non più usati da nessun template — sostituiti internamente da tempo da `tmw-datetimepicker` (campo Data) e da `tmw-image-drawer`/`tmw-image-marker` (campo Immagine con markers). Nessun impatto funzionale: build verificata anche con i due pacchetti fisicamente assenti da `node_modules`, per provare che non fossero più necessari. Chi consuma questa libreria non deve più installare `@eqproject/eqp-datetimepicker` né `@eqproject/eqp-img-drawing`.
-- **Cleanup — removed dead imports of `@eqproject/eqp-datetimepicker` and `@eqproject/eqp-img-drawing`:** both were registered in the `NgModule` (`EqpDatetimepickerModule`, `EqpImgDrawingModule`) and in `trigger-creator.component.ts` (`PickerModeEnum`) but no longer used by any template — internally superseded a while ago by `tmw-datetimepicker` (Date field) and `tmw-image-drawer`/`tmw-image-marker` (Image with markers field). No functional impact: build verified even with both packages physically absent from `node_modules`, to prove they were no longer required. Consumers of this library no longer need to install `@eqproject/eqp-datetimepicker` or `@eqproject/eqp-img-drawing`.
-
-### v2.10.99
-- **Bugfix configurator — immagine persa su campo `Immagine`/`Immagine con markers`:** `catchButtonImageChange` e `catchButtonImageWithMarkersChange` in `add-form-field` leggevano l'indice sbagliato (`attachments[1]`) dell'array emesso da `eqp-attachments`. Al primo caricamento di un'immagine su un campo nuovo l'array ha un solo elemento, quindi `field.DynAttachment` veniva sovrascritto con `undefined`: l'immagine spariva riaprendo la modale di modifica campo e non compariva mai in anteprima. Corretto leggendo `attachments[attachments.length - 1]`.
-- **Bugfix configurator — image lost on `Image`/`Image with markers` field:** `catchButtonImageChange` and `catchButtonImageWithMarkersChange` in `add-form-field` were reading the wrong index (`attachments[1]`) from the array emitted by `eqp-attachments`. On the first image upload to a new field the array has only one element, so `field.DynAttachment` was overwritten with `undefined`: the image disappeared when reopening the field edit dialog and never showed up in the preview. Fixed to read `attachments[attachments.length - 1]`.
-
-### v2.10.87
-- **Bugfix configurator — sezione "Generale" assente per 5 tipi di campo:** durante il lavoro di potenziamento grafico (v2.10.68–v2.10.70), i tipi `ActionButtonField`, `ImageField`, `ImageWithMarkersField`, `ListValueField` e `ImageSelectorField` avevano ricevuto la sezione "Grafica" nel tab "Stile Compilazione" del configuratore, ma la sezione "Generale" (Larghezza campo, Visibile, VisibleIf, Tooltip, Tipo di invisibilità, Mantieni il valore) era stata rimossa per errore. Ripristinata per tutti e 5 i tipi.
-- **Bugfix configurator — "Generale" section missing for 5 field types:** during the graphical enhancement work (v2.10.68–v2.10.70), `ActionButtonField`, `ImageField`, `ImageWithMarkersField`, `ListValueField` and `ImageSelectorField` received the "Grafica" section in the configurator's "Stile Compilazione" tab, but the "Generale" section (field width, visibility, VisibleIf, tooltip, invisibility type, maintain value) was accidentally removed. Restored for all 5 field types.
-
-### v2.10.86
-- **Bugfix loop infinito `ListValueField`:** `FormControl.setValue()` notificava il callback `_onChange` del `NgModel` registrato tramite `[formControlName]` sul `mat-checkbox`, causando `ngModelChange` → `updateSelected()` → `setFormControlValue()` in ricorsione infinita. Aggiunto `{ emitModelToViewChange: false }` a `setFormControlValue()` per interrompere il ciclo. Fix correlati: `updateSelected()` ora restituisce `null` (non `[]`) per campi single-choice senza selezione, evitando instabilità Angular CD da `[] !== []`; `resetArrayData()` chiama `updateSelected(false)` per non emettere `recordChange` durante il rebuild delle opzioni; `updateField()` distingue formula-per-valore da formula-per-opzioni nei campi `DataGetterType=Formula`.
-- **Bugfix loop infinito `onRecordChange`:** aggiunta guardia di rientranza `_recordChanging` con `try/finally` in `add-form-record.onRecordChange()` per prevenire ricorsione da campi formula concatenati (es. campo numerico → campo elenco valorizzato dalla formula del primo).
-- **Bugfix loop in anteprima — `DynAttachment.ButtonKey` null:** nei template `image-field-template` e `image-with-markers-field-template`, la valutazione di `field.DynAttachment.ButtonKey` in `*ngIf` lanciava eccezione quando `DynAttachment` era `null` (campo senza immagine caricata), innescando un loop di Angular CD. Sostituito con `field.DynAttachment?.ButtonKey`.
-- **Fix posizione dialog DataGetter:** la modale del Query Editor aperta con "Modifica" nel configuratore compariva a metà pagina. Aggiunti `position: { top: '20px' }` e `maxHeight: '90vh'` per allinearla al comportamento di tutte le altre dialog.
-- **Bugfix infinite loop `ListValueField`:** `FormControl.setValue()` was notifying the `_onChange` callback of the `NgModel` registered via `[formControlName]` on `mat-checkbox`, causing `ngModelChange` → `updateSelected()` → `setFormControlValue()` in infinite recursion. Added `{ emitModelToViewChange: false }` to `setFormControlValue()` to break the cycle. Related fixes: `updateSelected()` now returns `null` (not `[]`) for single-choice fields with no selection, preventing Angular CD instability from `[] !== []`; `resetArrayData()` calls `updateSelected(false)` to avoid emitting `recordChange` during option rebuild; `updateField()` now distinguishes formula-for-value from formula-for-options in `DataGetterType=Formula` fields.
-- **Bugfix infinite loop `onRecordChange`:** added `_recordChanging` re-entrancy guard with `try/finally` in `add-form-record.onRecordChange()` to prevent recursion from chained formula fields (e.g. numeric field → list field driven by the first field's formula).
-- **Bugfix preview loop — `DynAttachment.ButtonKey` null:** in `image-field-template` and `image-with-markers-field-template`, evaluating `field.DynAttachment.ButtonKey` in `*ngIf` threw an exception when `DynAttachment` was `null` (field with no image loaded), triggering an Angular CD loop. Replaced with `field.DynAttachment?.ButtonKey`.
-- **Fix DataGetter dialog position:** the Query Editor modal opened via "Modifica" in the configurator was appearing at mid-page. Added `position: { top: '20px' }` and `maxHeight: '90vh'` to align it with all other dialogs.
-
-### v2.10.85
-- **Bugfix loop infinito (approccio corretto):** il loop di v2.10.84 era asincrono: `setValue` chiama `writeValue` sui ControlValueAccessor di Angular Material che emettono eventi nel tick successivo, quando la guardia di rientranza era già rilasciata. Soluzione definitiva: il validator `required` ora legge direttamente da `record[field.Name]` tramite closure (anziché da `control.value`); in `onRecordChange()` viene chiamato `updateValueAndValidity({ emitEvent: false })` — che ri-esegue i validator senza invocare `writeValue` — eliminando alla radice ogni possibilità di cascade.
-- **Bugfix infinite loop (correct approach):** the v2.10.84 loop was asynchronous: `setValue` calls `writeValue` on Angular Material ControlValueAccessors which emit events on the next tick, after the re-entrancy guard was already released. Definitive fix: the `required` validator now reads directly from `record[field.Name]` via closure (instead of `control.value`); `onRecordChange()` calls `updateValueAndValidity({ emitEvent: false })` — which re-runs validators without invoking `writeValue` — eliminating any cascade at the root.
-
-### v2.10.84
-- **Bugfix loop infinito `onRecordChange`:** la sincronizzazione dei `FormControl` introdotta in v2.10.83 causava un loop: `setValue` invoca `writeValue` sui ControlValueAccessor (es. `mat-datepicker`), che emettono `(dateChange)/(ngModelChange)` → `recordChange` → `onRecordChange` di nuovo, all'infinito. Aggiunta una guardia di rientranza (`_isInRecordChange`) con `try/finally` che interrompe il ciclo. La sincronizzazione dei FormControl resta attiva e la validazione required funziona correttamente.
-- **Bugfix infinite loop `onRecordChange`:** the FormControl sync introduced in v2.10.83 caused an infinite loop: `setValue` calls `writeValue` on ControlValueAccessors (e.g. `mat-datepicker`), which emit `(dateChange)/(ngModelChange)` → `recordChange` → `onRecordChange` again, endlessly. Added a re-entrancy guard (`_isInRecordChange`) with `try/finally` that breaks the cycle. FormControl sync remains active and required validation works correctly.
-
-### v2.10.83
-- **Bugfix validazione form — campi obbligatori valorizzati via formula/ActionButton:** quando un campo con `required` veniva impostato tramite formula o ActionButton, il valore compariva visivamente ma il `FormControl` Angular rimaneva non aggiornato, lasciando il form invalido finché l'utente non interagiva manualmente col campo. Ora `onRecordChange()` risincronizza tutti i `FormControl` dal record dopo ogni aggiornamento formula, rendendo la validazione coerente con il valore visualizzato.
-- **Bugfix form validation — required fields set via formula/ActionButton:** when a required field was populated by a formula or ActionButton, the value appeared visually but the Angular `FormControl` was never updated, keeping the form invalid until the user manually interacted with the field. `onRecordChange()` now re-syncs all `FormControl` values from the record after every formula update, making validation consistent with the displayed value.
-
-### v2.10.81
-- **Bugfix configurator — `DataGetter` null dopo decode Base64:** quando il campo `DataGetterValueBase64String` decodifica in un JSON con `DataGetter: null`, viene ora creato un oggetto `DataGetter` vuoto anziché proseguire con `null`, evitando errori a runtime nel configuratore.
-- **Bugfix `add-form-record` — `actionButtons` null:** se l'input `actionButtons` arriva `null` al componente, viene ora inizializzato a un array vuoto prima del filtraggio, prevenendo un'eccezione al caricamento del record.
-- **Bugfix configurator — `DataGetter` null after Base64 decode:** when `DataGetterValueBase64String` decodes to a JSON with `DataGetter: null`, a new empty `DataGetter` object is now created instead of proceeding with `null`, preventing runtime errors in the configurator.
-- **Bugfix `add-form-record` — `actionButtons` null:** if the `actionButtons` input arrives as `null`, it is now initialized to an empty array before filtering, preventing an exception on record load.
-
-### v2.10.79
-- **DataGetter V2 — selezione automatica colonna singola:** quando il flusso V2 genera una sola `columnKey`, essa viene assegnata automaticamente a `DataGetterColumnForce` senza che l'utente debba selezionarla manualmente dalla dropdown.
-- **DataGetter V2 — single column auto-selection:** when the V2 flow produces exactly one `columnKey`, it is automatically assigned to `DataGetterColumnForce` without requiring manual selection from the dropdown.
-
-### v2.10.77
-- **DataGetter V2 — `DataGetterColumnForce` come stringa:** `onAiDataGetterOut` ora salva `DataGetterColumnForce` come stringa chiave (non come oggetto), allineandosi al formato atteso da `eqp-select`. Il valore pre-selezionato nella dropdown compare automaticamente dopo il flusso AI.
-- **DataGetter V2 — `DataGetterColumnForce` as string:** `onAiDataGetterOut` now stores `DataGetterColumnForce` as a key string (not as an object), matching the format expected by `eqp-select`. The pre-selected value in the dropdown appears automatically after the AI flow.
-
-### v2.10.76
-- **DataGetter V2 — `createColumnKeys` retrocompatibile:** `add-form-field` ora rileva `DataGetterCodeVersion=2` e legge `selectedFields` da `queryCommandDatabaseConfiguration.selectedFields` invece che dal livello radice; fallback su `PropertyName` se `CurrentTranslate` è assente.
-- **DataGetter V2 — `createColumnKeys` backward-compatible:** `add-form-field` now detects `DataGetterCodeVersion=2` and reads `selectedFields` from `queryCommandDatabaseConfiguration.selectedFields` instead of the root level; falls back to `PropertyName` when `CurrentTranslate` is missing.
-
-### v2.10.74 / v2.10.75
-- **DataGetter AI — nuova modalità "Da database" (DataGetterType=3):** aggiunto campo `DataGetterSpeechText` nel modello `DataGetter`. Il configurator AI può creare campi con recupero dati da database impostando un prompt testuale: al caricamento del form, il componente QueryEditor esterno viene invocato silenziosamente, elabora il prompt via AI e popola automaticamente `DataGetterValue`, `DataGetterCardinality=1`, `DataGetterHasResetButton=true` e `DataGetterColumnForce` (se il risultato ha un solo campo selezionato).
-- **DataGetterCodeVersion V2 — retrocompatibilità in lettura:** il `DbgetterComponent` rileva automaticamente i campi con `DataGetterCodeVersion=2` (formato Omnisearch AI) ed esegue un unwrap trasparente della struttura `queryCommandDatabaseConfiguration` al formato V1, senza impatto sui campi legacy. Il `DataGetterCodeVersion=2` viene propagato al componente QueryEditor esterno tramite `config.DataGetterCodeVersion` per consentire al client ospitante di attivare il flusso V2 in lettura.
-- **AI DataGetter — new "Da database" mode (DataGetterType=3):** added `DataGetterSpeechText` field to the `DataGetter` model. The AI configurator can create database-getter fields with a natural-language prompt: on form load, the external QueryEditor component is invoked silently, processes the prompt via AI and automatically populates `DataGetterValue`, `DataGetterCardinality=1`, `DataGetterHasResetButton=true` and `DataGetterColumnForce` (if a single output field is returned).
-- **DataGetterCodeVersion V2 — backward-compatible read flow:** `DbgetterComponent` now auto-detects fields with `DataGetterCodeVersion=2` (Omnisearch AI format) and transparently unwraps the `queryCommandDatabaseConfiguration` structure to the V1 format, with zero impact on legacy fields. `DataGetterCodeVersion=2` is forwarded to the external QueryEditor component via `config.DataGetterCodeVersion` to enable the V2 read flow on the host application side.
-
-### v2.10.70
-- **Theming configurator — nuovi input:** aggiunto `[configuratorThemeCss]` che accetta direttamente il testo di un file CSS con le dichiarazioni delle variabili `--conf-*`. Permette di portare il tema dall'esterno come file statico senza hardcodare valori TypeScript. Se entrambi gli input sono presenti, `configuratorTheme` sovrascrive `configuratorThemeCss` per le chiavi in conflitto.
-- **Theming configurator — nuove variabili CSS:** `--conf-stepper-header-bg` (sfondo zona step superiore), `--conf-stepper-content-bg` (sfondo zona inferiore), `--conf-step-icon-edit-bg` (sfondo pallini step completati), `--conf-hint-btn-bg` / `--conf-hint-btn-hover-bg` (bottone suggerimento rapido), `--conf-btn-color` (colore testo bottoni con sfondo gradiente).
-- **Theming configurator — forzatura `!important`:** tutti i valori iniettati tramite tema esterno sono ora applicati con `!important`, rendendo il sistema di theming l'unico canale valido per sovrascrivere i colori.
-- **Theming configurator — `--conf-btn-color`:** il colore del testo dei bottoni attivi (sfondo gradiente) è ora templatizzabile e forzato con `!important` per resistere a override CSS provenienti dall'applicazione ospitante.
-- **New theming input:** added `[configuratorThemeCss]` accepting a CSS text string with `--conf-*` variable declarations. Enables external theme files without TypeScript hardcoding. When both inputs are present, `configuratorTheme` overrides `configuratorThemeCss` for conflicting keys.
-- **New CSS variables:** `--conf-stepper-header-bg`, `--conf-stepper-content-bg`, `--conf-step-icon-edit-bg`, `--conf-hint-btn-bg`, `--conf-hint-btn-hover-bg`, `--conf-btn-color`.
-- **`!important` enforcement:** all externally-injected theme values are now set with `!important`, making the theming system the sole valid override channel.
-
-### v2.10.65
-- **TextField — icona opzionale:** aggiunta la possibilità di associare un'icona Material Icons al campo di testo. Le nuove proprietà `IconName` (stringa) e `IconPosition` (enum: `1`=Sinistra/prefix, `2`=Destra/suffix) sono opzionali e retrocompatibili (null sui form esistenti). Configurabili nel builder tramite il toggle "Icona" nella sezione Specifiche del campo.
-- **TextField — optional icon:** added support for a Material Icons icon on text fields. New properties `IconName` (string) and `IconPosition` (enum: `1`=Left/prefix, `2`=Right/suffix) are optional and backward-compatible (null on existing forms). Configurable in the builder via the "Icona" toggle in the field's Specifiche section.
-
-### v2.10.64
-- **Bugfix configurator:** se il campo `Code` del form risulta `null` al momento del salvataggio (scenario: form creato con AI senza salvataggio intermedio), ora viene generato automaticamente da `Name` prima dell'invio al server.
-
-### v2.10.63
-- README riscritto in formato bilingue (italiano completo + inglese completo).
-- Aggiunto `USERGUIDE.md` con guida pratica per scenari d'uso comuni e sezione prompt AI di esempio.
-- `USERGUIDE.md` incluso nel pacchetto npm tramite `ng-package.json` assets.
-
-### v2.10.62
-- Migrazione da `tmw-picker` 1.0.x a 1.1.0: NgModule → standalone components, moment.js → Luxon, aggiornamento di tutti i token formato data (`DD/MM/YYYY` → `dd/MM/yyyy`).
-- Rimossi input inutilizzati: `answerToDuplicateId` da `eqp-dynamic-module`, `ProjectName` da `eqp-dynamic-module-configurator`.
-- Documentazione NPM riscritta completamente (bilingue IT/EN).
-
-### v2.10.60
-- Aggiornamenti interni e correzioni bug.
-
----
-
-## Versione italiana
-
-- [Panoramica](#panoramica)
-- [Prerequisiti](#prerequisiti)
-- [Installazione](#installazione)
-- [Configurazione del modulo](#configurazione-del-modulo)
-- [Componenti](#componenti)
-  - [eqp-dynamic-module — Visualizzatore form](#eqp-dynamic-module--visualizzatore-form)
-  - [eqp-dynamic-module-configurator — Builder form](#eqp-dynamic-module-configurator--builder-form)
-- [Modelli di configurazione](#modelli-di-configurazione)
-- [Modalità di visualizzazione](#modalità-di-visualizzazione)
-- [Configurazione endpoint](#configurazione-endpoint)
-- [Modelli dati](#modelli-dati)
-- [Tipi di campo](#tipi-di-campo)
-
----
-
-### Panoramica
-
-`@eqproject/eqp-dynamic-module` espone **due componenti pubblici**:
-
-| Componente | Scopo |
-|-----------|-------|
-| `<eqp-dynamic-module>` | Visualizzatore, compilatore, lista, filtro e grafici a runtime |
-| `<eqp-dynamic-module-configurator>` | Builder no-code per creare e modificare le definizioni form |
-
-Le form sono strutture JSON salvate lato server e recuperate a runtime. La libreria gestisce rendering, validazione, recupero dati, operazioni CRUD e funzionalità avanzate come formule, trigger, action button e speech-to-text.
-
----
-
-### Prerequisiti
-
-```bash
-npm install @angular/cdk@^15.1.2 @angular/material@^15.1.2 @angular/material-luxon-adapter@^15.2.9 --legacy-peer-deps
-npm install @angular-material-components/datetime-picker@^15.0.0 @angular-material-components/moment-adapter@^15.0.0 --legacy-peer-deps
-npm install moment@^2.29.4 sweetalert2@^11.4.24 --legacy-peer-deps
-```
-
-> Tutti i comandi `npm install` per questa libreria richiedono il flag `--legacy-peer-deps`.
-
----
-
-### Installazione
-
-```bash
-npm install @eqproject/eqp-dynamic-module --legacy-peer-deps
-```
-
----
-
-### Configurazione del modulo
-
-```typescript
-import { EqpDynamicModuleModule } from '@eqproject/eqp-dynamic-module';
-
-@NgModule({
-  imports: [
-    EqpDynamicModuleModule
-  ]
-})
-export class AppModule {}
-```
-
-In `angular.json`, aggiungi il tema Material agli stili:
-
-```json
-"styles": [
-  "node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
-  "src/styles.css"
-]
-```
-
----
-
-### Componenti
-
-#### `eqp-dynamic-module` — Visualizzatore form
-
-Visualizza una form dinamica in una delle [modalità disponibili](#modalità-di-visualizzazione).
-
-**Utilizzo base**
-
-```typescript
-import { DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
-
-generalConfig = new DynamicModuleGeneralConfig(
-  'https://tua-api.esempio.it/api',
-  this.userToken,
-  this.context,
-  null
-);
-```
-
-```html
-<eqp-dynamic-module
-  [configurations]="generalConfig"
-  [formID]="'id-del-form'"
-  [starterViewMode]="DynamicModuleViewModeEnum.LIST"
-  [userID]="currentUser.id"
-  (saveRecord)="onSalvataggio($event)"
-  (afterSaveRecord)="dopoSalvataggio($event)">
-</eqp-dynamic-module>
-```
-
-**Input**
-
-| Input | Tipo | Default | Descrizione |
-|-------|------|---------|-------------|
-| `configurations` | `DynamicModuleGeneralConfig` | — | **Obbligatorio.** Configurazione connessione server. |
-| `formID` | `string` | — | **Obbligatorio.** ID del form da visualizzare. |
-| `starterViewMode` | `DynamicModuleViewModeEnum` | `LIST` | Modalità iniziale. |
-| `userID` | `string` | `"0"` | ID utente per il salvataggio record. |
-| `orgaID` | `string` | `"0"` | ID organizzazione. |
-| `showTitle` | `boolean` | `true` | Mostra/nasconde il nome del form. |
-| `showBackButton` | `boolean` | `true` | Mostra/nasconde il pulsante indietro. |
-| `showSaveButton` | `boolean` | `true` | Mostra/nasconde il pulsante salva. |
-| `values` | `Record[]` | `null` | Record pre-caricati per la modalità LIST. |
-| `FormJSON` | `string` | `""` | JSON del form per la modalità REPAIR. |
-| `formulaObject` | `any` | `{}` | Oggetto contesto per le formule (es. `{ role, user }`). |
-| `selectedRecord` | `Record \| string` | `null` | Record pre-selezionato (oggetto o ID). |
-| `externalButtons` | `RecordButton[]` | `[]` | Pulsanti extra nel menu azioni record. |
-| `actionButtons` | `ActionButton[]` | `[]` | Pulsanti azione per i campi di tipo `Bottone`. |
-| `defaultListActions` | `DynamicModuleListFormRecordActionsDefault` | tutti `true` | Azioni default lista: add, view, edit, duplicate, delete, graphs. |
-| `listViewRecordTitle` | `string[]` | `[]` | Chiavi dei campi che compongono il titolo accordion. |
-| `defaultListViewFunction` | `Function` | `null` | Funzione custom al caricamento della lista. |
-| `onSaveBackToList` | `boolean` | `false` | Torna alla LIST dopo il salvataggio. |
-| `onBackTo` | `DynamicModuleViewModeEnum` | `null` | Modalità di destinazione del pulsante indietro. |
-| `numberOfColumns` | `number` | `3` | Numero di colonne del layout. |
-| `showHiddenFields` | `boolean` | `true` | Mostra/nasconde i campi marcati come nascosti. |
-| `filterResultViewMode` | `DynamicModuleFilterResultViewModeEnum` | `INTERNAL_EQPTABLE` | Modalità visualizzazione risultati filtro. |
-| `additionalParams` | `any` | `null` | Parametri extra per le chiamate filtro server. |
-| `additionalInfo` | `any` | `null` | Dati extra per operazioni client-side. |
-| `prefilterParams` | `any` | `null` | Parametri pre-filtro. |
-| `updateInfo` | `any` | `null` | Dati per aggiornare i valori delle risposte. |
-| `contestualizationParams` | `any` | `null` | Parametri di contestualizzazione della lista risultati. |
-| `showNewSearchButton` | `boolean` | `true` | Mostra/nasconde il pulsante "nuova ricerca". |
-| `highlightFilter` | `any` | — | Configurazione evidenziazione righe/campi. |
-| `isDraggableListView` | `boolean` | `true` | Abilita drag-and-drop nella lista. |
-| `Statistic` | `FilterStatistic` | `null` | Configurazione statistiche e filtri. |
-| `QueryEditorComponent` | `any` | — | Componente query editor custom per i lookup. |
-| `debugMode` | `boolean` | `false` | Abilita log dettagliati in console. |
-
-**Output**
-
-| Output | Payload | Descrizione |
-|--------|---------|-------------|
-| `(saveRecord)` | `Record` | Emesso al salvataggio **senza** endpoint configurato. |
-| `(afterSaveRecord)` | `Record` | Emesso dopo la chiamata server di salvataggio. |
-| `(deleteRecord)` | `Record` | Emesso all'eliminazione **senza** endpoint configurato. |
-| `(afterDeleteRecord)` | `Record` | Emesso dopo la chiamata server di eliminazione. |
-| `(SaveJSON)` | `string` | Emesso all'esportazione del JSON del form. |
-| `(afterFilter)` | `DynRecord[]` | Emesso dopo l'applicazione di un filtro. |
-| `(dragStarted)` | `Record` | Emesso all'inizio di un drag. |
-| `(dragReleased)` | `void` | Emesso al rilascio del drag. |
-| `(clickDragIndicator)` | `Record` | Emesso al click sull'icona drag. |
-| `(out)` | `eventOut` | Output generico per comunicazione esterna. |
-| `(fireTrigger)` | `FireTrigger` | Emesso quando scatta un trigger. |
-| `(afterOutputExternalFilters)` | `FilterStatistic` | Emesso dopo filtri esterni applicati. |
-
----
-
-#### `eqp-dynamic-module-configurator` — Builder form
-
-Designer no-code per creare e modificare definizioni form.
-
-**Modalità d'uso**
-
-```typescript
-// Nuovo form
-const specific = new DynamicModuleConfiguratorSpecificConfig();
-specific.UserID = this.currentUser.id;
-specific.orgaID = this.currentOrga.id;
-const general = new DynamicModuleGeneralConfig(this.baseServerUrl, this.userToken, this.context, null);
-this.config = new DynamicModuleConfiguratorConfig(general, specific);
-```
-
-```html
-<!-- Nuovo form -->
-<eqp-dynamic-module-configurator
-  *ngIf="config"
-  [configurations]="config"
-  (saveFormEvent)="onSalvaForm($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Modifica form esistente -->
-<eqp-dynamic-module-configurator
-  *ngIf="config"
-  [configurations]="config"
-  [formID]="formID"
-  (saveFormEvent)="onSalvaForm($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Esportazione -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [formID]="formID"
-  [viewMode]="'Export'"
-  (saveFormEvent)="onSalvaForm($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Importazione da JSON -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [formID]="null"
-  [viewMode]="'Export'"
-  (saveFormEvent)="onSalvaForm($event)">
-</eqp-dynamic-module-configurator>
-```
-
-**Input**
-
-| Input | Tipo | Default | Descrizione |
-|-------|------|---------|-------------|
-| `configurations` | `DynamicModuleConfiguratorConfig` | — | **Obbligatorio.** Contenitore configurazione. |
-| `formID` | `string` | `null` | ID del form da modificare. `null` crea un nuovo form. |
-| `viewMode` | `string` | `"addOrEdit"` | `"addOrEdit"` per creare/modificare, `"Export"` per esportare/importare. |
-| `fieldsExtraConfig` | `FieldExtraConfig[]` | — | Configurazione extra per campi specifici. |
-| `triggers` | `any` | — | Definizioni trigger disponibili nell'editor. |
-| `actionButtons` | `any` | — | Definizioni action button disponibili. |
-| `contestualization` | `Contestualization[]` | — | Opzioni di contestualizzazione per lookup e filtri. |
-| `formulaObject` | `any` | — | Contesto per l'anteprima delle formule. |
-| `QueryEditorComponent` | `DynamicLoaderDirectiveData` | — | Componente query editor custom. |
-| `debugMode` | `boolean` | `false` | Abilita log dettagliati. |
-| `configuratorTheme` | `Record<string, string> \| null` | `null` | Override delle variabili CSS del tema tramite oggetto TypeScript. |
-| `configuratorThemeCss` | `string \| null` | `null` | Override delle variabili CSS del tema tramite stringa CSS (es. contenuto di un file `.css`). |
-
-**Output**
-
-| Output | Payload | Descrizione |
-|--------|---------|-------------|
-| `(saveFormEvent)` | `Form` | Emesso al salvataggio **senza** endpoint configurato. |
-| `(afterSaveFormEvent)` | `Form` | Emesso dopo la chiamata server di salvataggio. |
-| `(out)` | `eventOut` | Output generico per comunicazione esterna. |
-| `(fireTrigger)` | `FireTrigger` | Emesso quando scatta un trigger. |
-
-**Theming**
-
-Il configurator espone un sistema di temi basato su CSS custom properties. Tutti i valori iniettati tramite tema sono applicati con `!important` e non possono essere sovrascritti dall'esterno se non attraverso questi input.
-
-```html
-<!-- Opzione A: oggetto TypeScript -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [configuratorTheme]="{ '--conf-gradient': 'linear-gradient(to right, #1565c0, #0288d1)', '--conf-bg-page': '#f0f6fb' }">
-</eqp-dynamic-module-configurator>
-
-<!-- Opzione B: file CSS caricato come stringa -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [configuratorThemeCss]="themeCssString">
-</eqp-dynamic-module-configurator>
-```
-
-Formato del file CSS per `configuratorThemeCss` (nessun selettore richiesto):
-
-```css
---conf-gradient:           linear-gradient(to right, #1565c0, #0288d1);
---conf-bg-page:            #f0f6fb;
---conf-btn-color:          #ffffff;
-```
-
-Variabili disponibili:
-
-| Variabile | Default | Descrizione |
-|-----------|---------|-------------|
-| `--conf-gradient` | gradiente viola-blu | Sfondo bottoni e header |
-| `--conf-bg-page` | `#f5f5f5` | Sfondo generale pagina/stepper |
-| `--conf-radius` | `10px` | Border radius bottoni |
-| `--conf-modal-radius` | `12px` | Border radius modali |
-| `--conf-accent` | `#693DDA` | Colore accento (bordi, focus) |
-| `--conf-primary` | `#1E31EB` | Colore primario |
-| `--conf-step-selected` | `#643cda` | Freccia step selezionato |
-| `--conf-step-edit` | `#3034e7` | Freccia step completato |
-| `--conf-stepper-header-bg` | ereditato da `--conf-bg-page` | Sfondo zona superiore (header stepper) |
-| `--conf-stepper-content-bg` | ereditato da `--conf-bg-page` | Sfondo zona inferiore (form e bottoni) |
-| `--conf-step-icon-edit-bg` | ereditato da `--conf-step-edit` | Sfondo pallini step completati |
-| `--conf-btn-color` | `#ffffff` | Colore testo bottoni attivi (sfondo gradiente) |
-| `--conf-hint-btn-bg` | `#2563eb` | Sfondo bottone suggerimento rapido (lampadina) |
-| `--conf-hint-btn-hover-bg` | `#1d4ed8` | Sfondo lampadina al hover |
-| `--conf-table-header-bg` | variabile SCSS | Sfondo header tabella campi |
-| `--conf-search-bg` | variabile SCSS | Sfondo campo di ricerca |
-| `--conf-table-bg` | `#ffffff` | Sfondo righe tabella |
-| `--conf-card-bg` | `#ffffff` | Sfondo card |
-| `--conf-font-family` | `inherit` | Font dell'intero configurator |
-
----
-
-### Modelli di configurazione
-
-#### `DynamicModuleGeneralConfig`
-
-```typescript
-const general = new DynamicModuleGeneralConfig(
-  'https://api.esempio.it/api', // baseServerUrl
-  userToken,                    // token autenticazione
-  context,                      // oggetto Context
-  null                          // EndPointConfiguration (null = usa default)
-);
-```
-
-| Proprietà | Tipo | Descrizione |
-|-----------|------|-------------|
-| `baseServerUrl` | `string` | URL base API. Usato per costruire automaticamente gli endpoint se `endPointConfiguration` è `null`. |
-| `userToken` | `string` | Token di autenticazione inviato con ogni chiamata. |
-| `endPointConfiguration` | `EndPointConfiguration \| null` | Override completo degli endpoint. `null` usa le rotte standard. |
-| `context` | `Context` | Contesto applicativo. |
-
-#### `DynamicModuleListFormRecordActionsDefault`
-
-```typescript
-const actions = new DynamicModuleListFormRecordActionsDefault();
-actions.add       = true;   // Pulsante "Aggiungi" nell'header lista
-actions.view      = true;   // Visualizza record (solo lettura)
-actions.edit      = true;   // Modifica record
-actions.duplicate = false;  // Duplica record
-actions.delete    = true;   // Elimina record
-actions.graphs    = false;  // Grafici record
-```
-
----
-
-### Modalità di visualizzazione
-
-```typescript
-import { DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
-
-enum DynamicModuleViewModeEnum {
-  NONE            = 0,  // Nessuna visualizzazione
-  VIEW            = 1,  // Sola lettura
-  COMPILE         = 2,  // Compilazione / modifica
-  LIST            = 3,  // Lista record
-  REPAIR          = 4,  // Revisione form
-  LISTWIEW        = 5,  // Lista compatta alternativa
-  FILTER          = 6,  // Filtro / ricerca
-  GRAPHS          = 7,  // Statistiche e grafici
-  HLIST           = 8,  // Lista orizzontale
-  EXTERNAL_FILTER = 9   // Filtro guidato dal componente padre
-}
-```
-
----
-
-### Configurazione endpoint
-
-Per default la libreria costruisce tutti gli URL dagli endpoint a partire da `baseServerUrl`. Passa un `EndPointConfiguration` custom per sovrascrivere singole rotte.
-
-```typescript
-import { EndPointConfiguration, EndPointData, RequestMethodEnum, ParamTypeEnum } from '@eqproject/eqp-dynamic-module';
-
-const endPoints = new EndPointConfiguration();
-endPoints.Records.SaveEndPoint = new EndPointData();
-endPoints.Records.SaveEndPoint.Url = 'https://custom-api.esempio.it/records/save';
-endPoints.Records.SaveEndPoint.RequestMethod = RequestMethodEnum.POST;
-endPoints.Records.SaveEndPoint.Params = [{
-  ParamName: 'orgId',
-  ParamValue: this.orgaId,
-  ParamType: ParamTypeEnum['Query param']
-}];
-```
-
-**Endpoint Records disponibili:** `GetWithContextualizationByFormCodeEndPoint`, `GetByFormIDEndPoint`, `GetByFormCodeEndPoint`, `GetAllByEntAndUserIDEndPoint`, `GetByIDEndPoint`, `SaveEndPoint`, `DuplicateEndPoint`, `DeleteEndPoint`, `RepairEndPoint`, `ApplyFilter`, `GetAllAttachmentsEndPoint`.
-
-**Endpoint Forms disponibili:** `GetByIDEndPoint`, `GetAllFormEndPoint`, `GetByIDAndVersionEndPoint`, `SaveEndPoint`, `SaveAttachmentEndPoint`, `ExportByIDEndPoint`, `GetAttachmentWithBases64`, `SpeechToFormEditEndPoint`.
-
----
-
-### Modelli dati
-
-#### `Record`
-
-| Proprietà | Tipo | Descrizione |
-|-----------|------|-------------|
-| `ID` | `string` | Identificatore unico. |
-| `EntID` | `string` | ID del form (entità) di appartenenza. |
-| `Version` | `number` | Versione del form al momento della compilazione. |
-| `userID` | `string` | ID utente che ha creato il record. |
-| `AnswerDate` | `string` | Data di compilazione (ISO). |
-| `HTMLreadableValues` | `string` | Valori in formato HTML leggibile. |
-| `AdditionalParams` | `any` | Parametri aggiuntivi. |
-| `AdditionalInfo` | `any` | Informazioni aggiuntive. |
-
----
-
-### Tipi di campo
-
-| Valore | Chiave | Descrizione |
-|--------|--------|-------------|
-| `1` | `Campo di testo` | Input testo singola riga. |
-| `2` | `Area di testo` | Textarea multiriga. |
-| `3` | `Booleano` | Checkbox / toggle. |
-| `4` | `Data e/ora` | Selettore data e/o ora. |
-| `5` | `Campo numerico` | Input numerico con maschera. |
-| `6` | `Allegato` | Upload file. |
-| `7` | `Immagine` | Upload immagine con crop. |
-| `8` | `Elenco generico` | Dropdown / selezione multipla. |
-| `9` | `Lookup` | Lookup server-side con query configurabile. |
-| `10` | `Form di dettaglio` | Form di dettaglio annidato. |
-| `11` | `Elenco immagini` | Selettore lista immagini. |
-| `12` | `Etichetta` | Solo visualizzazione. |
-| `13` | `Immagine con markers` | Immagine con annotazioni interattive. |
-| `14` | `Bottone` | Campo pulsante azione. |
-
----
-
-## English version
-
-- [Overview](#overview)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-- [Module Setup](#module-setup)
-- [Components](#components)
-  - [eqp-dynamic-module — Form Viewer/Filler](#eqp-dynamic-module--form-viewerfiller)
-  - [eqp-dynamic-module-configurator — Form Builder](#eqp-dynamic-module-configurator--form-builder)
-- [Configuration Models](#configuration-models)
-- [View Modes](#view-modes)
-- [Endpoint Configuration](#endpoint-configuration)
-- [Data Models](#data-models)
-- [Field Types Reference](#field-types-reference)
-
----
-
-### Overview
-
-`@eqproject/eqp-dynamic-module` exposes **two public components**:
-
-| Component | Purpose |
-|-----------|---------|
-| `<eqp-dynamic-module>` | Runtime form viewer, filler, list, filter and graphs |
-| `<eqp-dynamic-module-configurator>` | No-code form builder (create, edit, import, export) |
-
-Forms are defined as JSON structures stored server-side and fetched at runtime. The library handles rendering, validation, data retrieval, CRUD operations and advanced features like formulas, triggers, action buttons and speech-to-text.
-
----
-
-### Prerequisites
-
-```bash
-npm install @angular/cdk@^15.1.2 @angular/material@^15.1.2 @angular/material-luxon-adapter@^15.2.9 --legacy-peer-deps
-npm install @angular-material-components/datetime-picker@^15.0.0 @angular-material-components/moment-adapter@^15.0.0 --legacy-peer-deps
-npm install moment@^2.29.4 sweetalert2@^11.4.24 --legacy-peer-deps
-```
-
-> All `npm install` commands for this library require `--legacy-peer-deps`.
-
----
-
-### Installation
-
-```bash
-npm install @eqproject/eqp-dynamic-module --legacy-peer-deps
-```
-
----
-
-### Module Setup
-
-```typescript
-import { EqpDynamicModuleModule } from '@eqproject/eqp-dynamic-module';
-
-@NgModule({
-  imports: [EqpDynamicModuleModule]
-})
-export class AppModule {}
-```
-
-Add Angular Material theme to `angular.json` styles:
-
-```json
-"styles": [
-  "node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
-  "src/styles.css"
-]
-```
-
----
-
-### Components
-
-#### `eqp-dynamic-module` — Form Viewer/Filler
-
-**Basic usage**
-
-```typescript
-import { DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
-
-generalConfig = new DynamicModuleGeneralConfig(
-  'https://your-api.example.com/api',
-  this.userToken,
-  this.context,
-  null
-);
-```
-
-```html
-<eqp-dynamic-module
-  [configurations]="generalConfig"
-  [formID]="'your-form-id'"
-  [starterViewMode]="DynamicModuleViewModeEnum.LIST"
-  [userID]="currentUser.id"
-  (saveRecord)="onSave($event)"
-  (afterSaveRecord)="onAfterSave($event)">
-</eqp-dynamic-module>
-```
-
-**Inputs**
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `configurations` | `DynamicModuleGeneralConfig` | — | **Required.** Server connection configuration. |
-| `formID` | `string` | — | **Required.** ID of the form to display. |
-| `starterViewMode` | `DynamicModuleViewModeEnum` | `LIST` | Initial view mode. |
-| `userID` | `string` | `"0"` | User ID stamped on saved records. |
-| `orgaID` | `string` | `"0"` | Organization ID. |
-| `showTitle` | `boolean` | `true` | Show/hide the form name. |
-| `showBackButton` | `boolean` | `true` | Show/hide the back button. |
-| `showSaveButton` | `boolean` | `true` | Show/hide the save button. |
-| `values` | `Record[]` | `null` | Pre-loaded records for LIST mode. |
-| `FormJSON` | `string` | `""` | Form JSON string for REPAIR mode. |
-| `formulaObject` | `any` | `{}` | Context object for formula evaluation. |
-| `selectedRecord` | `Record \| string` | `null` | Pre-select a record by object or ID. |
-| `externalButtons` | `RecordButton[]` | `[]` | Extra buttons in the record action menu. |
-| `actionButtons` | `ActionButton[]` | `[]` | Action buttons for `Bottone` field type. |
-| `defaultListActions` | `DynamicModuleListFormRecordActionsDefault` | all `true` | Toggle default list actions. |
-| `listViewRecordTitle` | `string[]` | `[]` | Field keys composing the accordion title. |
-| `defaultListViewFunction` | `Function` | `null` | Custom function called on list load. |
-| `onSaveBackToList` | `boolean` | `false` | Return to LIST after save. |
-| `onBackTo` | `DynamicModuleViewModeEnum` | `null` | View mode for the back button. |
-| `numberOfColumns` | `number` | `3` | Number of layout columns. |
-| `showHiddenFields` | `boolean` | `true` | Show/hide hidden fields. |
-| `filterResultViewMode` | `DynamicModuleFilterResultViewModeEnum` | `INTERNAL_EQPTABLE` | Filter results display mode. |
-| `additionalParams` | `any` | `null` | Extra params for server filter calls. |
-| `additionalInfo` | `any` | `null` | Extra data for client-side operations. |
-| `prefilterParams` | `any` | `null` | Pre-filter parameters. |
-| `updateInfo` | `any` | `null` | Data to update response values after load. |
-| `contestualizationParams` | `any` | `null` | Contextualisation parameters. |
-| `showNewSearchButton` | `boolean` | `true` | Show/hide the new search button. |
-| `highlightFilter` | `any` | — | Row/field highlighting configuration. |
-| `isDraggableListView` | `boolean` | `true` | Enable drag-and-drop in list view. |
-| `Statistic` | `FilterStatistic` | `null` | Statistics and filter configuration. |
-| `QueryEditorComponent` | `any` | — | Custom query editor component for lookups. |
-| `debugMode` | `boolean` | `false` | Enable verbose console logging. |
-
-**Outputs**
-
-| Output | Payload | Description |
-|--------|---------|-------------|
-| `(saveRecord)` | `Record` | Emitted on save when **no** save endpoint is configured. |
-| `(afterSaveRecord)` | `Record` | Emitted after server save call completes. |
-| `(deleteRecord)` | `Record` | Emitted on delete when **no** delete endpoint is configured. |
-| `(afterDeleteRecord)` | `Record` | Emitted after server delete call completes. |
-| `(SaveJSON)` | `string` | Emitted when form JSON is exported. |
-| `(afterFilter)` | `DynRecord[]` | Emitted after filter operation with result set. |
-| `(dragStarted)` | `Record` | Emitted when drag starts. |
-| `(dragReleased)` | `void` | Emitted when drag ends. |
-| `(clickDragIndicator)` | `Record` | Emitted when drag handle is clicked. |
-| `(out)` | `eventOut` | General-purpose external output. |
-| `(fireTrigger)` | `FireTrigger` | Emitted when a trigger fires. |
-| `(afterOutputExternalFilters)` | `FilterStatistic` | Emitted after external filters applied. |
-
----
-
-#### `eqp-dynamic-module-configurator` — Form Builder
-
-**Usage modes**
-
-```html
-<!-- Create new form -->
-<eqp-dynamic-module-configurator
-  *ngIf="config"
-  [configurations]="config"
-  (saveFormEvent)="onFormSaved($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Edit existing form -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [formID]="formID"
-  (saveFormEvent)="onFormSaved($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Export form -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [formID]="formID"
-  [viewMode]="'Export'"
-  (saveFormEvent)="onFormSaved($event)">
-</eqp-dynamic-module-configurator>
-
-<!-- Import from JSON -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [formID]="null"
-  [viewMode]="'Export'"
-  (saveFormEvent)="onFormSaved($event)">
-</eqp-dynamic-module-configurator>
-```
-
-**Inputs**
-
-| Input | Type | Default | Description |
-|-------|------|---------|-------------|
-| `configurations` | `DynamicModuleConfiguratorConfig` | — | **Required.** Configuration container. |
-| `formID` | `string` | `null` | Form ID to edit. `null` creates a new form. |
-| `viewMode` | `string` | `"addOrEdit"` | `"addOrEdit"` or `"Export"`. |
-| `fieldsExtraConfig` | `FieldExtraConfig[]` | — | Extra configuration for specific fields. |
-| `triggers` | `any` | — | Trigger definitions for the editor. |
-| `actionButtons` | `any` | — | Action button definitions. |
-| `contestualization` | `Contestualization[]` | — | Contextualisation options. |
-| `formulaObject` | `any` | — | Context for formula preview. |
-| `QueryEditorComponent` | `DynamicLoaderDirectiveData` | — | Custom query editor component. |
-| `debugMode` | `boolean` | `false` | Enable verbose logging. |
-| `configuratorTheme` | `Record<string, string> \| null` | `null` | CSS variable overrides via TypeScript object. |
-| `configuratorThemeCss` | `string \| null` | `null` | CSS variable overrides via CSS text string (e.g. contents of a `.css` file). |
-
-**Outputs**
-
-| Output | Payload | Description |
-|--------|---------|-------------|
-| `(saveFormEvent)` | `Form` | Emitted on save when **no** save endpoint is configured. |
-| `(afterSaveFormEvent)` | `Form` | Emitted after server save call completes. |
-| `(out)` | `eventOut` | General-purpose external output. |
-| `(fireTrigger)` | `FireTrigger` | Emitted when a trigger fires. |
-
-**Theming**
-
-The configurator exposes a theming system based on CSS custom properties. All values injected via the theme inputs are applied with `!important` and cannot be overridden externally except through these inputs.
-
-```html
-<!-- Option A: TypeScript object -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [configuratorTheme]="{ '--conf-gradient': 'linear-gradient(to right, #1565c0, #0288d1)' }">
-</eqp-dynamic-module-configurator>
-
-<!-- Option B: CSS file loaded as string -->
-<eqp-dynamic-module-configurator
-  [configurations]="config"
-  [configuratorThemeCss]="themeCssString">
-</eqp-dynamic-module-configurator>
-```
-
-CSS file format for `configuratorThemeCss` (no selector required):
-
-```css
---conf-gradient:           linear-gradient(to right, #1565c0, #0288d1);
---conf-bg-page:            #f0f6fb;
---conf-btn-color:          #ffffff;
-```
-
-Available variables:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--conf-gradient` | purple-blue gradient | Button and header background |
-| `--conf-bg-page` | `#f5f5f5` | General page/stepper background |
-| `--conf-radius` | `10px` | Button border radius |
-| `--conf-modal-radius` | `12px` | Modal border radius |
-| `--conf-accent` | `#693DDA` | Accent colour (borders, focus) |
-| `--conf-primary` | `#1E31EB` | Primary colour |
-| `--conf-step-selected` | `#643cda` | Selected step arrow |
-| `--conf-step-edit` | `#3034e7` | Completed step arrow |
-| `--conf-stepper-header-bg` | inherited from `--conf-bg-page` | Upper zone background (stepper header) |
-| `--conf-stepper-content-bg` | inherited from `--conf-bg-page` | Lower zone background (form and buttons) |
-| `--conf-step-icon-edit-bg` | inherited from `--conf-step-edit` | Completed step icon background |
-| `--conf-btn-color` | `#ffffff` | Active button text colour (gradient background) |
-| `--conf-hint-btn-bg` | `#2563eb` | Quick-suggestion button (lightbulb) background |
-| `--conf-hint-btn-hover-bg` | `#1d4ed8` | Lightbulb button hover background |
-| `--conf-table-header-bg` | SCSS variable | Field table header background |
-| `--conf-search-bg` | SCSS variable | Search field background |
-| `--conf-table-bg` | `#ffffff` | Table row background |
-| `--conf-card-bg` | `#ffffff` | Card background |
-| `--conf-font-family` | `inherit` | Configurator-wide font family |
-
----
-
-### Configuration Models
-
-#### `DynamicModuleGeneralConfig`
-
-```typescript
-const general = new DynamicModuleGeneralConfig(
-  baseServerUrl,        // string — e.g. "https://api.example.com/api"
-  userToken,            // string — auth token
-  context,              // Context
-  endPointConfiguration // EndPointConfiguration | null
-);
-```
-
-#### `DynamicModuleListFormRecordActionsDefault`
-
-```typescript
-const actions = new DynamicModuleListFormRecordActionsDefault();
-actions.add       = true;
-actions.view      = true;
-actions.edit      = true;
-actions.duplicate = false;
-actions.delete    = true;
-actions.graphs    = false;
-```
-
----
-
-### View Modes
-
-```typescript
-enum DynamicModuleViewModeEnum {
-  NONE            = 0,
-  VIEW            = 1,
-  COMPILE         = 2,
-  LIST            = 3,
-  REPAIR          = 4,
-  LISTWIEW        = 5,
-  FILTER          = 6,
-  GRAPHS          = 7,
-  HLIST           = 8,
-  EXTERNAL_FILTER = 9
-}
-```
-
----
-
-### Endpoint Configuration
-
-```typescript
-const endPoints = new EndPointConfiguration();
-endPoints.Records.SaveEndPoint = new EndPointData();
-endPoints.Records.SaveEndPoint.Url = 'https://custom-api.example.com/records/save';
-endPoints.Records.SaveEndPoint.RequestMethod = RequestMethodEnum.POST;
-endPoints.Records.SaveEndPoint.Params = [{
-  ParamName: 'orgId',
-  ParamValue: this.orgaId,
-  ParamType: ParamTypeEnum['Query param']
-}];
-const general = new DynamicModuleGeneralConfig(baseUrl, token, context, endPoints);
-```
-
-**Available Records endpoints:** `GetWithContextualizationByFormCodeEndPoint`, `GetByFormIDEndPoint`, `GetByFormCodeEndPoint`, `GetAllByEntAndUserIDEndPoint`, `GetByIDEndPoint`, `SaveEndPoint`, `DuplicateEndPoint`, `DeleteEndPoint`, `RepairEndPoint`, `ApplyFilter`, `GetAllAttachmentsEndPoint`.
-
-**Available Forms endpoints:** `GetByIDEndPoint`, `GetAllFormEndPoint`, `GetByIDAndVersionEndPoint`, `SaveEndPoint`, `SaveAttachmentEndPoint`, `ExportByIDEndPoint`, `GetAttachmentWithBases64`, `SpeechToFormEditEndPoint`.
-
----
-
-### Data Models
-
-#### `Record`
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `ID` | `string` | Unique record identifier. |
-| `EntID` | `string` | ID of the form this record belongs to. |
-| `Version` | `number` | Form version at compilation time. |
-| `userID` | `string` | ID of the user who created the record. |
-| `AnswerDate` | `string` | ISO date string of compilation. |
-| `HTMLreadableValues` | `string` | Pre-rendered HTML of field values. |
-| `AdditionalParams` | `any` | Extra parameters. |
-| `AdditionalInfo` | `any` | Extra information. |
-
----
-
-### Field Types Reference
-
-| Value | Key | Description |
-|-------|-----|-------------|
-| `1` | `Campo di testo` | Single-line text input. |
-| `2` | `Area di testo` | Multi-line textarea. |
-| `3` | `Booleano` | Checkbox / boolean toggle. |
-| `4` | `Data e/ora` | Date and/or time picker. |
-| `5` | `Campo numerico` | Numeric input with mask. |
-| `6` | `Allegato` | File attachment upload. |
-| `7` | `Immagine` | Image upload with optional cropping. |
-| `8` | `Elenco generico` | Dropdown / multi-select list. |
-| `9` | `Lookup` | Server-side lookup with configurable query. |
-| `10` | `Form di dettaglio` | Embedded detail (inner) form. |
-| `11` | `Elenco immagini` | Image selector list. |
-| `12` | `Etichetta` | Display-only label. |
-| `13` | `Immagine con markers` | Image with interactive annotation markers. |
-| `14` | `Bottone` | Action button field. |
+# @eqproject/eqp-dynamic-module
+
+[![npm version](https://img.shields.io/npm/v/@eqproject/eqp-dynamic-module.svg)](https://www.npmjs.com/package/@eqproject/eqp-dynamic-module)
+[![Angular](https://img.shields.io/badge/Angular-15-red.svg)](https://angular.io/)
+
+> Libreria Angular 15 per la creazione, visualizzazione e gestione di form dinamiche con configuratore no-code.  
+> Angular 15 library for building, rendering and managing dynamic forms with a no-code configurator.
+
+📖 **[Guida utente / User Guide →](./USERGUIDE.md)**
+
+---
+
+## Changelog
+
+### v2.10.102
+- **Bugfix `ListValueField` (Combo box) — pulsante di cancellazione (X) sempre presente:** in `list-value-field-template`, il pulsante "X" di `tmw-select` era condizionato a `!field.Required` (nascosto sui campi obbligatori). Ora `showCancelButton` è sempre `true`, indipendentemente dall'obbligatorietà del campo: l'utente può sempre svuotare la selezione, anche su un campo required (la validazione `required` interviene comunque al salvataggio). Nessun cambio di API pubblica.
+- **Bugfix `ListValueField` (Combo box) — cancel button (X) always present:** in `list-value-field-template`, the `tmw-select` "X" clear button was conditioned on `!field.Required` (hidden on required fields). `showCancelButton` is now always `true`, regardless of whether the field is required: the user can always clear the selection, and `required` validation still applies on save. No public API change.
+
+### v2.10.101
+- **Migrazione interna `eqp-table`/`eqp-attachments`/`eqp-numeric` → `tmw-table`/`tmw-attachments`/`tmw-numeric`:** le ultime tre dipendenze `@eqproject/eqp-*` sono state sostituite dalle librerie Material-free `tmw-*` (stesso lavoro già fatto per `eqp-select`/`eqp-datetimepicker` nelle versioni precedenti). Nessun cambio di API pubblica di questa libreria: i tag `<eqp-table>`/`<eqp-attachments>` erano già privati, i modelli `ConfigColumn`/`TypeColumn`/`DynAttachment` restano gli stessi nomi/forma. Chi consuma questa libreria non deve più installare `@eqproject/eqp-table`, `@eqproject/eqp-attachments`, `@eqproject/eqp-numeric` né `@eqproject/eqp-filters` (import morto, mai realmente usato).
+- **Migrazione completa `<mat-icon>` → `<tmw-icon>`:** tutte le icone della libreria (inclusi i pulsanti del builder, i template di campo e le colonne azione delle tabelle) sono ora renderizzate dalla nuova libreria `tmw-icons` (SVG inline, icone vendorizzate da Tabler Icons, nessuna dipendenza dal font Material Icons). **Attenzione per chi ha form esistenti con icone personalizzate**: i campi di testo libero "Icona" (`IconName` su `TextField`/`NumericField`/`TextareaField`, `Icon` su `ActionButton`) si aspettavano nomi Material Icons (es. `search`, `home`, `euro`) — ora si aspettano nomi Tabler Icons (es. `search`, `user`, `currency-euro`); i nomi già salvati che non trovano corrispondenza esatta nel registro `tmw-icons` semplicemente non renderizzano l'icona (nessun errore a runtime, solo icona assente). Nessun impatto sul resto del form.
+- **Pulizia dipendenze:** rimosse dalle `peerDependencies` `@angular-material-components/datetime-picker`, `@angular-material-components/moment-adapter` e `moment` (mai più necessarie dopo la migrazione a `tmw-picker`, completata in una versione precedente). Nuove dipendenze dirette: `tmw-attachments`, `tmw-icons`, `tmw-numeric`, `tmw-table`, `xlsx` (quest'ultima solo per l'export XLSX di `filter-form-statistic`, `tmw-table` non ha un formato XLSX nativo).
+
+- **Internal migration `eqp-table`/`eqp-attachments`/`eqp-numeric` → `tmw-table`/`tmw-attachments`/`tmw-numeric`:** the last three `@eqproject/eqp-*` dependencies have been replaced with the Material-free `tmw-*` libraries (same work already done for `eqp-select`/`eqp-datetimepicker` in previous versions). No public API change in this library: the `<eqp-table>`/`<eqp-attachments>` tags were already private, the `ConfigColumn`/`TypeColumn`/`DynAttachment` models keep the same names/shape. Consumers of this library no longer need to install `@eqproject/eqp-table`, `@eqproject/eqp-attachments`, `@eqproject/eqp-numeric` or `@eqproject/eqp-filters` (dead import, never actually used).
+- **Complete `<mat-icon>` → `<tmw-icon>` migration:** every icon in the library (including builder buttons, field templates and table action columns) is now rendered by the new `tmw-icons` library (inline SVG, icons vendored from Tabler Icons, no dependency on the Material Icons font). **Note for existing forms with custom icons**: the free-text "Icon" fields (`IconName` on `TextField`/`NumericField`/`TextareaField`, `Icon` on `ActionButton`) used to expect Material Icons names (e.g. `search`, `home`, `euro`) — they now expect Tabler Icons names (e.g. `search`, `user`, `currency-euro`); previously saved names with no exact match in the `tmw-icons` registry simply don't render the icon (no runtime error, just a missing icon). No impact on the rest of the form.
+- **Dependency cleanup:** removed `@angular-material-components/datetime-picker`, `@angular-material-components/moment-adapter` and `moment` from `peerDependencies` (no longer needed after the `tmw-picker` migration, completed in a previous version). New direct dependencies: `tmw-attachments`, `tmw-icons`, `tmw-numeric`, `tmw-table`, `xlsx` (the latter only for `filter-form-statistic`'s XLSX export — `tmw-table` has no native XLSX format).
+
+### v2.10.100
+- **Cleanup — rimossi import morti di `@eqproject/eqp-datetimepicker` e `@eqproject/eqp-img-drawing`:** entrambi erano registrati nell'`NgModule` (`EqpDatetimepickerModule`, `EqpImgDrawingModule`) e in `trigger-creator.component.ts` (`PickerModeEnum`) ma non più usati da nessun template — sostituiti internamente da tempo da `tmw-datetimepicker` (campo Data) e da `tmw-image-drawer`/`tmw-image-marker` (campo Immagine con markers). Nessun impatto funzionale: build verificata anche con i due pacchetti fisicamente assenti da `node_modules`, per provare che non fossero più necessari. Chi consuma questa libreria non deve più installare `@eqproject/eqp-datetimepicker` né `@eqproject/eqp-img-drawing`.
+- **Cleanup — removed dead imports of `@eqproject/eqp-datetimepicker` and `@eqproject/eqp-img-drawing`:** both were registered in the `NgModule` (`EqpDatetimepickerModule`, `EqpImgDrawingModule`) and in `trigger-creator.component.ts` (`PickerModeEnum`) but no longer used by any template — internally superseded a while ago by `tmw-datetimepicker` (Date field) and `tmw-image-drawer`/`tmw-image-marker` (Image with markers field). No functional impact: build verified even with both packages physically absent from `node_modules`, to prove they were no longer required. Consumers of this library no longer need to install `@eqproject/eqp-datetimepicker` or `@eqproject/eqp-img-drawing`.
+
+### v2.10.99
+- **Bugfix configurator — immagine persa su campo `Immagine`/`Immagine con markers`:** `catchButtonImageChange` e `catchButtonImageWithMarkersChange` in `add-form-field` leggevano l'indice sbagliato (`attachments[1]`) dell'array emesso da `eqp-attachments`. Al primo caricamento di un'immagine su un campo nuovo l'array ha un solo elemento, quindi `field.DynAttachment` veniva sovrascritto con `undefined`: l'immagine spariva riaprendo la modale di modifica campo e non compariva mai in anteprima. Corretto leggendo `attachments[attachments.length - 1]`.
+- **Bugfix configurator — image lost on `Image`/`Image with markers` field:** `catchButtonImageChange` and `catchButtonImageWithMarkersChange` in `add-form-field` were reading the wrong index (`attachments[1]`) from the array emitted by `eqp-attachments`. On the first image upload to a new field the array has only one element, so `field.DynAttachment` was overwritten with `undefined`: the image disappeared when reopening the field edit dialog and never showed up in the preview. Fixed to read `attachments[attachments.length - 1]`.
+
+### v2.10.87
+- **Bugfix configurator — sezione "Generale" assente per 5 tipi di campo:** durante il lavoro di potenziamento grafico (v2.10.68–v2.10.70), i tipi `ActionButtonField`, `ImageField`, `ImageWithMarkersField`, `ListValueField` e `ImageSelectorField` avevano ricevuto la sezione "Grafica" nel tab "Stile Compilazione" del configuratore, ma la sezione "Generale" (Larghezza campo, Visibile, VisibleIf, Tooltip, Tipo di invisibilità, Mantieni il valore) era stata rimossa per errore. Ripristinata per tutti e 5 i tipi.
+- **Bugfix configurator — "Generale" section missing for 5 field types:** during the graphical enhancement work (v2.10.68–v2.10.70), `ActionButtonField`, `ImageField`, `ImageWithMarkersField`, `ListValueField` and `ImageSelectorField` received the "Grafica" section in the configurator's "Stile Compilazione" tab, but the "Generale" section (field width, visibility, VisibleIf, tooltip, invisibility type, maintain value) was accidentally removed. Restored for all 5 field types.
+
+### v2.10.86
+- **Bugfix loop infinito `ListValueField`:** `FormControl.setValue()` notificava il callback `_onChange` del `NgModel` registrato tramite `[formControlName]` sul `mat-checkbox`, causando `ngModelChange` → `updateSelected()` → `setFormControlValue()` in ricorsione infinita. Aggiunto `{ emitModelToViewChange: false }` a `setFormControlValue()` per interrompere il ciclo. Fix correlati: `updateSelected()` ora restituisce `null` (non `[]`) per campi single-choice senza selezione, evitando instabilità Angular CD da `[] !== []`; `resetArrayData()` chiama `updateSelected(false)` per non emettere `recordChange` durante il rebuild delle opzioni; `updateField()` distingue formula-per-valore da formula-per-opzioni nei campi `DataGetterType=Formula`.
+- **Bugfix loop infinito `onRecordChange`:** aggiunta guardia di rientranza `_recordChanging` con `try/finally` in `add-form-record.onRecordChange()` per prevenire ricorsione da campi formula concatenati (es. campo numerico → campo elenco valorizzato dalla formula del primo).
+- **Bugfix loop in anteprima — `DynAttachment.ButtonKey` null:** nei template `image-field-template` e `image-with-markers-field-template`, la valutazione di `field.DynAttachment.ButtonKey` in `*ngIf` lanciava eccezione quando `DynAttachment` era `null` (campo senza immagine caricata), innescando un loop di Angular CD. Sostituito con `field.DynAttachment?.ButtonKey`.
+- **Fix posizione dialog DataGetter:** la modale del Query Editor aperta con "Modifica" nel configuratore compariva a metà pagina. Aggiunti `position: { top: '20px' }` e `maxHeight: '90vh'` per allinearla al comportamento di tutte le altre dialog.
+- **Bugfix infinite loop `ListValueField`:** `FormControl.setValue()` was notifying the `_onChange` callback of the `NgModel` registered via `[formControlName]` on `mat-checkbox`, causing `ngModelChange` → `updateSelected()` → `setFormControlValue()` in infinite recursion. Added `{ emitModelToViewChange: false }` to `setFormControlValue()` to break the cycle. Related fixes: `updateSelected()` now returns `null` (not `[]`) for single-choice fields with no selection, preventing Angular CD instability from `[] !== []`; `resetArrayData()` calls `updateSelected(false)` to avoid emitting `recordChange` during option rebuild; `updateField()` now distinguishes formula-for-value from formula-for-options in `DataGetterType=Formula` fields.
+- **Bugfix infinite loop `onRecordChange`:** added `_recordChanging` re-entrancy guard with `try/finally` in `add-form-record.onRecordChange()` to prevent recursion from chained formula fields (e.g. numeric field → list field driven by the first field's formula).
+- **Bugfix preview loop — `DynAttachment.ButtonKey` null:** in `image-field-template` and `image-with-markers-field-template`, evaluating `field.DynAttachment.ButtonKey` in `*ngIf` threw an exception when `DynAttachment` was `null` (field with no image loaded), triggering an Angular CD loop. Replaced with `field.DynAttachment?.ButtonKey`.
+- **Fix DataGetter dialog position:** the Query Editor modal opened via "Modifica" in the configurator was appearing at mid-page. Added `position: { top: '20px' }` and `maxHeight: '90vh'` to align it with all other dialogs.
+
+### v2.10.85
+- **Bugfix loop infinito (approccio corretto):** il loop di v2.10.84 era asincrono: `setValue` chiama `writeValue` sui ControlValueAccessor di Angular Material che emettono eventi nel tick successivo, quando la guardia di rientranza era già rilasciata. Soluzione definitiva: il validator `required` ora legge direttamente da `record[field.Name]` tramite closure (anziché da `control.value`); in `onRecordChange()` viene chiamato `updateValueAndValidity({ emitEvent: false })` — che ri-esegue i validator senza invocare `writeValue` — eliminando alla radice ogni possibilità di cascade.
+- **Bugfix infinite loop (correct approach):** the v2.10.84 loop was asynchronous: `setValue` calls `writeValue` on Angular Material ControlValueAccessors which emit events on the next tick, after the re-entrancy guard was already released. Definitive fix: the `required` validator now reads directly from `record[field.Name]` via closure (instead of `control.value`); `onRecordChange()` calls `updateValueAndValidity({ emitEvent: false })` — which re-runs validators without invoking `writeValue` — eliminating any cascade at the root.
+
+### v2.10.84
+- **Bugfix loop infinito `onRecordChange`:** la sincronizzazione dei `FormControl` introdotta in v2.10.83 causava un loop: `setValue` invoca `writeValue` sui ControlValueAccessor (es. `mat-datepicker`), che emettono `(dateChange)/(ngModelChange)` → `recordChange` → `onRecordChange` di nuovo, all'infinito. Aggiunta una guardia di rientranza (`_isInRecordChange`) con `try/finally` che interrompe il ciclo. La sincronizzazione dei FormControl resta attiva e la validazione required funziona correttamente.
+- **Bugfix infinite loop `onRecordChange`:** the FormControl sync introduced in v2.10.83 caused an infinite loop: `setValue` calls `writeValue` on ControlValueAccessors (e.g. `mat-datepicker`), which emit `(dateChange)/(ngModelChange)` → `recordChange` → `onRecordChange` again, endlessly. Added a re-entrancy guard (`_isInRecordChange`) with `try/finally` that breaks the cycle. FormControl sync remains active and required validation works correctly.
+
+### v2.10.83
+- **Bugfix validazione form — campi obbligatori valorizzati via formula/ActionButton:** quando un campo con `required` veniva impostato tramite formula o ActionButton, il valore compariva visivamente ma il `FormControl` Angular rimaneva non aggiornato, lasciando il form invalido finché l'utente non interagiva manualmente col campo. Ora `onRecordChange()` risincronizza tutti i `FormControl` dal record dopo ogni aggiornamento formula, rendendo la validazione coerente con il valore visualizzato.
+- **Bugfix form validation — required fields set via formula/ActionButton:** when a required field was populated by a formula or ActionButton, the value appeared visually but the Angular `FormControl` was never updated, keeping the form invalid until the user manually interacted with the field. `onRecordChange()` now re-syncs all `FormControl` values from the record after every formula update, making validation consistent with the displayed value.
+
+### v2.10.81
+- **Bugfix configurator — `DataGetter` null dopo decode Base64:** quando il campo `DataGetterValueBase64String` decodifica in un JSON con `DataGetter: null`, viene ora creato un oggetto `DataGetter` vuoto anziché proseguire con `null`, evitando errori a runtime nel configuratore.
+- **Bugfix `add-form-record` — `actionButtons` null:** se l'input `actionButtons` arriva `null` al componente, viene ora inizializzato a un array vuoto prima del filtraggio, prevenendo un'eccezione al caricamento del record.
+- **Bugfix configurator — `DataGetter` null after Base64 decode:** when `DataGetterValueBase64String` decodes to a JSON with `DataGetter: null`, a new empty `DataGetter` object is now created instead of proceeding with `null`, preventing runtime errors in the configurator.
+- **Bugfix `add-form-record` — `actionButtons` null:** if the `actionButtons` input arrives as `null`, it is now initialized to an empty array before filtering, preventing an exception on record load.
+
+### v2.10.79
+- **DataGetter V2 — selezione automatica colonna singola:** quando il flusso V2 genera una sola `columnKey`, essa viene assegnata automaticamente a `DataGetterColumnForce` senza che l'utente debba selezionarla manualmente dalla dropdown.
+- **DataGetter V2 — single column auto-selection:** when the V2 flow produces exactly one `columnKey`, it is automatically assigned to `DataGetterColumnForce` without requiring manual selection from the dropdown.
+
+### v2.10.77
+- **DataGetter V2 — `DataGetterColumnForce` come stringa:** `onAiDataGetterOut` ora salva `DataGetterColumnForce` come stringa chiave (non come oggetto), allineandosi al formato atteso da `eqp-select`. Il valore pre-selezionato nella dropdown compare automaticamente dopo il flusso AI.
+- **DataGetter V2 — `DataGetterColumnForce` as string:** `onAiDataGetterOut` now stores `DataGetterColumnForce` as a key string (not as an object), matching the format expected by `eqp-select`. The pre-selected value in the dropdown appears automatically after the AI flow.
+
+### v2.10.76
+- **DataGetter V2 — `createColumnKeys` retrocompatibile:** `add-form-field` ora rileva `DataGetterCodeVersion=2` e legge `selectedFields` da `queryCommandDatabaseConfiguration.selectedFields` invece che dal livello radice; fallback su `PropertyName` se `CurrentTranslate` è assente.
+- **DataGetter V2 — `createColumnKeys` backward-compatible:** `add-form-field` now detects `DataGetterCodeVersion=2` and reads `selectedFields` from `queryCommandDatabaseConfiguration.selectedFields` instead of the root level; falls back to `PropertyName` when `CurrentTranslate` is missing.
+
+### v2.10.74 / v2.10.75
+- **DataGetter AI — nuova modalità "Da database" (DataGetterType=3):** aggiunto campo `DataGetterSpeechText` nel modello `DataGetter`. Il configurator AI può creare campi con recupero dati da database impostando un prompt testuale: al caricamento del form, il componente QueryEditor esterno viene invocato silenziosamente, elabora il prompt via AI e popola automaticamente `DataGetterValue`, `DataGetterCardinality=1`, `DataGetterHasResetButton=true` e `DataGetterColumnForce` (se il risultato ha un solo campo selezionato).
+- **DataGetterCodeVersion V2 — retrocompatibilità in lettura:** il `DbgetterComponent` rileva automaticamente i campi con `DataGetterCodeVersion=2` (formato Omnisearch AI) ed esegue un unwrap trasparente della struttura `queryCommandDatabaseConfiguration` al formato V1, senza impatto sui campi legacy. Il `DataGetterCodeVersion=2` viene propagato al componente QueryEditor esterno tramite `config.DataGetterCodeVersion` per consentire al client ospitante di attivare il flusso V2 in lettura.
+- **AI DataGetter — new "Da database" mode (DataGetterType=3):** added `DataGetterSpeechText` field to the `DataGetter` model. The AI configurator can create database-getter fields with a natural-language prompt: on form load, the external QueryEditor component is invoked silently, processes the prompt via AI and automatically populates `DataGetterValue`, `DataGetterCardinality=1`, `DataGetterHasResetButton=true` and `DataGetterColumnForce` (if a single output field is returned).
+- **DataGetterCodeVersion V2 — backward-compatible read flow:** `DbgetterComponent` now auto-detects fields with `DataGetterCodeVersion=2` (Omnisearch AI format) and transparently unwraps the `queryCommandDatabaseConfiguration` structure to the V1 format, with zero impact on legacy fields. `DataGetterCodeVersion=2` is forwarded to the external QueryEditor component via `config.DataGetterCodeVersion` to enable the V2 read flow on the host application side.
+
+### v2.10.70
+- **Theming configurator — nuovi input:** aggiunto `[configuratorThemeCss]` che accetta direttamente il testo di un file CSS con le dichiarazioni delle variabili `--conf-*`. Permette di portare il tema dall'esterno come file statico senza hardcodare valori TypeScript. Se entrambi gli input sono presenti, `configuratorTheme` sovrascrive `configuratorThemeCss` per le chiavi in conflitto.
+- **Theming configurator — nuove variabili CSS:** `--conf-stepper-header-bg` (sfondo zona step superiore), `--conf-stepper-content-bg` (sfondo zona inferiore), `--conf-step-icon-edit-bg` (sfondo pallini step completati), `--conf-hint-btn-bg` / `--conf-hint-btn-hover-bg` (bottone suggerimento rapido), `--conf-btn-color` (colore testo bottoni con sfondo gradiente).
+- **Theming configurator — forzatura `!important`:** tutti i valori iniettati tramite tema esterno sono ora applicati con `!important`, rendendo il sistema di theming l'unico canale valido per sovrascrivere i colori.
+- **Theming configurator — `--conf-btn-color`:** il colore del testo dei bottoni attivi (sfondo gradiente) è ora templatizzabile e forzato con `!important` per resistere a override CSS provenienti dall'applicazione ospitante.
+- **New theming input:** added `[configuratorThemeCss]` accepting a CSS text string with `--conf-*` variable declarations. Enables external theme files without TypeScript hardcoding. When both inputs are present, `configuratorTheme` overrides `configuratorThemeCss` for conflicting keys.
+- **New CSS variables:** `--conf-stepper-header-bg`, `--conf-stepper-content-bg`, `--conf-step-icon-edit-bg`, `--conf-hint-btn-bg`, `--conf-hint-btn-hover-bg`, `--conf-btn-color`.
+- **`!important` enforcement:** all externally-injected theme values are now set with `!important`, making the theming system the sole valid override channel.
+
+### v2.10.65
+- **TextField — icona opzionale:** aggiunta la possibilità di associare un'icona Material Icons al campo di testo. Le nuove proprietà `IconName` (stringa) e `IconPosition` (enum: `1`=Sinistra/prefix, `2`=Destra/suffix) sono opzionali e retrocompatibili (null sui form esistenti). Configurabili nel builder tramite il toggle "Icona" nella sezione Specifiche del campo.
+- **TextField — optional icon:** added support for a Material Icons icon on text fields. New properties `IconName` (string) and `IconPosition` (enum: `1`=Left/prefix, `2`=Right/suffix) are optional and backward-compatible (null on existing forms). Configurable in the builder via the "Icona" toggle in the field's Specifiche section.
+
+### v2.10.64
+- **Bugfix configurator:** se il campo `Code` del form risulta `null` al momento del salvataggio (scenario: form creato con AI senza salvataggio intermedio), ora viene generato automaticamente da `Name` prima dell'invio al server.
+
+### v2.10.63
+- README riscritto in formato bilingue (italiano completo + inglese completo).
+- Aggiunto `USERGUIDE.md` con guida pratica per scenari d'uso comuni e sezione prompt AI di esempio.
+- `USERGUIDE.md` incluso nel pacchetto npm tramite `ng-package.json` assets.
+
+### v2.10.62
+- Migrazione da `tmw-picker` 1.0.x a 1.1.0: NgModule → standalone components, moment.js → Luxon, aggiornamento di tutti i token formato data (`DD/MM/YYYY` → `dd/MM/yyyy`).
+- Rimossi input inutilizzati: `answerToDuplicateId` da `eqp-dynamic-module`, `ProjectName` da `eqp-dynamic-module-configurator`.
+- Documentazione NPM riscritta completamente (bilingue IT/EN).
+
+### v2.10.60
+- Aggiornamenti interni e correzioni bug.
+
+---
+
+## Versione italiana
+
+- [Panoramica](#panoramica)
+- [Prerequisiti](#prerequisiti)
+- [Installazione](#installazione)
+- [Configurazione del modulo](#configurazione-del-modulo)
+- [Componenti](#componenti)
+  - [eqp-dynamic-module — Visualizzatore form](#eqp-dynamic-module--visualizzatore-form)
+  - [eqp-dynamic-module-configurator — Builder form](#eqp-dynamic-module-configurator--builder-form)
+- [Modelli di configurazione](#modelli-di-configurazione)
+- [Modalità di visualizzazione](#modalità-di-visualizzazione)
+- [Configurazione endpoint](#configurazione-endpoint)
+- [Modelli dati](#modelli-dati)
+- [Tipi di campo](#tipi-di-campo)
+
+---
+
+### Panoramica
+
+`@eqproject/eqp-dynamic-module` espone **due componenti pubblici**:
+
+| Componente | Scopo |
+|-----------|-------|
+| `<eqp-dynamic-module>` | Visualizzatore, compilatore, lista, filtro e grafici a runtime |
+| `<eqp-dynamic-module-configurator>` | Builder no-code per creare e modificare le definizioni form |
+
+Le form sono strutture JSON salvate lato server e recuperate a runtime. La libreria gestisce rendering, validazione, recupero dati, operazioni CRUD e funzionalità avanzate come formule, trigger, action button e speech-to-text.
+
+---
+
+### Prerequisiti
+
+```bash
+npm install @angular/cdk@^15.1.2 @angular/material@^15.1.2 @angular/material-luxon-adapter@^15.2.9 --legacy-peer-deps
+npm install sweetalert2@^11.4.24 --legacy-peer-deps
+```
+
+> Tutti i comandi `npm install` per questa libreria richiedono il flag `--legacy-peer-deps`.
+
+---
+
+### Installazione
+
+```bash
+npm install @eqproject/eqp-dynamic-module --legacy-peer-deps
+```
+
+---
+
+### Configurazione del modulo
+
+```typescript
+import { EqpDynamicModuleModule } from '@eqproject/eqp-dynamic-module';
+
+@NgModule({
+  imports: [
+    EqpDynamicModuleModule
+  ]
+})
+export class AppModule {}
+```
+
+In `angular.json`, aggiungi il tema Material agli stili:
+
+```json
+"styles": [
+  "node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
+  "src/styles.css"
+]
+```
+
+---
+
+### Componenti
+
+#### `eqp-dynamic-module` — Visualizzatore form
+
+Visualizza una form dinamica in una delle [modalità disponibili](#modalità-di-visualizzazione).
+
+**Utilizzo base**
+
+```typescript
+import { DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
+
+generalConfig = new DynamicModuleGeneralConfig(
+  'https://tua-api.esempio.it/api',
+  this.userToken,
+  this.context,
+  null
+);
+```
+
+```html
+<eqp-dynamic-module
+  [configurations]="generalConfig"
+  [formID]="'id-del-form'"
+  [starterViewMode]="DynamicModuleViewModeEnum.LIST"
+  [userID]="currentUser.id"
+  (saveRecord)="onSalvataggio($event)"
+  (afterSaveRecord)="dopoSalvataggio($event)">
+</eqp-dynamic-module>
+```
+
+**Input**
+
+| Input | Tipo | Default | Descrizione |
+|-------|------|---------|-------------|
+| `configurations` | `DynamicModuleGeneralConfig` | — | **Obbligatorio.** Configurazione connessione server. |
+| `formID` | `string` | — | **Obbligatorio.** ID del form da visualizzare. |
+| `starterViewMode` | `DynamicModuleViewModeEnum` | `LIST` | Modalità iniziale. |
+| `userID` | `string` | `"0"` | ID utente per il salvataggio record. |
+| `orgaID` | `string` | `"0"` | ID organizzazione. |
+| `showTitle` | `boolean` | `true` | Mostra/nasconde il nome del form. |
+| `showBackButton` | `boolean` | `true` | Mostra/nasconde il pulsante indietro. |
+| `showSaveButton` | `boolean` | `true` | Mostra/nasconde il pulsante salva. |
+| `values` | `Record[]` | `null` | Record pre-caricati per la modalità LIST. |
+| `FormJSON` | `string` | `""` | JSON del form per la modalità REPAIR. |
+| `formulaObject` | `any` | `{}` | Oggetto contesto per le formule (es. `{ role, user }`). |
+| `selectedRecord` | `Record \| string` | `null` | Record pre-selezionato (oggetto o ID). |
+| `externalButtons` | `RecordButton[]` | `[]` | Pulsanti extra nel menu azioni record. |
+| `actionButtons` | `ActionButton[]` | `[]` | Pulsanti azione per i campi di tipo `Bottone`. |
+| `defaultListActions` | `DynamicModuleListFormRecordActionsDefault` | tutti `true` | Azioni default lista: add, view, edit, duplicate, delete, graphs. |
+| `listViewRecordTitle` | `string[]` | `[]` | Chiavi dei campi che compongono il titolo accordion. |
+| `defaultListViewFunction` | `Function` | `null` | Funzione custom al caricamento della lista. |
+| `onSaveBackToList` | `boolean` | `false` | Torna alla LIST dopo il salvataggio. |
+| `onBackTo` | `DynamicModuleViewModeEnum` | `null` | Modalità di destinazione del pulsante indietro. |
+| `numberOfColumns` | `number` | `3` | Numero di colonne del layout. |
+| `showHiddenFields` | `boolean` | `true` | Mostra/nasconde i campi marcati come nascosti. |
+| `filterResultViewMode` | `DynamicModuleFilterResultViewModeEnum` | `INTERNAL_EQPTABLE` | Modalità visualizzazione risultati filtro. |
+| `additionalParams` | `any` | `null` | Parametri extra per le chiamate filtro server. |
+| `additionalInfo` | `any` | `null` | Dati extra per operazioni client-side. |
+| `prefilterParams` | `any` | `null` | Parametri pre-filtro. |
+| `updateInfo` | `any` | `null` | Dati per aggiornare i valori delle risposte. |
+| `contestualizationParams` | `any` | `null` | Parametri di contestualizzazione della lista risultati. |
+| `showNewSearchButton` | `boolean` | `true` | Mostra/nasconde il pulsante "nuova ricerca". |
+| `highlightFilter` | `any` | — | Configurazione evidenziazione righe/campi. |
+| `isDraggableListView` | `boolean` | `true` | Abilita drag-and-drop nella lista. |
+| `Statistic` | `FilterStatistic` | `null` | Configurazione statistiche e filtri. |
+| `QueryEditorComponent` | `any` | — | Componente query editor custom per i lookup. |
+| `debugMode` | `boolean` | `false` | Abilita log dettagliati in console. |
+
+**Output**
+
+| Output | Payload | Descrizione |
+|--------|---------|-------------|
+| `(saveRecord)` | `Record` | Emesso al salvataggio **senza** endpoint configurato. |
+| `(afterSaveRecord)` | `Record` | Emesso dopo la chiamata server di salvataggio. |
+| `(deleteRecord)` | `Record` | Emesso all'eliminazione **senza** endpoint configurato. |
+| `(afterDeleteRecord)` | `Record` | Emesso dopo la chiamata server di eliminazione. |
+| `(SaveJSON)` | `string` | Emesso all'esportazione del JSON del form. |
+| `(afterFilter)` | `DynRecord[]` | Emesso dopo l'applicazione di un filtro. |
+| `(dragStarted)` | `Record` | Emesso all'inizio di un drag. |
+| `(dragReleased)` | `void` | Emesso al rilascio del drag. |
+| `(clickDragIndicator)` | `Record` | Emesso al click sull'icona drag. |
+| `(out)` | `eventOut` | Output generico per comunicazione esterna. |
+| `(fireTrigger)` | `FireTrigger` | Emesso quando scatta un trigger. |
+| `(afterOutputExternalFilters)` | `FilterStatistic` | Emesso dopo filtri esterni applicati. |
+
+---
+
+#### `eqp-dynamic-module-configurator` — Builder form
+
+Designer no-code per creare e modificare definizioni form.
+
+**Modalità d'uso**
+
+```typescript
+// Nuovo form
+const specific = new DynamicModuleConfiguratorSpecificConfig();
+specific.UserID = this.currentUser.id;
+specific.orgaID = this.currentOrga.id;
+const general = new DynamicModuleGeneralConfig(this.baseServerUrl, this.userToken, this.context, null);
+this.config = new DynamicModuleConfiguratorConfig(general, specific);
+```
+
+```html
+<!-- Nuovo form -->
+<eqp-dynamic-module-configurator
+  *ngIf="config"
+  [configurations]="config"
+  (saveFormEvent)="onSalvaForm($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Modifica form esistente -->
+<eqp-dynamic-module-configurator
+  *ngIf="config"
+  [configurations]="config"
+  [formID]="formID"
+  (saveFormEvent)="onSalvaForm($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Esportazione -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [formID]="formID"
+  [viewMode]="'Export'"
+  (saveFormEvent)="onSalvaForm($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Importazione da JSON -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [formID]="null"
+  [viewMode]="'Export'"
+  (saveFormEvent)="onSalvaForm($event)">
+</eqp-dynamic-module-configurator>
+```
+
+**Input**
+
+| Input | Tipo | Default | Descrizione |
+|-------|------|---------|-------------|
+| `configurations` | `DynamicModuleConfiguratorConfig` | — | **Obbligatorio.** Contenitore configurazione. |
+| `formID` | `string` | `null` | ID del form da modificare. `null` crea un nuovo form. |
+| `viewMode` | `string` | `"addOrEdit"` | `"addOrEdit"` per creare/modificare, `"Export"` per esportare/importare. |
+| `fieldsExtraConfig` | `FieldExtraConfig[]` | — | Configurazione extra per campi specifici. |
+| `triggers` | `any` | — | Definizioni trigger disponibili nell'editor. |
+| `actionButtons` | `any` | — | Definizioni action button disponibili. |
+| `contestualization` | `Contestualization[]` | — | Opzioni di contestualizzazione per lookup e filtri. |
+| `formulaObject` | `any` | — | Contesto per l'anteprima delle formule. |
+| `QueryEditorComponent` | `DynamicLoaderDirectiveData` | — | Componente query editor custom. |
+| `debugMode` | `boolean` | `false` | Abilita log dettagliati. |
+| `configuratorTheme` | `Record<string, string> \| null` | `null` | Override delle variabili CSS del tema tramite oggetto TypeScript. |
+| `configuratorThemeCss` | `string \| null` | `null` | Override delle variabili CSS del tema tramite stringa CSS (es. contenuto di un file `.css`). |
+
+**Output**
+
+| Output | Payload | Descrizione |
+|--------|---------|-------------|
+| `(saveFormEvent)` | `Form` | Emesso al salvataggio **senza** endpoint configurato. |
+| `(afterSaveFormEvent)` | `Form` | Emesso dopo la chiamata server di salvataggio. |
+| `(out)` | `eventOut` | Output generico per comunicazione esterna. |
+| `(fireTrigger)` | `FireTrigger` | Emesso quando scatta un trigger. |
+
+**Theming**
+
+Il configurator espone un sistema di temi basato su CSS custom properties. Tutti i valori iniettati tramite tema sono applicati con `!important` e non possono essere sovrascritti dall'esterno se non attraverso questi input.
+
+```html
+<!-- Opzione A: oggetto TypeScript -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [configuratorTheme]="{ '--conf-gradient': 'linear-gradient(to right, #1565c0, #0288d1)', '--conf-bg-page': '#f0f6fb' }">
+</eqp-dynamic-module-configurator>
+
+<!-- Opzione B: file CSS caricato come stringa -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [configuratorThemeCss]="themeCssString">
+</eqp-dynamic-module-configurator>
+```
+
+Formato del file CSS per `configuratorThemeCss` (nessun selettore richiesto):
+
+```css
+--conf-gradient:           linear-gradient(to right, #1565c0, #0288d1);
+--conf-bg-page:            #f0f6fb;
+--conf-btn-color:          #ffffff;
+```
+
+Variabili disponibili:
+
+| Variabile | Default | Descrizione |
+|-----------|---------|-------------|
+| `--conf-gradient` | gradiente viola-blu | Sfondo bottoni e header |
+| `--conf-bg-page` | `#f5f5f5` | Sfondo generale pagina/stepper |
+| `--conf-radius` | `10px` | Border radius bottoni |
+| `--conf-modal-radius` | `12px` | Border radius modali |
+| `--conf-accent` | `#693DDA` | Colore accento (bordi, focus) |
+| `--conf-primary` | `#1E31EB` | Colore primario |
+| `--conf-step-selected` | `#643cda` | Freccia step selezionato |
+| `--conf-step-edit` | `#3034e7` | Freccia step completato |
+| `--conf-stepper-header-bg` | ereditato da `--conf-bg-page` | Sfondo zona superiore (header stepper) |
+| `--conf-stepper-content-bg` | ereditato da `--conf-bg-page` | Sfondo zona inferiore (form e bottoni) |
+| `--conf-step-icon-edit-bg` | ereditato da `--conf-step-edit` | Sfondo pallini step completati |
+| `--conf-btn-color` | `#ffffff` | Colore testo bottoni attivi (sfondo gradiente) |
+| `--conf-hint-btn-bg` | `#2563eb` | Sfondo bottone suggerimento rapido (lampadina) |
+| `--conf-hint-btn-hover-bg` | `#1d4ed8` | Sfondo lampadina al hover |
+| `--conf-table-header-bg` | variabile SCSS | Sfondo header tabella campi |
+| `--conf-search-bg` | variabile SCSS | Sfondo campo di ricerca |
+| `--conf-table-bg` | `#ffffff` | Sfondo righe tabella |
+| `--conf-card-bg` | `#ffffff` | Sfondo card |
+| `--conf-font-family` | `inherit` | Font dell'intero configurator |
+
+---
+
+### Modelli di configurazione
+
+#### `DynamicModuleGeneralConfig`
+
+```typescript
+const general = new DynamicModuleGeneralConfig(
+  'https://api.esempio.it/api', // baseServerUrl
+  userToken,                    // token autenticazione
+  context,                      // oggetto Context
+  null                          // EndPointConfiguration (null = usa default)
+);
+```
+
+| Proprietà | Tipo | Descrizione |
+|-----------|------|-------------|
+| `baseServerUrl` | `string` | URL base API. Usato per costruire automaticamente gli endpoint se `endPointConfiguration` è `null`. |
+| `userToken` | `string` | Token di autenticazione inviato con ogni chiamata. |
+| `endPointConfiguration` | `EndPointConfiguration \| null` | Override completo degli endpoint. `null` usa le rotte standard. |
+| `context` | `Context` | Contesto applicativo. |
+
+#### `DynamicModuleListFormRecordActionsDefault`
+
+```typescript
+const actions = new DynamicModuleListFormRecordActionsDefault();
+actions.add       = true;   // Pulsante "Aggiungi" nell'header lista
+actions.view      = true;   // Visualizza record (solo lettura)
+actions.edit      = true;   // Modifica record
+actions.duplicate = false;  // Duplica record
+actions.delete    = true;   // Elimina record
+actions.graphs    = false;  // Grafici record
+```
+
+---
+
+### Modalità di visualizzazione
+
+```typescript
+import { DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
+
+enum DynamicModuleViewModeEnum {
+  NONE            = 0,  // Nessuna visualizzazione
+  VIEW            = 1,  // Sola lettura
+  COMPILE         = 2,  // Compilazione / modifica
+  LIST            = 3,  // Lista record
+  REPAIR          = 4,  // Revisione form
+  LISTWIEW        = 5,  // Lista compatta alternativa
+  FILTER          = 6,  // Filtro / ricerca
+  GRAPHS          = 7,  // Statistiche e grafici
+  HLIST           = 8,  // Lista orizzontale
+  EXTERNAL_FILTER = 9   // Filtro guidato dal componente padre
+}
+```
+
+---
+
+### Configurazione endpoint
+
+Per default la libreria costruisce tutti gli URL dagli endpoint a partire da `baseServerUrl`. Passa un `EndPointConfiguration` custom per sovrascrivere singole rotte.
+
+```typescript
+import { EndPointConfiguration, EndPointData, RequestMethodEnum, ParamTypeEnum } from '@eqproject/eqp-dynamic-module';
+
+const endPoints = new EndPointConfiguration();
+endPoints.Records.SaveEndPoint = new EndPointData();
+endPoints.Records.SaveEndPoint.Url = 'https://custom-api.esempio.it/records/save';
+endPoints.Records.SaveEndPoint.RequestMethod = RequestMethodEnum.POST;
+endPoints.Records.SaveEndPoint.Params = [{
+  ParamName: 'orgId',
+  ParamValue: this.orgaId,
+  ParamType: ParamTypeEnum['Query param']
+}];
+```
+
+**Endpoint Records disponibili:** `GetWithContextualizationByFormCodeEndPoint`, `GetByFormIDEndPoint`, `GetByFormCodeEndPoint`, `GetAllByEntAndUserIDEndPoint`, `GetByIDEndPoint`, `SaveEndPoint`, `DuplicateEndPoint`, `DeleteEndPoint`, `RepairEndPoint`, `ApplyFilter`, `GetAllAttachmentsEndPoint`.
+
+**Endpoint Forms disponibili:** `GetByIDEndPoint`, `GetAllFormEndPoint`, `GetByIDAndVersionEndPoint`, `SaveEndPoint`, `SaveAttachmentEndPoint`, `ExportByIDEndPoint`, `GetAttachmentWithBases64`, `SpeechToFormEditEndPoint`.
+
+---
+
+### Modelli dati
+
+#### `Record`
+
+| Proprietà | Tipo | Descrizione |
+|-----------|------|-------------|
+| `ID` | `string` | Identificatore unico. |
+| `EntID` | `string` | ID del form (entità) di appartenenza. |
+| `Version` | `number` | Versione del form al momento della compilazione. |
+| `userID` | `string` | ID utente che ha creato il record. |
+| `AnswerDate` | `string` | Data di compilazione (ISO). |
+| `HTMLreadableValues` | `string` | Valori in formato HTML leggibile. |
+| `AdditionalParams` | `any` | Parametri aggiuntivi. |
+| `AdditionalInfo` | `any` | Informazioni aggiuntive. |
+
+---
+
+### Tipi di campo
+
+| Valore | Chiave | Descrizione |
+|--------|--------|-------------|
+| `1` | `Campo di testo` | Input testo singola riga. |
+| `2` | `Area di testo` | Textarea multiriga. |
+| `3` | `Booleano` | Checkbox / toggle. |
+| `4` | `Data e/ora` | Selettore data e/o ora. |
+| `5` | `Campo numerico` | Input numerico con maschera. |
+| `6` | `Allegato` | Upload file. |
+| `7` | `Immagine` | Upload immagine con crop. |
+| `8` | `Elenco generico` | Dropdown / selezione multipla. |
+| `9` | `Lookup` | Lookup server-side con query configurabile. |
+| `10` | `Form di dettaglio` | Form di dettaglio annidato. |
+| `11` | `Elenco immagini` | Selettore lista immagini. |
+| `12` | `Etichetta` | Solo visualizzazione. |
+| `13` | `Immagine con markers` | Immagine con annotazioni interattive. |
+| `14` | `Bottone` | Campo pulsante azione. |
+
+---
+
+## English version
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Module Setup](#module-setup)
+- [Components](#components)
+  - [eqp-dynamic-module — Form Viewer/Filler](#eqp-dynamic-module--form-viewerfiller)
+  - [eqp-dynamic-module-configurator — Form Builder](#eqp-dynamic-module-configurator--form-builder)
+- [Configuration Models](#configuration-models)
+- [View Modes](#view-modes)
+- [Endpoint Configuration](#endpoint-configuration)
+- [Data Models](#data-models)
+- [Field Types Reference](#field-types-reference)
+
+---
+
+### Overview
+
+`@eqproject/eqp-dynamic-module` exposes **two public components**:
+
+| Component | Purpose |
+|-----------|---------|
+| `<eqp-dynamic-module>` | Runtime form viewer, filler, list, filter and graphs |
+| `<eqp-dynamic-module-configurator>` | No-code form builder (create, edit, import, export) |
+
+Forms are defined as JSON structures stored server-side and fetched at runtime. The library handles rendering, validation, data retrieval, CRUD operations and advanced features like formulas, triggers, action buttons and speech-to-text.
+
+---
+
+### Prerequisites
+
+```bash
+npm install @angular/cdk@^15.1.2 @angular/material@^15.1.2 @angular/material-luxon-adapter@^15.2.9 --legacy-peer-deps
+npm install sweetalert2@^11.4.24 --legacy-peer-deps
+```
+
+> All `npm install` commands for this library require `--legacy-peer-deps`.
+
+---
+
+### Installation
+
+```bash
+npm install @eqproject/eqp-dynamic-module --legacy-peer-deps
+```
+
+---
+
+### Module Setup
+
+```typescript
+import { EqpDynamicModuleModule } from '@eqproject/eqp-dynamic-module';
+
+@NgModule({
+  imports: [EqpDynamicModuleModule]
+})
+export class AppModule {}
+```
+
+Add Angular Material theme to `angular.json` styles:
+
+```json
+"styles": [
+  "node_modules/@angular/material/prebuilt-themes/indigo-pink.css",
+  "src/styles.css"
+]
+```
+
+---
+
+### Components
+
+#### `eqp-dynamic-module` — Form Viewer/Filler
+
+**Basic usage**
+
+```typescript
+import { DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';
+
+generalConfig = new DynamicModuleGeneralConfig(
+  'https://your-api.example.com/api',
+  this.userToken,
+  this.context,
+  null
+);
+```
+
+```html
+<eqp-dynamic-module
+  [configurations]="generalConfig"
+  [formID]="'your-form-id'"
+  [starterViewMode]="DynamicModuleViewModeEnum.LIST"
+  [userID]="currentUser.id"
+  (saveRecord)="onSave($event)"
+  (afterSaveRecord)="onAfterSave($event)">
+</eqp-dynamic-module>
+```
+
+**Inputs**
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `configurations` | `DynamicModuleGeneralConfig` | — | **Required.** Server connection configuration. |
+| `formID` | `string` | — | **Required.** ID of the form to display. |
+| `starterViewMode` | `DynamicModuleViewModeEnum` | `LIST` | Initial view mode. |
+| `userID` | `string` | `"0"` | User ID stamped on saved records. |
+| `orgaID` | `string` | `"0"` | Organization ID. |
+| `showTitle` | `boolean` | `true` | Show/hide the form name. |
+| `showBackButton` | `boolean` | `true` | Show/hide the back button. |
+| `showSaveButton` | `boolean` | `true` | Show/hide the save button. |
+| `values` | `Record[]` | `null` | Pre-loaded records for LIST mode. |
+| `FormJSON` | `string` | `""` | Form JSON string for REPAIR mode. |
+| `formulaObject` | `any` | `{}` | Context object for formula evaluation. |
+| `selectedRecord` | `Record \| string` | `null` | Pre-select a record by object or ID. |
+| `externalButtons` | `RecordButton[]` | `[]` | Extra buttons in the record action menu. |
+| `actionButtons` | `ActionButton[]` | `[]` | Action buttons for `Bottone` field type. |
+| `defaultListActions` | `DynamicModuleListFormRecordActionsDefault` | all `true` | Toggle default list actions. |
+| `listViewRecordTitle` | `string[]` | `[]` | Field keys composing the accordion title. |
+| `defaultListViewFunction` | `Function` | `null` | Custom function called on list load. |
+| `onSaveBackToList` | `boolean` | `false` | Return to LIST after save. |
+| `onBackTo` | `DynamicModuleViewModeEnum` | `null` | View mode for the back button. |
+| `numberOfColumns` | `number` | `3` | Number of layout columns. |
+| `showHiddenFields` | `boolean` | `true` | Show/hide hidden fields. |
+| `filterResultViewMode` | `DynamicModuleFilterResultViewModeEnum` | `INTERNAL_EQPTABLE` | Filter results display mode. |
+| `additionalParams` | `any` | `null` | Extra params for server filter calls. |
+| `additionalInfo` | `any` | `null` | Extra data for client-side operations. |
+| `prefilterParams` | `any` | `null` | Pre-filter parameters. |
+| `updateInfo` | `any` | `null` | Data to update response values after load. |
+| `contestualizationParams` | `any` | `null` | Contextualisation parameters. |
+| `showNewSearchButton` | `boolean` | `true` | Show/hide the new search button. |
+| `highlightFilter` | `any` | — | Row/field highlighting configuration. |
+| `isDraggableListView` | `boolean` | `true` | Enable drag-and-drop in list view. |
+| `Statistic` | `FilterStatistic` | `null` | Statistics and filter configuration. |
+| `QueryEditorComponent` | `any` | — | Custom query editor component for lookups. |
+| `debugMode` | `boolean` | `false` | Enable verbose console logging. |
+
+**Outputs**
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `(saveRecord)` | `Record` | Emitted on save when **no** save endpoint is configured. |
+| `(afterSaveRecord)` | `Record` | Emitted after server save call completes. |
+| `(deleteRecord)` | `Record` | Emitted on delete when **no** delete endpoint is configured. |
+| `(afterDeleteRecord)` | `Record` | Emitted after server delete call completes. |
+| `(SaveJSON)` | `string` | Emitted when form JSON is exported. |
+| `(afterFilter)` | `DynRecord[]` | Emitted after filter operation with result set. |
+| `(dragStarted)` | `Record` | Emitted when drag starts. |
+| `(dragReleased)` | `void` | Emitted when drag ends. |
+| `(clickDragIndicator)` | `Record` | Emitted when drag handle is clicked. |
+| `(out)` | `eventOut` | General-purpose external output. |
+| `(fireTrigger)` | `FireTrigger` | Emitted when a trigger fires. |
+| `(afterOutputExternalFilters)` | `FilterStatistic` | Emitted after external filters applied. |
+
+---
+
+#### `eqp-dynamic-module-configurator` — Form Builder
+
+**Usage modes**
+
+```html
+<!-- Create new form -->
+<eqp-dynamic-module-configurator
+  *ngIf="config"
+  [configurations]="config"
+  (saveFormEvent)="onFormSaved($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Edit existing form -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [formID]="formID"
+  (saveFormEvent)="onFormSaved($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Export form -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [formID]="formID"
+  [viewMode]="'Export'"
+  (saveFormEvent)="onFormSaved($event)">
+</eqp-dynamic-module-configurator>
+
+<!-- Import from JSON -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [formID]="null"
+  [viewMode]="'Export'"
+  (saveFormEvent)="onFormSaved($event)">
+</eqp-dynamic-module-configurator>
+```
+
+**Inputs**
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `configurations` | `DynamicModuleConfiguratorConfig` | — | **Required.** Configuration container. |
+| `formID` | `string` | `null` | Form ID to edit. `null` creates a new form. |
+| `viewMode` | `string` | `"addOrEdit"` | `"addOrEdit"` or `"Export"`. |
+| `fieldsExtraConfig` | `FieldExtraConfig[]` | — | Extra configuration for specific fields. |
+| `triggers` | `any` | — | Trigger definitions for the editor. |
+| `actionButtons` | `any` | — | Action button definitions. |
+| `contestualization` | `Contestualization[]` | — | Contextualisation options. |
+| `formulaObject` | `any` | — | Context for formula preview. |
+| `QueryEditorComponent` | `DynamicLoaderDirectiveData` | — | Custom query editor component. |
+| `debugMode` | `boolean` | `false` | Enable verbose logging. |
+| `configuratorTheme` | `Record<string, string> \| null` | `null` | CSS variable overrides via TypeScript object. |
+| `configuratorThemeCss` | `string \| null` | `null` | CSS variable overrides via CSS text string (e.g. contents of a `.css` file). |
+
+**Outputs**
+
+| Output | Payload | Description |
+|--------|---------|-------------|
+| `(saveFormEvent)` | `Form` | Emitted on save when **no** save endpoint is configured. |
+| `(afterSaveFormEvent)` | `Form` | Emitted after server save call completes. |
+| `(out)` | `eventOut` | General-purpose external output. |
+| `(fireTrigger)` | `FireTrigger` | Emitted when a trigger fires. |
+
+**Theming**
+
+The configurator exposes a theming system based on CSS custom properties. All values injected via the theme inputs are applied with `!important` and cannot be overridden externally except through these inputs.
+
+```html
+<!-- Option A: TypeScript object -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [configuratorTheme]="{ '--conf-gradient': 'linear-gradient(to right, #1565c0, #0288d1)' }">
+</eqp-dynamic-module-configurator>
+
+<!-- Option B: CSS file loaded as string -->
+<eqp-dynamic-module-configurator
+  [configurations]="config"
+  [configuratorThemeCss]="themeCssString">
+</eqp-dynamic-module-configurator>
+```
+
+CSS file format for `configuratorThemeCss` (no selector required):
+
+```css
+--conf-gradient:           linear-gradient(to right, #1565c0, #0288d1);
+--conf-bg-page:            #f0f6fb;
+--conf-btn-color:          #ffffff;
+```
+
+Available variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--conf-gradient` | purple-blue gradient | Button and header background |
+| `--conf-bg-page` | `#f5f5f5` | General page/stepper background |
+| `--conf-radius` | `10px` | Button border radius |
+| `--conf-modal-radius` | `12px` | Modal border radius |
+| `--conf-accent` | `#693DDA` | Accent colour (borders, focus) |
+| `--conf-primary` | `#1E31EB` | Primary colour |
+| `--conf-step-selected` | `#643cda` | Selected step arrow |
+| `--conf-step-edit` | `#3034e7` | Completed step arrow |
+| `--conf-stepper-header-bg` | inherited from `--conf-bg-page` | Upper zone background (stepper header) |
+| `--conf-stepper-content-bg` | inherited from `--conf-bg-page` | Lower zone background (form and buttons) |
+| `--conf-step-icon-edit-bg` | inherited from `--conf-step-edit` | Completed step icon background |
+| `--conf-btn-color` | `#ffffff` | Active button text colour (gradient background) |
+| `--conf-hint-btn-bg` | `#2563eb` | Quick-suggestion button (lightbulb) background |
+| `--conf-hint-btn-hover-bg` | `#1d4ed8` | Lightbulb button hover background |
+| `--conf-table-header-bg` | SCSS variable | Field table header background |
+| `--conf-search-bg` | SCSS variable | Search field background |
+| `--conf-table-bg` | `#ffffff` | Table row background |
+| `--conf-card-bg` | `#ffffff` | Card background |
+| `--conf-font-family` | `inherit` | Configurator-wide font family |
+
+---
+
+### Configuration Models
+
+#### `DynamicModuleGeneralConfig`
+
+```typescript
+const general = new DynamicModuleGeneralConfig(
+  baseServerUrl,        // string — e.g. "https://api.example.com/api"
+  userToken,            // string — auth token
+  context,              // Context
+  endPointConfiguration // EndPointConfiguration | null
+);
+```
+
+#### `DynamicModuleListFormRecordActionsDefault`
+
+```typescript
+const actions = new DynamicModuleListFormRecordActionsDefault();
+actions.add       = true;
+actions.view      = true;
+actions.edit      = true;
+actions.duplicate = false;
+actions.delete    = true;
+actions.graphs    = false;
+```
+
+---
+
+### View Modes
+
+```typescript
+enum DynamicModuleViewModeEnum {
+  NONE            = 0,
+  VIEW            = 1,
+  COMPILE         = 2,
+  LIST            = 3,
+  REPAIR          = 4,
+  LISTWIEW        = 5,
+  FILTER          = 6,
+  GRAPHS          = 7,
+  HLIST           = 8,
+  EXTERNAL_FILTER = 9
+}
+```
+
+---
+
+### Endpoint Configuration
+
+```typescript
+const endPoints = new EndPointConfiguration();
+endPoints.Records.SaveEndPoint = new EndPointData();
+endPoints.Records.SaveEndPoint.Url = 'https://custom-api.example.com/records/save';
+endPoints.Records.SaveEndPoint.RequestMethod = RequestMethodEnum.POST;
+endPoints.Records.SaveEndPoint.Params = [{
+  ParamName: 'orgId',
+  ParamValue: this.orgaId,
+  ParamType: ParamTypeEnum['Query param']
+}];
+const general = new DynamicModuleGeneralConfig(baseUrl, token, context, endPoints);
+```
+
+**Available Records endpoints:** `GetWithContextualizationByFormCodeEndPoint`, `GetByFormIDEndPoint`, `GetByFormCodeEndPoint`, `GetAllByEntAndUserIDEndPoint`, `GetByIDEndPoint`, `SaveEndPoint`, `DuplicateEndPoint`, `DeleteEndPoint`, `RepairEndPoint`, `ApplyFilter`, `GetAllAttachmentsEndPoint`.
+
+**Available Forms endpoints:** `GetByIDEndPoint`, `GetAllFormEndPoint`, `GetByIDAndVersionEndPoint`, `SaveEndPoint`, `SaveAttachmentEndPoint`, `ExportByIDEndPoint`, `GetAttachmentWithBases64`, `SpeechToFormEditEndPoint`.
+
+---
+
+### Data Models
+
+#### `Record`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ID` | `string` | Unique record identifier. |
+| `EntID` | `string` | ID of the form this record belongs to. |
+| `Version` | `number` | Form version at compilation time. |
+| `userID` | `string` | ID of the user who created the record. |
+| `AnswerDate` | `string` | ISO date string of compilation. |
+| `HTMLreadableValues` | `string` | Pre-rendered HTML of field values. |
+| `AdditionalParams` | `any` | Extra parameters. |
+| `AdditionalInfo` | `any` | Extra information. |
+
+---
+
+### Field Types Reference
+
+| Value | Key | Description |
+|-------|-----|-------------|
+| `1` | `Campo di testo` | Single-line text input. |
+| `2` | `Area di testo` | Multi-line textarea. |
+| `3` | `Booleano` | Checkbox / boolean toggle. |
+| `4` | `Data e/ora` | Date and/or time picker. |
+| `5` | `Campo numerico` | Numeric input with mask. |
+| `6` | `Allegato` | File attachment upload. |
+| `7` | `Immagine` | Image upload with optional cropping. |
+| `8` | `Elenco generico` | Dropdown / multi-select list. |
+| `9` | `Lookup` | Server-side lookup with configurable query. |
+| `10` | `Form di dettaglio` | Embedded detail (inner) form. |
+| `11` | `Elenco immagini` | Image selector list. |
+| `12` | `Etichetta` | Display-only label. |
+| `13` | `Immagine con markers` | Image with interactive annotation markers. |
+| `14` | `Bottone` | Action button field. |