Add fixed position prop to Overlay (#2715)

* feat(Overlay): Add fixed position prop to overlay

* tests(Overlay): Update overlay tests and stories

* docs(Overlay): trailing comma

* feat: Update Overlay to use css props instead of custom position prop

* docs: update Overlay docs to include new props

* fix: remove unused types

Co-authored-by: Cole Bemis <colebemis@github.com>

* fix: simplify left check

Co-authored-by: Cole Bemis <colebemis@github.com>

* test: update test props

* fix: formatting

* docs(Overlay): add new props to Overlay json docs

* Create .changeset/wild-bananas-doubt.md

Co-authored-by: Cole Bemis <colebemis@github.com>

Author: ajhenry

.changeset/wild-bananas-doubt.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+Overlay: Add `position`, `right`, and `bottom` props

docs/content/Overlay.mdx

@@ -76,6 +76,8 @@ See the [W3C accessibility recommendations for modals](https://www.w3.org/TR/wai
 
 `Overlay` renders its `children` within a div positioned absolutely within a portal within the default portal root. The overlay will not update its positioning if the portal root's positioning changes (e.g., if the portal root is statically positioned after some DOM element that dynamically resizes). You may consider using the [AnchoredOverlay](/AnchoredOverlay) component or [customizing the portal root](/Portal#customizing-the-portal-root) to achieve different positioning behavior.
 
+The position of the Overlay can be customized by using the `position` prop in conjunction with the `top|left|right|bottom` props.
+
 ## Props
 
 <ComponentProps data={data} />

src/Overlay.docs.json

@@ -72,13 +72,29 @@
       "name": "top",
       "type": "number",
       "defaultValue": "0",
-      "description": "Vertical position of the overlay, relative to its closest positioned ancestor (often its `Portal`)."
+      "description": "The top CSS property of the Overlay — affects the vertical position."
     },
     {
       "name": "left",
       "type": "number",
       "defaultValue": "0",
-      "description": "Horizontal position of the overlay, relative to its closest positioned ancestor (often its `Portal`)."
+      "description": "The left CSS property of the Overlay — affects the horizontal position."
+    },
+    {
+      "name": "right",
+      "type": "number",
+      "description": "The right CSS property of the Overlay — affects the horizontal position."
+    },
+    {
+      "name": "bottom",
+      "type": "number",
+      "description": "The bottom CSS property of the Overlay — affects the vertical position."
+    },
+    {
+      "name": "position",
+      "type": "| 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'",
+      "defaultValue": "absolute",
+      "description": "The position CSS property of the Overlay — sets how the Overlay is positioned relative to its Portal"
     },
     {
       "name": "portalContainerName",

src/Overlay.tsx

@@ -94,8 +94,11 @@ type BaseOverlayProps = {
   onEscape: (e: KeyboardEvent) => void
   visibility?: 'visible' | 'hidden'
   'data-test-id'?: unknown
-  top?: number
-  left?: number
+  position?: React.CSSProperties['position']
+  top?: React.CSSProperties['top']
+  left?: React.CSSProperties['left']
+  right?: React.CSSProperties['right']
+  bottom?: React.CSSProperties['bottom']
   portalContainerName?: string
   preventFocusOnOpen?: boolean
   role?: AriaRole
@@ -117,8 +120,11 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @param height Sets the height of the `Overlay`, pick from our set list of heights, or pass `auto` to automatically set the height based on the content of the `Overlay`, or pass `initial` to set the height based on the initial content of the `Overlay` (i.e. ignoring content changes). `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`.
  * @param maxHeight Sets the maximum height of the `Overlay`, pick from our set list of heights. `xsmall` corresponds to `192px`, `small` corresponds to `256px`, `medium` corresponds to `320px`, `large` corresponds to `432px`, `xlarge` corresponds to `600px`.
  * @param anchorSide If provided, the Overlay will slide into position from the side of the anchor with a brief animation
- * @param top Optional. Vertical position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
- * @param left Optional. Horizontal position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
+ * @param top Optional. Vertical top position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
+ * @param left Optional. Horizontal left position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
+ * @param right Optional. Horizontal right position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
+ * @param bottom Optional. Vertical bottom position of the overlay, relative to its closest positioned ancestor (often its `Portal`).
+ * @param position Optional. Sets how an element is positioned in a document. Defaults to `absolute` positioning.
  * @param portalContainerName Optional. The name of the portal container to render the Overlay into.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
@@ -135,9 +141,12 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       width = 'auto',
       top,
       left,
+      right,
+      bottom,
       anchorSide,
       portalContainerName,
       preventFocusOnOpen,
+      position,
       ...rest
     },
     forwardedRef,
@@ -180,6 +189,9 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       )
     }, [anchorSide, slideAnimationDistance, slideAnimationEasing, visibility])
 
+    // To be backwards compatible with the old Overlay, we need to set the left prop if x-position is not specified
+    const leftPosition: React.CSSProperties = left === undefined && right === undefined ? {left: 0} : {left}
+
     return (
       <Portal containerName={portalContainerName}>
         <StyledOverlay
@@ -190,8 +202,11 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
           ref={overlayRef}
           style={
             {
-              top: `${top || 0}px`,
-              left: `${left || 0}px`,
+              ...leftPosition,
+              right,
+              top,
+              bottom,
+              position,
               '--styled-overlay-visibility': visibility,
             } as React.CSSProperties
           }

src/__tests__/Overlay.test.tsx

@@ -7,7 +7,7 @@ import {axe} from 'jest-axe'
 import theme from '../theme'
 import BaseStyles from '../BaseStyles'
 import {ThemeProvider} from '../ThemeProvider'
-import {NestedOverlays, MemexNestedOverlays, MemexIssueOverlay} from '../stories/Overlay.stories'
+import {NestedOverlays, MemexNestedOverlays, MemexIssueOverlay, PositionedOverlays} from '../stories/Overlay.stories'
 
 type TestComponentSettings = {
   initialFocus?: 'button'
@@ -141,6 +141,60 @@ describe('Overlay', () => {
     spy.mockRestore()
   })
 
+  it('should right align when given `right: 0` and `position: fixed`', async () => {
+    const spy = jest.spyOn(console, 'log').mockImplementation(message => {
+      if (!message.startsWith('global handler')) {
+        throw new Error(
+          `Expected console.log() to be called with: 'global handler:' but instead it was called with: ${message}`,
+        )
+      }
+    })
+
+    const user = userEvent.setup()
+    const container = render(
+      <ThemeProvider>
+        <PositionedOverlays right />
+      </ThemeProvider>,
+    )
+
+    // open first menu
+    await user.click(container.getByText('Open right overlay'))
+    expect(container.getByText('Look! right aligned')).toBeInTheDocument()
+
+    const overlay = container.getByText('Look! right aligned').parentElement?.parentElement
+
+    expect(overlay).toHaveStyle({position: 'fixed', right: 0})
+    expect(overlay).not.toHaveStyle({left: 0})
+
+    spy.mockRestore()
+  })
+
+  it('should left align when not given position and left props', async () => {
+    const spy = jest.spyOn(console, 'log').mockImplementation(message => {
+      if (!message.startsWith('global handler')) {
+        throw new Error(
+          `Expected console.log() to be called with: 'global handler:' but instead it was called with: ${message}`,
+        )
+      }
+    })
+
+    const user = userEvent.setup()
+    const container = render(
+      <ThemeProvider>
+        <PositionedOverlays />
+      </ThemeProvider>,
+    )
+
+    // open first menu
+    await user.click(container.getByText('Open left overlay'))
+    expect(container.getByText('Look! left aligned')).toBeInTheDocument()
+
+    const overlay = container.getByText('Look! left aligned').parentElement?.parentElement
+    expect(overlay).toHaveStyle({left: 0, position: 'absolute'})
+
+    spy.mockRestore()
+  })
+
   it('memex repro: should only close the dropdown when escape is pressed', async () => {
     const user = userEvent.setup()
     const container = render(

src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap

@@ -216,7 +216,7 @@ exports[`AnchoredOverlay should render consistently when open 1`] = `
           data-focus-trap="active"
           height="auto"
           role="none"
-          style="top: 4px; left: 0px; --styled-overlay-visibility: visible;"
+          style="left: 0px; top: 4px; --styled-overlay-visibility: visible;"
           width="auto"
         >
           <span

src/drafts/InlineAutocomplete/InlineAutocomplete.tsx

@@ -2,8 +2,8 @@ import React, {cloneElement, useRef} from 'react'
 import Box from '../../Box'
 import Portal from '../../Portal'
 import {BetterSystemStyleObject} from '../../sx'
-import {getAbsoluteCharacterCoordinates} from '../utils/character-coordinates'
 import {useSyntheticChange} from '../hooks/useSyntheticChange'
+import {getAbsoluteCharacterCoordinates} from '../utils/character-coordinates'
 
 import {ShowSuggestionsEvent, Suggestions, TextInputCompatibleChild, TextInputElement, Trigger} from './types'
 import {augmentHandler, calculateSuggestionsQuery, getSuggestionValue, requireChildrenToBeInput} from './utils'
@@ -198,8 +198,8 @@ const InlineAutocomplete = ({
         inputRef={inputRef}
         onCommit={onCommit}
         onClose={onHideSuggestions}
-        top={suggestionsOffset.top}
-        left={suggestionsOffset.left}
+        top={suggestionsOffset.top || 0}
+        left={suggestionsOffset.left || 0}
         visible={suggestionsVisible}
         tabInsertsSuggestions={tabInsertsSuggestions}
       />

src/stories/Overlay.stories.tsx

@@ -450,3 +450,86 @@ export const MemexIssueOverlay = () => {
     </>
   )
 }
+
+export const PositionedOverlays = ({right}: {right?: boolean}) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const [direction, setDirection] = useState<'left' | 'right'>(right ? 'right' : 'left')
+  const buttonRef = useRef<HTMLButtonElement>(null)
+  const confirmButtonRef = useRef<HTMLButtonElement>(null)
+  const anchorRef = useRef<HTMLDivElement>(null)
+  const closeOverlay = () => setIsOpen(false)
+  return (
+    <Box ref={anchorRef}>
+      <Button
+        ref={buttonRef}
+        onClick={() => {
+          setIsOpen(!isOpen)
+          setDirection('left')
+        }}
+      >
+        Open left overlay
+      </Button>
+      <Button
+        ref={buttonRef}
+        onClick={() => {
+          setIsOpen(!isOpen)
+          setDirection('right')
+        }}
+        sx={{
+          mt: 2,
+        }}
+      >
+        Open right overlay
+      </Button>
+      {isOpen ? (
+        direction === 'left' ? (
+          <Overlay
+            initialFocusRef={confirmButtonRef}
+            returnFocusRef={buttonRef}
+            ignoreClickRefs={[buttonRef]}
+            onEscape={closeOverlay}
+            onClickOutside={closeOverlay}
+            width="auto"
+            anchorSide="inside-right"
+          >
+            <Box
+              sx={{
+                height: '100vh',
+                width: '500px',
+                display: 'flex',
+                justifyContent: 'center',
+                alignItems: 'center',
+              }}
+            >
+              <Text>Look! left aligned</Text>
+            </Box>
+          </Overlay>
+        ) : (
+          <Overlay
+            initialFocusRef={confirmButtonRef}
+            returnFocusRef={buttonRef}
+            ignoreClickRefs={[buttonRef]}
+            onEscape={closeOverlay}
+            onClickOutside={closeOverlay}
+            width="auto"
+            anchorSide={'inside-left'}
+            right={0}
+            position="fixed"
+          >
+            <Box
+              sx={{
+                height: '100vh',
+                width: '500px',
+                display: 'flex',
+                justifyContent: 'center',
+                alignItems: 'center',
+              }}
+            >
+              <Text>Look! right aligned</Text>
+            </Box>
+          </Overlay>
+        )
+      ) : null}
+    </Box>
+  )
+}