fix(react-positioning): don't treat static overflow:hidden ancestors as a hide-middleware clipping boundary

change/@fluentui-react-positioning-95a68719-9f3f-4da2-8ac8-e2c22ecd0b4d.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: do not treat non-scrolling overflow:hidden ancestors as a clipping boundary for the hide middleware's escaped/referenceHidden detection",
+  "packageName": "@fluentui/react-positioning",
+  "email": "paulmardling@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-positioning/library/src/middleware/hide.test.ts

@@ -0,0 +1,53 @@
+import { hide as baseHide } from '@floating-ui/dom';
+import { hide } from './hide';
+
+jest.mock('@floating-ui/dom', () => {
+  const actual = jest.requireActual('@floating-ui/dom');
+  return {
+    ...actual,
+    hide: jest.fn(actual.hide),
+  };
+});
+
+/**
+ * `./hide.ts` relies on an implicit, lightly-documented behavior of `@floating-ui/dom`'s `hide`
+ * middleware: passing `boundary: []` (as opposed to the default `'clippingAncestors'`) causes its
+ * internal `getClippingRect` to skip all intermediate DOM clipping ancestors and only consider the
+ * `rootBoundary` (the viewport, by default) — see #36604 and the comment in `./hide.ts`.
+ *
+ * That deeper, real-browser geometry contract (that `boundary: []` genuinely behaves as
+ * "viewport-only") is covered by the Cypress regression tests in react-tooltip's `Tooltip.cy.tsx`
+ * (both the pre-existing scroll-based test for #32882, and the new static `overflow: hidden` test
+ * for #36604) — a real browser is required to reliably exercise floating-ui's
+ * offset-parent/scale/layout math; jsdom's emulation of that math doesn't match real browser
+ * behavior closely enough to pin it in a unit test here.
+ *
+ * These tests instead pin the narrower, fully deterministic thing this module is responsible for:
+ * that it maps `hasScrollableElement` to the correct `boundary` option passed to the underlying
+ * `@floating-ui/dom` `hide` middleware.
+ */
+describe('hide', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it.each([
+    ['referenceHidden', true, 'clippingAncestors'],
+    ['referenceHidden', false, []],
+    ['escaped', true, 'clippingAncestors'],
+    ['escaped', false, []],
+  ] as const)(
+    'strategy=%s, hasScrollableElement=%s -> boundary=%s',
+    (strategy, hasScrollableElement, expectedBoundary) => {
+      hide({ strategy, hasScrollableElement });
+
+      expect(baseHide).toHaveBeenCalledWith({ strategy, boundary: expectedBoundary });
+    },
+  );
+
+  it('defaults to a viewport-only boundary when hasScrollableElement is not provided', () => {
+    hide({ strategy: 'escaped' });
+
+    expect(baseHide).toHaveBeenCalledWith({ strategy: 'escaped', boundary: [] });
+  });
+});

packages/react-components/react-positioning/library/src/middleware/hide.ts

@@ -0,0 +1,43 @@
+import type { Middleware } from '@floating-ui/dom';
+import { hide as baseHide } from '@floating-ui/dom';
+
+export interface HideMiddlewareOptions {
+  strategy: 'referenceHidden' | 'escaped';
+  /**
+   * Whether the positioned element has a scrollable ancestor (an ancestor whose `overflow` is
+   * `auto`, `scroll`, or `overlay`), as opposed to merely a clipping one (`overflow: hidden`
+   * with no scrollable content).
+   *
+   * When there's no scrollable ancestor, non-scrolling `overflow: hidden` ancestors are excluded
+   * from the clipping boundary used to compute `referenceHidden`/`escaped`. Otherwise, a trigger
+   * placed in a tightly-fitted `overflow: hidden` container (a common layout pattern, e.g. a flex
+   * toolbar) would have its tooltip permanently hidden, even though nothing is actually being
+   * scrolled out of view.
+   */
+  hasScrollableElement?: boolean;
+}
+
+/**
+ * Wraps the floating UI hide middleware for easier usage of our options
+ */
+export function hide(options: HideMiddlewareOptions): Middleware {
+  const { strategy, hasScrollableElement } = options;
+
+  return baseHide({
+    strategy,
+    // Only consider intermediate clipping ancestors (including non-scrolling `overflow: hidden`
+    // containers) when there's an ancestor that can actually be scrolled. Otherwise, fall back to
+    // the viewport as the sole boundary by passing an empty array, so static, non-scrolling
+    // clipping ancestors aren't treated as a boundary an element can be "hidden" or "escaped" by.
+    //
+    // This relies on an implicit (undocumented in floating-ui's public docs, but verified against
+    // its source) behavior of `@floating-ui/dom@^1.6.12`'s `getClippingRect`: passing a `boundary`
+    // that isn't `'clippingAncestors'` (e.g. `[]`) skips all intermediate DOM clipping ancestors
+    // and only considers `rootBoundary` (the viewport, by default). This wrapper's own mapping of
+    // `hasScrollableElement` to `boundary` is pinned by unit tests in `./hide.test.ts`. The deeper
+    // real-browser geometry contract (that `boundary: []` genuinely behaves as viewport-only) is
+    // covered by react-tooltip's Cypress tests (`Tooltip.cy.tsx`, regressions #32882 and #36604) —
+    // if a future `@floating-ui/dom` upgrade changes this behavior, those should fail.
+    boundary: hasScrollableElement ? 'clippingAncestors' : [],
+  });
+}

packages/react-components/react-positioning/library/src/middleware/index.ts

@@ -1,6 +1,8 @@
 export { coverTarget } from './coverTarget';
 export type { FlipMiddlewareOptions } from './flip';
 export { flip } from './flip';
+export type { HideMiddlewareOptions } from './hide';
+export { hide } from './hide';
 export { intersecting } from './intersecting';
 export type { MaxSizeMiddlewareOptions } from './maxSize';
 export { maxSize, resetMaxSize } from './maxSize';

packages/react-components/react-positioning/library/src/usePositioningOptions.ts

@@ -1,7 +1,7 @@
 'use client';
 
 import { devtools } from '@floating-ui/devtools';
-import { hide as hideMiddleware, arrow as arrowMiddleware } from '@floating-ui/dom';
+import { arrow as arrowMiddleware } from '@floating-ui/dom';
 import type { Middleware, Placement, Strategy } from '@floating-ui/dom';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
 import * as React from 'react';
@@ -15,6 +15,7 @@ import {
   offset as offsetMiddleware,
   intersecting as intersectingMiddleware,
   matchTargetSize as matchTargetSizeMiddleware,
+  hide as hideMiddleware,
 } from './middleware';
 import type { PositioningConfigurationFn, PositioningConfigurationFnOptions, PositioningOptions } from './types';
 import { toFloatingUIPlacement, hasScrollParent, normalizeAutoSize } from './utils';
@@ -170,8 +171,8 @@ export function usePositioningOptions(options: PositioningOptions): (
           maxSizeMiddleware(normalizedAutoSize, { container, overflowBoundary, overflowBoundaryPadding, isRtl }),
         intersectingMiddleware(),
         arrow && arrowMiddleware({ element: arrow, padding: arrowPadding }),
-        hideMiddleware({ strategy: 'referenceHidden' }),
-        hideMiddleware({ strategy: 'escaped' }),
+        hideMiddleware({ strategy: 'referenceHidden', hasScrollableElement }),
+        hideMiddleware({ strategy: 'escaped', hasScrollableElement }),
         process.env.NODE_ENV !== 'production' &&
           targetDocument &&
           devtools(targetDocument, devtoolsCallback(optionsAfterEnhancement)),

packages/react-components/react-tooltip/library/src/components/Tooltip/Tooltip.cy.tsx

@@ -44,4 +44,20 @@ describe('Tooltip', () => {
         });
     });
   });
+
+  describe('static non-scrolling overflow:hidden container (regression: #36604)', () => {
+    it('still shows the tooltip when its trigger sits in a tightly-fitted overflow:hidden container', () => {
+      mount(
+        <div style={{ overflow: 'hidden', display: 'flex' }}>
+          <Tooltip content="I should still appear" relationship="label">
+            <Button id="trigger">Hover me</Button>
+          </Tooltip>
+        </div>,
+      );
+
+      cy.get('#trigger').realHover();
+
+      cy.get('[role="tooltip"]').should('be.visible').and('have.text', 'I should still appear');
+    });
+  });
 });

packages/react-components/react-tooltip/stories/src/Tooltip/TooltipStaticOverflowHidden.stories.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import type { JSXElement } from '@fluentui/react-components';
+import { Button, makeStyles, tokens, Tooltip } from '@fluentui/react-components';
+
+const useStyles = makeStyles({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: tokens.spacingVerticalS,
+    alignItems: 'flex-start',
+  },
+  description: {
+    margin: 0,
+    fontSize: tokens.fontSizeBase300,
+  },
+  staticContainer: {
+    display: 'flex',
+    overflow: 'hidden',
+    border: `${tokens.strokeWidthThin} solid ${tokens.colorNeutralStroke1}`,
+    borderRadius: tokens.borderRadiusMedium,
+    padding: tokens.spacingVerticalXS,
+  },
+});
+
+export const StaticOverflowHidden = (): JSXElement => {
+  const styles = useStyles();
+
+  return (
+    <div className={styles.root}>
+      <p className={styles.description}>
+        The button below sits in a tightly-fitted, non-scrolling <code>overflow: hidden</code> container. The tooltip
+        should still appear on hover, since nothing is being scrolled out of view.
+      </p>
+      <div className={styles.staticContainer}>
+        <Tooltip content="I should still appear" relationship="label">
+          <Button>Hover me</Button>
+        </Tooltip>
+      </div>
+    </div>
+  );
+};
+
+StaticOverflowHidden.parameters = {
+  docs: {
+    description: {
+      story:
+        'A tooltip trigger placed inside a static, non-scrolling `overflow: hidden` container (e.g. a flex toolbar) should still show its tooltip, since it is not a scroll boundary being escaped.',
+    },
+  },
+};

packages/react-components/react-tooltip/stories/src/Tooltip/index.stories.tsx

@@ -16,6 +16,7 @@ export { Positioning } from './TooltipPositioning.stories';
 export { Target } from './TooltipTarget.stories';
 export { Icon } from './TooltipIcon.stories';
 export { OverflowHidden } from './TooltipOverflowHidden.stories';
+export { StaticOverflowHidden } from './TooltipStaticOverflowHidden.stories';
 
 export default {
   title: 'Components/Tooltip',