@esfaenza/flow-builder 20.0.0

package/README.md

@@ -0,0 +1,354 @@
+# flow-builder
+
+Editor visuale per i flow descritti in [`FRONTEND.md`](../../FRONTEND.md): un componente
+**standalone Angular** che disegna il grafo, edita ogni tipo di elemento, valida, versiona e
+prova un flow.
+
+Requisiti: **Angular ≥ 18** (sviluppato e verificato su 19.2), TypeScript.
+
+---
+
+## Indice
+
+1. [Integrazione in tre passi](#integrazione-in-tre-passi)
+2. [L'interfaccia verso il backend](#linterfaccia-verso-il-backend)
+3. [Cosa fa il builder](#cosa-fa-il-builder)
+4. [Architettura](#architettura)
+5. [Dipendenze esterne](#dipendenze-esterne)
+6. [Tema e personalizzazione](#tema-e-personalizzazione)
+7. [Le trappole della §13, una per una](#le-trappole-della-13-una-per-una)
+8. [Limiti noti](#limiti-noti)
+
+---
+
+## Integrazione in tre passi
+
+### 1. Fornire l'implementazione dell'interfaccia
+
+`FlowBuilderApi` e' l'unica porta verso il backend: **tutto** il traffico di dati passa da
+lì, e nessun componente della libreria conosce HTTP.
+
+```ts
+import { FlowBuilderApi, HttpFlowBuilderApi, FLOW_BUILDER_HTTP_CONFIG } from 'flow-builder';
+
+bootstrapApplication(App, {
+  providers: [
+    provideHttpClient(),
+    { provide: FLOW_BUILDER_HTTP_CONFIG, useValue: { baseUrl: '/api' } },
+    { provide: FlowBuilderApi, useClass: HttpFlowBuilderApi },
+  ],
+});
+```
+
+`HttpFlowBuilderApi` usa le rotte **proposte** dalla §6. Se le vostre differiscono, ci sono
+due strade e nessuna delle due tocca l'editor:
+
+```ts
+// 1. estendere e sovrascrivere i soli metodi con rotta diversa
+class NostraApi extends HttpFlowBuilderApi {
+  override loadFlow(flowName: string, version?: number) { /* … */ }
+}
+
+// 2. implementare `FlowBuilderApi` da zero: e' una classe astratta, quindi il compilatore
+//    elenca esattamente i metodi che mancano
+```
+
+I metodi con implementazione di default rifiutano con `MissingService`: un ambiente che non
+espone `parseFlow`, `exportFlow` o le primitive di esecuzione resta usabile, con il comando
+corrispondente degradato invece di rotto.
+
+### 2. Includere i due fogli di stile
+
+```json
+// angular.json → architect.build.options.styles
+"styles": [
+  "node_modules/@foblex/flow/styles/default.scss",
+  "node_modules/flow-builder/styles/flow-builder.css",
+  "src/styles.css"
+]
+```
+
+Servono entrambi. `flow-builder.css` contiene le variabili del tema, i controlli di form e
+gli stili degli archi: i path SVG delle connessioni sono creati a runtime e non portano
+l'attributo di scope di Angular, quindi un CSS incapsulato non li raggiunge.
+
+### 3. Montare il componente
+
+```html
+<fb-flow-builder
+  [flowName]="'ApprovazioneOrdine'"
+  [version]="null"
+  [author]="utenteCorrente"
+  (saved)="onSaved($event)"
+  (activated)="onActivated($event)"
+/>
+```
+
+| Input | Significato |
+|---|---|
+| `flowName` | il flow da aprire; `null` → si parte da un flow nuovo |
+| `version` | la versione da aprire; assente → l'attiva se c'e', altrimenti l'ultima (§6.1) |
+| `author` | registrato sulla versione e mostrato nell'elenco |
+| `defaultProcessType` | `processType` iniziale di un flow nuovo |
+| `inspectorMode` | `'dialog'` (predefinito) apre il dettaglio dell'elemento in una finestra sopra il canvas, come il flow builder di Salesforce; `'panel'` lo tiene nel pannello laterale |
+
+| Output | Quando |
+|---|---|
+| `saved` | dopo un salvataggio riuscito, con `FlowSaveResult` |
+| `activated` | dopo un'attivazione riuscita |
+
+Il componente vuole un'altezza: `<fb-flow-builder style="height: 100vh">`, oppure un
+contenitore flex. Gli store sono provider **del componente**, quindi due builder sulla stessa
+pagina editano due flow indipendenti.
+
+---
+
+## L'interfaccia verso il backend
+
+Metodi raggruppati come nella specifica. Gli **astratti** sono obbligatori; i **concreti**
+sono opzionali e rifiutano con `MissingService` se non sovrascritti.
+
+| §6.1 Lettura | |
+|---|---|
+| `listFlows(query?)` | astratto |
+| `listVersions(flowName)` | astratto |
+| `loadFlow(flowName, version?)` | astratto |
+| `exportFlow(flowName, query?)` | opzionale |
+| `parseFlow(definition)` | opzionale — serve all'import di un file |
+
+| §6.2 Scrittura | |
+|---|---|
+| `createFlow(request)` | astratto |
+| `saveFlow(flowName, request)` | astratto |
+| `createVersion(flowName, request?)` | astratto |
+| `activateVersion(flowName, version)` | astratto |
+| `deactivateFlow(flowName)` | astratto |
+| `cloneFlow`, `deleteVersion`, `deleteFlow` | opzionali |
+
+| §6.3 Validazione | |
+|---|---|
+| `validateDefinition(definition)` | astratto — e' il pannello dei problemi |
+| `validateVersion(flowName, version)` | opzionale |
+
+| §6.4 Dizionari e cataloghi | |
+|---|---|
+| `getDictionaries()` | astratto |
+| `getReferences(query)` / `getWritableReferences(query)` | astratti |
+| `getConnectorTargets(definition, excluding?)` | astratto |
+| `getOutline(definition)` | astratto |
+| `listObjects()`, `listFields(object, usage?)` | astratti |
+| `listActionTypes` / `listActions` / `listActionParameters` | astratti |
+| `listScripts` / `listScriptParameters` | astratti |
+| `listForms` / `listFormParameters` | astratti |
+| `listEnumTypes`, `listEvents`, `listSubflowCandidates` | astratti |
+| `describeObject`, `listFieldValues` | opzionali |
+
+| §6.5 Esecuzione | |
+|---|---|
+| `startInterview`, `respondToScreen`, `resumeInterview`, `inspectInterview`, `abandonInterview` | opzionali — senza, il pannello «Prova» segnala che la funzione non c'e' |
+
+**Errori.** Ogni metodo, in caso di rifiuto, deve fallire con un `FlowApiError`
+categorizzato (§10). L'editor si comporta in base alla `category`, mai leggendo il
+messaggio: `NotEditable` fa comparire «Nuova versione» al posto di «Salva»,
+`VersionConflict` apre il banner con «ricarica» / «salva come nuova versione»,
+`ValidationFailed` apre il pannello dei problemi con il payload.
+
+```ts
+throw new FlowApiError('VersionConflict', 'Ha salvato mrossi.', undefined, 'mrossi');
+```
+
+Un'implementazione completa e commentata sta in
+[`projects/demo/src/app/backend/in-memory-flow-builder-api.ts`](../demo/src/app/backend/in-memory-flow-builder-api.ts):
+copre tutte le primitive, il ciclo di vita, la concorrenza ottimistica e un esecutore finto,
+senza una sola richiesta di rete.
+
+---
+
+## Cosa fa il builder
+
+**Canvas.** Node draggabili con l'ingresso sul bordo superiore e **un'uscita per ramo sul
+bordo inferiore**, in fila e nell'ordine del modello, secondo la mappa della §3.5:
+`connector`, `faultConnector`, `timeoutConnector`,
+`rules[].connector`, `nextValueConnector` / `noMoreValuesConnector`,
+`waitEvents[].connector`, `scheduledPaths[].connector`. Archi colorati per `kind` (Fault
+rosso, Rule viola ed etichettato, Default tratteggiato, LoopNext verde), `isGoTo` reso come
+salto, pan/zoom, minimap, selezione, creazione e riassegnazione di archi trascinando,
+drag-and-drop dalla palette, comando «Riordina» che ricalcola e **scrive** le coordinate nel
+documento. I node non raggiungibili e i rami dichiarati senza destinazione sono marcati
+sul canvas.
+
+Il lato da cui gli archi entrano ed escono e' dichiarato (`fConnectorConnectableSide`:
+`TOP` sull'ingresso, `BOTTOM` sulle uscite), non calcolato: lasciandolo calcolare a
+@foblex/flow, un ramo che risale — il ritorno di un Loop, per esempio — uscirebbe di fianco e
+il grafo perderebbe la lettura dall'alto verso il basso. La larghezza del node cresce a
+scaglioni col numero di rami, perche' le etichette delle uscite stanno in fila: arriva da una
+**classe** (`.fb-node--outlets-N`) e non da uno stile inline, perche' @foblex/flow riscrive
+l'attributo `style` del node a ogni spostamento e uno `[style.width]` verrebbe cancellato. La
+tabella delle larghezze e' la stessa che il comando «Riordina» passa a dagre: se divergessero,
+i node larghi resterebbero sovrapposti.
+
+**Dettaglio dell'elemento.** Con `inspectorMode="dialog"` (predefinito) il form si apre in una
+finestra sopra il canvas: doppio click sul node, bottone «✎» sul node, comando «Dettaglio»
+nella top bar, click su un rilievo nel pannello dei problemi, o creazione di un elemento dalla
+palette. Il click singolo **seleziona soltanto**: un click capita anche solo per spostare un
+node. La dialog non ha «Annulla» — le modifiche entrano nel documento mentre si digita,
+esattamente come nel pannello, e tornare indietro e' compito dell'annulla dell'editor. Vive
+dentro il componente e non in fondo al `body`: la libreria e' innestabile in una pagina
+qualsiasi.
+
+**Palette.** Costruita da `elementTypes`: nessun tipo e' cablato, e i tre non supportati
+(`Step`, `Experiment`, `OrchestratedStage`) sono nascosti tramite `isSupported`.
+
+**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. Più l'intestazione comune con la rinomina, che
+**riscrive tutti i riferimenti** all'elemento.
+
+**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.
+
+**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
+non e' una garanzia di correttezza.
+
+**Versioni.** Elenco con stato, «Nuova versione» al posto di «Salva» sulle versioni chiuse,
+attivazione bloccata finche' ci sono errori, eliminazione dietro una conferma esplicita che
+spiega il rischio per le esecuzioni sospese.
+
+**Prova.** Interview con form generato dalle variabili di input, form generico per gli screen
+(valori in ingresso più i campi da restituire), `canGoBack` / `canFinish` / `canPause` come
+verita' runtime, traccia navigabile e tabella delle risorse — con l'avviso in chiaro che la
+traccia riporta anche i dati personali.
+
+**Import/export.** Export JSON indentato; import via `POST /flows/parse`, che normalizza il
+documento o lo rifiuta con `InvalidDefinition`.
+
+---
+
+## Architettura
+
+```
+src/lib/
+  model/          i tipi: documento Flow, dizionari, payload API, errori categorizzati
+  api/            FlowBuilderApi (astratta = token DI) + HttpFlowBuilderApi
+  core/
+    element-outlets.ts       la mappa "tipo di elemento → uscite" (§3.5), in un posto solo
+    flow-document.store.ts   il documento come fonte di verita': flatten, CRUD, undo/redo
+    flow-dictionary.store.ts cache dei dizionari e memoizzazione dei cataloghi
+    flow-validation.store.ts debounce, indicizzazione dei rilievi per elemento e campo
+    flow-editor-session.ts   versioni, salvataggio, concorrenza ottimistica
+    flow-layout.service.ts   auto-layout con dagre
+    flow-name.util.ts        nomi: regexp, namespace unico, slug dalla label
+    condition-logic.util.ts  riscrittura di conditionLogic su cancella / riordina
+  ui/
+    flow-builder.component.ts  il componente da montare
+    canvas/ palette/ inspector/ resources/ problems/ versions/ debug/ shared/
+styles/
+  flow-builder.css   variabili del tema, controlli di form, stili degli archi
+```
+
+Due scelte di progetto che vale la pena conoscere.
+
+**Il documento e' la fonte di verita' unica.** Canvas, inspector e pannelli sono funzioni del
+`FlowDefinition` in memoria, e ogni gesto e' una mutazione del documento. Le primitive del
+backend non vengono mai chiamate dallo store, così l'editing resta sincrono e reattivo anche
+mentre una validazione e' in volo.
+
+**Local-first per il disegno, backend per la verita'.** Archi e raggiungibilita' sono
+calcolati anche in locale, perche' trascinare un arco deve riflettersi subito;
+`POST /flows/outline` viene richiamato con debounce e, quando arriva, il suo `isReachable`
+sovrascrive il calcolo locale. Chiedere l'outline a ogni movimento del mouse renderebbe il
+canvas dipendente dalla latenza.
+
+---
+
+## Dipendenze esterne
+
+Oltre ad Angular:
+
+| Pacchetto | Perche' |
+|---|---|
+| `@foblex/flow` (+ `@foblex/platform`, `@foblex/mediator`, `@foblex/2d`, `@foblex/utils`) | rendering del grafo, pan/zoom, gesti su node e connessioni. Usata in *classic mode*: la libreria disegna e riconosce i gesti, lo stato resta nostro |
+| `dagre` | auto-layout gerarchico del comando «Riordina» |
+
+Nessun design system: i controlli sono input nativi con binding espliciti e CSS custom, così
+il builder si integra nel tema dell'app ospite senza imporre il proprio.
+
+---
+
+## Tema e personalizzazione
+
+Le variabili si sovrascrivono sul contenitore:
+
+```css
+.mio-contenitore {
+  --fb-accent: #7048c4;
+  --fb-surface: #ffffff;
+  --fb-border: #dcdfe4;
+  --fb-error: #b3261e;
+  --fb-edge-fault: #b3261e;
+}
+```
+
+Elenco completo in `styles/flow-builder.css`. Per la variante scura basta
+`data-fb-theme="dark"` su un antenato.
+
+Nota sugli archi: il colore si imposta valorizzando le custom properties del tema di
+@foblex/flow (`--ff-connection-color`, `--ff-marker-color`) invece di sovrascrivere le sue
+regole, perche' i selettori hanno la stessa specificita' e chi vince dipenderebbe dall'ordine
+con cui l'app ospite carica i fogli di stile. Lo stesso vale per il resto del disegno che fa
+la libreria: `flow-builder.css` mappa i propri colori sui token `--ff-*` (sfondo del canvas,
+pattern, minimappa, spessore degli archi) e ne annulla due — le maniglie di riassegnazione
+(`--ff-connection-drag-handle-*`), che disegnate formavano una macchia sopra la punta della
+freccia. Il colore dell'uscita di un ramo passa da `--ff-connector-connected-color`, unico
+modo di sopravvivere alla regola di foblex per i connettori collegati, che ha specificita'
+(0,4,1) e non si batte con una classe.
+
+L'aspetto dei node segue l'esempio *call-center* di @foblex/flow: card con badge dell'icona
+colorato per categoria, titolo, sottotitolo e uscite sul bordo inferiore. I glifi sono
+caratteri Unicode in `core/element-icons.ts`, condivisi fra palette e canvas: nessun asset da
+distribuire e nessuna dipendenza da un font di icone dell'applicazione ospite.
+
+---
+
+## Le trappole della §13, una per una
+
+| # | Trappola | Dove e' gestita |
+|---|---|---|
+| 1 | **Operatori unari**: `rightValue` e' l'esito atteso, non il termine di confronto | `ConditionEditorComponent`: per gli operatori con `isUnary` il campo «confronta con» non esiste; c'e' un selettore «è / NON è» e la frase «questa condizione e' vera quando: *Esito NON è vuoto*». Il flag arriva dal dizionario, non da una lista cablata |
+| 2 | `assignNextValueToReference` di un Collection Processor **non** e' la destinazione | `CollectionProcessorInspectorComponent`: il campo si chiama «Elemento in esame», e un callout dice che il risultato e' l'output automatico dell'elemento |
+| 3 | Gli **output automatici** sono riferimenti validi anche se non dichiarati | `ReferencePickerComponent` chiede l'elenco a `POST /flows/references`, che li include; non ricostruisce nulla lato client |
+| 4 | Cancellare una condizione richiede di **riscrivere `conditionLogic`** | `condition-logic.util.ts`: `removeCondition` e `moveCondition` rimappano gli indici 1-based; un termine rimasto orfano diventa `?` e viene segnalato |
+| 5 | Node e risorse condividono **un unico spazio di nomi** | `FlowDocumentStore.usedNames` unisce i due insiemi e `checkFlowName` confronta case-insensitive; pannello risorse e inspector usano lo stesso controllo |
+| 6 | `processType` non e' decorativo | Banner in cima all'editor per `AutoLaunched` + screen, `Orchestration` non eseguibile, `Screen` senza screen; la palette segnala lo Screen incompatibile |
+| 7 | Le **regole di una Decision sono ordinate** | `DecisionInspectorComponent`: regole numerate, frecce di riordino, callout «valutate dall'alto verso il basso, si ferma alla prima vera» |
+| 8 | **Rinominare non aggiorna i riferimenti** | `FlowDocumentStore.renameNode` cammina il documento e riscrive ogni campo di riferimento, incluso il caso navigato (`Vecchio.Campo` → `Nuovo.Campo`); l'inspector dice quante occorrenze verranno toccate |
+| 9 | `Step`, `Experiment`, `OrchestratedStage` non sono supportati | Filtrati dalla palette via `isSupported`; se arrivano da un import, l'inspector li mostra in sola lettura spiegando perche' |
+| 10 | Un `Delete` senza filtri e' un **errore**, un `Update` senza filtri un **avviso** | `RecordWriteInspectorComponent`: severita' diverse, e l'update di massa chiede una conferma esplicita |
+| 11 | Non cablare enum e operatori | Ogni tendina legge da `getDictionaries()`; le mappe locali intervengono solo come fallback quando il dizionario non e' disponibile |
+| 12 | Il **token di continuazione e' opaco** | `DebugPanelComponent` lo rimanda tale e quale, non lo legge e non lo mette in nessun URL |
+
+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
+usati per rinominare o attivare (§2), un solo campo valorizzato in
+`FlowElementReferenceOrValue` con segnalazione e normalizzazione dei documenti ambigui (§4.2),
+`Transform.connector` e `start` trattati come array per fedelta' storica (§3.5), salvataggio
+possibile anche con errori e attivazione bloccata dagli errori (§8).
+
+---
+
+## Limiti noti
+
+- **Le uscite indicizzate cambiano chiave se si riordinano le regole**: la chiave di un
+  connettore contiene l'indice (`rule:0`), quindi riordinare le regole di una Decision
+  riassegna gli id dei connettori sul canvas. Le destinazioni seguono la regola, perche'
+  vivono dentro `rules[i].connector`, ma un arco selezionato perde la selezione.
+- **`relatedRecords` di Get Records** e' esposto in sola lettura con un avviso: e' modellato
+  ma non tradotto in query.
+- **L'esecutore della demo non valuta le condizioni**: prende il primo ramo disponibile e lo
+  scrive nella traccia. È un mock per esercitare il pannello, non il motore.
+- **Nessun test automatico**: la libreria e' stata verificata a mano sull'app demo (canvas,
+  inspector, salvataggio, attivazione, interview completa). Casi su `condition-logic.util`,
+  `flow-name.util`, `element-outlets` e `FlowDocumentStore` sarebbero il primo investimento
+  sensato.