@esfaenza/flow-builder 20.3.10 → 20.3.12

package/README.md

@@ -133,7 +133,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | §6.4 Dizionari e cataloghi | |
 |---|---|
 | `getDictionaries(processType?)` | astratto — `processType` filtra le globali (§4.1) |
-| `getReferences(query)` / `getWritableReferences(query)` | astratti |
+| `getReferences(definition)` / `getWritableReferences(definition)` | astratti — prendono il **documento nudo** e restituiscono **tutti** i riferimenti: nel body non c'e' nessun filtro di tipo, e la compatibilita' col campo la decide l'editor (§6.4, §13.17) |
 | `getConnectorTargets(definition, excluding?)` | astratto |
 | `getOutline(definition)` | astratto |
 | `listObjects()`, `listFields(object, usage?)` | astratti |
@@ -142,6 +142,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | `listForms` / `listFormParameters` | astratti |
 | `listEnumTypes`, `listEvents`, `listSubflowCandidates` | astratti |
 | `describeObject`, `listFieldValues` | opzionali |
+| `listEnumValues(enumType)` | opzionale — i **valori** di un tipo di enumerazione, cioe' i nomi scrivibili in `enumValue` (§4.2, §4.6). `listEnumTypes` e' l'altra meta' e non basta: quella dice quali tipi esistono, questa quali valori ha un tipo. `enumType` e' esattamente l'`objectType` della risorsa, del parametro o del **membro** di una classe (§4.7.1): la risposta e' del tipo, non del punto di uso, e la cache e' per nome del tipo. Lista vuota = "non lo so" — il valore si scrive a mano, e un tipo sconosciuto risponde vuoto, non 404 |
 | `listStructures`, `describeStructure(className)` | opzionali — le classi e i loro membri per le risorse `Structure` (§4.7). `listStructures` e' l'**elenco delle classi** senza membri; `describeStructure` restituisce la **descrizione** di una classe (`className`, `label`, `members`), non un array nudo (§4.7.1). Senza, le classi non sono verificabili e il nome si scrive a mano: "non lo so", non "non esiste". I tre esiti sono distinti: `members` popolato = elenco autorevole, `members: []` = membri non dichiarati (si digita, nessuna accusa), rifiuto `StructureNotFound` = classe non registrata (si segnala la **classe**) |
 
 | §6.5 Esecuzione | |
@@ -203,6 +204,14 @@ qualsiasi.
 dalla mappa delle uscite invece di essere «ramo di errore» per tutti: su uno stage di
 orchestrazione quel ramo e' lo **step rifiutato**, non un guasto.
 
+La stessa mappa distingue i rami di **recupero da errore** (`isFaultRecovery`: Record\*,
+ActionCall, ScriptCall, Wait) dagli altri, perche' lasciarne uno vuoto non significa «il
+percorso finisce qui» ma «se questo fallisce l'interview termina `Failed` e le modifiche
+vengono annullate» (§3.5). L'editor delle uscite lo dice come promemoria — non col colore
+d'avviso, perche' rinunciare al recupero e' la scelta piu' comune — e il backend lo segnala
+con `FAULT_CONNECTOR_MISSING`, che e' un `Warning` e non blocca niente. Lo stage di
+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.5) — e sceglierli dalla palette evita di
@@ -254,14 +263,20 @@ Restano fuori i percorsi radicati sul risultato **automatico** di un elemento
 (`Leggi_Contatti.Owner.Name`): la validazione non li verifica, e l'editor non accusa cio' che il
 backend non verifica.
 
-Il filtro di tipo di un campo (§6.4) guarda il tipo della **radice**, e quindi non basta: in un
+Il filtro di tipo di un campo (§6.4) lo applica **l'editor**: la primitiva prende il documento nudo
+e restituisce tutti i riferimenti, così la stessa risposta serve tutte le tendine di una schermata
+(§13.17). La regola sta in `core/reference-filter.util.ts`, ed e' la stessa per le radici e per i
+segmenti di un percorso. Il filtro guarda il tipo della **radice**, e quindi non basta: in un
 parametro `String` una variabile `Structure` non e' compatibile, ma `Richiesta.Ragione` sì. Per
-questo `<fb-reference-picker>`, dove un filtro c'e', chiede al backend **anche** l'elenco non
-filtrato, e ne ricava due cose: i contenitori compaiono come righe in cui si **entra** — cliccarle
-apre il percorso invece di scegliere un valore del tipo sbagliato — e le radici si riconoscono
-tutte, così un `Leggi_Ordine.Numero` già scritto in un campo `String` non viene accusato di non
-esistere. Le proposte le filtra il backend come prima; i segmenti di un percorso li filtra
-l'editor con la stessa regola, tenendo comunque quelli da cui si scende.
+questo `<fb-reference-picker>` tiene l'elenco **completo** accanto a quello filtrato, e ne ricava
+due cose: i contenitori compaiono come righe in cui si **entra** — cliccarle apre il percorso
+invece di scegliere un valore del tipo sbagliato — e le radici si riconoscono tutte, così un
+`Leggi_Ordine.Numero` già scritto in un campo `String` non viene accusato di non esistere. Nelle
+proposte non entra comunque nessun valore del tipo sbagliato: i segmenti li filtra la stessa
+regola, tenendo solo quelli da cui si scende. In un campo di **destinazione** le due liste sono due
+richieste — `getWritableReferences` per le proposte, `getReferences` per le radici — perche' la
+scrivibilita' e' del **percorso** e non della radice: un `$User.Anagrafica.Citta` scritto a mano e'
+`TARGET_NOT_WRITABLE`, non un nome che non esiste.
 
 **Le globali si navigano come le risorse.** Un percorso dichiarato dall'host puo' portare un
 contenitore, e allora `objectType` dice di che tipo: `$User.Anagrafica.Citta` si propone e si
@@ -305,6 +320,25 @@ quindi l'editor dice di filtrare per le colonne della chiave invece di far cerca
 nell'elenco non c'e'. Restano `<select>` i dizionari chiusi — tipi di dato, operatori,
 enumerazioni — dove non c'e' niente da scrivere a mano.
 
+**Valori di enum.** Un `Enum` ha due meta' e servono entrambe: l'`objectType` dice **quale tipo** —
+e quello resta un `<select>`, perche' l'elenco dei tipi e' un dizionario chiuso — mentre i **valori**
+di quel tipo arrivano da `listEnumValues(objectType)` e sono cio' che finisce in `enumValue` (§4.2,
+§4.6). Senza la seconda chiamata all'utente resta una casella di testo su un insieme chiuso, che e'
+il modo piu' facile di scrivere un valore che il runtime non riconoscera'. Li propone
+`<fb-enum-value-picker>`, che il `<fb-value-editor>` monta al posto della casella di testo appena il
+tipo della destinazione e' `Enum`: vale quindi in una condizione, in un filtro, nel valore iniziale
+di una risorsa, in un parametro di action o di form, in un Assignment e in una `Map` di un Transform.
+Cio' che si scrive e' il **nome**: `numericValue` viene mostrato accanto al valore — aiuta a
+riconoscerlo in dati legacy — ma un numero in `enumValue` sarebbe un altro tipo (§13.18). Elenco
+vuoto resta "non lo so" — primitiva non esposta, tipo senza valori dichiarati, `objectType` ancora
+da scegliere — e allora il valore si digita; con l'elenco popolato un valore fuori elenco e' un
+**avviso**, perche' nessun codice della §7 lo blocca ed e' l'editor ad accorgersene prima del runtime.
+
+Perche' l'editor conosca il tipo della destinazione serve saperlo: in un Assignment arriva da
+`getWritableReferences` (per corrispondenza esatta del nome: su `Cliente.Stato` resta ignoto), in una
+condizione e in un filtro dal riferimento o dal campo a sinistra, in un Transform dal **membro** della
+classe di destinazione. Dove il tipo non si sa, il campo resta generico invece di indovinare.
+
 Lo stesso controllo, nella variante `<fb-name-picker>`, vale per **ogni altro nome che il flow
 prende da fuori**: tipo di action e action, script, form, i nomi dei loro parametri di ingresso
 e di uscita, il flow di uno step in background e dei suoi evaluation flow, il flow invocato da
@@ -450,6 +484,8 @@ distribuire e nessuna dipendenza da un font di icone dell'applicazione ospite.
 | 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) |
+| 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 |
 
 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