@esfaenza/flow-builder 20.3.29 → 20.3.31

package/index.d.ts

@@ -992,6 +992,44 @@ interface FlowCatalogParameter {
     isOutput?: boolean;
     isRequired?: boolean;
 }
+/**
+ * §6.3, §6.4 — una funzione (o un operatore) scrivibile in un'espressione: la **palette**
+ * dell'editor di formule, cioe' la terza gamba accanto ai nomi (`POST /flows/references`) e al
+ * giudizio (`POST /flows/validate-formula`).
+ *
+ * Due cose da non dimenticare, perche' sbagliarle produce rilievi falsi:
+ *
+ *  - l'elenco **non e' autoritativo**: un motore puo' supportare piu' di quanto dichiara, quindi
+ *    una funzione fuori catalogo non si accusa. A giudicare e' `validateFormula`, sempre.
+ *  - la lista **vuota** significa «il motore non le dichiara», non «non ce ne sono» (§4.6): si
+ *    mostra il campo di testo libero e nessuna palette.
+ *
+ * `signature` e `description` sono da **mostrare**, non da parsare: la grammatica resta del
+ * motore. `parameters`, `resultDataType` e `category` possono mancare — un motore con overload e
+ * funzioni variadiche si descrive piu' fedelmente con la sola `signature`.
+ */
+interface FlowFormulaFunction {
+    name: string;
+    /** Per raggruppare la palette; assente = un gruppo senza titolo. */
+    category?: string | null;
+    /** La forma d'uso, da mostrare così com'e': `IF(condizione, se vero, se falso)`. */
+    signature?: string | null;
+    description?: string | null;
+    /** Cosa **inserire** quando si sceglie la voce. Assente: si inserisce `name`. */
+    snippet?: string | null;
+    example?: string | null;
+    resultDataType?: FlowDataType | null;
+    isCollection?: boolean;
+    parameters?: FlowFormulaFunctionParameter[];
+}
+/** Un parametro di una funzione di formula: descrittivo, non un contratto da validare. */
+interface FlowFormulaFunctionParameter {
+    name: string;
+    description?: string | null;
+    dataType?: FlowDataType | null;
+    isCollection?: boolean;
+    isOptional?: boolean;
+}
 
 /**
  * Payload delle primitive — FRONTEND.md §6, §7, §8, §10.
@@ -1592,6 +1630,27 @@ declare abstract class FlowBuilderApi {
     abstract listForms(kind?: FlowFormKind): Promise<FlowCatalogEntry[]>;
     /** `GET /catalog/forms/{name}/parameters` */
     abstract listFormParameters(formName: string): Promise<FlowCatalogParameter[]>;
+    /**
+     * `GET /catalog/formula-functions?usage=` — le funzioni (e gli operatori, se il motore li
+     * dichiara) scrivibili in un'espressione: la **palette** dell'editor di formule (§6.3, §6.4).
+     *
+     * È la terza gamba dell'editor di formule, e le altre due non la sostituiscono: i **nomi**
+     * citabili li da' {@link getReferences}, il **giudizio** sull'espressione
+     * {@link validateFormula}, e questa dice cosa si puo' scrivere in mezzo.
+     *
+     * `usage` chiede le sole funzioni che hanno senso in quel punto — lo stesso valore che va in
+     * {@link validateFormula}. Un motore che non filtra risponde comunque l'elenco intero, che e'
+     * legittimo: chi mostra non deve dedurre niente dal fatto che una voce ci sia.
+     *
+     * Due regole, e non sono dettagli. La lista **vuota** significa «il motore non le dichiara»,
+     * non «non ce ne sono» (§4.6): si mostra il campo di testo libero, non una palette vuota. E
+     * l'elenco **non e' autoritativo**: accusare una funzione che non c'e' produrrebbe un rilievo
+     * falso su una formula valida, perche' un motore puo' supportare piu' di quanto dichiara.
+     *
+     * Opzionale come ogni catalogo che dipende da un servizio dell'host: assente, l'editor di
+     * formule resta quello di prima — nomi e verifica, senza palette.
+     */
+    listFormulaFunctions(usage?: FlowFormulaUsage): Promise<FlowFormulaFunction[]>;
     /** `GET /catalog/enum-types` — per `objectType` delle risorse `Enum`. */
     abstract listEnumTypes(): Promise<FlowCatalogEntry[]>;
     /**
@@ -1778,6 +1837,11 @@ declare class HttpFlowBuilderApi extends FlowBuilderApi {
     listScriptParameters(scriptName: string): Promise<FlowCatalogParameter[]>;
     listForms(kind?: FlowFormKind): Promise<FlowCatalogEntry[]>;
     listFormParameters(formName: string): Promise<FlowCatalogParameter[]>;
+    /**
+     * §6.3 — la palette dell'editor di formule. `usage` e' un filtro, non un obbligo: chi non lo
+     * manda ottiene l'elenco intero, ed e' legittimo anche che un motore lo ignori.
+     */
+    listFormulaFunctions(usage?: FlowFormulaUsage): Promise<FlowFormulaFunction[]>;
     listEnumTypes(): Promise<FlowCatalogEntry[]>;
     /** §4.6 — i valori di un tipo: `enumType` e' l'`objectType`, e va nel path come segmento. */
     listEnumValues(enumType: string): Promise<FlowEnumValue[]>;
@@ -2446,6 +2510,7 @@ declare class FlowCatalogStore {
     private readonly entriesCache;
     private readonly parametersCache;
     private readonly membersCache;
+    private readonly formulaFunctionsCache;
     /**
      * Una lista vuota significa "non lo so", non "nessuno": con il catalogo non popolato la
      * validazione salta i controlli invece di produrre falsi allarmi (§7). L'editor fa lo
@@ -2469,6 +2534,15 @@ declare class FlowCatalogStore {
      */
     listForms(kind?: FlowFormKind): Promise<FlowCatalogEntry[]>;
     listFormParameters(formName: string): Promise<FlowCatalogParameter[]>;
+    /**
+     * §6.3 — la palette dell'editor di formule. La cache e' per **usage**, perche' e' cio' che
+     * cambia la risposta: un motore che filtra risponde due elenchi diversi a `Condition` e a
+     * `Resource`, e una chiave sola li farebbe sovrascrivere a vicenda.
+     *
+     * La primitiva e' opzionale e l'errore diventa lista vuota — che qui significa «il motore non
+     * le dichiara»: nessuna palette e nessuna accusa a una funzione fuori elenco (§4.6, §6.3).
+     */
+    listFormulaFunctions(usage?: FlowFormulaUsage): Promise<FlowFormulaFunction[]>;
     listEnumTypes(): Promise<FlowCatalogEntry[]>;
     /**
      * §4.6 — i valori di un tipo di enumerazione, cioe' i nomi scrivibili in `enumValue` (§4.2).
@@ -4195,6 +4269,7 @@ declare class FormulaEditorComponent {
     private readonly store;
     private readonly api;
     private readonly service;
+    private readonly catalog;
     private readonly destroyRef;
     readonly expression: _angular_core.InputSignal<string>;
     /** Dove comparira': e' cio' che dice al motore cosa pretendere (§6.3). */
@@ -4242,6 +4317,37 @@ declare class FormulaEditorComponent {
     private readonly token;
     protected readonly highlighted: _angular_core.WritableSignal<number>;
     readonly suggestions: _angular_core.Signal<FlowReference[]>;
+    /**
+     * Le funzioni dichiarate dal motore. L'elenco lo tiene in cache lo store, per `usage`: piu'
+     * editor montati insieme fanno una richiesta sola. Vuoto = non dichiarate, e allora la palette
+     * non esiste — mostrarla vuota farebbe credere che il motore non abbia funzioni.
+     */
+    private readonly functions;
+    protected readonly isPaletteOpen: _angular_core.WritableSignal<boolean>;
+    protected readonly paletteFilter: _angular_core.WritableSignal<string>;
+    readonly hasPalette: _angular_core.Signal<boolean>;
+    /**
+     * Le voci raggruppate per `category`. La categoria puo' mancare: quelle senza finiscono in un
+     * gruppo senza titolo, in coda, invece di sparire.
+     */
+    readonly paletteGroups: _angular_core.Signal<{
+        category: string;
+        items: FlowFormulaFunction[];
+    }[]>;
+    private matchesFilter;
+    togglePalette(): void;
+    /** La forma d'uso da mostrare: `signature` se il motore la da', altrimenti il solo nome. */
+    signatureOf(entry: FlowFormulaFunction): string;
+    /**
+     * Inserisce la voce scelta al punto in cui si stava scrivendo. Cosa inserire lo dice `snippet`
+     * — assente, il nome — e il cursore va **dentro** la prima parentesi: la palette serve a non
+     * ricordare la firma, e lasciare il cursore in fondo costringerebbe a tornare indietro a mano.
+     *
+     * Non si scrive niente nel documento oltre al testo: la firma resta del motore, e qui non c'e'
+     * nessun parser che la interpreti.
+     */
+    insertFunction(entry: FlowFormulaFunction): void;
+    private loadFunctions;
     readonly issues: _angular_core.Signal<FlowFormulaIssue[]>;
     readonly hasErrors: _angular_core.Signal<boolean>;
     /**
@@ -4611,6 +4717,16 @@ declare class ParameterEditorComponent {
     readonly inputs: _angular_core.Signal<FlowInputParameter[]>;
     readonly outputs: _angular_core.Signal<FlowOutputParameter[]>;
     readonly hasCatalog: _angular_core.Signal<boolean>;
+    /**
+     * I due elenchi **non** sono una partizione: `isInput` e `isOutput` sono flag indipendenti, e un
+     * parametro bidirezionale (tipico dei componenti di screen) va proposto in tutt'e due i posti.
+     * Filtrare i soli `isOutput !== true` lo faceva sparire dagli ingressi — e con esso dai
+     * `missingRequired`, quindi non veniva proposto da nessuna parte; scritto a mano nel picker degli
+     * input diventava poi `PARAMETER_UNKNOWN`, perche' il catalogo li' non lo conteneva.
+     *
+     * Chi non dichiara nessuno dei due flag vale **input**: e' il caso di gran lunga piu' comune, ed
+     * e' cio' che i cataloghi che i flag non li dichiarano si aspettano.
+     */
     readonly inputCatalog: _angular_core.Signal<FlowCatalogParameter[]>;
     readonly outputCatalog: _angular_core.Signal<FlowCatalogParameter[]>;
     /**
@@ -5874,4 +5990,4 @@ declare class SelectValueDirective implements AfterViewChecked {
 }
 
 export { ConditionEditorComponent, ConnectorEditorComponent, DebugPanelComponent, DynamicScreenInspectorComponent, ENUM_CHOICE_SET_DEFAULT_DISPLAY_FIELD, ENUM_CHOICE_SET_DEFAULT_VALUE_FIELD, ENUM_CHOICE_SET_FIELDS, ElementDialogComponent, ElementInspectorComponent, ElementPaletteComponent, EnumValuePickerComponent, FALLBACK_COLLECTION_BY_TYPE, FALLBACK_TYPE_LABEL, FLOW_BUILDER_HTTP_CONFIG, FLOW_CLIPBOARD_KIND, FLOW_CLIPBOARD_VERSION, FLOW_ELEMENT_ICONS, FLOW_ELEMENT_VARIANT_FIELDS, FLOW_ELEMENT_VARIANT_ICONS, FLOW_ERROR_FALLBACK_MESSAGE, FLOW_ERROR_HTTP_STATUS, FLOW_NAME_PATTERN, FLOW_NODE_COLLECTIONS, FLOW_NODE_HEIGHT, FLOW_NODE_WIDTH, FLOW_REFERENCE_FIELDS, FLOW_RESOURCE_COLLECTIONS, FLOW_VALUE_FIELDS, FLOW_VALUE_LITERAL_FIELDS, FieldAssignmentEditorComponent, FieldPickerComponent, FieldValuePickerComponent, FlowApiError, FlowBuilderApi, FlowBuilderComponent, FlowCanvasComponent, FlowCatalogStore, FlowClipboardService, FlowDictionaryStore, FlowDocumentStore, FlowEditorSession, FlowLayoutService, FlowValidationStore, FormulaEditorComponent, FormulaValidationService, HttpFlowBuilderApi, NamePickerComponent, NodeInspectorBase, ORCHESTRATION_CONDITION_OUTPUT, ObjectPickerComponent, OrchestratedStageInspectorComponent, ParameterEditorComponent, PasteDialogComponent, ProblemsPanelComponent, RecordFilterEditorComponent, ReferencePickerComponent, ResourcePanelComponent, RunDialogComponent, SEVERITY_BUCKETS, SEVERITY_ICON, SEVERITY_LABEL, START_NODE_NAME, SelectValueDirective, StartInspectorComponent, StructureMemberPickerComponent, StructurePickerComponent, TYPES_WITH_AUTOMATIC_OUTPUT, TYPE_BY_COLLECTION, UNSUPPORTED_TYPES, ValueEditorComponent, VersionPanelComponent, allFieldsOf, applyPaste, areTypesComparable, buildClipboardPayload, canvasNodeId, checkConditionLogic, checkFlowName, choiceSetSourceOf, declaredChoiceSetSources, describePathEntry, duplicateField, elementIcon, emptyFlowDefinition, enumChoiceSetFieldType, fieldAt, filterReferences, flattenFields, flowNodeWidth, flowNodeWidthClass, innerNamesOf, insertField, isClipboardPayload, isCustomConditionLogic, isEmptyReferenceFilter, isFieldResource, isGlobalReference, isNumericType, isPathInside, isTypeCheckedOperator, isUnknownEnumChoiceSetField, isValidFlowName, isValued, loadPathLevel, matchesReferenceFilter, moveCondition, moveField, navigatePath, otherSourceFieldsOf, outletByKey, outletsOf, parseCanvasNodeId, parseInvariantNumber, parseSourceConnectorId, parseTargetConnectorId, pathAvailableNames, pathContainerLabel, pathKey, pathNotVerifiableMessage, planPaste, referenceRoot, referencedRootsOf, remapConditionLogic, removeCondition, removeField, resolvePath, rewriteReferences, samePath, screenActionNames, screenFieldNames, severityBucket, slugifyFlowName, sourceConnectorId, stageStepNames, stageStepOutputReferenced, stepsOf, targetConnectorId, typeOfCollection, uniqueFlowName, valuedFieldOf, valuedFieldsOf, variantFieldOf, variantOf, variantPresetOf };
-export type { ChoiceSetSource, FieldAssignmentHolder, FilterFieldOption, FilterHolder, FlowActionCall, FlowAnyNode, FlowAssignment, FlowAssignmentItem, FlowAssignmentOperator, FlowAssignmentOperatorEntry, FlowBuilderHttpConfig, FlowCanvasEdge, FlowCanvasNode, FlowCatalogEntry, FlowCatalogParameter, FlowChoice, FlowClipboardNode, FlowClipboardPayload, FlowClipboardResource, FlowCloneRequest, FlowCollectionProcessor, FlowCollectionProcessorType, FlowComparisonOperator, FlowComparisonOperatorEntry, FlowCondition, FlowConditionHolder, FlowConditionLogic, FlowConflictState, FlowConnectionKind, FlowConnector, FlowConnectorTarget, FlowConstant, FlowCreateRequest, FlowCustomError, FlowCustomErrorMessage, FlowCustomProperty, FlowDataType, FlowDataTypeEntry, FlowDecision, FlowDecisionRule, FlowDefinition, FlowDictionaries, FlowDictionaryEntry, FlowDynamicChoiceSet, FlowDynamicScreen, FlowEdge, FlowElementType, FlowElementTypeEntry, FlowEnumValue, FlowErrorCategory, FlowExportQuery, FlowFieldDescription, FlowFieldUsage, FlowFieldValue, FlowFormKind, FlowFormula, FlowFormulaIssue, FlowFormulaUsage, FlowFormulaValidationRequest, FlowFormulaValidationResult, FlowGlobalVariableEntry, FlowInputFieldAssignment, FlowInputParameter, FlowInterviewResult, FlowInterviewStatus, FlowIssueSeverity, FlowLayoutDirection, FlowLayoutNodeInput, FlowLayoutOptions, FlowLayoutResult, FlowListQuery, FlowLoop, FlowNameCheck, FlowNameProblem, FlowNewVersionRequest, FlowNodeBase, FlowNodeCollection, FlowNodeRef, FlowObjectDescription, FlowObjectSummary, FlowOffsetUnit, FlowOrchestratedStage, FlowOutlet, FlowOutline, FlowOutlineConnection, FlowOutlineNode, FlowOutputFieldAssignment, FlowOutputParameter, FlowPalettePick, FlowPastePlan, FlowPasteRename, FlowPasteResource, FlowPendingScreen, FlowProcessType, FlowRecordCreate, FlowRecordDelete, FlowRecordFilter, FlowRecordFilterOperator, FlowRecordLookup, FlowRecordRollback, FlowRecordTriggerType, FlowRecordUpdate, FlowRecordValue, FlowReference, FlowReferenceFilter, FlowReferenceKind, FlowRegionContainerType, FlowResourceCollection, FlowResourceKindEntry, FlowResourceRef, FlowResumeRequest, FlowRunOutcome, FlowRunRequest, FlowSaveRequest, FlowSaveResult, FlowSchedule, FlowScheduledPath, FlowScreen, FlowScreenAction, FlowScreenField, FlowScreenFieldInputsRevisited, FlowScreenFieldNode, FlowScreenFieldPath, FlowScreenFieldType, FlowScreenFieldTypeEntry, FlowScreenNavigation, FlowScreenResponseRequest, FlowScreenTrigger, FlowScreenTriggerInitBehavior, FlowScreenValidationRule, FlowScriptPluginCall, FlowSeverityBucket, FlowSortOption, FlowSortOrder, FlowStage, FlowStageStep, FlowStageStepActionType, FlowStageStepAssignee, FlowStageStepConditionActionType, FlowStageStepRequest, FlowStageStepState, FlowStageStepStatus, FlowStageStepTypeEntry, FlowStart, FlowStartInterviewRequest, FlowStructureDescribed, FlowStructureDescription, FlowStructureInstance, FlowStructureMember, FlowSubflow, FlowSubflowInputAssignment, FlowSubflowOutputAssignment, FlowSummary, FlowTextTemplate, FlowTraceEntry, FlowTransactionModel, FlowTransform, FlowTransformType, FlowTransformValue, FlowTransformValueAction, FlowTriggerType, FlowTypedEntry, FlowTypedValue, FlowUnsupportedNode, FlowValidationIssue, FlowValidationResult, FlowValue, FlowVariable, FlowVersionStatus, FlowVersionSummary, FlowWait, FlowWaitEvent, NamePickerOption, PaletteGroup, PaletteItem, ParameterHolder, PathCatalog, PathContainer, PathContainerKind, PathEntry, PathLevel, PathLevelStatus, PathNavigation, PathNavigationRequest, PathResolution, PathStopReason, PathValueSet, StructureMemberUsage, ValueMode };
+export type { ChoiceSetSource, FieldAssignmentHolder, FilterFieldOption, FilterHolder, FlowActionCall, FlowAnyNode, FlowAssignment, FlowAssignmentItem, FlowAssignmentOperator, FlowAssignmentOperatorEntry, FlowBuilderHttpConfig, FlowCanvasEdge, FlowCanvasNode, FlowCatalogEntry, FlowCatalogParameter, FlowChoice, FlowClipboardNode, FlowClipboardPayload, FlowClipboardResource, FlowCloneRequest, FlowCollectionProcessor, FlowCollectionProcessorType, FlowComparisonOperator, FlowComparisonOperatorEntry, FlowCondition, FlowConditionHolder, FlowConditionLogic, FlowConflictState, FlowConnectionKind, FlowConnector, FlowConnectorTarget, FlowConstant, FlowCreateRequest, FlowCustomError, FlowCustomErrorMessage, FlowCustomProperty, FlowDataType, FlowDataTypeEntry, FlowDecision, FlowDecisionRule, FlowDefinition, FlowDictionaries, FlowDictionaryEntry, FlowDynamicChoiceSet, FlowDynamicScreen, FlowEdge, FlowElementType, FlowElementTypeEntry, FlowEnumValue, FlowErrorCategory, FlowExportQuery, FlowFieldDescription, FlowFieldUsage, FlowFieldValue, FlowFormKind, FlowFormula, FlowFormulaFunction, FlowFormulaFunctionParameter, FlowFormulaIssue, FlowFormulaUsage, FlowFormulaValidationRequest, FlowFormulaValidationResult, FlowGlobalVariableEntry, FlowInputFieldAssignment, FlowInputParameter, FlowInterviewResult, FlowInterviewStatus, FlowIssueSeverity, FlowLayoutDirection, FlowLayoutNodeInput, FlowLayoutOptions, FlowLayoutResult, FlowListQuery, FlowLoop, FlowNameCheck, FlowNameProblem, FlowNewVersionRequest, FlowNodeBase, FlowNodeCollection, FlowNodeRef, FlowObjectDescription, FlowObjectSummary, FlowOffsetUnit, FlowOrchestratedStage, FlowOutlet, FlowOutline, FlowOutlineConnection, FlowOutlineNode, FlowOutputFieldAssignment, FlowOutputParameter, FlowPalettePick, FlowPastePlan, FlowPasteRename, FlowPasteResource, FlowPendingScreen, FlowProcessType, FlowRecordCreate, FlowRecordDelete, FlowRecordFilter, FlowRecordFilterOperator, FlowRecordLookup, FlowRecordRollback, FlowRecordTriggerType, FlowRecordUpdate, FlowRecordValue, FlowReference, FlowReferenceFilter, FlowReferenceKind, FlowRegionContainerType, FlowResourceCollection, FlowResourceKindEntry, FlowResourceRef, FlowResumeRequest, FlowRunOutcome, FlowRunRequest, FlowSaveRequest, FlowSaveResult, FlowSchedule, FlowScheduledPath, FlowScreen, FlowScreenAction, FlowScreenField, FlowScreenFieldInputsRevisited, FlowScreenFieldNode, FlowScreenFieldPath, FlowScreenFieldType, FlowScreenFieldTypeEntry, FlowScreenNavigation, FlowScreenResponseRequest, FlowScreenTrigger, FlowScreenTriggerInitBehavior, FlowScreenValidationRule, FlowScriptPluginCall, FlowSeverityBucket, FlowSortOption, FlowSortOrder, FlowStage, FlowStageStep, FlowStageStepActionType, FlowStageStepAssignee, FlowStageStepConditionActionType, FlowStageStepRequest, FlowStageStepState, FlowStageStepStatus, FlowStageStepTypeEntry, FlowStart, FlowStartInterviewRequest, FlowStructureDescribed, FlowStructureDescription, FlowStructureInstance, FlowStructureMember, FlowSubflow, FlowSubflowInputAssignment, FlowSubflowOutputAssignment, FlowSummary, FlowTextTemplate, FlowTraceEntry, FlowTransactionModel, FlowTransform, FlowTransformType, FlowTransformValue, FlowTransformValueAction, FlowTriggerType, FlowTypedEntry, FlowTypedValue, FlowUnsupportedNode, FlowValidationIssue, FlowValidationResult, FlowValue, FlowVariable, FlowVersionStatus, FlowVersionSummary, FlowWait, FlowWaitEvent, NamePickerOption, PaletteGroup, PaletteItem, ParameterHolder, PathCatalog, PathContainer, PathContainerKind, PathEntry, PathLevel, PathLevelStatus, PathNavigation, PathNavigationRequest, PathResolution, PathStopReason, PathValueSet, StructureMemberUsage, ValueMode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esfaenza/flow-builder",
-  "version": "20.3.29",
+  "version": "20.3.31",
   "peerDependencies": {
     "@angular/cdk": "^20.2.14",
     "@angular/common": "^20.3.28",