From ff7d00d97fdba2603eaba1867599484583fd21a5 Mon Sep 17 00:00:00 2001
From: Teodor Taushanov <teodor.taushanov@sap.com>
Date: Tue, 21 Nov 2023 14:46:56 +0200
Subject: [PATCH] fix(ui5-popover): document special cases

---
 packages/main/src/Dialog.ts              | 9 ++++-----
 packages/main/src/Popover.ts             | 5 +++++
 packages/main/test/specs/Popover.spec.js | 6 ++++--
 3 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/packages/main/src/Dialog.ts b/packages/main/src/Dialog.ts
index 353cde68fda1..5a24f2e9b09d 100644
--- a/packages/main/src/Dialog.ts
+++ b/packages/main/src/Dialog.ts
@@ -94,11 +94,10 @@ const ICON_PER_STATE: Record<ValueStateWithIcon, string> = {
  *
  * <code>import "@ui5/webcomponents/dist/Dialog";</code>
  *
- * <b>Note:</b> We don't recommend nesting popup-like components (<code>ui5-dialog</code>, <code>ui5-popover</code>) inside <code>ui5-dialog</code>.
- * Ideally you should create all popups on the same level inside your HTML page and just open them from one another, rather than nesting them.
- *
- * <b>Note:</b> We don't recommend nesting popup-like components (<code>ui5-dialog</code>, <code>ui5-popover</code>) inside other components containing z-index.
- * This might break z-index management.
+ * <b>Note: </b> We recommend placing popup-like components (<code>ui5-dialog</code> and <code>ui5-popover</code>)
+ * outside any other components. Preferably the popup-like components should be placed in
+ * a top level container. Otherwise, in some cases the parent elements can break
+ * the position and/or z-index management of the popup-like components.
  *
  * @constructor
  * @author SAP SE
diff --git a/packages/main/src/Popover.ts b/packages/main/src/Popover.ts
index 8f4f7decfa95..d057ea3fd8e2 100644
--- a/packages/main/src/Popover.ts
+++ b/packages/main/src/Popover.ts
@@ -80,6 +80,11 @@ type CalculatedPlacement = {
  *
  * <code>import "@ui5/webcomponents/dist/Popover.js";</code>
  *
+ * <b>Note: </b> We recommend placing popup-like components (<code>ui5-dialog</code> and <code>ui5-popover</code>)
+ * outside any other components. Preferably the popup-like components should be placed in
+ * a top level container. Otherwise, in some cases the parent elements can break
+ * the position and/or the z-index management of the popup-like components.
+ *
  * @constructor
  * @author SAP SE
  * @alias sap.ui.webc.main.Popover
diff --git a/packages/main/test/specs/Popover.spec.js b/packages/main/test/specs/Popover.spec.js
index 2764c7d51bd7..1bd402356f7e 100644
--- a/packages/main/test/specs/Popover.spec.js
+++ b/packages/main/test/specs/Popover.spec.js
@@ -82,6 +82,8 @@ describe("Popover general interaction", () => {
 		const btnOpenPopover = await browser.$("#btnQuickViewCardOpener");
 		const btnMoveFocus = await browser.$("#btnMoveFocus");
 
+		await btnOpenPopover.scrollIntoView();
+
 		// assert - the opener is visible
 		assert.strictEqual(await btnOpenPopover.isDisplayedInViewport(), true,
 			"Opener is available.");
@@ -474,7 +476,7 @@ describe("Horizontal Alignment", () => {
 		await browser.$("#horizontalAlignBtn").click();
 		const popover = await browser.$("#popoverHorizontalAlign");
 		const opener = await browser.$("#targetOpener");
-	
+
 		assert.ok(await isHorizontallyCentered(popover, opener), `Popover should be centered`);
 	});
 
@@ -492,7 +494,7 @@ describe("Horizontal Alignment", () => {
 		await browser.$("#horizontalAlignBtn").click();
 		const popover = await browser.$("#popoverHorizontalAlign");
 		const opener = await browser.$("#targetOpener");
-	
+
 		assert.ok(await isHorizontallyRightAligned(popover, opener), `Popover should be right aligned`);
 	});