@esfaenza/flow-builder 20.3.41 → 20.3.43

package/README.md

@@ -235,8 +235,9 @@ 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
@@ -249,6 +250,26 @@ Rimuovere una risorsa **usata** chiede conferma e dice quanti riferimenti rester
 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
@@ -316,9 +337,9 @@ orchestrazione ne resta fuori: la §7 non lo comprende.
 Un tipo con un **discriminatore** compare come piu' voci, una per valore: il Collection
 Processor e' «Ordina» e «Filtra», non «ordina o filtra». Sono due gesti diversi — un `Sort`
 vuole `sortOptions`, un `Filter` vuole condizioni (§5.6) — e sceglierli dalla palette evita di
-sceglierli dopo, dentro il form. L'elemento nasce con il discriminatore già scritto, con la
-label della variante (da cui viene anche il nome tecnico) e con il glifo della variante, lo
-stesso che avra' sul canvas. `core/element-variants.ts` tiene la mappa tipo → campo del
+sceglierli dopo, dentro il form. L'elemento nasce con il discriminatore già scritto, con il
+glifo della variante — lo stesso che avra' sul canvas — e con un nome tecnico provvisorio preso
+dalla variante. `core/element-variants.ts` tiene la mappa tipo → campo del
 discriminatore; i valori restano nel dizionario del backend (`collectionProcessorTypes`), e
 senza quel dizionario il tipo torna a essere una voce sola.
 
@@ -327,6 +348,17 @@ 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.
 
+*Nominare un elemento nuovo.* Un elemento appena creato nasce **senza etichetta**, e il suo form
+si apre con il cursore lì: il nome tecnico parte **vuoto** e si costruisce dall'etichetta mentre
+la si digita, con spazi e caratteri non ammessi sostituiti da `_` (§3.3). Nel documento un nome
+provvisorio c'e' comunque, perché il nome e' la chiave con cui tutto raggiunge l'elemento — e' anche
+cio' che il canvas mostra al posto del titolo finché l'etichetta manca — ma non e' quello che si
+legge nel campo. Scrivere il nome a mano lo sgancia dall'etichetta; svuotare il campo lo rimette a
+seguirla. Su un elemento che un'etichetta ce l'ha già il nome torna in sola lettura dietro il
+comando «Rinomina»: da lì in poi cambiarlo riscrive i riferimenti di tutto il documento (§13.8) e
+non e' un gesto da fare per sbaglio. Corollario: l'annulla riporta indietro etichetta e nome
+**insieme**, in un passo solo, e la selezione dell'editor — che e' il nome — lo segue.
+
 **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
@@ -436,6 +468,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
@@ -664,6 +716,14 @@ 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.
 
+**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
+(`$Record` non c'e' in uno screen flow, §4.1), quali elementi sono ammessi (§13.6) e come il motore
+esegue il flow, e cambiarlo su un documento già scritto lo lascia pieno di riferimenti a cose che
+da quel momento non esistono — senza che nessuna primitiva del backend rimedi. Un host che crea i
+flow da sé (come la demo) il tipo lo chiede lì, e lo passa a `emptyFlowDefinition`.
+
 **Versioni.** Elenco con stato, «Nuova versione» al posto di «Salva» sulle versioni chiuse,
 attivazione bloccata finche' ci sono errori, eliminazione dietro una conferma esplicita che
 spiega il rischio per le esecuzioni sospese.
@@ -886,7 +946,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