@ui5/webcomponents-base 0.0.0-0fcda382e → 0.0.0-11d529e8a

package/dist/UI5Element.js

@@ -1,29 +1,51 @@
 import merge from "./thirdparty/merge.js";
-import boot from "./boot.js";
+import { boot } from "./Boot.js";
 import UI5ElementMetadata from "./UI5ElementMetadata.js";
+import EventProvider from "./EventProvider.js";
+import getSingletonElementInstance from "./util/getSingletonElementInstance.js";
 import StaticAreaItem from "./StaticAreaItem.js";
-import RenderScheduler from "./RenderScheduler.js";
-import { registerTag, isTagRegistered } from "./CustomElementsRegistry.js";
-import DOMObserver from "./compatibility/DOMObserver.js";
+import updateShadowRoot from "./updateShadowRoot.js";
+import { renderDeferred, renderImmediately, cancelRender } from "./Render.js";
+import { registerTag, isTagRegistered, recordTagRegistrationFailure } from "./CustomElementsRegistry.js";
+import { observeDOMNode, unobserveDOMNode } from "./DOMObserver.js";
 import { skipOriginalEvent } from "./config/NoConflict.js";
-import getConstructableStyle from "./theming/getConstructableStyle.js";
-import createComponentStyleTag from "./theming/createComponentStyleTag.js";
-import getEffectiveStyle from "./theming/getEffectiveStyle.js";
-import Integer from "./types/Integer.js";
+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";
-
-const metadata = {
-	events: {
-		_propertyChange: {},
-	},
-};
+import isDescendantOf from "./util/isDescendantOf.js";
+import { isSlot, getSlotName, getSlottedElementsList } 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";
 
 let autoId = 0;
 
 const elementTimeouts = new Map();
+const uniqueDependenciesCache = new Map();
+
+/**
+ * Triggers re-rendering of a UI5Element instance due to state change.
+ *
+ * @param  changeInfo An object with information about the change that caused invalidation.
+ * @private
+ */
+function _invalidate(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) {
+		return;
+	}
+
+	// Call the onInvalidation hook
+	this.onInvalidation(changeInfo);
+
+	this._changedState.push(changeInfo);
+	renderDeferred(this);
+	this._eventProvider.fireEvent("invalidate", { ...changeInfo, target: this });
+}
 
-const GLOBAL_CONTENT_DENSITY_CSS_VAR = "--_ui5_content_density";
 /**
  * Base class for all UI5 Web Components
  *
@@ -37,56 +59,40 @@ const GLOBAL_CONTENT_DENSITY_CSS_VAR = "--_ui5_content_density";
 class UI5Element extends HTMLElement {
 	constructor() {
 		super();
-		this._generateId();
-		this._initializeState();
-		this._upgradeAllProperties();
-		this._initializeContainers();
-		this._upToDate = false;
 
+		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
+		this._fullyConnected = false; // A flag telling whether the UI5Element's onEnterDOM hook was called (since it's possible to have the element removed from DOM before that)
+		this._childChangeListeners = new Map(); // used to store lazy listeners per slot for the child change event of every child inside that slot
+		this._slotChangeListeners = new Map(); // used to store lazy listeners per slot for the slotchange event of all slot children inside that slot
+		this._eventProvider = new EventProvider(); // used by parent components for listening to changes to child components
 		let deferredResolve;
 		this._domRefReadyPromise = new Promise(resolve => {
 			deferredResolve = resolve;
 		});
 		this._domRefReadyPromise._deferredResolve = deferredResolve;
 
-		this._monitoredChildProps = new Map();
-		this._firePropertyChange = false;
-	}
+		this._initializeState();
+		this._upgradeAllProperties();
 
-	/**
-	 * @private
-	 */
-	_generateId() {
-		this._id = `ui5wc_${++autoId}`;
+		if (this.constructor._needsShadowDOM()) {
+			this.attachShadow({ mode: "open" });
+		}
 	}
 
 	/**
-	 * @private
+	 * Returns a unique ID for this UI5 Element
+	 *
+	 * @deprecated - This property is not guaranteed in future releases
+	 * @protected
 	 */
-	_initializeContainers() {
-		const needsShadowDOM = this.constructor._needsShadowDOM();
-		const needsStaticArea = this.constructor._needsStaticArea();
-
-		// Init Shadow Root
-		if (needsShadowDOM) {
-			this.attachShadow({ mode: "open" });
-
-			// IE11, Edge
-			if (window.ShadyDOM) {
-				createComponentStyleTag(this.constructor);
-			}
-
-			// Chrome
-			if (document.adoptedStyleSheets) {
-				const style = getConstructableStyle(this.constructor);
-				this.shadowRoot.adoptedStyleSheets = [style];
-			}
+	get _id() {
+		if (!this.__id) {
+			this.__id = `ui5wc_${++autoId}`;
 		}
 
-		// Init StaticAreaItem only if needed
-		if (needsStaticArea) {
-			this.staticAreaItem = new StaticAreaItem(this);
-		}
+		return this.__id;
 	}
 
 	/**
@@ -94,26 +100,27 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	async connectedCallback() {
-		const needsShadowDOM = this.constructor._needsShadowDOM();
+		this.setAttribute(this.constructor.getMetadata().getPureTag(), "");
+
 		const slotsAreManaged = this.constructor.getMetadata().slotsAreManaged();
 
-		// Render the Shadow DOM
-		if (needsShadowDOM) {
-			if (slotsAreManaged) {
-				// always register the observer before yielding control to the main thread (await)
-				this._startObservingDOMChildren();
-				await this._processChildren();
-			}
+		this._inDOM = true;
 
-			if (!this.shadowRoot) { // Workaround for Firefox74 bug
-				await Promise.resolve();
-			}
+		if (slotsAreManaged) {
+			// always register the observer before yielding control to the main thread (await)
+			this._startObservingDOMChildren();
+			await this._processChildren();
+		}
 
-			await RenderScheduler.renderImmediately(this);
-			this._domRefReadyPromise._deferredResolve();
-			if (typeof this.onEnterDOM === "function") {
-				this.onEnterDOM();
-			}
+		if (!this._inDOM) { // Component removed from DOM while _processChildren was running
+			return;
+		}
+
+		renderImmediately(this);
+		this._domRefReadyPromise._deferredResolve();
+		this._fullyConnected = true;
+		if (typeof this.onEnterDOM === "function") {
+			this.onEnterDOM();
 		}
 	}
 
@@ -122,23 +129,26 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	disconnectedCallback() {
-		const needsShadowDOM = this.constructor._needsShadowDOM();
-		const needsStaticArea = this.constructor._needsStaticArea();
 		const slotsAreManaged = this.constructor.getMetadata().slotsAreManaged();
 
-		if (needsShadowDOM) {
-			if (slotsAreManaged) {
-				this._stopObservingDOMChildren();
-			}
+		this._inDOM = false;
+
+		if (slotsAreManaged) {
+			this._stopObservingDOMChildren();
+		}
 
+		if (this._fullyConnected) {
 			if (typeof this.onExitDOM === "function") {
 				this.onExitDOM();
 			}
+			this._fullyConnected = false;
 		}
 
-		if (needsStaticArea) {
-			this.staticAreaItem._removeFragmentFromStaticArea();
+		if (this.staticAreaItem && this.staticAreaItem.parentElement) {
+			this.staticAreaItem.parentElement.removeChild(this.staticAreaItem);
 		}
+
+		cancelRender(this);
 	}
 
 	/**
@@ -154,16 +164,16 @@ class UI5Element extends HTMLElement {
 		const mutationObserverOptions = {
 			childList: true,
 			subtree: canSlotText,
-			characterData: true,
+			characterData: canSlotText,
 		};
-		DOMObserver.observeDOMNode(this, this._processChildren.bind(this), mutationObserverOptions);
+		observeDOMNode(this, this._processChildren.bind(this), mutationObserverOptions);
 	}
 
 	/**
 	 * @private
 	 */
 	_stopObservingDOMChildren() {
-		DOMObserver.unobserveDOMNode(this);
+		unobserveDOMNode(this);
 	}
 
 	/**
@@ -185,8 +195,14 @@ class UI5Element extends HTMLElement {
 		const canSlotText = this.constructor.getMetadata().canSlotText();
 		const domChildren = Array.from(canSlotText ? this.childNodes : this.children);
 
-		// Init the _state object based on the supported slots
+		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
+
+		// 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]]);
 			this._clearSlot(slotName, slotData);
 		}
 
@@ -195,7 +211,7 @@ class UI5Element extends HTMLElement {
 
 		const allChildrenUpgraded = domChildren.map(async (child, idx) => {
 			// Determine the type of the child (mainly by the slot attribute)
-			const slotName = this.constructor._getSlotName(child);
+			const slotName = getSlotName(child);
 			const slotData = slotsMap[slotName];
 
 			// Check if the slotName is supported
@@ -233,8 +249,14 @@ class UI5Element extends HTMLElement {
 
 			child = this.constructor.getMetadata().constructor.validateSlotValue(child, slotData);
 
-			if (child.isUI5Element && slotData.listenFor) {
-				this._attachChildPropertyUpdated(child, slotData.listenFor);
+			// 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));
+			}
+
+			// Listen for the slotchange event if the child is a slot itself
+			if (isSlot(child)) {
+				this._attachSlotChange(child, slotName);
 			}
 
 			const propertyName = slotData.propertyName || slotName;
@@ -250,10 +272,33 @@ class UI5Element extends HTMLElement {
 
 		// Distribute the child in the _state object, keeping the Light DOM order,
 		// not the order elements are defined.
-		slottedChildrenMap.forEach((children, slot) => {
-			this._state[slot] = children.sort((a, b) => a.idx - b.idx).map(_ => _.child);
+		slottedChildrenMap.forEach((children, propertyName) => {
+			this._state[propertyName] = children.sort((a, b) => a.idx - b.idx).map(_ => _.child);
 		});
-		this._invalidate("slots");
+
+		// Compare the content of each slot with the cached values and invalidate for the ones that changed
+		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])) {
+				_invalidate.call(this, {
+					type: "slot",
+					name: propertyNameToSlotMap.get(propertyName),
+					reason: "children",
+				});
+				invalidated = true;
+			}
+		}
+
+		// If none of the slots had an invalidation due to changes to immediate children,
+		// the change is considered to be text content of the default slot
+		if (!invalidated) {
+			_invalidate.call(this, {
+				type: "slot",
+				name: "default",
+				reason: "textcontent",
+			});
+		}
 	}
 
 	/**
@@ -262,20 +307,61 @@ class UI5Element extends HTMLElement {
 	 */
 	_clearSlot(slotName, slotData) {
 		const propertyName = slotData.propertyName || slotName;
-
-		let children = this._state[propertyName];
-		if (!Array.isArray(children)) {
-			children = [children];
-		}
+		const children = this._state[propertyName];
 
 		children.forEach(child => {
 			if (child && child.isUI5Element) {
-				this._detachChildPropertyUpdated(child);
+				child.detachInvalidate(this._getChildChangeListener(slotName));
+			}
+
+			if (isSlot(child)) {
+				this._detachSlotChange(child, slotName);
 			}
 		});
 
 		this._state[propertyName] = [];
-		this._invalidate(propertyName, []);
+	}
+
+	/**
+	 * Attach a callback that will be executed whenever the component is invalidated
+	 *
+	 * @param callback
+	 * @public
+	 */
+	attachInvalidate(callback) {
+		this._eventProvider.attachEvent("invalidate", callback);
+	}
+
+	/**
+	 * Detach the callback that is executed whenever the component is invalidated
+	 *
+	 * @param callback
+	 * @public
+	 */
+	detachInvalidate(callback) {
+		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
+	 * @private
+	 */
+	_onChildChange(slotName, childChangeInfo) {
+		if (!this.constructor.getMetadata().shouldInvalidateOnChildChange(slotName, childChangeInfo.type, childChangeInfo.name)) {
+			return;
+		}
+
+		// The component should be invalidated as this type of change on the child is listened for
+		// However, no matter what changed on the child (property/slot), the invalidation is registered as "type=slot" for the component itself
+		_invalidate.call(this, {
+			type: "slot",
+			name: slotName,
+			reason: "childchange",
+			child: childChangeInfo.target,
+		});
 	}
 
 	/**
@@ -290,9 +376,8 @@ class UI5Element extends HTMLElement {
 			const propertyTypeClass = properties[nameInCamelCase].type;
 			if (propertyTypeClass === Boolean) {
 				newValue = newValue !== null;
-			}
-			if (propertyTypeClass === Integer) {
-				newValue = parseInt(newValue);
+			} else if (isDescendantOf(propertyTypeClass, DataType)) {
+				newValue = propertyTypeClass.attributeToProperty(newValue);
 			}
 			this[nameInCamelCase] = newValue;
 		}
@@ -305,22 +390,24 @@ class UI5Element extends HTMLElement {
 		if (!this.constructor.getMetadata().hasAttribute(name)) {
 			return;
 		}
-
-		if (typeof newValue === "object") {
-			return;
-		}
-
+		const properties = this.constructor.getMetadata().getProperties();
+		const propertyTypeClass = properties[name].type;
 		const attrName = camelToKebabCase(name);
 		const attrValue = this.getAttribute(attrName);
-		if (typeof newValue === "boolean") {
+
+		if (propertyTypeClass === Boolean) {
 			if (newValue === true && attrValue === null) {
 				this.setAttribute(attrName, "");
 			} else if (newValue === false && attrValue !== null) {
 				this.removeAttribute(attrName);
 			}
-		} else if (attrValue !== newValue) {
-			this.setAttribute(attrName, newValue);
-		}
+		} else if (isDescendantOf(propertyTypeClass, DataType)) {
+			this.setAttribute(attrName, propertyTypeClass.propertyToAttribute(newValue));
+		} else if (typeof newValue !== "object") {
+			if (attrValue !== newValue) {
+				this.setAttribute(attrName, newValue);
+			}
+		} // else { return; } // old object handling
 	}
 
 	/**
@@ -346,101 +433,96 @@ class UI5Element extends HTMLElement {
 	 * @private
 	 */
 	_initializeState() {
-		const defaultState = this.constructor._getDefaultState();
-		this._state = Object.assign({}, defaultState);
+		this._state = { ...this.constructor.getMetadata().getInitialState() };
 	}
 
 	/**
+	 * 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}
 	 * @private
 	 */
-	_attachChildPropertyUpdated(child, listenFor) {
-		const childMetadata = child.constructor.getMetadata(),
-			slotName = this.constructor._getSlotName(child), // all slotted children have the same configuration
-			childProperties = childMetadata.getProperties();
-
-		let observedProps = [],
-			notObservedProps = [];
-
-		if (Array.isArray(listenFor)) {
-			observedProps = listenFor;
-		} else {
-			observedProps = Array.isArray(listenFor.props) ? listenFor.props : Object.keys(childProperties);
-			notObservedProps = Array.isArray(listenFor.exclude) ? listenFor.exclude : [];
-		}
-
-		if (!this._monitoredChildProps.has(slotName)) {
-			this._monitoredChildProps.set(slotName, { observedProps, notObservedProps });
+	_getChildChangeListener(slotName) {
+		if (!this._childChangeListeners.has(slotName)) {
+			this._childChangeListeners.set(slotName, this._onChildChange.bind(this, slotName));
 		}
-
-		child.addEventListener("_propertyChange", this._invalidateParentOnPropertyUpdate);
-		child._firePropertyChange = true;
+		return this._childChangeListeners.get(slotName);
 	}
 
 	/**
+	 * 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}
 	 * @private
 	 */
-	_detachChildPropertyUpdated(child) {
-		child.removeEventListener("_propertyChange", this._invalidateParentOnPropertyUpdate);
-		child._firePropertyChange = false;
+	_getSlotChangeListener(slotName) {
+		if (!this._slotChangeListeners.has(slotName)) {
+			this._slotChangeListeners.set(slotName, this._onSlotChange.bind(this, slotName));
+		}
+		return this._slotChangeListeners.get(slotName);
 	}
 
 	/**
 	 * @private
 	 */
-	_propertyChange(name, value) {
-		this._updateAttribute(name, value);
-
-		if (this._firePropertyChange) {
-			this.dispatchEvent(new CustomEvent("_propertyChange", {
-				detail: { name, newValue: value },
-				composed: false,
-				bubbles: true,
-			}));
-		}
+	_attachSlotChange(child, slotName) {
+		child.addEventListener("slotchange", this._getSlotChangeListener(slotName));
 	}
 
 	/**
 	 * @private
 	 */
-	_invalidateParentOnPropertyUpdate(prop) {
-		// The web component to be invalidated
-		const parentNode = this.parentNode;
-		if (!parentNode) {
-			return;
-		}
-
-		const slotName = parentNode.constructor._getSlotName(this);
-		const propsMetadata = parentNode._monitoredChildProps.get(slotName);
-
-		if (!propsMetadata) {
-			return;
-		}
-		const { observedProps, notObservedProps } = propsMetadata;
-
-		if (observedProps.includes(prop.detail.name) && !notObservedProps.includes(prop.detail.name)) {
-			parentNode._invalidate("_parent_", this);
-		}
+	_detachSlotChange(child, slotName) {
+		child.removeEventListener("slotchange", this._getSlotChangeListener(slotName));
 	}
 
 	/**
-	 * Asynchronously re-renders an already rendered web component
+	 * Whenever a slot element is slotted inside a UI5 Web Component, its slotchange event invalidates the component
+	 *
+	 * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
 	 * @private
 	 */
-	_invalidate() {
-		if (!this._upToDate) {
-			// console.log("already invalidated", this, ...arguments);
-			return;
-		}
-
-		if (this.getDomRef() && !this._suppressInvalidation) {
-			this._upToDate = false;
-			// console.log("INVAL", this, ...arguments);
-			RenderScheduler.renderDeferred(this);
-		}
+	_onSlotChange(slotName) {
+		_invalidate.call(this, {
+			type: "slot",
+			name: slotName,
+			reason: "slotchange",
+		});
 	}
 
 	/**
-	 * Do not call this method directly, only intended to be called by RenderScheduler.js
+	 * A callback that is executed each time an already rendered component is invalidated (scheduled for re-rendering)
+	 *
+	 * @param  changeInfo An object with information about the change that caused invalidation.
+	 * The object can have the following properties:
+	 *  - type: (property|slot) tells what caused the invalidation
+	 *   1) property: a property value was changed either directly or as a result of changing the corresponding attribute
+	 *   2) slot: a slotted node(nodes) changed in one of several ways (see "reason")
+	 *
+	 *  - name: the name of the property or slot that caused the invalidation
+	 *
+	 *  - reason: (children|textcontent|childchange|slotchange) relevant only for type="slot" only and tells exactly what changed in the slot
+	 *   1) children: immediate children (HTML elements or text nodes) were added, removed or reordered in the slot
+	 *   2) textcontent: text nodes in the slot changed value (or nested text nodes were added or changed value). Can only trigger for slots of "type: Node"
+	 *   3) slotchange: a slot element, slotted inside that slot had its "slotchange" event listener called. This practically means that transitively slotted children changed.
+	 *      Can only trigger if the child of a slot is a slot element itself.
+	 *   4) childchange: indicates that a UI5Element child in that slot was invalidated and in turn invalidated the component.
+	 *      Can only trigger for slots with "invalidateOnChildChange" metadata descriptor
+	 *
+	 *  - newValue: the new value of the property (for type="property" only)
+	 *
+	 *  - oldValue: the old value of the property (for type="property" only)
+	 *
+	 *  - child the child that was changed (for type="slot" and reason="childchange" only)
+	 *
+	 * @public
+	 */
+	onInvalidation(changeInfo) {}
+
+	/**
+	 * Do not call this method directly, only intended to be called by js
 	 * @protected
 	 */
 	_render() {
@@ -459,15 +541,37 @@ class UI5Element extends HTMLElement {
 		}
 
 		// resume normal invalidation handling
-		delete this._suppressInvalidation;
+		this._suppressInvalidation = false;
 
 		// Update the shadow root with the render result
-		// console.log(this.getDomRef() ? "RE-RENDER" : "FIRST RENDER", this);
-		this._upToDate = true;
-		this._updateShadowRoot();
+		/*
+		if (this._changedState.length) {
+			let element = this.localName;
+			if (this.id) {
+				element = `${element}#${this.id}`;
+			}
+			console.log("Re-rendering:", element, this._changedState.map(x => { // eslint-disable-line
+				let res = `${x.type}`;
+				if (x.reason) {
+					res = `${res}(${x.reason})`;
+				}
+				res = `${res}: ${x.name}`;
+				if (x.type === "property") {
+					res = `${res} ${x.oldValue} => ${x.newValue}`;
+				}
+
+				return res;
+			}));
+		}
+		*/
+		this._changedState = [];
 
-		if (this._shouldUpdateFragment()) {
-			this.staticAreaItem._updateFragment(this);
+		// Update shadow root and static area item
+		if (this.constructor._needsShadowDOM()) {
+			updateShadowRoot(this);
+		}
+		if (this.staticAreaItem) {
+			this.staticAreaItem.update();
 		}
 
 		// Safari requires that children get the slot attribute only after the slot tags have been rendered in the shadow DOM
@@ -481,23 +585,6 @@ class UI5Element extends HTMLElement {
 		}
 	}
 
-	/**
-	 * @private
-	 */
-	_updateShadowRoot() {
-		if (!this.constructor._needsShadowDOM()) {
-			return;
-		}
-
-		let styleToPrepend;
-		const renderResult = this.constructor.template(this);
-
-		if (!document.adoptedStyleSheets && !window.ShadyDOM) {
-			styleToPrepend = getEffectiveStyle(this.constructor);
-		}
-		this.constructor.render(renderResult, this.shadowRoot, styleToPrepend, { eventContext: this });
-	}
-
 	/**
 	 * @private
 	 */
@@ -528,10 +615,19 @@ class UI5Element extends HTMLElement {
 			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
+		}
+	}
+
 	/**
 	 * Returns the DOM Element marked with "data-sap-focus-ref" inside the template.
 	 * This is the element that will receive the focus by default.
@@ -545,6 +641,27 @@ class UI5Element extends HTMLElement {
 		}
 	}
 
+	/**
+	 * Waits for dom ref and then returns the DOM Element marked with "data-sap-focus-ref" inside the template.
+	 * This is the element that will receive the focus by default.
+	 * @public
+	 */
+	async getFocusDomRefAsync() {
+		await this._waitForDomRef();
+		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")
 	 * @public
@@ -565,37 +682,47 @@ class UI5Element extends HTMLElement {
 	 * @param name - name of the event
 	 * @param data - additional data for the event
 	 * @param cancelable - true, if the user can call preventDefault on the event object
+	 * @param bubbles - true, if the event bubbles
 	 * @returns {boolean} false, if the event was cancelled (preventDefault called), true otherwise
 	 */
-	fireEvent(name, data, cancelable) {
-		let compatEventResult = true; // Initialized to true, because if the event is not fired at all, it should be considered "not-prevented"
+	fireEvent(name, data, cancelable = false, bubbles = true) {
+		const eventResult = this._fireEvent(name, data, cancelable, bubbles);
+		const camelCaseEventName = kebabToCamelCase(name);
+
+		if (camelCaseEventName !== name) {
+			return eventResult && this._fireEvent(camelCaseEventName, data, cancelable);
+		}
 
+		return eventResult;
+	}
+
+	_fireEvent(name, data, cancelable = false, bubbles = true) {
 		const noConflictEvent = new CustomEvent(`ui5-${name}`, {
 			detail: data,
 			composed: false,
-			bubbles: true,
+			bubbles,
 			cancelable,
 		});
 
-		// This will be false if the compat event is prevented
-		compatEventResult = this.dispatchEvent(noConflictEvent);
+		// This will be false if the no-conflict event is prevented
+		const noConflictEventResult = this.dispatchEvent(noConflictEvent);
 
 		if (skipOriginalEvent(name)) {
-			return compatEventResult;
+			return noConflictEventResult;
 		}
 
-		const customEvent = new CustomEvent(name, {
+		const normalEvent = new CustomEvent(name, {
 			detail: data,
 			composed: false,
-			bubbles: true,
+			bubbles,
 			cancelable,
 		});
 
 		// This will be false if the normal event is prevented
-		const normalEventResult = this.dispatchEvent(customEvent);
+		const normalEventResult = this.dispatchEvent(normalEvent);
 
 		// Return false if any of the two events was prevented (its result was false).
-		return normalEventResult && compatEventResult;
+		return normalEventResult && noConflictEventResult;
 	}
 
 	/**
@@ -604,24 +731,19 @@ class UI5Element extends HTMLElement {
 	 * @public
 	 */
 	getSlottedNodes(slotName) {
-		const reducer = (acc, curr) => {
-			if (curr.localName !== "slot") {
-				return acc.concat([curr]);
-			}
-			return acc.concat(curr.assignedNodes({ flatten: true }).filter(item => item instanceof HTMLElement));
-		};
-
-		return this[slotName].reduce(reducer, []);
-	}
-
-	get isCompact() {
-		return getComputedStyle(this).getPropertyValue(GLOBAL_CONTENT_DENSITY_CSS_VAR) === "compact";
+		return getSlottedElementsList(this[slotName]);
 	}
 
-	updateStaticAreaItemContentDensity() {
-		if (this.staticAreaItem) {
-			this.staticAreaItem._updateContentDensity(this.isCompact);
-		}
+	/**
+	 * Determines whether the component should be rendered in RTL mode or not.
+	 * Returns: "rtl", "ltr" or undefined
+	 *
+	 * @public
+	 * @returns {String|undefined}
+	 */
+	get effectiveDir() {
+		markAsRtlAware(this.constructor); // if a UI5 Element calls this method, it's considered to be rtl-aware
+		return getEffectiveDir(this);
 	}
 
 	/**
@@ -641,26 +763,6 @@ class UI5Element extends HTMLElement {
 		return this.getMetadata().getAttributesList();
 	}
 
-	/**
-	 * @private
-	 */
-	static _getSlotName(child) {
-		// Text nodes can only go to the default slot
-		if (!(child instanceof HTMLElement)) {
-			return "default";
-		}
-
-		// Discover the slot based on the real slot name (f.e. footer => footer, or content-32 => content)
-		const slot = child.getAttribute("slot");
-		if (slot) {
-			const match = slot.match(/^(.+?)-\d+$/);
-			return match ? match[1] : slot;
-		}
-
-		// Use default slot as a fallback
-		return "default";
-	}
-
 	/**
 	 * @private
 	 */
@@ -668,70 +770,30 @@ class UI5Element extends HTMLElement {
 		return !!this.template;
 	}
 
-	_shouldUpdateFragment() {
-		return this.constructor._needsStaticArea() && this.staticAreaItem.isRendered();
-	}
-
 	/**
 	 * @private
 	 */
 	static _needsStaticArea() {
-		return typeof this.staticAreaTemplate === "function";
+		return !!this.staticAreaTemplate;
 	}
 
 	/**
 	 * @public
 	 */
 	getStaticAreaItemDomRef() {
-		return this.staticAreaItem.getDomRef();
-	}
-
-	/**
-	 * @private
-	 */
-	static _getDefaultState() {
-		if (this._defaultState) {
-			return this._defaultState;
+		if (!this.constructor._needsStaticArea()) {
+			throw new Error("This component does not use the static area");
 		}
 
-		const MetadataClass = this.getMetadata();
-		const defaultState = {};
-		const slotsAreManaged = MetadataClass.slotsAreManaged();
-
-		// Initialize properties
-		const props = MetadataClass.getProperties();
-		for (const propName in props) { // eslint-disable-line
-			const propType = props[propName].type;
-			const propDefaultValue = props[propName].defaultValue;
-
-			if (propType === Boolean) {
-				defaultState[propName] = false;
-
-				if (propDefaultValue !== undefined) {
-					console.warn("The 'defaultValue' metadata key is ignored for all booleans properties, they would be initialized with 'false' by default"); // eslint-disable-line
-				}
-			} else if (props[propName].multiple) {
-				defaultState[propName] = [];
-			} else if (propType === Object) {
-				defaultState[propName] = "defaultValue" in props[propName] ? props[propName].defaultValue : {};
-			} else if (propType === String) {
-				defaultState[propName] = "defaultValue" in props[propName] ? props[propName].defaultValue : "";
-			} else {
-				defaultState[propName] = propDefaultValue;
-			}
+		if (!this.staticAreaItem) {
+			this.staticAreaItem = StaticAreaItem.createInstance();
+			this.staticAreaItem.setOwnerElement(this);
 		}
-
-		// Initialize slots
-		if (slotsAreManaged) {
-			const slots = MetadataClass.getSlots();
-			for (const [slotName, slotData] of Object.entries(slots)) { // eslint-disable-line
-				const propertyName = slotData.propertyName || slotName;
-				defaultState[propertyName] = [];
-			}
+		if (!this.staticAreaItem.parentElement) {
+			getSingletonElementInstance("ui5-static-area").appendChild(this.staticAreaItem);
 		}
 
-		this._defaultState = defaultState;
-		return defaultState;
+		return this.staticAreaItem.getDomRef();
 	}
 
 	/**
@@ -745,7 +807,7 @@ class UI5Element extends HTMLElement {
 		const properties = this.getMetadata().getProperties();
 		for (const [prop, propData] of Object.entries(properties)) { // eslint-disable-line
 			if (!isValidPropertyName(prop)) {
-				throw new Error(`"${prop}" is not a valid property name. Use a name that does not collide with DOM APIs`);
+				console.warn(`"${prop}" is not a valid property name. Use a name that does not collide with DOM APIs`); /* eslint-disable-line */
 			}
 
 			if (propData.type === Boolean && propData.defaultValue) {
@@ -783,14 +845,27 @@ class UI5Element extends HTMLElement {
 					}
 				},
 				set(value) {
+					let isDifferent;
 					value = this.constructor.getMetadata().constructor.validatePropertyValue(value, propData);
 
 					const oldState = this._state[prop];
+					if (propData.multiple && propData.compareValues) {
+						isDifferent = !arraysAreEqual(oldState, value);
+					} else if (isDescendantOf(propData.type, DataType)) {
+						isDifferent = !propData.type.valuesAreEqual(oldState, value);
+					} else {
+						isDifferent = oldState !== value;
+					}
 
-					if (oldState !== value) {
+					if (isDifferent) {
 						this._state[prop] = value;
-						this._invalidate(prop, value);
-						this._propertyChange(prop, value);
+						_invalidate.call(this, {
+							type: "property",
+							name: prop,
+							newValue: value,
+							oldValue: oldState,
+						});
+						this._updateAttribute(prop, value);
 					}
 				},
 			});
@@ -801,7 +876,7 @@ class UI5Element extends HTMLElement {
 			const slots = this.getMetadata().getSlots();
 			for (const [slotName, slotData] of Object.entries(slots)) { // eslint-disable-line
 				if (!isValidPropertyName(slotName)) {
-					throw new Error(`"${slotName}" is not a valid property name. Use a name that does not collide with DOM APIs`);
+					console.warn(`"${slotName}" is not a valid property name. Use a name that does not collide with DOM APIs`); /* eslint-disable-line */
 				}
 
 				const propertyName = slotData.propertyName || slotName;
@@ -813,7 +888,7 @@ class UI5Element extends HTMLElement {
 						return [];
 					},
 					set() {
-						throw new Error("Cannot set slots directly, use the DOM APIs");
+						throw new Error("Cannot set slot content directly, use the DOM APIs (appendChild, removeChild, etc...)");
 					},
 				});
 			}
@@ -825,7 +900,7 @@ class UI5Element extends HTMLElement {
 	 * @protected
 	 */
 	static get metadata() {
-		return metadata;
+		return {};
 	}
 
 	/**
@@ -844,6 +919,50 @@ class UI5Element extends HTMLElement {
 		return "";
 	}
 
+	/**
+	 * Returns an array with the dependencies for this UI5 Web Component, which could be:
+	 *  - composed components (used in its shadow root or static area item)
+	 *  - slotted components that the component may need to communicate with
+	 *
+	 * @protected
+	 */
+	static get dependencies() {
+		return [];
+	}
+
+	/**
+	 * Returns a list of the unique dependencies for this UI5 Web Component
+	 *
+	 * @public
+	 */
+	static getUniqueDependencies() {
+		if (!uniqueDependenciesCache.has(this)) {
+			const filtered = this.dependencies.filter((dep, index, deps) => deps.indexOf(dep) === index);
+			uniqueDependenciesCache.set(this, filtered);
+		}
+
+		return uniqueDependenciesCache.get(this);
+	}
+
+	/**
+	 * Returns a promise that resolves whenever all dependencies for this UI5 Web Component have resolved
+	 *
+	 * @returns {Promise<any[]>}
+	 */
+	static whenDependenciesDefined() {
+		return Promise.all(this.getUniqueDependencies().map(dep => dep.define()));
+	}
+
+	/**
+	 * Hook that will be called upon custom element definition
+	 *
+	 * @protected
+	 * @returns {Promise<void>}
+	 */
+	static async onDefine() {
+		return Promise.resolve();
+	}
+
 	/**
 	 * Registers a UI5 Web Component in the browser window object
 	 * @public
@@ -852,21 +971,30 @@ class UI5Element extends HTMLElement {
 	static async define() {
 		await boot();
 
-		if (this.onDefine) {
-			await this.onDefine();
-		}
+		await Promise.all([
+			this.whenDependenciesDefined(),
+			this.onDefine(),
+		]);
 
 		const tag = this.getMetadata().getTag();
+		const altTag = this.getMetadata().getAltTag();
 
 		const definedLocally = isTagRegistered(tag);
 		const definedGlobally = customElements.get(tag);
 
 		if (definedGlobally && !definedLocally) {
-			console.warn(`Skipping definition of tag ${tag}, because it was already defined by another instance of ui5-webcomponents.`); // eslint-disable-line
+			recordTagRegistrationFailure(tag);
 		} 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
+				}));
+			}
 		}
 		return this;
 	}