feat(ObjectPageSection): add tabRef prop (#7590)

Closes #7589
Related issue: #4369

Author: Lukas742

packages/main/src/components/ObjectPage/ObjectPage.cy.tsx

@@ -7,7 +7,7 @@ import TitleLevel from '@ui5/webcomponents/dist/types/TitleLevel.js';
 import ValueState from '@ui5/webcomponents-base/dist/types/ValueState.js';
 import IllustrationMessageType from '@ui5/webcomponents-fiori/dist/types/IllustrationMessageType.js';
 import type { CSSProperties } from 'react';
-import { useEffect, useReducer, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useReducer, useRef, useState } from 'react';
 import type { ObjectPagePropTypes } from '../..';
 import {
   CheckBox,
@@ -45,6 +45,7 @@ import {
   ToolbarButton,
 } from '../..';
 import { cypressPassThroughTestsFactory } from '@/cypress/support/utils';
+import type { TabDomRef } from '../../webComponents/Tab/index.js';
 
 const arbitraryCharsId = `~\`!1@#$%^&*()-_+={}[]:;"'z,<.>/?|♥`;
 
@@ -1432,6 +1433,45 @@ describe('ObjectPage', () => {
     cy.get('footer').should('have.attr', 'role', 'contentinfo');
   });
 
+  it('tabRef', () => {
+    const TestComp = () => {
+      const tabRef = useRef(null);
+
+      useLayoutEffect(() => {
+        if (tabRef.current) {
+          requestAnimationFrame(() => {
+            tabRef.current.getDomRefInStrip().setAttribute('data-hello', 'true');
+          });
+        }
+      }, []);
+
+      return (
+        <ObjectPage>
+          <ObjectPageSection
+            id="0"
+            titleText="callbackRef"
+            tabRef={(node: TabDomRef | null) => {
+              if (node) {
+                requestAnimationFrame(() => {
+                  node.getDomRefInStrip().setAttribute('data-hello', 'true');
+                });
+              }
+            }}
+          >
+            Content
+          </ObjectPageSection>
+          <ObjectPageSection id="1" titleText="refObject" tabRef={tabRef}>
+            Content
+          </ObjectPageSection>
+        </ObjectPage>
+      );
+    };
+
+    cy.mount(<TestComp />);
+
+    cy.get('[data-hello="true"]').should('be.visible').should('have.length', 2);
+  });
+
   cypressPassThroughTestsFactory(ObjectPage);
 
   it('focus behavior & keyboard navigation', () => {

packages/main/src/components/ObjectPage/index.tsx

@@ -724,6 +724,7 @@ const ObjectPage = forwardRef<ObjectPageDomRef, ObjectPagePropTypes>((props, ref
                 return (
                   <Tab
                     key={`Anchor-${section.props?.id}`}
+                    ref={section.props.tabRef}
                     data-index={index}
                     data-section-id={section.props.id}
                     text={section.props.titleText}

packages/main/src/components/ObjectPageSection/index.tsx

@@ -3,10 +3,11 @@
 import type TitleLevel from '@ui5/webcomponents/dist/types/TitleLevel.js';
 import { useStylesheet, useSyncRef } from '@ui5/webcomponents-react-base';
 import { clsx } from 'clsx';
-import type { ReactNode, FocusEventHandler, KeyboardEventHandler, FocusEvent } from 'react';
+import type { ReactNode, FocusEventHandler, KeyboardEventHandler, FocusEvent, Ref } from 'react';
 import { Children, isValidElement, forwardRef, useMemo } from 'react';
 import { ObjectPageMode } from '../../enums/ObjectPageMode.js';
 import type { CommonProps } from '../../types/index.js';
+import type { TabDomRef } from '../../webComponents/Tab/index.js';
 import { useObjectPageContext } from '../ObjectPage/context.js';
 import { navigateSections } from '../ObjectPage/ObjectPageUtils.js';
 import { classNames, styleData } from './ObjectPageSection.module.css.js';
@@ -57,6 +58,12 @@ export interface ObjectPageSectionPropTypes extends CommonProps {
    * __Note__: Although this prop accepts all HTML Elements, it is strongly recommended that you only use non-focusable elements to preserve the intended design.
    */
   header?: ReactNode;
+  // the ref is applied in the ObjectPage
+  /**
+   * This ref will be attached to the underlying `ui5-tab` DOM element,
+   * allowing direct access to its instance methods and properties (e.g. `getDomRefInStrip`).
+   */
+  tabRef?: Ref<TabDomRef>;
 }
 
 function recursiveSetTabIndexOnSubSection(el: HTMLElement | null, currentTarget: HTMLElement): void {
@@ -121,6 +128,9 @@ const ObjectPageSection = forwardRef<HTMLElement, ObjectPageSectionPropTypes>((p
     header,
     ...rest
   } = props;
+
+  const { tabRef: _0, ...propsWithoutOmitted } = rest;
+
   useStylesheet(styleData, ObjectPageSection.displayName);
   const [componentRef, sectionRef] = useSyncRef(ref);
   const htmlId = `ObjectPageSection-${id}`;
@@ -227,7 +237,7 @@ const ObjectPageSection = forwardRef<HTMLElement, ObjectPageSectionPropTypes>((p
       className={clsx(classNames.section, wrapTitleText && classNames.wrap, className)}
       style={style}
       tabIndex={objectPageMode === ObjectPageMode.Default ? -1 : 0}
-      {...rest}
+      {...propsWithoutOmitted}
       id={htmlId}
       data-component-name="ObjectPageSection"
       onFocus={objectPageMode === ObjectPageMode.Default ? handleFocusDefault : handleFocusIconTabBar}