From 9ce64937ce234d65f3e4ab28bfed1a71aac9a4de Mon Sep 17 00:00:00 2001
From: Josep Martins <josepmartins@github.com>
Date: Mon, 8 Aug 2022 12:06:01 +0200
Subject: [PATCH] Overlay documentation fixes (#2221)

* Add/remove missing/nonexisting props

* Add AnchoredOverlay in the navigation

* Add wicked-otters-warn changeset
---
 .changeset/wicked-otters-warn.md              |  5 ++++
 docs/content/Overlay.mdx                      | 29 ++++++++++++-------
 .../src/@primer/gatsby-theme-doctocat/nav.yml |  2 ++
 3 files changed, 25 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/wicked-otters-warn.md

diff --git a/.changeset/wicked-otters-warn.md b/.changeset/wicked-otters-warn.md
new file mode 100644
index 00000000000..43cede4e2f1
--- /dev/null
+++ b/.changeset/wicked-otters-warn.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+Overlay documentation fixes
diff --git a/docs/content/Overlay.mdx b/docs/content/Overlay.mdx
index 2d7dbba946c..90a912e9dd0 100644
--- a/docs/content/Overlay.mdx
+++ b/docs/content/Overlay.mdx
@@ -72,23 +72,13 @@ See the W3C accessibility recommendations for modals [here](https://www.w3.org/T
 
 ## Positioning
 
-`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 [customizing the portal or specifying a different portal root](/Portal#customizing-the-portal-root) to achieve different positioning behavior.
+`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.
 
 ## Props
 
 ### Overlay
 
 <PropsTable>
-  <PropsTableRow
-    required
-    name="anchorRef"
-    type="React.RefObject<HTMLElement>"
-    description={
-      <>
-        Element the <InlineCode>Overlay</InlineCode> should be anchored to.
-      </>
-    }
-  />
   <PropsTableRow
     required
     name="returnFocusRef"
@@ -182,6 +172,23 @@ See the W3C accessibility recommendations for modals [here](https://www.w3.org/T
       </>
     }
   />
+  <PropsTableRow
+    name="maxHeight"
+    type={`| 'xsmall'
+| 'small'
+| 'medium'
+| 'large'
+| 'xlarge'`}
+    description={
+      <>
+        Sets the maximum height of the <InlineCode>Overlay</InlineCode>, pick from our set list of heights.
+        <InlineCode>xsmall</InlineCode> corresponds to <InlineCode>192px</InlineCode>, <InlineCode>small</InlineCode> corresponds
+        to <InlineCode>256px</InlineCode>, <InlineCode>medium</InlineCode> corresponds to <InlineCode>320px</InlineCode>,{' '}
+        <InlineCode>large</InlineCode> corresponds to <InlineCode>432px</InlineCode>, <InlineCode>xlarge</InlineCode> corresponds
+        to <InlineCode>600px</InlineCode>.
+      </>
+    }
+  />
   <PropsTableRow
     name="visibility"
     type={`| 'visible' 
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
index a5d0f6c2dbf..5e965fbe9c1 100644
--- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml
+++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -38,6 +38,8 @@
       url: /ActionList
     - title: ActionMenu
       url: /ActionMenu
+    - title: AnchoredOverlay
+      url: /AnchoredOverlay
     - title: Autocomplete
       url: /Autocomplete
     - title: Avatar