docs(Toolbar): add popover inside overflow popover story (#4636)

Co-authored-by: Marcus Notheis <[email protected]>

Author: Lukas742

packages/main/src/components/Toolbar/Toolbar.mdx

@@ -85,7 +85,7 @@ It is furthermore possible to prevent the popover from opening by using `event.p
 
 <Canvas of={ComponentStories.CustomOverflowButton} />
 
-### Close overflow popover on interaction
+## Close overflow popover on interaction
 
 The overflow popover can be closed programmatically by using the `overflowPopoverRef`.
 
@@ -110,6 +110,103 @@ const ToolbarComponent = () => {
 };
 ```
 
+## Open Popovers by ID inside the overflow popover
+
+To prevent duplicate child `id`s in the DOM, all child `id`s get an `-overflow` suffix. If an ID is used to open the popover (e.g. via the `opener` prop), you have to make sure to use the correct id.
+You can achieve that either by leveraging the `onOverflowChange` event and retrieve the current ID there, or by updating it inside the `click` handler of the respective opener component.
+
+<Canvas of={ComponentStories.PopoverInOverflowPopover} sourceState="none" />
+
+<details>
+
+<summary>Set opener ID via click handler</summary>
+
+```jsx
+const ToolbarComponent = () => {
+  const [popoverIsOpen, setPopoverIsOpen] = useState(false);
+  const [opener, setOpener] = useState('openMenuBtn');
+  const handlePopoverOpenerClick = (e) => {
+    setOpener(e.target.id);
+    setPopoverIsOpen(true);
+  };
+  return (
+    <>
+      <Toolbar style={{ width: '400px' }}>
+        <Text>Toolbar</Text>
+        <Button>Button One</Button>
+        <Button>Button Two</Button>
+        <Button id="openMenuBtn" onClick={handlePopoverOpenerClick}>
+          Open Popover (Menu)
+        </Button>
+      </Toolbar>
+      <Menu
+        opener={opener}
+        open={popoverIsOpen}
+        onAfterClose={() => {
+          setPopoverIsOpen(false);
+        }}
+      >
+        <MenuItem text="New File" />
+        <MenuItem text="New Folder" />
+      </Menu>
+    </>
+  );
+};
+```
+
+</details>
+    
+<details>
+
+<summary>Set opener ID via onOverflowChange handler</summary>
+
+```jsx
+const ToolbarComponent = () => {
+  const [popoverIsOpen, setPopoverIsOpen] = useState(false);
+  const initialOpenerId = 'openMenuBtn';
+  const [opener, setOpener] = useState(initialOpenerId);
+  const handlePopoverOpenerClick = () => {
+    setPopoverIsOpen(true);
+  };
+  const handleOverflowChange = (e) => {
+    if (e.overflowElements?.length) {
+      const overflowId = [...e.overflowElements].find((item) => item.dataset.opener)?.id;
+      if (overflowId) {
+        setOpener(overflowId);
+      } else {
+        setOpener(initialOpenerId);
+      }
+    } else {
+      setOpener(initialOpenerId);
+    }
+  };
+  return (
+    <>
+      <Toolbar style={{ width: '400px' }} onOverflowChange={handleOverflowChange}>
+        <Text>Toolbar</Text>
+        <Button>Button One</Button>
+        <Button>Button Two</Button>
+        <Button id="openMenuBtn" onClick={handlePopoverOpenerClick} data-opener>
+          Open Popover (Menu)
+        </Button>
+      </Toolbar>
+      <Menu
+        opener={opener}
+        open={popoverIsOpen}
+        onAfterClose={() => {
+          setPopoverIsOpen(false);
+        }}
+      >
+        <MenuItem text="New File" />
+        <MenuItem text="New Folder" />
+      </Menu>
+    </>
+  );
+};
+```
+
+</details>
+
 <Markdown>{SubcomponentsSection}</Markdown>
 
 ## OverflowToolbarButton

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

@@ -9,6 +9,8 @@ import { Button } from '../../webComponents/Button/index.js';
 import { DatePicker } from '../../webComponents/DatePicker/index.js';
 import { Icon } from '../../webComponents/Icon/index.js';
 import { Input } from '../../webComponents/Input/index.js';
+import { Menu } from '../../webComponents/Menu/index.js';
+import { MenuItem } from '../../webComponents/MenuItem/index.js';
 import { Select } from '../../webComponents/Select/index.js';
 import { Slider } from '../../webComponents/Slider/index.js';
 import { Switch } from '../../webComponents/Switch/index.js';
@@ -103,6 +105,40 @@ export const WithSeparator: Story = {
   }
 };
 
+export const PopoverInOverflowPopover: Story = {
+  name: 'Popover in Overflow Popover',
+  render(args) {
+    const [popoverIsOpen, setPopoverIsOpen] = useState(false);
+    const [opener, setOpener] = useState('openMenuBtn');
+    const handlePopoverOpenerClick = (e) => {
+      setOpener(e.target.id);
+      setPopoverIsOpen(true);
+    };
+    return (
+      <>
+        <Toolbar {...args} style={{ width: '400px' }}>
+          <Text>Toolbar</Text>
+          <Button>Button One</Button>
+          <Button>Button Two</Button>
+          <Button id="openMenuBtn" onClick={handlePopoverOpenerClick}>
+            Open Popover (Menu)
+          </Button>
+        </Toolbar>
+        <Menu
+          opener={opener}
+          open={popoverIsOpen}
+          onAfterClose={() => {
+            setPopoverIsOpen(false);
+          }}
+        >
+          <MenuItem text="New File" />
+          <MenuItem text="New Folder" />
+        </Menu>
+      </>
+    );
+  }
+};
+
 export const WithOverflowButton: Story = {
   name: 'with overflow button',
   render(args) {

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

@@ -110,6 +110,8 @@ const OVERFLOW_BUTTON_WIDTH = 36 + 8 + 8; // width + padding end + spacing start
  * It can be accessed by the user through the overflow button that opens it in a popover.
  *
  * __Note:__ The overflow popover is mounted only when the overflow button is displayed, i.e., any child component of the popover will be remounted, when moved into it.
+ *
+ * __Note:__ To prevent duplicate child `id`s in the DOM, all child `id`s get an `-overflow` suffix. This is especially important when popovers are opened by id.
  */
 const Toolbar = forwardRef<HTMLDivElement, ToolbarPropTypes>((props, ref) => {
   const {