@esfaenza/flow-builder 20.3.8 → 20.3.10

package/index.d.ts

@@ -872,9 +872,10 @@ interface FlowReference {
     isCollection?: boolean;
     objectType?: string | null;
     /**
-     * Per i campi di destinazione. Scrivibili sono le variabili, `$Flow.CurrentStage`,
-     * `$Flow.ActiveStages` e le globali che il sistema ospite dichiara tali: la primitiva
-     * `POST /flows/references/writable` le comprende già, non vanno aggiunte lato client (§5.2).
+     * Per i campi di destinazione. Scrivibili sono le variabili, i campi di `$Record` e **due sole**
+     * globali, `$Flow.CurrentStage` e `$Flow.ActiveStages`: le globali dell'host sono sempre di sola
+     * lettura, membri compresi. La primitiva `POST /flows/references/writable` le comprende già, non
+     * vanno aggiunte lato client (§5.2).
      */
     isWritable?: boolean;
     description?: string | null;
@@ -1191,9 +1192,10 @@ declare abstract class FlowBuilderApi {
     abstract getReferences(query: FlowReferenceQuery): Promise<FlowReference[]>;
     /**
      * `POST /flows/references/writable` — le variabili **piu' le globali assegnabili**, per i
-     * campi di destinazione: `$Flow.CurrentStage`, `$Flow.ActiveStages` e quelle che il sistema
-     * ospite dichiara `isWritable`. La primitiva le comprende già, l'editor non le aggiunge
-     * (§5.2). Restano fuori i campi di `$Record`, che dipendono dallo schema: quelli arrivano da
+     * campi di destinazione. Le globali assegnabili sono **due**, `$Flow.CurrentStage` e
+     * `$Flow.ActiveStages`: quelle dell'host sono sempre di sola lettura e il catalogo non ha un
+     * flag per dichiararne una scrivibile (§5.2). La primitiva le comprende già, l'editor non le
+     * aggiunge. Restano fuori i campi di `$Record`, che dipendono dallo schema: quelli arrivano da
      * `listFields(object, 'updateable')` (§6.4).
      */
     abstract getWritableReferences(query: FlowReferenceQuery): Promise<FlowReference[]>;
@@ -2685,11 +2687,34 @@ declare class ReferencePickerComponent {
     readonly elementsOnly: _angular_core.InputSignal<boolean>;
     readonly valueChange: _angular_core.OutputEmitterRef<string | undefined>;
     private readonly references;
+    /**
+     * L'elenco **senza** il filtro di tipo, che serve solo a riconoscere le radici dei percorsi.
+     *
+     * Il filtro (§6.4) guarda il tipo della **radice**, e una radice scartata si porta via anche cio'
+     * che sta sotto: in un parametro `String` una variabile `Structure` non e' compatibile, ma
+     * `Richiesta.Ragione` lo e', e `Leggi_Ordine` non e' un `String` mentre `Leggi_Ordine.Numero` lo
+     * e'. Senza questo elenco il primo membro non si puo' proporre e il secondo viene accusato di non
+     * esistere pur essendo un riferimento valido (§4.5).
+     *
+     * Vuoto dove il filtro non c'e': lì {@link references} e' già l'elenco completo.
+     */
+    private readonly unfiltered;
+    /** Tutto cio' che puo' essere la radice di un percorso, filtrato o no. */
+    private readonly roots;
     private readonly isLoading;
     private readonly loadError;
     readonly isOpen: _angular_core.WritableSignal<boolean>;
     readonly query: _angular_core.WritableSignal<string>;
     constructor();
+    /**
+     * Il riferimento dichiarato piu' **lungo** che sia un prefisso del valore, sui confini del punto.
+     *
+     * Non basta il primo segmento: un nome dichiarato puo' contenere il punto. Le globali sono il caso
+     * per cui la regola esiste — di `$User.Anagrafica.Citta` il dizionario dichiara `$User.Anagrafica`,
+     * e cercare la corrispondenza esatta di tutto cio' che segue lo scope segnalerebbe come rotto un
+     * percorso giusto (§4.1: vince il prefisso dichiarato piu' lungo).
+     */
+    private readonly declaredPrefix;
     /**
      * La risorsa da cui il valore corrente sta navigando, quando la sua forma e' **dichiarata**: una
      * `Structure` con la classe, un record con l'entita'. È cio' che rende il percorso verificabile.
@@ -2710,7 +2735,28 @@ declare class ReferencePickerComponent {
      * segmento di sola lettura non si propone in un campo di destinazione, a meno che da lì il
      * percorso continui: `Richiesta.Cliente` non si assegna, ma `Richiesta.Cliente.Email` sì (§5.7).
      */
+    /**
+     * §5.2 — dentro una globale dell'host **niente** e' scrivibile, per quanto il membro si dichiari
+     * tale: le globali le risolve un componente che non ha modo di scriverle, e proporle come
+     * destinazione farebbe attivare un flow che poi fallisce davanti all'utente. L'eccezione sono i
+     * campi del record che innesca, che si assegnano (§4.1).
+     */
+    private readonly isReadOnlyPath;
     private readonly pathReferences;
+    /**
+     * Lo stesso filtro che il backend applica alle radici (§6.4), applicato ai segmenti di un
+     * percorso: in un parametro `String` non si propone un membro `Date`. Un segmento da cui si
+     * scende resta comunque proposto anche se il suo tipo non combacia — e' la strada per arrivare
+     * al membro che combacia.
+     */
+    private matchesTarget;
+    /**
+     * I contenitori che il filtro di tipo ha scartato: si mostrano per **entrarci**, non per
+     * scegliersi. Quelli che il filtro ha tenuto stanno già fra le proposte normali.
+     */
+    private readonly containerOptions;
+    /** `true` → questa riga apre il percorso e non e' un valore valido per il campo. */
+    isContainerOnly(reference: FlowReference): boolean;
     readonly options: _angular_core.Signal<FlowReference[]>;
     /** Le opzioni raggruppate per `kind`, così gli output automatici si distinguono. */
     readonly groups: _angular_core.Signal<{
@@ -2726,21 +2772,28 @@ declare class ReferencePickerComponent {
      *    elemento): il percorso resta fuori dalla validazione, quindi si accetta senza segnalare;
      *  - `host`: scope del sistema ospite che **non dichiara percorsi**: non verificabile (§4.1);
      *  - `member`: percorso dentro una forma dichiarata, verificato fino in fondo (§4.4, §4.7.1);
+     *  - `containerRoot`: il contenitore da solo in un campo che vuole un altro tipo: il valore e' un
+     *    suo membro, non lui;
      *  - `memberUnknown`: un segmento non esiste nella sua tappa: `STRUCTURE_MEMBER_UNKNOWN` su una
      *    classe, `FIELD_UNKNOWN` su un'entita', e a differenza di prima si sa per certo;
      *  - `memberNotWritable`: il segmento esiste, non e' scrivibile, e questo campo vuole una
      *    destinazione: `TARGET_NOT_WRITABLE`;
      *  - `pathUnverified`: la catena si interrompe (`PATH_NOT_VERIFIABLE`): avviso, non errore;
+     *  - `globalPathUntyped`: percorso globale che porta un contenitore senza dichiararne il tipo:
+     *    `PATH_NOT_VERIFIABLE`, e la correzione sta nel catalogo dell'host, non nel flow (§4.1);
+     *  - `globalPathInvalid`: si naviga un percorso globale scalare o una collection: `GLOBAL_UNKNOWN`;
      *  - `unknown`: nessuna corrispondenza: si avvisa, senza bloccare. Ci finisce anche il
      *    percorso inesistente di uno scope che i percorsi li dichiara, perche' lì il backend
      *    risponderebbe `GLOBAL_UNKNOWN`.
      */
-    readonly valueState: _angular_core.Signal<"empty" | "unknown" | "known" | "navigated" | "host" | "member" | "memberUnknown" | "memberNotWritable" | "pathUnverified">;
+    readonly valueState: _angular_core.Signal<"empty" | "known" | "navigated" | "host" | "member" | "containerRoot" | "memberUnknown" | "memberNotWritable" | "pathUnverified" | "globalPathUntyped" | "globalPathInvalid" | "unknown">;
     /** Le parole cambiano con la tappa: un campo di un'entita' non e' un membro di una classe. */
     private readonly tailIsObject;
     private readonly tailContainer;
     readonly hint: _angular_core.Signal<string | null>;
-    /** I due stati che sono errori e non avvisi: il colore deve dirlo. */
+    /** Gli stati che sono avvisi: «non lo so», o un valore da correggere che non blocca. */
+    readonly isHintWarning: _angular_core.Signal<boolean>;
+    /** Gli stati che sono errori e non avvisi: il colore deve dirlo. */
     readonly isHintError: _angular_core.Signal<boolean>;
     readonly errorMessage: _angular_core.Signal<string | null>;
     open(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esfaenza/flow-builder",
-  "version": "20.3.8",
+  "version": "20.3.10",
   "peerDependencies": {
     "@angular/common": "^20.3.25",
     "@angular/core": "^20.3.25",