Merge pull request #108 from ncoden/fix/safari-mui-series-pause-97-2

feat: change mui-series pause behavior & add `.is-paused` for Safari support #97

docs/animations.md

@@ -97,7 +97,7 @@ To add a delay to the start of the queue, add the length in seconds to the `mui-
 }
 ```
 
-To trigger the queue, add the class `.is-animating` to the parent container. This can be done easily in JavaScript:
+**To play the queue**, add the class `.is-animating` to the parent container. This can be done easily in JavaScript:
 
 ```js
 // Plain JavaScript (IE10+)
@@ -107,6 +107,10 @@ document.querySelector('.animation-wrapper').classList.add('is-animating');
 $('.animation-wrapper').addClass('is-animating');
 ```
 
+**To pause the queue**, add `.is-paused` to the parent container (without removing `.is-animating`). For macOS Safari to correctly play pause the animation, `.is-paused` must not be set by default but only after `.is-animating`. See https://git.io/motion-ui-97.
+
+**To reset the queue** to its initial state, remove `.is-animating` and `.is-paused` from the parent container. The queue can then be started again.
+
 ## Use with WOW.js
 
 Motion UI can be paired with WOW.js to animate elements in as the page scrolls. [Learn more about WOW.js integration.](wow.md);

docs/configuration.md

@@ -55,6 +55,7 @@ $motion-ui-settings: (
   hinge-and-fade: true,
   scale-and-fade: true,
   spin-and-fade: true,
+  pause-queue-class: 'is-paused',
   activate-queue-class: 'is-animating'
 );
 ```

docs/src/animations.md

@@ -85,11 +85,11 @@ Begin your series with the `mui-series()` mixin. Inside this mixin, attach anima
 ```scss
 @include mui-series {
   // 2 second shake
-  .shake    { @include mui-queue(2s, 0s, shake); }
+  .my-queue-shake     { @include mui-queue(2s, 0s, shake); }
   // 1 second spin with a 2 second pause
-  .spin     { @include mui-queue(1s, 2s, spin); }
+  .my-queue-spin      { @include mui-queue(1s, 2s, spin); }
   // 1 second zoom and fade
-  .fade-zoom { @include mui-queue(1s, 0s, fade, zoom); }
+  .my-queue-fade-zoom { @include mui-queue(1s, 0s, fade, zoom); }
 }
 ```
 
@@ -98,13 +98,13 @@ To add a delay to the start of the queue, add the length in seconds to the `mui-
 ```scss
 // 2 second delay before the first shake
 @include mui-series(2s) {
-  .shake  { @include mui-queue(2s, 0s, shake()); }
-  .spin   { @include mui-queue(1s, 2s, spin()); }
-  .wiggle { @include mui-queue(wiggle); }
+  .my-queue-shake     { @include mui-queue(2s, 0s, shake()); }
+  .my-queue-spin      { @include mui-queue(1s, 2s, spin()); }
+  .my-queue-wiggle    { @include mui-queue(wiggle); }
 }
 ```
 
-To trigger the queue, add the class `.is-animating` to the parent container. This can be done easily in JavaScript:
+**To play the queue**, add the class `.is-animating` to the parent container. This can be done easily in JavaScript:
 
 ```js
 // Plain JavaScript (IE10+)
@@ -114,6 +114,10 @@ document.querySelector('.animation-wrapper').classList.add('is-animating');
 $('.animation-wrapper').addClass('is-animating');
 ```
 
+**To pause the queue**, add `.is-paused` to the parent container (without removing `.is-animating`). For macOS Safari to correctly play pause the animation, `.is-paused` must not be set by default but only after `.is-animating`. See https://git.io/motion-ui-97.
+
+**To reset the queue** to its initial state, remove `.is-animating` and `.is-paused` from the parent container. The queue can then be started again.
+
 ## Use with WOW.js
 
 Motion UI can be paired with WOW.js to animate elements in as the page scrolls. [Learn more about WOW.js integration.](wow.md);

docs/src/configuration.md

@@ -58,6 +58,7 @@ $motion-ui-settings: (
   hinge-and-fade: true,
   scale-and-fade: true,
   spin-and-fade: true,
+  pause-queue-class: 'is-paused',
   activate-queue-class: 'is-animating'
 );
 ```

src/_settings.scss

@@ -57,5 +57,6 @@ $motion-ui-settings: (
   hinge-and-fade: true,
   scale-and-fade: true,
   spin-and-fade: true,
+  pause-queue-class: 'is-paused',
   activate-queue-class: 'is-animating',
 ) !default;

src/util/_series.scss

@@ -1,16 +1,5 @@
 $-mui-queue: ();
 
-/// Pauses the animation on an element by default, and then plays it when an active class is added to a parent. Also sets the fill mode of the animation to `both`. This pauses the element at the first frame of the animation, and holds it in place at the end.
-/// @access private
-%animated-element {
-  animation-play-state: paused;
-  animation-fill-mode: both;
-
-  .#{map-get($motion-ui-settings, activate-queue-class)} & {
-    animation-play-state: running;
-  }
-}
-
 /// Creates a new animation queue.
 /// @param {Duration} $delay [0s] - Delay in seconds or milliseconds to place at the front of the animation queue.
 @mixin mui-series($delay: 0s) {
@@ -46,9 +35,23 @@ $-mui-queue: ();
   $item: ($duration, $gap);
   $-mui-queue: append($-mui-queue, $item) !global;
 
-  // CSS output
-  @extend %animated-element;
-  @include mui-animation($kf);
-  animation-duration: $duration;
-  animation-delay: $actual-delay;
+  // --- CSS output ---
+  // Initial properties
+  @include -mui-keyframe-get($kf, 0);
+  animation-fill-mode: both;
+
+  // Start the animation
+  .#{map-get($motion-ui-settings, activate-queue-class)} & {
+    @include mui-animation($kf);
+    animation-delay: $actual-delay;
+    animation-duration: $duration;
+  }
+
+  // Pause the animation.
+  // For macOS Safari to play it correctly, `animation-play-state`
+  // must not be `paused` before the animation start.
+  // See https://git.io/motion-ui-97
+  .#{map-get($motion-ui-settings, pause-queue-class)} & {
+    animation-play-state: paused;
+  }
 }