feat: enable scoping for components in compat package (#11822)

nnaydenow · web-flow · commit 55e15276755b · 2025-07-04T11:19:18.000+03:00
This PR introduces a new scoping mechanism specifically for components in the compatibility package. A new module, `@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js`, has been added. It provides two functions: * `getCompatCustomElementsScopingSuffix()`: Returns a `string | undefined` representing the currently configured compatibility suffix. * `setCompatCustomElementsScopingSuffix(suffix: string)`: Sets the compatibility scoping suffix. > **Note:** This feature is different from the general [scoping mechanism](https://sap.github.io/ui5-webcomponents/nightly/docs/advanced/scoping/) and applies **only** to components from the compatibility package. When this feature is used, tag names are formatted as follows: * **No suffixes set**: `{tag}` (f.e ui5-table) * **Only compatibility suffix set**: `{tag}-{compatSuffix}` (f.e ui5-table-compat) * **Both compatibility and general scoping suffixes set**: `{tag}-{compatSuffix}-{suffix}` (f.e ui5-table-compat-1a35aff) Fixes: #11807 Related to: #10492, #11260
diff --git a/packages/base/src/CustomElementsScopeUtils.ts b/packages/base/src/CustomElementsScopeUtils.ts
@@ -43,7 +43,7 @@ const setCustomElementsScopingSuffix = (suffix: string) => {
  * @public
  * @returns {String|undefined}
  */
-const getCustomElementsScopingSuffix = () => {
+const getCustomElementsScopingSuffix = (): string | undefined => {
 	return suf;
 };
 
diff --git a/packages/compat/cypress/specs/ScopingCombinedSuffix.cy.tsx b/packages/compat/cypress/specs/ScopingCombinedSuffix.cy.tsx
@@ -0,0 +1,44 @@
+import "./utils/combined-suffix.js";
+import Table from "../../src/Table.js";
+import TableCell from "../../src/TableCell.js";
+import TableRow from "../../src/TableRow.js";
+import TableGroupRow from "../../src/TableGroupRow.js";
+import TableColumn from "../../src/TableColumn.js";
+import modifyTag from "./utils/modifyTag.js";
+
+describe("Package compatibility scoping", () => {
+	it("Compat and general suffix", () => {
+		cy.mount(
+			<Table>
+				<TableColumn slot="columns">
+					Product
+				</TableColumn>
+
+				<TableGroupRow>Group</TableGroupRow>
+
+				<TableRow>
+					<TableCell>
+						Product 1
+					</TableCell>
+				</TableRow>
+			</Table>
+		);
+
+		[
+			Table.getMetadata().getPureTag(),
+			TableCell.getMetadata().getPureTag(),
+			TableRow.getMetadata().getPureTag(),
+			TableGroupRow.getMetadata().getPureTag(),
+			TableColumn.getMetadata().getPureTag()
+		].map(tag => modifyTag(tag, "compat", "demo"))
+			.forEach(tag => {
+				cy.get(tag)
+					.should("exist");
+
+				cy.get(tag)
+					.shadow()
+					.find("*")
+					.should("exist");
+			})
+	});
+});
diff --git a/packages/compat/cypress/specs/ScopingCompatSuffix.cy.tsx b/packages/compat/cypress/specs/ScopingCompatSuffix.cy.tsx
@@ -0,0 +1,44 @@
+import "./utils/legacy-suffix.js";
+import Table from "../../src/Table.js";
+import TableCell from "../../src/TableCell.js";
+import TableRow from "../../src/TableRow.js";
+import TableGroupRow from "../../src/TableGroupRow.js";
+import TableColumn from "../../src/TableColumn.js";
+import modifyTag from "./utils/modifyTag.js";
+
+describe("Package compatibility scoping", () => {
+	it("Compat suffix", () => {
+		cy.mount(
+			<Table>
+				<TableColumn slot="columns">
+					Product
+				</TableColumn>
+
+				<TableGroupRow>Group</TableGroupRow>
+
+				<TableRow>
+					<TableCell>
+						Product 1
+					</TableCell>
+				</TableRow>
+			</Table>
+		);
+
+		[
+			Table.getMetadata().getPureTag(),
+			TableCell.getMetadata().getPureTag(),
+			TableRow.getMetadata().getPureTag(),
+			TableGroupRow.getMetadata().getPureTag(),
+			TableColumn.getMetadata().getPureTag()
+		].map(tag => modifyTag(tag, "compat"))
+			.forEach(tag => {
+				cy.get(tag)
+					.should("exist");
+
+				cy.get(tag)
+					.shadow()
+					.find("*")
+					.should("exist");
+			})
+	});
+});
diff --git a/packages/compat/cypress/specs/ScopingSuffix.cy.tsx b/packages/compat/cypress/specs/ScopingSuffix.cy.tsx
@@ -0,0 +1,44 @@
+import "./utils/suffix.js";
+import Table from "../../src/Table.js";
+import TableCell from "../../src/TableCell.js";
+import TableRow from "../../src/TableRow.js";
+import TableGroupRow from "../../src/TableGroupRow.js";
+import TableColumn from "../../src/TableColumn.js";
+import modifyTag from "./utils/modifyTag.js";
+
+describe("Table", () => {
+	it("tests doesn't fire loadMore with ArrowDown on last row", () => {
+		cy.mount(
+			<Table>
+				<TableColumn slot="columns">
+					Product
+				</TableColumn>
+
+				<TableGroupRow>Group</TableGroupRow>
+
+				<TableRow>
+					<TableCell>
+						Product 1
+					</TableCell>
+				</TableRow>
+			</Table>
+		);
+
+		[
+			Table.getMetadata().getPureTag(),
+			TableCell.getMetadata().getPureTag(),
+			TableRow.getMetadata().getPureTag(),
+			TableGroupRow.getMetadata().getPureTag(),
+			TableColumn.getMetadata().getPureTag()
+		].map(tag => modifyTag(tag, undefined, "demo"))
+			.forEach(tag => {
+				cy.get(tag)
+					.should("exist");
+
+				cy.get(tag)
+					.shadow()
+					.find("*")
+					.should("exist");
+			})
+	});
+});
diff --git a/packages/compat/cypress/specs/ScopingWithoutSuffix.cy.tsx b/packages/compat/cypress/specs/ScopingWithoutSuffix.cy.tsx
@@ -0,0 +1,43 @@
+import Table from "../../src/Table.js";
+import TableCell from "../../src/TableCell.js";
+import TableRow from "../../src/TableRow.js";
+import TableGroupRow from "../../src/TableGroupRow.js";
+import TableColumn from "../../src/TableColumn.js";
+import modifyTag from "./utils/modifyTag.js";
+
+describe("Package compatibility scoping", () => {
+	it("Without suffix", () => {
+		cy.mount(
+			<Table>
+				<TableColumn slot="columns">
+					Product
+				</TableColumn>
+
+				<TableGroupRow>Group</TableGroupRow>
+
+				<TableRow>
+					<TableCell>
+						Product 1
+					</TableCell>
+				</TableRow>
+			</Table>
+		);
+
+		[
+			Table.getMetadata().getPureTag(),
+			TableCell.getMetadata().getPureTag(),
+			TableRow.getMetadata().getPureTag(),
+			TableGroupRow.getMetadata().getPureTag(),
+			TableColumn.getMetadata().getPureTag()
+		].map(tag => modifyTag(tag))
+			.forEach(tag => {
+				cy.get(tag)
+					.should("exist");
+
+				cy.get(tag)
+					.shadow()
+					.find("*")
+					.should("exist");
+			})
+	});
+});
diff --git a/packages/compat/cypress/specs/utils/combined-suffix.ts b/packages/compat/cypress/specs/utils/combined-suffix.ts
@@ -0,0 +1,5 @@
+import { setCustomElementsScopingSuffix } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
+import { setCompatCustomElementsScopingSuffix } from "../../../src/utils/CompatCustomElementsScope.js";
+
+setCustomElementsScopingSuffix("demo")
+setCompatCustomElementsScopingSuffix("compat")
diff --git a/packages/compat/cypress/specs/utils/legacy-suffix.ts b/packages/compat/cypress/specs/utils/legacy-suffix.ts
@@ -0,0 +1,3 @@
+import { setCompatCustomElementsScopingSuffix } from "../../../src/utils/CompatCustomElementsScope.js";
+
+setCompatCustomElementsScopingSuffix("compat")
diff --git a/packages/compat/cypress/specs/utils/modifyTag.ts b/packages/compat/cypress/specs/utils/modifyTag.ts
@@ -0,0 +1,5 @@
+const modifyTag = (tag: string, legacySuffix?: string, suffix?: string) => {
+	return [tag, legacySuffix, suffix].filter(Boolean).join("-");
+}
+
+export default modifyTag;
diff --git a/packages/compat/cypress/specs/utils/suffix.ts b/packages/compat/cypress/specs/utils/suffix.ts
@@ -0,0 +1,3 @@
+import { setCustomElementsScopingSuffix } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
+
+setCustomElementsScopingSuffix("demo")
diff --git a/packages/compat/src/Table.ts b/packages/compat/src/Table.ts
@@ -59,6 +59,7 @@ import TableTemplate from "./TableTemplate.js";
 
 // Styles
 import tableStyles from "./generated/themes/Table.css.js";
+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";
 
 /**
  * Interface for components that may be slotted inside a `ui5-table` as rows
@@ -1194,6 +1195,8 @@ class Table extends UI5Element {
 	}
 }
 
+patchScopingSuffix(Table);
+
 Table.define();
 
 export default Table;
diff --git a/packages/compat/src/TableCell.ts b/packages/compat/src/TableCell.ts
@@ -14,6 +14,7 @@ import tableCellStyles from "./generated/themes/TableCell.css.js";
 import {
 	ARIA_LABEL_EMPTY_CELL,
 } from "./generated/i18n/i18n-defaults.js";
+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";
 
 /**
  * @class
@@ -71,6 +72,8 @@ class TableCell extends UI5Element {
 	}
 }
 
+patchScopingSuffix(TableCell);
+
 TableCell.define();
 
 export default TableCell;
diff --git a/packages/compat/src/TableColumn.ts b/packages/compat/src/TableColumn.ts
@@ -7,6 +7,7 @@ import type TableColumnPopinDisplay from "./types/TableColumnPopinDisplay.js";
 
 // Styles
 import tableColumnStyles from "./generated/themes/TableColumn.css.js";
+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";
 
 /**
  * @class
@@ -87,6 +88,8 @@ class TableColumn extends UI5Element {
 	last = false;
 }
 
+patchScopingSuffix(TableColumn);
+
 TableColumn.define();
 
 export default TableColumn;
diff --git a/packages/compat/src/TableGroupRow.ts b/packages/compat/src/TableGroupRow.ts
@@ -16,6 +16,7 @@ import {
 
 // Styles
 import tableGroupRowStyles from "./generated/themes/TableGroupRow.css.js";
+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";
 
 /**
  * @class
@@ -109,6 +110,8 @@ class TableGroupRow extends UI5Element implements ITableRow {
 	}
 }
 
+patchScopingSuffix(TableGroupRow);
+
 TableGroupRow.define();
 
 export default TableGroupRow;
diff --git a/packages/compat/src/TableRow.ts b/packages/compat/src/TableRow.ts
@@ -29,6 +29,7 @@ import {
 
 // Styles
 import tableRowStyles from "./generated/themes/TableRow.css.js";
+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";
 
 type TableRowClickEventDetail = {
 	row: TableRow,
@@ -452,6 +453,8 @@ class TableRow extends UI5Element implements ITableRow {
 	}
 }
 
+patchScopingSuffix(TableRow);
+
 TableRow.define();
 
 export default TableRow;
diff --git a/packages/compat/src/utils/CompatCustomElementsScope.ts b/packages/compat/src/utils/CompatCustomElementsScope.ts
@@ -0,0 +1,55 @@
+import type UI5Element from "@ui5/webcomponents-base";
+import { getCustomElementsScopingSuffix } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
+import { hasRegisteredTags } from "@ui5/webcomponents-base/dist/CustomElementsRegistry.js";
+
+let suf: string;
+
+const setCompatCustomElementsScopingSuffix = (suffix: string) => {
+	if (!suffix.match(/^[a-zA-Z0-9_-]+$/)) {
+		throw new Error("Only alphanumeric characters and dashes allowed for the scoping suffix");
+	}
+
+	if (hasRegisteredTags()) {
+		// eslint-disable-next-line no-console
+		console.warn("Setting the compatibility scoping suffix must be done before importing any components. For proper usage, read the scoping section: https://github.com/SAP/ui5-webcomponents/blob/main/docs/2-advanced/06-scoping.md.");
+	}
+
+	suf = suffix;
+};
+
+const getCompatCustomElementsScopingSuffix = () => {
+	return suf;
+};
+
+const patchScopingSuffix = (klass: typeof UI5Element) => {
+	const metadata = klass.getMetadata();
+	// eslint-disable-next-line @typescript-eslint/unbound-method
+	const originalGetTag = metadata.getTag;
+
+	metadata.getTag = function () {
+		const originalTag = originalGetTag.call(this);
+
+		if (!originalTag) {
+			return "";
+		}
+
+		const compatSuffix = getCompatCustomElementsScopingSuffix();
+		const suffix = getCustomElementsScopingSuffix();
+
+		if (!compatSuffix) {
+			return originalTag;
+		}
+
+		if (suffix && originalTag.endsWith(`-${suffix}`)) {
+			return originalTag.replace(`-${suffix}`, `-${compatSuffix}-${suffix}`);
+		}
+
+		return `${originalTag}-${compatSuffix}`;
+	};
+};
+
+export {
+	setCompatCustomElementsScopingSuffix,
+	getCompatCustomElementsScopingSuffix,
+	patchScopingSuffix,
+};

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import { setCompatCustomElementsScopingSuffix } from "../../../src/utils/CompatCustomElementsScope.js";`
	`2`	`+`
	`3`	`+setCompatCustomElementsScopingSuffix("compat")`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import { setCustomElementsScopingSuffix } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";`
	`2`	`+`
	`3`	`+setCustomElementsScopingSuffix("demo")`
Original file line number	Diff line number	Diff line change
`@@ -59,6 +59,7 @@ import TableTemplate from "./TableTemplate.js";`
`59`	`59`
`60`	`60`	`// Styles`
`61`	`61`	`import tableStyles from "./generated/themes/Table.css.js";`
	`62`	`+import { patchScopingSuffix } from "./utils/CompatCustomElementsScope.js";`
`62`	`63`
`63`	`64`	`/**`
`64`	`65`	* Interface for components that may be slotted inside a `ui5-table` as rows
`@@ -1194,6 +1195,8 @@ class Table extends UI5Element {`
`1194`	`1195`	`}`
`1195`	`1196`	`}`
`1196`	`1197`
	`1198`	`+patchScopingSuffix(Table);`
	`1199`	`+`
`1197`	`1200`	`Table.define();`
`1198`	`1201`
`1199`	`1202`	`export default Table;`