Tidy up content progress use case

Author: birtles

Overview.bs

@@ -263,50 +263,49 @@ union.timeline = new ScrollTimeline({
 
 ### The content progress bar ### {#content-progress-bar-usecase}
 
-There is much content that using to scroll linked animations.
-Here's one of these animation content, this content has a long article.
-And this content has a progress bar which indicates the current position of the article.
-
-If we scroll the content, this progress bar increased / decreased.
+Another common example of an animation that tracks scroll position is a
+progress bar that is used to indicate the reader's position in a long
+article.
 
 <figure>
 <img src="img/usecase3-2.svg" width="600"
-alt="Use case 3-2: Scroll based styling">
+alt="Use case: Scroll based styling">
  <figcaption>
-  Use case 3-2: Content progress bar.<br>
-  The left figure is before scroll, the progress bar is not displayed.<br>
-  The right figure is after scroll, the progress bar advanced.
+  Content progress bar.<br>
+  The left figure shows the initial state before scrolling.<br>
+  The right figure shows the progress bar is half-filled in since the
+  user has scrolled half way through the article.
  </figcaption>
 </figure>
 
-Usually, we won't need to this progress bar, because the scroll bar indicated the progress. But some content will want to hide the scroll bar, like this content.
+Typically, the scroll bar provides this visual indication but
+applications may wish to hide the scroll bar for aesthetic or useability
+reasons.
+
+Using the 'animation-timeline' property, this example could be written
+as follows:
 
-If we use animation-timeline, this example code will be as follow.
 <pre class='lang-css'>
-@keyframes progressAnimation {
-  from {
-    width: 0px;
-  }
-  to {
-    width: 500px;
-  }
+@keyframes progress {
+  to { width: 100%; }
 }
-div#progress {
-  width: 50%;
+#progress {
+  width: 0px;
   height: 30px;
   background: red;
-  animation: 1s linear progressAnimation;
-  animation-trigger: scroll(element(#scrollableContainer), vertical);
+  animation: progress 1s linear;
+  animation-trigger: scroll(element(#body));
   animation-timeline: scroll();
 }
 </pre>
 
 If we use this API for this case, the example code will be as follow:
+
 <pre class='lang-javascript'>
-  var animation = div.getAnimations()[0];
+  var animation = div.animate({ width: '100%' }, 1000);
   animation.timeline = new ScrollTimeline(
-    { trigger: new ScrollTrigger({ scrollSource: scrollableElement,
-                                   scrollOffset: '0px'}) });
+    { trigger: new ScrollTrigger({ scrollOffset: '0px' }) }
+  );
 </pre>
 
 ## Combination scroll and time-base animations ## {#combination-scroll-and-time-base-animations-usecase}

img/usecase3-2.svg

@@ -552,38 +552,36 @@ <h4 class="heading settled" data-level="2.3.1" id="scrollable-animation-usecase"
 <span class="p">}</span><span class="p">)</span><span class="p">;</span>
 </pre>
    <h4 class="heading settled" data-level="2.3.2" id="content-progress-bar-usecase"><span class="secno">2.3.2. </span><span class="content">The content progress bar</span><a class="self-link" href="#content-progress-bar-usecase"></a></h4>
-   <p>There is much content that using to scroll linked animations.
-Here’s one of these animation content, this content has a long article.
-And this content has a progress bar which indicates the current position of the article.</p>
-   <p>If we scroll the content, this progress bar increased / decreased.</p>
+   <p>Another common example of an animation that tracks scroll position is a
+progress bar that is used to indicate the reader’s position in a long
+article.</p>
    <figure>
-     <img alt="Use case 3-2: Scroll based styling" src="img/usecase3-2.svg" width="600"> 
-    <figcaption> Use case 3-2: Content progress bar.<br> The left figure is before scroll, the progress bar is not displayed.<br> The right figure is after scroll, the progress bar advanced. </figcaption>
+     <img alt="Use case: Scroll based styling" src="img/usecase3-2.svg" width="600"> 
+    <figcaption> Content progress bar.<br> The left figure shows the initial state before scrolling.<br> The right figure shows the progress bar is half-filled in since the
+  user has scrolled half way through the article. </figcaption>
    </figure>
-   <p>Usually, we won’t need to this progress bar, because the scroll bar indicated the progress. But some content will want to hide the scroll bar, like this content.</p>
-   <p>If we use animation-timeline, this example code will be as follow.</p>
-<pre class="lang-css highlight"><span class="n">@keyframes</span> progressAnimation <span class="p">{</span>
-  <span class="nt">from </span><span class="p">{</span>
-    <span class="k">width</span><span class="p">:</span> <span class="m">0</span><span class="l">px</span><span class="p">;</span>
-  <span class="p">}</span>
-  <span class="nt">to </span><span class="p">{</span>
-    <span class="k">width</span><span class="p">:</span> <span class="m">500</span><span class="l">px</span><span class="p">;</span>
-  <span class="p">}</span>
-<span class="p">}</span>
-<span class="nt">div#progress </span><span class="p">{</span>
-  <span class="k">width</span><span class="p">:</span> <span class="m">5</span><span class="l">0</span>%;
+   <p>Typically, the scroll bar provides this visual indication but
+applications may wish to hide the scroll bar for aesthetic or useability
+reasons.</p>
+   <p>Using the <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-1">animation-timeline</a> property, this example could be written
+as follows:</p>
+<pre class="lang-css highlight"><span class="n">@keyframes</span> progress <span class="p">{</span>
+  <span class="nt">to </span><span class="p">{</span> <span class="k">width</span><span class="p">:</span> <span class="m">10</span><span class="l">0</span>%; }
+}
+#progress {
+  width: 0px;
   height: 30px;
   background: red;
-  animation: 1s linear progressAnimation;
-  animation-trigger: scroll(element(#scrollableContainer), vertical);
+  animation: progress 1s linear;
+  animation-trigger: scroll(element(#body));
   animation-timeline: scroll();
 }
 </pre>
    <p>If we use this API for this case, the example code will be as follow:</p>
-<pre class="lang-javascript highlight"><span class="kd">var</span> animation <span class="o">=</span> div<span class="p">.</span>getAnimations<span class="p">(</span><span class="p">)</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="p">;</span>
+<pre class="lang-javascript highlight"><span class="kd">var</span> animation <span class="o">=</span> div<span class="p">.</span>animate<span class="p">(</span><span class="p">{</span> width<span class="o">:</span> <span class="s1">'100%'</span> <span class="p">}</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)</span><span class="p">;</span>
 animation<span class="p">.</span>timeline <span class="o">=</span> <span class="k">new</span> ScrollTimeline<span class="p">(</span>
-  <span class="p">{</span> trigger<span class="o">:</span> <span class="k">new</span> ScrollTrigger<span class="p">(</span><span class="p">{</span> scrollSource<span class="o">:</span> scrollableElement<span class="p">,</span>
-                                 scrollOffset<span class="o">:</span> <span class="s1">'0px'</span><span class="p">}</span><span class="p">)</span> <span class="p">}</span><span class="p">)</span><span class="p">;</span>
+  <span class="p">{</span> trigger<span class="o">:</span> <span class="k">new</span> ScrollTrigger<span class="p">(</span><span class="p">{</span> scrollOffset<span class="o">:</span> <span class="s1">'0px'</span> <span class="p">}</span><span class="p">)</span> <span class="p">}</span>
+<span class="p">)</span><span class="p">;</span>
 </pre>
    <h3 class="heading settled" data-level="2.4" id="combination-scroll-and-time-base-animations-usecase"><span class="secno">2.4. </span><span class="content">Combination scroll and time-base animations</span><a class="self-link" href="#combination-scroll-and-time-base-animations-usecase"></a></h3>
    <h4 class="heading settled" data-level="2.4.1" id="movie-show-case-usecase"><span class="secno">2.4.1. </span><span class="content">The photo viewer</span><a class="self-link" href="#movie-show-case-usecase"></a></h4>
@@ -1092,9 +1090,9 @@ <h4 class="heading settled" data-level="4.1.2" id="current-time-algorithm"><span
       <blockquote> <code>(<var>current scroll offset</var> - <code class="idl"><a data-link-type="idl" href="#dom-scrolltrigger-scrolloffset" id="ref-for-dom-scrolltrigger-scrolloffset-13">scrollOffset</a></code>) / (<code class="idl"><a data-link-type="idl" href="#dom-scrolltrigger-endscrolloffset" id="ref-for-dom-scrolltrigger-endscrolloffset-12">endScrollOffset</a></code> - <code class="idl"><a data-link-type="idl" href="#dom-scrolltrigger-scrolloffset" id="ref-for-dom-scrolltrigger-scrolloffset-14">scrollOffset</a></code>) × <a data-link-type="dfn" href="#effective-time-range" id="ref-for-effective-time-range-8">effective time range</a></code> </blockquote>
     </ol>
    </div>
-   <h3 class="heading settled" data-level="4.2" id="animation-timeline"><span class="secno">4.2. </span><span class="content">The <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-1">animation-timeline</a> property</span><a class="self-link" href="#animation-timeline"></a></h3>
+   <h3 class="heading settled" data-level="4.2" id="animation-timeline"><span class="secno">4.2. </span><span class="content">The <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-2">animation-timeline</a> property</span><a class="self-link" href="#animation-timeline"></a></h3>
    <p>A <code class="idl"><a data-link-type="idl" href="#scrolltimeline" id="ref-for-scrolltimeline-8">ScrollTimeline</a></code> may be applied to a CSS Animation <a data-link-type="biblio" href="#biblio-css3-animations">[CSS3-ANIMATIONS]</a> using
-the <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-2">animation-timeline</a> property.</p>
+the <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-3">animation-timeline</a> property.</p>
    <table class="def propdef" data-link-for-hint="animation-timeline">
     <tbody>
      <tr>
@@ -1129,7 +1127,7 @@ <h3 class="heading settled" data-level="4.2" id="animation-timeline"><span class
       <td>no
    </table>
    <p><dfn class="dfn-paneled css" data-dfn-type="type" data-export="" id="typedef-single-animation-timeline">&lt;single-animation-timeline></dfn> = auto | scroll([<a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-values-4/#time-value" title="Expands to: s | ms">&lt;time></a> [, <a class="production css" data-link-type="type" href="https://drafts.csswg.org/css-animations-1/#typedef-single-animation-fill-mode">&lt;single-animation-fill-mode></a>]])</p>
-   <p>The <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-3">animation-timeline</a> property is similar to properties like <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-animations-1/#propdef-animation-duration">animation-duration</a> and <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-animations-1/#propdef-animation-timing-function">animation-timing-function</a> in that it can have one or more values, each one imparting 
+   <p>The <a class="property" data-link-type="propdesc" href="#propdef-animation-timeline" id="ref-for-propdef-animation-timeline-4">animation-timeline</a> property is similar to properties like <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-animations-1/#propdef-animation-duration">animation-duration</a> and <a class="property" data-link-type="propdesc" href="https://drafts.csswg.org/css-animations-1/#propdef-animation-timing-function">animation-timing-function</a> in that it can have one or more values, each one imparting 
 additional behavior to a corresponding <a data-link-type="dfn" href="https://w3c.github.io/web-animations/#concept-animation">animation</a> on the 
 element, with the timelines matched up with animations as described <a href="https://drafts.csswg.org/css-animations-1/#animation-name">here</a>.</p>
    <p>Each value has type <a class="production css" data-link-type="type" href="#typedef-single-animation-timeline" id="ref-for-typedef-single-animation-timeline-2">&lt;single-animation-timeline></a>, whose possible values have the
@@ -1932,7 +1930,8 @@ <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content
   <aside class="dfn-panel" data-for="propdef-animation-timeline">
    <b><a href="#propdef-animation-timeline">#propdef-animation-timeline</a></b><b>Referenced in:</b>
    <ul>
-    <li><a href="#ref-for-propdef-animation-timeline-1">4.2. The animation-timeline property</a> <a href="#ref-for-propdef-animation-timeline-2">(2)</a> <a href="#ref-for-propdef-animation-timeline-3">(3)</a>
+    <li><a href="#ref-for-propdef-animation-timeline-1">2.3.2. The content progress bar</a>
+    <li><a href="#ref-for-propdef-animation-timeline-2">4.2. The animation-timeline property</a> <a href="#ref-for-propdef-animation-timeline-3">(2)</a> <a href="#ref-for-propdef-animation-timeline-4">(3)</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="typedef-single-animation-timeline">