[UnderlineNav2]: React router implementation fixes & docs improvement (#2448)

* react router implementation fixes

* add changeset

Author: broccolinisoup

.changeset/polite-dodos-behave.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+UnderlineNav2: Add support and docs for react router configuration

docs/content/drafts/UnderlineNav2.mdx

@@ -17,9 +17,9 @@ import {UnderlineNav} from '@primer/react/drafts'
 
 ```jsx live drafts
 <UnderlineNav aria-label="Repository">
-  <UnderlineNav.Item selected>Item 1</UnderlineNav.Item>
-  <UnderlineNav.Item>Item 2</UnderlineNav.Item>
-  <UnderlineNav.Item>Item 3</UnderlineNav.Item>
+  <UnderlineNav.Item selected>Code</UnderlineNav.Item>
+  <UnderlineNav.Item>Issues</UnderlineNav.Item>
+  <UnderlineNav.Item>Pull Requests</UnderlineNav.Item>
 </UnderlineNav>
 ```
 
@@ -48,87 +48,106 @@ import {UnderlineNav} from '@primer/react/drafts'
 
 ### Overflow Behaviour
 
-When overflow occurs, the component first hides icons if present to optimize for space and show as many items as possible.
-
-#### Items Without Icons
-
-```jsx live drafts
-<UnderlineNav aria-label="Repository">
-  <UnderlineNav.Item selected icon={CodeIcon}>
-    Code
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={IssueOpenedIcon} counter={30}>
-    Issues
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={GitPullRequestIcon} counter={3}>
-    Pull Requests
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={CommentDiscussionIcon}>Discussions</UnderlineNav.Item>
-  <UnderlineNav.Item icon={PlayIcon} counter={9}>
-    Actions
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={ProjectIcon} counter={7}>
-    Projects
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={ShieldLockIcon}>Security</UnderlineNav.Item>
-  <UnderlineNav.Item icon={GraphIcon}>Insights</UnderlineNav.Item>
-  <UnderlineNav.Item icon={GearIcon} counter={1}>
-    Settings
-  </UnderlineNav.Item>
-</UnderlineNav>
+Component first hides icons if they present to optimize for space and show as many items as possible. If there is still an overflow, it will display the items that don't fit in the `More` menu.
+
+```javascript noinline live drafts
+const Navigation = () => {
+  const items = [
+    {navigation: 'Code', icon: CodeIcon},
+    {navigation: 'Issues', icon: IssueOpenedIcon, counter: 120},
+    {navigation: 'Pull Requests', icon: GitPullRequestIcon, counter: 13},
+    {navigation: 'Discussions', icon: CommentDiscussionIcon, counter: 5},
+    {navigation: 'Actions', icon: PlayIcon, counter: 4},
+    {navigation: 'Projects', icon: ProjectIcon, counter: 9},
+    {navigation: 'Insights', icon: GraphIcon},
+    {navigation: 'Settings', icon: GearIcon, counter: 10},
+    {navigation: 'Security', icon: ShieldLockIcon}
+  ]
+  const [selectedIndex, setSelectedIndex] = React.useState(0)
+  return (
+    <Box sx={{width: 750, border: '1px solid', borderBottom: 0, borderColor: 'border.default'}}>
+      <UnderlineNav aria-label="Repository">
+        {items.map((item, index) => (
+          <UnderlineNav.Item
+            key={item.navigation}
+            icon={item.icon}
+            selected={index === selectedIndex}
+            onSelect={e => {
+              setSelectedIndex(index)
+              e.preventDefault()
+            }}
+            counter={item.counter}
+          >
+            {item.navigation}
+          </UnderlineNav.Item>
+        ))}
+      </UnderlineNav>
+    </Box>
+  )
+}
+render(<Navigation />)
 ```
 
-#### Display `More` Menu
-
-If there is still overflow, the component will behave depending on the pointer.
+### Loading State For Counters
 
 ```jsx live drafts
-<UnderlineNav aria-label="Repository">
-  <UnderlineNav.Item selected icon={CodeIcon}>
+<UnderlineNav aria-label="Repository" loadingCounters={true}>
+  <UnderlineNav.Item counter={4} selected>
     Code
   </UnderlineNav.Item>
-  <UnderlineNav.Item icon={IssueOpenedIcon} counter={30}>
-    Issues
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={GitPullRequestIcon} counter={3}>
-    Pull Requests
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={CommentDiscussionIcon}>Discussions</UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon} counter={9}>
-    Actions
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon} counter={7}>
-    Projects
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon}>Security</UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon} counter={14}>
-    Insights
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon} counter={1}>
-    Settings
-  </UnderlineNav.Item>
-  <UnderlineNav.Item icon={EyeIcon}>Wiki</UnderlineNav.Item>
+  <UnderlineNav.Item counter={44}>Issues</UnderlineNav.Item>
+  <UnderlineNav.Item>Pull Requests</UnderlineNav.Item>
 </UnderlineNav>
 ```
 
-### Loading state for counters
+### With React Router
 
-```jsx live drafts
-<UnderlineNav aria-label="Repository" loadingCounters={true}>
-  <UnderlineNav.Item counter={4} selected>
-    Item 1
-  </UnderlineNav.Item>
-  <UnderlineNav.Item counter={44}>Item 2</UnderlineNav.Item>
-  <UnderlineNav.Item>Item 3</UnderlineNav.Item>
-</UnderlineNav>
+```jsx
+import {Link, useNavigate} from 'react-router-dom'
+import {UnderlineNav} from '@primer/react/drafts'
+const Navigation = () => {
+  const navigate = useNavigate()
+  return (
+    <UnderlineNav aria-label="Repository">
+      <UnderlineNav.Item as={Link} to="code" counter={4} selected>
+        Code
+      </UnderlineNav.Item>
+      <UnderlineNav.Item
+        counter={44}
+        as={Link}
+        onSelect={() => {
+          navigate('issues')
+        }}
+      >
+        Issues
+      </UnderlineNav.Item>
+      <UnderlineNav.Item as={Link} to="pulls">
+        Pull Requests
+      </UnderlineNav.Item>
+    </UnderlineNav>
+  )
+}
 ```
 
+<Note>
+  You can bind the routing with both 'to' and 'onSelect' prop here. However; please note that if an 'href' prop is
+  passed, it will be ignored here.
+</Note>
+
 ## Props
 
 ### UnderlineNav
 
 <PropsTable>
-  <PropsTableRow name="aria-label" type="string" description="A unique name for the rendered 'nav' landmark." />
+  <PropsTableRow name="children" required type="UnderlineNav.Item[]" />
+  <PropsTableRow
+    name="aria-label"
+    type="string"
+    description="A unique name for the rendered 'nav' landmark. It will also be used to label the arrow
+        buttons that control the scroll behaviour on coarse pointer devices. (I.e.
+        'Scroll ${aria-label} left/right')
+     "
+  />
   <PropsTableRow
     name="loadingCounters"
     type="boolean"
@@ -146,18 +165,23 @@ If there is still overflow, the component will behave depending on the pointer.
 ### UnderlineNav.Item
 
 <PropsTable>
+  <PropsTableRow
+    name="href"
+    type="string"
+    description="The URL that the item navigates to. 'href' is passed to the underlying '<a>' element. If 'as' is specified, the component may need different props and 'href' is ignored. (Required prop for the react router is 'to' for example)"
+  />
   <PropsTableRow name="icon" type="Component" description="The leading icon comes before item label" />
   <PropsTableRow name="selected" type="boolean" description="Whether the link is selected" />
   <PropsTableRow
     name="onSelect"
     type="(event) => void"
-    description="The handler that gets called when a nav link is selected"
+    description="The handler that gets called when a nav link is selected. For example, a manual route binding can be done here(I.e. 'navigate(href)' for the react router.)"
   />
   <PropsTableRow
     name="as"
-    type="string | Component"
+    type="string | React.ElementType"
     defaultValue="a"
-    description="What kind of component needs to be rendered"
+    description="The underlying element to render — either a HTML element name or a React component."
   />
   <PropsTableSxRow />
 </PropsTable>

src/UnderlineNav2/UnderlineNav.tsx

@@ -192,6 +192,8 @@ export const UnderlineNav = forwardRef(
       React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement> | null
     >(null)
 
+    const [asNavItem, setAsNavItem] = useState('a')
+
     const [iconsVisible, setIconsVisible] = useState<boolean>(true)
 
     const afterSelectHandler = (event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
@@ -250,6 +252,7 @@ export const UnderlineNav = forwardRef(
           setSelectedLink,
           selectedLinkText,
           setSelectedLinkText,
+          setAsNavItem,
           selectEvent,
           afterSelect: afterSelectHandler,
           variant,
@@ -275,28 +278,32 @@ export const UnderlineNav = forwardRef(
                       {actions.map((action, index) => {
                         const {children: actionElementChildren, ...actionElementProps} = action.props
                         return (
-                          <ActionList.Item
-                            sx={menuItemStyles}
-                            key={index}
-                            {...actionElementProps}
-                            onSelect={(event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => {
-                              swapMenuItemWithListItem(action, index, event, updateListAndMenu)
-                              setSelectEvent(event)
-                            }}
-                          >
-                            <Box
-                              as="span"
-                              sx={{display: 'flex', alignItems: 'center', justifyContent: 'space-between'}}
+                          <Box key={index} as="li">
+                            <ActionList.Item
+                              sx={menuItemStyles}
+                              as={asNavItem}
+                              {...actionElementProps}
+                              onSelect={(
+                                event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>
+                              ) => {
+                                swapMenuItemWithListItem(action, index, event, updateListAndMenu)
+                                setSelectEvent(event)
+                              }}
                             >
-                              {actionElementChildren}
+                              <Box
+                                as="span"
+                                sx={{display: 'flex', alignItems: 'center', justifyContent: 'space-between'}}
+                              >
+                                {actionElementChildren}
 
-                              {loadingCounters ? (
-                                <LoadingCounter />
-                              ) : (
-                                <CounterLabel>{actionElementProps.counter}</CounterLabel>
-                              )}
-                            </Box>
-                          </ActionList.Item>
+                                {loadingCounters ? (
+                                  <LoadingCounter />
+                                ) : (
+                                  <CounterLabel>{actionElementProps.counter}</CounterLabel>
+                                )}
+                              </Box>
+                            </ActionList.Item>
+                          </Box>
                         )
                       })}
                     </ActionList>

src/UnderlineNav2/UnderlineNavContext.tsx

@@ -10,6 +10,7 @@ export const UnderlineNavContext = createContext<{
   selectedLinkText: string
   setSelectedLinkText: React.Dispatch<React.SetStateAction<string>>
   selectEvent: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement> | null
+  setAsNavItem: React.Dispatch<React.SetStateAction<string>>
   afterSelect?: (event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>) => void
   variant: 'default' | 'small'
   loadingCounters: boolean
@@ -23,6 +24,7 @@ export const UnderlineNavContext = createContext<{
   selectedLinkText: '',
   setSelectedLinkText: () => null,
   selectEvent: null,
+  setAsNavItem: () => null,
   variant: 'default',
   loadingCounters: false,
   iconsVisible: true

src/UnderlineNav2/UnderlineNavItem.tsx

@@ -72,6 +72,7 @@ export const UnderlineNavItem = forwardRef(
       selectedLinkText,
       setSelectedLinkText,
       selectEvent,
+      setAsNavItem,
       afterSelect,
       variant,
       loadingCounters,
@@ -106,6 +107,7 @@ export const UnderlineNavItem = forwardRef(
         if (typeof onSelect === 'function' && selectEvent !== null) onSelect(selectEvent)
         setSelectedLinkText('')
       }
+      setAsNavItem(Component)
     }, [
       ref,
       preSelected,
@@ -116,7 +118,9 @@ export const UnderlineNavItem = forwardRef(
       setChildrenWidth,
       setNoIconChildrenWidth,
       onSelect,
-      selectEvent
+      selectEvent,
+      setAsNavItem,
+      Component
     ])
 
     const keyPressHandler = React.useCallback(
@@ -126,7 +130,6 @@ export const UnderlineNavItem = forwardRef(
           if (typeof afterSelect === 'function') afterSelect(event)
         }
         setSelectedLink(ref as RefObject<HTMLElement>)
-        event.preventDefault()
       },
       [onSelect, afterSelect, ref, setSelectedLink]
     )
@@ -137,7 +140,6 @@ export const UnderlineNavItem = forwardRef(
           if (typeof afterSelect === 'function') afterSelect(event)
         }
         setSelectedLink(ref as RefObject<HTMLElement>)
-        event.preventDefault()
       },
       [onSelect, afterSelect, ref, setSelectedLink]
     )

src/UnderlineNav2/styles.ts

@@ -153,5 +153,7 @@ export const menuItemStyles = {
   // This is needed to hide the selected check icon on the menu item. https://github.com/primer/react/blob/main/src/ActionList/Selection.tsx#L32
   '& > span': {
     display: 'none'
-  }
+  },
+  // To reset the style when the menu items are rendered as react router links
+  textDecoration: 'none'
 }