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

diff --git a/docs/components/list-group.md b/docs/components/list-group.md
index 0d325498414b7b6a0e9d21a28cb12d224caad97f..c3d466d5fb8eac4c7c244a3f0b2cfff63909340f 100644 (file)
--- 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>

diff --git a/scss/_list-group.scss b/scss/_list-group.scss
index 3d74da4cbcab26a02cfb89711ab533fa828fba48..ba91d95f11a7422931b25b6860320b40bc7b0246 100644 (file)
--- a/scss/_list-group.scss
+++ b/scss/_list-group.scss
@@ -22,50 +22,15 @@
   background-color: $list-group-bg;
   border: $list-group-border-width solid $list-group-border-color;
 
-  // Round the first and last items
   &:first-child {
     @include border-top-radius($list-group-border-radius);
   }
+
   &:last-child {
     margin-bottom: 0;
     @include border-bottom-radius($list-group-border-radius);
   }
-}
-
-.list-group-flush {
-  .list-group-item {
-    border-radius: 0;
-  }
-}
-
-
-// Interactive list items
-//
-// Use anchor or button elements instead of `li`s or `div`s to create interactive
-// list items. Includes an extra `.active` modifier class for selected items.
-
-// scss-lint:disable QualifyingElement
-a.list-group-item,
-button.list-group-item {
-  width: 100%;
-  color: $list-group-link-color;
-  text-align: inherit;
-
-  .list-group-item-heading {
-    color: $list-group-link-heading-color;
-  }
-
-  // Hover state
-  @include hover-focus {
-    color: $list-group-link-hover-color;
-    text-decoration: none;
-    background-color: $list-group-hover-bg;
-  }
-}
-// scss-lint:enable QualifyingElement
 
-.list-group-item {
-  // Disabled state
   &.disabled {
     @include plain-hover-focus {
       color: $list-group-disabled-color;
@@ -82,11 +47,11 @@ button.list-group-item {
     }
   }
 
-  // Active class on item itself, not parent
   &.active {
     @include plain-hover-focus {
       z-index: 2; // Place active items above their siblings for proper border styling
       color: $list-group-active-color;
+      text-decoration: none; // Repeat here because it inherits global a:hover otherwise
       background-color: $list-group-active-bg;
       border-color: $list-group-active-border;
 
@@ -103,6 +68,35 @@ button.list-group-item {
   }
 }
 
+.list-group-flush {
+  .list-group-item {
+    border-radius: 0;
+  }
+}
+
+
+// Interactive list items
+//
+// Use anchor or button elements instead of `li`s or `div`s to create interactive
+// list items. Includes an extra `.active` modifier class for selected items.
+
+.list-group-item-action {
+  width: 100%; // For `<button>`s (anchors become 100% by default though)
+  color: $list-group-link-color;
+  text-align: inherit; // For `<button>`s (anchors inherit)
+
+  .list-group-item-heading {
+    color: $list-group-link-heading-color;
+  }
+
+  // Hover state
+  @include hover-focus {
+    color: $list-group-link-hover-color;
+    text-decoration: none;
+    background-color: $list-group-hover-bg;
+  }
+}
+
 
 // Contextual variants
 //