Merge branch 'main' into correct-semantics-for-tablist

.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>
+```

docs/content/SideNav.md → 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
 

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

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})