feat(ui5-view-settings-dialog): add group option (#11950)

This feature introduces a new `Group` option to the `ui5-view-settings-dialog` allowing users to select a group of options and in what way they should be ordered, similar to the `Sort` option.

To use the Group option, we introduced a `ui5-group-item` that can be slotted in the `groupItems` slot of a `ui5-view-settings-dialog`.

Fixes: #11815

Author: didip1000

packages/fiori/cypress/specs/ViewSettingsDialog.cy.tsx

@@ -1,10 +1,11 @@
 import ViewSettingsDialog from "../../src/ViewSettingsDialog.js";
+import GroupItem from "../../src/GroupItem.js";
 import SortItem from "../../src/SortItem.js";
 import FilterItem from "../../src/FilterItem.js";
 import FilterItemOption from "../../src/FilterItemOption.js";
 
-describe("View settings dialog - selection", () => {
-	it("tests clicking on sort items (both on the text and radio button)", () => {
+describe("View settings dialog - confirm event", () => {
+	it("should throw confirm event after selecting sort options and confirm button", () => {
 		cy.mount(
 			<ViewSettingsDialog id="vsd" onConfirm={cy.stub().as("confirm")}>
 				<SortItem slot="sortItems" text="Name" selected={true}></SortItem>
@@ -86,7 +87,7 @@ describe("View settings dialog - selection", () => {
 			.should("equal", "Name");
 	});
 
-	it("tests clicking on filter items, and filter item options (both on the text and checkbox)", () => {
+	it("should throw confirm event after selecting filter options and confirm button", () => {
 		cy.mount(
 			<ViewSettingsDialog id="vsd" onConfirm={cy.stub().as("confirm")}>
 				<FilterItem slot="filterItems" text="Filter 1">
@@ -167,6 +168,61 @@ describe("View settings dialog - selection", () => {
 			.find("[ui5-dialog]")
 			.should("not.be.visible");
 	});
+
+	it("should throw confirm event after selecting group options and confirm button", () => {
+		cy.mount(
+			<ViewSettingsDialog onConfirm={cy.stub().as("confirm")}>
+				<GroupItem slot="groupItems" text="Name"></GroupItem>
+				<GroupItem slot="groupItems" text="Position"></GroupItem>
+				<GroupItem slot="groupItems" text="(No Group)"></GroupItem>
+			</ViewSettingsDialog>
+		);
+
+		cy.get("[ui5-view-settings-dialog]")
+			.as("vsd")
+			.invoke("prop", "open", true);
+
+		cy.get("@vsd")
+			.shadow()
+			.find("[group-order] ui5-li")
+			.as("groupOrderItems");
+
+		cy.get("@groupOrderItems")
+			.should("have.length", 2);
+
+		// Select the group order (Descending)
+		cy.get("@groupOrderItems")
+			.eq(1)
+			.realClick();
+
+		cy.get("@vsd")
+			.shadow()
+			.find("[group-by] ui5-li")
+			.as("groupByItems");
+
+		cy.get("@groupByItems")
+			.should("have.length", 3);
+
+		// Select the group by (No Group)
+		cy.get("@groupByItems")
+			.eq(2)
+			.realClick();
+
+		// Confirm the selection
+		cy.get("@vsd")
+			.shadow()
+			.find(".ui5-vsd-footer ui5-button")
+			.realClick();
+
+		 // Check the confirm event for groupOrder and groupBy
+		 cy.get("@confirm")
+			.should("be.calledWithMatch", {
+				detail: {
+					groupOrder: "Descending",
+					groupBy: "(No Group)",
+				},
+			});
+	});
 });
 
 describe("ViewSettingsDialog Tests", () => {
@@ -371,6 +427,31 @@ describe("ViewSettingsDialog Tests", () => {
 			.invoke("prop", "open", false);
 	});
 
+	it("should handle group-only mode", () => {
+		cy.mount(
+			<ViewSettingsDialog id="vsdGroup">
+				<GroupItem slot="groupItems" text="Name"></GroupItem>
+				<GroupItem slot="groupItems" text="Position"></GroupItem>
+				<GroupItem slot="groupItems" text="Company"></GroupItem>
+				<GroupItem slot="groupItems" text="Department"></GroupItem>
+			</ViewSettingsDialog>
+		);
+
+		cy.get("#vsdGroup")
+			.as("vsd");
+
+		cy.get("@vsd")
+			.invoke("prop", "open", true);
+
+		cy.get("@vsd")
+			.shadow()
+			.find("[ui5-segmented-button]")
+			.should("not.exist");
+
+		cy.get("@vsd")
+			.invoke("prop", "open", false);
+	});
+
 	it("should focus first item in filter options", () => {
 		cy.mount(
 			<ViewSettingsDialog id="vsdFilter">
@@ -407,4 +488,37 @@ describe("ViewSettingsDialog Tests", () => {
 			.first()
 			.should("be.focused");
 	});
+
+	it("should show a split button with all loaded VSD options", () => {
+		cy.mount(
+			<ViewSettingsDialog id="vsd">
+				<SortItem slot="sortItems" text="Name"></SortItem>
+				<FilterItem slot="filterItems" text="Filter 1">
+					<FilterItemOption slot="values" text="Some filter 1"></FilterItemOption>
+					<FilterItemOption slot="values" text="Some filter 2"></FilterItemOption>
+					<FilterItemOption slot="values" text="Some filter 3"></FilterItemOption>
+				</FilterItem>
+				<GroupItem slot="groupItems" text="Name"></GroupItem>
+			</ViewSettingsDialog>
+		);
+
+		cy.get("[ui5-view-settings-dialog]")
+			.as("vsd")
+			.invoke("prop", "open", true);
+
+		cy.get("@vsd")
+			.shadow()
+			.find("[ui5-segmented-button]")
+			.as("segmentedButton");
+
+		cy.get("@segmentedButton")
+			.should("be.visible");
+
+		cy.get("@segmentedButton")
+			.find("[ui5-segmented-button-item]")
+			.as("items");
+
+		cy.get("@items")
+			.should("have.length", 3);
+	});
 });

packages/fiori/src/FilterItem.ts

@@ -9,12 +9,16 @@ import type FilterItemOption from "./FilterItemOption.js";
  *
  * ### Overview
  *
+ * The `ui5-filter-item` component defines the filtering criteria for data in `ui5-view-settings-dialog`.
+ * It represents a single filter category that contains multiple filter options that users can select.
+ *
  * ### Usage
  *
- * For the `ui5-filter-item`
+ * The `ui5-filter-item` is used within the `ui5-view-settings-dialog` to provide filtering options.
+ *
  * ### ES6 Module Import
  *
- * `import @ui5/webcomponents-fiori/dist/FilterItem.js";`
+ * `import "@ui5/webcomponents-fiori/dist/FilterItem.js";`
  * @constructor
  * @extends UI5Element
  * @abstract
@@ -24,23 +28,24 @@ import type FilterItemOption from "./FilterItemOption.js";
 @customElement("ui5-filter-item")
 class FilterItem extends UI5Element {
 	/**
-	 * Defines the text of the component.
+	 * Defines the text of the filter item.
 	 * @default undefined
 	 * @public
 	 */
 	@property()
 	text?: string;
 
 	/**
-	 * Defines the additional text of the component.
+	 * Defines the additional text of the filter item.
+	 * This text is typically used to show the number of selected filter options within this category.
 	 * @default undefined
 	 * @public
 	 */
 	@property()
 	additionalText?: string;
 
 	/**
-	 * Defines the `values` list.
+	 * Defines the filter options available for this filter category.
 	 * @public
 	 */
 	@slot()

packages/fiori/src/FilterItemOption.ts

@@ -7,12 +7,17 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
  *
  * ### Overview
  *
+ * The `ui5-filter-item-option` component defines individual filter values within a `ui5-filter-item`.
+ * It represents a single selectable option that users can choose to filter data.
+ *
  * ### Usage
  *
- * For the `ui5-filter-item-option`
+ * The `ui5-filter-item-option` is used as a child component within `ui5-filter-item` in the context
+ * of `ui5-view-settings-dialog`. Each option represents a specific value that can be used for filtering
+ *
  * ### ES6 Module Import
  *
- * `import @ui5/webcomponents-fiori/dist/FilterItemOption.js";`
+ * `import "@ui5/webcomponents-fiori/dist/FilterItemOption.js";`
  * @constructor
  * @extends UI5Element
  * @abstract
@@ -22,15 +27,15 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
 @customElement("ui5-filter-item-option")
 class FilterItemOption extends UI5Element {
 	/**
-	 * Defines the text of the component.
+	 * Defines the text of the filter option.
 	 * @default undefined
 	 * @public
 	 */
 	@property()
 	text?: string;
 
 	/**
-	 * Defines if the component is selected.
+	 * Defines if the filter option is selected.
 	 * @default false
 	 * @public
 	 */

packages/fiori/src/GroupItem.ts

@@ -0,0 +1,48 @@
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import property from "@ui5/webcomponents-base/dist/decorators/property.js";
+import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
+
+/**
+ * @class
+ *
+ * ### Overview
+ *
+ * The `ui5-group-item` component defines the grouping criteria for data in `ui5-view-settings-dialog`.
+ * It represents a single group option that users can select to organize data into logical groups.
+ *
+ * ### Usage
+ *
+ * The `ui5-group-item` is used within the `ui5-view-settings-dialog` to provide grouping options.
+ * Each group item represents a column or field by which data can be grouped.
+ *
+ * ### ES6 Module Import
+ *
+ * `import "@ui5/webcomponents-fiori/dist/GroupItem.js";`
+ * @constructor
+ * @extends UI5Element
+ * @abstract
+ * @since 2.13.0
+ * @public
+ */
+@customElement("ui5-group-item")
+class GroupItem extends UI5Element {
+	/**
+	 * Defines the text of the group item.
+	 * @default undefined
+	 * @public
+	 */
+	@property()
+	text?: string;
+
+	/**
+	 * Defines if the group item is selected.
+	 * @default false
+	 * @public
+	 */
+	@property({ type: Boolean })
+	selected = false;
+}
+
+GroupItem.define();
+
+export default GroupItem;

packages/fiori/src/SortItem.ts

@@ -7,12 +7,17 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
  *
  * ### Overview
  *
+ * The `ui5-sort-item` component defines the sorting criteria for data in `ui5-view-settings-dialog`.
+ * It represents a single sort option that users can select to organize data in ascending or descending order.
+ *
  * ### Usage
  *
- * For the `ui5-sort-item`
+ * The `ui5-sort-item` is used within the `ui5-view-settings-dialog` to provide sorting options.
+ * Each sort item represents a column or field by which data can be sorted.
+ *
  * ### ES6 Module Import
  *
- * `import @ui5/webcomponents-fiori/dist/SortItem.js";`
+ * `import "@ui5/webcomponents-fiori/dist/SortItem.js";`
  * @constructor
  * @extends UI5Element
  * @abstract
@@ -22,15 +27,15 @@ import customElement from "@ui5/webcomponents-base/dist/decorators/customElement
 @customElement("ui5-sort-item")
 class SortItem extends UI5Element {
 	/**
-	 * Defines the text of the component.
+	 * Defines the text of the sort item.
 	 * @default undefined
 	 * @public
 	 */
 	@property()
 	text?: string;
 
 	/**
-	 * Defines if the component is selected.
+	 * Defines if the sort item is selected.
 	 * @default false
 	 * @public
 	 */