Pagination algorithm enhancements

[hectahertz]

This PR replaces the Pagination algorithm to optimize how we decide which page numbers to render so the buttons stay in place, so we can reduce friction and make it easier to use for users with dexterity issues.

Changelog

New

Added a couple of tests for the new algorithm.

    ✓ adds a page when there would be only one page hidden by the left ellipsis
    ✓ adds a page when there would be only one page hidden by the right ellipsis

Changed

The algorithm has been completely rewritten, simplified and documented with the goal of increasing legibility and maintainability.

The previous algorithm relied heavily on traversing the list of pages back and forth and sliding counters and ranges. This new version calculates the dimensions of the different parts in one go, with visual explanations of the math in the comments.

The new algorithm has also two UX improvements:

• Doesn't create ellipsis when there's only a gap of one page, it just renders it.
• Keeps the number of pages shown in total consistent, making the dimensions of the overall component and the positions of the buttons static.

Previous UX

previous.mov

New UX (same parameters)

new.mov

This PR also changed the styling of the Previous and Next buttons so they always keep the chevron and their dimensions, even when disabled.

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Added two tests which should be pretty self explanatory

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: e723e40

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github depends on. If you are GitHub staff, we recommend testing these changes with github/github using the integration workflow. Thanks!

[github-actions]

size-limit report 📦

Path	Size
packages/react/dist/browser.esm.js	104.2 KB (+0.03% 🔺)
packages/react/dist/browser.umd.js	104.49 KB (-0.03% 🔽)

[primer-integration]

👋 Hi from github/github! Your integration PR is ready: https://github.com/github/github/pull/358229

[primer-integration]

🔴 golden-jobs completed with status failure.