chore(icons): updates to CSS animations (#4945)

Co-authored-by: Jacob Müller

Author: tmorehouse

src/_variables.scss

@@ -61,10 +61,15 @@ $b-custom-file-height-inner-sm: calc(
 
 // --- Icons ---
 
+$b-icon-vertical-offset: -0.15em;
+
 // Animations
 $b-icon-animation-spin-duration: 2s !default;
-$b-icon-animation-pulse-duration: 1s !default;
+$b-icon-animation-spin-reverse-duration: $b-icon-animation-spin-duration !default;
+$b-icon-animation-spin-pulse-duration: 1s !default;
+$b-icon-animation-spin-reverse-pulse-duration: $b-icon-animation-spin-pulse-duration !default;
 $b-icon-animation-cylon-duration: 0.75s !default;
+$b-icon-animation-cylon-vertical-duration: $b-icon-animation-cylon-duration !default;
 
 // --- Tables ---
 

src/icons/README.md

@@ -432,32 +432,53 @@ affected. If you need to shift the border/background with the icon, use Bootstra
 
 <span class="badge badge-info small">v2.7.0+</span>
 
-BootstrapVue includes two spinning animation options for icons: `spin` and `pulse`. Both animations
-spin the icon clockwise, but pulse uses a stepped spin. A third animation called `cylon` is also
-provided.
+BootstrapVue includes the following built-in animations for icons:
 
-To use the spin animation, set the `animation` prop to one of the animation names `'spin'`,
-`'pulse'` or `'cylon'`.
+- `'spin'` smoothly spins the icon clockwise
+- `'spin-reverse'` smoothly spins the icon counter-clockwise
+- `'spin-pulse'` spins the icon clockwise, but in a pulsed step style
+- `'spin-reverse-pulse'` spins the icon counter-clockwise, but in a pulsed step style
+- `'cylon'` slides the icon left-right
+- '`cylon-vertical'` slides the icon up-down
+
+To use the animation, set the `animation` prop to one of the animation names above.
 
 ```html
 <template>
-  <div>
-    <p>Spinning animation:</p>
-    <b-icon icon="arrow-clockwise" animation="spin" font-scale="4"></b-icon>
-
-    <p class="mt-3">Pulsing animation:</p>
-    <b-icon icon="arrow-clockwise" animation="pulse" font-scale="4"></b-icon>
-
-    <p class="mt-3">Cylon animation:</p>
-    <b-icon icon="three-dots" animation="cylon" font-scale="4"></b-icon>
+  <b-row class="text-md-center">
+    <b-col md="6" class="mb-3">
+      <p>Spinning animation:</p>
+      <b-icon icon="arrow-clockwise" animation="spin" font-scale="4"></b-icon>
+    </b-col>
+    <b-col md="6" class="mb-3">
+      <p>Reverse spinning animation:</p>
+      <b-icon icon="arrow-counterclockwise" animation="spin-reverse" font-scale="4"></b-icon>
+    </b-col>
+    <b-col md="6" class="mb-3">
+      <p>Pulsing spin animation:</p>
+      <b-icon icon="arrow-clockwise" animation="spin-pulse" font-scale="4"></b-icon>
+    </b-col>
+    <b-col md="6" class="mb-3">
+      <p>Reversed pulsing spin animation:</p>
+      <b-icon icon="arrow-counterclockwise" animation="spin-reverse-pulse" font-scale="4"></b-icon>
+    </b-col>
+    <b-col md="6" class="mb-3">
+      <p>Cylon animation:</p>
+      <b-icon icon="three-dots" animation="cylon" font-scale="4"></b-icon>
+    </b-col>
+    <b-col md="6" class="mb-3">
+      <p>Vertical cylon animation:</p>
+      <b-icon icon="three-dots-vertical" animation="cylon-vertical" font-scale="4"></b-icon>
+    </b-col>
   </div>
 </template>
 
-<!-- b-icon-spin-aminations.vue -->
+<!-- b-icon-aminations.vue -->
 ```
 
-Note with the `cylon` animation, the left-right movement extends past the icon's bounding box by
-`25%`, so you may need to adjust padding or margins to compensate for your use case.
+Note with the `cylon` animations, the left-right movement (or up-down movement) extends past the
+icon's bounding box by `+/- 25%`, so you may need to adjust padding or margins to compensate for
+your use case.
 
 As the animations are CSS based, they are applied _after_ any SVG transforms have taken place:
 
@@ -468,7 +489,7 @@ As the animations are CSS based, they are applied _after_ any SVG transforms hav
   </div>
 </template>
 
-<!-- b-icon-spin-aminations-transforms.vue -->
+<!-- b-icon-aminations-transforms.vue -->
 ```
 
 The BootstrapVue defined icon animation effects require BootstrapVue's custom CSS. The `animation`
@@ -538,20 +559,66 @@ individual icons (`<b-icon>` or `<b-icon-{icon-name}>`) to create complex icons:
   </div>
 </template>
 
-<!-- icons-stacking.vue -->
+<!-- b-iconsstack.vue -->
 ```
 
-`<b-iconstack>` supports the same `variant`, `font-size`, and transformation props available on
-individual icons.
+`<b-iconstack>` supports the same `variant`, `font-size`, `animation` and transformation props
+available on individual icons.
 
 Stacked icon notes:
 
 - Remember to set the `stacked` prop on the inner icon components
 - The `font-scale` prop cannot be used on the inner icon components
 - The `width` and `height` attributes cannot be applied to the inner icon components
 - Stacked icons **cannot** be stacked inside another `<b-iconstack>`
-- Note the animation props on the child icons will have no effect, however you _can_ use the
-  animation props on the `<b-iconstack>` component.
+
+### Stacked icon animation
+
+The `<b-iconstack>` component supports the same animations as individual icons:
+
+```html
+<template>
+  <div>
+    <b-iconstack font-scale="5" animation="spin">
+      <b-icon stacked icon="camera" variant="info" scale="0.75" shift-v="-0.25"></b-icon>
+      <b-icon stacked icon="circle-slash" variant="danger"></b-icon>
+    </b-iconstack>
+  </div>
+</template>
+
+<!-- b-iconstack-animation.vue -->
+```
+
+Individual icons within the icon stack can also be animated (except on IE 11):
+
+```html
+<template>
+  <div>
+    <b-iconstack font-scale="5" animation="cylon">
+      <b-icon
+        stacked
+        icon="camera"
+        animation="spin"
+        variant="info"
+        scale="0.75"
+        shift-v="-0.25"
+      ></b-icon>
+      <b-icon stacked icon="circle-slash" variant="danger"></b-icon>
+    </b-iconstack>
+  </div>
+</template>
+
+<!-- b-iconstack-animation-child-icons.vue -->
+```
+
+**Notes:**
+
+- IE 11 does not support animation of child elements within an SVG, hence only the `<b-iconstack>`
+  component can be animated. The child icon(s) animation will not be visible to IE 11 users.
+- The BootstrapVue defined animation effects of this component is dependent on the
+  `prefers-reduced-motion` media query. See the
+  [reduced motion section of our accessibility documentation](/docs/reference/accessibility) for
+  additional details.
 
 ## Using in components
 

src/icons/_icons.scss

@@ -5,28 +5,68 @@
     overflow: visible;
     // The following is required to compensate for alignment
     // issues with the Bootstrap Icons alpha implementation
-    // And might be able to remove in future version of bootstrap-icons
-    // Perhaps this values should be SASS variables?
-    vertical-align: -0.15em;
+    // TODO: Is this "hack" still required?
+    vertical-align: $b-icon-vertical-offset;
   }
 
-  &.b-icon-animation-spin {
-    animation: $b-icon-animation-spin-duration infinite linear b-icon-animation-spin;
+  &.b-icon-animation-spin,
+  &.b-iconstack .b-icon-animation-spin > g {
+    transform-origin: center;
+    animation: $b-icon-animation-spin-duration infinite linear normal b-icon-animation-spin;
+
+    @media (prefers-reduced-motion: reduce) {
+      animation: none;
+    }
+  }
+
+  &.b-icon-animation-spin-reverse,
+  &.b-iconstack .b-icon-animation-spin-reverse > g {
+    transform-origin: center;
+    animation: $b-icon-animation-spin-reverse-duration infinite linear reverse b-icon-animation-spin;
+
     @media (prefers-reduced-motion: reduce) {
       animation: none;
     }
   }
 
-  &.b-icon-animation-pulse {
-    animation: $b-icon-animation-pulse-duration infinite steps(8) b-icon-animation-spin;
+  &.b-icon-animation-spin-pulse,
+  &.b-iconstack .b-icon-animation-spin-pulse > g {
+    transform-origin: center;
+    animation: $b-icon-animation-spin-pulse-duration infinite steps(8) normal b-icon-animation-spin;
+
+    @media (prefers-reduced-motion: reduce) {
+      animation: none;
+    }
+  }
+
+  &.b-icon-animation-spin-reverse-pulse,
+  &.b-iconstack .b-icon-animation-spin-reverse-pulse > g {
+    transform-origin: center;
+    animation: $b-icon-animation-spin-reverse-pulse-duration infinite steps(8) reverse
+      b-icon-animation-spin;
+
     @media (prefers-reduced-motion: reduce) {
       animation: none;
     }
   }
 
-  &.b-icon-animation-cylon {
+  &.b-icon-animation-cylon,
+  &.b-iconstack .b-icon-animation-cylon > g {
+    transform-origin: center;
     animation: $b-icon-animation-cylon-duration infinite ease-in-out alternate
       b-icon-animation-cylon;
+
+    @media (prefers-reduced-motion: reduce) {
+      animation: none;
+    }
+  }
+
+  &.b-icon-animation-cylon-vertical,
+  &.b-iconstack .b-icon-animation-cylon-vertical > g {
+    transform-origin: center;
+    animation: $b-icon-animation-cylon-vertical-duration infinite ease-in-out alternate
+      b-icon-animation-cylon-vertical;
+
     @media (prefers-reduced-motion: reduce) {
       animation: none;
     }
@@ -52,6 +92,15 @@
   }
 }
 
+@keyframes b-icon-animation-cylon-vertical {
+  0% {
+    transform: translateY(25%);
+  }
+  100% {
+    transform: translateY(-25%);
+  }
+}
+
 // Make icons slightly larger in buttons, nav-links, dropdowns, and input-group-text
 .btn,
 .nav-link,