From 1e14b8142600d7439a3557edf6701d0c5797637d Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 15 Oct 2024 14:26:01 -0400
Subject: [PATCH 01/16] Add "reflow" prop to `Overlay`

---
 packages/react/src/Overlay/Overlay.tsx | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index 251ba0625ab..b9cdf20c48c 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -23,6 +23,7 @@ type StyledOverlayProps = {
   overflow?: 'auto' | 'hidden' | 'scroll' | 'visible'
   anchorSide?: AnchorSide
   style?: React.CSSProperties
+  reflow?: boolean
 } & SxProp
 
 export const heightMap = {
@@ -91,6 +92,14 @@ export const StyledOverlay = styled.div<StyledOverlayProps>`
     outline: solid 1px transparent;
   }
 
+  @media (max-width: 320px) {
+    &[data-overlay-reflow] {
+      width: 100%;
+      max-width: 320px;
+      flex-grow: 1;
+      position: fixed;
+    }
+  }
   ${sx};
 `
 type BaseOverlayProps = {
@@ -110,6 +119,7 @@ type BaseOverlayProps = {
   preventFocusOnOpen?: boolean
   role?: AriaRole
   children?: React.ReactNode
+  reflow?: boolean
 }
 
 type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
@@ -133,6 +143,7 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @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.
+ * @param reflow Optional. If true, the Overlay width will be adjusted responsively if there is not enough space to display the Overlay in the requested position.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (
@@ -155,6 +166,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       preventFocusOnOpen,
       position,
       style: styleFromProps = {},
+      reflow,
       ...rest
     },
     forwardedRef,
@@ -199,7 +211,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
 
     // 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}
-
+    console.log(reflow)
     return (
       <Portal containerName={portalContainerName}>
         <StyledOverlay
@@ -219,6 +231,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
               ...styleFromProps,
             } as React.CSSProperties
           }
+          data-overlay-reflow={reflow}
         />
       </Portal>
     )

From fdbe2a91e617286295f20bbf5357d305c7407a9d Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 15 Oct 2024 15:17:20 -0400
Subject: [PATCH 02/16] Remove `max-width`

---
 packages/react/src/Overlay/Overlay.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index b9cdf20c48c..a6bc19c1251 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -95,7 +95,6 @@ export const StyledOverlay = styled.div<StyledOverlayProps>`
   @media (max-width: 320px) {
     &[data-overlay-reflow] {
       width: 100%;
-      max-width: 320px;
       flex-grow: 1;
       position: fixed;
     }
@@ -211,7 +210,6 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
 
     // 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}
-    console.log(reflow)
     return (
       <Portal containerName={portalContainerName}>
         <StyledOverlay

From 0b7e9565ac6e9612f213bd2b33ddd2c39ddff487 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 15 Oct 2024 16:20:54 -0400
Subject: [PATCH 03/16] Update stories

---
 packages/react/src/Overlay/Overlay.features.stories.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/react/src/Overlay/Overlay.features.stories.tsx b/packages/react/src/Overlay/Overlay.features.stories.tsx
index ac35e8bfc5a..dbbe14172ae 100644
--- a/packages/react/src/Overlay/Overlay.features.stories.tsx
+++ b/packages/react/src/Overlay/Overlay.features.stories.tsx
@@ -213,6 +213,7 @@ export const MemexNestedOverlays = () => {
           ignoreClickRefs={[buttonRef]}
           top={60}
           left={16}
+          reflow={true}
         >
           <Box as="form" onSubmit={() => setOverlayOpen(false)} sx={{display: 'flex', flexDirection: 'column', py: 2}}>
             <Box sx={{paddingX: 3, display: 'flex', alignItems: 'center', gap: 1}}>
@@ -285,6 +286,7 @@ export const NestedOverlays = () => {
           ignoreClickRefs={[buttonRef]}
           top={100}
           left={16}
+          reflow={true}
         >
           <Box sx={{display: 'flex', flexDirection: 'column', py: 2}}>
             <Box sx={{paddingX: 3, paddingY: 2}}>

From 793e25f40ccd23d8fb60b46eaca4f03f9d4bd11a Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 15 Oct 2024 16:29:26 -0400
Subject: [PATCH 04/16] Update note

---
 packages/react/src/Overlay/Overlay.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index a6bc19c1251..ebef6f2b692 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -142,7 +142,7 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @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.
- * @param reflow Optional. If true, the Overlay width will be adjusted responsively if there is not enough space to display the Overlay in the requested position.
+ * @param reflow Optional. If true, the Overlay width will be adjusted responsively at `320px` if there is not enough space to display the Overlay in the requested position.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (

From d94abc73eff4560749308e498da4627301283ada Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Wed, 23 Oct 2024 09:50:12 -0400
Subject: [PATCH 05/16] Remove `reflow` prop

---
 packages/react/src/Overlay/Overlay.tsx | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index ebef6f2b692..ace80009b80 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -23,7 +23,6 @@ type StyledOverlayProps = {
   overflow?: 'auto' | 'hidden' | 'scroll' | 'visible'
   anchorSide?: AnchorSide
   style?: React.CSSProperties
-  reflow?: boolean
 } & SxProp
 
 export const heightMap = {
@@ -93,11 +92,9 @@ export const StyledOverlay = styled.div<StyledOverlayProps>`
   }
 
   @media (max-width: 320px) {
-    &[data-overlay-reflow] {
-      width: 100%;
-      flex-grow: 1;
-      position: fixed;
-    }
+    width: 100%;
+    flex-grow: 1;
+    position: fixed;
   }
   ${sx};
 `
@@ -118,7 +115,6 @@ type BaseOverlayProps = {
   preventFocusOnOpen?: boolean
   role?: AriaRole
   children?: React.ReactNode
-  reflow?: boolean
 }
 
 type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
@@ -142,7 +138,6 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @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.
- * @param reflow Optional. If true, the Overlay width will be adjusted responsively at `320px` if there is not enough space to display the Overlay in the requested position.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (
@@ -165,7 +160,6 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       preventFocusOnOpen,
       position,
       style: styleFromProps = {},
-      reflow,
       ...rest
     },
     forwardedRef,
@@ -229,7 +223,6 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
               ...styleFromProps,
             } as React.CSSProperties
           }
-          data-overlay-reflow={reflow}
         />
       </Portal>
     )

From 051884313ea21da89ec7284998d5f9e07f9451e3 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Sun, 27 Oct 2024 10:45:29 -0400
Subject: [PATCH 06/16] More changes

---
 .../react/src/AnchoredOverlay/AnchoredOverlay.tsx     |  1 +
 .../react/src/Overlay/Overlay.features.stories.tsx    |  3 +--
 packages/react/src/Overlay/Overlay.tsx                | 11 +++++++----
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index 88260c2c8a2..869c7620c4d 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -198,6 +198,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           left={position?.left || 0}
           anchorSide={position?.anchorSide}
           className={className}
+          reflow={false}
           {...overlayProps}
         >
           {children}
diff --git a/packages/react/src/Overlay/Overlay.features.stories.tsx b/packages/react/src/Overlay/Overlay.features.stories.tsx
index dbbe14172ae..09ed0056084 100644
--- a/packages/react/src/Overlay/Overlay.features.stories.tsx
+++ b/packages/react/src/Overlay/Overlay.features.stories.tsx
@@ -206,14 +206,13 @@ export const MemexNestedOverlays = () => {
       </ButtonGroup>
       {overlayOpen && (
         <Overlay
-          width="medium"
+          width="auto"
           onEscape={() => setOverlayOpen(false)}
           onClickOutside={() => setOverlayOpen(false)}
           returnFocusRef={buttonRef}
           ignoreClickRefs={[buttonRef]}
           top={60}
           left={16}
-          reflow={true}
         >
           <Box as="form" onSubmit={() => setOverlayOpen(false)} sx={{display: 'flex', flexDirection: 'column', py: 2}}>
             <Box sx={{paddingX: 3, display: 'flex', alignItems: 'center', gap: 1}}>
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index ace80009b80..636768e8170 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -91,11 +91,10 @@ export const StyledOverlay = styled.div<StyledOverlayProps>`
     outline: solid 1px transparent;
   }
 
-  @media (max-width: 320px) {
-    width: 100%;
-    flex-grow: 1;
-    position: fixed;
+  &[data-reflow-container='true'] {
+    max-width: calc(100vw - 2rem);
   }
+
   ${sx};
 `
 type BaseOverlayProps = {
@@ -115,6 +114,7 @@ type BaseOverlayProps = {
   preventFocusOnOpen?: boolean
   role?: AriaRole
   children?: React.ReactNode
+  reflow?: boolean
 }
 
 type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
@@ -138,6 +138,7 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @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.
+ * @param reflow Optional. If true, the Overlay width will be adjusted responsively at `320px` if there is not enough space to display the Overlay in the requested position.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (
@@ -160,6 +161,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       preventFocusOnOpen,
       position,
       style: styleFromProps = {},
+      reflow = true,
       ...rest
     },
     forwardedRef,
@@ -223,6 +225,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
               ...styleFromProps,
             } as React.CSSProperties
           }
+          data-reflow-container={width === 'auto' && reflow ? true : undefined}
         />
       </Portal>
     )

From 9476b99581dad588d60dc58eee6ec0c6e5163cea Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Mon, 28 Oct 2024 08:56:15 -0400
Subject: [PATCH 07/16] Update snapshot

---
 .../src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/react/src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap b/packages/react/src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap
index 786ea165f9b..38a2450ee5b 100644
--- a/packages/react/src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap
+++ b/packages/react/src/__tests__/__snapshots__/AnchoredOverlay.test.tsx.snap
@@ -313,6 +313,10 @@ exports[`AnchoredOverlay should render consistently when open 1`] = `
   outline: none;
 }
 
+.c3[data-reflow-container='true'] {
+  max-width: calc(100vw - 2rem);
+}
+
 @media (forced-colors:active) {
   .c1:focus {
     outline: solid 1px transparent;

From 08322c0a1ef825f8f139193f70e1ee203dce753f Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Mon, 28 Oct 2024 14:36:34 -0400
Subject: [PATCH 08/16] Add changeset

---
 .changeset/forty-olives-lay.md         | 5 +++++
 packages/react/src/Overlay/Overlay.tsx | 1 +
 2 files changed, 6 insertions(+)
 create mode 100644 .changeset/forty-olives-lay.md

diff --git a/.changeset/forty-olives-lay.md b/.changeset/forty-olives-lay.md
new file mode 100644
index 00000000000..d3e44460ed5
--- /dev/null
+++ b/.changeset/forty-olives-lay.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Overlay: Adds `min-width` to container to improve responsiveness
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index 636768e8170..4ef3cc2bde8 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -206,6 +206,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
 
     // 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

From 44ab1e1874c193c019ce160b904e0d4b2c4659d6 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 29 Oct 2024 08:57:46 -0400
Subject: [PATCH 09/16] Add condition for `data-reflow-container`, edits to
 stories

---
 .../src/Overlay/Overlay.features.stories.tsx  | 68 +++++++++++--------
 packages/react/src/Overlay/Overlay.tsx        |  3 +-
 2 files changed, 42 insertions(+), 29 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.features.stories.tsx b/packages/react/src/Overlay/Overlay.features.stories.tsx
index cc72e9ca626..f30fa24ebd9 100644
--- a/packages/react/src/Overlay/Overlay.features.stories.tsx
+++ b/packages/react/src/Overlay/Overlay.features.stories.tsx
@@ -560,25 +560,31 @@ export const PositionedOverlays = ({right, role}: OverlayProps) => {
           >
             <Box
               sx={{
-                height: '100vh',
                 width: '500px',
-                display: 'flex',
-                justifyContent: 'center',
-                alignItems: 'center',
               }}
             >
-              <IconButton
-                aria-label="Close"
-                onClick={closeOverlay}
-                icon={XIcon}
-                variant="invisible"
+              <Box
                 sx={{
-                  position: 'absolute',
-                  left: '5px',
-                  top: '5px',
+                  height: '100vh',
+                  maxWidth: 'calc(-1rem + 100vw)',
+                  display: 'flex',
+                  justifyContent: 'center',
+                  alignItems: 'center',
                 }}
-              />
-              <Text>Look! left aligned</Text>
+              >
+                <IconButton
+                  aria-label="Close"
+                  onClick={closeOverlay}
+                  icon={XIcon}
+                  variant="invisible"
+                  sx={{
+                    position: 'absolute',
+                    left: '5px',
+                    top: '5px',
+                  }}
+                />
+                <Text>Look! left aligned</Text>
+              </Box>
             </Box>
           </Overlay>
         ) : (
@@ -598,25 +604,31 @@ export const PositionedOverlays = ({right, role}: OverlayProps) => {
           >
             <Box
               sx={{
-                height: '100vh',
                 width: '500px',
-                display: 'flex',
-                justifyContent: 'center',
-                alignItems: 'center',
               }}
             >
-              <IconButton
-                aria-label="Close"
-                onClick={closeOverlay}
-                icon={XIcon}
-                variant="invisible"
+              <Box
                 sx={{
-                  position: 'absolute',
-                  right: '5px',
-                  top: '5px',
+                  height: '100vh',
+                  maxWidth: 'calc(-1rem + 100vw)',
+                  display: 'flex',
+                  justifyContent: 'center',
+                  alignItems: 'center',
                 }}
-              />
-              <Text>Look! right aligned</Text>
+              >
+                <IconButton
+                  aria-label="Close"
+                  onClick={closeOverlay}
+                  icon={XIcon}
+                  variant="invisible"
+                  sx={{
+                    position: 'absolute',
+                    right: '5px',
+                    top: '5px',
+                  }}
+                />
+                <Text>Look! right aligned</Text>
+              </Box>
             </Box>
           </Overlay>
         )
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index 4ef3cc2bde8..7f680d5edbd 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -206,6 +206,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
 
     // 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}
+    const reflowSize = ['xsmall', 'small', 'medium', 'auto'].includes(width)
 
     return (
       <Portal containerName={portalContainerName}>
@@ -226,7 +227,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
               ...styleFromProps,
             } as React.CSSProperties
           }
-          data-reflow-container={width === 'auto' && reflow ? true : undefined}
+          data-reflow-container={reflowSize && reflow ? true : undefined}
         />
       </Portal>
     )

From e98960f007512dca976d3700f5187638d015566c Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 29 Oct 2024 09:25:57 -0400
Subject: [PATCH 10/16] Fix tests

---
 packages/react/src/Overlay/Overlay.test.tsx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.test.tsx b/packages/react/src/Overlay/Overlay.test.tsx
index d80db8c755a..5a4fc97516a 100644
--- a/packages/react/src/Overlay/Overlay.test.tsx
+++ b/packages/react/src/Overlay/Overlay.test.tsx
@@ -154,7 +154,7 @@ describe('Overlay', () => {
     const user = userEvent.setup()
     const container = render(
       <ThemeProvider>
-        <PositionedOverlays right />
+        <PositionedOverlays role="dialog" right />
       </ThemeProvider>,
     )
 
@@ -162,8 +162,10 @@ describe('Overlay', () => {
     await user.click(container.getByText('Open right overlay'))
     expect(container.getByText('Look! right aligned')).toBeInTheDocument()
 
-    const overlay = container.getByText('Look! right aligned').parentElement?.parentElement
+    const innerOverlay = container.getByText('Look! right aligned')
+    const overlay = container.getByRole('dialog')
 
+    expect(innerOverlay).toBeInTheDocument()
     expect(overlay).toHaveStyle({position: 'fixed', right: 0})
     expect(overlay).not.toHaveStyle({left: 0})
 
@@ -182,7 +184,7 @@ describe('Overlay', () => {
     const user = userEvent.setup()
     const container = render(
       <ThemeProvider>
-        <PositionedOverlays />
+        <PositionedOverlays role="dialog" />
       </ThemeProvider>,
     )
 
@@ -190,7 +192,10 @@ describe('Overlay', () => {
     await user.click(container.getByText('Open left overlay'))
     expect(container.getByText('Look! left aligned')).toBeInTheDocument()
 
-    const overlay = container.getByText('Look! left aligned').parentElement?.parentElement
+    const innerOverlay = container.getByText('Look! left aligned')
+    const overlay = container.getByRole('dialog')
+
+    expect(innerOverlay).toBeInTheDocument()
     expect(overlay).toHaveStyle({left: 0, position: 'absolute'})
 
     spy.mockRestore()

From a241845358669b370bc6cfd047ae1f049fea5486 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 29 Oct 2024 18:00:24 -0400
Subject: [PATCH 11/16] Add to docs, rename prop, add feature flag

---
 .../react/src/FeatureFlags/DefaultFeatureFlags.ts    |  1 +
 packages/react/src/Overlay/Overlay.docs.json         |  6 ++++++
 .../react/src/Overlay/Overlay.features.stories.tsx   |  2 +-
 packages/react/src/Overlay/Overlay.tsx               | 12 ++++++++----
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
index 3ab756ea60f..b10d4e35447 100644
--- a/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
+++ b/packages/react/src/FeatureFlags/DefaultFeatureFlags.ts
@@ -6,4 +6,5 @@ export const DefaultFeatureFlags = FeatureFlagScope.create({
   primer_react_css_modules_ga: false,
   primer_react_action_list_item_as_button: false,
   primer_react_select_panel_with_modern_action_list: false,
+  primer_react_overlay_overflow: false,
 })
diff --git a/packages/react/src/Overlay/Overlay.docs.json b/packages/react/src/Overlay/Overlay.docs.json
index 6377595594b..8187889934b 100644
--- a/packages/react/src/Overlay/Overlay.docs.json
+++ b/packages/react/src/Overlay/Overlay.docs.json
@@ -112,6 +112,12 @@
       "defaultValue": "",
       "description": "If defined, Overlays will be rendered in the named portal. See also `Portal`."
     },
+    {
+      "name": "preventOverflow",
+      "type": "boolean",
+      "defaultValue": "true",
+      "description": "Determines if the Overlay width should be adjusted responsively if `width` is set to either `auto`, `medium` or lower and there is not enough space to display the Overlay. If `preventOverflow` is set to `false`, the Overlay will be displayed at the maximum width that fits within the viewport."
+    },
     {
       "name": "sx",
       "type": "SystemStyleObject"
diff --git a/packages/react/src/Overlay/Overlay.features.stories.tsx b/packages/react/src/Overlay/Overlay.features.stories.tsx
index f30fa24ebd9..777e46676d9 100644
--- a/packages/react/src/Overlay/Overlay.features.stories.tsx
+++ b/packages/react/src/Overlay/Overlay.features.stories.tsx
@@ -327,7 +327,7 @@ export const NestedOverlays = ({role}: OverlayProps) => {
           ignoreClickRefs={[buttonRef]}
           top={100}
           left={16}
-          reflow={true}
+          preventOverflow={false}
           ref={primaryContainer}
           role={role}
           aria-modal={role === 'dialog' ? 'true' : undefined}
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index 7f680d5edbd..8b9579d99eb 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -13,6 +13,7 @@ import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import type {AnchorSide} from '@primer/behaviors'
 import {useTheme} from '../ThemeProvider'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
+import {useFeatureFlag} from '../FeatureFlags'
 
 type StyledOverlayProps = {
   width?: keyof typeof widthMap
@@ -114,7 +115,7 @@ type BaseOverlayProps = {
   preventFocusOnOpen?: boolean
   role?: AriaRole
   children?: React.ReactNode
-  reflow?: boolean
+  preventOverflow?: boolean
 }
 
 type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
@@ -138,7 +139,7 @@ type OwnOverlayProps = Merge<StyledOverlayProps, BaseOverlayProps>
  * @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.
- * @param reflow Optional. If true, the Overlay width will be adjusted responsively at `320px` if there is not enough space to display the Overlay in the requested position.
+ * @param preventOverflow Optional. The Overlay width will be adjusted responsively if width is `auto`, `medium` or lower and there is not enough space to display the Overlay. If `preventOverflow` is `true`, the width of the `Overlay` will not be adjusted.
  */
 const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
   (
@@ -161,7 +162,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
       preventFocusOnOpen,
       position,
       style: styleFromProps = {},
-      reflow = true,
+      preventOverflow = true,
       ...rest
     },
     forwardedRef,
@@ -208,6 +209,9 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
     const leftPosition: React.CSSProperties = left === undefined && right === undefined ? {left: 0} : {left}
     const reflowSize = ['xsmall', 'small', 'medium', 'auto'].includes(width)
 
+    const enabled = useFeatureFlag('primer_react_overlay_overflow')
+    const overflow = enabled && reflowSize ? true : undefined
+
     return (
       <Portal containerName={portalContainerName}>
         <StyledOverlay
@@ -227,7 +231,7 @@ const Overlay = React.forwardRef<HTMLDivElement, OwnOverlayProps>(
               ...styleFromProps,
             } as React.CSSProperties
           }
-          data-reflow-container={reflowSize && reflow ? true : undefined}
+          data-reflow-container={overflow || (reflowSize && !preventOverflow) ? true : undefined}
         />
       </Portal>
     )

From 4ef10224a10a1c99d1c083c837e72fe4eab89aff Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Tue, 29 Oct 2024 18:16:49 -0400
Subject: [PATCH 12/16] Add new prop to `AnchoredOverlay`

---
 packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index 869c7620c4d..c6166938da9 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -198,7 +198,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           left={position?.left || 0}
           anchorSide={position?.anchorSide}
           className={className}
-          reflow={false}
+          preventOverflow={false}
           {...overlayProps}
         >
           {children}

From 46ed885df97c55460363b2e11444bd084cb6c77b Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Wed, 30 Oct 2024 09:35:58 -0400
Subject: [PATCH 13/16] Fix test

---
 packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index c6166938da9..bfc08cf041a 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -198,7 +198,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           left={position?.left || 0}
           anchorSide={position?.anchorSide}
           className={className}
-          preventOverflow={false}
+          preventOverflow={true}
           {...overlayProps}
         >
           {children}

From bdc6ec3aeea9e5f6e110055fa76a62f6a272c070 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Thu, 31 Oct 2024 14:42:30 -0400
Subject: [PATCH 14/16] edit stories to be responsive at min of `320px`

---
 .../src/Overlay/Overlay.features.stories.tsx    | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.features.stories.tsx b/packages/react/src/Overlay/Overlay.features.stories.tsx
index 777e46676d9..6b31bdbb7ca 100644
--- a/packages/react/src/Overlay/Overlay.features.stories.tsx
+++ b/packages/react/src/Overlay/Overlay.features.stories.tsx
@@ -172,6 +172,7 @@ export const OverlayOnTopOfOverlay = ({anchorSide, role}: OverlayProps) => {
           role={role}
           aria-modal={role === 'dialog' ? 'true' : undefined}
           ref={primaryContainer}
+          preventOverflow={false}
         >
           <Button ref={secondaryButtonRef} onClick={() => setIsSecondaryOpen(!isSecondaryOpen)}>
             open overlay
@@ -188,11 +189,12 @@ export const OverlayOnTopOfOverlay = ({anchorSide, role}: OverlayProps) => {
               role={role}
               aria-modal={role === 'dialog' ? 'true' : undefined}
               ref={secondaryContainer}
+              preventOverflow={false}
             >
               <Box display="flex" flexDirection="column" p={2}>
                 <Text>Select an option!</Text>
                 <ActionMenu>
-                  <ActionMenu.Button sx={{width: 200}}>{selectedItem}</ActionMenu.Button>
+                  <ActionMenu.Button>{selectedItem}</ActionMenu.Button>
                   <ActionMenu.Overlay>
                     <ActionList selectionVariant="single">
                       {items.map(item => (
@@ -248,6 +250,7 @@ export const MemexNestedOverlays = ({role}: OverlayProps) => {
           role={role}
           aria-modal={role === 'dialog' ? 'true' : undefined}
           ref={containerRef}
+          preventOverflow={false}
         >
           <Box as="form" onSubmit={() => setOverlayOpen(false)} sx={{display: 'flex', flexDirection: 'column', py: 2}}>
             <Box sx={{paddingX: 3, display: 'flex', alignItems: 'center', gap: 1}}>
@@ -435,17 +438,17 @@ export const MemexIssueOverlay = ({role}: OverlayProps) => {
       {overlayOpen && (
         <Overlay
           height="auto"
-          width="large"
+          width="auto"
           onEscape={() => setOverlayOpen(false)}
           onClickOutside={() => setOverlayOpen(false)}
           returnFocusRef={linkRef}
           top={0}
-          left="calc(100vw - 480px)"
+          left="calc(100vw - 350px)"
           role={role}
           aria-modal={role === 'dialog' ? 'true' : undefined}
           ref={containerRef}
         >
-          <Box sx={{p: 4, height: '100vh'}}>
+          <Box sx={{p: 4, height: '100vh', width: '350px'}}>
             <Box sx={{display: 'flex', alignItems: 'center', gap: 1, mb: 2}}>
               <Label size="large">
                 <IssueDraftIcon /> Draft
@@ -489,7 +492,7 @@ export const MemexIssueOverlay = ({role}: OverlayProps) => {
                 aria-label="Change issue title"
                 sx={{
                   width: '100%',
-                  fontSize: 4,
+                  fontSize: 3,
                   color: 'fg.default',
                   p: 2,
                   textAlign: 'left',
@@ -560,7 +563,7 @@ export const PositionedOverlays = ({right, role}: OverlayProps) => {
           >
             <Box
               sx={{
-                width: '500px',
+                width: ['350px', '500px'],
               }}
             >
               <Box
@@ -604,7 +607,7 @@ export const PositionedOverlays = ({right, role}: OverlayProps) => {
           >
             <Box
               sx={{
-                width: '500px',
+                width: ['350px', '500px'],
               }}
             >
               <Box

From 6d8ab1e8d71dcf6189a83b44c8edf34f2f2fba7b Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Thu, 31 Oct 2024 15:11:41 -0400
Subject: [PATCH 15/16] Add test for FF

---
 packages/react/src/Overlay/Overlay.test.tsx | 44 ++++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/Overlay/Overlay.test.tsx b/packages/react/src/Overlay/Overlay.test.tsx
index 5a4fc97516a..050622d2914 100644
--- a/packages/react/src/Overlay/Overlay.test.tsx
+++ b/packages/react/src/Overlay/Overlay.test.tsx
@@ -7,12 +7,14 @@ import theme from '../theme'
 import BaseStyles from '../BaseStyles'
 import {ThemeProvider} from '../ThemeProvider'
 import {NestedOverlays, MemexNestedOverlays, MemexIssueOverlay, PositionedOverlays} from './Overlay.features.stories'
+import {FeatureFlags} from '../FeatureFlags'
 
 type TestComponentSettings = {
   initialFocus?: 'button'
+  width?: string
   callback?: () => void
 }
-const TestComponent = ({initialFocus, callback}: TestComponentSettings) => {
+const TestComponent = ({initialFocus, width = 'small', callback}: TestComponentSettings) => {
   const [isOpen, setIsOpen] = useState(false)
   const buttonRef = useRef<HTMLButtonElement>(null)
   const confirmButtonRef = useRef<HTMLButtonElement>(null)
@@ -38,7 +40,7 @@ const TestComponent = ({initialFocus, callback}: TestComponentSettings) => {
               ignoreClickRefs={[buttonRef]}
               onEscape={closeOverlay}
               onClickOutside={closeOverlay}
-              width="small"
+              width={width}
             >
               <Box display="flex" flexDirection="column" p={2}>
                 <Text>Are you sure?</Text>
@@ -287,4 +289,42 @@ describe('Overlay', () => {
     // if stopPropagation worked, mockHandler would not have been called
     expect(mockHandler).toHaveBeenCalledTimes(0)
   })
+
+  it('should not have `data-reflow-container` if FF is not enabled', async () => {
+    const user = userEvent.setup()
+    const {getByRole} = render(<TestComponent />)
+
+    await user.click(getByRole('button', {name: 'open overlay'}))
+
+    const container = getByRole('none')
+    expect(container).not.toHaveAttribute('data-reflow-container')
+  })
+
+  it('should `data-reflow-container` if FF is enabled', async () => {
+    const user = userEvent.setup()
+    const {getByRole} = render(
+      <FeatureFlags flags={{primer_react_overlay_overflow: true}}>
+        <TestComponent />
+      </FeatureFlags>,
+    )
+
+    await user.click(getByRole('button', {name: 'open overlay'}))
+
+    const container = getByRole('none')
+    expect(container).toHaveAttribute('data-reflow-container')
+  })
+
+  it('should not have `data-reflow-container` if FF is enabled but the overlay is above `medium`', async () => {
+    const user = userEvent.setup()
+    const {getByRole} = render(
+      <FeatureFlags flags={{primer_react_overlay_overflow: true}}>
+        <TestComponent width="large" />
+      </FeatureFlags>,
+    )
+
+    await user.click(getByRole('button', {name: 'open overlay'}))
+
+    const container = getByRole('none')
+    expect(container).not.toHaveAttribute('data-reflow-container')
+  })
 })

From 2f7a92c2a81435432e41f9b031fc029dba372d45 Mon Sep 17 00:00:00 2001
From: Tyler Jones <tylerjdev@github.com>
Date: Thu, 31 Oct 2024 15:19:27 -0400
Subject: [PATCH 16/16] Fix types

---
 packages/react/src/Overlay/Overlay.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/Overlay/Overlay.test.tsx b/packages/react/src/Overlay/Overlay.test.tsx
index 050622d2914..7c8c90b953a 100644
--- a/packages/react/src/Overlay/Overlay.test.tsx
+++ b/packages/react/src/Overlay/Overlay.test.tsx
@@ -11,7 +11,7 @@ import {FeatureFlags} from '../FeatureFlags'
 
 type TestComponentSettings = {
   initialFocus?: 'button'
-  width?: string
+  width?: 'small' | 'medium' | 'large' | 'auto' | 'xlarge' | 'xxlarge'
   callback?: () => void
 }
 const TestComponent = ({initialFocus, width = 'small', callback}: TestComponentSettings) => {