feat(Pagination): add renderPage prop to Pagination (#5820)

Co-authored-by: hussam-i-am <[email protected]>

Author: hussam-i-am

.changeset/cyan-lights-try.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+feat(Pagination): add renderPage prop to Pagination

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-dark-colorblind-linux.png

@@ -15,6 +15,10 @@ const stories = [
     title: 'Hide Page Numbers',
     id: 'components-pagination-features--hide-page-numbers',
   },
+  {
+    title: 'Render Links',
+    id: 'components-pagination-features--render-links',
+  },
 ] as const
 
 test.describe('Pagination', () => {

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-dark-dimmed-linux.png

@@ -19,6 +19,7 @@ import Text from '../Text'
 import FormControl from '../FormControl'
 import {AriaStatus} from '../live-region'
 import {VisuallyHidden} from '../VisuallyHidden'
+import {ReactRouterLikeLink} from '../__tests__/mocks/ReactRouterLink'
 
 const meta: Meta = {
   title: 'Components/ActionList/Examples',
@@ -31,17 +32,6 @@ const meta: Meta = {
 }
 export default meta
 
-type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode}
-const ReactRouterLikeLink = forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
-  ({to, children, ...props}: {to: string; children: React.ReactNode}, ref) => {
-    return (
-      <a ref={ref} href={to} {...props}>
-        {children}
-      </a>
-    )
-  },
-)
-
 const NextJSLikeLink = forwardRef(
   ({href, children}: {href: string; children: React.ReactNode}, ref): React.ReactElement => {
     const child = React.Children.only(children)

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-dark-high-contrast-linux.png

@@ -1,6 +1,7 @@
+import React from 'react'
 import {EyeIcon, ChevronRightIcon, HeartIcon, DownloadIcon} from '@primer/octicons-react'
-import React, {forwardRef} from 'react'
 import {LinkButton} from '.'
+import {ReactRouterLikeLink} from '../__tests__/mocks/ReactRouterLink'
 
 export default {
   title: 'Components/LinkButton/Features',
@@ -66,17 +67,6 @@ export const Large = () => (
   </LinkButton>
 )
 
-type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode}
-const ReactRouterLikeLink = forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
-  ({to, children, ...props}: {to: string; children: React.ReactNode}, ref) => {
-    return (
-      <a ref={ref} href={to} {...props}>
-        {children}
-      </a>
-    )
-  },
-)
-
 export const WithReactRouter = () => (
   <LinkButton to="/dummy" as={ReactRouterLikeLink}>
     Default

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-dark-linux.png

@@ -21,6 +21,7 @@ import {
 } from '@primer/octicons-react'
 import Octicon from '../Octicon'
 import VisuallyHidden from '../_VisuallyHidden'
+import {ReactRouterLikeLink} from '../__tests__/mocks/ReactRouterLink'
 
 const meta: Meta = {
   title: 'Components/NavList',
@@ -110,17 +111,6 @@ export const WithNestedSubItems: StoryFn = () => (
   </PageLayout>
 )
 
-type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode}
-const ReactRouterLikeLink = React.forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
-  ({to, children, ...props}, ref) => {
-    return (
-      <a ref={ref} href={to} {...props}>
-        {children}
-      </a>
-    )
-  },
-)
-
 export const WithReactRouterLink = () => (
   <PageLayout>
     <PageLayout.Pane position="start">

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-dark-tritanopia-linux.png

@@ -3,18 +3,7 @@ import React from 'react'
 import {ThemeProvider} from '..'
 import {NavList} from './NavList'
 import {FeatureFlags} from '../FeatureFlags'
-
-type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode}
-
-const ReactRouterLikeLink = React.forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
-  ({to, children, ...props}, ref) => {
-    return (
-      <a ref={ref} href={to} {...props}>
-        {children}
-      </a>
-    )
-  },
-)
+import {ReactRouterLikeLink} from '../__tests__/mocks/ReactRouterLink'
 
 type NextJSLinkProps = {href: string; children: React.ReactNode}
 
@@ -97,7 +86,7 @@ describe('NavList.Item', () => {
     expect(aboutLink).not.toHaveAttribute('aria-current')
   })
 
-  it('is compatiable with React-Router-like link components', () => {
+  it('is compatible with React-Router-like link components', () => {
     const {getByRole} = render(
       <NavList>
         <NavList.Item as={ReactRouterLikeLink} to={'/'} aria-current="page">

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-light-colorblind-linux.png

@@ -66,6 +66,12 @@
       "defaultValue": "2",
       "description": "How many pages to display on each side of the currently selected page."
     },
+    {
+      "name": "renderPage",
+      "type": "function",
+      "defaultValue": "(props: PageProps) => ReactNode",
+      "description": "Provide a custom component or render prop to render each page link within the component."
+    },
     {
       "name": "sx",
       "type": "SystemStyleObject"

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-light-high-contrast-linux.png

@@ -1,7 +1,8 @@
-import React from 'react'
+import React, {useState} from 'react'
 import type {Meta} from '@storybook/react'
 import type {ComponentProps} from '../utils/types'
 import Pagination from './Pagination'
+import {ReactRouterLikeLink} from '../__tests__/mocks/ReactRouterLink'
 
 export default {
   title: 'Components/Pagination/Features',
@@ -32,3 +33,19 @@ HidePageNumbersByViewport.parameters = {
 export const HigherSurroundingPageCount = () => (
   <Pagination pageCount={15} currentPage={5} surroundingPageCount={4} onPageChange={e => e.preventDefault()} />
 )
+
+export const RenderLinks = () => {
+  const [page, setPage] = useState(2)
+
+  return (
+    <Pagination
+      pageCount={15}
+      currentPage={page}
+      onPageChange={(e, n) => {
+        e.preventDefault()
+        setPage(n)
+      }}
+      renderPage={({number, ...props}) => <ReactRouterLikeLink to={`#${number}`} {...props} />}
+    />
+  )
+}

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-light-linux.png

@@ -4,7 +4,7 @@ import Box from '../Box'
 import {get} from '../constants'
 import type {SxProp} from '../sx'
 import sx from '../sx'
-import {buildComponentData, buildPaginationModel} from './model'
+import {buildComponentData, buildPaginationModel, type PageDataProps} from './model'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
 import {viewportRanges} from '../hooks/useResponsiveValue'
 import {toggleStyledComponent} from '../internal/utils/toggleStyledComponent'
@@ -146,6 +146,17 @@ const Page = toggleStyledComponent(
   `,
 )
 
+export type PageProps = {
+  /* Unique key for the page number */
+  key: string
+  /* Children to render, typically the page number, 'Prev', or 'Next' */
+  children: React.ReactNode
+  /* Page number */
+  number: number
+  /* Default styles for the page number */
+  className: string
+} & Omit<PageDataProps['props'], 'as' | 'role'>
+
 type UsePaginationPagesParameters = {
   theme?: Record<string, unknown> // set to theme type once /src/theme.js is converted
   pageCount: number
@@ -155,6 +166,7 @@ type UsePaginationPagesParameters = {
   marginPageCount: number
   showPages?: PaginationProps['showPages']
   surroundingPageCount: number
+  renderPage?: (props: PageProps) => React.ReactNode
 }
 
 function usePaginationPages({
@@ -166,6 +178,7 @@ function usePaginationPages({
   marginPageCount,
   showPages,
   surroundingPageCount,
+  renderPage,
 }: UsePaginationPagesParameters) {
   const pageChange = React.useCallback((n: number) => (e: React.MouseEvent) => onPageChange(e, n), [onPageChange])
 
@@ -178,13 +191,17 @@ function usePaginationPages({
   const children = React.useMemo(() => {
     return model.map(page => {
       const {props, key, content} = buildComponentData(page, hrefBuilder, pageChange(page.num))
+      if (renderPage && props.as !== 'span') {
+        return renderPage({key, children: content, number: page.num, className: classes.Page, ...props})
+      }
+
       return (
         <Page {...props} key={key} theme={theme} className={clsx(enabled && classes.Page)}>
           {content}
         </Page>
       )
     })
-  }, [model, hrefBuilder, pageChange, theme, enabled])
+  }, [model, hrefBuilder, pageChange, renderPage, theme, enabled])
 
   return children
 }
@@ -233,6 +250,7 @@ export type PaginationProps = {
   marginPageCount?: number
   showPages?: boolean | ResponsiveValue<boolean>
   surroundingPageCount?: number
+  renderPage?: (props: PageProps) => React.ReactNode
 }
 
 function Pagination({
@@ -244,6 +262,7 @@ function Pagination({
   marginPageCount = 1,
   showPages = true,
   surroundingPageCount = 2,
+  renderPage,
   ...rest
 }: PaginationProps) {
   const pageElements = usePaginationPages({
@@ -255,6 +274,7 @@ function Pagination({
     marginPageCount,
     showPages,
     surroundingPageCount,
+    renderPage,
   })
 
   const enabled = useFeatureFlag(CSS_MODULES_FEATURE_FLAG)

.playwright/snapshots/components/Pagination.test.ts-snapshots/Pagehead-Render-Links-light-tritanopia-linux.png

@@ -135,11 +135,27 @@ type PageType = {
   precedesBreak?: boolean
 }
 
+export type PageDataProps = {
+  props: {
+    href?: string
+    rel?: string
+    'aria-label'?: string
+    'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | boolean
+    'aria-hidden'?: boolean
+    'aria-disabled'?: boolean
+    onClick?: (e: React.MouseEvent) => void
+    as?: string
+    role?: string
+  }
+  key: string
+  content: string
+}
+
 export function buildComponentData(
   page: PageType,
   hrefBuilder: (n: number) => string,
   onClick: (e: React.MouseEvent) => void,
-) {
+): PageDataProps {
   const props = {}
   let content = ''
   let key = ''

e2e/components/Pagination.test.ts

@@ -3,6 +3,7 @@ import Pagination from '../../Pagination'
 import {behavesAsComponent} from '../../utils/testing'
 import {render as HTMLRender} from '@testing-library/react'
 import axe from 'axe-core'
+import {ReactRouterLikeLink} from '../mocks/ReactRouterLink'
 
 const reqProps = {pageCount: 10, currentPage: 1}
 const comp = <Pagination {...reqProps} />
@@ -24,4 +25,16 @@ describe('Pagination', () => {
     })
     expect(results).toHaveNoViolations()
   })
+
+  it('should render links instead of anchor tags with the renderPage prop', () => {
+    const {container} = HTMLRender(
+      <Pagination
+        pageCount={10}
+        currentPage={1}
+        renderPage={({number, ...props}) => <ReactRouterLikeLink to={`#${number}`} {...props} />}
+      />,
+    )
+
+    expect(container.querySelectorAll('a').length).toEqual(10)
+  })
 })

packages/react/src/ActionList/ActionList.examples.stories.tsx

@@ -0,0 +1,13 @@
+import React from 'react'
+
+export type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode; className?: string}
+
+export const ReactRouterLikeLink = React.forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
+  ({to, children, ...props}, ref) => {
+    return (
+      <a ref={ref} href={to} {...props}>
+        {children}
+      </a>
+    )
+  },
+)

packages/react/src/Button/LinkButton.features.stories.tsx

@@ -19,6 +19,7 @@ import {ActionList as _ActionList} from '../../deprecated/ActionList'
 import {Header} from '../../deprecated/ActionList/Header'
 import BaseStyles from '../../BaseStyles'
 import sx from '../../sx'
+import {ReactRouterLikeLink} from '../../__tests__/mocks/ReactRouterLink'
 
 const ActionList = Object.assign(_ActionList, {
   Header,
@@ -365,17 +366,6 @@ export function SizeStressTestingStory(): JSX.Element {
 }
 SizeStressTestingStory.storyName = 'Size Stress Testing'
 
-type ReactRouterLikeLinkProps = {to: string; children: React.ReactNode}
-const ReactRouterLikeLink = forwardRef<HTMLAnchorElement, ReactRouterLikeLinkProps>(
-  ({to, children, ...props}: {to: string; children: React.ReactNode}, ref) => {
-    return (
-      <a ref={ref} href={to} {...props}>
-        {children}
-      </a>
-    )
-  },
-)
-
 const NextJSLikeLink = forwardRef(
   ({href, children}: {href: string; children: React.ReactNode}, ref): React.ReactElement => {
     const child = React.Children.only(children)

packages/react/src/NavList/NavList.stories.tsx

@@ -10,6 +10,6 @@
     "src/**/*.js",
     "src/**/*.ts",
     "src/**/*.tsx",
-    "script/**/*.ts"
+    "script/**/*.ts",
   ]
 }