docs(Toolbar): outline how to open popovers (#6741)

Fixes #6739

Author: Lukas742

packages/main/src/components/ObjectPage/ObjectPage.mdx

@@ -64,8 +64,6 @@ This component exposes public methods. You can use them directly on the instance
   </tbody>
 </table>
 
-# More Examples
-
 ## ObjectPage with IllustratedMessage (`UnableToLoad`) placeholder
 
 <Canvas of={ComponentStories.WithIllustratedMessage} />
@@ -90,6 +88,10 @@ To render a single section in fullscreen mode, set its height to `100%`.
 </ObjectPageSection>
 ```
 
+## Opening popover components by pressing an action
+
+Please see the [Docs](?path=/docs/layouts-floorplans-toolbar--docs#open-popovers-with-toolbarbutton) of the `Toolbar` component.
+
 ## Legacy Toolbar Support
 
 The ObjectPage still supports the old (React-only) `Toolbar` implementation. Please only use this toolbar if your app is dependent on some features the `Toolbar` web component is currently not offering.

packages/main/src/webComponents/DynamicPage/DynamicPage.mdx

@@ -112,4 +112,8 @@ function DynamicPageWithStickyContent(props) {
 }
 ```
 
+## Opening popover components by pressing an action
+
+Please see the [Docs](?path=/docs/layouts-floorplans-toolbar--docs#open-popovers-with-toolbarbutton) of the `Toolbar` component.
+
 <Footer />

packages/main/src/webComponents/Toolbar/Toolbar.mdx

@@ -18,6 +18,47 @@ import * as ComponentStories from './Toolbar.stories';
 
 <ControlsWithNote of={ComponentStories.Default} />
 
+## Opening Popovers via ToolbarButton
+
+Since the `ToolbarButton` is an [abstract UI5 web component](?path=/docs/knowledge-base-faq--docs#what-are-abstract-ui5-web-components), the opener of the `Popover` needs the DOM reference of the actual element to position the popover correctly.
+Starting with v2.5.0 of `@ui5/webcomponents(-react)`, the `detail` property of the `ToolbarButton`'s click handler now includes a `targetRef` property, which can be used as the opener.
+
+<Canvas of={ComponentStories.OpenPopover} />
+
+### Example Code
+
+```tsx
+function ToolbarWithPopover() {
+  const [popoverOpen, setPopoverOpen] = useState(false);
+  const popoverRef = useRef<PopoverDomRef>(null);
+  return (
+    <>
+      <Toolbar>
+        <ToolbarButton
+          onClick={(e) => {
+            const { targetRef } = e.detail;
+            if (popoverRef.current) {
+              popoverRef.current.opener = targetRef;
+              setPopoverOpen(true);
+            }
+          }}
+          text="Open Popover"
+        />
+      </Toolbar>
+      <Popover
+        open={popoverOpen}
+        ref={popoverRef}
+        onClose={() => {
+          setPopoverOpen(false);
+        }}
+      >
+        Content
+      </Popover>
+    </>
+  );
+}
+```
+
 <Markdown>{SubcomponentsSection}</Markdown>
 
 ## ToolbarButton

packages/main/src/webComponents/Toolbar/Toolbar.stories.tsx

@@ -1,5 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import ToolbarAlign from '@ui5/webcomponents/dist/types/ToolbarAlign.js';
+import { useRef, useState } from 'react';
+import { Popover } from '../Popover/index.js';
+import type { PopoverDomRef } from '../Popover/index.js';
 import { ToolbarButton } from '../ToolbarButton/index.js';
 import { ToolbarSelect } from '../ToolbarSelect/index.js';
 import { ToolbarSelectOption } from '../ToolbarSelectOption/index.js';
@@ -43,3 +46,36 @@ export const Default: Story = {
     </Toolbar>
   )
 };
+
+export const OpenPopover: Story = {
+  name: 'Opening Popovers via ToolbarButton',
+  render(args) {
+    const [popoverOpen, setPopoverOpen] = useState(false);
+    const popoverRef = useRef<PopoverDomRef>(null);
+    return (
+      <>
+        <Toolbar {...args}>
+          <ToolbarButton
+            onClick={(e) => {
+              const { targetRef } = e.detail;
+              if (popoverRef.current) {
+                popoverRef.current.opener = targetRef;
+                setPopoverOpen(true);
+              }
+            }}
+            text="Open Popover"
+          />
+        </Toolbar>
+        <Popover
+          open={popoverOpen}
+          ref={popoverRef}
+          onClose={() => {
+            setPopoverOpen(false);
+          }}
+        >
+          Content
+        </Popover>
+      </>
+    );
+  }
+};