use popover API in Tooltip if supported

.changeset/quick-ligers-serve.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-css': minor
+---
+
+Added support for `popover` attribute in `iui-tooltip`.

.changeset/tender-forks-visit.md

@@ -0,0 +1,5 @@
+---
+'@itwin/itwinui-react': minor
+---
+
+`Tooltip` will now automatically use the [`popover` API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) in supported browsers. This ensures that tooltips appear in the top layer, avoiding stacking context issues.

apps/website/src/content/docs/tooltip.mdx

@@ -37,7 +37,7 @@ There are some advanced props available for more granular control over positioni
 
 ### Portals
 
-It is important to know that before calculating the position, the tooltip gets [portaled](https://react.dev/reference/react-dom/createPortal) into the nearest [`ThemeProvider`](themeprovider) to avoid [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) issues. This behavior can be controlled using the Tooltip's `portal` prop or the ThemeProvider's [`portalContainer`](themeprovider#portals) prop.
+It is important to know that before calculating the position, the tooltip gets [portaled](https://react.dev/reference/react-dom/createPortal) into the nearest [`ThemeProvider`](themeprovider). This is done to avoid [stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context) issues in browsers where the [`popover` API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) is not supported. This portaling behavior can be controlled using the Tooltip's `portal` prop or the ThemeProvider's [`portalContainer`](themeprovider#portals) prop.
 
 ## Accessibility
 

packages/itwinui-css/src/tooltip/tooltip.scss

@@ -23,7 +23,7 @@
 
   @include mixins.iui-blur($hsl: 0 0% 0%, $opacity: 3);
 
-  &[hidden] {
+  &:where([hidden], [popover]:not(:popover-open)) {
     display: none !important;
   }
 }

packages/itwinui-react/src/core/Tooltip/Tooltip.test.tsx

@@ -20,6 +20,7 @@ it('should toggle the visibility of tooltip on hover', () => {
 
   const tooltip = getByText('some text');
   expect(tooltip).not.toBeVisible();
+  expect(tooltip).toHaveAttribute('popover', 'manual');
 
   fireEvent.mouseEnter(trigger);
   expect(tooltip).toBeVisible();
@@ -45,6 +46,7 @@ it('should toggle the visibility of tooltip on focus', async () => {
 
   const tooltip = getByText('some text');
   expect(tooltip).not.toBeVisible();
+  expect(tooltip).toHaveAttribute('popover', 'manual');
 
   fireEvent.focus(trigger);
   act(() => void vi.advanceTimersByTime(50));

packages/itwinui-react/src/core/Tooltip/Tooltip.tsx

@@ -36,6 +36,8 @@ import type {
   PortalProps,
 } from '../../utils/index.js';
 
+// ----------------------------------------------------------------------------
+
 type TooltipOptions = {
   /**
    * Placement of the Tooltip
@@ -117,6 +119,14 @@ type TooltipOwnProps = {
   children?: React.ReactNode;
 } & PortalProps;
 
+// TODO: Remove this when types are available
+type HTMLElementWithPopover = HTMLElement & {
+  /** @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/togglePopover */
+  togglePopover?: (force?: boolean) => void;
+};
+
+// ----------------------------------------------------------------------------
+
 const useTooltip = (options: TooltipOptions = {}) => {
   const uniqueId = useId();
   const {
@@ -137,6 +147,20 @@ const useTooltip = (options: TooltipOptions = {}) => {
     onVisibleChange,
   );
 
+  const syncWithControlledState = React.useCallback(
+    (element: HTMLElementWithPopover | null) => {
+      // Using a microtask ensures that the popover is mounted before calling togglePopover
+      queueMicrotask(() => {
+        try {
+          element?.togglePopover?.(open);
+        } catch {
+          // Fail silently, to avoid crashing the page
+        }
+      });
+    },
+    [open],
+  );
+
   const floating = useFloating({
     placement,
     open,
@@ -242,13 +266,15 @@ const useTooltip = (options: TooltipOptions = {}) => {
   );
 
   const floatingProps = React.useMemo(
-    () =>
-      interactions.getFloatingProps({
+    () => ({
+      ...interactions.getFloatingProps({
         hidden: !open,
         'aria-hidden': 'true',
         ...props,
         id,
       }),
+      popover: 'manual',
+    }),
     [interactions, props, id, open],
   );
 
@@ -257,10 +283,17 @@ const useTooltip = (options: TooltipOptions = {}) => {
       getReferenceProps,
       floatingProps,
       ...floating,
+      refs: {
+        ...floating.refs,
+        setFloating: (element: HTMLElement | null) => {
+          floating.refs.setFloating(element);
+          syncWithControlledState(element);
+        },
+      },
       // styles are not relevant when tooltip is not open
       floatingStyles: floating.context.open ? floating.floatingStyles : {},
     }),
-    [getReferenceProps, floatingProps, floating],
+    [getReferenceProps, floatingProps, floating, syncWithControlledState],
   );
 };