@automattic/vip-design-system 2.17.0 → 2.17.1

package/build/system/Pagination/Pagination.d.ts

@@ -11,6 +11,7 @@ export interface PaginationProps {
     onPageChange: (page: number) => void;
     onItemsPerPageChange: (itemsPerPage: number) => void;
     hasNextPage?: boolean;
+    maxReachablePage?: number;
     variant?: PaginationVariant;
     pageSizeOptions?: number[];
     className?: string;
@@ -18,5 +19,5 @@ export interface PaginationProps {
     children?: React.ReactNode;
 }
 export type PageNumberItem = number | 'ellipsis';
-export declare function getPageNumbers(currentPage: number, totalPages?: number, hasNextPage?: boolean): PageNumberItem[];
+export declare function getPageNumbers(currentPage: number, totalPages?: number, hasNextPage?: boolean, maxReachablePage?: number): PageNumberItem[];
 export declare const Pagination: import("react").ForwardRefExoticComponent<PaginationProps & import("react").RefAttributes<HTMLElement>>;

package/build/system/Pagination/Pagination.js

@@ -1,4 +1,4 @@
-var _excluded = ["displayItemsPerPageSelector", "currentPage", "totalItems", "totalPages", "itemsPerPage", "onPageChange", "onItemsPerPageChange", "hasNextPage", "variant", "pageSizeOptions", "className", "sx", "children"];
+var _excluded = ["displayItemsPerPageSelector", "currentPage", "totalItems", "totalPages", "itemsPerPage", "onPageChange", "onItemsPerPageChange", "hasNextPage", "maxReachablePage", "variant", "pageSizeOptions", "className", "sx", "children"];
 function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 /** @jsxImportSource theme-ui */
@@ -23,34 +23,60 @@ function range(start, end) {
     return start + i;
   });
 }
-export function getPageNumbers(currentPage, totalPages, hasNextPage) {
+
+/** Total number of visible items (page numbers + ellipsis indicators) in the pagination bar. */
+var VISIBLE_PAGE_SLOTS = 8;
+
+/** When currentPage <= this value, the "near start" layout is used (no leading ellipsis). */
+var NEAR_START_THRESHOLD = 5;
+
+/** Pages shown before the current page in the middle layout. */
+var PAGES_BEFORE_CURRENT = 1;
+
+/** Pages shown after the current page in the bounded middle layout. */
+var PAGES_AFTER_CURRENT = 2;
+export function getPageNumbers(currentPage, totalPages, hasNextPage, maxReachablePage) {
+  var _last;
+  // Resolve the last known page
   var last;
-  if (totalPages === undefined) {
-    if (hasNextPage === false) {
-      last = currentPage;
-    } else {
-      last = undefined;
-    }
-  } else {
+  if (totalPages !== undefined) {
     last = Math.max(1, Number(totalPages));
+  } else if (hasNextPage === false) {
+    last = currentPage;
   }
   if (last !== undefined && (!Number.isFinite(last) || last < 1)) {
     return [];
   }
-  if (last !== undefined && last <= 8) {
-    return range(1, last);
+
+  // Effective end anchor: known last page, or capped reachable page
+  var end = (_last = last) != null ? _last : maxReachablePage !== undefined ? Math.max(currentPage, maxReachablePage) : undefined;
+
+  // Small page count — show all without ellipsis
+  if (end !== undefined && end <= VISIBLE_PAGE_SLOTS) {
+    return range(1, end);
   }
 
-  // Bounded (last is a known page number)
-  if (last !== undefined) {
-    if (currentPage <= 5) return [].concat(range(1, 6), ['ellipsis', last]);
-    if (currentPage >= last - 4) return [1, 'ellipsis'].concat(range(last - 5, last));
-    return [1, 'ellipsis'].concat(range(currentPage - 1, currentPage + 2), ['ellipsis', last]);
+  // Near start
+  if (currentPage <= NEAR_START_THRESHOLD) {
+    if (end !== undefined) return [].concat(range(1, NEAR_START_THRESHOLD + 1), ['ellipsis', end]);
+    return [].concat(range(1, VISIBLE_PAGE_SLOTS - 1), ['ellipsis']);
   }
 
-  // Open-ended (no known last page)
-  if (currentPage <= 5) return [].concat(range(1, 7), ['ellipsis']);
-  return [1, 'ellipsis'].concat(range(currentPage - 1, currentPage + 3), ['ellipsis']);
+  // Near end (bounded only — open-ended has no "end zone")
+  if (last !== undefined && currentPage >= last - (NEAR_START_THRESHOLD - 1)) {
+    return [1, 'ellipsis'].concat(range(last - NEAR_START_THRESHOLD, last));
+  }
+
+  // Middle
+  if (end !== undefined) {
+    var rangeEnd = Math.min(currentPage + PAGES_AFTER_CURRENT, end);
+    var middle = range(currentPage - PAGES_BEFORE_CURRENT, rangeEnd);
+    if (rangeEnd >= end) return [1, 'ellipsis'].concat(middle);
+    return [1, 'ellipsis'].concat(middle, ['ellipsis', end]);
+  }
+
+  // Fully open-ended middle
+  return [1, 'ellipsis'].concat(range(currentPage - PAGES_BEFORE_CURRENT, currentPage + PAGES_AFTER_CURRENT + 1), ['ellipsis']);
 }
 var ItemsPerPageSelect = function ItemsPerPageSelect(_ref) {
   var itemsPerPage = _ref.itemsPerPage,
@@ -76,8 +102,9 @@ var PageNumbers = function PageNumbers(_ref2) {
   var currentPage = _ref2.currentPage,
     totalPages = _ref2.totalPages,
     hasNextPage = _ref2.hasNextPage,
+    maxReachablePage = _ref2.maxReachablePage,
     onPageChange = _ref2.onPageChange;
-  var pages = getPageNumbers(currentPage, totalPages, hasNextPage);
+  var pages = getPageNumbers(currentPage, totalPages, hasNextPage, maxReachablePage);
   return _jsx(_Fragment, {
     children: pages.map(function (page, index) {
       if (page === 'ellipsis') {
@@ -100,14 +127,12 @@ var PageNumbers = function PageNumbers(_ref2) {
 var CompactPageSelector = function CompactPageSelector(_ref3) {
   var currentPage = _ref3.currentPage,
     totalPages = _ref3.totalPages,
+    maxReachablePage = _ref3.maxReachablePage,
     onPageChange = _ref3.onPageChange;
   var isOpenEnded = totalPages === undefined;
-  var pageOptions = isOpenEnded ? Array.from({
-    length: currentPage + 1
-  }, function (_, i) {
-    return i + 1;
-  }) : Array.from({
-    length: totalPages
+  var upperBound = isOpenEnded ? maxReachablePage != null ? maxReachablePage : currentPage + 1 : totalPages;
+  var pageOptions = Array.from({
+    length: upperBound
   }, function (_, i) {
     return i + 1;
   });
@@ -160,6 +185,7 @@ export var Pagination = /*#__PURE__*/forwardRef(function (_ref4, ref) {
     onPageChange = _ref4.onPageChange,
     onItemsPerPageChange = _ref4.onItemsPerPageChange,
     hasNextPage = _ref4.hasNextPage,
+    maxReachablePage = _ref4.maxReachablePage,
     _ref4$variant = _ref4.variant,
     variant = _ref4$variant === void 0 ? 'full' : _ref4$variant,
     _ref4$pageSizeOptions = _ref4.pageSizeOptions,
@@ -194,10 +220,12 @@ export var Pagination = /*#__PURE__*/forwardRef(function (_ref4, ref) {
         currentPage: currentPage,
         totalPages: resolvedTotalPages,
         hasNextPage: hasNextPage,
+        maxReachablePage: maxReachablePage,
         onPageChange: onPageChange
       }), variant === 'compact' && _jsx(CompactPageSelector, {
         currentPage: currentPage,
         totalPages: resolvedTotalPages,
+        maxReachablePage: maxReachablePage,
         onPageChange: onPageChange
       }), _jsx(Button, {
         "aria-label": "Previous page",

package/build/system/Pagination/Pagination.stories.d.ts

@@ -13,6 +13,7 @@ export declare const FewPages: Story;
 export declare const MiddlePage: Story;
 export declare const CustomPageSizes: Story;
 export declare const WithItemsPerPageSelector: Story;
+export declare const OpenEndedCursorBased: Story;
 export declare const OpenEnded: Story;
 export declare const OpenEndedCompact: Story;
 export declare const OpenEndedLastPage: Story;

package/build/system/Pagination/Pagination.stories.js

@@ -161,6 +161,59 @@ export var WithItemsPerPageSelector = {
     });
   }
 };
+var CursorBasedPaginationWithState = function CursorBasedPaginationWithState() {
+  var _useState5 = useState(1),
+    currentPage = _useState5[0],
+    setCurrentPage = _useState5[1];
+  var _useState6 = useState(20),
+    itemsPerPage = _useState6[0],
+    setItemsPerPage = _useState6[1];
+  var _useState7 = useState(1),
+    maxVisited = _useState7[0],
+    setMaxVisited = _useState7[1];
+  var handlePageChange = function handlePageChange(page) {
+    setCurrentPage(page);
+    setMaxVisited(function (prev) {
+      return Math.max(prev, page);
+    });
+  };
+  var hasNextPage = true; // Simulate always having a next page
+  var maxReachablePage = hasNextPage ? maxVisited + 1 : maxVisited;
+  return _jsx(Pagination, {
+    currentPage: currentPage,
+    itemsPerPage: itemsPerPage,
+    onPageChange: handlePageChange,
+    onItemsPerPageChange: function onItemsPerPageChange(size) {
+      setItemsPerPage(size);
+      setCurrentPage(1);
+      setMaxVisited(1);
+    },
+    hasNextPage: hasNextPage,
+    maxReachablePage: maxReachablePage,
+    displayItemsPerPageSelector: true,
+    children: _jsxs(Flex, {
+      sx: {
+        justifyContent: 'center',
+        alignItems: 'center',
+        verticalAlign: 'middle'
+      },
+      children: [_jsx(Badge, {
+        variant: "gold",
+        sx: {
+          mr: 2
+        },
+        children: "DEBUG"
+      }), _jsxs(Text, {
+        children: ["Page ", currentPage, " \u2014 max reachable: ", maxReachablePage]
+      })]
+    })
+  });
+};
+export var OpenEndedCursorBased = {
+  render: function render() {
+    return _jsx(CursorBasedPaginationWithState, {});
+  }
+};
 export var OpenEnded = {
   render: function render() {
     return _jsx(OpenEndedPaginationWithState, {});

package/build/system/Pagination/Pagination.test.js

@@ -7,7 +7,6 @@ function _extends() { _extends = Object.assign ? Object.assign.bind() : function
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
-import React from 'react';
 import '@testing-library/jest-dom';
 import { Pagination, getPageNumbers } from './Pagination';
 import { jsx as _jsx } from "theme-ui/jsx-runtime";
@@ -253,6 +252,26 @@ describe('getPageNumbers', function () {
     expect(getPageNumbers(10, 20)).toEqual([1, 'ellipsis', 9, 10, 11, 12, 'ellipsis', 20]);
   });
 });
+describe('getPageNumbers (open-ended with maxReachablePage)', function () {
+  it('caps pages to maxReachablePage when near start', function () {
+    expect(getPageNumbers(1, undefined, true, 2)).toEqual([1, 2]);
+  });
+  it('shows all reachable pages when they fit', function () {
+    expect(getPageNumbers(3, undefined, true, 4)).toEqual([1, 2, 3, 4]);
+  });
+  it('shows ellipsis for large reachable ranges', function () {
+    expect(getPageNumbers(8, undefined, true, 9)).toEqual([1, 'ellipsis', 7, 8, 9]);
+  });
+  it('shows both ellipsis when end is far from current page', function () {
+    expect(getPageNumbers(8, undefined, true, 15)).toEqual([1, 'ellipsis', 7, 8, 9, 10, 'ellipsis', 15]);
+  });
+  it('returns all pages when maxReachablePage <= 8', function () {
+    expect(getPageNumbers(1, undefined, true, 8)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+  });
+  it('does not affect behavior when maxReachablePage is undefined', function () {
+    expect(getPageNumbers(1, undefined, true)).toEqual([1, 2, 3, 4, 5, 6, 7, 'ellipsis']);
+  });
+});
 describe('getPageNumbers (open-ended)', function () {
   it('always returns 8 items when page >= 6', function () {
     for (var cp = 6; cp <= 20; cp++) {
@@ -272,6 +291,49 @@ describe('getPageNumbers (open-ended)', function () {
     expect(getPageNumbers(10, undefined, false)).toEqual([1, 'ellipsis', 5, 6, 7, 8, 9, 10]);
   });
 });
+describe('<Pagination /> with maxReachablePage', function () {
+  var maxReachableProps = {
+    currentPage: 1,
+    itemsPerPage: 20,
+    hasNextPage: true,
+    maxReachablePage: 2,
+    onPageChange: jest.fn(),
+    onItemsPerPageChange: jest.fn()
+  };
+  it('only renders reachable page buttons', function () {
+    render(_jsx(Pagination, _extends({}, maxReachableProps)));
+    expect(screen.getByRole('button', {
+      name: 'Go to page 1'
+    })).toBeInTheDocument();
+    expect(screen.getByRole('button', {
+      name: 'Go to page 2'
+    })).toBeInTheDocument();
+    expect(screen.queryByRole('button', {
+      name: 'Go to page 3'
+    })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', {
+      name: 'Go to page 7'
+    })).not.toBeInTheDocument();
+  });
+  it('has no accessibility violations', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee6() {
+    var _render3, container;
+    return _regeneratorRuntime().wrap(function _callee6$(_context6) {
+      while (1) switch (_context6.prev = _context6.next) {
+        case 0:
+          _render3 = render(_jsx(Pagination, _extends({}, maxReachableProps))), container = _render3.container;
+          _context6.t0 = expect;
+          _context6.next = 4;
+          return axe(container);
+        case 4:
+          _context6.t1 = _context6.sent;
+          (0, _context6.t0)(_context6.t1).toHaveNoViolations();
+        case 6:
+        case "end":
+          return _context6.stop();
+      }
+    }, _callee6);
+  })));
+});
 describe('<Pagination /> open-ended mode', function () {
   var openEndedProps = {
     currentPage: 5,
@@ -296,14 +358,14 @@ describe('<Pagination /> open-ended mode', function () {
       name: 'Next page'
     })).toBeDisabled();
   });
-  it('calls onPageChange when clicking next in open-ended mode', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee6() {
+  it('calls onPageChange when clicking next in open-ended mode', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee7() {
     var user;
-    return _regeneratorRuntime().wrap(function _callee6$(_context6) {
-      while (1) switch (_context6.prev = _context6.next) {
+    return _regeneratorRuntime().wrap(function _callee7$(_context7) {
+      while (1) switch (_context7.prev = _context7.next) {
         case 0:
           user = userEvent.setup();
           render(_jsx(Pagination, _extends({}, openEndedProps)));
-          _context6.next = 4;
+          _context7.next = 4;
           return user.click(screen.getByRole('button', {
             name: 'Next page'
           }));
@@ -311,9 +373,9 @@ describe('<Pagination /> open-ended mode', function () {
           expect(openEndedProps.onPageChange).toHaveBeenCalledWith(6);
         case 5:
         case "end":
-          return _context6.stop();
+          return _context7.stop();
       }
-    }, _callee6);
+    }, _callee7);
   })));
   it('renders compact variant with "Page" but without "of Y"', function () {
     render(_jsx(Pagination, _extends({}, openEndedProps, {
@@ -322,32 +384,12 @@ describe('<Pagination /> open-ended mode', function () {
     expect(screen.getByText('Page')).toBeInTheDocument();
     expect(screen.queryByText(/of \d+/)).not.toBeInTheDocument();
   });
-  it('has no accessibility violations (open-ended full)', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee7() {
-    var _render3, container;
-    return _regeneratorRuntime().wrap(function _callee7$(_context7) {
-      while (1) switch (_context7.prev = _context7.next) {
-        case 0:
-          _render3 = render(_jsx(Pagination, _extends({}, openEndedProps))), container = _render3.container;
-          _context7.t0 = expect;
-          _context7.next = 4;
-          return axe(container);
-        case 4:
-          _context7.t1 = _context7.sent;
-          (0, _context7.t0)(_context7.t1).toHaveNoViolations();
-        case 6:
-        case "end":
-          return _context7.stop();
-      }
-    }, _callee7);
-  })));
-  it('has no accessibility violations (open-ended compact)', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee8() {
+  it('has no accessibility violations (open-ended full)', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee8() {
     var _render4, container;
     return _regeneratorRuntime().wrap(function _callee8$(_context8) {
       while (1) switch (_context8.prev = _context8.next) {
         case 0:
-          _render4 = render(_jsx(Pagination, _extends({}, openEndedProps, {
-            variant: "compact"
-          }))), container = _render4.container;
+          _render4 = render(_jsx(Pagination, _extends({}, openEndedProps))), container = _render4.container;
           _context8.t0 = expect;
           _context8.next = 4;
           return axe(container);
@@ -360,4 +402,24 @@ describe('<Pagination /> open-ended mode', function () {
       }
     }, _callee8);
   })));
+  it('has no accessibility violations (open-ended compact)', /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee9() {
+    var _render5, container;
+    return _regeneratorRuntime().wrap(function _callee9$(_context9) {
+      while (1) switch (_context9.prev = _context9.next) {
+        case 0:
+          _render5 = render(_jsx(Pagination, _extends({}, openEndedProps, {
+            variant: "compact"
+          }))), container = _render5.container;
+          _context9.t0 = expect;
+          _context9.next = 4;
+          return axe(container);
+        case 4:
+          _context9.t1 = _context9.sent;
+          (0, _context9.t0)(_context9.t1).toHaveNoViolations();
+        case 6:
+        case "end":
+          return _context9.stop();
+      }
+    }, _callee9);
+  })));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/vip-design-system",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/Automattic/vip-design-system"

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

@@ -154,6 +154,49 @@ export const WithItemsPerPageSelector: Story = {
 	),
 };
 
+const CursorBasedPaginationWithState = () => {
+	const [ currentPage, setCurrentPage ] = useState( 1 );
+	const [ itemsPerPage, setItemsPerPage ] = useState( 20 );
+	const [ maxVisited, setMaxVisited ] = useState( 1 );
+
+	const handlePageChange = ( page: number ) => {
+		setCurrentPage( page );
+		setMaxVisited( prev => Math.max( prev, page ) );
+	};
+
+	const hasNextPage = true; // Simulate always having a next page
+	const maxReachablePage = hasNextPage ? maxVisited + 1 : maxVisited;
+
+	return (
+		<Pagination
+			currentPage={ currentPage }
+			itemsPerPage={ itemsPerPage }
+			onPageChange={ handlePageChange }
+			onItemsPerPageChange={ size => {
+				setItemsPerPage( size );
+				setCurrentPage( 1 );
+				setMaxVisited( 1 );
+			} }
+			hasNextPage={ hasNextPage }
+			maxReachablePage={ maxReachablePage }
+			displayItemsPerPageSelector
+		>
+			<Flex sx={ { justifyContent: 'center', alignItems: 'center', verticalAlign: 'middle' } }>
+				<Badge variant="gold" sx={ { mr: 2 } }>
+					DEBUG
+				</Badge>
+				<Text>
+					Page { currentPage } — max reachable: { maxReachablePage }
+				</Text>
+			</Flex>
+		</Pagination>
+	);
+};
+
+export const OpenEndedCursorBased: Story = {
+	render: () => <CursorBasedPaginationWithState />,
+};
+
 export const OpenEnded: Story = {
 	render: () => <OpenEndedPaginationWithState />,
 };

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

@@ -3,7 +3,6 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { axe } from 'jest-axe';
-import React from 'react';
 import '@testing-library/jest-dom';
 
 import { Pagination, getPageNumbers } from './Pagination';
@@ -178,6 +177,41 @@ describe( 'getPageNumbers', () => {
 	} );
 } );
 
+describe( 'getPageNumbers (open-ended with maxReachablePage)', () => {
+	it( 'caps pages to maxReachablePage when near start', () => {
+		expect( getPageNumbers( 1, undefined, true, 2 ) ).toEqual( [ 1, 2 ] );
+	} );
+
+	it( 'shows all reachable pages when they fit', () => {
+		expect( getPageNumbers( 3, undefined, true, 4 ) ).toEqual( [ 1, 2, 3, 4 ] );
+	} );
+
+	it( 'shows ellipsis for large reachable ranges', () => {
+		expect( getPageNumbers( 8, undefined, true, 9 ) ).toEqual( [ 1, 'ellipsis', 7, 8, 9 ] );
+	} );
+
+	it( 'shows both ellipsis when end is far from current page', () => {
+		expect( getPageNumbers( 8, undefined, true, 15 ) ).toEqual( [
+			1,
+			'ellipsis',
+			7,
+			8,
+			9,
+			10,
+			'ellipsis',
+			15,
+		] );
+	} );
+
+	it( 'returns all pages when maxReachablePage <= 8', () => {
+		expect( getPageNumbers( 1, undefined, true, 8 ) ).toEqual( [ 1, 2, 3, 4, 5, 6, 7, 8 ] );
+	} );
+
+	it( 'does not affect behavior when maxReachablePage is undefined', () => {
+		expect( getPageNumbers( 1, undefined, true ) ).toEqual( [ 1, 2, 3, 4, 5, 6, 7, 'ellipsis' ] );
+	} );
+} );
+
 describe( 'getPageNumbers (open-ended)', () => {
 	it( 'always returns 8 items when page >= 6', () => {
 		for ( let cp = 6; cp <= 20; cp++ ) {
@@ -210,6 +244,32 @@ describe( 'getPageNumbers (open-ended)', () => {
 	} );
 } );
 
+describe( '<Pagination /> with maxReachablePage', () => {
+	const maxReachableProps = {
+		currentPage: 1,
+		itemsPerPage: 20,
+		hasNextPage: true,
+		maxReachablePage: 2,
+		onPageChange: jest.fn(),
+		onItemsPerPageChange: jest.fn(),
+	};
+
+	it( 'only renders reachable page buttons', () => {
+		render( <Pagination { ...maxReachableProps } /> );
+
+		expect( screen.getByRole( 'button', { name: 'Go to page 1' } ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'button', { name: 'Go to page 2' } ) ).toBeInTheDocument();
+		expect( screen.queryByRole( 'button', { name: 'Go to page 3' } ) ).not.toBeInTheDocument();
+		expect( screen.queryByRole( 'button', { name: 'Go to page 7' } ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'has no accessibility violations', async () => {
+		const { container } = render( <Pagination { ...maxReachableProps } /> );
+
+		expect( await axe( container ) ).toHaveNoViolations();
+	} );
+} );
+
 describe( '<Pagination /> open-ended mode', () => {
 	const openEndedProps = {
 		currentPage: 5,

package/src/system/Pagination/Pagination.tsx

@@ -30,6 +30,7 @@ export interface PaginationProps {
 	onPageChange: ( page: number ) => void;
 	onItemsPerPageChange: ( itemsPerPage: number ) => void;
 	hasNextPage?: boolean;
+	maxReachablePage?: number;
 	variant?: PaginationVariant;
 	pageSizeOptions?: number[];
 	className?: string;
@@ -43,39 +44,72 @@ function range( start: number, end: number ): number[] {
 	return Array.from( { length: end - start + 1 }, ( _, i ) => start + i );
 }
 
+/** Total number of visible items (page numbers + ellipsis indicators) in the pagination bar. */
+const VISIBLE_PAGE_SLOTS = 8;
+
+/** When currentPage <= this value, the "near start" layout is used (no leading ellipsis). */
+const NEAR_START_THRESHOLD = 5;
+
+/** Pages shown before the current page in the middle layout. */
+const PAGES_BEFORE_CURRENT = 1;
+
+/** Pages shown after the current page in the bounded middle layout. */
+const PAGES_AFTER_CURRENT = 2;
+
 export function getPageNumbers(
 	currentPage: number,
 	totalPages?: number,
-	hasNextPage?: boolean
+	hasNextPage?: boolean,
+	maxReachablePage?: number
 ): PageNumberItem[] {
+	// Resolve the last known page
 	let last: number | undefined;
-	if ( totalPages === undefined ) {
-		if ( hasNextPage === false ) {
-			last = currentPage;
-		} else {
-			last = undefined;
-		}
-	} else {
+	if ( totalPages !== undefined ) {
 		last = Math.max( 1, Number( totalPages ) );
+	} else if ( hasNextPage === false ) {
+		last = currentPage;
 	}
 
 	if ( last !== undefined && ( ! Number.isFinite( last ) || last < 1 ) ) {
 		return [];
 	}
-	if ( last !== undefined && last <= 8 ) {
-		return range( 1, last );
+
+	// Effective end anchor: known last page, or capped reachable page
+	const end =
+		last ??
+		( maxReachablePage !== undefined ? Math.max( currentPage, maxReachablePage ) : undefined );
+
+	// Small page count — show all without ellipsis
+	if ( end !== undefined && end <= VISIBLE_PAGE_SLOTS ) {
+		return range( 1, end );
+	}
+
+	// Near start
+	if ( currentPage <= NEAR_START_THRESHOLD ) {
+		if ( end !== undefined ) return [ ...range( 1, NEAR_START_THRESHOLD + 1 ), 'ellipsis', end ];
+		return [ ...range( 1, VISIBLE_PAGE_SLOTS - 1 ), 'ellipsis' ];
+	}
+
+	// Near end (bounded only — open-ended has no "end zone")
+	if ( last !== undefined && currentPage >= last - ( NEAR_START_THRESHOLD - 1 ) ) {
+		return [ 1, 'ellipsis', ...range( last - NEAR_START_THRESHOLD, last ) ];
 	}
 
-	// Bounded (last is a known page number)
-	if ( last !== undefined ) {
-		if ( currentPage <= 5 ) return [ ...range( 1, 6 ), 'ellipsis', last ];
-		if ( currentPage >= last - 4 ) return [ 1, 'ellipsis', ...range( last - 5, last ) ];
-		return [ 1, 'ellipsis', ...range( currentPage - 1, currentPage + 2 ), 'ellipsis', last ];
+	// Middle
+	if ( end !== undefined ) {
+		const rangeEnd = Math.min( currentPage + PAGES_AFTER_CURRENT, end );
+		const middle = range( currentPage - PAGES_BEFORE_CURRENT, rangeEnd );
+		if ( rangeEnd >= end ) return [ 1, 'ellipsis', ...middle ];
+		return [ 1, 'ellipsis', ...middle, 'ellipsis', end ];
 	}
 
-	// Open-ended (no known last page)
-	if ( currentPage <= 5 ) return [ ...range( 1, 7 ), 'ellipsis' ];
-	return [ 1, 'ellipsis', ...range( currentPage - 1, currentPage + 3 ), 'ellipsis' ];
+	// Fully open-ended middle
+	return [
+		1,
+		'ellipsis',
+		...range( currentPage - PAGES_BEFORE_CURRENT, currentPage + PAGES_AFTER_CURRENT + 1 ),
+		'ellipsis',
+	];
 }
 
 const ItemsPerPageSelect = ( {
@@ -104,14 +138,16 @@ const PageNumbers = ( {
 	currentPage,
 	totalPages,
 	hasNextPage,
+	maxReachablePage,
 	onPageChange,
 }: {
 	currentPage: number;
 	totalPages?: number;
 	hasNextPage?: boolean;
+	maxReachablePage?: number;
 	onPageChange: ( page: number ) => void;
 } ) => {
-	const pages = getPageNumbers( currentPage, totalPages, hasNextPage );
+	const pages = getPageNumbers( currentPage, totalPages, hasNextPage, maxReachablePage );
 
 	return (
 		<>
@@ -142,16 +178,17 @@ const PageNumbers = ( {
 const CompactPageSelector = ( {
 	currentPage,
 	totalPages,
+	maxReachablePage,
 	onPageChange,
 }: {
 	currentPage: number;
 	totalPages?: number;
+	maxReachablePage?: number;
 	onPageChange: ( page: number ) => void;
 } ) => {
 	const isOpenEnded = totalPages === undefined;
-	const pageOptions = isOpenEnded
-		? Array.from( { length: currentPage + 1 }, ( _, i ) => i + 1 )
-		: Array.from( { length: totalPages }, ( _, i ) => i + 1 );
+	const upperBound: number = isOpenEnded ? maxReachablePage ?? currentPage + 1 : totalPages;
+	const pageOptions = Array.from( { length: upperBound }, ( _, i ) => i + 1 );
 
 	return (
 		<Flex sx={ compactTextStyles }>
@@ -187,6 +224,7 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 			onPageChange,
 			onItemsPerPageChange,
 			hasNextPage,
+			maxReachablePage,
 			variant = 'full',
 			pageSizeOptions = [ 20, 50, 100 ],
 			className,
@@ -228,6 +266,7 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 							currentPage={ currentPage }
 							totalPages={ resolvedTotalPages }
 							hasNextPage={ hasNextPage }
+							maxReachablePage={ maxReachablePage }
 							onPageChange={ onPageChange }
 						/>
 					) }
@@ -236,6 +275,7 @@ export const Pagination = forwardRef< HTMLElement, PaginationProps >(
 						<CompactPageSelector
 							currentPage={ currentPage }
 							totalPages={ resolvedTotalPages }
+							maxReachablePage={ maxReachablePage }
 							onPageChange={ onPageChange }
 						/>
 					) }