@esfaenza/flow-builder 20.3.32 → 20.3.34

package/README.md

@@ -194,6 +194,48 @@ l'attributo `style` del node a ogni spostamento e uno `[style.width]` verrebbe c
 tabella delle larghezze e' la stessa che il comando «Riordina» passa a dagre: se divergessero,
 i node larghi resterebbero sovrapposti.
 
+**Lavorare su un flow grande.** Un flow di produzione arriva a quaranta elementi distribuiti su
+settemila pixel di canvas, e a quella scala quasi tutto quello che serve e' *trovare* e
+*orientarsi*. Quattro cose lo rendono possibile.
+
+*Inquadratura leggibile.* «Inquadra» non scende sotto il **60%**: `fitToScreen` non ha un minimo
+e su un flow del genere chiede lo 8%, cioe' quaranta rettangoli grigi senza una etichetta
+leggibile. Sotto la soglia si rinuncia a mostrare tutto e si inquadra l'**inizio** del flow.
+Accanto ci sono i comandi di zoom con la percentuale, e il numero e' un bottone: riporta al 100%
+sull'elemento selezionato.
+
+*Ricerca nel documento.* La casella in alto (`Ctrl`+`F`) cerca fra **tutto cio' che ha un nome
+nello spazio dei nomi comune** (§3.3): elementi, risorse, campi di screen dinamico, screen action,
+step di orchestrazione. Scegliere un risultato porta la vista sull'elemento e apre il suo form —
+e se il risultato e' un campo di uno screen dinamico, apre il form **con quel campo
+selezionato**. La casella della palette e' un'altra cosa e lo dice: filtra i *tipi* che si
+possono aggiungere.
+
+*Innesto su un arco.* Trascinando un elemento dalla palette **sopra un arco**, l'arco si accende
+e il rilascio lo innesta nel percorso: chi precedeva punta al nuovo elemento, il nuovo elemento
+riprende da dove l'arco arrivava, e cio' che sta sotto scende per fargli spazio — solo se serve,
+e in **un solo passo di annulla**. Quale uscita «riprende il percorso» e' una scelta semantica e
+non «la prima»: una Decision riprende dal ramo `default` (le regole sono cio' che l'autore deve
+ancora scrivere), un Loop da `loopEnd`, e un Custom Error **non riprende affatto** perche'
+interrompe l'esecuzione (§5.12) — in quel caso l'editor dice che il percorso a valle e' rimasto
+scollegato.
+
+*Spostare un blocco di elementi.* Su un flow di produzione riordinare a mano un elemento alla
+volta non e' lavoro, e' penitenza. I gesti ci sono — `Ctrl`+clic aggiunge o toglie un elemento
+dalla selezione, `Shift`+trascina disegna un rettangolo, `Ctrl`+`A` prende tutto, e trascinando
+**uno** degli elementi selezionati si spostano tutti in **un solo passo di annulla** — ma nessuno
+di questi si vede. Per questo accanto ai comandi di zoom c'e' un interruttore «Seleziona»: acceso,
+il trascinamento sul canvas vuoto disegna il rettangolo di selezione invece di spostare la vista
+(che nel frattempo si muove col tasto centrale del mouse). E quando la selezione contiene piu' di
+un elemento, il canvas lo dice e dice **cosa farne**: «trascinane uno per spostarli tutti». Un
+gesto che nessuno annuncia non esiste.
+
+*Quante volte e' usata.* Ogni risorsa porta il numero dei suoi usi, formule comprese; a zero
+occorrenze lo dice, ed e' l'unico modo di sapere quali delle venti variabili sono morte.
+Rimuovere una risorsa **usata** chiede conferma e dice quanti riferimenti resterebbero orfani:
+cancellare una variabile non fa sparire nessun arco dal canvas, e senza il numero il danno si
+scopriva alla validazione successiva.
+
 **Copia, incolla, duplica.** `Ctrl`+`C` copia gli elementi selezionati — la selezione del canvas
 puo' contenerne piu' d'uno (rettangolo, `Ctrl`+`A`) — `Ctrl`+`V` li incolla, `Ctrl`+`D` li duplica in
 loco; gli stessi comandi stanno nella top bar («⧉» e «⎘») e sul node selezionato («⧉»). I tasti
@@ -222,12 +264,28 @@ Tutto l'incolla e' **un solo passo di annulla**.
 
 **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
+nella top bar, bottone «✎» (o doppio click) su un rilievo nel pannello dei problemi, un risultato
+della ricerca, o creazione di un elemento dalla palette. Da qualunque di queste strade la **vista si porta
+sull'elemento**: aprire il form giusto lasciando il grafo dov'era, su un flow grande, lascia
+«dove sono» senza risposta. 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.
+qualsiasi. **Si sposta prendendola per l'intestazione**: configurare un elemento richiede spesso
+di guardare il grafo — quale ramo esce da dove, come si chiama l'elemento accanto — e una finestra
+larga 1400px inchiodata al centro copre esattamente cio' che si deve leggere. Cio' che resta dentro
+il builder e' la **maniglia**, non tutta la finestra: si puo' spingere quasi fuori per sbirciare
+sotto, e riportarla indietro e' sempre possibile. La posizione non si azzera cambiando elemento —
+solo alla riapertura.
+
+Nelle **opzioni** di un campo choice il selettore e' un comando e non un campo: si sceglie
+dall'elenco, oppure si scrive il nome e si conferma con **Invio** (`commitOn="enter"` del name
+picker). A emettere per tasto ogni lettera diventerebbe un'opzione a se'.
+
+**Le tendine dei picker si chiudono cliccando fuori**, e `Esc` chiude la tendina senza portarsi
+via la dialog. Sul selettore di riferimento, entrare in un record o in un'istanza di classe (il
+`›`) porta i suoi campi **in cima** all'elenco: sotto le radici, e in fondo a una tendina che
+scorre, sembrava che il comando non facesse niente.
 
 **Palette.** Costruita da `elementTypes`: nessun tipo e' cablato, e i due non supportati
 (`Step`, `Experiment`) sono nascosti tramite `isSupported`. L'etichetta del ramo di fault arriva
@@ -524,9 +582,17 @@ versione attiva e' un avviso. Prima questi campi erano `<select>` con un'opzione
 «(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
-non e' una garanzia di correttezza.
+**Problemi.** Pannello con filtro per gravita', validazione su pausa di digitazione (debounce
+400 ms) e l'avvertenza che l'assenza di rilievi
+non e' una garanzia di correttezza. Il `path` del rilievo si mostra **per nome**: il backend lo
+manda come percorso di campi e sugli screen dinamici spesso a indici
+(`fields[1].fields[1].fields[0]`), che e' esatto e inutile perche' per seguirlo si devono contare
+i figli a mano — i nomi li ha il documento, quindi tradurli e' compito dell'editor. Un clic su una
+riga **mostra**: seleziona l'elemento e lo porta al centro della vista, senza aprire niente —
+l'elenco dei problemi si scorre, e un form che si apre a ogni riga copre il grafo che si sta
+leggendo. Ad aprire il form ci sono il bottone «✎» della riga e il doppio clic, che e' la stessa
+coppia di gesti del canvas. Per la stessa
+ragione il clic non si limita ad aprire l'elemento: **seleziona il campo** che il rilievo nomina.
 
 **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
@@ -568,6 +634,31 @@ distingue le due attese di `Suspended` (`isWaitingForEvent` / `isWaitingForStage
 uno step al posto dell'assegnatario — rifiuto compreso, con la `interviewKey` nuova che sostituisce
 la vecchia — e mostra traccia e risorse solo in debug, dove riportano anche i dati personali.
 
+**Riquadri di raggruppamento (§3.6).** Cornici che racchiudono degli elementi per documentarli,
+come i commenti dell'editor a blueprint di Unreal Engine: barra col titolo, testo del commento,
+colore, apri/chiudi, ridimensionamento, e un pannello laterale «Riquadri» per il nome tecnico, il
+commento per intero e l'elenco dei membri. Il runtime non li legge mai — nessun connettore,
+nessuna raggiungibilita' — quindi aggiungerne uno e' l'unica modifica a un flow che con certezza
+non ne cambia il comportamento. Quattro conseguenze, tutte visibili nell'editor:
+
+- **il nome sta in uno spazio dei nomi a parte.** Il doppione si cerca fra i riquadri
+  (`GROUP_NAME_DUPLICATED`) e non in `usedNames`: un riquadro non e' referenziabile, quindi un
+  omonimo di una variabile e' legittimo e segnalarlo sarebbe un falso positivo;
+- **l'appartenenza la dichiara `members`, non la geometria.** La geometria serve a **calcolarla**
+  — trascinando un elemento dentro o fuori dalla cornice l'editor riscrive `members` — e a
+  spostare i membri quando si sposta il riquadro. Dedurla dai rettangoli a ogni disegno, con un
+  auto-layout (coordinate a 0) metterebbe tutti i node in tutti i riquadri;
+- **`width`/`height` a 0 significano «calcolala sui membri»**, quindi il rettangolo disegnato non
+  e' quello scritto nel documento. Ridimensionare un riquadro **dichiara** la geometria, ed e'
+  come si esce da quel caso;
+- **nessun rilievo su un riquadro blocca l'attivazione.** I tre codici sono avvisi, e un `members`
+  che nomina un elemento cancellato e' cio' che resta dopo la cancellazione: l'editor offre di
+  ripulirlo con un comando e non lo fa di soppiatto mentre si trascina qualcos'altro.
+
+Chiuso, il riquadro resta la sola barra del titolo e **gli elementi restano visibili**: nasconderli
+vorrebbe dire connettori con `display: none`, cioe' geometria 0×0 e archi attaccati nel punto
+sbagliato.
+
 **Import/export.** Export JSON indentato; import via `POST /flows/parse`, che normalizza il
 documento o lo rifiuta con `InvalidDefinition`.
 
@@ -597,9 +688,11 @@ src/lib/
     condition-types.util.ts  quali tipi si confrontano, e i numeri in cultura invariante
     stage-step.util.ts       gli step di uno stage: nomi, output non condizionabili
     screen-field.util.ts     l'albero dei campi di uno screen dinamico: percorsi, nomi, mutazioni
+    flow-groups.ts           i riquadri (§3.6): geometria risolta (anche quando il documento non
+                             la dichiara) e appartenenza calcolata dai rettangoli
   ui/
     flow-builder.component.ts  il componente da montare
-    canvas/ palette/ inspector/ resources/ problems/ versions/ run/ debug/ shared/
+    canvas/ palette/ inspector/ resources/ groups/ problems/ versions/ run/ debug/ shared/
 styles/
   flow-builder.css   variabili del tema, controlli di form, stili degli archi
 ```