Revamp list group items built with anchors and buttons

- Make it an explicit class instead of qualifying with elements (.list-group-item-action)
- Rearrange the entire file for more straightforward flow
- Fix text-decoration bug as a result of the reorder
- Switch from h4's to h5's in docs
- Update docs to merge anchors and buttons sections; clearify usage guidelines there, too
- Nullify #17479 in the process

1 files changed, 30 insertions, 30 deletions

diff --git a/docs/components/list-group.md b/docs/components/list-group.md
index 0d3254984..c3d466d5f 100644
--- a/docs/components/list-group.md
+++ b/docs/components/list-group.md
@@ -45,13 +45,13 @@ Add labels to any list group item to show unread counts, activity, etc.
 </ul>
 {% endexample %}
 
-## Linked items
+## Disabled items
 
-Linkify list group items by using anchor tags instead of list items (that also means a parent `<div>` instead of an `<ul>`). No need for individual parents around each element.
+Add `.disabled` to a `.list-group-item` to gray it out to appear disabled.
 
 {% example html %}
 <div class="list-group">
-  <a href="#" class="list-group-item active">
+  <a href="#" class="list-group-item disabled">
     Cras justo odio
   </a>
   <a href="#" class="list-group-item">Dapibus ac facilisis in</a>
@@ -61,33 +61,33 @@ Linkify list group items by using anchor tags instead of list items (that also m
 </div>
 {% endexample %}
 
-## Button items
+## Anchors and buttons
+
+Use anchors or buttons to create actionable list group items with hover, disabled, and active states by adding `.list-group-item-action`. This separate class contains a few overrides to add compatibility for `<a>`s and `<button>`s, as well as the hover and focus states.
 
-List group items may be buttons instead of list items (that also means a parent `<div>` instead of an `<ul>`). No need for individual parents around each element. **Don't use the standard `.btn` classes here.**
+Be sure to **not use the standard `.btn` classes here**.
 
 {% example html %}
 <div class="list-group">
-  <button type="button" class="list-group-item">Cras justo odio</button>
-  <button type="button" class="list-group-item">Dapibus ac facilisis in</button>
-  <button type="button" class="list-group-item">Morbi leo risus</button>
-  <button type="button" class="list-group-item">Porta ac consectetur ac</button>
-  <button type="button" class="list-group-item">Vestibulum at eros</button>
+  <a href="#" class="list-group-item active">
+    Cras justo odio
+  </a>
+  <a href="#" class="list-group-item list-group-item-action">Dapibus ac facilisis in</a>
+  <a href="#" class="list-group-item list-group-item-action">Morbi leo risus</a>
+  <a href="#" class="list-group-item list-group-item-action">Porta ac consectetur ac</a>
+  <a href="#" class="list-group-item list-group-item-action disabled">Vestibulum at eros</a>
 </div>
 {% endexample %}
 
-## Disabled items
-
-Add `.disabled` to a `.list-group-item` to gray it out to appear disabled.
-
 {% example html %}
 <div class="list-group">
-  <a href="#" class="list-group-item disabled">
+  <button type="button" class="list-group-item list-group-item-action active">
     Cras justo odio
-  </a>
-  <a href="#" class="list-group-item">Dapibus ac facilisis in</a>
-  <a href="#" class="list-group-item">Morbi leo risus</a>
-  <a href="#" class="list-group-item">Porta ac consectetur ac</a>
-  <a href="#" class="list-group-item">Vestibulum at eros</a>
+  </button>
+  <button type="button" class="list-group-item list-group-item-action">Dapibus ac facilisis in</button>
+  <button type="button" class="list-group-item list-group-item-action">Morbi leo risus</button>
+  <button type="button" class="list-group-item list-group-item-action">Porta ac consectetur ac</button>
+  <button type="button" class="list-group-item list-group-item-action disabled">Vestibulum at eros</button>
 </div>
 {% endexample %}
 
@@ -97,10 +97,10 @@ Use contextual classes to style list items, default or linked. Also includes `.a
 
 {% example html %}
 <div class="list-group">
-  <a href="#" class="list-group-item list-group-item-success">Dapibus ac facilisis in</a>
-  <a href="#" class="list-group-item list-group-item-info">Cras sit amet nibh libero</a>
-  <a href="#" class="list-group-item list-group-item-warning">Porta ac consectetur ac</a>
-  <a href="#" class="list-group-item list-group-item-danger">Vestibulum at eros</a>
+  <a href="#" class="list-group-item list-group-item-action list-group-item-success">Dapibus ac facilisis in</a>
+  <a href="#" class="list-group-item list-group-item-action list-group-item-info">Cras sit amet nibh libero</a>
+  <a href="#" class="list-group-item list-group-item-action list-group-item-warning">Porta ac consectetur ac</a>
+  <a href="#" class="list-group-item list-group-item-action list-group-item-danger">Vestibulum at eros</a>
 </div>
 {% endexample %}
 
@@ -110,16 +110,16 @@ Add nearly any HTML within, even for linked list groups like the one below.
 
 {% example html %}
 <div class="list-group">
-  <a href="#" class="list-group-item active">
-    <h4 class="list-group-item-heading">List group item heading</h4>
+  <a href="#" class="list-group-item list-group-item-action active">
+    <h5 class="list-group-item-heading">List group item heading</h5>
     <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
   </a>
-  <a href="#" class="list-group-item">
-    <h4 class="list-group-item-heading">List group item heading</h4>
+  <a href="#" class="list-group-item list-group-item-action">
+    <h5 class="list-group-item-heading">List group item heading</h5>
     <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
   </a>
-  <a href="#" class="list-group-item">
-    <h4 class="list-group-item-heading">List group item heading</h4>
+  <a href="#" class="list-group-item list-group-item-action">
+    <h5 class="list-group-item-heading">List group item heading</h5>
     <p class="list-group-item-text">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
   </a>
 </div>