@esfaenza/flow-builder 20.3.2 → 20.3.4

package/README.md

@@ -142,6 +142,7 @@ sono opzionali e rifiutano con `MissingService` se non sovrascritti.
 | `listForms` / `listFormParameters` | astratti |
 | `listEnumTypes`, `listEvents`, `listSubflowCandidates` | astratti |
 | `describeObject`, `listFieldValues` | opzionali |
+| `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 | |
 |---|---|
@@ -202,6 +203,15 @@ 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.
 
+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
+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
+discriminatore; i valori restano nel dizionario del backend (`collectionProcessorTypes`), e
+senza quel dizionario il tipo torna a essere una voce sola.
+
 **Inspector.** Un form per ogni tipo supportato: Start, Screen, Assignment, Decision, Loop,
 Collection Processor, Get / Create / Update / Delete / Rollback Records, Action, Script,
 Subflow, Wait, Custom Error, Transform, Orchestrated Stage. Più l'intestazione comune con la
@@ -215,8 +225,29 @@ fa fallire l'interview. Una condizione che referenzia l'output di un altro step
 con la via d'uscita: scrivere quel risultato in una variabile.
 
 **Risorse.** I sette tipi, con i vincoli visibili: `dataType` obbligatorio, `objectType` per
-`Object` / `Enum`, `scale` solo sui numerici, costanti che non possono referenziare risorse,
-`stageOrder` distinti.
+`Object` / `Enum` / `Structure`, `scale` solo sui numerici, costanti che non possono referenziare
+risorse, `stageOrder` distinti.
+
+**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
+non ha nulla da istanziare — mentre il campo «valore iniziale» non c'e' affatto, perche' non
+esiste un `structureValue` e la variabile parte con un'istanza vuota. I membri si scelgono con
+`<fb-structure-member-picker>`, e nelle destinazioni si propongono **solo** quelli scrivibili: un
+membro calcolato si legge in una condizione ma assegnarlo e' `TARGET_NOT_WRITABLE`. Lo stesso
+vale dentro `<fb-reference-picker>`, dove i membri di una variabile `Structure` sono l'unica
+eccezione ai percorsi non verificati: `Richiesta.Ragione` si propone e il **primo** segmento si
+verifica (`STRUCTURE_MEMBER_UNKNOWN`), oltre quello si torna a "non lo so" — la descrizione della
+classe e' piatta, e i membri di una classe annidata sono una seconda chiamata (§4.7.1). Un
+Transform con target `Structure` compone l'istanza intera in un elemento solo: lì
+`outputFieldApiName` e' il nome di un membro, e il form lo dice invece di far indovinare (§5.12).
+
+Dei tre esiti di `describeStructure` il picker mostra tre messaggi diversi, perche' portano a
+gesti opposti: con l'elenco autorevole un nome fuori elenco e' un errore; con `members: []` la
+classe e' valida ma i membri non sono dichiarati e il nome si **digita**, senza accuse; con un
+404 (`StructureNotFound`) e' la **classe** a essere sbagliata, e il messaggio manda a correggere
+quella invece del membro. L'intestazione dell'elenco usa la `label` della classe, che e' la
+ragione per cui la risposta ha un involucro invece di essere un array.
 
 **Oggetti e campi.** Ogni punto che chiede un'entita' o un suo campo usa lo stesso controllo:
 `<fb-object-picker>` e `<fb-field-picker>`, una casella con autocomplete che filtra il catalogo
@@ -226,18 +257,31 @@ campo di testo cieco. La scrittura libera e' voluta — i percorsi di relazione
 (`Cliente.Citta`) non sono enumerabili e il catalogo dell'host puo' essere incompleto — ma un
 nome fuori catalogo viene segnalato subito, prima che il backend risponda `OBJECT_UNKNOWN` o
 `FIELD_UNKNOWN`. Il campo si chiede sempre con l'uso giusto (`filterable`, `sortable`,
-`updateable`), che decide sia l'elenco sia il testo dell'avviso: "non filtrabile" e "non
-aggiornabile" sono errori diversi. Restano `<select>` i dizionari chiusi — tipi di dato,
-operatori, enumerazioni — dove non c'e' niente da scrivere a mano.
-
-Lo stesso controllo, nella variante `<fb-name-picker>`, vale per i nomi che dipendono dal
-contesto e non da un catalogo di schema: il flow di uno step in background e dei suoi
-evaluation flow, il flow invocato da un Subflow, le variabili di input e output **del flow
-invocato**. Qui l'elenco arriva da chi ospita il picker (`listSubflowCandidates`, le variabili
-della definizione caricata), e un elenco vuoto resta "non lo so": il campo si scrive a mano e
-non si accusa nessun nome. Con l'elenco popolato, invece, un nome che non c'e' e' segnalato —
-ed e' la differenza rispetto al `datalist` che questi campi usavano prima, che accettava
-qualunque cosa in silenzio.
+`updateable`, `createable`), che decide sia l'elenco sia il testo dell'avviso: "non filtrabile",
+"non aggiornabile" e "non valorizzabile alla creazione" sono errori diversi. In particolare
+`createable` e `updateable` **non** sono sinonimi (§5.7): un Create propone i primi, un Update i
+secondi, e il validatore usa il codice giusto per l'elemento (`FIELD_NOT_CREATEABLE` /
+`FIELD_NOT_UPDATEABLE`). Per lo stesso motivo l'editor non da' per scontato che `Id` sia
+filtrabile: su una chiave composta porta la forma canonica della chiave e non e' filtrabile,
+quindi l'editor dice di filtrare per le colonne della chiave invece di far cercare un campo che
+nell'elenco non c'e'. Restano `<select>` i dizionari chiusi — tipi di dato, operatori,
+enumerazioni — dove non c'e' niente da scrivere a mano.
+
+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
+un Subflow e le variabili di input e output **del flow invocato**. Qui l'elenco arriva da chi
+ospita il picker — il catalogo già caricato per altri motivi, `listSubflowCandidates`, le
+variabili della definizione caricata — perche' dipende dal contesto: le action dipendono dal
+tipo scelto, i parametri dall'action, le variabili dal subflow.
+
+Un elenco vuoto resta "non lo so": il campo si scrive a mano e non si accusa nessun nome. Con
+l'elenco popolato, un nome che non c'e' e' segnalato, e con la **gravita' giusta**: un'action,
+un form, uno script o un parametro inesistenti sono errori che bloccano l'attivazione
+(`ACTION_UNKNOWN`, `FORM_UNKNOWN`, `PARAMETER_UNKNOWN`) e si mostrano in rosso; un flow senza
+versione attiva e' un avviso. Prima questi campi erano `<select>` con un'opzione sintetica
+«(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', navigazione all'elemento con un clic,
 validazione su pausa di digitazione (debounce 400 ms) e l'avvertenza che l'assenza di rilievi
@@ -367,6 +411,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 primo segmento; 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) |
 
 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