feat(ui-popover): add shouldScrollContent prop

Author: joyenjoyer

packages/ui-popover/src/Popover/v2/README.md

@@ -425,6 +425,37 @@ const Example = () => {
 render(<Example />)
 ```
 
+#### Scrolling content (`shouldScrollContent`)
+
+When the popover content can grow taller than the available viewport space, set `shouldScrollContent` to wrap the content in a scroll container that fits to the room between the trigger element and the viewport edge. To try the example below, zoom in until the available space becomes small enough that a scrollbar is displayed in the Popover.
+
+```js
+---
+type: example
+---
+const fpo = lorem.paragraphs(8)
+class Example extends React.Component {
+  state = { isOpen: false }
+  render () {
+    return (
+      <Popover
+        on="click"
+        placement="bottom start"
+        isShowingContent={this.state.isOpen}
+        onShowContent={() => this.setState({ isOpen: true })}
+        onHideContent={() => this.setState({ isOpen: false })}
+        shouldScrollContent
+        screenReaderLabel="A long popover"
+        renderTrigger={<Button>Open scrollable popover</Button>}
+      >
+        <View as="div" padding="small" maxWidth="22rem">{fpo}</View>
+      </Popover>
+    )
+  }
+}
+render(<Example />)
+```
+
 ### Guidelines
 
 ```js

packages/ui-popover/src/Popover/v2/__tests__/Popover.test.tsx

@@ -306,4 +306,43 @@ describe('<Popover />', () => {
 
     expect(popover).toHaveStyle('display: block')
   })
+
+  describe('shouldScrollContent', () => {
+    it('does not wrap content when the prop is unset', async () => {
+      render(
+        <Popover
+          isShowingContent
+          on="click"
+          renderTrigger={<button>Trigger</button>}
+        >
+          <h2 data-testid="content">Popover content</h2>
+        </Popover>
+      )
+      const content = await screen.findByTestId('content')
+      expect(
+        content.closest('[class*="popover__scrollContainer"]')
+      ).toBeNull()
+    })
+
+    it('wraps content in an overflow:auto + auto-fit max-height container when set', async () => {
+      render(
+        <Popover
+          isShowingContent
+          on="click"
+          renderTrigger={<button>Trigger</button>}
+          shouldScrollContent
+        >
+          <h2 data-testid="content">Popover content</h2>
+        </Popover>
+      )
+      const content = await screen.findByTestId('content')
+      const wrapper = content.closest(
+        '[class*="popover__scrollContainer"]'
+      ) as HTMLElement
+      expect(wrapper).not.toBeNull()
+      const computed = getComputedStyle(wrapper)
+      expect(computed.overflowY).toBe('auto')
+      expect(computed.maxHeight).toContain('--ui-position-available-height')
+    })
+  })
 })

packages/ui-popover/src/Popover/v2/index.tsx

@@ -517,6 +517,12 @@ class Popover extends Component<PopoverProps, PopoverState> {
   renderContent() {
     let content = callRenderProp(this.props.children)
 
+    if (this.props.shouldScrollContent) {
+      content = (
+        <div css={this.props.styles?.scrollContainer}>{content}</div>
+      )
+    }
+
     if (this.shown && !this.isTooltip) {
       // if popover is NOT being used as a tooltip, create a Dialog
       // to manage the content FocusRegion, when showing

packages/ui-popover/src/Popover/v2/props.ts

@@ -24,7 +24,12 @@
 import React from 'react'
 import { BorderWidth } from '@instructure/emotion'
 
-import type { Shadow, Stacking, WithStyleProps } from '@instructure/emotion'
+import type {
+  Shadow,
+  Stacking,
+  StyleObject,
+  WithStyleProps
+} from '@instructure/emotion'
 
 import type {
   PlacementPropValues,
@@ -284,6 +289,12 @@ type PopoverOwnProps = {
    * otherwise its calculated automatically based on whether the content is shown.
    */
   shouldSetAriaExpanded?: boolean
+  /**
+   * When `true`, wraps the popover content in a container that caps its
+   * height to the available viewport space and scrolls when content
+   * overflows.
+   */
+  shouldScrollContent?: boolean
 }
 
 type PopoverProps = PopoverOwnProps &
@@ -302,7 +313,11 @@ type PropKeys = keyof PopoverOwnProps
 
 type AllowedPropKeys = Readonly<Array<PropKeys>>
 
-type PopoverStyle = { borderRadius: string; borderColor: string }
+type PopoverStyle = {
+  borderRadius: string
+  borderColor: string
+  scrollContainer: StyleObject
+}
 const allowedProps: AllowedPropKeys = [
   'isShowingContent',
   'defaultIsShowingContent',
@@ -347,7 +362,8 @@ const allowedProps: AllowedPropKeys = [
   'children',
   'elementRef',
   'borderWidth',
-  'shouldSetAriaExpanded'
+  'shouldSetAriaExpanded',
+  'shouldScrollContent'
 ]
 
 export type { PopoverOwnProps, PopoverProps, PopoverState, PopoverStyle }

packages/ui-popover/src/Popover/v2/styles.ts

@@ -38,7 +38,13 @@ const generateStyle = (
 ): PopoverStyle => {
   return {
     borderColor: componentTheme.borderColor,
-    borderRadius: componentTheme.borderRadius
+    borderRadius: componentTheme.borderRadius,
+    scrollContainer: {
+      label: 'popover__scrollContainer',
+      maxHeight: 'var(--ui-position-available-height, 100vh)',
+      overflowY: 'auto',
+      overflowX: 'hidden'
+    }
   }
 }