docs(pagination): put current page on link element for a11y (#41154)

* docs(pagination): put current page on link element for a11y

* Reorganize and rewrite

* Update pagination.mdx

---------

Co-authored-by: Mark Otto <markdotto@gmail.com>

Author: MarkoOleksiyenko

site/src/content/docs/components/pagination.mdx

@@ -42,38 +42,42 @@ Looking to use an icon or symbol in place of text for some pagination links? Be
     </ul>
   </nav>`} />
 
-## Disabled and active states
+## Active
 
-Pagination links are customizable for different circumstances. Use `.disabled` for links that appear un-clickable and `.active` to indicate the current page.
-
-While the `.disabled` class uses `pointer-events: none` to _try_ to disable the link functionality of `<a>`s, that CSS property is not yet standardized and doesn’t account for keyboard navigation. As such, you should always add `tabindex="-1"` on disabled links and use custom JavaScript to fully disable their functionality.
+Add `.active` to indicate a `.page-item` is the one currently being viewed. If using an `<a>` on the current page, `aria-current="page"` should be added for assistive technologies.
 
 <Example code={`<nav aria-label="...">
     <ul class="pagination">
-      <li class="page-item disabled">
-        <a class="page-link">Previous</a>
-      </li>
+      <li class="page-item"><a href="#" class="page-link">Previous</a></li>
       <li class="page-item"><a class="page-link" href="#">1</a></li>
-      <li class="page-item active" aria-current="page">
-        <a class="page-link" href="#">2</a>
+      <li class="page-item active">
+        <a class="page-link" href="#" aria-current="page">2</a>
       </li>
       <li class="page-item"><a class="page-link" href="#">3</a></li>
-      <li class="page-item">
-        <a class="page-link" href="#">Next</a>
-      </li>
+      <li class="page-item"><a class="page-link" href="#">Next</a></li>
     </ul>
   </nav>`} />
 
-You can optionally swap out active or disabled anchors for `<span>`, or omit the anchor in the case of the prev/next arrows, to remove click functionality and prevent keyboard focus while retaining intended styles.
+If using a non-interactive element, like a `<span>` for the current page, you may omit the `aria-current` attribute.
+
+```html
+<li class="page-item active">
+  <span class="page-link">2</span>
+</li>
+```
+
+## Disabled
+
+Add `.disabled` to a `.page-item` to make it appear un-clickable. While `.disabled` uses `pointer-events: none` to disable the link‘s interactivity, that CSS property is not yet standardized and doesn’t account for keyboard navigation. As such, you should always add `tabindex="-1"` on disabled links and use custom JavaScript to fully disable their functionality.
 
 <Example code={`<nav aria-label="...">
     <ul class="pagination">
       <li class="page-item disabled">
-        <span class="page-link">Previous</span>
+        <a class="page-link">Previous</a>
       </li>
       <li class="page-item"><a class="page-link" href="#">1</a></li>
-      <li class="page-item active" aria-current="page">
-        <span class="page-link">2</span>
+      <li class="page-item active">
+        <a class="page-link" href="#" aria-current="page">2</a>
       </li>
       <li class="page-item"><a class="page-link" href="#">3</a></li>
       <li class="page-item">
@@ -82,14 +86,22 @@ You can optionally swap out active or disabled anchors for `<span>`, or omit the
     </ul>
   </nav>`} />
 
+And just like active page items, you can swap out the disabled `<a>` for a `<span>` to remove click functionality and prevent keyboard focus while retaining intended styles.
+
+```html
+<li class="page-item disabled">
+  <span class="page-link">Previous</span>
+</li>
+```
+
 ## Sizing
 
 Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for additional sizes.
 
 <Example code={`<nav aria-label="...">
     <ul class="pagination pagination-lg">
-      <li class="page-item active" aria-current="page">
-        <span class="page-link">1</span>
+      <li class="page-item active" >
+        <a class="page-link" aria-current="page">1</a>
       </li>
       <li class="page-item"><a class="page-link" href="#">2</a></li>
       <li class="page-item"><a class="page-link" href="#">3</a></li>
@@ -98,8 +110,8 @@ Fancy larger or smaller pagination? Add `.pagination-lg` or `.pagination-sm` for
 
 <Example code={`<nav aria-label="...">
     <ul class="pagination pagination-sm">
-      <li class="page-item active" aria-current="page">
-        <span class="page-link">1</span>
+      <li class="page-item active">
+        <a class="page-link" aria-current="page">1</a>
       </li>
       <li class="page-item"><a class="page-link" href="#">2</a></li>
       <li class="page-item"><a class="page-link" href="#">3</a></li>