@esfaenza/flow-builder 20.3.39 → 20.3.41

package/README.md

@@ -349,7 +349,11 @@ Tre cose che il modello non mostra e il form dice:
 - le regole di visibilita' si rivalutano **sui valori appena inviati**, i campi nascosti vengono
   **azzerati** e solo i visibili vengono validati;
 - `choiceReferences` accetta **solo** `Choice` e `DynamicChoiceSet`, e gli output automatici di un
-  `ComponentInstance` sono esclusivi con i suoi `outputParameters`.
+  `ComponentInstance` sono esclusivi con i suoi `outputParameters`;
+- `autoSelectSingleChoice` fa prendere al campo l'**unica** opzione risolta, quando e' una sola: e'
+  la tendina che dipende da un'altra tendina — i CAP di un comune — dove chiedere di scegliere non
+  decide niente. La spunta compare solo dove il tipo `acceptsChoices`, e altrove e'
+  `SCREEN_FIELD_CONFIGURATION_INVALID` (avviso).
 
 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».
@@ -400,7 +404,9 @@ Le tre cose che riguardano l'editor, e non il runtime:
 - **un trigger senza campo e senza `initBehavior` non scattera' mai**
   (`SCREEN_TRIGGER_WITHOUT_CAUSE`), e l'unico `initBehavior` ammesso e' `runOnLoad` — il
   `runOnRevisit` della specifica Salesforce e' `SCREEN_TRIGGER_INIT_BEHAVIOR_UNKNOWN`, e vale la
-  pena saperlo perche' chi arriva da quella specifica lo scrive per abitudine.
+  pena saperlo perche' chi arriva da quella specifica lo scrive per abitudine. Dove il campo
+  osservato ha un `defaultValue` il form dice che `runOnLoad` **non serve**: un campo precompilato
+  dal flow conta come un campo che ha preso un valore, e l'action gira comunque all'arrivo.
 
 Le action si aprono **una alla volta**: i cataloghi delle action e dei loro parametri dipendono da
 `actionType`/`actionName`, e tenerne N in volo sarebbe N volte la corsa fra risposte che l'inspector
@@ -489,6 +495,16 @@ sapere: le globali sono di sola lettura, membri compresi — le assegnabili sono
 `$Flow.ActiveStages` e i campi di `$Record` — e il picker lo dice con `TARGET_NOT_WRITABLE` invece
 di far sembrare il nome inesistente (§5.2).
 
+**Uno scope puo' nominarsi da solo.** `$Profile` senza percorso e' un riferimento valido se — e solo
+se — l'host lo dichiara così, con una voce **senza punto** che porta il suo `dataType` e il suo
+`objectType` (§4.1): e' come un host espone l'utente corrente come un'unica istanza invece di
+elencarne i campi, e da lì la navigazione riparte, quindi `$Profile.Livello` si verifica sui membri
+della classe senza che il catalogo dichiari un percorso per ognuno. Il prefisso dichiarato piu' lungo
+e' la stessa regola di prima: la voce senza punto e' il prefisso **vuoto**, cioe' quello che vince
+solo quando nessun altro corrisponde. Dove lo scope dichiara percorsi ma non la voce senza punto,
+`$Profile` da solo resta `GLOBAL_UNKNOWN`: nella demo e' la differenza fra `$Profile` (dichiarato
+così) e `$User` (che dichiara i suoi campi).
+
 Su una destinazione la colonna che decide non e' la stessa nei due mondi: un membro porta il proprio
 `isWritable`, un campo no. Fuori da un Create o da un Update il contesto non c'e' — un Assignment su
 `Cliente.Codice` non sa se quel record verra' creato o aggiornato — quindi lì basta `isCreateable`
@@ -575,6 +591,19 @@ aggiunte. Tre esiti restano distinti e nessuno dei tre e' «formula valida»: pr
 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.
 
+**Testo con merge field (§5.12).** Il messaggio di un Custom Error non e' una casella di testo
+qualunque: supporta i segnaposto `{!...}` come il testo di un text template e le scritte di uno screen
+dinamico, e lì servono piu' che altrove — *«L'ordine e' già stato evaso»* senza il numero dell'ordine e'
+meta' messaggio. Lo monta `<fb-merge-text-editor>`, ed e' un componente diverso dall'editor di formule
+perche' il contenuto e' diverso: qui c'e' una **frase**, con dentro delle isole. Tre conseguenze. Offre
+l'**inserimento** di un riferimento (un bottone con l'elenco, piu' i suggerimenti mentre si scrive dentro
+un `{!` aperto), e scrive l'isola intera, graffe comprese: la sintassi non deve stare a memoria. Manda il
+testo al motore **solo se contiene `{!`**, perche' una frase in italiano mandata a un motore di
+espressioni si farebbe accusare parola per parola. E gli esiti restano i tre delle formule, con la stessa
+regola: nessuna spunta su un testo che nessuno ha guardato. Lo stesso controllo avviene nella validazione
+del documento, con `usage: "Text"` e il rilievo sul path `customErrorMessages[n].errorMessage`: un refuso
+dentro una graffa non si scopre davanti a chi sta usando il flow.
+
 **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
@@ -849,7 +878,7 @@ distribuire e nessuna dipendenza da un font di icone dell'applicazione ospite.
 | 13 | **Testo e numero non si confrontano** (`CONDITION_TYPE_MISMATCH`) | `ConditionEditorComponent` conosce il tipo del lato sinistro da `POST /flows/references`: filtra gli operatori applicabili, guida il campo del letterale del secondo operando e segnala la coppia vietata. La regola sta in `core/condition-types.util.ts`, che salta gli operatori con semantica propria (`Contains`, `In`, …). I numeri si scrivono in cultura invariante: `1234,50` viene tradotto in `1234.50`, non troncato |
 | 14 | **`None` non e' un operatore, e' un "da completare"** | Condizione evidenziata come incompleta, con il conteggio in testa alla sezione e la frase «la bozza si salva, l'attivazione no»; il validatore della demo lo emette come **errore** |
 | 15 | **Un valore data senza `Z` significa ora locale** | `ValueEditorComponent` ha un selettore «Ora locale / UTC (Z)», dice che cambiare fuso riscrive l'orario e non lo converte, e toglie il suffisso solo per il controllo `datetime-local`, che con il fuso resterebbe vuoto |
-| 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` dove serve una destinazione. 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) |
+| 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` |