fix(ui5-popover): document special cases

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

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

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`);
 	});