@esfaenza/flow-builder 20.3.42 → 20.3.44

package/README.md

@@ -235,20 +235,48 @@ il trascinamento sul canvas vuoto disegna il rettangolo di selezione invece di s
 un elemento, il canvas lo dice e dice **cosa farne**: «trascinane uno per spostarli tutti». Un
 gesto che nessuno annuncia non esiste.
 
-**Risorse.** Il pannello «Risorse» e' un **elenco**: nome, tipo, quante volte e' usata, i rilievi
-della riga. Aggiungerne una o cliccarne il nome apre una **finestra** dedicata con il form dentro,
+**Risorse.** Il pannello «Risorse» e' un **elenco**: nome, tipo — con la **classe** o l'entita'
+accanto, perche' «Structure» da solo non dice quale, e su ventun variabili la classe si leggeva
+solo aprendole una per una — quante volte e' usata, i rilievi della riga. Aggiungerne una o cliccarne il nome apre una **finestra** dedicata con il form dentro,
 come per il dettaglio di un elemento — e per la stessa ragione: il form di un dynamic choice set
 (sorgente, due campi, ordinamento, limite, filtri) dentro la colonna laterale spingeva l'elenco
 fuori dallo schermo, cioe' faceva sparire il contesto per cui l'elenco esiste. La finestra si
 sposta prendendola per l'intestazione, non ha «Annulla» — le modifiche sono già nel documento, e
 a tornare indietro e' l'annulla dell'editor — e si chiude da se' se la risorsa viene rimossa.
 
-*Quante volte e' usata.* Ogni risorsa porta il numero dei suoi usi, formule comprese; a zero
-occorrenze lo dice, ed e' l'unico modo di sapere quali delle venti variabili sono morte.
+*Quante volte e' usata.* Ogni risorsa porta il numero dei suoi usi; a zero
+occorrenze lo dice, ed e' l'unico modo di sapere quali delle venti variabili sono morte. Il
+conteggio comprende **tre** modi di citare un nome, e il `title` della riga dice quanti ce n'e'
+per ognuno, perche' sono tre posti diversi in cui andare a cercare: i campi di **riferimento**, le
+**espressioni** delle formule (`Importo * 1.22` usa `Importo`) e i **merge field** `{!…}` nei
+testi che il contratto dichiara — `interviewLabel`, il testo di un text template, `fieldText` e
+`helpText`, `choiceText`, `errorMessage` (§5.12). Senza i merge field una variabile citata da tre
+messaggi risultava «non usata», che e' esattamente l'informazione su cui si decide di
+cancellarla.
 Rimuovere una risorsa **usata** chiede conferma e dice quanti riferimenti resterebbero orfani:
 cancellare una variabile non fa sparire nessun arco dal canvas, e senza il numero il danno si
 scopriva alla validazione successiva.
 
+*Il filtro.* Sopra l'elenco c'e' una casella e due interruttori, e sono per la **scala**: un flow
+di produzione ha ventun variabili e dodici dynamic choice set, e a quella misura il problema
+dell'elenco non e' leggerlo ma trovarci dentro una riga. La casella cerca nel nome,
+nell'etichetta, nel tipo (`objectType` compreso: «address» trova le tre variabili `AddressDTO`) e
+nelle **parole dei flag** (`input`, `output`, `collection`) — cioe' in cio' che la riga mostra, ed
+e' anche il motivo per cui la riga mostra la classe — e non dentro i valori e le formule: «chi cita `Totale`» e' un'altra
+domanda, e la risponde il conteggio degli usi. I due interruttori sono invece le domande che un
+nome non sa fare: **non usate** e **con rilievi**; a zero si disabilitano, perche' un filtro che
+darebbe certamente un elenco vuoto non restringe l'elenco, lo nasconde.
+
+Il filtro **non e' la ricerca del flow**: quella (la casella in cima all'editor) sa dov'e' un nome
+che si conosce già, e arrivando su una risorsa **spegne** il filtro — altrimenti aprirebbe la
+finestra su una riga che il filtro tiene fuori dall'elenco. Qui invece si restringe un elenco che
+si sta guardando, e per questo il filtro **resta acceso cambiando scheda**: il numero accanto a
+ogni tipo diventa quello delle **corrispondenze**, ed e' cio' che dice dove sta la risorsa cercata
+— che il piu' delle volte e' in un'altra collection. Un elenco vuoto distingue i tre casi, perche'
+i rimedi sono diversi: la collection e' vuota, il filtro non trova niente **qui** ma trova
+altrove, il filtro non trova niente da nessuna parte. Aggiungere una risorsa spegne il filtro: si
+chiama «variabile_1» e non corrisponderebbe a niente di cio' che si stava cercando.
+
 **Copia, incolla, duplica.** `Ctrl`+`C` copia gli elementi selezionati — la selezione del canvas
 puo' contenerne piu' d'uno (rettangolo, `Ctrl`+`A`) — `Ctrl`+`V` li incolla, `Ctrl`+`D` li duplica in
 loco; gli stessi comandi stanno nella top bar («⧉» e «⎘») e sul node selezionato («⧉»). I tasti
@@ -447,6 +475,26 @@ compreso il **tipo** di ciascuna: senza, il valore di un filtro su `NumericValue
 casella di testo. `displayField` e `valueField` hanno un default (`Label` e `Name`) e il form li
 mostra come tali, cosi' non finiscono nel documento senza motivo.
 
+E la sorgente decide anche **quali campi esistono**: `limit`, `displayField` e `valueField`
+valgono su tutt'e tre, ma `filters`, `filterLogic`, `sortField` e `sortOrder` valgono sulle sole
+`object` — dove diventano la query — ed `enumType`, dove il runtime li valuta in memoria. Su una
+`collectionReference` le opzioni sono gli elementi della collection **nell'ordine in cui ci
+sono**: il form non offre quei controlli, e se il documento li porta lo dice con
+`CHOICE_SET_FILTERS_IGNORED` — un **avviso**, perche' il flow gira e il campo funziona, solo
+propone tutto; il difetto e' che chi l'ha scritto crede di aver selezionato qualcosa. La
+ripulitura e' un comando («Togli»), non un effetto dell'apertura del form: cancellare i filtri di
+un flow scritto altrove farebbe sparire l'unico indizio di cosa doveva selezionare. Il rilievo si
+vede in **tutti e due** i posti, elenco e form, come gli altri controlli locali.
+
+*La logica dei filtri.* `filterLogic` **esiste anche sui choice set**, con le stesse forme degli
+elementi che interrogano il database: `AND` (o assente), `OR`, oppure l'espressione sugli indici
+1-based dei filtri (`1 AND (2 OR 3)`), che l'editor verifica mentre si scrive e **riscrive** quando
+si cancella un filtro — senza, l'espressione resterebbe valida puntando al filtro sbagliato, che
+e' il peggiore dei due esiti. Il valore `Formula` invece **non e' supportato da nessun elemento**:
+non lo scrive nessun gesto dell'editor — la modalita' «Formula» scrive `filterFormula`, che e' un
+campo suo — e se arriva da un documento scritto altrove si vede un rilievo che dice cosa fare, non
+una modalita' che sembra buona.
+
 **Classi (`Structure`).** L'ottavo tipo di dato non e' un doppione di `Object` (§4.7): di
 un'istanza di classe il flow legge e scrive i **membri**. Cambia quindi il form: la classe si
 scoglie con `<fb-structure-picker>` e la sua assenza e' un **errore** — senza classe il runtime
@@ -663,8 +711,8 @@ versione attiva e' un avviso. Prima questi campi erano `<select>` con un'opzione
 «(non nel catalogo)» per non perdere il valore, oppure un `datalist` che accettava qualunque
 cosa in silenzio: il primo non si poteva cercare, il secondo non diceva niente.
 
-**Problemi.** Pannello con filtro per gravita', validazione su pausa di digitazione (debounce
-400 ms) e l'avvertenza che l'assenza di rilievi
+**Problemi.** Pannello con filtri per gravita', **testo** e **codice**, validazione su pausa di
+digitazione (debounce 400 ms) e l'avvertenza che l'assenza di rilievi
 non e' una garanzia di correttezza. Il `path` del rilievo si mostra **per nome**: il backend lo
 manda come percorso di campi e sugli screen dinamici spesso a indici
 (`fields[1].fields[1].fields[0]`), che e' esatto e inutile perche' per seguirlo si devono contare
@@ -675,6 +723,26 @@ leggendo. Ad aprire il form ci sono il bottone «✎» della riga e il doppio cl
 coppia di gesti del canvas. Per la stessa
 ragione il clic non si limita ad aprire l'elemento: **seleziona il campo** che il rilievo nomina.
 
+*I filtri.* Sono per la scala, come quelli delle risorse: il flow di produzione della demo ha 64
+rilievi e sette codici distinti, e a quella misura l'elenco si legge solo restringendolo. La
+casella cerca in cio' che la riga mostra — messaggio, codice, nome dell'elemento e **percorso
+tradotto per nome**, che e' quello che si legge sullo schermo: cercando il nome di un campo di
+screen dinamico un confronto sul path a indici non troverebbe niente. La tendina «Codici» e' una
+selezione **multipla**, perche' la domanda vera e' «fammi vedere questi tre codici» — sul flow di
+produzione i 47 errori sono quasi tutti cataloghi della demo che non conoscono quell'ambiente, e
+`OBJECT_UNKNOWN` piu' `STRUCTURE_TYPE_UNKNOWN` sono 23 righe da mettere da parte in un gesto.
+
+Tre scelte che si notano solo quando mancano. I codici elencati sono quelli **presenti** nel
+risultato, col loro conteggio, e non quelli della §7: l'elenco del contratto e' dichiarato aperto,
+e proporre codici che questo flow non ha vuol dire proporre filtri che danno zero righe. Un codice
+**selezionato** resta nell'elenco anche quando la gravita' scelta non ne contiene piu' nessuno —
+si vede a zero — altrimenti continuerebbe a filtrare senza che si possa vederlo ne' togliere. E i
+numeri sui chip della gravita' si ricalcolano sui filtri attivi, perche' il numero su un filtro
+deve essere quello che il filtro apre: «Errori 47» accanto a una casella che ne lascia passare
+tre promette quarantaquattro righe che non compariranno. L'unico numero che **non** segue i filtri
+e' quello della nota in fondo sugli errori che bloccano l'attivazione: filtrando per «Note»
+spariva proprio quando serve.
+
 **Il tipo di flow si sceglie alla creazione.** Su un flow nuovo — quello che l'editor apre senza
 `flowName` — il `processType` e' una scelta nella barra in cima; da quando il flow e' salvato
 diventa un'etichetta e non si tocca più. Non e' prudenza: il tipo decide quali globali esistono
@@ -905,7 +973,9 @@ distribuire e nessuna dipendenza da un font di icone dell'applicazione ospite.
 | 21 | **Un campo nascosto viene azzerato all'invio** | L'inspector lo dice dove si scrive la `visibilityRule`: la regola si rivaluta sui valori appena inviati e il campo che sparisce **perde** il valore. È l'unica cosa che chi disegna il flow non puo' dedurre dal metadata, e per questo sta nel form e non solo in questa tabella |
 
 Altre regole del contratto rispettate: liste vuote omesse invece di scritte come `[]` (§2),
-`filterLogic` mostrato **solo** dove il modello lo prevede (§4.4), `fullName` / `status` mai
+`filterLogic` mostrato **solo** dove il modello lo prevede — Get Records, Create Records, Start,
+eventi di un Wait e dynamic choice set, **non** Update e Delete (§4.4) — e mai col valore
+`Formula`, che nessun elemento supporta, `fullName` / `status` mai
 usati per rinominare o attivare (§2), un solo campo valorizzato in
 `FlowElementReferenceOrValue` con segnalazione e normalizzazione dei documenti ambigui (§4.2),
 `Transform.connector` e `start` trattati come array per fedelta' storica (§3.5), salvataggio