@esfaenza/flow-builder 20.3.43 → 20.3.45

package/README.md

@@ -244,8 +244,15 @@ fuori dallo schermo, cioe' faceva sparire il contesto per cui l'elenco esiste. L
 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.
@@ -369,8 +376,8 @@ inerte di proposito: i controlli non ricevono il puntatore, perche' un input che
 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.
+`isRepeatingSection`, `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:
 
@@ -390,6 +397,42 @@ Tre cose che il modello non mostra e il form dice:
 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».
 
+**La sezione ripetibile (§5.2).** `RepeatingSection` e' N copie della stessa struttura di campi
+sulla stessa schermata — N punti di fornitura, N referenti, N righe di un ordine — e un tasto con
+cui l'utente decide quante. Il flag che l'accende e' `isRepeatingSection`, ed e' distinto da
+`isContainer` di proposito: contiene campi, ma quelli che contiene sono il **modello di una riga**,
+non campi della schermata.
+
+Da quella distinzione discende tutto cio' che l'editor fa di diverso lì dentro, e sono le quattro
+cose che un editor ingenuo sbaglia lasciandole comporre per poi accusarle:
+
+- **i campi di una riga non sono risorse.** Esistono in una copia per ogni elemento della
+  collection, quindi il loro nome non individua alcun valore: non compaiono fra i riferimenti
+  proponibili (`resourceFieldsOf` li esclude, e la demo li toglie anche da `POST /flows/references`)
+  e nominarli e' `SCREEN_FIELD_IN_REPEATER` — un codice **diverso** da «il nome non esiste», perche'
+  quel nome nel documento c'e' e il rimedio e' un altro. Il nome resta comunque unico, perche' e'
+  l'indirizzo con cui il frontend rende il campo: un omonimo di una variabile e' `NAME_DUPLICATED`
+  come sempre, e `screenFieldNames` li comprende tutti;
+- **dentro una riga si nomina il cursore.** `collectionReference` e' dove vivono le righe (una
+  variabile collection di `Structure`), `itemReference` e' il cursore su cui il runtime appoggia la
+  riga corrente — lo stesso ruolo di `assignNextValueToReference` in un Loop. Il pannello lo dice, e
+  i selettori di riferimento del campo lo propongono **per primo** (`preferredRoots`, che riordina e
+  non aggiunge niente). Ogni incoerenza fra i due — mancante, costante invece di variabile,
+  collection scambiata col cursore, classi diverse — e' `REPEATING_SECTION_INVALID`, e l'editor la
+  dice prima della validazione;
+- **due cose che fuori sono lecite qui non lo sono**, e non si propongono affatto: la tendina dei
+  `fieldType` dentro una riga non offre la sezione ripetibile (non si annidano: il cursore e' una
+  variabile sola per sezione) e la spunta degli output automatici di un `ComponentInstance` sparisce
+  — si esporrebbero come `<NomeCampo>.<NomeOutput>`, cioe' **una risorsa sola per tutte le righe**.
+  Per lo stesso motivo un campo di riga non compare fra gli inneschi di una screen action;
+- **`memberName` e il riferimento sono la stessa domanda posta due volte.** `memberName: "PodId"` e
+  `PuntoCorrente.PodId` sono lo stesso membro, e la classe da cui vengono e' l'`objectType` della
+  variabile in `collectionReference`: il campo si sceglie da `<fb-structure-member-picker>` con
+  `usage="writable"`, perche' un membro calcolato e' `TARGET_NOT_WRITABLE`.
+
+Nell'anteprima si disegna **una** riga, ed e' il modello: a runtime la schermata ne rende una copia
+per elemento. Disegnarne due sarebbe finto — quante siano lo decide chi compila.
+
 **Transform (§5.13).** Anche questo e' un compositore e non un form: **tre colonne** — le sorgenti,
 la destinazione, il dettaglio della riga scelta. Si mappa **trascinando** una sorgente su una
 destinazione, oppure selezionando la destinazione e cliccando la sorgente; il bersaglio del rilascio
@@ -704,8 +747,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
@@ -716,6 +759,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
@@ -941,7 +1004,7 @@ distribuire e nessuna dipendenza da un font di icone dell'applicazione ospite.
 | 16 | **`Structure` e `Object` non sono intercambiabili** | `StructurePickerComponent` per la classe (fuori catalogo = **errore**, `STRUCTURE_TYPE_UNKNOWN`) e `StructureMemberPickerComponent` per i membri, filtrati su `isWritable` **soltanto** con `usage="writable"`, cioe' dove serve una destinazione: un membro calcolato si legge — in una condizione, in una formula, in un valore — e filtrarlo ovunque renderebbe invisibili proprio i membri derivati (§13.16). Il pannello risorse mostra la classe come obbligatoria con severita' di errore e **non** mostra il valore iniziale, perche' un `structureValue` non esiste; `ReferencePickerComponent` propone `Variabile.Membro` e verifica il percorso **fino in fondo** con `core/path-navigation.ts`, con `PATH_NOT_VERIFIABLE` dove la catena si interrompe; il Transform con target classe chiede un membro invece di un campo. `FlowDictionaryStore.isStructure` legge il flag dal dizionario, non dal nome del tipo. La risposta dei membri e' la **descrizione della classe** (`{className, label, members}`), e i suoi tre esiti restano distinti fino alla UI: `FlowCatalogStore.describeStructure` li traduce in `declared` / `undeclared` / `unknown-class` / `unknown-catalog`, e solo `declared` autorizza a dire che un membro non esiste (§4.7.1) |
 | 17 | **Due body diversi per due famiglie di primitive** | `HttpFlowBuilderApi`: le primitive che **analizzano** il documento — `validate`, `parse`, `references`, `references/writable`, `connector-targets`, `outline` — lo mandano **nudo alla radice**; l'involucro `{definition, flowName, …}` resta alle sole primitive di scrittura della §6.2. Sbagliare involucro non da' nessun errore: il backend legge un flow vuoto e risponde `200`. Per lo stesso motivo `getReferences`/`getWritableReferences` prendono la `FlowDefinition` e non un oggetto query: non c'e' nessun campo di filtro nel body, e il filtro di tipo lo applica l'editor con `core/reference-filter.util.ts` |
 | 18 | **Gli enum si scrivono come stringhe** | Il modello e' fatto di unioni di stringhe letterali (`FlowDataType`, `FlowVersionStatus`, …) e non di enum numerici: `JSON.stringify` non ha modo di produrre un ordinale. Conta perche' `"status": 3` non e' `Draft` ma `InvalidDraft` e `"dataType": 0` e' `String`, non "non specificato" — nessun errore lo segnalerebbe. Chi scrive un'altra implementazione di `FlowBuilderApi` non traduca i valori in numeri |
-| 19 | **Un campo di screen dinamico e' una risorsa, ma di sola lettura** | Lo restituisce `POST /flows/references` con `kind: "ScreenField"`, e il reference picker lo propone in un gruppo suo; nei selettori di **destinazione** non compare, perche' `references/writable` lo esclude. L'unica eccezione e' l'`assignToReference` di una **screen action**, dove il campo di *quella* schermata e' una destinazione e l'elenco lo passa il chiamante (`extraReferences`). Il nome entra in `FlowDocumentStore.usedNames`, quindi un campo omonimo di una variabile e' `NAME_DUPLICATED`, e `renameScreenField` riscrive i riferimenti come `renameNode` |
+| 19 | **Un campo di screen dinamico e' una risorsa, ma di sola lettura** | Lo restituisce `POST /flows/references` con `kind: "ScreenField"`, e il reference picker lo propone in un gruppo suo; nei selettori di **destinazione** non compare, perche' `references/writable` lo esclude. L'unica eccezione e' l'`assignToReference` di una **screen action**, dove il campo di *quella* schermata e' una destinazione e l'elenco lo passa il chiamante (`extraReferences`). Il nome entra in `FlowDocumentStore.usedNames`, quindi un campo omonimo di una variabile e' `NAME_DUPLICATED`, e `renameScreenField` riscrive i riferimenti come `renameNode`. **L'eccezione sono i campi dentro una `RepeatingSection`**: risorse non sono — la riga esiste una volta per elemento della collection — ma un nome unico ce l'hanno lo stesso, quindi `screenFieldNames` li comprende e `resourceFieldsOf` no; nominarli e' `SCREEN_FIELD_IN_REPEATER` |
 | 20 | **La validazione di uno screen dinamico la fa il server e non fa avanzare il flow** | Riguarda il runtime, non l'editor: `EXECUTION_FRONTEND.md` §5.5 e §6.2, e lato client `flow-execution` (`isValidationRetry`, `indexValidationErrors`). Qui l'editor fa la sua parte a monte: `validationRule` si scrive con `<fb-formula-editor>`, che la fa verificare mentre si digita (§6.3) |
 | 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 |