feat(compat): enable scoping for custom elements in compat package only (#7514)

Author: Lukas742

.storybook/preview.tsx

@@ -1,3 +1,4 @@
+import './scoping.js';
 import '@ui5/webcomponents-icons/dist/AllIcons.js';
 import '@ui5/webcomponents-base/dist/features/F6Navigation.js';
 import type { Preview } from '@storybook/react';

.storybook/scoping.ts

@@ -0,0 +1,3 @@
+import { setCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
+
+setCompatCustomElementsScopingSuffix('compat');

packages/cli/README.md

@@ -16,7 +16,7 @@ You can find an interactive documentation in our [Storybook](https://sap.github.
 
 - [Wrapper generation](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/knowledge-base-bring-your-own-web-components--docs)
 - [Code-mod](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/migration-guide--docs#codemod)
-- [Patch compatibility table](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/legacy-components-docs--docs#experimental-patch-script)
+- ~~[Patch compatibility table](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/legacy-components-docs--docs#experimental-patch-script)~~ (deprecated in favor of [compatibility package scoping](https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/legacy-components-docs--docs#using-the-compat-v1-table-together-with-the-v2-table-in-one-application))
 
 ## Contribute
 

packages/cli/src/bin/index.ts

@@ -125,7 +125,9 @@ switch (command) {
 
   case 'patch-compat-table': {
     const patchesPath = relative(process.cwd(), fileURLToPath(new URL('../../patches', import.meta.url)));
-
+    console.warn(
+      'This command is deprecated and will be removed in the future. Please apply scoping to the "compat" table and its subcomponents manually: https://sap.github.io/ui5-webcomponents-react/v2/?path=/docs/legacy-components-docs--docs#using-the-compat-v1-table-together-with-the-v2-table-in-one-application',
+    );
     try {
       await $`patch-package --patch-dir ${patchesPath}`;
       console.log('Patches applied successfully!');

packages/compat/README.md

@@ -14,13 +14,13 @@ Components in this package will not receive any new features. Only critical bugs
 npm install @ui5/webcomponents-react-compat
 ```
 
-> ⚠️ **Warning:** It is not supported using the v1 `Table` and the v2 `Table` in the same application!
+> ⚠️ **Warning:** It is not supported using the v1 `Table` and the v2 `Table` in the same application without "compat" package scoping!
 
 > ⚠️ **Warning:** Please only import components from this package via the file path!
 
 ## Compatibility
 
-The legacy v1 (compat) `Table` and the modern v2 `Table` component and some subcomponents both register the same custom element names for `ui5-table`, `ui5-table-row` and `ui5-table-cell`, which will lead to conflicts when they coexist in the same application.
+The legacy v1 (compat) `Table` and the modern v2 `Table` component and some subcomponents both register the same custom element names for `ui5-table`, `ui5-table-row` and `ui5-table-cell`, which will lead to conflicts when they coexist in the same application. To solve this, please see the section about scoping below.
 
 ### Recommendation
 
@@ -44,13 +44,32 @@ Following are the imports of duplicate custom element names:
 - `TableCell` (`ui5-table-cell`): `import "@ui5/webcomponents-compat/dist/TableCell.js";`
 - `TableRow` (`ui5-table-row`): `import "@ui5/webcomponents-compat/dist/TableRow.js";`
 
-### Experimental Patch Script
+### Using the Compat (v1) Table Together with the v2 Table in One Application
+
+As of **v2.12.0** of `@ui5/webcomponents-compat`, a dedicated **scoping mechanism** is available for custom elements from the compat package.
+
+> **Note:** This feature is different from the general [scoping mechanism](https://sap.github.io/ui5-webcomponents/docs/advanced/scoping/) and applies **only** to custom elements from the compatibility package (Table and its subcomponents).
+
+Setting up scoping for the compat package is done in the same way as general scoping, but with specific methods coming from `@ui5/webcomponents-compat`.
+
+```js
+//scoping.js
+import { setCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
+setCompatCustomElementsScopingSuffix('compat');
+
+// app main file, e.g index.js, main.tsx, etc.
+import './scoping.js';
+// now, all other component imports - the scoping config import must be the first import of the app
+import { Table } from '@ui5/webcomponents-react-compat';
+```
+
+### Experimental Patch Script (deprecated)
+
+> ⚠️ **Deprecated**: This script is deprecated in favor of scoping the "compat" package components!
 
 The `patch-compat-table` script (included in the `@ui5/webcomponents-react-cli` package) is developed to address specific compatibility issues that arise when using the legacy v1 Table component in conjunction with the `FilterBar` or `VariantManagement` components. These components internally rely on the v2 `Table`, and therefore conflicts will occur when using the v1 `Table`.
 The script will change the custom element name by adding a `-v1` suffix (via [patch-package](https://github.com/ds300/patch-package)) to all duplicate v1 table components.
 
-> ⚠️ **Experimental**: This script is in experimental state and not subject to semantic versioning.
-
 > ⚠️ **Temporary Solution:** This script is intended as a temporary workaround. It is strongly recommended to plan for a migration to the v2 Table component to ensure long-term compatibility and support.
 
 <details style="cursor:auto;">

packages/compat/src/components/Table/Table.mdx

@@ -16,7 +16,7 @@ import * as ComponentStories from './Table.stories';
   children={
     <Text>
       Using the Table from the <code>compat</code> package and the <code>main</code> package in the same application is
-      not supported!
+      not supported without scoping the compat package.
     </Text>
   }
   design="Critical"

packages/compat/src/components/Table/index.tsx

@@ -8,10 +8,14 @@ import type {
 import type { TableRowClickEventDetail } from '@ui5/webcomponents-compat/dist/TableRow.js';
 import type TableGrowingMode from '@ui5/webcomponents-compat/dist/types/TableGrowingMode.js';
 import type TableMode from '@ui5/webcomponents-compat/dist/types/TableMode.js';
+import { getCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
 import type { CommonProps, Ui5CustomEvent, Ui5DomRef, UI5WCSlotsNode } from '@ui5/webcomponents-react-base';
 import { withWebComponent } from '@ui5/webcomponents-react-base/dist/wrapper/withWebComponent.js';
 import type { ReactNode } from 'react';
 
+const compatScopingSuffix = getCompatCustomElementsScopingSuffix();
+const tagSuffix = compatScopingSuffix ? `-${compatScopingSuffix}` : '';
+
 interface TableAttributes {
   /**
    * Defines the accessible ARIA name of the component.
@@ -269,7 +273,7 @@ interface TablePropTypes
  * @deprecated Deprecated as of version 2.12.0, use `@ui5/webcomponents/dist/Table.js` instead.
  */
 const Table = withWebComponent<TablePropTypes, TableDomRef>(
-  'ui5-table',
+  `ui5-table${tagSuffix}`,
   [
     'accessibleName',
     'accessibleNameRef',

packages/compat/src/components/TableCell/index.tsx

@@ -1,10 +1,14 @@
 'use client';
 
 import '@ui5/webcomponents-compat/dist/TableCell.js';
+import { getCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
 import type { CommonProps, Ui5DomRef } from '@ui5/webcomponents-react-base';
 import { withWebComponent } from '@ui5/webcomponents-react-base/dist/wrapper/withWebComponent.js';
 import type { ReactNode } from 'react';
 
+const compatScopingSuffix = getCompatCustomElementsScopingSuffix();
+const tagSuffix = compatScopingSuffix ? `-${compatScopingSuffix}` : '';
+
 interface TableCellAttributes {}
 
 interface TableCellDomRef extends Required<TableCellAttributes>, Ui5DomRef {}
@@ -22,7 +26,7 @@ interface TableCellPropTypes extends TableCellAttributes, Omit<CommonProps, 'chi
  * __Note__: This is a UI5 Web Component! [Repository](https://github.com/SAP/ui5-webcomponents) | [Documentation](https://sap.github.io/ui5-webcomponents/)
  * @deprecated Deprecated as of version 2.12.0, use `@ui5/webcomponents/dist/TableCell.js` instead.
  */
-const TableCell = withWebComponent<TableCellPropTypes, TableCellDomRef>('ui5-table-cell', [], [], [], []);
+const TableCell = withWebComponent<TableCellPropTypes, TableCellDomRef>(`ui5-table-cell${tagSuffix}`, [], [], [], []);
 
 TableCell.displayName = 'TableCell';
 

packages/compat/src/components/TableColumn/index.tsx

@@ -2,10 +2,14 @@
 
 import '@ui5/webcomponents-compat/dist/TableColumn.js';
 import type TableColumnPopinDisplay from '@ui5/webcomponents-compat/dist/types/TableColumnPopinDisplay.js';
+import { getCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
 import type { CommonProps, Ui5DomRef } from '@ui5/webcomponents-react-base';
 import { withWebComponent } from '@ui5/webcomponents-react-base/dist/wrapper/withWebComponent.js';
 import type { ReactNode } from 'react';
 
+const compatScopingSuffix = getCompatCustomElementsScopingSuffix();
+const tagSuffix = compatScopingSuffix ? `-${compatScopingSuffix}` : '';
+
 interface TableColumnAttributes {
   /**
    * According to your `minWidth` settings, the component can be hidden
@@ -64,7 +68,7 @@ interface TableColumnPropTypes
  * @deprecated Deprecated as of version 2.12.0, use `@ui5/webcomponents/dist/Table.js` instead.
  */
 const TableColumn = withWebComponent<TableColumnPropTypes, TableColumnDomRef>(
-  'ui5-table-column',
+  `ui5-table-column${tagSuffix}`,
   ['minWidth', 'popinDisplay', 'popinText'],
   ['demandPopin'],
   [],

packages/compat/src/components/TableGroupRow/index.tsx

@@ -1,10 +1,14 @@
 'use client';
 
 import '@ui5/webcomponents-compat/dist/TableGroupRow.js';
+import { getCompatCustomElementsScopingSuffix } from '@ui5/webcomponents-compat/dist/utils/CompatCustomElementsScope.js';
 import type { CommonProps, Ui5DomRef } from '@ui5/webcomponents-react-base';
 import { withWebComponent } from '@ui5/webcomponents-react-base/dist/wrapper/withWebComponent.js';
 import type { ReactNode } from 'react';
 
+const compatScopingSuffix = getCompatCustomElementsScopingSuffix();
+const tagSuffix = compatScopingSuffix ? `-${compatScopingSuffix}` : '';
+
 interface TableGroupRowAttributes {}
 
 interface TableGroupRowDomRef extends Required<TableGroupRowAttributes>, Ui5DomRef {}
@@ -27,7 +31,7 @@ interface TableGroupRowPropTypes extends TableGroupRowAttributes, Omit<CommonPro
  * @deprecated Deprecated as of version 2.12.0, use `@ui5/webcomponents/dist/Table.js` instead.
  */
 const TableGroupRow = withWebComponent<TableGroupRowPropTypes, TableGroupRowDomRef>(
-  'ui5-table-group-row',
+  `ui5-table-group-row${tagSuffix}`,
   [],
   [],
   [],