fix(SelectPanel): Correctly recalculate position on overflow

.changeset/silent-cameras-care.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+fix(SelectPanel): Correctly recalculate position on overflow

packages/react/src/AnchoredOverlay/AnchoredOverlay.dev.stories.tsx

@@ -0,0 +1,110 @@
+import type {Meta} from '@storybook/react'
+import React, {useState} from 'react'
+
+import {Button} from '../Button'
+import {AnchoredOverlay} from '.'
+import {Stack} from '../Stack'
+import {Dialog, Spinner} from '..'
+
+const meta = {
+  title: 'Components/AnchoredOverlay/Dev',
+  component: AnchoredOverlay,
+} satisfies Meta<typeof AnchoredOverlay>
+
+export default meta
+
+export const RepositionAfterContentGrows = () => {
+  const [open, setOpen] = useState(false)
+
+  const [loading, setLoading] = useState(true)
+
+  React.useEffect(() => {
+    window.setTimeout(() => {
+      if (open) setLoading(false)
+    }, 2000)
+  }, [open])
+
+  return (
+    <Stack direction="vertical" justify="space-between" style={{height: 'calc(100vh - 200px)'}}>
+      <div>
+        What to expect:
+        <ul>
+          <li>The anchored overlay should open below the anchor (default position)</li>
+          <li>After 2000ms, the amount of content in the overlay grows</li>
+          <li>the overlay should reposition itself above the anchor so that it stays inside the window</li>
+        </ul>
+      </div>
+      <AnchoredOverlay
+        renderAnchor={props => (
+          <Button {...props} sx={{width: 'fit-content'}}>
+            Button
+          </Button>
+        )}
+        open={open}
+        onOpen={() => setOpen(true)}
+        onClose={() => {
+          setOpen(false)
+          setLoading(true)
+        }}
+      >
+        {loading ? (
+          <>
+            <Spinner />
+            loading for 2000ms
+          </>
+        ) : (
+          <div style={{height: '300px'}}>content with 300px height</div>
+        )}
+      </AnchoredOverlay>
+    </Stack>
+  )
+}
+
+export const RepositionAfterContentGrowsWithinDialog = () => {
+  const [open, setOpen] = useState(false)
+
+  const [loading, setLoading] = useState(true)
+
+  React.useEffect(() => {
+    window.setTimeout(() => {
+      if (open) setLoading(false)
+    }, 2000)
+  }, [open])
+
+  return (
+    <Dialog onClose={() => {}}>
+      <Stack direction="vertical" justify="space-between" style={{height: 'calc(100vh - 300px)'}}>
+        <div>
+          What to expect:
+          <ul>
+            <li>The anchored overlay should open below the anchor (default position)</li>
+            <li>After 2000ms, the amount of content in the overlay grows</li>
+            <li>the overlay should reposition itself above the anchor so that it stays inside the window</li>
+          </ul>
+        </div>
+        <AnchoredOverlay
+          renderAnchor={props => (
+            <Button {...props} sx={{width: 'fit-content'}}>
+              Button
+            </Button>
+          )}
+          open={open}
+          onOpen={() => setOpen(true)}
+          onClose={() => {
+            setOpen(false)
+            setLoading(true)
+          }}
+        >
+          {loading ? (
+            <>
+              <Spinner />
+              loading for 2000ms
+            </>
+          ) : (
+            <div style={{height: '300px'}}>content with 300px height</div>
+          )}
+        </AnchoredOverlay>
+      </Stack>
+    </Dialog>
+  )
+}

packages/react/src/AnchoredOverlay/AnchoredOverlay.docs.json

@@ -147,6 +147,12 @@
       "required": false,
       "description": "",
       "defaultValue": ""
+    },    {
+      "name": "pinPosition",
+      "type": "boolean",
+      "required": false,
+      "description": "If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.",
+      "defaultValue": "false"
     }
   ]
 }

packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx

@@ -89,6 +89,10 @@ interface AnchoredOverlayBaseProps extends Pick<OverlayProps, 'height' | 'width'
    * If `preventOverflow` is `true`, the width of the `Overlay` will not be adjusted.
    */
   preventOverflow?: boolean
+  /**
+   * If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.
+   */
+  pinPosition?: boolean
 }
 
 export type AnchoredOverlayProps = AnchoredOverlayBaseProps &
@@ -112,11 +116,12 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
   overlayProps,
   focusTrapSettings,
   focusZoneSettings,
-  side = 'outside-bottom',
+  side = overlayProps?.['anchorSide'] || 'outside-bottom',
   align = 'start',
   alignmentOffset,
   anchorOffset,
   className,
+  pinPosition,
   preventOverflow = true,
 }) => {
   const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
@@ -155,6 +160,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
     {
       anchorElementRef: anchorRef,
       floatingElementRef: overlayRef,
+      pinPosition,
       side,
       align,
       alignmentOffset,

packages/react/src/Overlay/Overlay.module.css

@@ -13,6 +13,7 @@
   width: auto;
   min-width: 192px;
   height: auto;
+  max-height: 100vh;
   overflow: hidden;
   background-color: var(--overlay-bgColor);
   border-radius: var(--borderRadius-large);

packages/react/src/Overlay/Overlay.tsx

@@ -75,7 +75,7 @@ const StyledOverlay = toggleStyledComponent(
     min-width: 192px;
     max-width: ${props => props.maxWidth && widthMap[props.maxWidth]};
     height: ${props => heightMap[props.height || 'auto']};
-    max-height: ${props => props.maxHeight && heightMap[props.maxHeight]};
+    max-height: ${props => (props.maxHeight ? heightMap[props.maxHeight] : '100vh')};
     width: ${props => widthMap[props.width || 'auto']};
     border-radius: 12px;
     overflow: ${props => (props.overflow ? props.overflow : 'hidden')};

packages/react/src/SelectPanel/SelectPanel.examples.stories.tsx

@@ -8,6 +8,8 @@ import type {OverlayProps} from '../Overlay'
 import {TriangleDownIcon} from '@primer/octicons-react'
 import {ActionList} from '../deprecated/ActionList'
 import FormControl from '../FormControl'
+import {Stack} from '../Stack'
+import {Dialog} from '../experimental'
 
 const meta = {
   title: 'Components/SelectPanel/Examples',
@@ -442,3 +444,96 @@ export const ItemsInScope = () => {
     </FormControl>
   )
 }
+
+export const RepositionAfterLoading = () => {
+  const [selected, setSelected] = React.useState<ItemInput[]>([items[0], items[1]])
+  const [open, setOpen] = useState(false)
+  const [filter, setFilter] = React.useState('')
+  const [filteredItems, setFilteredItems] = React.useState<typeof items>([])
+
+  const [loading, setLoading] = useState(true)
+
+  React.useEffect(() => {
+    if (!open) setLoading(true)
+    window.setTimeout(() => {
+      if (open) {
+        setFilteredItems(items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase())))
+        setLoading(false)
+      }
+    }, 2000)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open])
+
+  React.useEffect(() => {
+    if (!loading) {
+      setFilteredItems(items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase())))
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filter])
+
+  return (
+    <>
+      <Stack direction="vertical" justify="space-between" style={{height: 'calc(100vh - 300px)', width: 'fit-content'}}>
+        <h1>Reposition panel after loading</h1>
+        <SelectPanel
+          loading={loading}
+          title="Select labels"
+          placeholderText="Filter Labels"
+          open={open}
+          onOpenChange={setOpen}
+          items={filteredItems}
+          selected={selected}
+          onSelectedChange={setSelected}
+          onFilterChange={setFilter}
+        />
+      </Stack>
+    </>
+  )
+}
+
+export const SelectPanelRepositionInsideDialog = () => {
+  const [selected, setSelected] = React.useState<ItemInput[]>([items[0], items[1]])
+  const [open, setOpen] = useState(false)
+  const [filter, setFilter] = React.useState('')
+  const [filteredItems, setFilteredItems] = React.useState<typeof items>([])
+
+  const [loading, setLoading] = useState(true)
+
+  React.useEffect(() => {
+    if (!open) setLoading(true)
+    window.setTimeout(() => {
+      if (open) {
+        setFilteredItems(items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase())))
+        setLoading(false)
+      }
+    }, 2000)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open])
+
+  React.useEffect(() => {
+    if (!loading) {
+      setFilteredItems(items.filter(item => item.text.toLowerCase().startsWith(filter.toLowerCase())))
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filter])
+
+  return (
+    <Dialog title="SelectPanel reposition after loading inside Dialog" onClose={() => {}}>
+      <Stack direction="vertical" justify="space-between" style={{height: 'calc(100vh - 500px)', width: 'fit-content'}}>
+        <p>other content</p>
+        <SelectPanel
+          loading={loading}
+          title="Select labels"
+          placeholderText="Filter Labels"
+          open={open}
+          onOpenChange={setOpen}
+          items={filteredItems}
+          selected={selected}
+          onSelectedChange={setSelected}
+          onFilterChange={setFilter}
+          overlayProps={{anchorSide: 'outside-top'}}
+        />
+      </Stack>
+    </Dialog>
+  )
+}

packages/react/src/SelectPanel/SelectPanel.tsx

@@ -132,7 +132,7 @@ interface SelectPanelBaseProps {
 
 export type SelectPanelProps = SelectPanelBaseProps &
   Omit<FilteredActionListProps, 'selectionVariant'> &
-  Pick<AnchoredOverlayProps, 'open' | 'height'> &
+  Pick<AnchoredOverlayProps, 'open' | 'height' | 'width'> &
   AnchoredOverlayWrapperAnchorProps &
   (SelectPanelSingleSelection | SelectPanelMultiSelection)
 
@@ -185,8 +185,9 @@ export function SelectPanel({
   sx,
   loading,
   initialLoadingType = 'spinner',
-  height,
   className,
+  height,
+  width,
   id,
   ...listProps
 }: SelectPanelProps): JSX.Element {
@@ -451,7 +452,9 @@ export function SelectPanel({
         focusTrapSettings={focusTrapSettings}
         focusZoneSettings={focusZoneSettings}
         height={height}
+        width={width}
         anchorId={id}
+        pinPosition={!height}
       >
         <LiveRegionOutlet />
         {usingModernActionList ? null : (

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

@@ -13,6 +13,7 @@ exports[`AnchoredOverlay should render consistently when open 1`] = `
   position: absolute;
   min-width: 192px;
   height: auto;
+  max-height: 100vh;
   width: auto;
   border-radius: 12px;
   overflow: hidden;

packages/react/src/hooks/useAnchoredPosition.ts

@@ -8,6 +8,7 @@ import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 export interface AnchoredPositionHookSettings extends Partial<PositionSettings> {
   floatingElementRef?: React.RefObject<Element>
   anchorElementRef?: React.RefObject<Element>
+  pinPosition?: boolean
 }
 
 /**
@@ -30,22 +31,61 @@ export function useAnchoredPosition(
   const floatingElementRef = useProvidedRefOrCreate(settings?.floatingElementRef)
   const anchorElementRef = useProvidedRefOrCreate(settings?.anchorElementRef)
   const [position, setPosition] = React.useState<AnchorPosition | undefined>(undefined)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const [_, setPrevHeight] = React.useState<number | undefined>(undefined)
+
+  const topPositionChanged = (prevPosition: AnchorPosition | undefined, newPosition: AnchorPosition) => {
+    return (
+      prevPosition &&
+      ['outside-top', 'inside-top'].includes(prevPosition.anchorSide) &&
+      // either the anchor changed or the element is trying to shrink in height
+      (prevPosition.anchorSide !== newPosition.anchorSide || prevPosition.top < newPosition.top)
+    )
+  }
+
+  const updateElementHeight = () => {
+    let heightUpdated = false
+    setPrevHeight(prevHeight => {
+      // if the element is trying to shrink in height, restore to old height to prevent it from jumping
+      if (prevHeight && prevHeight > (floatingElementRef.current?.clientHeight ?? 0)) {
+        requestAnimationFrame(() => {
+          ;(floatingElementRef.current as HTMLElement).style.height = `${prevHeight}px`
+        })
+        heightUpdated = true
+      }
+      return prevHeight
+    })
+    return heightUpdated
+  }
 
   const updatePosition = React.useCallback(
     () => {
       if (floatingElementRef.current instanceof Element && anchorElementRef.current instanceof Element) {
-        setPosition(getAnchoredPosition(floatingElementRef.current, anchorElementRef.current, settings))
+        const newPosition = getAnchoredPosition(floatingElementRef.current, anchorElementRef.current, settings)
+        setPosition(prev => {
+          if (settings?.pinPosition && topPositionChanged(prev, newPosition)) {
+            const anchorTop = anchorElementRef.current?.getBoundingClientRect().top ?? 0
+            const elementStillFitsOnTop = anchorTop > (floatingElementRef.current?.clientHeight ?? 0)
+
+            if (elementStillFitsOnTop && updateElementHeight()) {
+              return prev
+            }
+          }
+          return newPosition
+        })
       } else {
         setPosition(undefined)
       }
+      setPrevHeight(floatingElementRef.current?.clientHeight)
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [floatingElementRef, anchorElementRef, ...dependencies],
   )
 
   useLayoutEffect(updatePosition, [updatePosition])
 
-  useResizeObserver(updatePosition)
+  useResizeObserver(updatePosition) // watches for changes in window size
+  useResizeObserver(updatePosition, floatingElementRef as React.RefObject<HTMLElement>) // watches for changes in floating element size
 
   return {
     floatingElementRef,