@ui5/webcomponents-base 0.0.0-2c7615fe9 → 0.0.0-2f7664755

package/src/{UI5Element.js → UI5Element.ts}

@@ -1,6 +1,12 @@
 import merge from "./thirdparty/merge.js";
 import { boot } from "./Boot.js";
-import UI5ElementMetadata from "./UI5ElementMetadata.js";
+import UI5ElementMetadata, {
+	Slot,
+	SlotValue,
+	State,
+	PropertyValue,
+	Metadata,
+} from "./UI5ElementMetadata.js";
 import EventProvider from "./EventProvider.js";
 import getSingletonElementInstance from "./util/getSingletonElementInstance.js";
 import StaticAreaItem from "./StaticAreaItem.js";
@@ -13,25 +19,40 @@ import getEffectiveDir from "./locale/getEffectiveDir.js";
 import DataType from "./types/DataType.js";
 import { kebabToCamelCase, camelToKebabCase } from "./util/StringHelper.js";
 import isValidPropertyName from "./util/isValidPropertyName.js";
-import isDescendantOf from "./util/isDescendantOf.js";
-import { isSlot, getSlotName, getSlottedElementsList } from "./util/SlotsHelper.js";
+import { getSlotName, getSlottedNodesList } from "./util/SlotsHelper.js";
 import arraysAreEqual from "./util/arraysAreEqual.js";
-import getClassCopy from "./util/getClassCopy.js";
 import { markAsRtlAware } from "./locale/RTLAwareRegistry.js";
-import isLegacyBrowser from "./isLegacyBrowser.js";
+import preloadLinks from "./theming/preloadLinks.js";
+import { TemplateFunction, TemplateFunctionResult } from "./renderer/executeTemplate.js";
+import { PromiseResolve, ComponentStylesData, ClassMap } from "./types.js";
 
 let autoId = 0;
 
-const elementTimeouts = new Map();
-const uniqueDependenciesCache = new Map();
+const elementTimeouts = new Map<string, Promise<void>>();
+const uniqueDependenciesCache = new Map<typeof UI5Element, Array<typeof UI5Element>>();
+
+type ChangeInfo = {
+	type: "property" | "slot",
+	name: string,
+	reason?: string,
+	child?: SlotValue,
+	target?: UI5Element,
+	newValue?: PropertyValue,
+	oldValue?: PropertyValue,
+}
+
+type InvalidationInfo = ChangeInfo & { target: UI5Element };
+
+type ChildChangeListener = (param: InvalidationInfo) => void;
+
+type SlotChangeListener = (this: HTMLSlotElement, ev: Event) => void;
 
 /**
  * Triggers re-rendering of a UI5Element instance due to state change.
- *
- * @param  changeInfo An object with information about the change that caused invalidation.
+ * @param {ChangeInfo} changeInfo An object with information about the change that caused invalidation.
  * @private
  */
-function _invalidate(changeInfo) {
+function _invalidate(this: UI5Element, changeInfo: ChangeInfo) {
 	// Invalidation should be suppressed: 1) before the component is rendered for the first time 2) and during the execution of onBeforeRendering
 	// This is necessary not only as an optimization, but also to avoid infinite loops on invalidation between children and parents (when invalidateOnChildChange is used)
 	if (this._suppressInvalidation) {
@@ -46,20 +67,44 @@ function _invalidate(changeInfo) {
 	this._eventProvider.fireEvent("invalidate", { ...changeInfo, target: this });
 }
 
+let metadata = {} as Metadata;
+
 /**
  * Base class for all UI5 Web Components
  *
  * @class
  * @constructor
  * @author SAP SE
- * @alias sap.ui.webcomponents.base.UI5Element
+ * @alias sap.ui.webc.base.UI5Element
  * @extends HTMLElement
  * @public
  */
-class UI5Element extends HTMLElement {
+abstract class UI5Element extends HTMLElement {
+	__id?: string;
+	_suppressInvalidation: boolean;
+	_changedState: Array<ChangeInfo>;
+	_eventProvider: EventProvider<InvalidationInfo, void>;
+	_inDOM: boolean;
+	_fullyConnected: boolean;
+	_childChangeListeners: Map<string, ChildChangeListener>;
+	_slotChangeListeners: Map<string, SlotChangeListener>;
+	_domRefReadyPromise: Promise<void> & { _deferredResolve?: PromiseResolve };
+	_doNotSyncAttributes: Set<string>;
+	_state: State;
+	_onComponentStateFinalized?: () => void;
+	_getRealDomRef?: () => HTMLElement;
+
+	staticAreaItem?: StaticAreaItem;
+
+	static template?: TemplateFunction;
+	static staticAreaTemplate?: TemplateFunction;
+	static _metadata: UI5ElementMetadata;
+	static render: (templateFunctionResult: TemplateFunctionResult, container: HTMLElement | DocumentFragment, styleStrOrHrefsArr: string | Array<string> | undefined, forStaticArea: boolean, options: { host: HTMLElement }) => void;
+
 	constructor() {
 		super();
 
+		const ctor = this.constructor as typeof UI5Element;
 		this._changedState = []; // Filled on each invalidation, cleared on re-render (used for debugging)
 		this._suppressInvalidation = true; // A flag telling whether all invalidations should be ignored. Initialized with "true" because a UI5Element can not be invalidated until it is rendered for the first time
 		this._inDOM = false; // A flag telling whether the UI5Element is currently in the DOM tree of the document or not
@@ -72,11 +117,13 @@ class UI5Element extends HTMLElement {
 			deferredResolve = resolve;
 		});
 		this._domRefReadyPromise._deferredResolve = deferredResolve;
+		this._doNotSyncAttributes = new Set(); // attributes that are excluded from attributeChangedCallback synchronization
+
+		this._state = { ...ctor.getMetadata().getInitialState() };
 
-		this._initializeState();
 		this._upgradeAllProperties();
 
-		if (this.constructor._needsShadowDOM()) {
+		if (ctor._needsShadowDOM()) {
 			this.attachShadow({ mode: "open" });
 		}
 	}
@@ -100,9 +147,14 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	async connectedCallback() {
-		this.setAttribute(this.constructor.getMetadata().getPureTag(), "");
+		const ctor = this.constructor as typeof UI5Element;
 
-		const slotsAreManaged = this.constructor.getMetadata().slotsAreManaged();
+		this.setAttribute(ctor.getMetadata().getPureTag(), "");
+		if (ctor.getMetadata().supportsF6FastNavigation()) {
+			this.setAttribute("data-sap-ui-fastnavgroup", "true");
+		}
+
+		const slotsAreManaged = ctor.getMetadata().slotsAreManaged();
 
 		this._inDOM = true;
 
@@ -117,11 +169,9 @@ class UI5Element extends HTMLElement {
 		}
 
 		renderImmediately(this);
-		this._domRefReadyPromise._deferredResolve();
+		this._domRefReadyPromise._deferredResolve!();
 		this._fullyConnected = true;
-		if (typeof this.onEnterDOM === "function") {
-			this.onEnterDOM();
-		}
+		this.onEnterDOM();
 	}
 
 	/**
@@ -129,7 +179,8 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	disconnectedCallback() {
-		const slotsAreManaged = this.constructor.getMetadata().slotsAreManaged();
+		const ctor = this.constructor as typeof UI5Element;
+		const slotsAreManaged = ctor.getMetadata().slotsAreManaged();
 
 		this._inDOM = false;
 
@@ -138,9 +189,7 @@ class UI5Element extends HTMLElement {
 		}
 
 		if (this._fullyConnected) {
-			if (typeof this.onExitDOM === "function") {
-				this.onExitDOM();
-			}
+			this.onExitDOM();
 			this._fullyConnected = false;
 		}
 
@@ -151,22 +200,47 @@ class UI5Element extends HTMLElement {
 		cancelRender(this);
 	}
 
+	/**
+	 * Called every time before the component renders.
+	 * @public
+	 */
+	onBeforeRendering() {}
+
+	/**
+	 * Called every time after the component renders.
+	 * @public
+	 */
+	onAfterRendering() {}
+
+	/**
+	 * Called on connectedCallback - added to the DOM.
+	 * @public
+	 */
+	onEnterDOM() {}
+
+	/**
+	 * Called on disconnectedCallback - removed from the DOM.
+	 * @public
+	 */
+	onExitDOM() {}
+
 	/**
 	 * @private
 	 */
 	_startObservingDOMChildren() {
-		const shouldObserveChildren = this.constructor.getMetadata().hasSlots();
+		const ctor = this.constructor as typeof UI5Element;
+		const shouldObserveChildren = ctor.getMetadata().hasSlots();
 		if (!shouldObserveChildren) {
 			return;
 		}
 
-		const canSlotText = this.constructor.getMetadata().canSlotText();
+		const canSlotText = ctor.getMetadata().canSlotText();
 		const mutationObserverOptions = {
 			childList: true,
 			subtree: canSlotText,
 			characterData: canSlotText,
 		};
-		observeDOMNode(this, this._processChildren.bind(this), mutationObserverOptions);
+		observeDOMNode(this, this._processChildren.bind(this) as MutationCallback, mutationObserverOptions);
 	}
 
 	/**
@@ -181,7 +255,7 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	async _processChildren() {
-		const hasSlots = this.constructor.getMetadata().hasSlots();
+		const hasSlots = (this.constructor as typeof UI5Element).getMetadata().hasSlots();
 		if (hasSlots) {
 			await this._updateSlots();
 		}
@@ -191,23 +265,24 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	async _updateSlots() {
-		const slotsMap = this.constructor.getMetadata().getSlots();
-		const canSlotText = this.constructor.getMetadata().canSlotText();
-		const domChildren = Array.from(canSlotText ? this.childNodes : this.children);
+		const ctor = this.constructor as typeof UI5Element;
+		const slotsMap = ctor.getMetadata().getSlots();
+		const canSlotText = ctor.getMetadata().canSlotText();
+		const domChildren = Array.from(canSlotText ? this.childNodes : this.children) as Array<Node>;
 
-		const slotsCachedContentMap = new Map(); // Store here the content of each slot before the mutation occurred
-		const propertyNameToSlotMap = new Map(); // Used for reverse lookup to determine to which slot the property name corresponds
+		const slotsCachedContentMap = new Map<string, Array<SlotValue>>(); // Store here the content of each slot before the mutation occurred
+		const propertyNameToSlotMap = new Map<string, string>(); // Used for reverse lookup to determine to which slot the property name corresponds
 
 		// Init the _state object based on the supported slots and store the previous values
 		for (const [slotName, slotData] of Object.entries(slotsMap)) { // eslint-disable-line
 			const propertyName = slotData.propertyName || slotName;
 			propertyNameToSlotMap.set(propertyName, slotName);
-			slotsCachedContentMap.set(propertyName, [...this._state[propertyName]]);
+			slotsCachedContentMap.set(propertyName, [...(this._state[propertyName] as Array<SlotValue>)]);
 			this._clearSlot(slotName, slotData);
 		}
 
-		const autoIncrementMap = new Map();
-		const slottedChildrenMap = new Map();
+		const autoIncrementMap = new Map<string, number>();
+		const slottedChildrenMap = new Map<string, Array<{child: Node, idx: number }>>();
 
 		const allChildrenUpgraded = domChildren.map(async (child, idx) => {
 			// Determine the type of the child (mainly by the slot attribute)
@@ -216,8 +291,11 @@ class UI5Element extends HTMLElement {
 
 			// Check if the slotName is supported
 			if (slotData === undefined) {
-				const validValues = Object.keys(slotsMap).join(", ");
-				console.warn(`Unknown slotName: ${slotName}, ignoring`, child, `Valid values are: ${validValues}`); // eslint-disable-line
+				if (slotName !== "default") {
+					const validValues = Object.keys(slotsMap).join(", ");
+					console.warn(`Unknown slotName: ${slotName}, ignoring`, child, `Valid values are: ${validValues}`); // eslint-disable-line
+				}
+
 				return;
 			}
 
@@ -225,7 +303,7 @@ class UI5Element extends HTMLElement {
 			if (slotData.individualSlots) {
 				const nextIndex = (autoIncrementMap.get(slotName) || 0) + 1;
 				autoIncrementMap.set(slotName, nextIndex);
-				child._individualSlot = `${slotName}-${nextIndex}`;
+				(child as Record<string, any>)._individualSlot = `${slotName}-${nextIndex}`;
 			}
 
 			// Await for not-yet-defined custom elements
@@ -247,22 +325,26 @@ class UI5Element extends HTMLElement {
 				}
 			}
 
-			child = this.constructor.getMetadata().constructor.validateSlotValue(child, slotData);
+			child = (ctor.getMetadata().constructor as typeof UI5ElementMetadata).validateSlotValue(child, slotData);
 
 			// Listen for any invalidation on the child if invalidateOnChildChange is true or an object (ignore when false or not set)
-			if (child.isUI5Element && slotData.invalidateOnChildChange) {
-				child.attachInvalidate(this._getChildChangeListener(slotName));
+			if (instanceOfUI5Element(child) && slotData.invalidateOnChildChange) {
+				const childChangeListener = this._getChildChangeListener(slotName);
+
+				if (childChangeListener) {
+					child.attachInvalidate.call(child, childChangeListener);
+				}
 			}
 
 			// Listen for the slotchange event if the child is a slot itself
-			if (isSlot(child)) {
+			if (child instanceof HTMLSlotElement) {
 				this._attachSlotChange(child, slotName);
 			}
 
 			const propertyName = slotData.propertyName || slotName;
 
 			if (slottedChildrenMap.has(propertyName)) {
-				slottedChildrenMap.get(propertyName).push({ child, idx });
+				slottedChildrenMap.get(propertyName)!.push({ child, idx });
 			} else {
 				slottedChildrenMap.set(propertyName, [{ child, idx }]);
 			}
@@ -280,10 +362,10 @@ class UI5Element extends HTMLElement {
 		let invalidated = false;
 		for (const [slotName, slotData] of Object.entries(slotsMap)) { // eslint-disable-line
 			const propertyName = slotData.propertyName || slotName;
-			if (!arraysAreEqual(slotsCachedContentMap.get(propertyName), this._state[propertyName])) {
+			if (!arraysAreEqual(slotsCachedContentMap.get(propertyName)!, this._state[propertyName] as Array<SlotValue>)) {
 				_invalidate.call(this, {
 					type: "slot",
-					name: propertyNameToSlotMap.get(propertyName),
+					name: propertyNameToSlotMap.get(propertyName)!,
 					reason: "children",
 				});
 				invalidated = true;
@@ -305,16 +387,20 @@ class UI5Element extends HTMLElement {
 	 * Removes all children from the slot and detaches listeners, if any
 	 * @private
 	 */
-	_clearSlot(slotName, slotData) {
+	_clearSlot(slotName: string, slotData: Slot) {
 		const propertyName = slotData.propertyName || slotName;
-		const children = this._state[propertyName];
+		const children = this._state[propertyName] as Array<SlotValue>;
 
 		children.forEach(child => {
-			if (child && child.isUI5Element) {
-				child.detachInvalidate(this._getChildChangeListener(slotName));
+			if (instanceOfUI5Element(child)) {
+				const childChangeListener = this._getChildChangeListener(slotName);
+
+				if (childChangeListener) {
+					child.detachInvalidate.call(child, childChangeListener);
+				}
 			}
 
-			if (isSlot(child)) {
+			if (child instanceof HTMLSlotElement) {
 				this._detachSlotChange(child, slotName);
 			}
 		});
@@ -325,32 +411,32 @@ class UI5Element extends HTMLElement {
 	/**
 	 * Attach a callback that will be executed whenever the component is invalidated
 	 *
-	 * @param callback
+	 * @param {InvalidationInfo} callback
 	 * @public
 	 */
-	attachInvalidate(callback) {
+	attachInvalidate(callback: (param: InvalidationInfo) => void) {
 		this._eventProvider.attachEvent("invalidate", callback);
 	}
 
 	/**
 	 * Detach the callback that is executed whenever the component is invalidated
 	 *
-	 * @param callback
+	 * @param {InvalidationInfo} callback
 	 * @public
 	 */
-	detachInvalidate(callback) {
+	detachInvalidate(callback: (param: InvalidationInfo) => void) {
 		this._eventProvider.detachEvent("invalidate", callback);
 	}
 
 	/**
 	 * Callback that is executed whenever a monitored child changes its state
 	 *
-	 * @param slotName the slot in which a child was invalidated
-	 * @param childChangeInfo the changeInfo object for the child in the given slot
+	 * @param {sting} slotName the slot in which a child was invalidated
+	 * @param { ChangeInfo } childChangeInfo the changeInfo object for the child in the given slot
 	 * @private
 	 */
-	_onChildChange(slotName, childChangeInfo) {
-		if (!this.constructor.getMetadata().shouldInvalidateOnChildChange(slotName, childChangeInfo.type, childChangeInfo.name)) {
+	_onChildChange(slotName: string, childChangeInfo: ChangeInfo) {
+		if (!(this.constructor as typeof UI5Element).getMetadata().shouldInvalidateOnChildChange(slotName, childChangeInfo.type, childChangeInfo.name)) {
 			return;
 		}
 
@@ -368,44 +454,74 @@ class UI5Element extends HTMLElement {
 	 * Do not override this method in derivatives of UI5Element
 	 * @private
 	 */
-	attributeChangedCallback(name, oldValue, newValue) {
-		const properties = this.constructor.getMetadata().getProperties();
+	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
+		let newPropertyValue: PropertyValue;
+		if (this._doNotSyncAttributes.has(name)) { // This attribute is mutated internally, not by the user
+			return;
+		}
+
+		const properties = (this.constructor as typeof UI5Element).getMetadata().getProperties();
 		const realName = name.replace(/^ui5-/, "");
 		const nameInCamelCase = kebabToCamelCase(realName);
 		if (properties.hasOwnProperty(nameInCamelCase)) { // eslint-disable-line
-			const propertyTypeClass = properties[nameInCamelCase].type;
-			if (propertyTypeClass === Boolean) {
-				newValue = newValue !== null;
-			} else if (isDescendantOf(propertyTypeClass, DataType)) {
-				newValue = propertyTypeClass.attributeToProperty(newValue);
+			const propData = properties[nameInCamelCase];
+			const propertyType = propData.type;
+			let propertyValidator = propData.validator as typeof DataType;
+
+			if (propertyType && (propertyType as typeof DataType).isDataTypeClass) {
+				propertyValidator = propertyType as typeof DataType;
 			}
-			this[nameInCamelCase] = newValue;
+
+			if (propertyValidator) {
+				newPropertyValue = propertyValidator.attributeToProperty(newValue);
+			} else if (propertyType === Boolean) {
+				newPropertyValue = newValue !== null;
+			} else {
+				newPropertyValue = newValue as string;
+			}
+
+			(this as Record<string, any>)[nameInCamelCase] = newPropertyValue;
 		}
 	}
 
 	/**
 	 * @private
 	 */
-	_updateAttribute(name, newValue) {
-		if (!this.constructor.getMetadata().hasAttribute(name)) {
+	_updateAttribute(name: string, newValue: PropertyValue) {
+		const ctor = this.constructor as typeof UI5Element;
+
+		if (!ctor.getMetadata().hasAttribute(name)) {
 			return;
 		}
-		const properties = this.constructor.getMetadata().getProperties();
-		const propertyTypeClass = properties[name].type;
+		const properties = ctor.getMetadata().getProperties();
+		const propData = properties[name];
+		const propertyType = propData.type;
+		let propertyValidator = propData.validator as typeof DataType;
 		const attrName = camelToKebabCase(name);
 		const attrValue = this.getAttribute(attrName);
 
-		if (propertyTypeClass === Boolean) {
+		if (propertyType && (propertyType as typeof DataType).isDataTypeClass) {
+			propertyValidator = propertyType as typeof DataType;
+		}
+
+		if (propertyValidator) {
+			const newAttrValue = propertyValidator.propertyToAttribute(newValue);
+			if (newAttrValue === null) { // null means there must be no attribute for the current value of the property
+				this._doNotSyncAttributes.add(attrName); // skip the attributeChangedCallback call for this attribute
+				this.removeAttribute(attrName); // remove the attribute safely (will not trigger synchronization to the property value due to the above line)
+				this._doNotSyncAttributes.delete(attrName); // enable synchronization again for this attribute
+			} else {
+				this.setAttribute(attrName, newAttrValue);
+			}
+		} else if (propertyType === Boolean) {
 			if (newValue === true && attrValue === null) {
 				this.setAttribute(attrName, "");
 			} else if (newValue === false && attrValue !== null) {
 				this.removeAttribute(attrName);
 			}
-		} else if (isDescendantOf(propertyTypeClass, DataType)) {
-			this.setAttribute(attrName, propertyTypeClass.propertyToAttribute(newValue));
 		} else if (typeof newValue !== "object") {
 			if (attrValue !== newValue) {
-				this.setAttribute(attrName, newValue);
+				this.setAttribute(attrName, newValue as string);
 			}
 		} // else { return; } // old object handling
 	}
@@ -413,11 +529,11 @@ class UI5Element extends HTMLElement {
 	/**
 	 * @private
 	 */
-	_upgradeProperty(prop) {
-		if (this.hasOwnProperty(prop)) { // eslint-disable-line
-			const value = this[prop];
-			delete this[prop];
-			this[prop] = value;
+	_upgradeProperty(this: Record<string, any>, propertyName: string) {
+		if (this.hasOwnProperty(propertyName)) { // eslint-disable-line
+			const value = this[propertyName];
+			delete this[propertyName];
+			this[propertyName] = value;
 		}
 	}
 
@@ -425,25 +541,18 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	_upgradeAllProperties() {
-		const allProps = this.constructor.getMetadata().getPropertiesList();
-		allProps.forEach(this._upgradeProperty, this);
-	}
-
-	/**
-	 * @private
-	 */
-	_initializeState() {
-		this._state = { ...this.constructor.getMetadata().getInitialState() };
+		const allProps = (this.constructor as typeof UI5Element).getMetadata().getPropertiesList();
+		allProps.forEach(this._upgradeProperty.bind(this));
 	}
 
 	/**
 	 * Returns a singleton event listener for the "change" event of a child in a given slot
 	 *
 	 * @param slotName the name of the slot, where the child is
-	 * @returns {any}
+	 * @returns {ChildChangeListener}
 	 * @private
 	 */
-	_getChildChangeListener(slotName) {
+	_getChildChangeListener(slotName: string) {
 		if (!this._childChangeListeners.has(slotName)) {
 			this._childChangeListeners.set(slotName, this._onChildChange.bind(this, slotName));
 		}
@@ -454,27 +563,30 @@ class UI5Element extends HTMLElement {
 	 * Returns a singleton slotchange event listener that invalidates the component due to changes in the given slot
 	 *
 	 * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
-	 * @returns {any}
+	 * @returns {SlotChangeListener}
 	 * @private
 	 */
-	_getSlotChangeListener(slotName) {
+	_getSlotChangeListener(slotName: string) {
 		if (!this._slotChangeListeners.has(slotName)) {
 			this._slotChangeListeners.set(slotName, this._onSlotChange.bind(this, slotName));
 		}
-		return this._slotChangeListeners.get(slotName);
+		return this._slotChangeListeners.get(slotName)!;
 	}
 
 	/**
 	 * @private
 	 */
-	_attachSlotChange(child, slotName) {
-		child.addEventListener("slotchange", this._getSlotChangeListener(slotName));
+	_attachSlotChange(child: HTMLSlotElement, slotName: string) {
+		const slotChangeListener = this._getSlotChangeListener(slotName);
+		if (slotChangeListener) {
+			child.addEventListener("slotchange", slotChangeListener);
+		}
 	}
 
 	/**
 	 * @private
 	 */
-	_detachSlotChange(child, slotName) {
+	_detachSlotChange(child: HTMLSlotElement, slotName: string) {
 		child.removeEventListener("slotchange", this._getSlotChangeListener(slotName));
 	}
 
@@ -484,7 +596,7 @@ class UI5Element extends HTMLElement {
 	 * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
 	 * @private
 	 */
-	_onSlotChange(slotName) {
+	_onSlotChange(slotName: string) {
 		_invalidate.call(this, {
 			type: "slot",
 			name: slotName,
@@ -519,21 +631,20 @@ class UI5Element extends HTMLElement {
 	 *
 	 * @public
 	 */
-	onInvalidation(changeInfo) {}
+	onInvalidation(changeInfo: ChangeInfo) {} // eslint-disable-line
 
 	/**
 	 * Do not call this method directly, only intended to be called by js
 	 * @protected
 	 */
 	_render() {
-		const hasIndividualSlots = this.constructor.getMetadata().hasIndividualSlots();
+		const ctor = this.constructor as typeof UI5Element;
+		const hasIndividualSlots = ctor.getMetadata().hasIndividualSlots();
 
 		// suppress invalidation to prevent state changes scheduling another rendering
 		this._suppressInvalidation = true;
 
-		if (typeof this.onBeforeRendering === "function") {
-			this.onBeforeRendering();
-		}
+		this.onBeforeRendering();
 
 		// Intended for framework usage only. Currently ItemNavigation updates tab indexes after the component has updated its state but before the template is rendered
 		if (this._onComponentStateFinalized) {
@@ -557,7 +668,7 @@ class UI5Element extends HTMLElement {
 				}
 				res = `${res}: ${x.name}`;
 				if (x.type === "property") {
-					res = `${res} ${x.oldValue} => ${x.newValue}`;
+					res = `${res} ${JSON.stringify(x.oldValue)} => ${JSON.stringify(x.newValue)}`;
 				}
 
 				return res;
@@ -567,7 +678,7 @@ class UI5Element extends HTMLElement {
 		this._changedState = [];
 
 		// Update shadow root and static area item
-		if (this.constructor._needsShadowDOM()) {
+		if (ctor._needsShadowDOM()) {
 			updateShadowRoot(this);
 		}
 		if (this.staticAreaItem) {
@@ -580,9 +691,7 @@ class UI5Element extends HTMLElement {
 		}
 
 		// Call the onAfterRendering hook
-		if (typeof this.onAfterRendering === "function") {
-			this.onAfterRendering();
-		}
+		this.onAfterRendering();
 	}
 
 	/**
@@ -591,7 +700,7 @@ class UI5Element extends HTMLElement {
 	_assignIndividualSlotsToChildren() {
 		const domChildren = Array.from(this.children);
 
-		domChildren.forEach(child => {
+		domChildren.forEach((child: Record<string, any>) => {
 			if (child._individualSlot) {
 				child.setAttribute("slot", child._individualSlot);
 			}
@@ -607,25 +716,27 @@ class UI5Element extends HTMLElement {
 
 	/**
 	 * Returns the DOM Element inside the Shadow Root that corresponds to the opening tag in the UI5 Web Component's template
+	 * *Note:* For logical (abstract) elements (items, options, etc...), returns the part of the parent's DOM that represents this option
 	 * Use this method instead of "this.shadowRoot" to read the Shadow DOM, if ever necessary
+	 *
 	 * @public
 	 */
 	getDomRef() {
+		// If a component set _getRealDomRef to its children, use the return value of this function
+		if (typeof this._getRealDomRef === "function") {
+			return this._getRealDomRef();
+		}
+
 		if (!this.shadowRoot || this.shadowRoot.children.length === 0) {
 			return;
 		}
 
-		this._assertShadowRootStructure();
-
-		return this.shadowRoot.children.length === 1
-			? this.shadowRoot.children[0] : this.shadowRoot.children[1];
-	}
-
-	_assertShadowRootStructure() {
-		const expectedChildrenCount = document.adoptedStyleSheets || isLegacyBrowser() ? 1 : 2;
-		if (this.shadowRoot.children.length !== expectedChildrenCount) {
-			console.warn(`The shadow DOM for ${this.constructor.getMetadata().getTag()} does not have a top level element, the getDomRef() method might not work as expected`); // eslint-disable-line
+		const children = [...this.shadowRoot.children].filter(child => !["link", "style"].includes(child.localName));
+		if (children.length !== 1) {
+			console.warn(`The shadow DOM for ${(this.constructor as typeof UI5Element).getMetadata().getTag()} does not have a top level element, the getDomRef() method might not work as expected`); // eslint-disable-line
 		}
+
+		return children[0] as HTMLElement;
 	}
 
 	/**
@@ -636,7 +747,7 @@ class UI5Element extends HTMLElement {
 	getFocusDomRef() {
 		const domRef = this.getDomRef();
 		if (domRef) {
-			const focusRef = domRef.querySelector("[data-sap-focus-ref]");
+			const focusRef = domRef.querySelector("[data-sap-focus-ref]") as HTMLElement;
 			return focusRef || domRef;
 		}
 	}
@@ -651,28 +762,18 @@ class UI5Element extends HTMLElement {
 		return this.getFocusDomRef();
 	}
 
-	/**
-	 * Use this method in order to get a reference to an element in the shadow root of the web component or the static area item of the component
-	 * @public
-	 * @method
-	 * @param {String} refName Defines the name of the stable DOM ref
-	 */
-	getStableDomRef(refName) {
-		const staticAreaResult = this.staticAreaItem && this.staticAreaItem.getStableDomRef(refName);
-		return staticAreaResult || this.getDomRef().querySelector(`[data-ui5-stable=${refName}]`);
-	}
-
 	/**
 	 * Set the focus to the element, returned by "getFocusDomRef()" (marked by "data-sap-focus-ref")
+	 * @param {FocusOptions} focusOptions additional options for the focus
 	 * @public
 	 */
-	async focus() {
+	async focus(focusOptions?: FocusOptions) {
 		await this._waitForDomRef();
 
 		const focusDomRef = this.getFocusDomRef();
 
 		if (focusDomRef && typeof focusDomRef.focus === "function") {
-			focusDomRef.focus();
+			focusDomRef.focus(focusOptions);
 		}
 	}
 
@@ -685,7 +786,7 @@ class UI5Element extends HTMLElement {
 	 * @param bubbles - true, if the event bubbles
 	 * @returns {boolean} false, if the event was cancelled (preventDefault called), true otherwise
 	 */
-	fireEvent(name, data, cancelable = false, bubbles = true) {
+	fireEvent<T>(name: string, data?: T, cancelable = false, bubbles = true) {
 		const eventResult = this._fireEvent(name, data, cancelable, bubbles);
 		const camelCaseEventName = kebabToCamelCase(name);
 
@@ -696,8 +797,8 @@ class UI5Element extends HTMLElement {
 		return eventResult;
 	}
 
-	_fireEvent(name, data, cancelable = false, bubbles = true) {
-		const noConflictEvent = new CustomEvent(`ui5-${name}`, {
+	_fireEvent<T>(name: string, data?: T, cancelable = false, bubbles = true) {
+		const noConflictEvent = new CustomEvent<T>(`ui5-${name}`, {
 			detail: data,
 			composed: false,
 			bubbles,
@@ -711,7 +812,7 @@ class UI5Element extends HTMLElement {
 			return noConflictEventResult;
 		}
 
-		const normalEvent = new CustomEvent(name, {
+		const normalEvent = new CustomEvent<T>(name, {
 			detail: data,
 			composed: false,
 			bubbles,
@@ -730,8 +831,8 @@ class UI5Element extends HTMLElement {
 	 * Useful when there are transitive slots in nested component scenarios and you don't want to get a list of the slots, but rather of their content.
 	 * @public
 	 */
-	getSlottedNodes(slotName) {
-		return getSlottedElementsList(this[slotName]);
+	getSlottedNodes(slotName: string) {
+		return getSlottedNodesList((this as unknown as Record<string, Array<SlotValue>>)[slotName]);
 	}
 
 	/**
@@ -742,7 +843,7 @@ class UI5Element extends HTMLElement {
 	 * @returns {String|undefined}
 	 */
 	get effectiveDir() {
-		markAsRtlAware(this.constructor); // if a UI5 Element calls this method, it's considered to be rtl-aware
+		markAsRtlAware(this.constructor as typeof UI5Element); // if a UI5 Element calls this method, it's considered to be rtl-aware
 		return getEffectiveDir(this);
 	}
 
@@ -755,6 +856,10 @@ class UI5Element extends HTMLElement {
 		return true;
 	}
 
+	get classes(): ClassMap {
+		return {};
+	}
+
 	/**
 	 * Do not override this method in derivatives of UI5Element, use metadata properties instead
 	 * @private
@@ -781,7 +886,7 @@ class UI5Element extends HTMLElement {
 	 * @public
 	 */
 	getStaticAreaItemDomRef() {
-		if (!this.constructor._needsStaticArea()) {
+		if (!(this.constructor as typeof UI5Element)._needsStaticArea()) {
 			throw new Error("This component does not use the static area");
 		}
 
@@ -827,7 +932,7 @@ class UI5Element extends HTMLElement {
 			}
 
 			Object.defineProperty(proto, prop, {
-				get() {
+				get(this: UI5Element) {
 					if (this._state[prop] !== undefined) {
 						return this._state[prop];
 					}
@@ -844,15 +949,25 @@ class UI5Element extends HTMLElement {
 						return propDefaultValue;
 					}
 				},
-				set(value) {
+
+				set(this: UI5Element, value: PropertyValue) {
 					let isDifferent;
-					value = this.constructor.getMetadata().constructor.validatePropertyValue(value, propData);
+					const ctor = this.constructor as typeof UI5Element;
+					const metadataCtor = ctor.getMetadata().constructor as typeof UI5ElementMetadata;
 
+					value = metadataCtor.validatePropertyValue(value, propData);
+					const propertyType = propData.type;
+					let propertyValidator = propData.validator as typeof DataType;
 					const oldState = this._state[prop];
-					if (propData.multiple && propData.compareValues) {
+
+					if (propertyType && (propertyType as typeof DataType).isDataTypeClass) {
+						propertyValidator = propertyType as typeof DataType;
+					}
+
+					if (propertyValidator) {
+						isDifferent = !propertyValidator.valuesAreEqual(oldState, value);
+					} else if (Array.isArray(oldState) && Array.isArray(value) && propData.multiple && propData.compareValues) { // compareValues is added for IE, test if needed now
 						isDifferent = !arraysAreEqual(oldState, value);
-					} else if (isDescendantOf(propData.type, DataType)) {
-						isDifferent = !propData.type.valuesAreEqual(oldState, value);
 					} else {
 						isDifferent = oldState !== value;
 					}
@@ -881,7 +996,7 @@ class UI5Element extends HTMLElement {
 
 				const propertyName = slotData.propertyName || slotName;
 				Object.defineProperty(proto, propertyName, {
-					get() {
+					get(this: UI5Element) {
 						if (this._state[propertyName] !== undefined) {
 							return this._state[propertyName];
 						}
@@ -900,14 +1015,22 @@ class UI5Element extends HTMLElement {
 	 * @protected
 	 */
 	static get metadata() {
-		return {};
+		return metadata;
+	}
+
+	/**
+	 * Sets a new metadata object for this UI5 Web Component Class
+	 * @protected
+	 */
+	static set metadata(newMetadata) {
+		metadata = newMetadata;
 	}
 
 	/**
 	 * Returns the CSS for this UI5 Web Component Class
 	 * @protected
 	 */
-	static get styles() {
+	static get styles(): ComponentStylesData {
 		return "";
 	}
 
@@ -915,7 +1038,7 @@ class UI5Element extends HTMLElement {
 	 * Returns the Static Area CSS for this UI5 Web Component Class
 	 * @protected
 	 */
-	static get staticAreaStyles() {
+	static get staticAreaStyles(): ComponentStylesData {
 		return "";
 	}
 
@@ -926,7 +1049,7 @@ class UI5Element extends HTMLElement {
 	 *
 	 * @protected
 	 */
-	static get dependencies() {
+	static get dependencies(): Array<typeof UI5Element> {
 		return [];
 	}
 
@@ -935,21 +1058,21 @@ class UI5Element extends HTMLElement {
 	 *
 	 * @public
 	 */
-	static getUniqueDependencies() {
+	static getUniqueDependencies(this: typeof UI5Element) {
 		if (!uniqueDependenciesCache.has(this)) {
 			const filtered = this.dependencies.filter((dep, index, deps) => deps.indexOf(dep) === index);
 			uniqueDependenciesCache.set(this, filtered);
 		}
 
-		return uniqueDependenciesCache.get(this);
+		return uniqueDependenciesCache.get(this) || [];
 	}
 
 	/**
 	 * Returns a promise that resolves whenever all dependencies for this UI5 Web Component have resolved
 	 *
-	 * @returns {Promise<any[]>}
+	 * @returns {Promise}
 	 */
-	static whenDependenciesDefined() {
+	static whenDependenciesDefined(): Promise<Array<typeof UI5Element>> {
 		return Promise.all(this.getUniqueDependencies().map(dep => dep.define()));
 	}
 
@@ -977,7 +1100,6 @@ class UI5Element extends HTMLElement {
 		]);
 
 		const tag = this.getMetadata().getTag();
-		const altTag = this.getMetadata().getAltTag();
 
 		const definedLocally = isTagRegistered(tag);
 		const definedGlobally = customElements.get(tag);
@@ -987,14 +1109,8 @@ class UI5Element extends HTMLElement {
 		} else if (!definedGlobally) {
 			this._generateAccessors();
 			registerTag(tag);
-			window.customElements.define(tag, this);
-
-			if (altTag && !customElements.get(altTag)) {
-				registerTag(altTag);
-				window.customElements.define(altTag, getClassCopy(this, () => {
-					console.log(`The ${altTag} tag is deprecated and will be removed in the next release, please use ${tag} instead.`); // eslint-disable-line
-				}));
-			}
+			window.customElements.define(tag, this as unknown as CustomElementConstructor);
+			preloadLinks(this);
 		}
 		return this;
 	}
@@ -1010,17 +1126,31 @@ class UI5Element extends HTMLElement {
 			return this._metadata;
 		}
 
-		const metadataObjects = [this.metadata];
+		const effectiveMetadata = Object.keys(this.metadata).length ? this.metadata : this.decoratorMetadata;
+		const metadataObjects = [effectiveMetadata];
 		let klass = this; // eslint-disable-line
 		while (klass !== UI5Element) {
 			klass = Object.getPrototypeOf(klass);
-			metadataObjects.unshift(klass.metadata);
+			const effectiveKlassMetadata = Object.keys(klass.metadata).length ? klass.metadata : klass.decoratorMetadata;
+			metadataObjects.unshift(effectiveKlassMetadata);
 		}
-		const mergedMetadata = merge({}, ...metadataObjects);
+		const mergedMetadata = merge({}, ...metadataObjects) as Metadata;
 
 		this._metadata = new UI5ElementMetadata(mergedMetadata);
 		return this._metadata;
 	}
+
+	static decoratorMetadata: Metadata = {};
 }
 
+/**
+ * Always use duck-typing to cover all runtimes on the page.
+ * @returns {boolean}
+ */
+const instanceOfUI5Element = (object: any): object is UI5Element => {
+	return "isUI5Element" in object;
+};
+
 export default UI5Element;
+export { instanceOfUI5Element };
+export type { ChangeInfo };