From 53713b2f3ab7dd7084ce3e602c01c3f66ccd7579 Mon Sep 17 00:00:00 2001
From: Cole Bemis <colebemis@github.com>
Date: Mon, 20 Jun 2022 10:20:09 -0500
Subject: [PATCH] Deprecate SideNav in favor of NavList (#2120)

* Deprecate SideNav

* Create small-donkeys-provide.md
---
 .changeset/small-donkeys-provide.md           | 29 +++++++++++++++++
 docs/content/{ => deprecated}/SideNav.md      | 32 +++++++++++++++++--
 .../src/@primer/gatsby-theme-doctocat/nav.yml |  5 +--
 src/SideNav.tsx                               |  1 +
 4 files changed, 63 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/small-donkeys-provide.md
 rename docs/content/{ => deprecated}/SideNav.md (90%)

diff --git a/.changeset/small-donkeys-provide.md b/.changeset/small-donkeys-provide.md
new file mode 100644
index 00000000000..e8d8e02c13d
--- /dev/null
+++ b/.changeset/small-donkeys-provide.md
@@ -0,0 +1,29 @@
+---
+"@primer/react": patch
+---
+
+Deprecate SideNav in favor of [NavList](https://primer.style/NavList).
+
+## Before
+
+```jsx
+<SideNav aria-label="Main">
+  <SideNav.Link href="/" selected>
+    Home
+  </SideNav.Link>
+  <SideNav.Link href="/about">About</SideNav.Link>
+  <SideNav.Link href="/contact">Contact</SideNav.Link>
+</SideNav>
+```
+
+## After
+
+```jsx
+<NavList aria-label="Main">
+  <NavList.Item href="/" aria-current="page">
+    Home
+  </NavList.Item>
+  <NavList.Item href="/about">About</NavList.Item>
+  <NavList.Item href="/contact">Contact</NavList.Item>
+</NavList>
+```
diff --git a/docs/content/SideNav.md b/docs/content/deprecated/SideNav.md
similarity index 90%
rename from docs/content/SideNav.md
rename to docs/content/deprecated/SideNav.md
index 04c2ff0535d..a2db1858682 100644
--- a/docs/content/SideNav.md
+++ b/docs/content/deprecated/SideNav.md
@@ -1,10 +1,38 @@
 ---
 componentId: side_nav
 title: SideNav
-status: Alpha
+status: Deprecated
 ---
 
-The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **SideNav elements have no default width or positioning.**
+The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, SideNav elements have no default width or positioning.
+
+## Deprecation
+
+Use [NavList](/NavList) instead.
+
+**Before**
+
+```jsx
+<SideNav aria-label="Main">
+  <SideNav.Link href="/" selected>
+    Home
+  </SideNav.Link>
+  <SideNav.Link href="/about">About</SideNav.Link>
+  <SideNav.Link href="/contact">Contact</SideNav.Link>
+</SideNav>
+```
+
+**After**
+
+```jsx
+<NavList aria-label="Main">
+  <NavList.Item href="/" aria-current="page">
+    Home
+  </NavList.Item>
+  <NavList.Item href="/about">About</NavList.Item>
+  <NavList.Item href="/contact">Contact</NavList.Item>
+</NavList>
+```
 
 ## Default example
 
diff --git a/docs/src/@primer/gatsby-theme-doctocat/nav.yml b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
index b353429d7c5..48faae7fe91 100644
--- a/docs/src/@primer/gatsby-theme-doctocat/nav.yml
+++ b/docs/src/@primer/gatsby-theme-doctocat/nav.yml
@@ -116,8 +116,7 @@
       url: /Select
     - title: SelectPanel
       url: /SelectPanel
-    - title: SideNav
-      url: /SideNav
+
     - title: Spinner
       url: /Spinner
     - title: StateLabel
@@ -184,3 +183,5 @@
       url: /deprecated/Position
     - title: SelectMenu
       url: /deprecated/SelectMenu
+    - title: SideNav
+      url: /deprecated/SideNav
diff --git a/src/SideNav.tsx b/src/SideNav.tsx
index 3b4cc0bd768..2ece1f38816 100644
--- a/src/SideNav.tsx
+++ b/src/SideNav.tsx
@@ -187,4 +187,5 @@ SideNavLink.displayName = 'SideNav.Link'
 export type SideNavProps = ComponentProps<typeof SideNav>
 export type SideNavLinkProps = ComponentProps<typeof SideNavLink>
 
+/** @deprecated Use [NavList](https://primer.style/react/NavList) instead */
 export default Object.assign(SideNav, {Link: SideNavLink})