From 001a4529bab9ab8ad2791fd49a030051bb5ed2e6 Mon Sep 17 00:00:00 2001
From: Dan Cormier <dcormier@stackoverflow.com>
Date: Thu, 12 Dec 2024 17:00:46 -0500
Subject: [PATCH] fix(pagination): support accessible markup (#1870)

* fix(pagination): support accessible markup

[STACKS-687](https://stackoverflow.atlassian.net/browse/STACKS-687)

* Remove reference to Stacks 2.6.1 in markup deprecation notice

* Update docs with review suggestions

Addresses review: https://github.com/StackExchange/Stacks/pull/1870#pullrequestreview-2498703726
---
 docs/product/components/pagination.html       | 115 +++++++++++++++++-
 .../pagination/pagination.a11y.test.ts        |  31 +++--
 lib/components/pagination/pagination.less     |  18 ++-
 .../pagination/pagination.visual.test.ts      |  27 ++++
 .../baseline/s-pagination-dark-legacy.ico     |   3 +
 .../s-pagination-highcontrast-dark-legacy.ico |   3 +
 ...s-pagination-highcontrast-light-legacy.ico |   3 +
 .../baseline/s-pagination-light-legacy.ico    |   3 +
 .../baseline/s-pagination-dark-legacy.ico     |   3 +
 .../s-pagination-highcontrast-dark-legacy.ico |   3 +
 ...s-pagination-highcontrast-light-legacy.ico |   3 +
 .../baseline/s-pagination-light-legacy.ico    |   3 +
 .../baseline/s-pagination-dark-legacy.ico     |   3 +
 .../s-pagination-highcontrast-dark-legacy.ico |   3 +
 ...s-pagination-highcontrast-light-legacy.ico |   3 +
 .../baseline/s-pagination-light-legacy.ico    |   3 +
 16 files changed, 216 insertions(+), 11 deletions(-)
 create mode 100644 screenshots/Chromium/baseline/s-pagination-dark-legacy.ico
 create mode 100644 screenshots/Chromium/baseline/s-pagination-highcontrast-dark-legacy.ico
 create mode 100644 screenshots/Chromium/baseline/s-pagination-highcontrast-light-legacy.ico
 create mode 100644 screenshots/Chromium/baseline/s-pagination-light-legacy.ico
 create mode 100644 screenshots/Firefox/baseline/s-pagination-dark-legacy.ico
 create mode 100644 screenshots/Firefox/baseline/s-pagination-highcontrast-dark-legacy.ico
 create mode 100644 screenshots/Firefox/baseline/s-pagination-highcontrast-light-legacy.ico
 create mode 100644 screenshots/Firefox/baseline/s-pagination-light-legacy.ico
 create mode 100644 screenshots/Webkit/baseline/s-pagination-dark-legacy.ico
 create mode 100644 screenshots/Webkit/baseline/s-pagination-highcontrast-dark-legacy.ico
 create mode 100644 screenshots/Webkit/baseline/s-pagination-highcontrast-light-legacy.ico
 create mode 100644 screenshots/Webkit/baseline/s-pagination-light-legacy.ico

diff --git a/docs/product/components/pagination.html b/docs/product/components/pagination.html
index 26f8f343eb..ffd98c3695 100644
--- a/docs/product/components/pagination.html
+++ b/docs/product/components/pagination.html
@@ -31,6 +31,119 @@
     {% header "h2", "Example" %}
     <div class="stacks-preview">
 {% highlight html %}
+<nav class="s-pagination" aria-label="pagination">
+    <ul>
+        <li>
+            <a class="s-pagination--item is-selected" href="…" aria-current="page">
+                <span class="v-visible-sr">page</span>
+                1
+            </a>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                <span class="v-visible-sr">page</span>
+                2
+            </a>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                <span class="v-visible-sr">page</span>
+                3
+            </a>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                <span class="v-visible-sr">page</span>
+                4
+            </a>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                <span class="v-visible-sr">page</span>
+                5
+            </a>
+        </li>
+        <li>
+            <span class="s-pagination--item s-pagination--item__clear">…</span>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                <span class="v-visible-sr">page</span>
+                122386
+            </a>
+        </li>
+        <li>
+            <a class="s-pagination--item" href="…">
+                Next
+                <span class="v-visible-sr">page</span>
+            </a>
+        </li>
+    </ul>
+</nav>
+{% endhighlight %}
+        <div class="stacks-preview--example overflow-x-auto">
+            <nav class="s-pagination" role="presentation">
+                <ul>
+                    <li>
+                        <a class="s-pagination--item is-selected" href="#" aria-current="page">
+                            <span class="v-visible-sr">page</span>
+                            1
+                        </a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            <span class="v-visible-sr">page</span>
+                            2
+                        </a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            <span class="v-visible-sr">page</span>
+                            3
+                        </a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            <span class="v-visible-sr">page</span>
+                            4
+                        </a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            <span class="v-visible-sr">page</span>
+                            5
+                        </a>
+                    </li>
+                    <li>
+                        <span class="s-pagination--item s-pagination--item__clear">…</span>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            <span class="v-visible-sr">page</span>
+                            122386
+                        </a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">
+                            Next
+                            <span class="v-visible-sr">page</span>
+                        </a>
+                    </li>
+                </ul>
+            </nav>
+        </div>
+    </div>
+</section>
+
+<section class="stacks-section">
+    {% header "h2", "Legacy example" %}
+
+    {% tip, "warning", "mb24" %}
+        <strong>Note:</strong>The below markup has been deprecated due to insufficient accessibility. Please use the new markup above.
+    {% endtip %}
+
+    <div class="stacks-preview">
+{% highlight html %}
 <div class="s-pagination">
     <a class="s-pagination--item is-selected" href="…" aria-current="page">
         <span class="v-visible-sr">page</span>
@@ -64,7 +177,7 @@
 </div>
 {% endhighlight %}
         <div class="stacks-preview--example overflow-x-auto">
-            <div class="s-pagination">
+            <div class="s-pagination" role="presentation">
                 <a class="s-pagination--item is-selected" href="#" aria-current="page">
                     <span class="v-visible-sr">page</span>
                     1
diff --git a/lib/components/pagination/pagination.a11y.test.ts b/lib/components/pagination/pagination.a11y.test.ts
index c7fd0e9cb7..4009191c87 100644
--- a/lib/components/pagination/pagination.a11y.test.ts
+++ b/lib/components/pagination/pagination.a11y.test.ts
@@ -7,15 +7,32 @@ describe("pagination", () => {
         baseClass: "s-pagination",
         children: {
             default: `
-                <a class="s-pagination--item" href="#">Prev</a>
-                <a class="s-pagination--item" href="#">1</a>
-                <span class="s-pagination--item is-selected" aria-current="page">2</span>
-                <a class="s-pagination--item" href="#">3</a>
-                <span class="s-pagination--item s-pagination--item__clear">…</span>
-                <a class="s-pagination--item" href="#">100</a>
-                <a class="s-pagination--item" href="#">Next</a>
+                <ul>
+                    <li>
+                        <a class="s-pagination--item" href="#">Prev</a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">1</a>
+                    </li>
+                    <li>
+                        <span class="s-pagination--item is-selected" aria-current="page">2</span>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">3</a>
+                    </li>
+                    <li>
+                        <span class="s-pagination--item s-pagination--item__clear">…</span>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">100</a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">Next</a>
+                    </li>
+                </ul>
             `,
         },
+        tag: "nav",
         additionalAssertions: [WCAGNonTextContrast],
     });
 });
diff --git a/lib/components/pagination/pagination.less b/lib/components/pagination/pagination.less
index b3893cd084..c79a213ae9 100644
--- a/lib/components/pagination/pagination.less
+++ b/lib/components/pagination/pagination.less
@@ -1,4 +1,12 @@
 .s-pagination {
+    // reset list styles on ul.s-pagination and .s-pagination ul
+    ul,
+    ul& {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+    }
+
     & &--item {
         --_pa-item-bg: transparent;
         --_pa-item-bc: var(--bc-darker);
@@ -54,12 +62,16 @@
         color: var(--_pa-item-fc);
 
         border-radius: var(--br-sm);
+        display: inline-block;
         font-size: var(--fs-body1);
         line-height: var(--lh-xl);
         padding: 0 var(--su8);
     }
 
-    display: flex;
-    flex-wrap: wrap;
-    gap: var(--su4);
+    &,
+    ul {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--su4);
+    }
 }
diff --git a/lib/components/pagination/pagination.visual.test.ts b/lib/components/pagination/pagination.visual.test.ts
index 737750e157..cea8d729d0 100644
--- a/lib/components/pagination/pagination.visual.test.ts
+++ b/lib/components/pagination/pagination.visual.test.ts
@@ -7,6 +7,32 @@ describe("pagination", () => {
         baseClass: "s-pagination",
         children: {
             default: `
+                <ul>
+                    <li>
+                        <a class="s-pagination--item" href="#">Prev</a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">1</a>
+                    </li>
+                    <li>
+                        <span class="s-pagination--item is-selected" aria-current="page">2</span>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">3</a>
+                    </li>
+                    <li>
+                        <span class="s-pagination--item s-pagination--item__clear">…</span>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">100</a>
+                    </li>
+                    <li>
+                        <a class="s-pagination--item" href="#">Next</a>
+                    </li>
+                </ul>
+            `,
+            // legacy test for deprecated pagination component markup
+            legacy: `
                 <a class="s-pagination--item" href="#">Prev</a>
                 <a class="s-pagination--item" href="#">1</a>
                 <span class="s-pagination--item is-selected" aria-current="page">2</span>
@@ -16,6 +42,7 @@ describe("pagination", () => {
                 <a class="s-pagination--item" href="#">Next</a>
             `,
         },
+        tag: "nav",
         template: ({ component, testid }) => html`
             <div class="d-inline-block p8" data-testid="${testid}">
                 ${component}
diff --git a/screenshots/Chromium/baseline/s-pagination-dark-legacy.ico b/screenshots/Chromium/baseline/s-pagination-dark-legacy.ico
new file mode 100644
index 0000000000..46f0a07480
--- /dev/null
+++ b/screenshots/Chromium/baseline/s-pagination-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:56267fe9e1543dcbe35c39d4b88b36e3f6e1071d52f0ddc6ae6074c4942dede9
+size 2930
diff --git a/screenshots/Chromium/baseline/s-pagination-highcontrast-dark-legacy.ico b/screenshots/Chromium/baseline/s-pagination-highcontrast-dark-legacy.ico
new file mode 100644
index 0000000000..f42f7c4cb0
--- /dev/null
+++ b/screenshots/Chromium/baseline/s-pagination-highcontrast-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08a4173c2e773e613ec9ae58b05166157cc00ff71dc26d78c6b10357a2121777
+size 2810
diff --git a/screenshots/Chromium/baseline/s-pagination-highcontrast-light-legacy.ico b/screenshots/Chromium/baseline/s-pagination-highcontrast-light-legacy.ico
new file mode 100644
index 0000000000..0906d033f9
--- /dev/null
+++ b/screenshots/Chromium/baseline/s-pagination-highcontrast-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e2d9586a4623896d24b3e69bea97f7d307e1a674a3e8ecb07617d11d45ab6e27
+size 2891
diff --git a/screenshots/Chromium/baseline/s-pagination-light-legacy.ico b/screenshots/Chromium/baseline/s-pagination-light-legacy.ico
new file mode 100644
index 0000000000..5ae152afe8
--- /dev/null
+++ b/screenshots/Chromium/baseline/s-pagination-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:aca0115bfbfe0d36ec2b8cd2a4821846d009c65a47e5ab9e599f19117253609c
+size 2947
diff --git a/screenshots/Firefox/baseline/s-pagination-dark-legacy.ico b/screenshots/Firefox/baseline/s-pagination-dark-legacy.ico
new file mode 100644
index 0000000000..eeac2dd0e7
--- /dev/null
+++ b/screenshots/Firefox/baseline/s-pagination-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7525ea34e5ceaa5f55895fb4f683f74ae78160c4de11254cd5790297e593246b
+size 3564
diff --git a/screenshots/Firefox/baseline/s-pagination-highcontrast-dark-legacy.ico b/screenshots/Firefox/baseline/s-pagination-highcontrast-dark-legacy.ico
new file mode 100644
index 0000000000..27a989fbb0
--- /dev/null
+++ b/screenshots/Firefox/baseline/s-pagination-highcontrast-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:50049f9525cedbc6db037aef76ac8cd1b3aad0ed5ad194995a8882ec47dc106b
+size 3527
diff --git a/screenshots/Firefox/baseline/s-pagination-highcontrast-light-legacy.ico b/screenshots/Firefox/baseline/s-pagination-highcontrast-light-legacy.ico
new file mode 100644
index 0000000000..2be89e9477
--- /dev/null
+++ b/screenshots/Firefox/baseline/s-pagination-highcontrast-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d12df32fe9413c902d9aa86e780603f74efd78ae536b4c02e13f1cbb80fe2e32
+size 3517
diff --git a/screenshots/Firefox/baseline/s-pagination-light-legacy.ico b/screenshots/Firefox/baseline/s-pagination-light-legacy.ico
new file mode 100644
index 0000000000..94195b090a
--- /dev/null
+++ b/screenshots/Firefox/baseline/s-pagination-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0571367c9c902dda5a440ed30c0689cfa58521b369c5f6af84db0d72ce01fad2
+size 3492
diff --git a/screenshots/Webkit/baseline/s-pagination-dark-legacy.ico b/screenshots/Webkit/baseline/s-pagination-dark-legacy.ico
new file mode 100644
index 0000000000..0bbd80dee9
--- /dev/null
+++ b/screenshots/Webkit/baseline/s-pagination-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e0acd89ef473ba1390edea605dd9c11947160f37a6bcb6d56327c1fb45f6b3b
+size 2412
diff --git a/screenshots/Webkit/baseline/s-pagination-highcontrast-dark-legacy.ico b/screenshots/Webkit/baseline/s-pagination-highcontrast-dark-legacy.ico
new file mode 100644
index 0000000000..6ebd032230
--- /dev/null
+++ b/screenshots/Webkit/baseline/s-pagination-highcontrast-dark-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:63d357bf92886a4b2a3de71024cea5d3677bf93a38a406f7532721e3f8d102d2
+size 2333
diff --git a/screenshots/Webkit/baseline/s-pagination-highcontrast-light-legacy.ico b/screenshots/Webkit/baseline/s-pagination-highcontrast-light-legacy.ico
new file mode 100644
index 0000000000..f9e529640f
--- /dev/null
+++ b/screenshots/Webkit/baseline/s-pagination-highcontrast-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4921395ccb4b14c481ee180751a3757ff5a50d32917a84b1c69e69e9579b9564
+size 2433
diff --git a/screenshots/Webkit/baseline/s-pagination-light-legacy.ico b/screenshots/Webkit/baseline/s-pagination-light-legacy.ico
new file mode 100644
index 0000000000..a0afeecfec
--- /dev/null
+++ b/screenshots/Webkit/baseline/s-pagination-light-legacy.ico
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2b11d98ca9c19a4a77111c79cd8a3f34cd14d53692096f5713d690f1f1ea18d7
+size 2396