feat(Popover): Support nesting

change/@fluentui-react-portal-7e967006-0a2d-4cbf-a040-9c510134c3f3.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Render portals with virtual parent",
+  "packageName": "@fluentui/react-portal",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-tooltip-44f53e3c-eea5-4747-b250-9b8bdc2efbd8.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update snapshots referencing months (#10023)",
+  "packageName": "@fluentui/react-tooltip",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

change/@fluentui-react-utilities-d865e9d6-c439-410e-bc3c-aa754d0b206e.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Support custom `contains` check",
+  "packageName": "@fluentui/react-utilities",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-popover/e2e/Popover.e2e.ts

@@ -43,3 +43,55 @@ describe('With custom trigger', () => {
       .should('not.exist');
   });
 });
+
+describe('Nested', () => {
+  beforeEach(() => {
+    // Open the whole stack of popovers
+    cy.visitStory('Popover', 'NestedPopovers')
+      .contains('Root')
+      .click()
+      .get('body')
+      .contains('First')
+      .click()
+      .get('body')
+      .contains('Second')
+      .first()
+      .click();
+  });
+
+  it('should dismiss all nested popovers on outside click', () => {
+    cy.get('body')
+      .click('bottomRight')
+      .get(popoverContentSelector)
+      .should('not.exist');
+  });
+
+  it('should not dismiss when clicking on nested content', () => {
+    cy.contains('Second nested button')
+      .click()
+      .get(popoverContentSelector)
+      .should('have.length', 3);
+  });
+
+  it('should dismiss child popovers when clicking on parents', () => {
+    cy.contains('First nested button')
+      .click()
+      .get(popoverContentSelector)
+      .should('have.length', 2)
+      .contains('Root button')
+      .click()
+      .get(popoverContentSelector)
+      .should('have.length', 1);
+  });
+
+  it('should when opening a sibling popover, should dismiss other sibling popover', () => {
+    cy.contains('Sibling nested trigger')
+      .click()
+      .get(popoverContentSelector)
+      .should('have.length', 3)
+      .contains('Second nested trigger')
+      .click()
+      .get(popoverContentSelector)
+      .should('have.length', 3);
+  });
+});

packages/react-popover/src/Popover.stories.tsx

@@ -103,6 +103,51 @@ export const WithCustomTrigger = () => {
   );
 };
 
+export const NestedPopovers = () => {
+  return (
+    <Popover>
+      <PopoverTrigger>
+        <button>Root trigger</button>
+      </PopoverTrigger>
+
+      <PopoverContent>
+        <ExampleContent />
+        <button>Root button</button>
+        <Popover>
+          <PopoverTrigger>
+            <button style={{ marginLeft: 100 }}>First nested trigger</button>
+          </PopoverTrigger>
+
+          <PopoverContent>
+            <ExampleContent />
+            <button>First nested button</button>
+            <Popover>
+              <PopoverTrigger>
+                <button>Second nested trigger</button>
+              </PopoverTrigger>
+
+              <PopoverContent>
+                <ExampleContent />
+                <button>Second nested button</button>
+              </PopoverContent>
+            </Popover>
+            <Popover>
+              <PopoverTrigger>
+                <button style={{ marginLeft: 100 }}>Sibling nested trigger</button>
+              </PopoverTrigger>
+
+              <PopoverContent>
+                <ExampleContent />
+                <button>Second nested button</button>
+              </PopoverContent>
+            </Popover>
+          </PopoverContent>
+        </Popover>
+      </PopoverContent>
+    </Popover>
+  );
+};
+
 export default {
   title: 'Components/Popover',
   component: Popover,

packages/react-popover/src/components/Popover/usePopover.ts

@@ -1,7 +1,8 @@
 import * as React from 'react';
-import { makeMergeProps, useControllableValue, useOnClickOutside, useEventCallback } from '@fluentui/react-utilities';
+import { makeMergeProps, useControllableValue, useEventCallback, useOnClickOutside } from '@fluentui/react-utilities';
 import { useFluent } from '@fluentui/react-shared-contexts';
 import { usePopper } from '@fluentui/react-positioning';
+import { elementContains } from '@fluentui/react-portal';
 import { PopoverProps, PopoverState } from './Popover.types';
 
 const mergeProps = makeMergeProps<PopoverState>({});
@@ -35,6 +36,7 @@ export const usePopover = (props: PopoverProps, defaultProps?: PopoverProps): Po
 
   const { targetDocument } = useFluent();
   useOnClickOutside({
+    contains: elementContains,
     element: targetDocument,
     callback: ev => state.setOpen(ev, false),
     refs: [state.triggerRef, state.contentRef],

packages/react-popover/src/components/PopoverContent/PopoverContent.test.tsx

@@ -10,10 +10,12 @@ jest.mock('../../popoverContext');
 
 describe('PopoverContent', () => {
   isConformant({
+    // as render test will pass a span tag which is also considered one of the skipped helperComponents
+    disabledTests: ['as-renders-html'],
     Component: PopoverContent,
     displayName: 'PopoverContent',
     requiredProps: { open: true },
-    helperComponents: [Portal],
+    helperComponents: [Portal, 'span'],
   });
 
   let wrapper: ReactWrapper | undefined;

packages/react-portal/README.md

@@ -31,3 +31,117 @@ const node = document.getElementById('customNode');
 ### Styling
 
 `Portal` renders React children directly to the default/configured DOM node. Therefore styling should be applied to the `children` by users directly.
+
+### Virtual parents
+
+Out of order DOM elements can be problematic when using 'click outside' event listeners since you cannot rely on `element.contains(event.target)` because the `Portal` elements are out of DOM order.
+
+```tsx
+
+const outerButtonRef = React.useRef();
+const innerButtonRef = React.useRef();
+
+
+<Portal>
+  <div>
+    <button ref={outerButtonRef}> Outer button </button>
+    <Portal>
+      <div>
+        <button ref={innerButtonRef}> Inner button </button>
+      </div>
+    </Portal>
+  </div>
+</Portal>
+
+// DOM output
+<div>
+  <button>Outer button</button>
+</div>
+
+<div>
+  <button>Inner button</button>
+</div>
+
+// Let's add an event listener to 'dismss' the outer portal when clicked outside
+// ⚠⚠⚠ This will always be called when clicking on the inner button
+document.addEventListener((event) => {
+  if (outerButtonRef.current.contains(event.target)) {
+    dismissOuterPortal();
+  }
+})
+```
+
+When the above case is not required, using `element.contains` is perfectly fine. But nested cases should still be handled appropriately. We do this using the concept of `virtual parents`
+
+`Portal` will make public 2 utilities that will only be used in cases where the user needs to know if an out of order DOM element will need to be used or not.
+
+- `setVirtualParent` - sets virtual parent. Portal uses this already internally.
+- `elementContains` - similar to `element.contains` but uses the virtual hierarchy as reference
+
+Below shows what a virtual parent is
+
+```tsx
+// Setting a virtual parent
+
+const parent document.getElementById('parent')
+const child document.getElement.ById('child');
+
+child._virtual.parent = parent;
+```
+
+`Portals` will render a hidden span that will be the virtual parent, by nesting portals virtual parens will also be nested so that `elementContains` will work predictably.
+
+```tsx
+<FluentProvider>
+  <Portal id="portal-1" />
+  <Portal id="portal-2" />
+</FluentProvider>
+```
+
+DOM output:
+
+```tsx
+<body>
+  <div>
+    {/* Virtual parent for portal*/}
+    <span aria-hidden />
+    {/* Virtual parent for portal*/}
+    <span aria-hidden />
+  </div>
+
+  <div id="portal-1" class="theme-provider-0">
+    {children}
+  </div>
+  <div id="portal-2" class="theme-provider-0">
+    {children}
+  </div>
+</body>
+```
+
+```tsx
+<FluentProvider>
+  <Portal id="portal-1">
+    <Portal id="portal-2" />
+  </Portal>
+</FluentProvider>
+```
+
+DOM output:
+
+```tsx
+<body>
+  <div>
+    {/* Virtual parent for outer portal*/}
+    <span aria-hidden></span>
+  </div>
+
+  <div id="portal-1" class="theme-provider-0">
+    {/* Virtual parent for inner portal*/}
+    <span aria-hidden />
+    {children}
+  </div>
+  <div id="portal-2" class="theme-provider-0">
+    {children}
+  </div>
+</body>
+```