feat: create dom ref interfaces for all web components (#2292)

BREAKING CHANGE: **TypeScript only**: The `Ui5` prefix for interfaces for using DOM refs (e.g. `Ui5DialogDomRef`) has been removed (now `DialogDomRef`) and the interfaces are now exported from the respective components themselves. For details please check our [Migration Guide](https://sap.github.io/ui5-webcomponents-react/?path=/docs/migration-guide--page#changed-typescript-interfaces-for-ref).

Co-authored-by: Harbarth, Lukas <lukas.harbarth@sap.com>

Author: MarcusNotheis

.eslintrc.cjs

@@ -133,7 +133,8 @@ module.exports = {
         '@typescript-eslint/semi': ['error', 'always'],
         '@typescript-eslint/space-within-parens': ['off', 'never'],
         '@typescript-eslint/type-annotation-spacing': 'error',
-        '@typescript-eslint/unified-signatures': 'error'
+        '@typescript-eslint/unified-signatures': 'error',
+        '@typescript-eslint/no-empty-interface': 'warn'
       }
     }
   ]

docs/1-Welcome.stories.mdx

@@ -151,10 +151,10 @@ Example - `Popover` with `Ref` type declaration:
 ```tsx
 import React, { useRef } from 'react';
 import { ThemeProvider, Button, Popover } from '@ui5/webcomponents-react';
-import { Ui5PopoverDomRef } from '@ui5/webcomponents-react/interfaces/Ui5PopoverDomRef';
+import { PopoverDomRef } from '@ui5/webcomponents-react/dist/Popover';
 
 export default function App() {
-  const popoverRef = useRef<Ui5PopoverDomRef>(null);
+  const popoverRef = useRef<PopoverDomRef>(null);
   const onClick = (e: React.MouseEvent<HTMLElement, MouseEvent>) => {
     popoverRef.current?.showAt(e.target);
   };

docs/2-MigrationGuide.stories.mdx

@@ -17,6 +17,73 @@ or the [changelog](https://github.com/SAP/ui5-webcomponents-react/blob/main/CHAN
 
 <TableOfContent headingSelector="h2.sbdocs-h2" />
 
+## Migrating from 0.19.x to 0.20.0
+
+### Changed TypeScript `interfaces` for `ref`
+
+TypeScript `interfaces` that can be used for accessing the DOM-`ref` of a component have been updated:
+
+- The `Ui5` prefix has been removed
+- The `interfaces` can now be imported from the component itself
+
+Migration Path:
+
+```tsx
+import { Dialog } from '@ui5/webcomponents-react';
+import { Ui5DialogDomRef } from '@ui5/webcomponents-react/interfaces/Ui5DialogDomRef';
+import { useRef } from 'react';
+
+function MyOldComponent() {
+  const ref = useRef<Ui5DialogDomRef>(null);
+  return <Dialog ref={ref} />;
+}
+
+// becomes
+
+import { Dialog } from '@ui5/webcomponents-react';
+import { DialogDomRef } from '@ui5/webcomponents-react/dist/Dialog';
+import { useRef } from 'react';
+
+function MyNewComponent() {
+  const ref = useRef<DialogDomRef>(null);
+  return <Dialog ref={ref} />;
+}
+```
+
+Affected Interfaces:
+
+- `Ui5BarcodeScannerDialogDomRef` <br />
+  new import: `import { BarcodeScannerDialogDomRef } from '@ui5/webcomponents-react/dist/BarcodeScannerDialog';`
+- `Ui5CarouselDomRef`<br />
+  new import: `import { CarouselDomRef } from '@ui5/webcomponents-react/dist/Carousel';`
+- `Ui5DatePickerDomRef`<br />
+  new import: `import { DatePickerDomRef } from '@ui5/webcomponents-react/dist/DatePicker';`
+- `Ui5DateRangePickerDomRef`<br />
+  new import: `import { DateRangePickerDomRef } from '@ui5/webcomponents-react/dist/DateRangePicker';`
+- `Ui5DateTimePickerDomRef`<br />
+  new import: `import { DateTimePickerDomRef } from '@ui5/webcomponents-react/dist/DateTimePicker';`
+- `Ui5DialogDomRef`<br />
+  new import: `import { DialogDomRef } from '@ui5/webcomponents-react/dist/Dialog';`
+- `Ui5PopoverDomRef`<br />
+  new import: `import { PopoverDomRef } from '@ui5/webcomponents-react/dist/Popover';`
+- `Ui5ResponsivePopoverDomRef`<br />
+  new import: `import { ResponsivePopoverDomRef } from '@ui5/webcomponents-react/dist/ResponsivePopover';`
+- `Ui5ShellBarDomRef`<br />
+  new import: `import { ShellBarDomRef } from '@ui5/webcomponents-react/dist/ShellBar';`
+- `Ui5TimePickerDomRef`<br />
+  new import: `import { TimePickerDomRef } from '@ui5/webcomponents-react/dist/TimePicker';`
+- `Ui5ToastDomRef`<br />
+  new import: `import { ToastDomRef } from '@ui5/webcomponents-react/dist/Toast';`
+- `Ui5TreeDomRef`<br />
+  new import: `import { TreeDomRef } from '@ui5/webcomponents-react/dist/Tree';`
+- `Ui5TreeItemDomRef`<br />
+  new import: `import { TreeItemDomRef } from '@ui5/webcomponents-react/dist/TreeItem';`
+
+- `AnalyticalTableDomRef`<br />
+  new import: `import { AnalyticalTableDomRef } from '@ui5/webcomponents-react/dist/AnalyticalTable';`
+- `MessageViewDomRef`<br />
+  new import: `import { MessageViewDomRef } from '@ui5/webcomponents-react/dist/MessageView';`
+
 ## Migrating from 0.18.x to 0.19.0
 
 ### VariantManagement

packages/main/scripts/create-web-components-wrapper.mjs

@@ -11,6 +11,7 @@ import Handlebars from 'handlebars';
 import * as Utils from '../../../scripts/web-component-wrappers/utils.js';
 import {
   COMPONENTS_WITHOUT_DEMOS,
+  KNOWN_ATTRIBUTES,
   KNOWN_EVENTS,
   PRIVATE_COMPONENTS
 } from '../../../scripts/web-component-wrappers/config.js';
@@ -291,58 +292,72 @@ const getEventParameters = (name, parameters) => {
 };
 
 const createWebComponentWrapper = async (
-  name,
-  tag,
+  componentSpec,
   description,
-  types,
+  attributes,
+  slotsAndEvents,
   importStatements,
-  ref,
   defaultProps,
   regularProps,
   booleanProps,
   slotProps,
   eventProps
 ) => {
-  const eventsToBeOmitted = eventProps.filter((eventName) => KNOWN_EVENTS.has(eventName));
+  const eventsToBeOmitted = eventProps
+    .filter((eventName) => KNOWN_EVENTS.has(eventName))
+    .map((eventName) => `'on${capitalizeFirstLetter(snakeToCamel(eventName))}'`);
+  const attributesToBeOmitted = [...regularProps, ...booleanProps]
+    .filter((attribute) => KNOWN_ATTRIBUTES.has(attribute))
+    .map((a) => `'${a}'`);
+
+  let domRefExtends = 'Ui5DomRef';
+  if (attributesToBeOmitted.length > 0) {
+    domRefExtends = `Omit<Ui5DomRef, ${attributesToBeOmitted.join(' | ')}>`;
+  }
+
   let tsExtendsStatement = 'CommonProps';
-  if (eventsToBeOmitted.length > 0) {
-    tsExtendsStatement = `Omit<CommonProps, ${eventsToBeOmitted
-      .map((eventName) => `'on${capitalizeFirstLetter(snakeToCamel(eventName))}'`)
-      .join(' | ')}>`;
+  if (eventsToBeOmitted.length > 0 || attributesToBeOmitted.length > 0) {
+    tsExtendsStatement = `Omit<CommonProps, ${[...attributesToBeOmitted, ...eventsToBeOmitted].join(' | ')}>`;
   }
   let componentDescription;
   try {
     componentDescription = turndownService.turndown(description).replace(/\n/g, '\n * ');
   } catch (e) {
     console.warn(
-      `----------------------\nHeader description of ${name} couldn't be generated. \nThere is probably a syntax error in the associated description that can't be fixed automatically.\n----------------------`
+      `----------------------\nHeader description of ${componentSpec.module} couldn't be generated. \nThere is probably a syntax error in the associated description that can't be fixed automatically.\n----------------------`
     );
     componentDescription = '';
   }
 
+  const domRef = Utils.createDomRef(componentSpec);
+
   const imports = [
     ...importStatements,
     '', // do not remove this empty line - otherwise the eslint/import-order plugin won't work as expected
-    `import '@ui5/webcomponents${componentsFromFioriPackage.has(name) ? '-fiori' : ''}/dist/${name}.js';`
+    `import '@ui5/webcomponents${componentsFromFioriPackage.has(componentSpec.module) ? '-fiori' : ''}/dist/${
+      componentSpec.module
+    }.js';`
   ];
 
   return prettier.format(
     await Utils.runEsLint(
       componentTemplate({
-        name,
+        name: componentSpec.module,
         imports,
         propTypesExtends: tsExtendsStatement,
-        types,
+        domRefExtends,
+        attributes,
+        slotsAndEvents,
         description: componentDescription,
-        tagName: tag,
+        tagName: componentSpec.tagname,
         regularProps,
         booleanProps,
         slotProps: slotProps.filter((name) => name !== 'children'),
         eventProps,
         defaultProps,
-        ref: ref?.tsType
+        domRef
       }),
-      name
+      componentSpec.module
     ),
     Utils.prettierConfig
   );
@@ -570,59 +585,55 @@ const resolveInheritedAttributes = (componentSpec) => {
   );
 });
 
+const propDescription = (componentSpec, property) => {
+  if (!componentSpec.tagname) {
+    return property.description || '';
+  }
+  let formattedDescription = turndownService.turndown((property.description || '').trim()).replace(/\n/g, '\n   * ');
+
+  const customDescriptionReplace = CUSTOM_DESCRIPTION_REPLACE[componentSpec.module];
+  if (customDescriptionReplace && customDescriptionReplace[property.name]) {
+    formattedDescription = customDescriptionReplace[property.name](formattedDescription);
+  }
+
+  const extendedDescription = EXTENDED_PROP_DESCRIPTION[property.name];
+
+  if (property.name !== 'children' && componentSpec?.slots?.some((item) => item.name === property.name)) {
+    formattedDescription += `
+          *
+          * __Note:__ When passing a custom React component to this prop, you have to make sure your component reads the \`slot\` prop and appends it to the most outer element of your component.
+          * Learn more about it [here](https://sap.github.io/ui5-webcomponents-react/?path=/docs/knowledge-base--page#adding-custom-components-to-slots).`;
+  }
+
+  if (extendedDescription) {
+    return replaceTagNameWithModuleName(`${formattedDescription}${extendedDescription}`);
+  }
+  return replaceTagNameWithModuleName(formattedDescription);
+};
+
 allWebComponents
   .filter((spec) => spec.visibility === 'public')
   .filter((spec) => !PRIVATE_COMPONENTS.has(spec.module))
   .map(resolveInheritedAttributes)
   .forEach(async (componentSpec) => {
-    const propTypes = [];
+    const attributes = [];
+    const slotsAndEvents = [];
     const importStatements = [];
     const defaultProps = [];
-    const allComponentProperties = [...(componentSpec.properties || []), ...(componentSpec.slots || [])]
+    const allComponentProperties = (componentSpec.properties || [])
       .filter((prop) => prop.visibility === 'public' && prop.readonly !== 'true' && prop.static !== true)
       .map((property) => {
         const tsType = Utils.getTypeDefinitionForProperty(property);
         if (tsType.importStatement) {
           importStatements.push(tsType.importStatement);
         }
 
-        if (property.name === 'default') {
-          property.name = 'children';
-        }
-        const propDescription = () => {
-          if (!componentSpec.tagname) {
-            return property.description || '';
-          }
-          let formattedDescription = turndownService
-            .turndown((property.description || '').trim())
-            .replace(/\n/g, '\n   * ');
-
-          const customDescriptionReplace = CUSTOM_DESCRIPTION_REPLACE[componentSpec.module];
-          if (customDescriptionReplace && customDescriptionReplace[property.name]) {
-            formattedDescription = customDescriptionReplace[property.name](formattedDescription);
-          }
-
-          const extendedDescription = EXTENDED_PROP_DESCRIPTION[property.name];
-
-          if (property.name !== 'children' && componentSpec?.slots?.some((item) => item.name === property.name)) {
-            formattedDescription += `
-          *
-          * __Note:__ When passing a custom React component to this prop, you have to make sure your component reads the \`slot\` prop and appends it to the most outer element of your component.
-          * Learn more about it [here](https://sap.github.io/ui5-webcomponents-react/?path=/docs/knowledge-base--page#adding-custom-components-to-slots).`;
-          }
-
-          if (extendedDescription) {
-            return replaceTagNameWithModuleName(`${formattedDescription}${extendedDescription}`);
-          }
-          return replaceTagNameWithModuleName(formattedDescription);
-        };
-
-        propTypes.push(dedent`
-    /**
-     * ${propDescription()}
-     */
-     ${property.name}?: ${tsType.tsType};
-    `);
+        attributes.push(dedent`
+        /**
+         * ${propDescription(componentSpec, property)}
+         */
+         ${property.name}?: ${tsType.tsType};
+        `);
 
         if (
           property.hasOwnProperty('defaultValue') &&
@@ -646,6 +657,33 @@ allWebComponents
         };
       });
 
+    allComponentProperties.push(
+      ...(componentSpec.slots || [])
+        .filter((prop) => prop.visibility === 'public' && prop.readonly !== 'true' && prop.static !== true)
+        .map((property) => {
+          const tsType = Utils.getTypeDefinitionForProperty(property);
+          if (tsType.importStatement) {
+            importStatements.push(tsType.importStatement);
+          }
+
+          if (property.name === 'default') {
+            property.name = 'children';
+          }
+
+          slotsAndEvents.push(dedent`
+        /**
+         * ${propDescription(componentSpec, property)}
+         */
+         ${property.name}?: ${tsType.tsType};
+        `);
+
+          return {
+            ...property,
+            ...tsType
+          };
+        })
+    );
+
     (componentSpec.events || [])
       .filter((eventSpec) => eventSpec.visibility === 'public')
       .forEach((eventSpec) => {
@@ -666,7 +704,7 @@ allWebComponents
           eventParameters = getEventParameters(componentSpec.module, eventSpec.parameters || []);
         }
         importStatements.push(...eventParameters.importStatements);
-        propTypes.push(dedent`
+        slotsAndEvents.push(dedent`
       /**
        * ${replaceTagNameWithModuleName(
          turndownService.turndown((eventSpec.description || '').trim()).replace(/\n/g, '\n   * ')
@@ -676,8 +714,6 @@ allWebComponents
       `);
       });
 
-    const uniqueAdditionalImports = [...new Set(importStatements)];
-
     const formatDescription = () => {
       let description = componentSpec.description;
       if (!description) {
@@ -718,22 +754,16 @@ allWebComponents
       fs.writeFileSync(webComponentWrapperPath, '');
     }
 
-    const domRef = Utils.createDomRef(componentSpec);
-    if (domRef) {
-      uniqueAdditionalImports.push(domRef.importStatement);
-    }
-
     if (
       (CREATE_SINGLE_COMPONENT === componentSpec.module || !CREATE_SINGLE_COMPONENT) &&
       !EXCLUDE_LIST.includes(componentSpec.module)
     ) {
       const webComponentWrapper = await createWebComponentWrapper(
-        componentSpec.module,
-        componentSpec.tagname,
+        componentSpec,
         mainDescription,
-        propTypes,
-        uniqueAdditionalImports,
-        domRef,
+        attributes,
+        slotsAndEvents,
+        [...new Set(importStatements)],
         defaultProps,
         (componentSpec.properties || [])
           .filter(filterNonPublicAttributes)

packages/main/src/components/ActionSheet/ActionSheet.test.tsx

@@ -1,10 +1,10 @@
 import { fireEvent, render, screen } from '@shared/tests';
 import { createPassThroughPropsTest } from '@shared/tests/utils';
 import { ActionSheet } from '@ui5/webcomponents-react/dist/ActionSheet';
+import { PopoverDomRef } from '@ui5/webcomponents-react/dist/Popover';
 import { Button } from '@ui5/webcomponents-react/dist/Button';
 import { Label } from '@ui5/webcomponents-react/dist/Label';
 import React, { createRef, RefObject } from 'react';
-import { Ui5PopoverDomRef } from '../../interfaces/Ui5PopoverDomRef';
 
 describe('ActionSheet', () => {
   test('Render without Crashing', () => {
@@ -52,7 +52,7 @@ describe('ActionSheet', () => {
   });
 
   test('Ref object', () => {
-    const ref: RefObject<Ui5PopoverDomRef> = createRef();
+    const ref: RefObject<PopoverDomRef> = createRef();
     render(<ActionSheet ref={ref} />);
     expect((ref.current as any).tagName).toEqual('UI5-RESPONSIVE-POPOVER');
   });