@sapui5/sap.suite.ui.generic.template 1.147.2 → 1.148.1

package/src/sap/suite/ui/generic/template/lib/ai/EasyFill/EasyFillApplyHandler.js

@@ -0,0 +1,476 @@
+sap.ui.define([
+    "sap/suite/ui/generic/template/genericUtilities/FeLogger",
+    "sap/suite/ui/generic/template/genericUtilities/FeError",
+    "sap/ui/model/Filter",
+    "sap/ui/model/FilterOperator"
+], function(FeLogger, FeError, Filter, FilterOperator) {
+    "use strict";
+
+    var sClassName = "lib.ai.EasyFill.EasyFillApplyHandler";
+    var oLogger = new FeLogger(sClassName).getLogger();
+
+    /**
+     * Returns the first ValueListParameterInOut parameter matching the given local property name.
+     * Extracted as a module-level helper to avoid no-loop-func ESLint violations.
+     *
+     * @param {Array} aParameters - value-list Parameters array from OData annotations
+     * @param {string} sProperty - local property name to match
+     * @returns {object|undefined}
+     */
+    function fnFindValueListParameter(aParameters, sProperty) {
+        return aParameters.find(function(oParam) {
+            return oParam.RecordType === "com.sap.vocabularies.Common.v1.ValueListParameterInOut" &&
+                oParam.LocalDataProperty &&
+                oParam.LocalDataProperty.PropertyPath === sProperty;
+        });
+    }
+
+    /**
+     * EasyFillApplyHandler
+     *
+     * Responsible for:
+    * 1. Applying AI-suggested field values from transient contexts back to the live ObjectPage context on Confirm.
+    * 2. Building and validating staged collection (table) row updates before allowing save.
+    * 3. Resetting the EasyFill dialog state (model, staged values, transient context) on cancel or clear.
+     */
+    return {
+
+        /**
+         * Applies all AI-suggested scalar field values from the transient context to the live ObjectPage context.
+         * Called when the user clicks "Confirm" in the EasyFill dialog.
+         *
+         * 
+         * Only properties present in the updatable lookup map are written back.
+         * Collection (table) row values are copied from transient staging contexts to the
+         * live row contexts only here, so the ObjectPage table updates only after confirm.
+         *
+         * @param {object} oTransientContextForEasyFill - the transient OData context holding AI-suggested values
+         * @param {object} oObjectPageContext - the live ObjectPage binding context to write values into
+         * @param {object} mUpdatableLookupMap - map of { fieldName: value } for fields that are updatable
+         * @param {object} oTableStagingState - table staging state { mStagedRows }
+         * @param {object} mCollectionState - collection tracking state
+         */
+        applyAndSave: function(oTransientContextForEasyFill, oObjectPageContext, mUpdatableLookupMap, oTableStagingState, mCollectionState) {
+            if (!oTransientContextForEasyFill || !oObjectPageContext) {
+                oLogger.warning("applyAndSave: missing transient or ObjectPage context — skipping apply");
+                return;
+            }
+
+            var oTransientObject = oTransientContextForEasyFill.getObject();
+            var iApplied = 0;
+
+            // Copy each AI-suggested property value from the transient context to the live OP context
+            for (var sProp in oTransientObject) {
+                if (sProp !== "__metadata" && mUpdatableLookupMap[sProp]) {
+                    oObjectPageContext.setProperty(sProp, oTransientObject[sProp]);
+                    iApplied++;
+                }
+            }
+
+            oLogger.debug("applyAndSave: applied " + iApplied + " field(s) to ObjectPage context");
+
+            var mCollectionUpdates = this.buildStagedCollectionUpdates(oTableStagingState, mCollectionState);
+            var iCollectionApplied = 0;
+
+            Object.keys(mCollectionUpdates).forEach(function(sCollectionName) {
+                var aRowUpdates = mCollectionUpdates[sCollectionName] || [];
+                aRowUpdates.forEach(function(oRowUpdate) {
+                    var oResolvedRow = this._resolveCollectionRowContext(sCollectionName, oRowUpdate, mCollectionState);
+                    if (!oResolvedRow || !oResolvedRow.context) {
+                        return;
+                    }
+
+                    Object.keys(oRowUpdate).forEach(function(sPropertyName) {
+                        if (sPropertyName === "_rowIndex" || sPropertyName === "_contextPath") {
+                            return;
+                        }
+                        oResolvedRow.context.setProperty(sPropertyName, oRowUpdate[sPropertyName]);
+                        iCollectionApplied++;
+                    });
+                }, this);
+            }, this);
+
+            oLogger.debug("applyAndSave: applied " + iCollectionApplied + " staged table value(s) to ObjectPage context");
+        },
+
+        /**
+         * Builds a collection updates map from the staged transient row contexts.
+         * Only editable scalar properties whose staged value differs from the live row value are included.
+         *
+         * @param {object} oTableStagingState - table staging state { mStagedRows }
+         * @param {object} mCollectionState - collection tracking state
+         * @returns {object} map of { navProperty: [ rowUpdate ] }
+         */
+        buildStagedCollectionUpdates: function(oTableStagingState, mCollectionState) {
+            var mCollectionUpdates = Object.create(null);
+            var mStagedRowsByCollection = oTableStagingState && oTableStagingState.mStagedRows;
+
+            Object.keys(mStagedRowsByCollection || {}).forEach(function(sCollectionName) {
+                var aStagedRows = mStagedRowsByCollection[sCollectionName] || [];
+                var mCollectionPropertyMap = mCollectionState.mCollectionProperties[sCollectionName] || Object.create(null);
+
+                aStagedRows.forEach(function(oStagedRow) {
+                    var oRealContext = oStagedRow.realContext;
+                    var oTransientContext = oStagedRow.transientContext;
+                    if (!oRealContext || !oTransientContext) {
+                        return;
+                    }
+
+                    var oRealRowObject = oRealContext.getObject && oRealContext.getObject();
+                    var oRowUpdate = {
+                        _rowIndex: oStagedRow.rowIndex,
+                        _contextPath: oRealContext.getPath && oRealContext.getPath()
+                    };
+                    var bHasChanges = false;
+
+                    (oStagedRow.propertyNames || []).forEach(function(sPropertyName) {
+                        var oPropertyMeta = mCollectionPropertyMap[sPropertyName];
+                        if (!oPropertyMeta || !this._isEditableProperty(oPropertyMeta, oRealRowObject)) {
+                            return;
+                        }
+
+                        var vLiveValue = oRealContext.getProperty(sPropertyName);
+                        var vStagedValue = oTransientContext.getProperty(sPropertyName);
+                        if (!this._isSupportedStagedValue(vStagedValue)) {
+                            return;
+                        }
+
+                        if (!this._areValuesEqual(vLiveValue, vStagedValue)) {
+                            oRowUpdate[sPropertyName] = vStagedValue;
+                            bHasChanges = true;
+                        }
+                    }, this);
+
+                    if (bHasChanges) {
+                        if (!mCollectionUpdates[sCollectionName]) {
+                            mCollectionUpdates[sCollectionName] = [];
+                        }
+                        mCollectionUpdates[sCollectionName].push(oRowUpdate);
+                    }
+                }, this);
+            }, this);
+
+            return mCollectionUpdates;
+        },
+
+        /**
+         * Returns whether any staged collection row currently differs from the live ObjectPage rows.
+         *
+         * @param {object} oTableStagingState - table staging state { mStagedRows }
+         * @param {object} mCollectionState - collection tracking state
+         * @returns {boolean}
+         */
+        hasStagedCollectionChanges: function(oTableStagingState, mCollectionState) {
+            var mCollectionUpdates = this.buildStagedCollectionUpdates(oTableStagingState, mCollectionState);
+            return Object.keys(mCollectionUpdates).some(function(sCollectionName) {
+                return (mCollectionUpdates[sCollectionName] || []).length > 0;
+            });
+        },
+
+        /**
+         * Validates each collection (table) row update by checking that value-help constrained
+         * properties contain values that exist in the corresponding value-help collection.
+         *
+         * Returns an array of validation error objects for any values that fail the check.
+         * If validation cannot be performed (e.g. missing metadata), the property is skipped
+         * and save is not blocked.
+         *
+         * @param {object} mCollectionUpdates - map of { navProperty: [ rowUpdate ] }
+         * @param {object} mCollectionState - collection tracking state: { mCollectionProperties, mCollectionEntityTypes, mCollectionRowContextsByPath, mCollectionRowContexts }
+         * @param {object} oObjectPageModel - the OData model (used to read value-help collections)
+         * @param {object} oRb - i18n resource bundle
+         * @param {object} oFieldCollector - EasyFillFieldCollector (used for isEditableByContextObject)
+         * @param {object} oGenericAnnotationHelper - GenericAnnotationHelper (used for isValueHelpTableAvailable)
+         * @returns {Promise<Array>} array of { collectionName, collectionLabel, rowLabel, rowIndex, rowPath, propertyName, propertyLabel }
+         */
+        validateCollectionUpdatesAgainstValueHelp: async function(mCollectionUpdates, mCollectionState, oObjectPageModel, oRb, oFieldCollector, oGenericAnnotationHelper) {
+            var oMetaModel = oObjectPageModel && oObjectPageModel.getMetaModel();
+            if (!oMetaModel) {
+                oLogger.warning("validateCollectionUpdatesAgainstValueHelp: no MetaModel available");
+                return [];
+            }
+
+            var aValidationErrors = [];
+            var aCollectionNames = Object.keys(mCollectionUpdates || {});
+
+            for (var i = 0; i < aCollectionNames.length; i++) {
+                var sCollectionName = aCollectionNames[i];
+                var aRowUpdates = mCollectionUpdates[sCollectionName] || [];
+                var mCollectionPropertyMap = mCollectionState.mCollectionProperties[sCollectionName] || Object.create(null);
+                var oCollectionEntityType = mCollectionState.mCollectionEntityTypes[sCollectionName];
+
+                if (!oCollectionEntityType) { continue; }
+
+                // Use the field mapping description as the collection label in error messages
+                var sCollectionLabel = sCollectionName;
+
+                for (var j = 0; j < aRowUpdates.length; j++) {
+                    var oRowUpdate = aRowUpdates[j];
+                    var oResolvedRow = this._resolveCollectionRowContext(sCollectionName, oRowUpdate, mCollectionState);
+                    if (!oResolvedRow || !oResolvedRow.context) { continue; }
+
+                    var oRowContext = oResolvedRow.context;
+                    var oRowObject = oRowContext.getObject && oRowContext.getObject();
+                    var sRowLabel = oRb.getText("EASY_FILL_TABLE_ROW_LABEL", [String((oResolvedRow.rowIndex || 0) + 1)]);
+
+                    var aPropNames = Object.keys(oRowUpdate);
+                    for (var k = 0; k < aPropNames.length; k++) {
+                        var sPropertyName = aPropNames[k];
+                        if (sPropertyName === "_rowIndex" || sPropertyName === "_contextPath") { continue; }
+
+                        var oPropertyMeta = mCollectionPropertyMap[sPropertyName];
+                        // Skip non-editable properties — they cannot be written back
+                        if (!oPropertyMeta || !oFieldCollector.isEditableByContextObject(oPropertyMeta, oRowObject)) { continue; }
+
+                        // Only validate properties that have an associated value-help table
+                        if (!oGenericAnnotationHelper.isValueHelpTableAvailable(oPropertyMeta)) { continue; }
+
+                        var vUpdatedValue = oRowUpdate[sPropertyName];
+                        if (vUpdatedValue === null || vUpdatedValue === undefined || typeof vUpdatedValue === "object") { continue; }
+
+                        try {
+                            var sPropertyPath = oMetaModel.getODataProperty(oCollectionEntityType, sPropertyName, true);
+                            if (!sPropertyPath) { continue; }
+
+                            var oPropertyContext = oMetaModel.createBindingContext(sPropertyPath);
+                            var oValueLists = await oMetaModel.getODataValueLists(oPropertyContext);
+                            var oDefaultValueList = oValueLists && oValueLists[""];
+
+                            if (!oDefaultValueList || !oDefaultValueList.CollectionPath || !oDefaultValueList.CollectionPath.String) { continue; }
+
+                            // Resolve which value-list property maps to this local property
+                            var sValueListProperty = sPropertyName;
+                            if (Array.isArray(oDefaultValueList.Parameters)) {
+                                var oParameter = fnFindValueListParameter(oDefaultValueList.Parameters, sPropertyName);
+                                if (oParameter && oParameter.ValueListProperty && oParameter.ValueListProperty.String) {
+                                    sValueListProperty = oParameter.ValueListProperty.String;
+                                }
+                            }
+
+                            // Check that the AI-provided value exists in the value-help collection
+                            var bValueFound = await this._readValueListByEquality(
+                                oDefaultValueList.CollectionPath.String,
+                                sValueListProperty,
+                                vUpdatedValue,
+                                oObjectPageModel
+                            );
+
+                            if (!bValueFound) {
+                                aValidationErrors.push({
+                                    collectionName: sCollectionName,
+                                    collectionLabel: sCollectionLabel,
+                                    rowLabel: sRowLabel,
+                                    rowIndex: oResolvedRow.rowIndex,
+                                    rowPath: oRowContext.getPath && oRowContext.getPath(),
+                                    propertyName: sPropertyName,
+                                    propertyLabel: this._getPropertyLabel(oPropertyMeta) || sPropertyName
+                                });
+                                oLogger.warning("validateCollectionUpdatesAgainstValueHelp: invalid value for '" + sPropertyName + "' in row " + oResolvedRow.rowIndex);
+                            }
+                        } catch (e) {
+                            // If metadata or value list cannot be resolved, skip the check and do not block save
+                            oLogger.warning("validateCollectionUpdatesAgainstValueHelp: could not validate '" + sPropertyName + "': " + (e && e.message));
+                        }
+                    }
+                }
+            }
+
+            return aValidationErrors;
+        },
+
+        /**
+         * Updates the EasyFill dialog model to reflect the current table validation state.
+         * Sets hasTableValidationErrors and a human-readable summary message (up to 3 errors shown).
+         *
+         * @param {Array} aValidationErrors - array of validation error objects
+         * @param {object} oDialogModel - the easyFillDialogModel JSONModel
+         * @param {object} oRb - i18n resource bundle
+         */
+        applyTableValidationState: function(aValidationErrors, oDialogModel, oRb) {
+            if (!aValidationErrors || aValidationErrors.length === 0) {
+                oDialogModel.setProperty("/hasTableValidationErrors", false);
+                oDialogModel.setProperty("/tableValidationMessage", "");
+                return;
+            }
+
+            // Show up to 3 errors in the summary message to avoid overwhelming the user
+            var sSummary = aValidationErrors.slice(0, 3).map(function(oError) {
+                return oError.collectionLabel + " / " + oError.rowLabel + " / " + oError.propertyLabel;
+            }).join(", ");
+
+            oDialogModel.setProperty("/hasTableValidationErrors", true);
+            oDialogModel.setProperty(
+                "/tableValidationMessage",
+                oRb.getText("EASY_FILL_TABLE_VALIDATION_MESSAGE", [sSummary])
+            );
+
+            oLogger.warning("applyTableValidationState: " + aValidationErrors.length + " validation error(s) found");
+        },
+
+        /**
+         * Resets the EasyFill dialog to its initial empty state.
+         * Clears the dialog model properties, destroys table preview items,
+         * and optionally clears the text area value.
+         *
+         * @param {boolean} bRemoveTextAreaValue - if true, also clears the user input text area
+         * @param {object} oDialogModel - the easyFillDialogModel JSONModel
+         * @param {object} oController - MVC controller (used to byId controls)
+         * @param {object} mCollectionUpdates - mutable collection updates map (cleared in place)
+         * @param {object} oEasyFillLayoutMode - EasyFillLayoutMode enum
+         * @param {function} fnRevertStagedUpdates - EasyFillTableRenderer.revertStagedCollectionUpdates
+         * @param {function} fnResetTransientContext - EasyFillFormRenderer.resetTransientContext
+         */
+        resetEasyFill: function(bRemoveTextAreaValue, oDialogModel, oController, mCollectionUpdates, oEasyFillLayoutMode, fnRevertStagedUpdates, fnResetTransientContext) {
+            // Destroy all rendered table preview sections
+            var oTablePreviewContainer = oController.byId("EasyFillTablePreviewContainer");
+            if (oTablePreviewContainer) {
+                oTablePreviewContainer.destroyItems();
+            }
+
+            // Revert any staged table row values back to original
+            fnRevertStagedUpdates();
+
+            // Reset the transient context (discard all staged scalar AI values)
+            fnResetTransientContext();
+
+            // Reset all dialog model properties to their initial state
+            oDialogModel.setProperty("/isFormVisible", false);
+            oDialogModel.setProperty("/isIllustrationVisible", true);
+            oDialogModel.setProperty("/isSaveEnabled", false);
+            oDialogModel.setProperty("/stateType", "Initial");
+            oDialogModel.setProperty("/feedbackEnabled", true);
+            oDialogModel.setProperty("/feedbackPressedUp", false);
+            oDialogModel.setProperty("/feedbackPressedDown", false);
+            oDialogModel.setProperty("/isFullScreen", true);
+            oDialogModel.setProperty("/hasTableUpdates", false);
+            oDialogModel.setProperty("/hasTableValidationErrors", false);
+            oDialogModel.setProperty("/tableValidationMessage", "");
+            oDialogModel.setProperty("/easyFillMode", oEasyFillLayoutMode.CondensedMode);
+            oDialogModel.setProperty("/llmData", {});
+            oDialogModel.setProperty("/sections", []);
+
+            // Clear the mutable collection updates map in place
+            Object.keys(mCollectionUpdates).forEach(function(sKey) {
+                delete mCollectionUpdates[sKey];
+            });
+
+            if (bRemoveTextAreaValue) {
+                var oTextArea = oController.byId("EasyFillInputTextArea");
+                if (oTextArea) {
+                    oTextArea.setValue("");
+                }
+                oDialogModel.setProperty("/isEasyFillButtonEnabled", false);
+            }
+
+            oLogger.debug("resetEasyFill: dialog state reset" + (bRemoveTextAreaValue ? " (including text area)" : ""));
+        },
+
+        // ─── Private Helpers ─────────────────────────────────────────────────────
+
+        /**
+         * Resolves an OData row context for a collection row update.
+         * Prefers context path; falls back to row index.
+         * (Mirrors EasyFillTableRenderer._resolveCollectionRowContext to keep this module independent.)
+         *
+         * @param {string} sCollectionName
+         * @param {object} oRowUpdate
+         * @param {object} mCollectionState
+         * @returns {{ context, rowIndex }|null}
+         */
+        _resolveCollectionRowContext: function(sCollectionName, oRowUpdate, mCollectionState) {
+            var mByPath = mCollectionState.mCollectionRowContextsByPath[sCollectionName] || Object.create(null);
+            var sContextPath = oRowUpdate && oRowUpdate._contextPath;
+            if (typeof sContextPath === "string" && mByPath[sContextPath]) {
+                return mByPath[sContextPath];
+            }
+            var iRowIndex = oRowUpdate && oRowUpdate._rowIndex;
+            var aRowContexts = mCollectionState.mCollectionRowContexts[sCollectionName] || [];
+            if (typeof iRowIndex === "number" && aRowContexts[iRowIndex]) {
+                return { context: aRowContexts[iRowIndex], rowIndex: iRowIndex };
+            }
+            return null;
+        },
+
+        /**
+         * Checks whether a given value exists in a value-help collection via an OData $filter read.
+         * Returns true if the value is found or if the read fails (fail-open to not block save unexpectedly).
+         *
+         * @param {string} sCollectionPath - value-help entity set name
+         * @param {string} sValueListProperty - property name in the value-help to filter on
+         * @param {*} vValue - the value to look up
+         * @param {object} oObjectPageModel - the OData model
+         * @returns {Promise<boolean>}
+         */
+        _readValueListByEquality: function(sCollectionPath, sValueListProperty, vValue, oObjectPageModel) {
+            return new Promise(function(resolve) {
+                oObjectPageModel.read("/" + sCollectionPath, {
+                    filters: [
+                        new Filter({
+                            path: sValueListProperty,
+                            operator: FilterOperator.EQ,
+                            value1: vValue
+                        })
+                    ],
+                    success: function(oResponse) {
+                        // Value found if the filtered result set is non-empty
+                        resolve(!!(oResponse && Array.isArray(oResponse.results) && oResponse.results.length > 0));
+                    },
+                    error: function() {
+                        // On error, resolve true to not block save (fail-open)
+                        resolve(true);
+                    }
+                });
+            });
+        },
+
+        /**
+         * Extracts the display label for an OData property.
+         * Prefers Common.Label annotation, falls back to sap:label.
+         *
+         * @param {object} oPropertyMeta - OData property metadata
+         * @returns {string|null}
+         */
+        _getPropertyLabel: function(oPropertyMeta) {
+            if (!oPropertyMeta) { return null; }
+            var oLabel = oPropertyMeta["com.sap.vocabularies.Common.v1.Label"];
+            if (oLabel && oLabel.String) {
+                return oLabel.String;
+            }
+            return oPropertyMeta["sap:label"] || null;
+        },
+
+        _isEditableProperty: function(oPropertyMeta, oRowObject) {
+            if (!oPropertyMeta) {
+                return false;
+            }
+            var sUpdatable = oPropertyMeta["sap:updatable"];
+            if (sUpdatable) {
+                return sUpdatable !== "false";
+            }
+            var oAnnotation = oPropertyMeta["com.sap.vocabularies.Common.v1.FieldControl"];
+            if (oAnnotation && oAnnotation["EnumMember"]) {
+                return oAnnotation["EnumMember"] !== "com.sap.vocabularies.Common.v1.FieldControlType/ReadOnly";
+            }
+            var sFieldControl = oPropertyMeta["sap:field-control"];
+            if (sFieldControl) {
+                var iFieldControlValue = oRowObject && oRowObject[sFieldControl];
+                return iFieldControlValue !== 1;
+            }
+            return true;
+        },
+
+        _isSupportedStagedValue: function(vValue) {
+            return vValue === null ||
+                vValue === undefined ||
+                typeof vValue !== "object" ||
+                vValue instanceof Date;
+        },
+
+        _areValuesEqual: function(vLeft, vRight) {
+            if (vLeft instanceof Date && vRight instanceof Date) {
+                return vLeft.getTime() === vRight.getTime();
+            }
+            return vLeft === vRight;
+        }
+    };
+});