@esfaenza/flow-builder 20.3.44 → 20.3.45

package/README.md

@@ -376,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:
 
@@ -397,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
@@ -968,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 |