@esfaenza/flow-builder 20.3.15 → 20.3.17

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 | |
 |---|---|
@@ -139,7 +140,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | `listObjects()`, `listFields(object, usage?)` | astratti |
 | `listActionTypes` / `listActions` / `listActionParameters` | astratti |
 | `listScripts` / `listScriptParameters` | astratti |
-| `listForms` / `listFormParameters` | astratti |
+| `listForms(kind?)` / `listFormParameters` | astratti — **un catalogo, due ruoli** (§5.1, §5.2): le schermate intere di uno Screen (`formName`) e i componenti di uno screen dinamico (`extensionName`) stanno nello stesso elenco e si distinguono per `formKind`. `kind` vale `Form`, `Component` o assente per tutto; una voce **senza** `formKind` vale `Any` e resta proponibile in entrambi i posti, perche' un catalogo che il ruolo non lo dichiara non deve vietare tutto. Usare l'uno al posto dell'altro e' `FORM_KIND_MISMATCH`, che e' un errore **diverso** da «il nome non esiste». I parametri si chiedono per nome, uguali per i due ruoli |
 | `listEnumTypes`, `listEvents`, `listSubflowCandidates` | astratti |
 | `describeObject`, `listFieldValues` | opzionali |
 | `listEnumValues(enumType)` | opzionale — i **valori** di un tipo di enumerazione, cioe' i nomi scrivibili in `enumValue` (§4.2, §4.6). `listEnumTypes` e' l'altra meta' e non basta: quella dice quali tipi esistono, questa quali valori ha un tipo. `enumType` e' esattamente l'`objectType` della risorsa, del parametro o del **membro** di una classe (§4.7.1): la risposta e' del tipo, non del punto di uso, e la cache e' per nome del tipo. Lista vuota = "non lo so" — il valore si scrive a mano, e un tipo sconosciuto risponde vuoto, non 404 |
@@ -226,9 +227,15 @@ Decision, Loop, Collection Processor, Get / Create / Update / Delete / Rollback
 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).** È l'unico inspector a due pannelli, e per questo la dialog e' larga
-il doppio di com'era: a sinistra l'albero dei campi con la larghezza in dodicesimi disegnata, a
-destra le proprieta' del campo selezionato. Quali proprieta' mostrare **lo decide il dizionario**
+**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.
@@ -244,8 +251,8 @@ Tre cose che il modello non mostra e il form dice:
 - `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`) oppure con i comandi
-«su / giu' / porta dentro / porta fuori», che coprono anche gli alberi piu' alti del pannello.
+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
@@ -355,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
@@ -427,6 +455,8 @@ 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
@@ -552,13 +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.
-- **L'albero dei campi dello screen dinamico e' una lista di rilascio piatta**, non una per
-  contenitore: le drop list annidate del CDK sono ambigue proprio qui — 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. Con la lista piatta il contenitore di arrivo si deduce
-  dalla riga che precede il punto di rilascio (sotto un contenitore = dentro, sotto un campo =
-  accanto). Il prezzo: trascinando una sezione, i suoi figli restano fermi finche' non si
-  rilascia — poi si spostano con lei.
+- **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,