@automattic/vip-design-system 2.18.0 → 2.18.1

package/src/system/Pagination/Pagination.tsx

@@ -1,13 +1,12 @@
 /** @jsxImportSource theme-ui */
 
-import classNames from 'classnames';
 import { forwardRef } from 'react';
 import { BiDotsHorizontalRounded } from 'react-icons/bi';
 import { MdChevronLeft, MdChevronRight } from 'react-icons/md';
-import { Flex, ThemeUIStyleObject } from 'theme-ui';
+import { Flex } from 'theme-ui';
 
+import { PaginationLayout, PaginationLayoutProps } from './PaginationLayout';
 import {
-	containerStyles,
 	navigationStyles,
 	pageButtonStyles,
 	activePageButtonStyles,
@@ -19,13 +18,7 @@ import { Button } from '../Button';
 import { Select } from '../NewForm';
 import { Text } from '../Text';
 
-export type PaginationVariant = 'full' | 'compact';
-
-export interface PaginationProps {
-	/** Whether to show the items-per-page dropdown selector.
-	 * @default false
-	 */
-	displayItemsPerPageSelector?: boolean;
+export interface PaginationProps extends PaginationLayoutProps {
 	/** The currently active page number (1-based). */
 	currentPage: number;
 	/** Total number of items across all pages. Used to compute totalPages if not provided. */
@@ -42,20 +35,15 @@ export interface PaginationProps {
 	hasNextPage?: boolean;
 	/** The maximum page number that can be reached. Used for open-ended pagination without totalPages. */
 	maxReachablePage?: number;
-	/** The display variant: 'full' shows page number buttons, 'compact' shows a page dropdown.
-	 * @default 'full'
+	/** When true, shows a compact dropdown page selector instead of individual page buttons.
+	 * @default false
 	 */
-	variant?: PaginationVariant;
-	/** Available page size options for the items-per-page selector.
-	 * @default [20, 50, 100]
+	compact?: boolean;
+	/** Display variant. Use 'compact' for dropdown page selector. Equivalent to the `compact` prop.
+	 * @default 'full'
+	 * @deprecated Use the `compact` prop instead, or `SimplePagination` for cursor-based navigation.
 	 */
-	pageSizeOptions?: number[];
-	/** Additional CSS class name for the pagination container. */
-	className?: string;
-	/** Theme UI style overrides. */
-	sx?: ThemeUIStyleObject;
-	/** Optional content rendered between the items-per-page selector and page navigation. */
-	children?: React.ReactNode;
+	variant?: 'full' | 'compact';
 }
 
 export type PageNumberItem = number | 'ellipsis';
@@ -132,28 +120,6 @@ export function getPageNumbers(
 	];
 }
 
-const ItemsPerPageSelect = ( {
-	itemsPerPage,
-	pageSizeOptions,
-	onItemsPerPageChange,
-}: {
-	itemsPerPage: number;
-	pageSizeOptions: number[];
-	onItemsPerPageChange: ( size: number ) => void;
-} ) => (
-	<Select
-		id="items-per-page"
-		aria-label="Items per page"
-		separator={ false }
-		value={ itemsPerPage }
-		options={ pageSizeOptions.map( size => ( {
-			value: size,
-			label: `${ size.toString() } / page`,
-		} ) ) }
-		onChange={ option => onItemsPerPageChange( Number( option?.value ) ) }
-	/>
-);
-
 const PageNumbers = ( {
 	currentPage,
 	totalPages,
@@ -235,12 +201,11 @@ const CompactPageSelector = ( {
 
 /**
  * A pagination control for navigating through paged content.
- * Supports full page-number buttons and compact dropdown modes, with optional items-per-page selection.
+ * Shows page-number buttons by default, or a compact dropdown when `compact` is true.
  */
 export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 	(
 		{
-			displayItemsPerPageSelector = false,
 			currentPage,
 			totalItems,
 			totalPages,
@@ -249,8 +214,10 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 			onItemsPerPageChange,
 			hasNextPage,
 			maxReachablePage,
-			variant = 'full',
-			pageSizeOptions = [ 20, 50, 100 ],
+			compact = false,
+			variant,
+			displayItemsPerPageSelector,
+			pageSizeOptions,
 			className,
 			sx,
 			children,
@@ -258,47 +225,45 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 		},
 		ref
 	) => {
+		const isCompact = compact || variant === 'compact';
+
 		const resolvedTotalPages =
 			totalPages ??
 			( totalItems !== undefined ? Math.ceil( totalItems / itemsPerPage ) : undefined );
 
 		const isFirstPage = currentPage <= 1;
-		const isLastPage =
-			resolvedTotalPages !== undefined ? currentPage >= resolvedTotalPages : hasNextPage === false;
+		let isLastPage: boolean;
+		if ( resolvedTotalPages !== undefined ) {
+			isLastPage = currentPage >= resolvedTotalPages;
+		} else {
+			isLastPage = hasNextPage === false;
+		}
 
 		return (
-			<nav
+			<PaginationLayout
 				ref={ ref }
-				aria-label="Pagination"
-				className={ classNames( 'vip-pagination-component', className ) }
-				sx={ { ...containerStyles, ...sx } }
+				displayItemsPerPageSelector={ displayItemsPerPageSelector }
+				itemsPerPage={ itemsPerPage }
+				pageSizeOptions={ pageSizeOptions }
+				onItemsPerPageChange={ onItemsPerPageChange }
+				className={ className }
+				sx={ sx }
 				{ ...rest }
 			>
-				<Box>
-					{ displayItemsPerPageSelector && (
-						<ItemsPerPageSelect
-							itemsPerPage={ itemsPerPage }
-							pageSizeOptions={ pageSizeOptions }
-							onItemsPerPageChange={ onItemsPerPageChange }
-						/>
-					) }
-				</Box>
 				<Box sx={ { flex: 1 } }>{ children }</Box>
 				<Flex sx={ navigationStyles }>
-					{ variant === 'full' && (
-						<PageNumbers
+					{ isCompact ? (
+						<CompactPageSelector
 							currentPage={ currentPage }
 							totalPages={ resolvedTotalPages }
-							hasNextPage={ hasNextPage }
 							maxReachablePage={ maxReachablePage }
 							onPageChange={ onPageChange }
 						/>
-					) }
-
-					{ variant === 'compact' && (
-						<CompactPageSelector
+					) : (
+						<PageNumbers
 							currentPage={ currentPage }
 							totalPages={ resolvedTotalPages }
+							hasNextPage={ hasNextPage }
 							maxReachablePage={ maxReachablePage }
 							onPageChange={ onPageChange }
 						/>
@@ -322,7 +287,7 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 						<MdChevronRight size={ 20 } />
 					</Button>
 				</Flex>
-			</nav>
+			</PaginationLayout>
 		);
 	}
 );

package/src/system/Pagination/PaginationLayout.tsx

@@ -0,0 +1,93 @@
+/** @jsxImportSource theme-ui */
+
+import classNames from 'classnames';
+import { forwardRef } from 'react';
+import { ThemeUIStyleObject } from 'theme-ui';
+
+import { containerStyles } from './styles';
+import { Box } from '../Box';
+import { Select } from '../NewForm';
+
+export interface PaginationLayoutProps {
+	/** Whether to show the items-per-page dropdown selector.
+	 * @default false
+	 */
+	displayItemsPerPageSelector?: boolean;
+	/** Number of items displayed per page. */
+	itemsPerPage?: number;
+	/** Available page size options for the items-per-page selector.
+	 * @default [20, 50, 100]
+	 */
+	pageSizeOptions?: number[];
+	/** Callback fired when the user changes the items-per-page value. */
+	onItemsPerPageChange?: ( itemsPerPage: number ) => void;
+	/** Additional CSS class name for the pagination container. */
+	className?: string;
+	/** Theme UI style overrides. */
+	sx?: ThemeUIStyleObject;
+	/** Slot for variant-specific content (page numbers, arrows, etc.). */
+	children?: React.ReactNode;
+}
+
+const ItemsPerPageSelect = ( {
+	itemsPerPage,
+	pageSizeOptions,
+	onItemsPerPageChange,
+}: {
+	itemsPerPage: number;
+	pageSizeOptions: number[];
+	onItemsPerPageChange: ( size: number ) => void;
+} ) => (
+	<Select
+		id="items-per-page"
+		aria-label="Items per page"
+		separator={ false }
+		value={ itemsPerPage }
+		options={ pageSizeOptions.map( size => ( {
+			value: size,
+			label: `${ size.toString() } / page`,
+		} ) ) }
+		onChange={ option => onItemsPerPageChange( Number( option?.value ) ) }
+	/>
+);
+
+/**
+ * Shared layout wrapper for pagination components.
+ * Renders the nav landmark, optional items-per-page selector, and variant content.
+ */
+export const PaginationLayout = forwardRef< HTMLElement, PaginationLayoutProps >(
+	(
+		{
+			displayItemsPerPageSelector = false,
+			itemsPerPage,
+			pageSizeOptions = [ 20, 50, 100 ],
+			onItemsPerPageChange,
+			className,
+			sx,
+			children,
+			...rest
+		},
+		ref
+	) => (
+		<nav
+			ref={ ref }
+			aria-label="Pagination"
+			className={ classNames( 'vip-pagination-component', className ) }
+			sx={ { ...containerStyles, ...sx } }
+			{ ...rest }
+		>
+			<Box>
+				{ displayItemsPerPageSelector && itemsPerPage && onItemsPerPageChange && (
+					<ItemsPerPageSelect
+						itemsPerPage={ itemsPerPage }
+						pageSizeOptions={ pageSizeOptions }
+						onItemsPerPageChange={ onItemsPerPageChange }
+					/>
+				) }
+			</Box>
+			{ children }
+		</nav>
+	)
+);
+
+PaginationLayout.displayName = 'PaginationLayout';

package/src/system/Pagination/SimplePagination.stories.tsx

@@ -0,0 +1,127 @@
+/** @jsxImportSource theme-ui */
+
+import { useState } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { SimplePagination } from './SimplePagination';
+import { Badge } from '../Badge';
+import { Flex } from '../Flex';
+import { Text } from '../Text';
+
+import type { StoryObj, Meta } from '@storybook/react-vite';
+
+const meta: Meta< typeof SimplePagination > = {
+	title: 'SimplePagination',
+	component: SimplePagination,
+	parameters: {
+		docs: {
+			description: {
+				component: `
+A pagination control with only previous/next arrow buttons.
+Designed for cursor-based pagination APIs with custom param names (e.g., \`after\`/\`before\`).
+
+For page-number based pagination, see \`Pagination\`.
+
+## Component Properties
+`,
+			},
+		},
+	},
+};
+
+export default meta;
+
+type Story = StoryObj< typeof SimplePagination >;
+
+const pageTokens = [ 'start', 'abc123', 'def456', 'ghi789', 'jkl012', 'end' ];
+
+const SimplePaginationWithState = ( {
+	initialIndex = 0,
+	displayItemsPerPageSelector = false,
+}: {
+	initialIndex?: number;
+	displayItemsPerPageSelector?: boolean;
+} ) => {
+	const [ index, setIndex ] = useState( initialIndex );
+	const [ itemsPerPage, setItemsPerPage ] = useState( 20 );
+
+	const hasPreviousPage = index > 0;
+	const hasNextPage = index < pageTokens.length - 1;
+
+	return (
+		<SimplePagination
+			hasNextPage={ hasNextPage }
+			hasPreviousPage={ hasPreviousPage }
+			nextParam={ hasNextPage ? { param: 'after', value: pageTokens[ index + 1 ] } : undefined }
+			previousParam={
+				hasPreviousPage ? { param: 'before', value: pageTokens[ index ] } : undefined
+			}
+			onNavigate={ param => {
+				if ( param === 'after' ) {
+					setIndex( i => i + 1 );
+				}
+				if ( param === 'before' ) {
+					setIndex( i => i - 1 );
+				}
+			} }
+			displayItemsPerPageSelector={ displayItemsPerPageSelector }
+			itemsPerPage={ displayItemsPerPageSelector ? itemsPerPage : undefined }
+			onItemsPerPageChange={
+				displayItemsPerPageSelector
+					? size => {
+							setItemsPerPage( size );
+							setIndex( 0 );
+					  }
+					: undefined
+			}
+		>
+			<Flex sx={ { justifyContent: 'center', alignItems: 'center', verticalAlign: 'middle' } }>
+				<Badge variant="gold" sx={ { mr: 2 } }>
+					DEBUG
+				</Badge>
+				<Text>
+					Index: { index } — token: { pageTokens[ index ] }
+				</Text>
+			</Flex>
+		</SimplePagination>
+	);
+};
+
+export const Default: Story = {
+	render: () => <SimplePaginationWithState />,
+};
+
+export const FirstPage: Story = {
+	render: () => <SimplePaginationWithState />,
+	parameters: {
+		docs: {
+			description: {
+				story: 'On the first page — Previous button is disabled.',
+			},
+		},
+	},
+};
+
+export const LastPage: Story = {
+	render: () => <SimplePaginationWithState initialIndex={ pageTokens.length - 1 } />,
+	parameters: {
+		docs: {
+			description: {
+				story: 'On the last page — Next button is disabled.',
+			},
+		},
+	},
+};
+
+export const WithPageSize: Story = {
+	render: () => <SimplePaginationWithState displayItemsPerPageSelector />,
+	parameters: {
+		docs: {
+			description: {
+				story: 'With an items-per-page selector.',
+			},
+		},
+	},
+};

package/src/system/Pagination/SimplePagination.test.tsx

@@ -0,0 +1,120 @@
+/** @jsxImportSource theme-ui */
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import '@testing-library/jest-dom';
+
+import { SimplePagination } from './SimplePagination';
+
+const defaultProps = {
+	hasNextPage: true,
+	hasPreviousPage: true,
+	nextParam: { param: 'after', value: 'cursor_abc' },
+	previousParam: { param: 'before', value: 'cursor_xyz' },
+	onNavigate: jest.fn(),
+};
+
+describe( '<SimplePagination />', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'renders a nav landmark with aria-label', () => {
+		render( <SimplePagination { ...defaultProps } /> );
+
+		expect( screen.getByRole( 'navigation', { name: 'Pagination' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'renders prev and next arrow buttons', () => {
+		render( <SimplePagination { ...defaultProps } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Previous page' } ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'button', { name: 'Next page' } ) ).toBeInTheDocument();
+	} );
+
+	it( 'does not render page number buttons', () => {
+		render( <SimplePagination { ...defaultProps } /> );
+
+		expect( screen.queryByRole( 'button', { name: /Go to page/ } ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'disables previous button when hasPreviousPage is false', () => {
+		render( <SimplePagination { ...defaultProps } hasPreviousPage={ false } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Previous page' } ) ).toBeDisabled();
+	} );
+
+	it( 'disables next button when hasNextPage is false', () => {
+		render( <SimplePagination { ...defaultProps } hasNextPage={ false } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Next page' } ) ).toBeDisabled();
+	} );
+
+	it( 'disables previous button when previousParam is undefined', () => {
+		render( <SimplePagination { ...defaultProps } previousParam={ undefined } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Previous page' } ) ).toBeDisabled();
+	} );
+
+	it( 'disables next button when nextParam is undefined', () => {
+		render( <SimplePagination { ...defaultProps } nextParam={ undefined } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Next page' } ) ).toBeDisabled();
+	} );
+
+	it( 'calls onNavigate with correct param and value when clicking next', async () => {
+		const user = userEvent.setup();
+		render( <SimplePagination { ...defaultProps } /> );
+
+		await user.click( screen.getByRole( 'button', { name: 'Next page' } ) );
+
+		expect( defaultProps.onNavigate ).toHaveBeenCalledWith( 'after', 'cursor_abc' );
+	} );
+
+	it( 'calls onNavigate with correct param and value when clicking previous', async () => {
+		const user = userEvent.setup();
+		render( <SimplePagination { ...defaultProps } /> );
+
+		await user.click( screen.getByRole( 'button', { name: 'Previous page' } ) );
+
+		expect( defaultProps.onNavigate ).toHaveBeenCalledWith( 'before', 'cursor_xyz' );
+	} );
+
+	it( 'renders children content', () => {
+		render(
+			<SimplePagination { ...defaultProps }>
+				<span>Showing results</span>
+			</SimplePagination>
+		);
+
+		expect( screen.getByText( 'Showing results' ) ).toBeInTheDocument();
+	} );
+
+	it( 'renders items-per-page selector when enabled', () => {
+		render(
+			<SimplePagination
+				{ ...defaultProps }
+				displayItemsPerPageSelector
+				itemsPerPage={ 20 }
+				onItemsPerPageChange={ jest.fn() }
+			/>
+		);
+
+		expect( screen.getByRole( 'combobox' ) ).toBeInTheDocument();
+	} );
+
+	it( 'has no accessibility violations', async () => {
+		const { container } = render( <SimplePagination { ...defaultProps } /> );
+
+		expect( await axe( container ) ).toHaveNoViolations();
+	} );
+
+	it( 'has no accessibility violations with both buttons disabled', async () => {
+		const { container } = render(
+			<SimplePagination { ...defaultProps } hasNextPage={ false } hasPreviousPage={ false } />
+		);
+
+		expect( await axe( container ) ).toHaveNoViolations();
+	} );
+} );

package/src/system/Pagination/SimplePagination.tsx

@@ -0,0 +1,97 @@
+/** @jsxImportSource theme-ui */
+
+import { forwardRef } from 'react';
+import { MdChevronLeft, MdChevronRight } from 'react-icons/md';
+import { Flex } from 'theme-ui';
+
+import { PaginationLayout, PaginationLayoutProps } from './PaginationLayout';
+import { navigationStyles, arrowButtonStyles } from './styles';
+import { Box } from '../Box';
+import { Button } from '../Button';
+
+/** A navigation parameter for SimplePagination. */
+export interface SimpleNavigationParam {
+	/** The query parameter name (e.g., 'after', 'before'). */
+	param: string;
+	/** The parameter token value. */
+	value: string;
+}
+
+export interface SimplePaginationProps extends PaginationLayoutProps {
+	/** Whether there is a next page available. */
+	hasNextPage?: boolean;
+	/** Whether there is a previous page available. */
+	hasPreviousPage?: boolean;
+	/** Navigation parameter for the next page. */
+	nextParam?: SimpleNavigationParam;
+	/** Navigation parameter for the previous page. */
+	previousParam?: SimpleNavigationParam;
+	/** Callback fired when the user navigates. Receives the param name and value. */
+	onNavigate: ( param: string, value: string ) => void;
+}
+
+/**
+ * A pagination control with only previous/next arrow buttons.
+ * Designed for cursor-based pagination APIs with custom param names (e.g., `after`/`before`).
+ */
+export const SimplePagination = forwardRef< HTMLElement, SimplePaginationProps >(
+	(
+		{
+			hasNextPage,
+			hasPreviousPage,
+			nextParam,
+			previousParam,
+			onNavigate,
+			displayItemsPerPageSelector,
+			itemsPerPage,
+			pageSizeOptions,
+			onItemsPerPageChange,
+			className,
+			sx,
+			children,
+			...rest
+		},
+		ref
+	) => {
+		const isPrevDisabled = ! hasPreviousPage || ! previousParam?.value;
+		const isNextDisabled = ! hasNextPage || ! nextParam?.value;
+
+		return (
+			<PaginationLayout
+				ref={ ref }
+				displayItemsPerPageSelector={ displayItemsPerPageSelector }
+				itemsPerPage={ itemsPerPage }
+				pageSizeOptions={ pageSizeOptions }
+				onItemsPerPageChange={ onItemsPerPageChange }
+				className={ className }
+				sx={ sx }
+				{ ...rest }
+			>
+				<Box sx={ { flex: 1 } }>{ children }</Box>
+				<Flex sx={ navigationStyles }>
+					<Button
+						aria-label="Previous page"
+						disabled={ isPrevDisabled }
+						onClick={ () =>
+							previousParam && onNavigate( previousParam.param, previousParam.value )
+						}
+						sx={ arrowButtonStyles }
+					>
+						<MdChevronLeft size={ 20 } />
+					</Button>
+
+					<Button
+						aria-label="Next page"
+						disabled={ isNextDisabled }
+						onClick={ () => nextParam && onNavigate( nextParam.param, nextParam.value ) }
+						sx={ arrowButtonStyles }
+					>
+						<MdChevronRight size={ 20 } />
+					</Button>
+				</Flex>
+			</PaginationLayout>
+		);
+	}
+);
+
+SimplePagination.displayName = 'SimplePagination';

package/src/system/Pagination/index.ts

@@ -1,2 +1,4 @@
 export { Pagination, getPageNumbers } from './Pagination';
-export type { PaginationProps, PaginationVariant, PageNumberItem } from './Pagination';
+export { SimplePagination } from './SimplePagination';
+export type { PaginationProps, PageNumberItem } from './Pagination';
+export type { SimplePaginationProps, SimpleNavigationParam } from './SimplePagination';

package/src/system/index.ts

@@ -50,7 +50,7 @@ import * as Form from './NewForm';
 import { NewTooltip } from './NewTooltip';
 import { Notice } from './Notice';
 import { OptionRow } from './OptionRow';
-import { Pagination } from './Pagination';
+import { SimplePagination, Pagination } from './Pagination';
 import { Progress } from './Progress';
 import { ScreenReaderText } from './ScreenReaderText';
 import { Skeleton } from './Skeleton';
@@ -99,6 +99,7 @@ export {
 	Flex,
 	Notice,
 	OptionRow,
+	SimplePagination,
 	Pagination,
 	Heading,
 	Hr,