@ui5/webcomponents 0.0.0-39bd3067f → 0.0.0-4180fe799

package/dist/Popup.js

@@ -1,13 +1,19 @@
+import { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
+import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import { isChrome } from "@ui5/webcomponents-base/dist/Device.js";
 import { getFirstFocusableElement, getLastFocusableElement } from "@ui5/webcomponents-base/dist/util/FocusableElements.js";
-import Integer from "@ui5/webcomponents-base/dist/types/Integer.js";
-import { isEscape } from "@ui5/webcomponents-base/dist/Keys.js";
+import { hasStyle, createStyle } from "@ui5/webcomponents-base/dist/ManagedStyles.js";
+import { isTabPrevious } from "@ui5/webcomponents-base/dist/Keys.js";
+import { getNextZIndex, getFocusedElement, isFocusedElementWithinNode } from "@ui5/webcomponents-base/dist/util/PopupUtils.js";
+import PopupTemplate from "./generated/templates/PopupTemplate.lit.js";
+import PopupBlockLayer from "./generated/templates/PopupBlockLayerTemplate.lit.js";
+import { addOpenedPopup, removeOpenedPopup } from "./popup-utils/OpenedPopupsRegistry.js";
 
 // Styles
 import styles from "./generated/themes/Popup.css.js";
-
-import { addOpenedPopup, removeOpenedPopup } from "./popup-utils/OpenedPopupsRegistry.js";
-import { getNextZIndex } from "./popup-utils/PopupUtils.js";
+import staticAreaStyles from "./generated/themes/PopupStaticAreaStyles.css.js";
+import globalStyles from "./generated/themes/PopupGlobal.css.js";
 
 /**
  * @public
@@ -17,35 +23,14 @@ const metadata = {
 	slots: /** @lends  sap.ui.webcomponents.main.Popup.prototype */ {
 
 		/**
-		 * Defines the content of the Web Component.
-		 * @type {Node[]}
-		 * @slot
-		 * @public
-		 */
-		"default": {
-			type: HTMLElement,
-		},
-
-		/**
-		 * Defines the header HTML Element.
-		 *
-		 * @type {HTMLElement[]}
-		 * @slot
-		 * @public
-		 */
-		header: {
-			type: HTMLElement,
-		},
-
-		/**
-		 * Defines the footer HTML Element.
-		 *
+		 * Defines the content of the Popup.
 		 * @type {HTMLElement[]}
 		 * @slot
 		 * @public
 		 */
-		footer: {
+		"default": {
 			type: HTMLElement,
+			propertyName: "content",
 		},
 	},
 	properties: /** @lends  sap.ui.webcomponents.main.Popup.prototype */ {
@@ -61,34 +46,38 @@ const metadata = {
 		},
 
 		/**
-		 * Defines the header text.
-		 * <br><br>
-		 * <b>Note:</b> If <code>header</code> slot is provided, the <code>headerText</code> is ignored.
-		 *
-		 * @type {string}
-		 * @defaultvalue ""
+		 * Defines if the focus should be returned to the previously focused element,
+		 * when the popup closes.
+		 * @type {boolean}
+		 * @defaultvalue false
 		 * @public
-		 */
-		headerText: {
-			type: String,
+		 * @since 1.0.0-rc.8
+		*/
+		preventFocusRestore: {
+			type: Boolean,
 		},
 
 		/**
-		 * Indicates if the elements is on focus
+		 * Indicates if the element is open
 		 * @private
+		 * @type {boolean}
+		 * @defaultvalue false
 		 */
 		opened: {
 			type: Boolean,
 		},
 
-		_zIndex: {
-			type: Integer,
-			noAttribute: true,
-		},
-
-		_hideBlockLayer: {
-			type: Boolean,
-			noAttribute: true,
+		/**
+		 * Sets the accessible aria name of the component.
+		 *
+		 * @type {String}
+		 * @defaultvalue ""
+		 * @public
+		 * @since 1.0.0-rc.15
+		 */
+		accessibleName: {
+			type: String,
+			defaultValue: undefined,
 		},
 
 		/**
@@ -97,129 +86,98 @@ const metadata = {
 		_disableInitialFocus: {
 			type: Boolean,
 		},
+
+		_blockLayerHidden: {
+			type: Boolean,
+		},
 	},
 	events: /** @lends  sap.ui.webcomponents.main.Popup.prototype */ {
 
 		/**
-		 * Fired before the component is opened.
+		 * Fired before the component is opened. This event can be cancelled, which will prevent the popup from opening. <b>This event does not bubble.</b>
 		 *
 		 * @public
-		 * @event
+		 * @event sap.ui.webcomponents.main.Popup#before-open
+		 * @allowPreventDefault
 		 */
+		"before-open": {},
 
-		beforeOpen: {},
 		/**
-		 * Fired after the component is opened.
+		 * Fired after the component is opened. <b>This event does not bubble.</b>
 		 *
 		 * @public
-		 * @event
+		 * @event sap.ui.webcomponents.main.Popup#after-open
 		 */
+		"after-open": {},
 
-		afterOpen: {},
 		/**
-		 * Fired before the component is closed.
+		 * Fired before the component is closed. This event can be cancelled, which will prevent the popup from closing. <b>This event does not bubble.</b>
 		 *
 		 * @public
-		 * @event
-		 * @param {Boolean} escPressed Indicates that <code>ESC</code> key has triggered the event.
+		 * @event sap.ui.webcomponents.main.Popup#before-close
+		 * @allowPreventDefault
+		 * @param {boolean} escPressed Indicates that <code>ESC</code> key has triggered the event.
 		 */
-
-		beforeClose: {
-			escPressed: { type: Boolean },
+		"before-close": {
+			detail: {
+				escPressed: { type: Boolean },
+			},
 		},
 
 		/**
-		 * Fired after the component is closed.
+		 * Fired after the component is closed. <b>This event does not bubble.</b>
 		 *
 		 * @public
-		 * @event
+		 * @event sap.ui.webcomponents.main.Popup#after-close
+		 */
+		"after-close": {},
+
+		/**
+		 * Fired whenever the popup content area is scrolled
+		 *
+		 * @private
+		 * @event sap.ui.webcomponents.main.Popup#scroll
 		 */
-		afterClose: {},
+		"scroll": {},
 	},
 };
 
-const openedPopups = [];
-let isBodyScrollingDisabled = false;
-let customBLyBackStyleInserted = false;
-
-function getParentHost(node) {
-	while (node && !node.host) {
-		node = node.parentNode;
-	}
-
-	return node && node.host;
-}
-
-function createBLyBackStyle() {
-	if (customBLyBackStyleInserted) {
-		return;
-	}
-
-	customBLyBackStyleInserted = true;
-
-	const bodyStyleSheet = document.createElement("style");
-	bodyStyleSheet.type = "text/css";
-	bodyStyleSheet.innerHTML = `
-		.ui5-popup-BLy--back {
-			width: 100%;
-			height: 100%;
-			position: fixed;
-			overflow: hidden;
-		}
-	`;
-	document.head.appendChild(bodyStyleSheet);
-}
-
-function updateBlockLayers() {
-	let popup,
-		i,
-		hasModal = false;
-
-	for (i = openedPopups.length - 1; i >= 0; i--) {
-		popup = openedPopups[i];
-		if (hasModal) {
-			popup._hideBlockLayer = true;
-		} else {
-			if (popup.isModal()) { // eslint-disable-line
-				popup._hideBlockLayer = false;
-				hasModal = true;
-			}
-		}
-	}
-
-	updateBodyScrolling(hasModal);
-}
-
-function updateBodyScrolling(hasModal) {
-	if (isBodyScrollingDisabled === hasModal) {
-		return;
-	}
-
-	createBLyBackStyle();
-
-	if (hasModal) {
-		addBodyStyles();
-	} else {
-		removeBodyStyles();
+const createBlockingStyle = () => {
+	if (!hasStyle("data-ui5-popup-scroll-blocker")) {
+		createStyle(globalStyles, "data-ui5-popup-scroll-blocker");
 	}
-	isBodyScrollingDisabled = hasModal;
-}
+};
 
-function addBodyStyles() {
-	document.body.style.top = `-${window.pageYOffset}px`;
-	document.body.classList.add("ui5-popup-BLy--back");
-}
+createBlockingStyle();
 
-function removeBodyStyles() {
-	document.body.classList.remove("ui5-popup-BLy--back");
-	window.scrollTo(0, -parseFloat(document.body.style.top));
-	document.body.style.top = "";
-}
+const bodyScrollingBlockers = new Set();
 
 /**
  * @class
  * <h3 class="comment-api-title">Overview</h3>
- * Represents a base class for all popup Web Components.
+ * Base class for all popup Web Components.
+ *
+ * If you need to create your own popup-like custom UI5 Web Components, it is highly recommended that you extend
+ * at least Popup in order to have consistency with other popups in terms of modal behavior and z-index management.
+ *
+ * 1. The Popup class handles modality:
+ *  - The "isModal" getter can be overridden by derivatives to provide their own conditions when they are modal or not
+ *  - Derivatives may call the "blockBodyScrolling" and "unblockBodyScrolling" static methods to temporarily remove scrollbars on the body
+ *  - Derivatives may call the "open" and "close" methods which handle focus, manage the popup registry and for modal popups, manage the blocking layer
+ *
+ *  2. Provides blocking layer (relevant for modal popups only):
+ *   - It is in the static area
+ *   - Controlled by the "open" and "close" methods
+ *
+ * 3. The Popup class "traps" focus:
+ *  - Derivatives may call the "applyInitialFocus" method (usually when opening, to transfer focus inside the popup)
+ *
+ * 4. The Popup class automatically assigns "z-index"
+ *  - Each time a popup is opened, it gets a higher than the previously opened popup z-index
+ *
+ * 5. The template of this component exposes two inline partials you can override in derivatives:
+ *  - beforeContent (upper part of the box, useful for header/title/close button)
+ *  - afterContent (lower part, useful for footer/action buttons)
  *
  * @constructor
  * @author SAP SE
@@ -232,238 +190,377 @@ class Popup extends UI5Element {
 		return metadata;
 	}
 
+	static get render() {
+		return litRender;
+	}
+
 	static get styles() {
 		return styles;
 	}
 
-	static hitTest(popup, event) {
-		const indexOf = openedPopups.indexOf(popup);
-		let openedPopup;
+	static get template() {
+		return PopupTemplate;
+	}
 
-		for (let i = indexOf; i < openedPopups.length; i++) {
-			openedPopup = openedPopups[i];
-			if (openedPopup.hitTest(event)) {
-				return true;
-			}
-		}
+	static get staticAreaTemplate() {
+		return PopupBlockLayer;
+	}
 
-		return false;
+	static get staticAreaStyles() {
+		return staticAreaStyles;
 	}
 
-	static hasModalPopup() {
-		for (let i = 0; i < openedPopups.length; i++) {
-			if (openedPopups[i].isModal()) {
-				return true;
-			}
+	onEnterDOM() {
+		if (!this.isOpen()) {
+			this._blockLayerHidden = true;
 		}
-
-		return false;
 	}
 
-	constructor() {
-		super();
-
-		this._documentKeyDownHandler = this.documentKeyDown.bind(this);
+	onExitDOM() {
+		if (this.isOpen()) {
+			Popup.unblockBodyScrolling(this);
+			this._removeOpenedPopup();
+		}
 	}
 
-	isTopPopup() {
-		return openedPopups.indexOf(this) === openedPopups.length - 1;
+	get _displayProp() {
+		return "block";
 	}
 
-	isModal() {
-		return true;
+	/**
+	 * Prevents the user from interacting with the content under the block layer
+	 */
+	_preventBlockLayerFocus(event) {
+		event.preventDefault();
 	}
 
-	documentKeyDown(event) {
-		if (isEscape(event) && this.isTopPopup()) {
-			this.escPressed = true;
-			this.close();
+	/**
+	 * Temporarily removes scrollbars from the body
+	 * @protected
+	 */
+	static blockBodyScrolling(popup) {
+		bodyScrollingBlockers.add(popup);
+
+		if (bodyScrollingBlockers.size !== 1) {
+			return;
+		}
+
+		if (window.pageYOffset > 0) {
+			document.body.style.top = `-${window.pageYOffset}px`;
 		}
+		document.body.classList.add("ui5-popup-scroll-blocker");
 	}
 
-	getPopupDomRef() {
-		const domRef = this.getDomRef();
-		return domRef && domRef.querySelector(".ui5-popup-root");
+	/**
+	 * Restores scrollbars on the body, if needed
+	 * @protected
+	 */
+	static unblockBodyScrolling(popup) {
+		bodyScrollingBlockers.delete(popup);
+
+		if (bodyScrollingBlockers.size !== 0) {
+			return;
+		}
+
+		document.body.classList.remove("ui5-popup-scroll-blocker");
+		window.scrollTo(0, -parseFloat(document.body.style.top));
+		document.body.style.top = "";
 	}
 
-	hitTest(_event) {
-		return true;
+	_scroll(e) {
+		this.fireEvent("scroll", {
+			scrollTop: e.target.scrollTop,
+			targetRef: e.target,
+		});
 	}
 
-	open() {
-		this.fireEvent("beforeOpen", { });
+	_onkeydown(e) {
+		if (e.target === this._root && isTabPrevious(e)) {
+			e.preventDefault();
+		}
+	}
 
-		this._isFirstTimeRendered = false;
+	_onfocusout(e) {
+		// relatedTarget is the element, which will get focus. If no such element exists, focus the root.
+		// This happens after the mouse is released in order to not interrupt text selection.
+		if (!e.relatedTarget) {
+			this._shouldFocusRoot = true;
+		}
+	}
 
-		this._zIndex = getNextZIndex();
-		openedPopups.push(this);
-		addOpenedPopup(this);
+	_onmousedown(e) {
+		this._root.removeAttribute("tabindex");
 
+		if (this.shadowRoot.contains(e.target)) {
+			this._shouldFocusRoot = true;
+		} else {
+			this._shouldFocusRoot = false;
+		}
+	}
 
-		updateBlockLayers();
+	_onmouseup() {
+		this._root.tabIndex = -1;
+		if (this._shouldFocusRoot) {
+			if (isChrome()) {
+				this._root.focus();
+			}
+			this._shouldFocusRoot = false;
+		}
 	}
 
-	close() {
-		this.fireEvent("beforeClose", {
-			escPressed: this.escPressed,
-		}, true);
+	/**
+	 * Focus trapping
+	 * @private
+	 */
+	async forwardToFirst() {
+		const firstFocusable = await getFirstFocusableElement(this);
 
-		this.escPressed = false;
+		if (firstFocusable) {
+			firstFocusable.focus();
+		} else {
+			this._root.focus();
+		}
+	}
 
-		const index = openedPopups.indexOf(this);
-		openedPopups.splice(index, 1);
+	/**
+	 * Focus trapping
+	 * @private
+	 */
+	async forwardToLast() {
+		const lastFocusable = await getLastFocusableElement(this);
 
-		if (this.opened) {
-			removeOpenedPopup(this);
+		if (lastFocusable) {
+			lastFocusable.focus();
+		} else {
+			this._root.focus();
 		}
-
-		updateBlockLayers();
 	}
 
-	initInitialFocus() {
-		const initialFocus = this.initialFocus;
-		let initialFocusDomRef = this.initialFocus;
-
-		if (initialFocus && typeof initialFocus === "string") {
-			initialFocusDomRef = document.getElementById(initialFocus);
+	/**
+	 * Use this method to focus the element denoted by "initialFocus", if provided, or the first focusable element otherwise.
+	 * @protected
+	 */
+	async applyInitialFocus() {
+		await this.applyFocus();
+	}
 
-			if (!initialFocusDomRef) {
-				const parentHost = getParentHost(this);
-				if (parentHost) {
-					initialFocusDomRef = parentHost.shadowRoot.querySelector(`#${initialFocus}`);
-				}
+	/**
+	 * Focuses the element denoted by <code>initialFocus</code>, if provided,
+	 * or the first focusable element otherwise.
+	 * @public
+	 * @async
+	 * @returns {Promise} Promise that resolves when the focus is applied
+	 */
+	async applyFocus() {
+		await this._waitForDomRef();
+
+		const element = this.getRootNode().getElementById(this.initialFocus)
+			|| document.getElementById(this.initialFocus)
+			|| await getFirstFocusableElement(this)
+			|| this._root; // in case of no focusable content focus the root
+
+		if (element) {
+			if (element === this._root) {
+				element.tabIndex = -1;
 			}
+			element.focus();
 		}
-
-		this._initialFocusDomRef = initialFocusDomRef;
 	}
 
-	onFirstTimeAfterRendering() {
-		if (this.isTopPopup()) {
-			this.initInitialFocus();
-			this.setInitialFocus(this.getPopupDomRef());
-		}
+	/**
+	 * Tells if the component is opened
+	 * @public
+	 * @returns {boolean}
+	 */
+	isOpen() {
+		return this.opened;
+	}
 
-		this.fireEvent("afterOpen", {});
+	isFocusWithin() {
+		return isFocusedElementWithinNode(this.shadowRoot.querySelector(".ui5-popup-root"));
 	}
 
-	onAfterRendering() {
-		if (!this.opened) {
+	/**
+	 * Shows the block layer (for modal popups only) and sets the correct z-index for the purpose of popup stacking
+	 * @protected
+	 */
+	async _open(preventInitialFocus) {
+		const prevented = !this.fireEvent("before-open", {}, true, false);
+		if (prevented) {
 			return;
 		}
 
-		if (!this._isFirstTimeRendered) {
-			this.onFirstTimeAfterRendering();
-			this._isFirstTimeRendered = true;
+		if (this.isModal && !this.shouldHideBackdrop) {
+			// create static area item ref for block layer
+			this.getStaticAreaItemDomRef();
+			this._blockLayerHidden = false;
+			Popup.blockBodyScrolling(this);
 		}
-	}
 
-	setInitialFocus(container) {
-		if (this._disableInitialFocus) {
-			return;
-		}
+		this._zIndex = getNextZIndex();
+		this.style.zIndex = this._zIndex;
+		this._focusedElementBeforeOpen = getFocusedElement();
 
-		if (this._initialFocusDomRef) {
-			if (this._initialFocusDomRef !== document.activeElement) {
-				this._initialFocusDomRef.focus();
-			}
-			return;
-		}
+		this._show();
 
-		if (!container) {
-			return;
+		if (!this._disableInitialFocus && !preventInitialFocus) {
+			this.applyInitialFocus();
 		}
 
-		const focusableElement = getFirstFocusableElement(container);
+		this._addOpenedPopup();
 
-		if (focusableElement) {
-			focusableElement.focus();
-		} else {
-			container.focus();
-		}
+		this.opened = true;
+
+		await renderFinished();
+		this.fireEvent("after-open", {}, false, false);
 	}
 
-	_onfocusin(event) {
-		this.preserveFocus(event, this.getPopupDomRef());
+	/**
+	 * Adds the popup to the "opened popups registry"
+	 * @protected
+	 */
+	_addOpenedPopup() {
+		addOpenedPopup(this);
 	}
 
-	preserveFocus(event, container) {
-		if (!this.isTopPopup()) {
+	/**
+	 * Hides the block layer (for modal popups only)
+	 * @public
+	 */
+	close(escPressed = false, preventRegistryUpdate = false, preventFocusRestore = false) {
+		if (!this.opened) {
 			return;
 		}
 
-		let target = event.target;
+		const prevented = !this.fireEvent("before-close", { escPressed }, true, false);
+		if (prevented) {
+			return;
+		}
 
-		while (target.shadowRoot && target.shadowRoot.activeElement) {
-			target = target.shadowRoot.activeElement;
+		if (this.isModal) {
+			this._blockLayerHidden = true;
+			Popup.unblockBodyScrolling(this);
 		}
 
-		let focusableElement;
-		let isSpecialCase = false;
-
-		switch (target.id) {
-		case `${this._id}-firstfe`:
-			focusableElement = getLastFocusableElement(container);
-			isSpecialCase = true;
-			break;
-		case `${this._id}-lastfe`:
-			focusableElement = getFirstFocusableElement(container);
-			isSpecialCase = true;
-			break;
-		case `${this._id}-blocklayer`:
-			focusableElement = this._currentFocusedElement
-				|| getFirstFocusableElement(container);
-			isSpecialCase = true;
-			break;
+		this.hide();
+		this.opened = false;
+
+		if (!preventRegistryUpdate) {
+			this._removeOpenedPopup();
 		}
 
-		if (focusableElement) {
-			focusableElement.focus();
-		} else if (isSpecialCase) {
-			container.focus();
+		if (!this.preventFocusRestore && !preventFocusRestore) {
+			this.resetFocus();
 		}
 
-		this._currentFocusedElement = focusableElement || document.activeElement;
+		this.fireEvent("after-close", {}, false, false);
 	}
 
-	storeCurrentFocus() {
-		let element = document.activeElement;
-
-		while (element.shadowRoot && element.shadowRoot.activeElement) {
-			element = element.shadowRoot.activeElement;
-		}
-
-		this._lastFocusableElement = (element && typeof element.focus === "function") ? element : null;
+	/**
+	 * Removes the popup from the "opened popups registry"
+	 * @protected
+	 */
+	_removeOpenedPopup() {
+		removeOpenedPopup(this);
 	}
 
+	/**
+	 * Returns the focus to the previously focused element
+	 * @protected
+	 */
 	resetFocus() {
-		if (!this._lastFocusableElement) {
+		if (!this._focusedElementBeforeOpen) {
 			return;
 		}
 
-		const lastFocusableElement = this._lastFocusableElement;
-		if (lastFocusableElement) {
-			lastFocusableElement.focus();
-		}
+		this._focusedElementBeforeOpen.focus();
+		this._focusedElementBeforeOpen = null;
+	}
 
-		this._lastFocusableElement = null;
+	/**
+	 * Sets "block" display to the popup. The property can be overriden by derivatives of Popup.
+	 * @protected
+	 */
+	_show() {
+		this.style.display = this._displayProp;
 	}
 
-	onExitDOM() {
-		removeBodyStyles();
+	/**
+	 * Sets "none" display to the popup
+	 * @protected
+	 */
+	hide() {
+		this.style.display = "none";
+	}
+
+	/**
+	 * Implement this getter with relevant logic regarding the modality of the popup (e.g. based on a public property)
+	 *
+	 * @protected
+	 * @abstract
+	 * @returns {boolean}
+	 */
+	get isModal() {} // eslint-disable-line
+
+	/**
+	 * Implement this getter with relevant logic in order to hide the block layer (f.e. based on a public property)
+	 *
+	 * @protected
+	 * @abstract
+	 * @returns {boolean}
+	 */
+	get shouldHideBackdrop() {} // eslint-disable-line
+
+	/**
+	 * Return the ID of an element in the shadow DOM that is going to label this popup
+	 *
+	 * @protected
+	 * @abstract
+	 * @returns {String}
+	 */
+	get _ariaLabelledBy() {} // eslint-disable-line
+
+	/**
+	 * Return the value for aria-modal for this popup
+	 *
+	 * @protected
+	 * @abstract
+	 * @returns {String}
+	 */
+	get _ariaModal() {} // eslint-disable-line
+
+	/**
+	 * Ensures ariaLabel is never null or empty string
+	 * @returns {String|undefined}
+	 * @protected
+	 */
+	get _ariaLabel() {
+		return this.accessibleName || undefined;
 	}
 
-	get hasHeader() {
-		const hasHeaderText = this.headerText && this.headerText.length;
-		return !!(hasHeaderText || this.header.length);
+	get _root() {
+		return this.shadowRoot.querySelector(".ui5-popup-root");
 	}
 
-	get hasFooter() {
-		return !!this.footer.length;
+	get styles() {
+		return {
+			root: {},
+			content: {},
+			blockLayer: {
+				"zIndex": (this._zIndex - 1),
+			},
+		};
 	}
 
-	get role() {
-		return "heading";
+	get classes() {
+		return {
+			root: {
+				"ui5-popup-root": true,
+			},
+			content: {
+				"ui5-popup-content": true,
+			},
+		};
 	}
 }