From fce0940b45ed17d42ea1e6d31cb0e7d9a1e8e2d2 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Thu, 10 Oct 2024 13:45:50 -0400
Subject: [PATCH 1/5] adds NavList.GroupHeading component

---
 packages/react/src/ActionList/Group.tsx       |  4 +--
 packages/react/src/ActionList/index.ts        |  2 +-
 .../react/src/NavList/NavList.stories.tsx     | 28 +++++++++++++++++++
 packages/react/src/NavList/NavList.tsx        | 23 +++++++++++++++
 4 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/ActionList/Group.tsx b/packages/react/src/ActionList/Group.tsx
index da31c6830ef..fefafde863e 100644
--- a/packages/react/src/ActionList/Group.tsx
+++ b/packages/react/src/ActionList/Group.tsx
@@ -106,7 +106,7 @@ export const Group: React.FC<React.PropsWithChildren<ActionListGroupProps>> = ({
   )
 }
 
-export type GroupHeadingProps = Pick<ActionListGroupProps, 'variant' | 'auxiliaryText'> &
+export type ActionListGroupHeadingProps = Pick<ActionListGroupProps, 'variant' | 'auxiliaryText'> &
   Omit<ActionListHeadingProps, 'as'> &
   SxProp &
   React.HTMLAttributes<HTMLElement> & {
@@ -122,7 +122,7 @@ export type GroupHeadingProps = Pick<ActionListGroupProps, 'variant' | 'auxiliar
  * hidden from the accessibility tree due to the limitation of listbox children. https://w3c.github.io/aria/#listbox
  * groups under menu or listbox are labelled by `aria-label`
  */
-export const GroupHeading: React.FC<React.PropsWithChildren<GroupHeadingProps>> = ({
+export const GroupHeading: React.FC<React.PropsWithChildren<ActionListGroupHeadingProps>> = ({
   as,
   variant,
   // We are not recommending this prop to be used, it should only be used internally for incremental rollout.
diff --git a/packages/react/src/ActionList/index.ts b/packages/react/src/ActionList/index.ts
index e3ca7e4e333..71542b10680 100644
--- a/packages/react/src/ActionList/index.ts
+++ b/packages/react/src/ActionList/index.ts
@@ -9,7 +9,7 @@ import {LeadingVisual, TrailingVisual} from './Visuals'
 import {Heading} from './Heading'
 
 export type {ActionListProps} from './shared'
-export type {ActionListGroupProps} from './Group'
+export type {ActionListGroupProps, ActionListGroupHeadingProps} from './Group'
 export type {ActionListItemProps} from './shared'
 export type {ActionListLinkItemProps} from './LinkItem'
 export type {ActionListDividerProps} from './Divider'
diff --git a/packages/react/src/NavList/NavList.stories.tsx b/packages/react/src/NavList/NavList.stories.tsx
index 97403ba9d2d..4410ea85a50 100644
--- a/packages/react/src/NavList/NavList.stories.tsx
+++ b/packages/react/src/NavList/NavList.stories.tsx
@@ -247,6 +247,34 @@ export const WithGroup: StoryFn = () => (
   </PageLayout>
 )
 
+export const WithGroupHeadingLinks: StoryFn = () => (
+  <PageLayout>
+    <PageLayout.Pane position="start">
+      <NavList>
+        <NavList.Group>
+          <NavList.GroupHeading>
+            <a href="#group-1">Group 1</a>
+          </NavList.GroupHeading>
+          <NavList.Item aria-current="true" href="#">
+            Item 1A
+          </NavList.Item>
+          <NavList.Item href="#">Item 1B</NavList.Item>
+          <NavList.Item href="#">Item 1C</NavList.Item>
+        </NavList.Group>
+        <NavList.Group>
+          <NavList.GroupHeading>
+            <a href="#group-2">Group 2</a>
+          </NavList.GroupHeading>
+          <NavList.Item href="#">Item 2A</NavList.Item>
+          <NavList.Item href="#">Item 2B</NavList.Item>
+          <NavList.Item href="#">Item 2C</NavList.Item>
+        </NavList.Group>
+      </NavList>
+    </PageLayout.Pane>
+    <PageLayout.Content></PageLayout.Content>
+  </PageLayout>
+)
+
 export const WithTrailingAction = () => {
   return (
     <PageLayout>
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 2ba2fc0d2c0..87249d4e0ae 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -7,6 +7,7 @@ import type {
   ActionListDividerProps,
   ActionListLeadingVisualProps,
   ActionListTrailingVisualProps,
+  ActionListGroupHeadingProps,
 } from '../ActionList'
 import {ActionList} from '../ActionList'
 import {ActionListContainerContext} from '../ActionList/ActionListContainerContext'
@@ -290,6 +291,27 @@ const Group: React.FC<NavListGroupProps> = ({title, children, sx: sxProp = defau
 
 Group.displayName = 'NavList.Group'
 
+export type NavListGroupHeadingProps = ActionListGroupHeadingProps
+
+/**
+ * This is an alternative to the `title` prop on `NavList.Group`.
+ * It was primarily added to allow links in group headings.
+ */
+const GroupHeading: React.FC<NavListGroupHeadingProps> = ({sx: sxProp = defaultSxProp, ...rest}) => {
+  return (
+    <ActionList.GroupHeading
+      as="h3"
+      sx={merge<SxProp['sx']>(
+        {
+          '> a {': {color: 'inherit', textDecoration: 'inherit', ':hover': {textDecoration: 'underline'}},
+        },
+        sxProp,
+      )}
+      {...rest}
+    />
+  )
+}
+
 // ----------------------------------------------------------------------------
 // Export
 
@@ -301,4 +323,5 @@ export const NavList = Object.assign(Root, {
   TrailingAction,
   Divider,
   Group,
+  GroupHeading,
 })

From fb5771777931d7e56edb3017cb836d97549790fa Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Thu, 10 Oct 2024 13:58:21 -0400
Subject: [PATCH 2/5] Create twelve-kings-confess.md

---
 .changeset/twelve-kings-confess.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/twelve-kings-confess.md

diff --git a/.changeset/twelve-kings-confess.md b/.changeset/twelve-kings-confess.md
new file mode 100644
index 00000000000..7d55fca5497
--- /dev/null
+++ b/.changeset/twelve-kings-confess.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Adds NavList.GroupHeading component that can be used instead of the ActionList.Group 'title' prop if you need to render something besides a string

From b485e2daad0acdf53b5140e4e73ed9c16457a21d Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Tue, 15 Oct 2024 15:00:56 -0400
Subject: [PATCH 3/5] re-styles NavList.GroupHeading links to be
 fgColor-default

---
 packages/react/src/NavList/NavList.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 87249d4e0ae..ae9d29b7d4a 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -303,7 +303,11 @@ const GroupHeading: React.FC<NavListGroupHeadingProps> = ({sx: sxProp = defaultS
       as="h3"
       sx={merge<SxProp['sx']>(
         {
-          '> a {': {color: 'inherit', textDecoration: 'inherit', ':hover': {textDecoration: 'underline'}},
+          '> a {': {
+            color: 'var(--fgColor-default)',
+            textDecoration: 'inherit',
+            ':hover': {textDecoration: 'underline'},
+          },
         },
         sxProp,
       )}

From 0feefefc7b5ea090368f86c5d34ec4e7e24bc148 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Tue, 22 Oct 2024 14:50:23 -0400
Subject: [PATCH 4/5] guards against 'title' AND 'NavList.GroupHeading' being
 used together, adds tests, updates docs

---
 packages/react/src/NavList/NavList.docs.json  | 18 +++++++
 .../react/src/NavList/NavList.stories.tsx     |  2 +-
 packages/react/src/NavList/NavList.test.tsx   | 23 +++++++++
 packages/react/src/NavList/NavList.tsx        | 21 ++++++--
 .../__snapshots__/NavList.test.tsx.snap       | 50 +++++++++++--------
 5 files changed, 87 insertions(+), 27 deletions(-)

diff --git a/packages/react/src/NavList/NavList.docs.json b/packages/react/src/NavList/NavList.docs.json
index efdff7a4d9d..c6df5c21b99 100644
--- a/packages/react/src/NavList/NavList.docs.json
+++ b/packages/react/src/NavList/NavList.docs.json
@@ -113,6 +113,24 @@
     },
     {
       "name": "NavList.Group",
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "description": "The text that gets rendered as the group's heading. Alternatively, you can pass the `NavList.GroupHeading` component as a child of `NavList.Group`.\n If both `title` and `NavList.GroupHeading` are passed, `NavList.GroupHeading` will be rendered as the heading."
+        },
+        {
+          "name": "sx",
+          "type": "SystemStyleObject"
+        },
+        {
+          "name": "ref",
+          "type": "React.RefObject<HTMLElement>"
+        }
+      ]
+    },
+    {
+      "name": "NavList.GroupHeading",
       "props": [
         {
           "name": "sx",
diff --git a/packages/react/src/NavList/NavList.stories.tsx b/packages/react/src/NavList/NavList.stories.tsx
index 4410ea85a50..8191cd3c7e4 100644
--- a/packages/react/src/NavList/NavList.stories.tsx
+++ b/packages/react/src/NavList/NavList.stories.tsx
@@ -251,7 +251,7 @@ export const WithGroupHeadingLinks: StoryFn = () => (
   <PageLayout>
     <PageLayout.Pane position="start">
       <NavList>
-        <NavList.Group>
+        <NavList.Group title="Group one">
           <NavList.GroupHeading>
             <a href="#group-1">Group 1</a>
           </NavList.GroupHeading>
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index b62bf6290c2..178ff7a3a81 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -63,6 +63,29 @@ describe('NavList', () => {
     expect(container).toMatchSnapshot()
   })
 
+  it('only shows NavList.GroupHeading when NavList.Group `title` prop is passed AND NavList.GroupHeading is a child', () => {
+    const {getByText} = render(
+      <ThemeProvider>
+        <NavList>
+          <NavList.Group title="Overview">
+            <NavList.GroupHeading>Group heading</NavList.GroupHeading>
+            <NavList.Item href="/getting-started" aria-current="page">
+              Getting started
+            </NavList.Item>
+          </NavList.Group>
+          <NavList.Group title="Components">
+            <NavList.Item href="/Avatar">Avatar</NavList.Item>
+          </NavList.Group>
+        </NavList>
+      </ThemeProvider>,
+    )
+    const groupHeading = getByText('Group heading')
+    const groupTitle = getByText('Overview')
+
+    expect(groupHeading).toBeVisible()
+    expect(groupTitle).not.toBeVisible()
+  })
+
   it('supports TrailingAction', async () => {
     const {getByRole} = render(
       <NavList>
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index ae9d29b7d4a..05594a55ca7 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -280,9 +280,21 @@ const Group: React.FC<NavListGroupProps> = ({title, children, sx: sxProp = defau
     <>
       {/* Hide divider if the group is the first item in the list */}
       <ActionList.Divider sx={{'&:first-child': {display: 'none'}}} />
-      <ActionList.Group {...props} sx={sxProp}>
+      <ActionList.Group
+        {...props}
+        // If somebody tries to pass the `title` prop AND a `NavList.GroupHeading` as a child, hide the `ActionList.GroupHeading`
+        sx={merge<SxProp['sx']>(sxProp, {
+          ':has([data-component="NavList.GroupHeading"]):has([data-component="ActionList.GroupHeading"])': {
+            '[data-component="ActionList.GroupHeading"]': {display: 'none'},
+          },
+        })}
+      >
         {/* Setting up the default value for the heading level. TODO: API update to give flexibility to NavList.Group title's heading level */}
-        {title ? <ActionList.GroupHeading as="h3">{title}</ActionList.GroupHeading> : null}
+        {title ? (
+          <ActionList.GroupHeading as="h3" data-component="ActionList.GroupHeading">
+            {title}
+          </ActionList.GroupHeading>
+        ) : null}
         {children}
       </ActionList.Group>
     </>
@@ -297,10 +309,10 @@ export type NavListGroupHeadingProps = ActionListGroupHeadingProps
  * This is an alternative to the `title` prop on `NavList.Group`.
  * It was primarily added to allow links in group headings.
  */
-const GroupHeading: React.FC<NavListGroupHeadingProps> = ({sx: sxProp = defaultSxProp, ...rest}) => {
+const GroupHeading: React.FC<NavListGroupHeadingProps> = ({as = 'h3', sx: sxProp = defaultSxProp, ...rest}) => {
   return (
     <ActionList.GroupHeading
-      as="h3"
+      as={as}
       sx={merge<SxProp['sx']>(
         {
           '> a {': {
@@ -311,6 +323,7 @@ const GroupHeading: React.FC<NavListGroupHeadingProps> = ({sx: sxProp = defaultS
         },
         sxProp,
       )}
+      data-component="NavList.GroupHeading"
       {...rest}
     />
   )
diff --git a/packages/react/src/NavList/__snapshots__/NavList.test.tsx.snap b/packages/react/src/NavList/__snapshots__/NavList.test.tsx.snap
index a8eb41cec20..c425395d008 100644
--- a/packages/react/src/NavList/__snapshots__/NavList.test.tsx.snap
+++ b/packages/react/src/NavList/__snapshots__/NavList.test.tsx.snap
@@ -464,6 +464,10 @@ exports[`NavList renders with groups 1`] = `
   margin-top: 8px;
 }
 
+.c2:has([data-component="NavList.GroupHeading"]):has([data-component="ActionList.GroupHeading"]) [data-component="ActionList.GroupHeading"] {
+  display: none;
+}
+
 .c3 {
   padding-top: 6px;
   padding-bottom: 6px;
@@ -872,6 +876,7 @@ exports[`NavList renders with groups 1`] = `
         >
           <h3
             class="ActionListGroupHeading Heading"
+            data-component="ActionList.GroupHeading"
             id=":r7:"
           >
             Overview
@@ -920,6 +925,7 @@ exports[`NavList renders with groups 1`] = `
         >
           <h3
             class="ActionListGroupHeading Heading"
+            data-component="ActionList.GroupHeading"
             id=":r9:"
           >
             Components
@@ -1389,15 +1395,15 @@ exports[`NavList.Item with NavList.SubNav does not have active styles if SubNav
       class="c0"
     >
       <li
-        aria-labelledby=":r26:"
+        aria-labelledby=":r2c:"
         class="c1 c2"
       >
         <button
-          aria-controls=":r27:"
+          aria-controls=":r2d:"
           aria-expanded="true"
-          aria-labelledby=":r26:--label :r26:--trailing-visual "
+          aria-labelledby=":r2c:--label :r2c:--trailing-visual "
           class="c3 c4"
-          id=":r26:"
+          id=":r2c:"
           tabindex="0"
         >
           <div
@@ -1409,13 +1415,13 @@ exports[`NavList.Item with NavList.SubNav does not have active styles if SubNav
             >
               <span
                 class="c1 c7"
-                id=":r26:--label"
+                id=":r2c:--label"
               >
                 Item
               </span>
               <span
                 class="c1 c8"
-                id=":r26:--trailing-visual"
+                id=":r2c:--trailing-visual"
               >
                 <svg
                   aria-hidden="true"
@@ -1437,19 +1443,19 @@ exports[`NavList.Item with NavList.SubNav does not have active styles if SubNav
         </button>
         <div>
           <ul
-            aria-labelledby=":r26:"
+            aria-labelledby=":r2c:"
             class="c1 c10"
-            id=":r27:"
+            id=":r2d:"
           >
             <li
               class="c3 c11"
             >
               <a
                 aria-current="page"
-                aria-labelledby=":r29:--label  "
+                aria-labelledby=":r2f:--label  "
                 class="c12 c13"
                 href="#"
-                id=":r29:"
+                id=":r2f:"
                 tabindex="0"
               >
                 <div
@@ -1458,7 +1464,7 @@ exports[`NavList.Item with NavList.SubNav does not have active styles if SubNav
                 >
                   <span
                     class="c1 c14"
-                    id=":r29:--label"
+                    id=":r2f:--label"
                   >
                     Sub Item
                   </span>
@@ -1923,15 +1929,15 @@ exports[`NavList.Item with NavList.SubNav has active styles if SubNav contains t
       class="c0"
     >
       <li
-        aria-labelledby=":r20:"
+        aria-labelledby=":r26:"
         class="c1 c2"
       >
         <button
-          aria-controls=":r21:"
+          aria-controls=":r27:"
           aria-expanded="false"
-          aria-labelledby=":r20:--label :r20:--trailing-visual "
+          aria-labelledby=":r26:--label :r26:--trailing-visual "
           class="c3 c4"
-          id=":r20:"
+          id=":r26:"
           tabindex="0"
         >
           <div
@@ -1943,13 +1949,13 @@ exports[`NavList.Item with NavList.SubNav has active styles if SubNav contains t
             >
               <span
                 class="c1 c7"
-                id=":r20:--label"
+                id=":r26:--label"
               >
                 Item
               </span>
               <span
                 class="c1 c8"
-                id=":r20:--trailing-visual"
+                id=":r26:--trailing-visual"
               >
                 <svg
                   aria-hidden="true"
@@ -1971,19 +1977,19 @@ exports[`NavList.Item with NavList.SubNav has active styles if SubNav contains t
         </button>
         <div>
           <ul
-            aria-labelledby=":r20:"
+            aria-labelledby=":r26:"
             class="c1 c10"
-            id=":r21:"
+            id=":r27:"
           >
             <li
               class="c3 c11"
             >
               <a
                 aria-current="page"
-                aria-labelledby=":r23:--label  "
+                aria-labelledby=":r29:--label  "
                 class="c12 c13"
                 href="#"
-                id=":r23:"
+                id=":r29:"
                 tabindex="0"
               >
                 <div
@@ -1992,7 +1998,7 @@ exports[`NavList.Item with NavList.SubNav has active styles if SubNav contains t
                 >
                   <span
                     class="c1 c7"
-                    id=":r23:--label"
+                    id=":r29:--label"
                   >
                     Sub Item
                   </span>

From 93fc0f3d50ebfb1155abd9774a6118878d293b68 Mon Sep 17 00:00:00 2001
From: Mike Perrotti <mperrotti@github.com>
Date: Tue, 22 Oct 2024 14:52:12 -0400
Subject: [PATCH 5/5] rm title prop from NavList.GroupHeading story

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

diff --git a/packages/react/src/NavList/NavList.stories.tsx b/packages/react/src/NavList/NavList.stories.tsx
index 8191cd3c7e4..4410ea85a50 100644
--- a/packages/react/src/NavList/NavList.stories.tsx
+++ b/packages/react/src/NavList/NavList.stories.tsx
@@ -251,7 +251,7 @@ export const WithGroupHeadingLinks: StoryFn = () => (
   <PageLayout>
     <PageLayout.Pane position="start">
       <NavList>
-        <NavList.Group title="Group one">
+        <NavList.Group>
           <NavList.GroupHeading>
             <a href="#group-1">Group 1</a>
           </NavList.GroupHeading>