feat(ui5-carousel): add navigate event (#1454)

The event is fired whenever the selectedIndex changes due to user interaction - when the user clicks on the navigation arrows or while resizing, based on the "items-per-page-s/m/l" properties.

Fixes: #1449

packages/main/src/Carousel.hbs

@@ -24,13 +24,15 @@
         {{#if arrows.content}}
             <div class="ui5-carousel-navigation-arrows">
                 <ui5-button
+                    arrow-back
                     class="ui5-carousel-navigation-button {{classes.navPrevButton}}"
                     icon="slim-arrow-left"
                     tabindex="-1"
                     @click={{navigateLeft}}
                     @keydown={{_onbuttonkeydown}}
                 ></ui5-button>
                 <ui5-button
+                    arrow-forward
                     class="ui5-carousel-navigation-button {{classes.navNextButton}}"
                     icon="slim-arrow-right"
                     tabindex="-1"
@@ -44,6 +46,7 @@
             <div class="{{classes.navigation}}">
                 {{#if arrows.navigation}}
                 <ui5-button
+                    arrow-back
                     class="ui5-carousel-navigation-button {{classes.navPrevButton}}"
                     icon="slim-arrow-left"
                     tabindex="-1"
@@ -69,6 +72,7 @@
 
                 {{#if arrows.navigation}}
                     <ui5-button
+                        arrow-forward
                         class="ui5-carousel-navigation-button {{classes.navNextButton}}"
                         icon="slim-arrow-right"
                         tabindex="-1"

packages/main/src/Carousel.js

@@ -90,7 +90,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the index of the initially selected page.
+		 * Defines the index of the initially selected item.
 		 * @type {Integer}
 		 * @defaultvalue 0
 		 * @public
@@ -152,7 +152,22 @@ const metadata = {
 		},
 	},
 	events: /** @lends sap.ui.webcomponents.main.Carousel.prototype */ {
-		//
+
+		/**
+		 * Fired whenever the <code>selectedIndex</code> changes due to user interaction,
+		 * when the user clicks on the navigation arrows or while resizing,
+		 * based on the <code>items-per-page-l</code>, <code>items-per-page-m</code> and <code>items-per-page-s</code> properties.
+		 *
+		 * @event
+		 * @param {Integer} selectedIndex the current <code>selectedIndex</code>.
+		 * @public
+		 * @since 1.0.0-rc.7
+		 */
+		navigate: {
+			detail: {
+				selectedIndex: { type: Integer },
+			},
+		},
 	},
 };
 
@@ -263,6 +278,7 @@ class Carousel extends UI5Element {
 
 		if (this.selectedIndex > this.pagesCount - 1) {
 			this.selectedIndex = this.pagesCount - 1;
+			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
 		}
 	}
 
@@ -291,23 +307,39 @@ class Carousel extends UI5Element {
 	}
 
 	navigateLeft() {
+		this._resizing = false;
+
+		const peviousSelectedIndex = this.selectedIndex;
+
 		if (this.selectedIndex - 1 < 0) {
 			if (this.cyclic) {
 				this.selectedIndex = this.pagesCount - 1;
 			}
 		} else {
 			--this.selectedIndex;
 		}
+
+		if (peviousSelectedIndex !== this.selectedIndex) {
+			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
+		}
 	}
 
 	navigateRight() {
+		this._resizing = false;
+
+		const peviousSelectedIndex = this.selectedIndex;
+
 		if (this.selectedIndex + 1 > this.pagesCount - 1) {
 			if (this.cyclic) {
 				this.selectedIndex = 0;
 			}
 		} else {
 			++this.selectedIndex;
 		}
+
+		if (peviousSelectedIndex !== this.selectedIndex) {
+			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
+		}
 	}
 
 	/**

packages/main/test/pages/Carousel.html

@@ -484,5 +484,26 @@
 	<ui5-button>Button 9</ui5-button>
 </ui5-carousel>
 
+<ui5-carousel id="carousel8" items-per-page-m="4" items-per-page-l="4">
+	<ui5-button>Button 1</ui5-button>
+	<ui5-button>Button 2</ui5-button>
+	<ui5-button>Button 3</ui5-button>
+	<ui5-button>Button 4</ui5-button>
+	<ui5-button>Button 5</ui5-button>
+	<ui5-button>Button 6</ui5-button>
+	<ui5-button>Button 7</ui5-button>
+	<ui5-button>Button 8</ui5-button>
+</ui5-carousel>
+<ui5-input id="result"></ui5-input>
+<ui5-input id="resultCounter"></ui5-input>
+
 </body>
+
+<script>
+	var counter = 0;
+	carousel8.addEventListener("ui5-navigate", function(event){
+		result.value = event.detail.selectedIndex;
+		resultCounter.value = ++counter;
+	});
+</script>
 </html>

packages/main/test/specs/Carousel.spec.js

@@ -110,4 +110,43 @@ describe("Carousel general interaction", () => {
 		assert.strictEqual(selectedIndex, NORMALIZED_INDEX,
 			"Although '15' is set, the actual selectedIndex is changed to 0.");
 	});
+
+	it("Event navigate fired when pressing navigation arrows", () => {
+		const carousel = browser.$("#carousel8");
+		const selectedIndex = browser.$("#result");
+		const eventCounter = browser.$("#resultCounter");
+		const navigationArrowForward = carousel.shadow$("ui5-button[arrow-forward]");
+		const navigationArrowsBack = carousel.shadow$("ui5-button[arrow-back]");
+
+		// using the navigtion arrows
+		navigationArrowForward.click(); // forward
+		assert.strictEqual(selectedIndex.getProperty("value"), "1", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "1", "The navigate event is fired.");
+
+		navigationArrowForward.click(); // forward
+		assert.strictEqual(selectedIndex.getProperty("value"), "2", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "2", "The navigate event is fired.");
+
+		navigationArrowsBack.click(); // back
+		assert.strictEqual(selectedIndex.getProperty("value"), "1", "The selectedIndex is correct");
+		assert.strictEqual(eventCounter.getProperty("value"), "3", "The navigate event is fired.");
+
+		navigationArrowsBack.click(); // back
+		assert.strictEqual(selectedIndex.getProperty("value"), "0", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "4", "The navigate event is fired.");
+
+		// using the keyboard navigation
+		carousel.click();
+		carousel.keys("ArrowRight");
+		assert.strictEqual(selectedIndex.getProperty("value"), "1", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "5", "The navigate event is fired.");
+
+		carousel.keys("ArrowLeft");
+		assert.strictEqual(selectedIndex.getProperty("value"), "0", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "6", "The navigate event is fired.");
+
+		carousel.keys("ArrowLeft");
+		assert.strictEqual(selectedIndex.getProperty("value"), "0", "The selectedIndex is correct.");
+		assert.strictEqual(eventCounter.getProperty("value"), "6", "The navigate event is not fired as no previous item.");
+	});
 });