@sapui5/sap.fe.controls 1.147.0 → 1.148.0

package/src/sap/fe/controls/easyFilter/EasyFilterBarContainer.tsx

@@ -1,4 +1,5 @@
 import Log from "sap/base/Log";
+import encodeXML from "sap/base/security/encodeXML";
 import type { EnhanceWithUI5, StateOf } from "sap/fe/base/ClassSupport";
 import {
 	aggregation,
@@ -50,6 +51,7 @@ import type EasyFilter from "ux/eng/fioriai/reuse/easyfilter/EasyFilter";
 import type { EasyFilterMetadata, EasyFilterResult, PropertyMetadata } from "ux/eng/fioriai/reuse/easyfilter/EasyFilter";
 import type { Success } from "ux/eng/fioriai/reuse/shared";
 import type { EventHandler } from "../../../../../../../types/extension_types";
+import ErrorMessageHandler from "./ErrorMessageHandler";
 import { triggerPXIntegration } from "./PXFeedback";
 import EasyFilterUtils from "./utils";
 
@@ -111,8 +113,17 @@ export type NonValueHelpTokenDefinition = {
 
 export type TokenDefinition = ValueHelpTokenDefinition | NonValueHelpTokenDefinition;
 
+export type SortDefinition = {
+	key: string;
+	descending: boolean;
+};
+
 export type TokenSetters = "setSelectedValues";
 
+export type GroupLevelDefinition = {
+	key: string;
+};
+
 export type EasyFilterPropertyMetadata = PropertyMetadata &
 	(
 		| {
@@ -184,12 +195,25 @@ export default class EasyFilterBarContainer extends Control {
 	@event()
 	tokensChanged?: EventHandler<UI5Event<{ tokens: TokenDefinition[]; reset: boolean }, EasyFilterBarContainer>>;
 
+	@event()
+	sortersChanged?: EventHandler<UI5Event<{ sorters: SortDefinition[] }, EasyFilterBarContainer>>;
+
+	@event()
+	groupLevelsChanged?: EventHandler<UI5Event<{ groupLevels: GroupLevelDefinition[] }, EasyFilterBarContainer>>;
+
 	@event()
 	queryChanged?: EventHandler<UI5Event<{ query: string }, EasyFilterBarContainer>>;
 
 	@event()
 	showValueHelp?: EventHandler<EasyFilterBarContainer$ShowValueHelpEvent>;
 
+	@event()
+	liveChange?: EventHandler<UI5Event<{ query: string }, EasyFilterBarContainer>>;
+
+	/** Fires when the user manually removes or edits a filter token. Does not fire when tokens are set by the AI search result. */
+	@event()
+	tokensChangedByUser?: EventHandler<UI5Event<{ tokens: TokenDefinition[] }, EasyFilterBarContainer>>;
+
 	@event()
 	clearFilters?: EventHandler;
 
@@ -205,6 +229,8 @@ export default class EasyFilterBarContainer extends Control {
 	protected state: StateOf<{
 		showResult: boolean;
 		tokens: TokenDefinition[];
+		sorters: SortDefinition[];
+		groupLevels: GroupLevelDefinition[];
 		tokenizerEditable: boolean;
 		showSingleValueMessageStrip?: boolean;
 		singleValueMessageStripText?: string;
@@ -217,6 +243,8 @@ export default class EasyFilterBarContainer extends Control {
 	}> = {
 		showResult: false,
 		tokens: [] as TokenDefinition[],
+		sorters: [] as SortDefinition[],
+		groupLevels: [] as GroupLevelDefinition[],
 		tokenizerEditable: true,
 		showSingleValueMessageStrip: false,
 		singleValueMessageStripText: "",
@@ -257,6 +285,10 @@ export default class EasyFilterBarContainer extends Control {
 
 	private shouldMessageStripRemove = true;
 
+	private supportsSorting = true;
+
+	private supportsGrouping = true;
+
 	constructor(properties: string | ($ControlSettings & PropertiesOf<EasyFilterBarContainer>), others?: $ControlSettings) {
 		super(properties as string, others);
 		this.initialize();
@@ -275,7 +307,6 @@ export default class EasyFilterBarContainer extends Control {
 			this.setProperty("appId", appId, true);
 			await this.inputFieldReady;
 			this.easyFilterInput.current?.setProperty("appId", appId, true);
-			await this.easyFilterInput.current?.initShellHistoryProvider();
 		}
 	}
 
@@ -416,6 +447,7 @@ export default class EasyFilterBarContainer extends Control {
 			this.setMessageStrip(easyFilterResult.message);
 			this.invisibleMessage.announce(this.resourceBundle.getText(easyFilterResult.message), InvisibleMessageMode.Assertive);
 			this.state.messageStripType = MessageType.Warning;
+			this.state.groupLevels = [];
 			Log.error("Error while generating filter criteria: ", easyFilterResult.message);
 		}
 
@@ -498,12 +530,162 @@ export default class EasyFilterBarContainer extends Control {
 			}
 
 			const updatedTokens = this.verifySingleSelectTokenValues(tokens);
+
+			// Validate and store sort expressions (applied to table directly, not shown as tokens)
+			this.state.sorters = this.supportsSorting ? this.validateSortExpressions(easyFilterResult.data.sorters) : [];
 			this.state.showResult = true;
 			this.state.thumbButtonEnabled = true;
 			this.state.thumbDownButtonPressed = false;
 			this.state.thumbUpButtonPressed = false;
 			this.state.tokens = updatedTokens;
 		}
+
+		this.state.groupLevels = this.supportsGrouping ? this.applyGroupLevels(easyFilterResult.data.groupLevels) : [];
+
+		this.showUnsupportedCapabilitiesWarning(easyFilterResult.data.sorters, easyFilterResult.data.groupLevels);
+	}
+
+	/**
+	 * Shows a warning when the app does not support the LLM's sort/group expressions.
+	 * @param sorters Sort expressions from the LLM.
+	 * @param groupLevels Group levels from the LLM.
+	 */
+	private showUnsupportedCapabilitiesWarning(
+		sorters: EasyFilter.EasyFilterSortExpression[] | undefined,
+		groupLevels: EasyFilter.EasyFilterGroupLevelDefinition[] | undefined
+	): void {
+		const hasSortersFromLLM = sorters && sorters.length > 0;
+		const hasGroupLevelsFromLLM = groupLevels && groupLevels.length > 0;
+		const sortingUnsupported = !this.supportsSorting && hasSortersFromLLM;
+		const groupingUnsupported = !this.supportsGrouping && hasGroupLevelsFromLLM;
+
+		if (sortingUnsupported && groupingUnsupported) {
+			this.appendMessageStrip(this.resourceBundle.getText("M_EASY_FILTER_SORTING_AND_GROUPING_NOT_SUPPORTED"), MessageType.Warning);
+		} else if (sortingUnsupported) {
+			this.appendMessageStrip(this.resourceBundle.getText("M_EASY_FILTER_SORTING_NOT_SUPPORTED"), MessageType.Warning);
+		} else if (groupingUnsupported) {
+			this.appendMessageStrip(this.resourceBundle.getText("M_EASY_FILTER_GROUPING_NOT_SUPPORTED"), MessageType.Warning);
+		}
+	}
+
+	/**
+	 * Updates whether the app supports sorting and grouping based on table personalization settings.
+	 * @param sorting Whether the app supports sorting.
+	 * @param grouping Whether the app supports grouping.
+	 */
+	public setPersonalizationSupport(sorting: boolean, grouping: boolean): void {
+		this.supportsSorting = sorting;
+		this.supportsGrouping = grouping;
+	}
+
+	/**
+	 *  Validates and triggers the groupLevelsChanged function, which warns about non-groupable fields.
+	 * @param groupLevels The group levels to validate and apply
+	 * @returns GroupLevelDefinition[] An array of valid group level definitions to be applied
+	 */
+	private applyGroupLevels(groupLevels: GroupLevelDefinition[] | undefined): GroupLevelDefinition[] {
+		const metadata = this.filterBarMetadata as EasyFilterPropertyMetadata[];
+
+		if (!metadata || !groupLevels || groupLevels.length === 0) {
+			return [];
+		}
+
+		const resolveField = (groupDef: GroupLevelDefinition): EasyFilterPropertyMetadata | undefined => {
+			const propertyName = EasyFilterUtils.resolvePropertyName(groupDef.key);
+			const field = metadata.find((f) => f.name === groupDef.key || f.name.endsWith(`/${propertyName}`));
+			if (!field) {
+				Log.warning(`EasyFilterBarContainer: group key "${groupDef.key}" not found in filter bar metadata, skipping`);
+			}
+			return field;
+		};
+
+		if (groupLevels.length === 1) {
+			const errorHandler = new ErrorMessageHandler();
+			const field = resolveField(groupLevels[0]);
+			if (!field) return [];
+			const isGroupable = errorHandler.isGroupableProperty(field);
+			if (errorHandler.hasErrors()) {
+				this.appendMessageStrip(encodeXML(errorHandler.getErrorMessage()), MessageType.Warning);
+			}
+			return isGroupable ? [groupLevels[0]] : [];
+		}
+
+		// Multiple group levels: find the first valid groupable field
+		const errorHandler = new ErrorMessageHandler();
+		let firstGroupableDef: GroupLevelDefinition | undefined;
+		let firstGroupableLabel: string | undefined;
+
+		for (const groupDef of groupLevels) {
+			const field = resolveField(groupDef);
+			if (!field) continue;
+			if (errorHandler.isGroupableProperty(field)) {
+				if (!firstGroupableDef) {
+					firstGroupableDef = groupDef;
+					firstGroupableLabel = field.label ?? field.name;
+				}
+			}
+		}
+
+		if (firstGroupableDef) {
+			const warning = this.resourceBundle.getText("M_EASY_FILTER_MULTIPLE_GROUP_WARNING", [firstGroupableLabel]);
+			this.appendMessageStrip(encodeXML(warning), MessageType.Warning);
+			return [firstGroupableDef];
+		}
+
+		// All fields are non-groupable
+		if (errorHandler.hasErrors()) {
+			this.appendMessageStrip(encodeXML(errorHandler.getErrorMessage()), MessageType.Warning);
+		}
+		return [];
+	}
+
+	/**
+	 * Validates sort expressions from the AI result and returns valid sort definitions.
+	 * @param sortExpressions The sort expressions from the ABAP service.
+	 * @returns Array of validated sort definitions.
+	 * @private
+	 */
+	private validateSortExpressions(sortExpressions?: EasyFilter.EasyFilterSortExpression[]): SortDefinition[] {
+		if (!sortExpressions || sortExpressions.length === 0) {
+			return [];
+		}
+
+		const nonSortableFields: string[] = [];
+
+		const validSorters = sortExpressions
+			.filter((sortExpression) => {
+				// Validate that the field exists in metadata and is sortable
+				const fieldMetadata = this.filterBarMetadata?.find((field) => {
+					const fieldName = field.name.split("/").pop();
+					return fieldName === sortExpression.key || field.name === sortExpression.key;
+				});
+
+				if (!fieldMetadata) {
+					return false;
+				}
+
+				if (fieldMetadata.sortable === false) {
+					nonSortableFields.push(fieldMetadata.label ?? sortExpression.key);
+					return false;
+				}
+
+				return true;
+			})
+			.map((sortExpression) => {
+				const propertyName = sortExpression.key.split("/").pop() ?? sortExpression.key;
+				return {
+					key: propertyName,
+					descending: sortExpression.descending
+				};
+			});
+
+		// Show warning message for non-sortable fields
+		if (nonSortableFields.length > 0) {
+			const message = this.resourceBundle.getText("M_EASY_FILTER_NON_SORTABLE", [nonSortableFields.join(", ")]);
+			this.appendMessageStrip(message, MessageType.Warning);
+		}
+
+		return validSorters;
 	}
 
 	//every single select menu type should have only one value, else splice to one value and update the  message strip
@@ -547,6 +729,21 @@ export default class EasyFilterBarContainer extends Control {
 		this.state.showMessageStrip = true;
 	}
 
+	setMessageStripWithType(text: string, type: MessageType): void {
+		this.setMessageStrip(text);
+		this.state.messageStripType = type;
+	}
+
+	/**
+	 * Appends a message to the existing message strip instead of overwriting it.
+	 * @param text The message text to append.
+	 * @param type The message type for this message.
+	 */
+	appendMessageStrip(text: string, type: MessageType): void {
+		const combined = this.state.showMessageStrip && this.state.messageStripText ? `${this.state.messageStripText}<br>${text}` : text;
+		this.setMessageStripWithType(combined, type);
+	}
+
 	createPopoverForInnerControls(): Popover {
 		if (!this.innerControlPopover) {
 			this.innerControlPopover = (
@@ -637,14 +834,26 @@ export default class EasyFilterBarContainer extends Control {
 				/**
 				 * The user has acknowledged the message strip and understood the issue.
 				 * When the tokens are updated next time, displaying the message strip again serves no purpose.
-				 * Additionally, once the tokens are updated, the input field text will be removed
-				 * rendering the message strip irrelevant. However, the message strip will be displayed again the next time the "GO" button is pressed.
+				 * Additionally, once the tokens are updated, the input field text is removed
+				 * rendering the message strip irrelevant. However, the message strip is displayed again the next time the "Go" button is pressed.
 				 */
 				this.clearMessageStrip();
 				this.clearMessageStripForSingleValue();
 			}
 			this.shouldMessageStripRemove = true;
 		}
+
+		if (changedProps.includes("sorters")) {
+			this.fireEvent("sortersChanged", {
+				sorters: this.state.sorters
+			});
+		}
+
+		if (changedProps.includes("groupLevels")) {
+			this.fireEvent("groupLevelsChanged", {
+				groupLevels: this.state.groupLevels
+			});
+		}
 		//Resetting to default values
 		this.isMandatoryCheckRequired = false;
 		this.shouldTokenChangeEventFired = true;
@@ -752,6 +961,7 @@ export default class EasyFilterBarContainer extends Control {
 						}}
 						liveChange={(): void => {
 							this.state.tokenizerEditable = false;
+							this.fireEvent("liveChange", { query: this.getQuery() });
 						}}
 					/>
 
@@ -797,6 +1007,7 @@ export default class EasyFilterBarContainer extends Control {
 												newTokens.splice(tokenIndex, 1);
 												this.state.tokens = newTokens;
 												this.updateFilterInput("tokenUpdated");
+												this.fireEvent("tokensChangedByUser", { tokens: [...this.state.tokens] });
 											}}
 										>
 											{{
@@ -829,7 +1040,7 @@ export default class EasyFilterBarContainer extends Control {
 						/>
 					</FlexBox>
 				</FlexBox>
-				<FlexBox renderType="Bare">
+				<VBox renderType="Bare" class={"sapUiTinyMarginTop sapFeControlsGap8px"}>
 					<MessageStrip
 						text={bindState(this.state, "singleValueMessageStripText")}
 						showIcon={true}
@@ -840,23 +1051,23 @@ export default class EasyFilterBarContainer extends Control {
 							this.clearMessageStripForSingleValue();
 						}}
 					></MessageStrip>
-				</FlexBox>
-				<FlexBox renderType="Bare" class={"sapFeControlsGap8px"}>
-					<MessageStrip
-						type={bindState(this.state, "messageStripType")}
-						text={bindState(this.state, "messageStripText")}
-						showIcon={true}
-						enableFormattedText={true}
-						showCloseButton={true}
-						close={(): void => {
-							this.clearMessageStrip();
-						}}
-						visible={bindState(this.state, "showMessageStrip")}
-					></MessageStrip>
-					<HBox visible={and(bindState(this.state, "showMessageStrip"), not(bindState(this.state, "showResult")))}>
-						{thumbUpButtonMessageStripe}, {thumbDownButtonMessageStripe}
-					</HBox>
-				</FlexBox>
+					<FlexBox renderType="Bare" class={"sapFeControlsGap8px"}>
+						<MessageStrip
+							type={bindState(this.state, "messageStripType")}
+							text={bindState(this.state, "messageStripText")}
+							showIcon={true}
+							enableFormattedText={true}
+							showCloseButton={true}
+							close={(): void => {
+								this.clearMessageStrip();
+							}}
+							visible={bindState(this.state, "showMessageStrip")}
+						></MessageStrip>
+						<HBox visible={and(bindState(this.state, "showMessageStrip"), not(bindState(this.state, "showResult")))}>
+							{thumbUpButtonMessageStripe}, {thumbDownButtonMessageStripe}
+						</HBox>
+					</FlexBox>
+				</VBox>
 			</VBox>
 		) as VBox;
 		FESRHelper.setSemanticStepname($topGoBtn.current!, "press", "fe:ai:search");
@@ -891,10 +1102,12 @@ export default class EasyFilterBarContainer extends Control {
 	resetState(clearAllFilters = true, isResettingToDefaultTokens = false): void {
 		if (clearAllFilters) {
 			this.fireEvent("clearFilters");
+			this.state.groupLevels = [];
 			this.isResettingToDefaultTokens = isResettingToDefaultTokens;
 		} else {
 			this.shouldTokenChangeEventFired = false;
 		}
+		this.state.sorters = [];
 		this.state.tokens = this.getDefaultTokens();
 		this.updateFilterInput("tokenReset");
 		this.state.tokenizerEditable = true;
@@ -905,6 +1118,12 @@ export default class EasyFilterBarContainer extends Control {
 		this.clearMessageStrip(); //clear the message strip for validated filters
 	}
 
+	clearFiltersAndTokens(): void {
+		this.fireEvent("clearFilters");
+		this.shouldTokenChangeEventFired = false;
+		this.state.tokens = [];
+	}
+
 	//The below code updates the existing state by fetching the key and selectedValues
 	updateTokenArray(
 		changeType: TokenSetters,
@@ -932,6 +1151,7 @@ export default class EasyFilterBarContainer extends Control {
 			this.state.tokens = newTokens as TokenDefinition[];
 			this.state.showResult = newTokens.length > 0;
 			this.updateFilterInput("tokenUpdated");
+			this.fireEvent("tokensChangedByUser", { tokens: [...this.state.tokens] });
 		}
 	}
 
@@ -958,6 +1178,14 @@ export default class EasyFilterBarContainer extends Control {
 		return this.mandatoryKeyMap[key] ? true : false;
 	}
 
+	/**
+	 * Checks whether the current state has sort definitions from the easy filter.
+	 * @returns True if the current state contains one or more sorters.
+	 */
+	private hasSorters(): boolean {
+		return this.state.sorters.length > 0;
+	}
+
 	removeNonMandatoryTokens(): this {
 		const newToken: TokenDefinition[] = this.state.tokens.filter((token) => {
 			return this.isKeyMandatory(token.key);
@@ -966,6 +1194,33 @@ export default class EasyFilterBarContainer extends Control {
 		return this;
 	}
 
+	hasGroupLevels(): boolean {
+		return this.state.groupLevels.length > 0;
+	}
+
+	/**
+	 * Notifies the container that an external table state change (sort or group) has been detected.
+	 * If the container currently has active sorters or group levels, the filter input is marked dirty
+	 * because the external change makes the easy filter result inconsistent.
+	 */
+	notifyExternalTableStateChange(): void {
+		if (this.hasSorters() || this.hasGroupLevels()) {
+			this.updateFilterInput("tokenUpdated");
+		}
+	}
+
+	getQuery(): string {
+		return this.easyFilterInput.current?.getValue() ?? "";
+	}
+
+	getTokens(): TokenDefinition[] {
+		return [...this.state.tokens];
+	}
+
+	setQuery(query: string): void {
+		this.easyFilterInput.current?.setValue(query);
+	}
+
 	updateFilterInput(value: string): void {
 		const currValue: string = this.easyFilterInput.current?.getValue() || "";
 		if (value === "tokenUpdated" && currValue !== "") {