improve sl-animation

docs/components/animation.md

@@ -4,14 +4,14 @@
 
 Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
 
-To animate an element, wrap it in `<sl-animation>` and set a `name` and `duration`. Refer to the [properties table](#properties) for additional options.
+To animate an element, wrap it in `<sl-animation>` and set an animation `name`. The animation not start until you add the `play` attribute. Refer to the [properties table](#properties) for a list of all animation options.
 
 ```html preview
 <div class="animation-overview">
-  <sl-animation name="bounce" duration="2000"><div class="box"></div></sl-animation>
-  <sl-animation name="jello" duration="2000"><div class="box"></div></sl-animation>
-  <sl-animation name="heartBeat" duration="2000"><div class="box"></div></sl-animation>
-  <sl-animation name="flip" duration="2000"><div class="box"></div></sl-animation>
+  <sl-animation name="bounce" duration="2000" play><div class="box"></div></sl-animation>
+  <sl-animation name="jello" duration="2000" play><div class="box"></div></sl-animation>
+  <sl-animation name="heartBeat" duration="2000" play><div class="box"></div></sl-animation>
+  <sl-animation name="flip" duration="2000" play><div class="box"></div></sl-animation>
 </div>
 
 <style>
@@ -25,7 +25,7 @@ To animate an element, wrap it in `<sl-animation>` and set a `name` and `duratio
 </style>
 ```
 
-?> The animation will be applied only to the first child element found in `<sl-animation>`.
+?> The animation will only be applied to the first child element found in `<sl-animation>`.
 
 ## Examples
 
@@ -35,7 +35,7 @@ This example demonstrates all of the baked-in animations and easings. Animations
 
 ```html preview
 <div class="animation-sandbox">
-  <sl-animation name="bounce" easing="ease-in-out" duration="2000">
+  <sl-animation name="bounce" easing="ease-in-out" duration="2000" play>
     <div class="box"></div>
   </sl-animation>
 
@@ -115,11 +115,10 @@ Use an [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/
   const observer = new IntersectionObserver(entries => {
     if (entries[0].isIntersecting) {
       // Start the animation when the box enters the viewport
-      animation.pause = null;
+      animation.play = true;
     } else {
-      // Reset the animation when the box leaves the viewport
-      animation.pause = true;
-      animation.setCurrentTime(0);
+      animation.play = false;
+      animation.currentTime = 0;
     }
   });
   observer.observe(box);
@@ -141,7 +140,7 @@ Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/
 
 ```html preview
 <div class="animation-keyframes">
-  <sl-animation easing="ease-in-out" duration="2000">
+  <sl-animation easing="ease-in-out" duration="2000" play>
     <div class="box"></div>
   </sl-animation>
 </div>
@@ -175,4 +174,26 @@ Supply your own [keyframe formats](https://developer.mozilla.org/en-US/docs/Web/
 </style>
 ```
 
+### Playing Animations on Demand
+
+Animations won't play until you apply the `play` attribute. You can omit it initially, then apply it on demand such as after a user interaction. In this example, the button will animate once every time the button is clicked.
+
+```html preview
+<div class="animation-form">
+  <sl-animation name="rubberBand" duration="1000" iterations="1">
+    <sl-button type="primary">Click me</sl-button>
+  </sl-animation>
+</div>
+
+<script>
+  const container = document.querySelector('.animation-form');
+  const animation = container.querySelector('sl-animation');
+  const button = container.querySelector('sl-button');
+
+  button.addEventListener('click', () => {
+    animation.play = true;
+  });
+</script>
+```
+
 [component-metadata:sl-animation]

docs/resources/changelog.md

@@ -6,6 +6,16 @@ Components with the <sl-badge type="warning" pill>Experimental</sl-badge> badge
 
 _During the beta period, these restrictions may be relaxed in the event of a mission-critical bug._ 🐛
 
+## 2.0.0-beta.46
+
+This release improves the developer experience of `<sl-animation>`. Previously, an animation was assumed to be playing unless the `pause` attribute was set. This behavior has been reversed and `pause` has been removed. Now, animations will not play until the new `play` attribute is applied.
+
+This is a lot more intuitive and makes it easier to activate animations imperatively. In addition, the `play` attribute is automatically removed automatically when the animation finishes or cancels, making it easier to restart finite animations. Lastly, the animation's timing is now accessible through the new `currentTime` property instead of `getCurrentTime()` and `setCurrentTime()`.
+
+- 🚨 BREAKING: removed the `pause` prop from `sl-animation` (use the `play` prop to start and stop the animation instead)
+- 🚨 BREAKING: removed `getCurrentTime()` and `setCurrentTime()` from `sl-animation` (use the `currentTime` property instead)
+- Added `currentTime` to `sl-animation` to control the current time without methods
+
 ## 2.0.0-beta.45
 
 This release changes the way component metadata is generated. Previously, the project used TypeDoc to analyze components and generate a very large file with type data. The data was then parsed and converted to an easier-to-consume file called `metadata.json`. Alas, TypeDoc is expensive to run and the metadata format wasn't standard.