@ui5/webcomponents-base 0.0.0-d0bcf47c7 → 0.0.0-d4d43327a

package/src/decorators/customElement.ts

@@ -0,0 +1,57 @@
+import type UI5Element from "../UI5Element.js";
+import type { Renderer } from "../UI5Element.js";
+import type { TemplateFunction as Template } from "../renderer/executeTemplate.js";
+import type { ComponentStylesData as Styles } from "../types.js";
+
+/**
+ * Returns a custom element class decorator.
+ *
+ * @param { string | object } tagNameOrComponentSettings
+ * @returns { ClassDecorator }
+ */
+const customElement = (tagNameOrComponentSettings: string | {
+	tag?: string,
+	renderer?: Renderer,
+	styles?: Styles,
+	template?: Template,
+	dependencies?: Array<typeof UI5Element>,
+	staticAreaStyles?: Styles,
+	staticAreaTemplate?: Template,
+	languageAware?: boolean,
+	themeAware?: boolean,
+	fastNavigation?: boolean,
+}): ClassDecorator => {
+	return (target: any) => {
+		if (!Object.prototype.hasOwnProperty.call(target, "metadata")) {
+			target.metadata = {};
+		}
+
+		if (typeof tagNameOrComponentSettings === "string") {
+			target.metadata.tag = tagNameOrComponentSettings;
+			return;
+		}
+
+		const {
+			tag,
+			languageAware = false,
+			themeAware = false,
+			fastNavigation = false,
+		 } = tagNameOrComponentSettings;
+
+		target.metadata.tag = tag;
+		target.metadata.languageAware = languageAware;
+		target.metadata.themeAware = themeAware;
+		target.metadata.fastNavigation = fastNavigation;
+
+		["render", "renderer", "template", "staticAreaTemplate", "styles", "staticAreaStyles", "dependencies"].forEach((customElementEntity: string) => {
+			const _customElementEntity = customElementEntity === "render" ? "renderer" : customElementEntity;
+			const customElementEntityValue = tagNameOrComponentSettings[_customElementEntity as keyof typeof tag];
+
+			customElementEntityValue && Object.defineProperty(target, customElementEntity, {
+				get: () => customElementEntityValue,
+			});
+		});
+	};
+};
+
+export default customElement;

package/src/decorators/event.ts

@@ -0,0 +1,28 @@
+import { EventData } from "../UI5ElementMetadata.js";
+
+/**
+ * Returns an event class decorator.
+ *
+ * @param { string } name the event name
+ * @param { EventData } data the event data
+ * @returns { ClassDecorator }
+ */
+const event = (name: string, data: EventData = {}): ClassDecorator => {
+	return (target: any) => {
+		if (!Object.prototype.hasOwnProperty.call(target, "metadata")) {
+			target.metadata = {};
+		}
+
+		const metadata = target.metadata;
+		if (!metadata.events) {
+			metadata.events = {};
+		}
+
+		const eventsMetadata = metadata.events;
+		if (!eventsMetadata[name]) {
+			eventsMetadata[name] = data;
+		}
+	};
+};
+
+export default event;

package/src/decorators/fastNavigation.ts

@@ -0,0 +1,14 @@
+/**
+ * Class decorator, that sets the fastNavigation metadata.
+ * @param { any } target the decorated class
+ * @returns { void }
+ */
+const fastNavigation = (target: any): void => {
+	if (!Object.prototype.hasOwnProperty.call(target, "metadata")) {
+		target.metadata = {};
+	}
+
+	target.metadata.fastNavigation = true;
+};
+
+export default fastNavigation;

package/src/decorators/languageAware.ts

@@ -0,0 +1,14 @@
+/**
+ * Class decorator, that sets the languageAware metadata.
+ * @param { any } target the decorated class
+ * @returns { void }
+ */
+const languageAware = (target: any): void => {
+	if (!Object.prototype.hasOwnProperty.call(target, "metadata")) {
+		target.metadata = {};
+	}
+
+	target.metadata.languageAware = true;
+};
+
+export default languageAware;

package/src/decorators/property.ts

@@ -0,0 +1,30 @@
+import type UI5Element from "../UI5Element.js";
+import { Property } from "../UI5ElementMetadata.js";
+
+/**
+ * Returns a property decorator.
+ *
+ * @param { Property } propData
+ * @returns { PropertyDecorator }
+ */
+const property = (propData?: Property): PropertyDecorator => {
+	return (target: any, propertyKey: string | symbol) => {
+		const ctor = target.constructor as typeof UI5Element;
+
+		if (!Object.prototype.hasOwnProperty.call(ctor, "metadata")) {
+			ctor.metadata = {};
+		}
+
+		const metadata = ctor.metadata;
+		if (!metadata.properties) {
+			metadata.properties = {};
+		}
+
+		const propsMetadata = metadata.properties;
+		if (!propsMetadata[propertyKey as string]) {
+			propsMetadata[propertyKey as string] = propData || { type: String };
+		}
+	};
+};
+
+export default property;

package/src/decorators/slot.ts

@@ -0,0 +1,49 @@
+import type UI5Element from "../UI5Element.js";
+import { Slot } from "../UI5ElementMetadata.js";
+
+/**
+ * Returns a slot decorator.
+ *
+ * @param { Slot } slotData
+ * @returns { PropertyDecorator }
+ */
+const slot = (slotData?: Slot): PropertyDecorator => {
+	return (target: any, slotKey: string | symbol) => {
+		const ctor = target.constructor as typeof UI5Element;
+
+		if (!Object.prototype.hasOwnProperty.call(ctor, "metadata")) {
+			ctor.metadata = {};
+		}
+
+		const metadata = ctor.metadata;
+		if (!metadata.slots) {
+			metadata.slots = {};
+		}
+
+		const slotMetadata = metadata.slots;
+
+		if (slotData?.default && slotMetadata.default) {
+			throw new Error("Only one slot can be the default slot.");
+		}
+
+		const key = slotData?.default ? "default" : slotKey as string;
+		slotData = slotData || { type: HTMLElement };
+
+		if (!slotData.type) {
+			slotData.type = HTMLElement;
+		}
+
+		if (!slotMetadata[key]) {
+			slotMetadata[key] = slotData;
+		}
+
+		if (slotData.default) {
+			delete slotMetadata.default.default;
+			slotMetadata.default.propertyName = slotKey as string;
+		}
+
+		ctor.metadata.managedSlots = true;
+	};
+};
+
+export default slot;

package/src/decorators/themeAware.ts

@@ -0,0 +1,14 @@
+/**
+ * Class decorator, that sets the themeAware metadata.
+ * @param { any } target the decorated class
+ * @returns { void }
+ */
+const themeAware = (target: any): void => {
+	if (!Object.prototype.hasOwnProperty.call(target, "metadata")) {
+		target.metadata = {};
+	}
+
+	target.metadata.themeAware = true;
+};
+
+export default themeAware;

package/src/delegate/ItemNavigation.ts

@@ -0,0 +1,393 @@
+import {
+	isDown,
+	isUp,
+	isLeft,
+	isRight,
+	isHome,
+	isEnd,
+	isPageDown,
+	isPageUp,
+} from "../Keys.js";
+import getActiveElement from "../util/getActiveElement.js";
+
+import NavigationMode from "../types/NavigationMode.js";
+import ItemNavigationBehavior from "../types/ItemNavigationBehavior.js";
+
+import type UI5Element from "../UI5Element.js";
+import { instanceOfUI5Element } from "../UI5Element.js";
+
+interface ITabbable {
+	id: string,
+	_tabIndex: string,
+}
+
+type ItemNavigationOptions = {
+	currentIndex?: number,
+	navigationMode?: NavigationMode,
+	rowSize?: number
+	skipItemsSize?: number,
+	behavior?: ItemNavigationBehavior,
+	getItemsCallback: () => Array<ITabbable>,
+	affectedPropertiesNames?: Array<string>,
+};
+
+/**
+ * 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 {
+	rootWebComponent: UI5Element;
+
+	_getItems: () => Array<ITabbable>;
+
+	_currentIndex: number;
+
+	_rowSize: number;
+
+	_behavior: ItemNavigationBehavior;
+
+	_navigationMode: NavigationMode;
+
+	_affectedPropertiesNames: Array<string>;
+
+	_skipItemsSize: number | null;
+
+	/**
+	 *
+	 * @param rootWebComponent the component to operate on (component that slots or contains within its shadow root the items the user navigates among)
+	 * @param {ItemNavigationOptions} 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: UI5Element, options: ItemNavigationOptions) {
+		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._onComponentStateFinalized = () => {
+			this._init();
+		};
+
+		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;
+	}
+
+	/**
+	 * 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: ITabbable) {
+		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();
+	}
+
+	/**
+	 * Call this method to dynamically change the row size
+	 *
+	 * @public
+	 * @param newRowSize
+	 */
+	setRowSize(newRowSize: number) {
+		this._rowSize = newRowSize;
+	}
+
+	_init() {
+		this._getItems().forEach((item, idx) => {
+			item._tabIndex = (idx === this._currentIndex) ? "0" : "-1";
+		});
+	}
+
+	_onkeydown(event: KeyboardEvent) {
+		if (!this._canNavigate()) {
+			return;
+		}
+
+		const horizontalNavigationOn = this._navigationMode === NavigationMode.Horizontal || this._navigationMode === NavigationMode.Auto;
+		const verticalNavigationOn = this._navigationMode === NavigationMode.Vertical || this._navigationMode === NavigationMode.Auto;
+		const isRTL = this.rootWebComponent.effectiveDir === "rtl";
+
+		if (isRTL && isLeft(event) && horizontalNavigationOn) {
+			this._handleRight();
+		} else if (isRTL && isRight(event) && horizontalNavigationOn) {
+			this._handleLeft();
+		} else if (isLeft(event) && horizontalNavigationOn) {
+			this._handleLeft();
+		} else if (isRight(event) && horizontalNavigationOn) {
+			this._handleRight();
+		} else if (isUp(event) && verticalNavigationOn) {
+			this._handleUp();
+		} else if (isDown(event) && verticalNavigationOn) {
+			this._handleDown();
+		} 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
+		}
+
+		event.preventDefault();
+		this._applyTabIndex();
+		this._focusCurrentItem();
+	}
+
+	_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 (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;
+		}
+	}
+
+	_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 (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;
+		}
+	}
+
+	_handleLeft() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex > 0) {
+			this._currentIndex -= 1;
+			return;
+		}
+
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // go to the first item in the next column
+			this._currentIndex = itemsLength - 1;
+		}
+	}
+
+	_handleRight() {
+		const itemsLength = this._getItems().length;
+		if (this._currentIndex < itemsLength - 1) {
+			this._currentIndex += 1;
+			return;
+		}
+
+		if (this._behavior === ItemNavigationBehavior.Cyclic) { // go to the first item in the next column
+			this._currentIndex = 0;
+		}
+	}
+
+	_handleHome() {
+		const homeEndRange = this._rowSize > 1 ? this._rowSize : this._getItems().length;
+		this._currentIndex -= this._currentIndex % homeEndRange;
+	}
+
+	_handleEnd() {
+		const homeEndRange = this._rowSize > 1 ? this._rowSize : this._getItems().length;
+		this._currentIndex += (homeEndRange - 1 - this._currentIndex % homeEndRange); // eslint-disable-line
+	}
+
+	_handlePageUp() {
+		if (this._rowSize > 1) {
+			// eslint-disable-next-line
+			// TODO: handle page up on matrix (grid) layout - ColorPalette, ProductSwitch.
+			return;
+		}
+		this._handlePageUpFlat();
+	}
+
+	_handlePageDown() {
+		if (this._rowSize > 1) {
+			// eslint-disable-next-line
+			// TODO: handle page up on matrix (grid) layout - ColorPalette, ProductSwitch.
+			return;
+		}
+		this._handlePageDownFlat();
+	}
+
+	/**
+	 * 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;
+			return;
+		}
+
+		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;
+		}
+	}
+
+	/**
+	 * 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;
+			return;
+		}
+
+		const currentToEndRange = this._getItems().length - this._currentIndex - 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._affectedPropertiesNames.forEach(propName => {
+			const prop = (this.rootWebComponent as Record<string, any>)[propName];
+			(this.rootWebComponent as Record<string, any>)[propName] = Array.isArray(prop) ? [...prop] : { ...prop };
+		});
+	}
+
+	_focusCurrentItem() {
+		const currentItem = this._getCurrentItem();
+		if (currentItem) {
+			currentItem.focus({ focusVisible: true } as FocusOptions);
+		}
+	}
+
+	_canNavigate() {
+		const currentItem = this._getCurrentItem();
+		const activeElement = getActiveElement();
+
+		return currentItem && currentItem === activeElement;
+	}
+
+	_getCurrentItem() {
+		const items = this._getItems();
+
+		if (!items.length) {
+			return;
+		}
+
+		// normalize the index
+		while (this._currentIndex >= items.length) {
+			this._currentIndex -= this._rowSize;
+		}
+
+		if (this._currentIndex < 0) {
+			this._currentIndex = 0;
+		}
+
+		const currentItem = items[this._currentIndex];
+
+		if (!currentItem) {
+			return;
+		}
+
+		if (instanceOfUI5Element(currentItem)) {
+			return currentItem.getFocusDomRef();
+		}
+
+		const currentItemDOMRef = this.rootWebComponent.getDomRef();
+		if (!currentItemDOMRef) {
+			return;
+		}
+
+		if (currentItem.id) {
+			return currentItemDOMRef.querySelector(`#${currentItem.id}`) as HTMLElement;
+		}
+	}
+}
+
+export default ItemNavigation;
+
+export {
+	ITabbable,
+};