[Popover] Add captureOverscroll prop (#7588)

<!--
  ☝️How to write a good PR title:
- Prefix it with [ComponentName] (if applicable), for example: [Button]
  - Start with a verb, for example: Add, Delete, Improve, Fix…
  - Give as much context as necessary and as little as possible
  - Prefix it with [WIP] while it’s a work in progress
-->

### WHY are these changes introduced?

When a user scrolls to the bottom of the feed, we don't want the rest of
the page to scroll.

Fixes
[#1206](Shopify/merchant-communication#1206)
<!-- link to issue if one exists -->

<!--
  Context about the problem that’s being addressed.
-->

### WHAT is this pull request doing?

<!--
  Summary of the changes committed.

Before / after screenshots are appreciated for UI changes. Make sure to
include alt text that describes the screenshot.

If you include an animated gif showing your change, wrapping it in a
details tag is recommended. Gifs usually autoplay, which can cause
accessibility issues for people reviewing your PR:

    <details>
      <summary>Summary of your gif(s)</summary>
      <img src="..." alt="Description of what the gif shows">
    </details>
-->
This PR adds an optional `captureOverscroll` prop to the `Popover`
component, which gets passed to its `Pane` component. When the prop is
truthy, a class is added to the `Pane` component to capture the
overscroll with this CSS: `overscroll-behavior: contain;`.

The prop is set to `false` by default and will not impact any existing
implementations.

<details>
<summary>Attempts to scroll past the end of the alerts feed do not cause
the page to scroll</summary>


https://user-images.githubusercontent.com/100380574/199125795-b6f90cf6-ce20-4a6e-b801-f658146c2c0e.mp4


</details>
<!-- ℹ️ Delete the following for small / trivial changes -->

### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#local-development)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

<!--
  Give as much information as needed to experiment with the component
  in the playground.
-->

The updated version of the `Popover` component has been implemented on
[this spin
instance](https://admin.web.polaris-popover-update.rick-caplan.us.spin.dev/store/shop1).

- [ ] Open the alerts feed by clicking on the bell icon
- [ ] Scroll to the bottom of the feed to load the next set of results
- [ ] Scroll to the bottom again and confirm attempts to scroll past the
`No more alerts` message do not cause the page to scroll


### 🎩 checklist

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

Author: rcaplanshopify

.changeset/strange-beans-grow.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Added optional `captureOverscroll` prop to `Popover`

polaris-react/src/components/Popover/Popover.scss

@@ -106,6 +106,10 @@ $vertical-motion-offset: -5px;
   flex: 0 0 auto;
 }
 
+.Pane-captureOverscroll {
+  overscroll-behavior: contain;
+}
+
 .Section {
   padding: var(--p-space-4);
 

polaris-react/src/components/Popover/Popover.tsx

@@ -78,6 +78,11 @@ export interface PopoverProps {
   autofocusTarget?: PopoverAutofocusTarget;
   /** Prevents closing the popover when other overlays are clicked */
   preventCloseOnChildOverlayClick?: boolean;
+  /**
+   * Prevents page scrolling when the end of the scrollable Popover overlay content is reached - applied to Pane subcomponent
+   * @default false
+   */
+  captureOverscroll?: boolean;
 }
 
 export interface PopoverPublicAPI {

polaris-react/src/components/Popover/components/Pane/Pane.tsx

@@ -17,16 +17,26 @@ export interface PaneProps {
   height?: string;
   /** Callback when the bottom of the popover is reached by mouse or keyboard  */
   onScrolledToBottom?(): void;
+  /**
+   * Prevents page scrolling when the end of the scrollable Popover content is reached
+   * @default false
+   */
+  captureOverscroll?: boolean;
 }
 
 export function Pane({
+  captureOverscroll = false,
   fixed,
   sectioned,
   children,
   height,
   onScrolledToBottom,
 }: PaneProps) {
-  const className = classNames(styles.Pane, fixed && styles['Pane-fixed']);
+  const className = classNames(
+    styles.Pane,
+    fixed && styles['Pane-fixed'],
+    captureOverscroll && styles['Pane-captureOverscroll'],
+  );
   const content = sectioned
     ? wrapWithComponent(children, Section, {})
     : children;

polaris-react/src/components/Popover/components/Pane/tests/Pane.test.tsx

@@ -153,4 +153,54 @@ describe('<Pane />', () => {
       });
     });
   });
+
+  describe('captureOverscroll', () => {
+    const Children = () => (
+      <TextContainer>
+        <p>Text</p>
+      </TextContainer>
+    );
+
+    describe('when not passed', () => {
+      it('does not apply the Pane-captureOverscroll class', () => {
+        const popoverPane = mountWithApp(
+          <Pane>
+            <Children />
+          </Pane>,
+        );
+
+        expect(popoverPane).toContainReactComponent(Scrollable, {
+          className: 'Pane',
+        });
+      });
+    });
+
+    describe('when passed as true', () => {
+      it('applies the Pane-captureOverscroll class', () => {
+        const popoverPane = mountWithApp(
+          <Pane captureOverscroll>
+            <Children />
+          </Pane>,
+        );
+
+        expect(popoverPane).toContainReactComponent(Scrollable, {
+          className: 'Pane Pane-captureOverscroll',
+        });
+      });
+    });
+
+    describe('when passed as false', () => {
+      it('does not apply the Pane-captureOverscroll class', () => {
+        const popoverPane = mountWithApp(
+          <Pane captureOverscroll={false}>
+            <Children />
+          </Pane>,
+        );
+
+        expect(popoverPane).toContainReactComponent(Scrollable, {
+          className: 'Pane',
+        });
+      });
+    });
+  });
 });

polaris-react/src/components/Popover/components/PopoverOverlay/PopoverOverlay.tsx

@@ -57,6 +57,7 @@ export interface PopoverOverlayProps {
   onClose(source: PopoverCloseSource): void;
   autofocusTarget?: PopoverAutofocusTarget;
   preventCloseOnChildOverlayClick?: boolean;
+  captureOverscroll?: boolean;
 }
 
 interface State {
@@ -222,6 +223,7 @@ export class PopoverOverlay extends PureComponent<PopoverOverlayProps, State> {
       fluidContent,
       hideOnPrint,
       autofocusTarget,
+      captureOverscroll,
     } = this.props;
 
     const className = classNames(
@@ -248,7 +250,7 @@ export class PopoverOverlay extends PureComponent<PopoverOverlayProps, State> {
         style={contentStyles}
         ref={this.contentNode}
       >
-        {renderPopoverContent(children, {sectioned})}
+        {renderPopoverContent(children, {captureOverscroll, sectioned})}
       </div>
     );
 

polaris-react/src/components/Popover/tests/Popover.test.tsx

@@ -5,8 +5,9 @@ import {Portal} from '../../Portal';
 import {PositionedOverlay} from '../../PositionedOverlay';
 import {Popover} from '../Popover';
 import type {PopoverPublicAPI} from '../Popover';
-import {PopoverOverlay} from '../components';
+import {Pane, PopoverOverlay} from '../components';
 import * as setActivatorAttributes from '../set-activator-attributes';
+import {TextContainer} from '../../TextContainer';
 
 describe('<Popover />', () => {
   const spy = jest.fn();
@@ -368,6 +369,64 @@ describe('<Popover />', () => {
       });
     });
   });
+
+  describe('captureOverscroll', () => {
+    const TestActivator = <button>Activator</button>;
+
+    const Children = () => (
+      <TextContainer>
+        <p>Text</p>
+      </TextContainer>
+    );
+
+    const defaultProps = {
+      active: true,
+      activator: TestActivator,
+      onClose: jest.fn(),
+    };
+
+    describe('when not passed', () => {
+      it('does not pass the prop as true to the Pane component', () => {
+        const popover = mountWithApp(
+          <Popover {...defaultProps}>
+            <Children />
+          </Popover>,
+        );
+
+        expect(popover).toContainReactComponent(Pane, {
+          captureOverscroll: undefined,
+        });
+      });
+    });
+
+    describe('when passed as true', () => {
+      it('passes the prop as true to the Pane component', () => {
+        const popover = mountWithApp(
+          <Popover {...defaultProps} captureOverscroll>
+            <Children />
+          </Popover>,
+        );
+
+        expect(popover).toContainReactComponent(Pane, {
+          captureOverscroll: true,
+        });
+      });
+    });
+
+    describe('when passed as false', () => {
+      it('passes the prop as false to the Pane component', () => {
+        const popover = mountWithApp(
+          <Popover {...defaultProps} captureOverscroll={false}>
+            <Children />
+          </Popover>,
+        );
+
+        expect(popover).toContainReactComponent(Pane, {
+          captureOverscroll: false,
+        });
+      });
+    });
+  });
 });
 
 function noop() {}