@ui5/webcomponents-base 0.0.0-c6155714e → 0.0.0-c638668a1

package/src/delegate/ItemNavigation.js

@@ -5,174 +5,302 @@ import {
 	isRight,
 	isHome,
 	isEnd,
-} from "../events/PseudoEvents.js";
+	isPageDown,
+	isPageUp,
+} from "../Keys.js";
+import getActiveElement from "../util/getActiveElement.js";
 
-import EventProvider from "../EventProvider.js";
-import UI5Element from "../UI5Element.js";
 import NavigationMode from "../types/NavigationMode.js";
 import ItemNavigationBehavior from "../types/ItemNavigationBehavior.js";
 
-// navigatable items must have id and tabindex
-class ItemNavigation extends EventProvider {
+/**
+ * The ItemNavigation class manages the calculations to determine the correct "tabindex" for a group of related items inside a root component.
+ * Important: ItemNavigation only does the calculations and does not change "tabindex" directly, this is a responsibility of the developer.
+ *
+ * The keys that trigger ItemNavigation are:
+ *  - Up/down
+ *  - Left/right
+ *  - Home/End
+ *
+ * Usage:
+ * 1) Use the "getItemsCallback" constructor property to pass a callback to ItemNavigation, which, whenever called, will return the list of items to navigate among.
+ *
+ * Each item passed to ItemNavigation via "getItemsCallback" must be:
+ *  - A) either a UI5Element with a "_tabIndex" property
+ *  - B) or an Object with "id" and "_tabIndex" properties which represents a part of the root component's shadow DOM.
+ *    The "id" must be a valid ID within the shadow root of the component ItemNavigation operates on.
+ *    This object must not be a DOM object because, as said, ItemNavigation will not set "tabindex" on it. It must be a representation of a DOM object only
+ *    and the developer has the responsibility to update the "tabindex" in the component's DOM.
+ *  - C) a combination of the above
+ *
+ * Whenever the user navigates with the keyboard, ItemNavigation will modify the "_tabIndex" properties of the items.
+ * It is the items' responsibilities to re-render themselves and apply the correct value of "tabindex" (i.e. to map the "_tabIndex" ItemNavigation set to them to the "tabindex" property).
+ * If the items of the ItemNavigation are UI5Elements themselves, this can happen naturally since they will be invalidated by their "_tabIndex" property.
+ * If the items are Objects with "id" and "_tabIndex" however, it is the developer's responsibility to apply these and the easiest way is to have the root component invalidated by ItemNavigation.
+ * To do so, set the "affectedPropertiesNames" constructor property to point to one or more of the root component's properties that need refreshing when "_tabIndex" is changed deeply.
+ *
+ * 2) Call the "setCurrentItem" method of ItemNavigation whenever you want to change the current item.
+ * This is most commonly required if the user for example clicks on an item and thus selects it directly.
+ * Pass as the only argument to "setCurrentItem" the item that becomes current (must be one of the items, returned by "getItemsCallback").
+ *
+ * @class
+ * @public
+ */
+class ItemNavigation {
+	/**
+	 *
+	 * @param rootWebComponent the component to operate on (component that slots or contains within its shadow root the items the user navigates among)
+	 * @param options Object with configuration options:
+	 *  - currentIndex: the index of the item that will be initially selected (from which navigation will begin)
+	 *  - navigationMode (Auto|Horizontal|Vertical): whether the items are displayed horizontally (Horizontal), vertically (Vertical) or as a matrix (Auto) meaning the user can navigate in both directions (up/down and left/right)
+	 *  - rowSize: tells how many items per row there are when the items are not rendered as a flat list but rather as a matrix. Relevant for navigationMode=Auto
+	 * 	- skipItemsSize: tells how many items upon PAGE_UP and PAGE_DOWN should be skipped to applying the focus on the next item
+	 *  - behavior (Static|Cycling): tells what to do when trying to navigate beyond the first and last items
+	 *    Static means that nothing happens if the user tries to navigate beyond the first/last item.
+	 *    Cycling means that when the user navigates beyond the last item they go to the first and vice versa.
+	 *  - getItemsCallback: function that, when called, returns an array with all items the user can navigate among
+	 *  - affectedPropertiesNames: a list of metadata properties on the root component which, upon user navigation, will be reassigned by address thus causing the root component to invalidate
+	 */
 	constructor(rootWebComponent, options = {}) {
-		super();
-
-		this.currentIndex = options.currentIndex || 0;
-		this.rowSize = options.rowSize || 1;
-		this.behavior = options.behavior || ItemNavigationBehavior.Static;
-
-		const navigationMode = options.navigationMode;
-		const autoNavigation = !navigationMode || navigationMode === NavigationMode.Auto;
-		this.horizontalNavigationOn = autoNavigation || navigationMode === NavigationMode.Horizontal;
-		this.verticalNavigationOn = autoNavigation || navigationMode === NavigationMode.Vertical;
+		this._setRootComponent(rootWebComponent);
+		this._initOptions(options);
+	}
 
+	_setRootComponent(rootWebComponent) {
+		if (!rootWebComponent.isUI5Element) {
+			throw new Error("The root web component must be a UI5 Element instance");
+		}
 		this.rootWebComponent = rootWebComponent;
-		this.rootWebComponent.addEventListener("keydown", this.onkeydown.bind(this));
-		this.rootWebComponent.addEventListener("_componentStateFinalized", () => {
+		this.rootWebComponent.addEventListener("keydown", this._onkeydown.bind(this));
+		this.rootWebComponent._onComponentStateFinalized = () => {
 			this._init();
-		});
+		};
 	}
 
-	_init() {
-		this._getItems().forEach((item, idx) => {
-			item._tabIndex = (idx === this.currentIndex) ? "0" : "-1";
-		});
+	_initOptions(options) {
+		if (typeof options.getItemsCallback !== "function") {
+			throw new Error("getItemsCallback is required");
+		}
+
+		this._getItems = options.getItemsCallback;
+		this._currentIndex = options.currentIndex || 0;
+		this._rowSize = options.rowSize || 1;
+		this._behavior = options.behavior || ItemNavigationBehavior.Static;
+		this._navigationMode = options.navigationMode || NavigationMode.Auto;
+		this._affectedPropertiesNames = options.affectedPropertiesNames || [];
+		this._skipItemsSize = options.skipItemsSize || null;
 	}
 
-	_horizontalNavigationOn() {
-		return this.horizontalNavigationOn;
+	/**
+	 * Call this method to set a new "current" (selected) item in the item navigation
+	 * Note: the item passed to this function must be one of the items, returned by the getItemsCallback function
+	 *
+	 * @public
+	 * @param current the new selected item
+	 */
+	setCurrentItem(current) {
+		const currentItemIndex = this._getItems().indexOf(current);
+
+		if (currentItemIndex === -1) {
+			console.warn(`The provided item is not managed by ItemNavigation`, current); // eslint-disable-line
+			return;
+		}
+
+		this._currentIndex = currentItemIndex;
+		this._applyTabIndex();
 	}
 
-	_verticalNavigationOn() {
-		return this.verticalNavigationOn;
+	/**
+	 * Call this method to dynamically change the row size
+	 *
+	 * @public
+	 * @param newRowSize
+	 */
+	setRowSize(newRowSize) {
+		this._rowSize = newRowSize;
 	}
 
-	_onKeyPress(event) {
-		const items = this._getItems();
-		if (this.currentIndex >= items.length) {
-			if (this.behavior !== ItemNavigationBehavior.Cyclic) {
-				if (this.behavior === ItemNavigationBehavior.Paging) {
-					this.currentIndex = this.currentIndex - items.length;
-				} else {
-					this.currentIndex = items.length - 1;
-				}
-				this.fireEvent(ItemNavigation.BORDER_REACH, { start: false, end: true, offset: this.currentIndex });
-			} else {
-				this.currentIndex = this.currentIndex - items.length;
-			}
-		} else if (this.currentIndex < 0) {
-			if (this.behavior !== ItemNavigationBehavior.Cyclic) {
-				if (this.behavior === ItemNavigationBehavior.Paging) {
-					this.currentIndex = items.length + this.currentIndex - this.rowSize + (this.rowSize - (this._getItems().length % this.rowSize));
-				} else {
-					this.currentIndex = 0;
-				}
-				this.fireEvent(ItemNavigation.BORDER_REACH, { start: true, end: false, offset: this.currentIndex });
-			} else {
-				this.currentIndex = items.length + this.currentIndex;
-			}
+	_init() {
+		this._getItems().forEach((item, idx) => {
+			item._tabIndex = (idx === this._currentIndex) ? "0" : "-1";
+		});
+	}
+
+	_onkeydown(event) {
+		if (!this._canNavigate()) {
+			return;
 		}
 
-		this.update();
-		this.focusCurrent();
+		const horizontalNavigationOn = this._navigationMode === NavigationMode.Horizontal || this._navigationMode === NavigationMode.Auto;
+		const verticalNavigationOn = this._navigationMode === NavigationMode.Vertical || this._navigationMode === NavigationMode.Auto;
+
+		if (isUp(event) && verticalNavigationOn) {
+			this._handleUp();
+		} else if (isDown(event) && verticalNavigationOn) {
+			this._handleDown();
+		} else if (isLeft(event) && horizontalNavigationOn) {
+			this._handleLeft();
+		} else if (isRight(event) && horizontalNavigationOn) {
+			this._handleRight();
+		} else if (isHome(event)) {
+			this._handleHome();
+		} else if (isEnd(event)) {
+			this._handleEnd();
+		} else if (isPageUp(event)) {
+			this._handlePageUp();
+		} else if (isPageDown(event)) {
+			this._handlePageDown();
+		} else {
+			return; // if none of the supported keys is pressed, we don't want to prevent the event or update the item navigation
+		}
 
-		// stops browser scrolling with up/down keys
 		event.preventDefault();
+		this._applyTabIndex();
+		this._focusCurrentItem();
 	}
 
-	onkeydown(event) {
-		if (isUp(event) && this._verticalNavigationOn()) {
-			return this._handleUp(event);
+	_handleUp() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex - this._rowSize >= 0) { // no border reached, just decrease the index by a row
+			this._currentIndex -= this._rowSize;
+			return;
 		}
 
-		if (isDown(event) && this._verticalNavigationOn()) {
-			return this._handleDown(event);
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // if cyclic, go to the **last** item in the **previous** column
+			const firstItemInThisColumnIndex = this._currentIndex % this._rowSize;
+			const firstItemInPreviousColumnIndex = firstItemInThisColumnIndex === 0 ? this._rowSize - 1 : firstItemInThisColumnIndex - 1; // find the first item in the previous column (if the current column is the first column -> move to the last column)
+			const rows = Math.ceil(itemsLength / this._rowSize); // how many rows there are (even if incomplete, f.e. for 14 items and _rowSize=4 -> 4 rows total, although only 2 items on the last row)
+			let lastItemInPreviousColumnIndex = firstItemInPreviousColumnIndex + (rows - 1) * this._rowSize; // multiply rows by columns, and add the column's first item's index
+			if (lastItemInPreviousColumnIndex > itemsLength - 1) { // for incomplete rows, use the previous row's last item, as for them the last item is missing
+				lastItemInPreviousColumnIndex -= this._rowSize;
+			}
+			this._currentIndex = lastItemInPreviousColumnIndex;
+		} else { // not cyclic, so just go to the first item
+			this._currentIndex = 0;
 		}
+	}
 
-		if (isLeft(event) && this._horizontalNavigationOn()) {
-			return this._handleLeft(event);
+	_handleDown() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex + this._rowSize < itemsLength) { // no border reached, just increase the index by a row
+			this._currentIndex += this._rowSize;
+			return;
 		}
 
-		if (isRight(event) && this._horizontalNavigationOn()) {
-			return this._handleRight(event);
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // if cyclic, go to the **first** item in the **next** column
+			const firstItemInThisColumnIndex = this._currentIndex % this._rowSize; // find the first item in the current column first
+			const firstItemInNextColumnIndex = (firstItemInThisColumnIndex + 1) % this._rowSize; // to get the first item in the next column, just increase the index by 1. The modulo by rows is for the case when we are at the last column
+			this._currentIndex = firstItemInNextColumnIndex;
+		} else { // not cyclic, so just go to the last item
+			this._currentIndex = itemsLength - 1;
 		}
+	}
 
-		if (isHome(event)) {
-			return this._handleHome(event);
+	_handleLeft() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex > 0) {
+			this._currentIndex -= 1;
+			return;
 		}
 
-		if (isEnd(event)) {
-			return this._handleEnd(event);
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // go to the first item in the next column
+			this._currentIndex = itemsLength - 1;
 		}
 	}
 
-	_handleUp(event) {
-		if (this._canNavigate()) {
-			this.currentIndex -= this.rowSize;
-			this._onKeyPress(event);
+	_handleRight() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex < itemsLength - 1) {
+			this._currentIndex += 1;
+			return;
 		}
-	}
 
-	_handleDown(event) {
-		if (this._canNavigate()) {
-			this.currentIndex += this.rowSize;
-			this._onKeyPress(event);
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // go to the first item in the next column
+			this._currentIndex = 0;
 		}
 	}
 
-	_handleLeft(event) {
-		if (this._canNavigate()) {
-			this.currentIndex -= 1;
-			this._onKeyPress(event);
-		}
+	_handleHome() {
+		const homeEndRange = this._rowSize > 1 ? this._rowSize : this._getItems().length;
+		this._currentIndex -= this._currentIndex % homeEndRange;
 	}
 
-	_handleRight(event) {
-		if (this._canNavigate()) {
-			this.currentIndex += 1;
-			this._onKeyPress(event);
-		}
+	_handleEnd() {
+		const homeEndRange = this._rowSize > 1 ? this._rowSize : this._getItems().length;
+		this._currentIndex += (homeEndRange - 1 - this._currentIndex % homeEndRange); // eslint-disable-line
 	}
 
-	_handleHome(event) {
-		if (this._canNavigate()) {
-			const homeEndRange = this.rowSize > 1 ? this.rowSize : this._getItems().length;
-			this.currentIndex -= this.currentIndex % homeEndRange;
-			this._onKeyPress(event);
+	_handlePageUp() {
+		if (this._rowSize > 1) {
+			// eslint-disable-next-line
+			// TODO: handle page up on matrix (grid) layout - ColorPalette, ProductSwitch.
+			return;
 		}
+		this._handlePageUpFlat();
 	}
 
-	_handleEnd(event) {
-		if (this._canNavigate()) {
-			const homeEndRange = this.rowSize > 1 ? this.rowSize : this._getItems().length;
-			this.currentIndex += (homeEndRange - 1 - this.currentIndex % homeEndRange); // eslint-disable-line
-			this._onKeyPress(event);
+	_handlePageDown() {
+		if (this._rowSize > 1) {
+			// eslint-disable-next-line
+			// TODO: handle page up on matrix (grid) layout - ColorPalette, ProductSwitch.
+			return;
 		}
+		this._handlePageDownFlat();
 	}
 
-	update(current) {
-		const origItems = this._getItems();
+	/**
+	 * Handles PAGE_UP in a flat list-like structure, both vertically and horizontally.
+	 */
+	_handlePageUpFlat() {
+		if (this._skipItemsSize === null) {
+			// Move the focus to the very top (as Home).
+			this._currentIndex -= this._currentIndex;
+		}
 
-		if (current) {
-			this.currentIndex = this._getItems().indexOf(current);
+		if (this._currentIndex + 1 > this._skipItemsSize) {
+			// When there are more than "skipItemsSize" number of items to the top,
+			// move the focus up/left with the predefined number.
+			this._currentIndex -= this._skipItemsSize;
+		} else {
+			// Otherwise, move the focus to the very top (as Home).
+			this._currentIndex -= this._currentIndex;
 		}
+	}
 
-		if (!origItems[this.currentIndex]
-			|| (origItems[this.currentIndex]._tabIndex && origItems[this.currentIndex]._tabIndex === "0")) {
-			return;
+	/**
+	 * Handles PAGE_DOWN in a flat list-like structure, both vertically and horizontally.
+	 */
+	_handlePageDownFlat() {
+		if (this._skipItemsSize === null) {
+			// Move the focus to the very bottom (as End).
+			this._currentIndex = this._getItems().length - 1;
 		}
 
-		const items = origItems.slice(0);
+		const currentToEndRange = this._getItems().length - this._currentIndex - 1;
 
-		for (let i = 0; i < items.length; i++) {
-			items[i]._tabIndex = (i === this.currentIndex ? "0" : "-1");
+		if (currentToEndRange > this._skipItemsSize) {
+			// When there are more than "skipItemsSize" number of items until the bottom,
+			// move the focus down/right with the predefined number.
+			this._currentIndex += this._skipItemsSize;
+		} else {
+			// Otherwise, move the focus to the very bottom (as End).
+			this._currentIndex = this._getItems().length - 1;
 		}
+	}
 
+	_applyTabIndex() {
+		const items = this._getItems();
+		for (let i = 0; i < items.length; i++) {
+			items[i]._tabIndex = i === this._currentIndex ? "0" : "-1";
+		}
 
-		this.rootWebComponent._invalidate();
+		this._affectedPropertiesNames.forEach(propName => {
+			const prop = this.rootWebComponent[propName];
+			this.rootWebComponent[propName] = Array.isArray(prop) ? [...prop] : { ...prop };
+		});
 	}
 
-	focusCurrent() {
+	_focusCurrentItem() {
 		const currentItem = this._getCurrentItem();
 		if (currentItem) {
 			currentItem.focus();
@@ -181,12 +309,7 @@ class ItemNavigation extends EventProvider {
 
 	_canNavigate() {
 		const currentItem = this._getCurrentItem();
-
-		let activeElement = document.activeElement;
-
-		while (activeElement.shadowRoot && activeElement.shadowRoot.activeElement) {
-			activeElement = activeElement.shadowRoot.activeElement;
-		}
+		const activeElement = getActiveElement();
 
 		return currentItem && currentItem === activeElement;
 	}
@@ -199,17 +322,21 @@ class ItemNavigation extends EventProvider {
 		}
 
 		// normalize the index
-		while (this.currentIndex >= items.length) {
-			this.currentIndex -= this.rowSize;
+		while (this._currentIndex >= items.length) {
+			this._currentIndex -= this._rowSize;
 		}
 
-		if (this.currentIndex < 0) {
-			this.currentIndex = 0;
+		if (this._currentIndex < 0) {
+			this._currentIndex = 0;
 		}
 
-		const currentItem = items[this.currentIndex];
+		const currentItem = items[this._currentIndex];
 
-		if (currentItem instanceof UI5Element) {
+		if (!currentItem) {
+			return;
+		}
+
+		if (currentItem.isUI5Element) {
 			return currentItem.getFocusDomRef();
 		}
 
@@ -219,16 +346,6 @@ class ItemNavigation extends EventProvider {
 
 		return this.rootWebComponent.getDomRef().querySelector(`#${currentItem.id}`);
 	}
-
-	set getItemsCallback(fn) {
-		this._getItems = fn;
-	}
-
-	set current(val) {
-		this.currentIndex = val;
-	}
 }
 
-ItemNavigation.BORDER_REACH = "_borderReach";
-
 export default ItemNavigation;

package/src/delegate/ResizeHandler.js

@@ -1,66 +1,106 @@
-import UI5Element from "../UI5Element.js";
-import NativeResize from "./NativeResize.js";
-import CustomResize from "./CustomResize.js";
+let resizeObserver;
+const observedElements = new Map();
 
-class ResizeHandler {
-	static initialize() {
-		ResizeHandler.Implementation = window.ResizeObserver ? NativeResize : CustomResize;
-		ResizeHandler.Implementation.initialize();
+const getResizeObserver = () => {
+	if (!resizeObserver) {
+		resizeObserver = new window.ResizeObserver(entries => {
+			entries.forEach(entry => {
+				const callbacks = observedElements.get(entry.target);
+				callbacks.forEach(callback => callback());
+			});
+		});
 	}
+	return resizeObserver;
+};
 
-	/**
-	 * @static
-	 * @private
-	 * @param {*} ref Reference to be observed
-	 * @param {*} callback Callback to be executed
-	 * @memberof ResizeHandler
-	 */
-	static attachListener(ref, callback) {
-		ResizeHandler.Implementation.attachListener.call(ResizeHandler.Implementation, ref, callback);
+let observe = (element, callback) => {
+	const callbacks = observedElements.get(element) || [];
+
+	// if no callbacks have been added for this element - start observing it
+	if (!callbacks.length) {
+		getResizeObserver().observe(element);
 	}
 
-	/**
-	 * @static
-	 * @private
-	 * @param {*} ref Reference to be unobserved
-	 * @memberof ResizeHandler
-	 */
-	static detachListener(ref, callback) {
-		ResizeHandler.Implementation.detachListener.call(ResizeHandler.Implementation, ref, callback);
+	// save the callbacks in an array
+	observedElements.set(element, [...callbacks, callback]);
+};
+
+let unobserve = (element, callback) => {
+	const callbacks = observedElements.get(element) || [];
+	if (callbacks.length === 0) {
+		return;
 	}
 
+	const filteredCallbacks = callbacks.filter(fn => fn !== callback);
+	if (filteredCallbacks.length === 0) {
+		getResizeObserver().unobserve(element);
+		observedElements.delete(element);
+	} else {
+		observedElements.set(element, filteredCallbacks);
+	}
+};
 
+/**
+ * Allows to register/deregister resize observers for a DOM element
+ *
+ * @public
+ * @class
+  */
+class ResizeHandler {
 	/**
 	 * @static
 	 * @public
-	 * @param {*} ref Reference to a UI5 Web Component or DOM Element to be observed
+	 * @param {*} element UI5 Web Component or DOM Element to be observed
 	 * @param {*} callback Callback to be executed
-	 * @memberof ResizeHandler
 	 */
-	static register(ref, callback) {
-		if (ref instanceof UI5Element) {
-			ref = ref.getDomRef();
+	static register(element, callback) {
+		if (element.isUI5Element) {
+			element = element.getDomRef();
 		}
 
-		ResizeHandler.attachListener(ref, callback);
+		if (element instanceof HTMLElement) {
+			observe(element, callback);
+		} else {
+			console.warn("Cannot register ResizeHandler for element", element); // eslint-disable-line
+		}
 	}
 
-
 	/**
 	 * @static
 	 * @public
-	 * @param {*} ref Reference to UI5 Web Component or DOM Element to be unobserved
-	 * @memberof ResizeHandler
+	 * @param {*} element UI5 Web Component or DOM Element to be unobserved
+	 * @param {*} callback Callback to be removed
 	 */
-	static deregister(ref, callback) {
-		if (ref instanceof UI5Element) {
-			ref = ref.getDomRef();
+	static deregister(element, callback) {
+		if (element.isUI5Element) {
+			element = element.getDomRef();
 		}
 
-		ResizeHandler.detachListener(ref, callback);
+		if (element instanceof HTMLElement) {
+			unobserve(element, callback);
+		} else {
+			console.warn("Cannot deregister ResizeHandler for element", element); // eslint-disable-line
+		}
 	}
 }
 
-ResizeHandler.initialize();
+/**
+ * Set a function to be executed whenever a DOM node needs to be observed for size change.
+ * @public
+ * @param fn
+ */
+const setResizeHandlerObserveFn = fn => {
+	observe = fn;
+};
+
+/**
+ * Set a function to be executed whenever a DOM node needs to no longer be observed for size changes
+ * @public
+ * @param fn
+ */
+const setResizeHandlerUnobserveFn = fn => {
+	unobserve = fn;
+};
 
 export default ResizeHandler;
+export { setResizeHandlerObserveFn, setResizeHandlerUnobserveFn };