@ui5/webcomponents 1.0.0-rc.7 → 1.0.1

package/dist/Carousel.js

@@ -6,26 +6,28 @@ import {
 	isRight,
 	isDown,
 	isUp,
+	isF7,
 } from "@ui5/webcomponents-base/dist/Keys.js";
-import {
-	fetchI18nBundle,
-	getI18nBundle,
-} from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import ScrollEnablement from "@ui5/webcomponents-base/dist/delegate/ScrollEnablement.js";
 import ResizeHandler from "@ui5/webcomponents-base/dist/delegate/ResizeHandler.js";
+import { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
 import { isDesktop } from "@ui5/webcomponents-base/dist/Device.js";
 import AnimationMode from "@ui5/webcomponents-base/dist/types/AnimationMode.js";
 import { getAnimationMode } from "@ui5/webcomponents-base/dist/config/AnimationMode.js";
 import {
 	CAROUSEL_OF_TEXT,
 	CAROUSEL_DOT_TEXT,
+	CAROUSEL_PREVIOUS_ARROW_TEXT,
+	CAROUSEL_NEXT_ARROW_TEXT,
 } from "./generated/i18n/i18n-defaults.js";
 import CarouselArrowsPlacement from "./types/CarouselArrowsPlacement.js";
 import CarouselTemplate from "./generated/templates/CarouselTemplate.lit.js";
-import "@ui5/webcomponents-icons/dist/icons/slim-arrow-left.js";
-import "@ui5/webcomponents-icons/dist/icons/slim-arrow-right.js";
+import "@ui5/webcomponents-icons/dist/slim-arrow-left.js";
+import "@ui5/webcomponents-icons/dist/slim-arrow-right.js";
 
 import Button from "./Button.js";
+import Label from "./Label.js";
 
 // Styles
 import CarouselCss from "./generated/themes/Carousel.css.js";
@@ -35,6 +37,7 @@ import CarouselCss from "./generated/themes/Carousel.css.js";
  */
 const metadata = {
 	tag: "ui5-carousel",
+	languageAware: true,
 	properties: /** @lends sap.ui.webcomponents.main.Carousel.prototype */ {
 		/**
 		 * Defines whether the carousel should loop, i.e show the first page after the last page is reached and vice versa.
@@ -47,7 +50,7 @@ const metadata = {
 		},
 
 		/**
-		 * Sets the number of items per page on small size (up to 640px). One item per page shown by default.
+		 * Defines the number of items per page on small size (up to 640px). One item per page shown by default.
 		 * @type {Integer}
 		 * @defaultvalue 1
 		 * @public
@@ -58,7 +61,7 @@ const metadata = {
 		},
 
 		/**
-		 * Sets the number of items per page on medium size (from 640px to 1024px). One item per page shown by default.
+		 * Defines the number of items per page on medium size (from 640px to 1024px). One item per page shown by default.
 		 * @type {Integer}
 		 * @defaultvalue 1
 		 * @public
@@ -69,7 +72,7 @@ const metadata = {
 		},
 
 		/**
-		 * Sets the number of items per page on large size (more than 1024px). One item per page shown by default.
+		 * Defines the number of items per page on large size (more than 1024px). One item per page shown by default.
 		 * @type {Integer}
 		 * @defaultvalue 1
 		 * @public
@@ -80,12 +83,29 @@ const metadata = {
 		},
 
 		/**
-		 * If set to true the navigation is hidden.
+		 * Defines the visibility of the navigation arrows.
+		 * If set to true the navigation arrows will be hidden.
+		 * <br><br>
+		 * <b>Note:</b> The navigation arrows are never displayed on touch devices.
+		 * In this case, the user can swipe to navigate through the items.
+		 * @type {boolean}
+		 * @since 1.0.0-rc.15
+		 * @defaultvalue false
+		 * @public
+		 */
+		hideNavigationArrows: {
+			type: Boolean,
+		},
+
+		/**
+		 * Defines the visibility of the paging indicator.
+		 * If set to true the page indicator will be hidden.
 		 * @type {boolean}
+		 * @since 1.0.0-rc.15
 		 * @defaultvalue false
 		 * @public
 		 */
-		hideNavigation: {
+		hidePageIndicator: {
 			type: Boolean,
 		},
 
@@ -93,9 +113,9 @@ const metadata = {
 		 * Defines the index of the initially selected item.
 		 * @type {Integer}
 		 * @defaultvalue 0
-		 * @public
+		 * @private
 		 */
-		selectedIndex: {
+		_selectedIndex: {
 			type: Integer,
 			defaultValue: 0,
 		},
@@ -122,7 +142,7 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the carousel width in pixels
+		 * Defines the carousel width in pixels.
 		 * @private
 		 */
 		_width: {
@@ -130,19 +150,29 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the carousel item width in pixels
+		 * Defines the carousel item width in pixels.
 		 * @private
 		 */
 		_itemWidth: {
 			type: Integer,
 		},
+
+		/**
+		 * If set to true navigation arrows are shown.
+		 * @private
+		 * @since 1.0.0-rc.15
+		 */
+		_visibleNavigationArrows: {
+			type: Boolean,
+			noAttribute: true,
+		},
 	},
 	managedSlots: true,
 	slots: /** @lends sap.ui.webcomponents.main.Carousel.prototype */ {
 		/**
-		 * Defines the content of the <code>ui5-carousel</code>.
+		 * Defines the content of the component.
 		 * @type {HTMLElement[]}
-		 * @slot
+		 * @slot content
 		 * @public
 		 */
 		"default": {
@@ -154,12 +184,12 @@ const metadata = {
 	events: /** @lends sap.ui.webcomponents.main.Carousel.prototype */ {
 
 		/**
-		 * Fired whenever the <code>selectedIndex</code> changes due to user interaction,
+		 * Fired whenever the page 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>.
+		 * @param {Integer} selectedIndex the current selected index
 		 * @public
 		 * @since 1.0.0-rc.7
 		 */
@@ -175,24 +205,44 @@ const metadata = {
  * @class
  *
  * <h3 class="comment-api-title">Overview</h3>
- * The carousel allows the user to browse through a set of items by swiping right or left.
+ * The Carousel allows the user to browse through a set of items.
  * The component is mostly used for showing a gallery of images, but can hold any other HTML element.
+ * <br>
+ * There are several ways to perform navigation:
+ * <ul>
+ * <li>on desktop - the user can navigate using the navigation arrows or with keyboard shorcuts.</li>
+ * <li>on mobile - the user can use swipe gestures.</li>
+ * </ul>
  *
  * <h3>Usage</h3>
  *
- * When to use
+ * <h4>When to use:</h4>
  *
- * - The items you want to display are very different from each other.
- * - You want to display the items one after the other.
- * When not to use
+ * <ul>
+ * <li>The items you want to display are very different from each other.</li>
+ * <li>You want to display the items one after the other.</li>
+ * </ul>
  *
- * - The items you want to display need to be visible at the same time.
- * - The items you want to display are uniform and very similar
+ * <h4>When not to use:</h4>
+ *
+ * <ul>
+ * <li>The items you want to display need to be visible at the same time.</li>
+ * <li>The items you want to display are uniform and very similar.</li>
+ * </ul>
+ *
+ * <h3>Keyboard Handling</h3>
+ * When the <code>ui5-carousel</code> is focused the user can navigate between the items
+ * with the following keyboard shortcuts:
+ * <br>
+ *
+ * <ul>
+ * <li>[UP/DOWN] - Navigates to previous and next item</li>
+ * <li>[LEFT/RIGHT] - Navigates to previous and next item</li>
+ * </ul>
  *
- * For the <code>ui5-carousel</code>
  * <h3>ES6 Module Import</h3>
  *
- * <code>import @ui5/webcomponents/dist/Carousel.js";</code>
+ * <code>import "@ui5/webcomponents/dist/Carousel.js";</code>
  *
  * @constructor
  * @author SAP SE
@@ -230,13 +280,18 @@ class Carousel extends UI5Element {
 		this._scrollEnablement.attachEvent("touchend", event => {
 			this._updateScrolling(event);
 		});
-
-		this.i18nBundle = getI18nBundle("@ui5/webcomponents");
 		this._onResizeBound = this._onResize.bind(this);
 		this._resizing = false; // indicates if the carousel is in process of resizing
+
+		this._lastFocusedElements = [];
+		this._orderOfLastFocusedPages = [];
 	}
 
 	onBeforeRendering() {
+		if (this.arrowsPlacement === CarouselArrowsPlacement.Navigation) {
+			this._visibleNavigationArrows = true;
+		}
+
 		this.validateSelectedIndex();
 	}
 
@@ -254,9 +309,8 @@ class Carousel extends UI5Element {
 	}
 
 	validateSelectedIndex() {
-		if (!this.isIndexInRange(this.selectedIndex)) {
-			this.selectedIndex = 0;
-			console.warn(`The "selectedIndex" is out of range, changed to: ${0}`); // eslint-disable-line
+		if (!this.isIndexInRange(this._selectedIndex)) {
+			this._selectedIndex = 0;
 		}
 	}
 
@@ -276,9 +330,9 @@ class Carousel extends UI5Element {
 			return;
 		}
 
-		if (this.selectedIndex > this.pagesCount - 1) {
-			this.selectedIndex = this.pagesCount - 1;
-			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
+		if (this._selectedIndex > this.pagesCount - 1) {
+			this._selectedIndex = this.pagesCount - 1;
+			this.fireEvent("navigate", { selectedIndex: this._selectedIndex });
 		}
 	}
 
@@ -294,68 +348,156 @@ class Carousel extends UI5Element {
 		}
 	}
 
-	_onkeydown(event) {
+	async _onkeydown(event) {
+		if (isF7(event)) {
+			this._handleF7Key(event);
+			return;
+		}
+
 		if (event.target !== this.getDomRef()) {
 			return;
 		}
 
 		if (isLeft(event) || isDown(event)) {
 			this.navigateLeft();
+			await renderFinished();
+			this.getDomRef().focus();
 		} else if (isRight(event) || isUp(event)) {
 			this.navigateRight();
+			await renderFinished();
+			this.getDomRef().focus();
+		}
+	}
+
+	_onfocusin(event) {
+		if (event.target === this.getDomRef()) {
+			return;
+		}
+
+		let pageIndex = -1;
+
+		for (let i = 0; i < this.content.length; i++) {
+			if (this.content[i].contains(event.target)) {
+				pageIndex = i;
+				break;
+			}
+		}
+
+		if (pageIndex === -1) {
+			return;
+		}
+
+		// Save reference of the last focused element for each page
+		this._lastFocusedElements[pageIndex] = event.target;
+
+		const sortedPageIndex = this._orderOfLastFocusedPages.indexOf(pageIndex);
+		if (sortedPageIndex === -1) {
+			this._orderOfLastFocusedPages.unshift(pageIndex);
+		} else {
+			this._orderOfLastFocusedPages.splice(0, 0, this._orderOfLastFocusedPages.splice(sortedPageIndex, 1)[0]);
+		}
+	}
+
+	_onmouseout() {
+		if (this.arrowsPlacement === CarouselArrowsPlacement.Content) {
+			this._visibleNavigationArrows = false;
+		}
+	}
+
+	_onmouseover() {
+		if (this.arrowsPlacement === CarouselArrowsPlacement.Content) {
+			this._visibleNavigationArrows = true;
+		}
+	}
+
+	_handleF7Key(event) {
+		const lastFocusedElement = this._lastFocusedElements[this._getLastFocusedActivePageIndex];
+
+		if (event.target === this.getDomRef() && lastFocusedElement) {
+			lastFocusedElement.focus();
+		} else {
+			this.getDomRef().focus();
+		}
+	}
+
+	get _getLastFocusedActivePageIndex() {
+		for (let i = 0; i < this._orderOfLastFocusedPages.length; i++) {
+			const pageIndex = this._orderOfLastFocusedPages[i];
+
+			if (this.isItemInViewport(pageIndex)) {
+				return pageIndex;
+			}
 		}
+
+		return this._selectedIndex;
 	}
 
 	navigateLeft() {
 		this._resizing = false;
 
-		const peviousSelectedIndex = this.selectedIndex;
+		const previousSelectedIndex = this._selectedIndex;
 
-		if (this.selectedIndex - 1 < 0) {
+		if (this._selectedIndex - 1 < 0) {
 			if (this.cyclic) {
-				this.selectedIndex = this.pagesCount - 1;
+				this._selectedIndex = this.pagesCount - 1;
 			}
 		} else {
-			--this.selectedIndex;
+			--this._selectedIndex;
 		}
 
-		if (peviousSelectedIndex !== this.selectedIndex) {
-			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
+		if (previousSelectedIndex !== this._selectedIndex) {
+			this.fireEvent("navigate", { selectedIndex: this._selectedIndex });
 		}
 	}
 
 	navigateRight() {
 		this._resizing = false;
 
-		const peviousSelectedIndex = this.selectedIndex;
+		const previousSelectedIndex = this._selectedIndex;
 
-		if (this.selectedIndex + 1 > this.pagesCount - 1) {
+		if (this._selectedIndex + 1 > this.pagesCount - 1) {
 			if (this.cyclic) {
-				this.selectedIndex = 0;
+				this._selectedIndex = 0;
+			} else {
+				return;
 			}
 		} else {
-			++this.selectedIndex;
+			++this._selectedIndex;
 		}
 
-		if (peviousSelectedIndex !== this.selectedIndex) {
-			this.fireEvent("navigate", { selectedIndex: this.selectedIndex });
+		if (previousSelectedIndex !== this._selectedIndex) {
+			this.fireEvent("navigate", { selectedIndex: this._selectedIndex });
 		}
 	}
 
+	/**
+	 * Changes the currently displayed page.
+	 * @param {Integer} itemIndex The index of the target page
+	 * @since 1.0.0-rc.15
+	 * @public
+	 */
+	navigateTo(itemIndex) {
+		this._resizing = false;
+		this._selectedIndex = itemIndex;
+	}
+
 	/**
 	 * Assuming that all items have the same width
 	 * @private
 	 */
 	get items() {
 		return this.content.map((item, idx) => {
+			const visible = this.isItemInViewport(idx);
 			return {
 				id: `${this._id}-carousel-item-${idx + 1}`,
 				item,
-				tabIndex: idx === this.selectedIndex ? "0" : "-1",
+				tabIndex: visible ? "0" : "-1",
 				posinset: idx + 1,
 				setsize: this.content.length,
-				width: this._itemWidth,
-				classes: this.isItemInViewport(idx) ? "" : "ui5-carousel-item--hidden",
+				styles: {
+					width: `${this._itemWidth}px`,
+				},
+				classes: visible ? "" : "ui5-carousel-item--hidden",
 			};
 		});
 	}
@@ -373,17 +515,40 @@ class Carousel extends UI5Element {
 	}
 
 	isItemInViewport(index) {
-		return index >= this.selectedIndex && index <= this.selectedIndex + this.effectiveItemsPerPage - 1;
+		return index >= this._selectedIndex && index <= this._selectedIndex + this.effectiveItemsPerPage - 1;
 	}
 
 	isIndexInRange(index) {
 		return index >= 0 && index <= this.pagesCount - 1;
 	}
 
+	/**
+	 * @private
+	 */
+	get renderNavigation() {
+		if (!this.hasManyPages) {
+			return false;
+		}
+
+		if (this.arrowsPlacement === CarouselArrowsPlacement.Navigation && !this.hideNavigationArrows) {
+			return true;
+		}
+
+		if (this.hidePageIndicator) {
+			return false;
+		}
+
+		return true;
+	}
+
+	get hasManyPages() {
+		return this.pagesCount > 1;
+	}
+
 	get styles() {
 		return {
 			content: {
-				transform: `translateX(-${this.selectedIndex * this._itemWidth}px`,
+				transform: `translateX(${this._isRTL ? "" : "-"}${this._selectedIndex * this._itemWidth}px`,
 			},
 		};
 	}
@@ -391,17 +556,18 @@ class Carousel extends UI5Element {
 	get classes() {
 		return {
 			viewport: {
+				"ui5-carousel-viewport": true,
 				"ui5-carousel-viewport--single": this.pagesCount === 1,
 			},
 			content: {
 				"ui5-carousel-content": true,
-				"ui5-carousel-content-no-animation": this.supressAimation,
-				"ui5-carousel-content-has-navigation": this.showNavigationArrows,
-				"ui5-carousel-content-has-navigation-and-buttons": this.showNavigationArrows && this.arrowsPlacement === CarouselArrowsPlacement.Navigation,
+				"ui5-carousel-content-no-animation": this.suppressAnimation,
+				"ui5-carousel-content-has-navigation": this.renderNavigation,
+				"ui5-carousel-content-has-navigation-and-buttons": this.renderNavigation && this.arrowsPlacement === CarouselArrowsPlacement.Navigation && !this.hideNavigationArrows,
 			},
 			navigation: {
 				"ui5-carousel-navigation-wrapper": true,
-				"ui5-carousel-navigation-with-buttons": this.showNavigationArrows && this.arrowsPlacement === CarouselArrowsPlacement.Navigation,
+				"ui5-carousel-navigation-with-buttons": this.renderNavigation && this.arrowsPlacement === CarouselArrowsPlacement.Navigation && !this.hideNavigationArrows,
 			},
 			navPrevButton: {
 				"ui5-carousel-navigation-button--hidden": !this.hasPrev,
@@ -427,8 +593,8 @@ class Carousel extends UI5Element {
 
 		for (let index = 0; index < pages; index++) {
 			dots.push({
-				active: index === this.selectedIndex,
-				ariaLabel: this.i18nBundle.getText(CAROUSEL_DOT_TEXT, [index + 1], [pages]),
+				active: index === this._selectedIndex,
+				ariaLabel: Carousel.i18nBundle.getText(CAROUSEL_DOT_TEXT, index + 1, pages),
 			});
 		}
 
@@ -436,47 +602,77 @@ class Carousel extends UI5Element {
 	}
 
 	get arrows() {
-		const showArrows = this.showNavigationArrows && isDesktop();
+		const showArrows = this._visibleNavigationArrows && this.hasManyPages && isDesktop();
 
 		return {
-			content: showArrows && this.arrowsPlacement === CarouselArrowsPlacement.Content,
-			navigation: showArrows && this.arrowsPlacement === CarouselArrowsPlacement.Navigation,
+			content: !this.hideNavigationArrows && showArrows && this.arrowsPlacement === CarouselArrowsPlacement.Content,
+			navigation: !this.hideNavigationArrows && showArrows && this.arrowsPlacement === CarouselArrowsPlacement.Navigation,
 		};
 	}
 
 	get hasPrev() {
-		return this.cyclic || this.selectedIndex - 1 >= 0;
+		return this.cyclic || this._selectedIndex - 1 >= 0;
 	}
 
 	get hasNext() {
-		return this.cyclic || this.selectedIndex + 1 <= this.pagesCount - 1;
+		return this.cyclic || this._selectedIndex + 1 <= this.pagesCount - 1;
 	}
 
-	get supressAimation() {
+	get suppressAnimation() {
 		return this._resizing || getAnimationMode() === AnimationMode.None;
 	}
 
-	get selectedIndexToShow() {
-		return this.selectedIndex + 1;
+	get _isRTL() {
+		return this.effectiveDir === "rtl";
 	}
 
-	get showNavigationArrows() {
-		return !this.hideNavigation && this.pagesCount > 1;
+	get selectedIndexToShow() {
+		return this._isRTL ? this.pagesCount - (this.pagesCount - this._selectedIndex) + 1 : this._selectedIndex + 1;
 	}
 
 	get ofText() {
-		return this.i18nBundle.getText(CAROUSEL_OF_TEXT);
+		return Carousel.i18nBundle.getText(CAROUSEL_OF_TEXT);
 	}
 
 	get ariaActiveDescendant() {
-		return this.content.length ? `${this._id}-carousel-item-${this.selectedIndex + 1}` : undefined;
+		return this.content.length ? `${this._id}-carousel-item-${this._selectedIndex + 1}` : undefined;
+	}
+
+	get nextPageText() {
+		return Carousel.i18nBundle.getText(CAROUSEL_NEXT_ARROW_TEXT);
+	}
+
+	get previousPageText() {
+		return Carousel.i18nBundle.getText(CAROUSEL_PREVIOUS_ARROW_TEXT);
+	}
+
+	/**
+	 * The indices of the currently visible items of the component.
+	 * @readonly
+	 * @since 1.0.0-rc.15
+	 * @returns {Integer[]} the indices of the visible items
+	 */
+	get visibleItemsIndices() {
+		const visibleItemsIndices = [];
+
+		this.items.forEach((item, index) => {
+			if (this.isItemInViewport(index)) {
+				visibleItemsIndices.push(index);
+			}
+		});
+
+		return visibleItemsIndices;
+	}
+
+	static get dependencies() {
+		return [
+			Button,
+			Label,
+		];
 	}
 
 	static async onDefine() {
-		await Promise.all([
-			fetchI18nBundle("@ui5/webcomponents"),
-			Button.define(),
-		]);
+		Carousel.i18nBundle = await getI18nBundle("@ui5/webcomponents");
 	}
 }