Feature: Add carousel fade option (#22958)

* Move helpful code comments

* Add .carousel-fade option to Sass

* Document example of the fade carousel

* more logical warning of the .active class on carousel items

1 files changed, 46 insertions, 2 deletions

diff --git a/scss/_carousel.scss b/scss/_carousel.scss
index 72a503445b..3b048e0d1a 100644
--- a/scss/_carousel.scss
+++ b/scss/_carousel.scss
@@ -1,4 +1,13 @@
-// Wrapper for the slide container and indicators
+// Notes on the classes:
+//
+// 1. The .carousel-item-left and .carousel-item-right is used to indicate where
+//    the active slide is heading.
+// 2. .active.carousel-item is the current slide.
+// 3. .active.carousel-item-left and .active.carousel-item-right is the current
+//    slide in it's in-transition state. Only one of these occur at a time.
+// 4. .carousel-item-next.carousel-item-left and .carousel-item-prev.carousel-item-right
+//    is the upcoming slide in transition.
+
 .carousel {
   position: relative;
 }
@@ -31,7 +40,6 @@
   top: 0;
 }
 
-// CSS3 transforms when supported by the browser
 .carousel-item-next.carousel-item-left,
 .carousel-item-prev.carousel-item-right {
   transform: translateX(0);
@@ -61,6 +69,42 @@
 
 
 //
+// Alternate transitions
+//
+
+.carousel-fade {
+  .carousel-item {
+    opacity: 0;
+    transition-duration: .6s;
+    transition-property: opacity;
+  }
+
+  .carousel-item.active,
+  .carousel-item-next.carousel-item-left,
+  .carousel-item-prev.carousel-item-right {
+    opacity: 1;
+  }
+
+  .active.carousel-item-left,
+  .active.carousel-item-right {
+    opacity: 0;
+  }
+
+  .carousel-item-next,
+  .carousel-item-prev,
+  .carousel-item.active,
+  .active.carousel-item-left,
+  .active.carousel-item-prev {
+    transform: translateX(0);
+
+    @supports (transform-style: preserve-3d) {
+      transform: translate3d(0, 0, 0);
+    }
+  }
+}
+
+
+//
 // Left/right controls for nav
 //