@esfaenza/flow-builder 20.3.14 → 20.3.16

package/README.md

@@ -129,6 +129,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 |---|---|
 | `validateDefinition(definition)` | astratto — e' il pannello dei problemi |
 | `validateVersion(flowName, version)` | opzionale |
+| `validateFormula(request)` | opzionale — verifica **una** espressione mentre si digita, ed e' cio' che alimenta `<fb-formula-editor>`. Unica primitiva di analisi con un involucro: il documento sta sotto `flow`, insieme a `expression`, `usage` e `expectedDataType` (§6.3, §6.4). I rilievi portano `position`/`length`, che la validazione dell'intero documento non ha. Tre esiti da tenere distinti e nessuno dei tre e' «formula valida»: rifiuto `MissingService` (primitiva assente), `isVerified: false` (primitiva sì, motore non configurato), `isValid` (verificata davvero) |
 
 | §6.4 Dizionari e cataloghi | |
 |---|---|
@@ -221,10 +222,37 @@ stesso che avra' sul canvas. `core/element-variants.ts` tiene la mappa tipo →
 discriminatore; i valori restano nel dizionario del backend (`collectionProcessorTypes`), e
 senza quel dizionario il tipo torna a essere una voce sola.
 
-**Inspector.** Un form per ogni tipo supportato: Start, Screen, Assignment, Decision, Loop,
-Collection Processor, Get / Create / Update / Delete / Rollback Records, Action, Script,
-Subflow, Wait, Custom Error, Transform, Orchestrated Stage. Più l'intestazione comune con la
-rinomina, che **riscrive tutti i riferimenti** all'elemento.
+**Inspector.** Un form per ogni tipo supportato: Start, Screen, Screen dinamico, Assignment,
+Decision, Loop, Collection Processor, Get / Create / Update / Delete / Rollback Records,
+Action, Script, Subflow, Wait, Custom Error, Transform, Orchestrated Stage. Più l'intestazione
+comune con la rinomina, che **riscrive tutti i riferimenti** all'elemento.
+
+**Screen dinamico (§5.2).** È un **compositore**, non un form, e per questo la dialog e' larga il
+doppio di com'era: **tre colonne**. A sinistra la palette (due schede — i componenti, e i campi di
+un'entita' che portano tipo ed etichetta dallo schema), al centro **la schermata disegnata** (si
+clicca il campo da configurare, lo si trascina dove deve stare, la larghezza in dodicesimi si
+vede), a destra le proprieta' di cio' che e' selezionato — o della schermata, se non c'e'
+selezione, che e' anche cio' che si ottiene cliccando l'anteprima fuori dai campi. L'anteprima e'
+inerte di proposito: i controlli non ricevono il puntatore, perche' un input che accetta testo in
+un editor di metadati fa credere di star compilando la schermata. Quali proprieta' mostrare **lo
+decide il dizionario**
+(`screenFieldTypes` e i suoi flag `storesValue`, `isCollection`, `acceptsChoices`, `isContainer`,
+`requiresDataType`), non il codice: sono gli stessi flag che applica il runtime, e
+reimplementarli porta a proporre configurazioni che il motore rifiuta.
+
+Tre cose che il modello non mostra e il form dice:
+
+- un campo che raccoglie un valore **e' una risorsa del flow**, referenziabile per nome ovunque
+  e di **sola lettura** — il suo nome vive nello spazio dei nomi comune, e rinominarlo riscrive i
+  riferimenti (`FlowDocumentStore.renameScreenField`, come per i node: nessuna primitiva del
+  backend lo fa);
+- le regole di visibilita' si rivalutano **sui valori appena inviati**, i campi nascosti vengono
+  **azzerati** e solo i visibili vengono validati;
+- `choiceReferences` accetta **solo** `Choice` e `DynamicChoiceSet`, e gli output automatici di un
+  `ComponentInstance` sono esclusivi con i suoi `outputParameters`.
+
+Il riordino e l'annidamento si fanno trascinando (`@angular/cdk/drag-drop`, senza drop list: il
+bersaglio si calcola dal DOM) oppure con i comandi «su / giu' / porta fuori».
 
 Sullo stage di orchestrazione il form dice le tre cose che il modello non mostra: gli step
 **non sono una sequenza** (le frecce riordinano l'esame, non l'esecuzione), ingresso e uscita
@@ -334,6 +362,27 @@ vuoto resta "non lo so" — primitiva non esposta, tipo senza valori dichiarati,
 da scegliere — e allora il valore si digita; con l'elenco popolato un valore fuori elenco e' un
 **avviso**, perche' nessun codice della §7 lo blocca ed e' l'editor ad accorgersene prima del runtime.
 
+**Formule.** L'espressione va al motore di regole e la sua sintassi resta del motore: la libreria
+non ha nessun parser. Cio' che ha e' il **controllo**, `validateFormula` (`POST /flows/validate-formula`,
+§6.3), chiesto con debounce mentre si digita: risponde lo stesso motore, e i suoi rilievi portano la
+**posizione** del tratto sbagliato. Li mostra `<fb-formula-editor>`, che monta la casella e sotto
+l'elenco dei rilievi, ognuno con un bottone che **seleziona quel tratto** nella casella — senza il
+salto, `position` resterebbe un numero da contare a mano. Lo stesso componente offre i nomi
+citabili come **autocompletamento** mentre si scrive un identificatore: la fonte e'
+`POST /flows/references`, la stessa del reference picker, output automatici compresi; frecce per
+scorrere, Invio o clic per inserire. Elenco non disponibile = nessun suggerimento e nessuna
+accusa — la formula si scrive lo stesso. Lo usano tutti i punti in cui si scrive
+un'espressione: la risorsa `Formula`, la modalita' Formula di una condizione, la `filterFormula`
+di un filtro, la regola di validazione di un campo di screen dinamico e il `formulaExpression`
+dentro un valore. A ogni punto corrispondono un `usage` e un `expectedDataType` — `Boolean` per
+condizioni e validation rule, il tipo dichiarato per una risorsa — e mandarli e' cio' che permette
+al motore di dire «qui serve un booleano» invece di accettare un'espressione che fallira' davanti
+all'utente. Il documento si manda **in lavorazione**: una formula cita le variabili appena
+aggiunte. Tre esiti restano distinti e nessuno dei tre e' «formula valida»: primitiva assente
+(`MissingService`, silenzio), `isVerified: false` (motore non configurato: si dice che non e'
+stata controllata), `isValid` (verificata davvero, ed e' l'unico caso con la spunta verde) — una
+spunta su un'espressione mai controllata e' peggio di nessuna spunta.
+
 **Un campo a `null` e' assente.** Il valore ha un campo per tipo e va valorizzato **uno e un solo**
 campo (§4.2); la §2 dice che cio' che non c'e' si omette, ma un backend che serializza tutte le
 proprieta' — `System.Text.Json` senza `IgnoreNullValues` lo fa di default — manda
@@ -406,12 +455,15 @@ src/lib/
     flow-document.store.ts   il documento come fonte di verita': flatten, CRUD, undo/redo
     flow-dictionary.store.ts cache dei dizionari e memoizzazione dei cataloghi
     flow-validation.store.ts debounce, indicizzazione dei rilievi per elemento e campo
+    formula-validation.service.ts la verifica di una singola formula, e la memoria di
+                                  "questo ambiente la primitiva non ce l'ha"
     flow-editor-session.ts   versioni, salvataggio, concorrenza ottimistica
     flow-layout.service.ts   auto-layout con dagre
     flow-name.util.ts        nomi: regexp, namespace unico, slug dalla label
     condition-logic.util.ts  riscrittura di conditionLogic su cancella / riordina
     condition-types.util.ts  quali tipi si confrontano, e i numeri in cultura invariante
     stage-step.util.ts       gli step di uno stage: nomi, output non condizionabili
+    screen-field.util.ts     l'albero dei campi di uno screen dinamico: percorsi, nomi, mutazioni
   ui/
     flow-builder.component.ts  il componente da montare
     canvas/ palette/ inspector/ resources/ problems/ versions/ debug/ shared/
@@ -442,6 +494,7 @@ Oltre ad Angular:
 |---|---|
 | `@foblex/flow` (+ `@foblex/platform`, `@foblex/mediator`, `@foblex/2d`, `@foblex/utils`) | rendering del grafo, pan/zoom, gesti su node e connessioni. Usata in *classic mode*: la libreria disegna e riconosce i gesti, lo stato resta nostro |
 | `dagre` | auto-layout gerarchico del comando «Riordina» |
+| `@angular/cdk` | il solo `drag-drop`, per l'albero dei campi dello screen dinamico. Nessun componente Material: i controlli restano input nativi |
 
 Nessun design system: i controlli sono input nativi con binding espliciti e CSS custom, così
 il builder si integra nel tema dell'app ospite senza imporre il proprio.
@@ -465,6 +518,12 @@ Le variabili si sovrascrivono sul contenitore:
 Elenco completo in `styles/flow-builder.css`. Per la variante scura basta
 `data-fb-theme="dark"` su un antenato.
 
+La dialog di modifica ha **una misura sola per ogni tipo di elemento** — l'inspector dentro
+cambia, la finestra no, altrimenti i comandi si spostano sotto il mouse a ogni apertura — e le
+due misure sono token: `--fb-dialog-width` (1400px) e `--fb-dialog-height` (860px), entrambe
+limitate allo spazio disponibile. La larghezza e' quella che serve al compositore dello screen
+dinamico, che e' a due pannelli.
+
 Nota sugli archi: il colore si imposta valorizzando le custom properties del tema di
 @foblex/flow (`--ff-connection-color`, `--ff-marker-color`) invece di sovrascrivere le sue
 regole, perche' i selettori hanno la stessa specificita' e chi vince dipenderebbe dall'ordine
@@ -523,6 +582,15 @@ possibile anche con errori e attivazione bloccata dagli errori (§8).
   vivono dentro `rules[i].connector`, ma un arco selezionato perde la selezione.
 - **`relatedRecords` di Get Records** e' esposto in sola lettura con un avviso: e' modellato
   ma non tradotto in query.
+- **La verifica delle formule e' del sistema ospite**: senza un motore configurato l'editor non
+  ha nulla da dire sulla sintassi, e lo dice — non finge una conferma. La libreria non prova a
+  supplire con un parser proprio: una grammatica indovinata segnalerebbe come sbagliate le
+  espressioni che il motore vero accetta.
+- **Il compositore dello screen dinamico non usa le drop list del CDK**: annidate sono ambigue
+  — il rettangolo di una sezione contiene quello delle sue colonne, e a ricevere il rilascio e'
+  sempre la lista registrata per prima, cioe' la radice. Il bersaglio si calcola dal DOM
+  (`elementFromPoint` per il contenitore piu' interno, i rettangoli dei fratelli per la
+  posizione).
 - **L'esecutore della demo non valuta le condizioni**: prende il primo ramo disponibile e lo
   scrive nella traccia. È un mock per esercitare il pannello, non il motore.
 - **Nessun test automatico**: la libreria e' stata verificata a mano sull'app demo (canvas,