From 079e7e38e9b7b3149621e560eb3aa8d002b28522 Mon Sep 17 00:00:00 2001
From: "beeps (Kim Grey)" <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Wed, 17 May 2023 14:05:40 +0100
Subject: [PATCH] Spike modifications to pagination component

---
 .../govuk/components/pagination/_index.scss   |  28 +--
 .../components/pagination/pagination.yaml     | 200 ++++++++++++------
 .../govuk/components/pagination/template.njk  |  64 ++++--
 3 files changed, 204 insertions(+), 88 deletions(-)

diff --git a/packages/govuk-frontend/src/govuk/components/pagination/_index.scss b/packages/govuk-frontend/src/govuk/components/pagination/_index.scss
index 439e46cf3d..9bf4c74faa 100644
--- a/packages/govuk-frontend/src/govuk/components/pagination/_index.scss
+++ b/packages/govuk-frontend/src/govuk/components/pagination/_index.scss
@@ -37,17 +37,9 @@
   }
 
   .govuk-pagination__item {
-    // Hide items on small screens except the prev/next items,
-    // non-link items and the first and last items
-    display: none;
-
     // Center align pagination links in their parent list item so that they
     // visually sit in the middle of their touch area
     text-align: center;
-
-    @include govuk-media-query($from: tablet) {
-      display: block;
-    }
   }
 
   .govuk-pagination__prev,
@@ -70,12 +62,20 @@
     padding-right: 0;
   }
 
-  // Only show first, last and non-link items on mobile
-  .govuk-pagination__item--current,
-  .govuk-pagination__item--ellipses,
-  .govuk-pagination__item:first-child,
-  .govuk-pagination__item:last-child {
-    display: block;
+  // Hide neighbouring items on mobile
+  .govuk-pagination__item--neighbour {
+    display: none;
+
+    @include govuk-media-query($from: tablet) {
+      display: block;
+    }
+  }
+
+  // Show 'collapsed only' items only on mobile
+  .govuk-pagination__item--collapsed-only {
+    @include govuk-media-query($from: tablet) {
+      display: none;
+    }
   }
 
   .govuk-pagination__item--current {
diff --git a/packages/govuk-frontend/src/govuk/components/pagination/pagination.yaml b/packages/govuk-frontend/src/govuk/components/pagination/pagination.yaml
index b8b93d691a..655a311df4 100644
--- a/packages/govuk-frontend/src/govuk/components/pagination/pagination.yaml
+++ b/packages/govuk-frontend/src/govuk/components/pagination/pagination.yaml
@@ -16,14 +16,6 @@ params:
         type: string
         required: true
         description: The link's URL.
-      - name: current
-        type: boolean
-        required: false
-        description: Set to `true` to indicate the current page the user is on.
-      - name: ellipsis
-        type: boolean
-        required: false
-        description: Use this option if you want to specify an ellipsis at a given point between numbers. If you set this option as `true`, any other options for the item are ignored.
       - name: attributes
         type: object
         required: false
@@ -70,6 +62,10 @@ params:
         type: object
         required: false
         description: The HTML attributes (for example, data attributes) you want to add to the anchor.
+  - name: currentPage
+    type: integer
+    required: true
+    description: The index of the current page within the set of `items`. This is a 1-based index, so that it matches the visible number that is rendered by default.
   - name: landmarkLabel
     type: string
     required: false
@@ -90,14 +86,11 @@ examples:
         href: '/previous'
       next:
         href: '/next'
+      currentPage: 2
       items:
-        - number: 1
-          href: '/page/1'
-        - number: 2
-          href: '/page/2'
-          current: true
-        - number: 3
-          href: '/page/3'
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
   - name: with custom navigation landmark
     data:
       previous:
@@ -105,14 +98,11 @@ examples:
       next:
         href: '/next'
       landmarkLabel: 'search'
+      currentPage: 2
       items:
-        - number: 1
-          href: '/page/1'
-        - number: 2
-          href: '/page/2'
-          current: true
-        - number: 3
-          href: '/page/3'
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
   - name: with custom link and item text
     data:
       previous:
@@ -121,12 +111,12 @@ examples:
       next:
         href: '/next'
         text: 'Next page'
+      currentPage: 2
       items:
         - number: 'one'
           href: '/page/1'
         - number: 'two'
           href: '/page/2'
-          current: true
         - number: 'three'
           href: '/page/3'
   - name: with custom accessible labels on item links
@@ -135,16 +125,13 @@ examples:
         href: '/previous'
       next:
         href: '/next'
+      currentPage: 2
       items:
-        - number: 1
-          href: '/page/1'
+        - href: '/page/1'
           visuallyHiddenText: '1st page'
-        - number: 2
-          href: '/page/2'
-          current: true
+        - href: '/page/2'
           visuallyHiddenText: '2nd page (you are currently on this page)'
-        - number: 3
-          href: '/page/3'
+        - href: '/page/3'
           visuallyHiddenText: '3rd page'
   - name: with many pages
     data:
@@ -152,48 +139,139 @@ examples:
         href: '/previous'
       next:
         href: '/next'
+      currentPage: 10
       items:
-        - number: 1
-          href: '/page/1'
-        - ellipsis: true
-        - number: 8
-          href: '/page/8'
-        - number: 9
-          href: '/page/9'
-        - number: 10
-          href: '/page/10'
-          current: true
-        - number: 11
-          href: '/page/11'
-        - number: 12
-          href: '/page/12'
-        - ellipsis: true
-        - number: 40
-          href: '/page/40'
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
+        - href: '/page/11'
+        - href: '/page/12'
+        - href: '/page/13'
+        - href: '/page/14'
+        - href: '/page/15'
+        - href: '/page/16'
+        - href: '/page/17'
+        - href: '/page/18'
+        - href: '/page/19'
+        - href: '/page/20'
   - name: first page
     data:
       next:
         href: '/next'
+      currentPage: 1
       items:
-        - number: 1
-          href: '/page/1'
-          current: true
-        - number: 2
-          href: '/page/2'
-        - number: 3
-          href: '/page/3'
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
   - name: last page
     data:
       previous:
         href: '/previous'
+      currentPage: 3
       items:
-        - number: 1
-          href: '/page/1'
-        - number: 2
-          href: '/page/2'
-        - number: 3
-          href: '/page/3'
-          current: true
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+  - name: bordering first page
+    data:
+      previous:
+        href: '/previous'
+      next:
+        href: '/next'
+      currentPage: 4
+      items:
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
+  - name: bordering last page
+    data:
+      previous:
+        href: '/previous'
+      next:
+        href: '/next'
+      currentPage: 7
+      items:
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
+  - name: with fewer neighbours
+    data:
+      previous:
+        href: '/previous'
+      next:
+        href: '/next'
+      currentPage: 4
+      neighbouringPages: 1
+      items:
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
+  - name: with more neighbours
+    data:
+      previous:
+        href: '/previous'
+      next:
+        href: '/next'
+      currentPage: 7
+      neighbouringPages: 4
+      items:
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
+  - name: with no neighbours
+    data:
+      previous:
+        href: '/previous'
+      next:
+        href: '/next'
+      currentPage: 7
+      neighbouringPages: 0
+      items:
+        - href: '/page/1'
+        - href: '/page/2'
+        - href: '/page/3'
+        - href: '/page/4'
+        - href: '/page/5'
+        - href: '/page/6'
+        - href: '/page/7'
+        - href: '/page/8'
+        - href: '/page/9'
+        - href: '/page/10'
   - name: with prev and next only
     data:
       previous:
diff --git a/packages/govuk-frontend/src/govuk/components/pagination/template.njk b/packages/govuk-frontend/src/govuk/components/pagination/template.njk
index a1bcdb1c10..c617e890a1 100644
--- a/packages/govuk-frontend/src/govuk/components/pagination/template.njk
+++ b/packages/govuk-frontend/src/govuk/components/pagination/template.njk
@@ -1,5 +1,20 @@
 {% set blockLevel = not params.items and (params.next or params.previous) %}
 
+{% set currentPage = params.currentPage %}
+{% set neighbouringPages = params.neighbouringPages if params.neighbouringPages !== undefined else 2 %}
+
+{% set visiblePagesLower = currentPage - neighbouringPages %}
+{% set visiblePagesUpper = currentPage + neighbouringPages %}
+
+{% macro _paginationItem(index, item, context = {}) %}
+  {%- set isCurrent = index == currentPage %}
+  <li class="govuk-pagination__item {{- ' govuk-pagination__item--current' if isCurrent }} {{- ' govuk-pagination__item--neighbour' if context.neighbour }}">
+    <a class="govuk-link govuk-pagination__link" href="{{ item.href }}" aria-label="{{ item.visuallyHiddenText | default("Page " + item.number) }}" {%- if isCurrent %} aria-current="page"{% endif %} {%- for attribute, value in item.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+      {{- item.number | default(index) -}}
+    </a>
+  </li>
+{% endmacro %}
+
 <nav class="govuk-pagination {{- ' ' + params.classes if params.classes }} {{- ' govuk-pagination--block' if blockLevel }}" role="navigation" aria-label="{{ params.landmarkLabel | default("results") }}" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}" {%- endfor -%}>
   {%- if params.previous and params.previous.href -%}
     <div class="govuk-pagination__prev">
@@ -18,21 +33,44 @@
     </div>
   {% endif %}
 
-  {%- if params.items -%}
+  {# Only show numbered pagination if params.items is set #}
+  {%- if params.items %}
     <ul class="govuk-pagination__list">
-      {%- for item in params.items -%}
-        {%- if item.ellipsis -%}
-          <li class="govuk-pagination__item govuk-pagination__item--ellipses">&ctdot;</li>
-        {%- elseif item.number -%}
-          <li class="govuk-pagination__item {{- ' govuk-pagination__item--current' if item.current }}">
-            <a class="govuk-link govuk-pagination__link" href="{{ item.href }}" aria-label="{{ item.visuallyHiddenText | default("Page " + item.number) }}" {%- if item.current %} aria-current="page" {%- endif -%} {%- for attribute, value in item.attributes %} {{ attribute }}="{{ value }}" {%- endfor -%}>
-              {{ item.number }}
-            </a>
-          </li>
-        {%- endif -%}
-      {%- endfor -%}
+
+    {%- for item in params.items %}
+
+      {# Always show the first and last numbered option #}
+      {%- if loop.first or loop.last %}
+
+        {# If the last item in the loop, and we're likely to need one, prepend an ellipsis #}
+        {%- if loop.last and loop.index > currentPage + 1 %}
+          <li class="govuk-pagination__item govuk-pagination__item--ellipses {{- ' govuk-pagination__item--collapsed-only' if loop.index - 1 <= visiblePagesUpper }}">&ctdot;</li>
+        {%- endif %}
+
+        {{ _paginationItem(loop.index, item) }}
+
+        {# If the first item in the loop, and we're likely to need one, append an ellipsis #}
+        {%- if loop.first and loop.index < currentPage - 1 %}
+          <li class="govuk-pagination__item govuk-pagination__item--ellipses {{- ' govuk-pagination__item--collapsed-only' if loop.index + 1 >= visiblePagesLower }}">&ctdot;</li>
+        {%- endif %}
+
+      {# Is this within neighbourly range of the current page? Show it! #}
+      {%- elif loop.index >= visiblePagesLower and loop.index <= visiblePagesUpper %}
+
+        {# If this is a 'neighbour' page, mark it as such so we can hide it later #}
+        {%- if loop.index != currentPage %}
+          {{ _paginationItem(loop.index, item, { neighbour: true }) }}
+
+        {# Otherwise, output it normally #}
+        {%- else %}
+          {{ _paginationItem(loop.index, item) }}
+
+        {%- endif %}
+      {%- endif %}
+
+    {%- endfor %}
     </ul>
-  {%- endif -%}
+  {%- endif %}
 
   {%- if params.next and params.next.href -%}
     {%- set nextArrow -%}