From 2604c4ef3b0b128e255f740c5c32a88bc8108c06 Mon Sep 17 00:00:00 2001
From: Dan Cormier <dancormierall@gmail.com>
Date: Thu, 12 Dec 2024 16:23:44 -0500
Subject: [PATCH] Update docs with review suggestions

Addresses review: https://github.com/StackExchange/Stacks/pull/1870#pullrequestreview-2498703726
---
 docs/product/components/pagination.html | 86 +++++++++++++++++++++++--
 1 file changed, 79 insertions(+), 7 deletions(-)

diff --git a/docs/product/components/pagination.html b/docs/product/components/pagination.html
index 7b96999548..ffd98c3695 100644
--- a/docs/product/components/pagination.html
+++ b/docs/product/components/pagination.html
@@ -29,14 +29,9 @@
 </section>
 <section class="stacks-section">
     {% header "h2", "Example" %}
-
-    {% tip, "warning", "mb24" %}
-        <strong>Note:</strong> The recommended pagination component markup has been updated for better accessibility. Please update any existing implementations to the new markup.
-    {% endtip %}
-
     <div class="stacks-preview">
 {% highlight html %}
-<nav class="s-pagination">
+<nav class="s-pagination" aria-label="pagination">
     <ul>
         <li>
             <a class="s-pagination--item is-selected" href="…" aria-current="page">
@@ -87,7 +82,7 @@
 </nav>
 {% endhighlight %}
         <div class="stacks-preview--example overflow-x-auto">
-            <nav class="s-pagination">
+            <nav class="s-pagination" role="presentation">
                 <ul>
                     <li>
                         <a class="s-pagination--item is-selected" href="#" aria-current="page">
@@ -139,3 +134,80 @@
         </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>
+        1
+    </a>
+    <a class="s-pagination--item" href="…">
+        <span class="v-visible-sr">page</span>
+        2
+    </a>
+    <a class="s-pagination--item" href="…">
+        <span class="v-visible-sr">page</span>
+        3
+    </a>
+    <a class="s-pagination--item" href="…">
+        <span class="v-visible-sr">page</span>
+        4
+    </a>
+    <a class="s-pagination--item" href="…">
+        <span class="v-visible-sr">page</span>
+        5
+    </a>
+    <span class="s-pagination--item s-pagination--item__clear">…</span>
+    <a class="s-pagination--item" href="…">
+        <span class="v-visible-sr">page</span>
+        122386
+    </a>
+    <a class="s-pagination--item" href="…">
+        Next
+        <span class="v-visible-sr">page</span>
+    </a>
+</div>
+{% endhighlight %}
+        <div class="stacks-preview--example overflow-x-auto">
+            <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
+                </a>
+                <a class="s-pagination--item" href="#">
+                    <span class="v-visible-sr">page</span>
+                    2
+                </a>
+                <a class="s-pagination--item" href="#">
+                    <span class="v-visible-sr">page</span>
+                    3
+                </a>
+                <a class="s-pagination--item" href="#">
+                    <span class="v-visible-sr">page</span>
+                    4
+                </a>
+                <a class="s-pagination--item" href="#">
+                    <span class="v-visible-sr">page</span>
+                    5
+                </a>
+                <span class="s-pagination--item s-pagination--item__clear">…</span>
+                <a class="s-pagination--item" href="#">
+                    <span class="v-visible-sr">page</span>
+                    122386
+                </a>
+                <a class="s-pagination--item" href="#">
+                    Next
+                    <span class="v-visible-sr">page</span>
+                </a>
+            </div>
+        </div>
+    </div>
+</section>