feat: rework stableDomRef concept (#4210)

packages/base/hash.txt

@@ -1 +1 @@
-i/Y2atBKmmJfJWfPYtjAghmFTKw=
+E8o8rXi7ssheVuSIOTkqLT5otB8=

packages/base/src/StaticAreaItem.js

@@ -76,15 +76,6 @@ class StaticAreaItem extends HTMLElement {
 		return this.shadowRoot;
 	}
 
-	/**
-	 * @protected
-	 * @param refName
-	 * @returns {Element}
-	 */
-	getStableDomRef(refName) {
-		return this.shadowRoot.querySelector(`[data-ui5-stable=${refName}]`);
-	}
-
 	static getTag() {
 		const pureTag = "ui5-static-area-item";
 		const suffix = getEffectiveScopingSuffixForTag(pureTag);

packages/base/src/UI5Element.js

@@ -607,10 +607,17 @@ 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;
 		}
@@ -646,17 +653,6 @@ 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")
 	 * @public

packages/fiori/src/ShellBar.js

@@ -362,12 +362,6 @@ const metadata = {
  * <li>product-switch</li>
  * </ul>
  *
- * In the context of <code>ui5-shellbar</code>, you can provide a custom stable DOM refs for:
- * <ul>
- * <li>Every <code>ui5-shellbar-item</code> that you provide.
- * Example: <code><ui5-shellbar-item stable-dom-ref="messages"></ui5-shellbar-item></code></li>
- * </ul>
- *
  * <h3>CSS Shadow Parts</h3>
  *
  * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
@@ -770,6 +764,54 @@ class ShellBar extends UI5Element {
 		}, true);
 	}
 
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get logoDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="logo"]`);
+	}
+
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get copilotDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="copilot"]`);
+	}
+
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get notificationsDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="notifications"]`);
+	}
+
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get overflowlogoDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="notifications"]`);
+	}
+
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get profileDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="profile"]`);
+	}
+
+	/**
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	get productSwitchDomRef() {
+		return this.shadowRoot.querySelector(`*[data-ui5-stable="product-switch"]`);
+	}
+
 	/**
 	 * Returns all items that will be placed in the right of the bar as icons / dom elements.
 	 * @param {boolean} showOverflowButton Determines if overflow button should be visible (not overflowing)
@@ -792,6 +834,7 @@ class ShellBar extends UI5Element {
 				show: !!this.searchField.length,
 			},
 			...this.items.map((item, index) => {
+				item._getRealDomRef = () => this.getDomRef().querySelector(`*[data-ui5-stable=${item.stableDomRef}]`);
 				return {
 					icon: item.icon,
 					id: item._id,

packages/fiori/src/ShellBarItem.js

@@ -1,9 +1,6 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 
-// Template
-import ShellBarItemTemplate from "./generated/templates/ShellBarItemTemplate.lit.js";
-
 /**
  * @public
  */
@@ -40,16 +37,6 @@ const metadata = {
 		count: {
 			type: String,
 		},
-
-		/**
-		 * Defines the stable selector that you can use via getStableDomRef method.
-		 * @public
-		 * @type {string}
-		 * @since 1.0.0-rc.8
-		 */
-		stableDomRef: {
-			type: String,
-		},
 	},
 
 	events: /** @lends sap.ui.webcomponents.fiori.ShellBarItem.prototype */ {
@@ -93,8 +80,8 @@ class ShellBarItem extends UI5Element {
 		return litRender;
 	}
 
-	static get template() {
-		return ShellBarItemTemplate;
+	get stableDomRef() {
+		return `${this._id}-stable-dom-ref`;
 	}
 }
 

packages/main/src/MultiComboBox.js

@@ -339,12 +339,6 @@ const metadata = {
  * <li> Backspace -  deletes the token and focus the next token. </li>
  * </ul>
  *
- * In the context of <code>ui5-multi-combobox</code>, you can provide a custom stable DOM ref for:
- * <ul>
- * <li>Every <code>ui5-mcb-item</code> that you provide.
- * Example: <code>&lt;ui5-mcb-item stable-dom-ref="item1"&gt;&lt;/ui5-mcb-item&gt;</code></li>
- * </ul>
- *
  * <h3>CSS Shadow Parts</h3>
  *
  * <ui5-link target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/::part">CSS Shadow Parts</ui5-link> allow developers to style elements inside the Shadow DOM.
@@ -821,6 +815,10 @@ class MultiComboBox extends UI5Element {
 			this._filteredItems = this.items;
 		}
 
+		this.items.forEach(item => {
+			item._getRealDomRef = () => this.allItemsPopover.querySelector(`*[data-ui5-stable=${item.stableDomRef}]`);
+		});
+
 		const filteredItems = this._filterItems(this.value);
 		this._filteredItems = filteredItems;
 	}

packages/main/src/MultiComboBoxItem.js

@@ -13,16 +13,6 @@ const metadata = {
 		 * @public
 		 */
 		selected: { type: Boolean },
-
-		/**
-		 * Defines the stable selector that you can use via getStableDomRef method.
-		 * @public
-		 * @type {string}
-		 * @since 1.0.0-rc.11
-		 */
-		stableDomRef: {
-			type: String,
-		},
 	},
 };
 
@@ -42,6 +32,10 @@ class MultiComboBoxItem extends ComboBoxItem {
 	static get metadata() {
 		return metadata;
 	}
+
+	get stableDomRef() {
+		return `${this._id}-stable-dom-ref`;
+	}
 }
 
 MultiComboBoxItem.define();

packages/main/src/Option.js

@@ -57,16 +57,6 @@ const metadata = {
 			type: String,
 		},
 
-		/**
-		 * Defines the stable selector that you can use via getStableDomRef method.
-		 * @public
-		 * @type {string}
-		 * @since 1.0.0-rc.11
-		 */
-		stableDomRef: {
-			type: String,
-		},
-
 		/**
 		 * Defines the focused state of the component.
 		 * @type {boolean}
@@ -114,6 +104,10 @@ class Option extends UI5Element {
 	static get metadata() {
 		return metadata;
 	}
+
+	get stableDomRef() {
+		return `${this._id}-stable-dom-ref`;
+	}
 }
 
 Option.define();

packages/main/src/Select.js

@@ -264,14 +264,6 @@ const metadata = {
  * </ul>
  * <br>
  *
- * <h3>Stable DOM Refs</h3>
- *
- * In the context of <code>ui5-select</code>, you can provide a custom stable DOM ref for:
- * <ul>
- * <li>Every <code>ui5-option</code> that you provide.
- * Example: <code><ui5-option stable-dom-ref="option1"></ui5-option></code></li>
- * </ul>
- *
  * <h3>ES6 Module Import</h3>
  * <code>import "@ui5/webcomponents/dist/Select";</code>
  * <br>
@@ -335,6 +327,8 @@ class Select extends UI5Element {
 				this._listWidth = this.responsivePopover.offsetWidth;
 			}
 		}
+
+		this._attachRealDomRefs();
 	}
 
 	_onfocusin() {
@@ -378,6 +372,14 @@ class Select extends UI5Element {
 		}
 	}
 
+	async _attachRealDomRefs() {
+		this.responsivePopover = await this._respPopover();
+
+		this.options.forEach(option => {
+			option._getRealDomRef = () => this.responsivePopover.querySelector(`*[data-ui5-stable=${option.stableDomRef}]`);
+		});
+	}
+
 	_syncSelection() {
 		let lastSelectedOptionIndex = -1,
 			firstEnabledOptionIndex = -1;

packages/main/src/Tab.js

@@ -102,16 +102,6 @@ const metadata = {
 			defaultValue: SemanticColor.Default,
 		},
 
-		/**
-		 * Defines the stable selector that you can use via getStableDomRef method.
-		 * @public
-		 * @type {string}
-		 * @since 1.0.0-rc.8
-		 */
-		stableDomRef: {
-			type: String,
-		},
-
 		/**
 		 * Specifies if the component is selected.
 		 *
@@ -201,6 +191,22 @@ class Tab extends UI5Element {
 		return executeTemplate(this.constructor.overflowTemplate, this);
 	}
 
+	get stableDomRef() {
+		return `${this._id}-stable-dom-ref`;
+	}
+
+	/**
+	 * Returns the DOM reference of the tab that is placed in the header.
+	 * <b>Note:</b> If you need a DOM ref to the tab content please use the <code>getDomRef</code> method.
+	 *
+	 * @function
+	 * @public
+	 * @since 1.0.0-rc.16
+	 */
+	getTabInStripDomRef() {
+		return this._getTabInStripDomRef;
+	}
+
 	getFocusDomRef() {
 		let focusedDomRef = super.getFocusDomRef();
 

packages/main/src/TabContainer.hbs

@@ -30,7 +30,12 @@
 							{{this.stripPresentation}}
 						{{/unless}}
 						{{#if this.isSeparator}}
-							<li id="{{this._id}}" role="separator" class="{{../classes.separator}}"></li>
+							<li
+								id="{{this._id}}"
+								data-ui5-stable="{{this.stableDomRef}}"
+								role="separator"
+								class="{{../classes.separator}}"
+							></li>
 						{{/if}}
 					{{/each}}
 				</ul>

packages/main/src/TabContainer.js

@@ -235,14 +235,6 @@ const metadata = {
  * <li><code>ui5-tab-separator</code> - used to separate tabs with a vertical line</li>
  * </ul>
  *
- * <h3>Stable DOM Refs</h3>
- *
- * In the context of <code>ui5-tabcontainer</code>, you can provide a custom stable DOM refs for:
- * <ul>
- * <li>Each <code>ui5-tab</code>
- * Example: <code><ui5-tab stable-dom-ref="in-stock"></ui5-tab></code></li>
- * </ul>
- *
  * <h3>ES6 Module Import</h3>
  *
  * <code>import "@ui5/webcomponents/dist/TabContainer";</code>
@@ -318,6 +310,7 @@ class TabContainer extends UI5Element {
 				return this.getDomRef().querySelector(`#${item._id}`);
 			};
 			item._itemSelectCallback = this._onItemSelect.bind(this);
+			item._getRealDomRef = () => this.getDomRef().querySelector(`*[data-ui5-stable=${item.stableDomRef}]`);
 		});
 
 		if (!this._animationRunning) {
@@ -328,6 +321,10 @@ class TabContainer extends UI5Element {
 	onAfterRendering() {
 		this._scrollEnablement.scrollContainer = this._getHeaderScrollContainer();
 		this._updateScrolling();
+
+		this.items.forEach(item => {
+			item._getTabInStripDomRef = this.getDomRef().querySelector(`*[data-ui5-stable="${item.stableDomRef}"]`);
+		});
 	}
 
 	onEnterDOM() {