# @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.11.0
- **Bugfix critico — pagina Trigger che si rompeva completamente:** `trigger-creator.component.ts` andava in eccezione in `ngOnInit()` quando il tipo di trigger salvato in precedenza (`trigger.execution`) non era più presente nel catalogo formule corrente (es. rimosso o rinominato dopo il salvataggio): l'intera pagina di modifica dei trigger diventava inutilizzabile. Ora il caso viene gestito esplicitamente — si resetta `selectedFormula` e si continua a popolare normalmente la select "Tipo Trigger", senza bloccare il resto del componente.
- **Bugfix — condizioni dei trigger rotte per i campi Modulo Dinamico (DMMODULE):** in `trigger-creator` e `action-button-creator`, l'elenco dei form (usato per popolare i campi di tipo `DMMODULE`) veniva ricaricato dal server ad ogni cambio di "Tipo Trigger"/"Tipo Action Button", sovrascrivendo temporaneamente `res.object` prima che la risposta arrivasse. Aggiunto `ensureModulesLoaded()`: la chiamata al server avviene solo la prima volta per apertura di modale, le volte successive si riusa `this.forms` già scaricato. Aggiunta anche una validazione minima (`isValid()`) che impedisce il salvataggio di un trigger senza descrizione o senza tipo selezionato.
- **Fix build da sorgente — tipi TypeScript per `fabric`:** aggiunto `@types/fabric` alle `devDependencies` della libreria; senza questi tipi `tmw-image-drawer`/`tmw-image-marker` (usati dal campo "Immagine con markers") non compilavano (`Cannot find module 'fabric'`). Aggiunto anche un cast esplicito a `HTMLCanvasElement` nell'inizializzazione di `fabric.Canvas` in entrambi i componenti. Nessun impatto sui consumatori della libreria pubblicata (i tipi servono solo in fase di sviluppo/build).
- **Fix ambiente di sviluppo — disallineamento versione `tmw-icons`:** nel workspace del monorepo la copia di `tmw-icons` installata dentro `projects/eqp-dynamic-module/node_modules` era rimasta bloccata alla `0.1.1` (lockfile non aggiornato) mentre l'app host ne installava la `0.1.3`, causando due classi `TmwIconComponent` fisicamente distinte e un errore di compilazione Angular (`NG3004: Unable to import class TmwIconComponent`) che a cascata rompeva l'intera compilazione dell'app host. Nessun cambio di dipendenza dichiarata (resta `^0.1.1`), solo riallineamento del lockfile locale.
- **Versione 2.11.0:** consolida in un'unica release la migrazione completa `eqp-*` → `tmw-*` portata avanti nelle versioni 2.10.94–2.10.103 (vedi le voci sottostanti) insieme ai fix qui sopra.

- **Critical bugfix — Trigger page completely breaking:** `trigger-creator.component.ts` threw in `ngOnInit()` whenever a previously saved trigger type (`trigger.execution`) was no longer present in the current formula catalog (e.g. removed or renamed after saving): the entire trigger edit page became unusable. This case is now handled explicitly — `selectedFormula` is reset and the "Trigger Type" select is still populated normally, without blocking the rest of the component.
- **Bugfix — broken trigger conditions for Dynamic Module fields (DMMODULE):** in `trigger-creator` and `action-button-creator`, the forms list (used to populate `DMMODULE`-type fields) was re-fetched from the server on every "Trigger Type"/"Action Button Type" change, temporarily wiping `res.object` before the response arrived. Added `ensureModulesLoaded()`: the server call now happens only the first time per modal opening, subsequent changes reuse the already-fetched `this.forms`. Also added minimal validation (`isValid()`) preventing a trigger from being saved without a description or a selected type.
- **Source-build fix — TypeScript types for `fabric`:** added `@types/fabric` to the library's `devDependencies`; without these types `tmw-image-drawer`/`tmw-image-marker` (used by the "Image with markers" field) failed to compile (`Cannot find module 'fabric'`). Also added an explicit cast to `HTMLCanvasElement` when initializing `fabric.Canvas` in both components. No impact on consumers of the published library (the types are only needed at development/build time).
- **Dev environment fix — `tmw-icons` version mismatch:** inside the monorepo workspace, the `tmw-icons` copy installed under `projects/eqp-dynamic-module/node_modules` was stuck at `0.1.1` (stale lockfile) while the host app installed `0.1.3`, resulting in two physically distinct `TmwIconComponent` classes and an Angular compile error (`NG3004: Unable to import class TmwIconComponent`) that cascaded into breaking the entire host app build. No change to the declared dependency (still `^0.1.1`), just a local lockfile realignment.
- **Version 2.11.0:** consolidates into a single release the complete `eqp-*` → `tmw-*` migration carried out across versions 2.10.94–2.10.103 (see entries below) together with the fixes above.

### 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. |