[scroll-animations-1] Move remaining trigger text out of spec (#4913)

The specification no longer has a trigger API. Now that we have a
explainer, the explanation as to why we made this design decision
belongs there.

Also removed empty trigger examples from specification and updated
usecases to mention that trigger usecases are deferred.

Author: majido

scroll-animations-1/EXPLAINER.md

@@ -31,12 +31,13 @@ Scroll-linked animated effect are common in web design:
 
 
 Currently the only way to achieve them is to respond to scroll events on the main thread. This
-means that these animations have to run on the main thread. There are two main problems with this:
+means that these animations have to run on the main thread which leads to two main problems:
 1. Modern browsers perform scrolling on separate thread/process so scroll events are delivered
-asynchronously
+   asynchronously.
 2. Main thread animations are subject to jank. 
 
-Creating performant scroll-linked animation can be impossible or [very
+These make creating performant scroll-linked animations that are in-sync with
+scrolling impossible or [very
 difficult](https://developers.google.com/web/updates/2016/12/performant-parallaxing).
 
 
@@ -46,27 +47,47 @@ scroll-linked animation under the existing common web-animation model allowing t
 inspected, controlled via a common animations API.
 
 ### Non-goals
-* **Scroll-triggered animations**: these are time-based animations that may be triggered when a
-  scroller reaches a certain offset. These are also common but do not suffer from jank issues since
-  time-based animations can easily be off-thread. The current best practice is to use
-  IntersectionObserver to kick-off such animation which seems sufficient. Other alternative ideas
-  (`:ever-been-visible` pseudo class or generic animation-trigger) have been proposed
-  [here](https://github.com/w3c/csswg-drafts/issues/4339#issuecomment-499666491) that the current
-  ScrollTimeline proposal does not prohibit.
-
-* **Stateful scripted scroll driven animations**: Some scroll-linked animations may not fit well
-  within declarative animations such as those that depend on scroll velocity, or direction, or have
-  custom per frame logic. We believe these can continue to be solved using rAF (and in future
-  be made more efficient with [CSS Animation
-  Worklet](https://drafts.css-houdini.org/css-animationworklet/)). ScrollTimeline may be used in
-  conjunction with these.
+
+#### Scroll-triggered animations
+
+These are a class of animation whose progress is driven by time but whose activation may be
+triggered when scrolling past a certain position or into a given scroll range.  These are also
+common on the web but they don't suffer from main thread jank and synchronous scrolling lad in the
+same way that scroll-linked animations do. This is becuase only their activation is tied to scroll
+position and and not their progress.
+
+However, we found that in the vast majority of cases where a web author would want to do this, they
+would want to do it for a CSS transition (as opposed to a CSS animation). Unfortunately, it's not
+possible to trigger CSS transitions from the compositor thread (because triggering a transition
+requires style resolution, which cannot be performed on the compositor thread). 
+
+Earlier versions of this specification included a triggering mechanims. But given the extent to
+which triggering complicated the API and because of the smaller benefit that these type of
+animation will receive, we decided it wasn't worth it if you can't use it for transitions, so this
+feature was remove and scroll-triggered animations are non-goal for this API.
+
+
+At the moment, the current best practice is to use IntersectionObserver to kick-off such animation
+which seems sufficient. Other alternative ideas (`:ever-been-visible` pseudo class or generic
+animation-trigger) have been proposed
+[here](https://github.com/w3c/csswg-drafts/issues/4339#issuecomment-499666491) that the current
+ScrollTimeline proposal does not prohibit. The design space for triggering animations is still open
+and we welcome input on this subject for future revisions in this specification.
+
+#### Stateful scripted scroll driven animations
+
+Some scroll-linked animations may not fit well within declarative animations such as those that
+depend on scroll velocity, or direction, or have custom per frame logic. We believe these can
+continue to be solved using rAF (and in future be made more efficient with [Houdini Animation
+Worklet](https://drafts.css-houdini.org/css-animationworklet/)). ScrollTimeline may be used in
+conjunction with these.
 
 ## New APIs
 
 The [Scroll-linked Animations](https://drafts.csswg.org/scroll-animations-1/) spec introduces one
 new concept: ScrollTimeline
 
-### Scroll Timeline API
+### Scroll Timeline
 
 A [ScrollTimeline](https://drafts.csswg.org/scroll-animations-1/#scrolltimeline-interface) is an
 [AnimationTimeline](https://drafts.csswg.org/web-animations-1/#the-animationtimeline-interface)

scroll-animations-1/Overview.bs

@@ -8,8 +8,8 @@ Group: CSSWG
 URL: https://drafts.csswg.org/scroll-animations-1/
 ED: https://drafts.csswg.org/scroll-animations-1/
 Shortname: scroll-animations-1
-Abstract: Defines an API and markup for creating animations that are either
-          triggered by or tied to the scroll offset of a scroll container.
+Abstract: Defines an API and markup for creating animations that are tied to 
+          the scroll offset of a scroll container.
 Editor: Brian Birtles, Invited Expert, brian@birchill.co.jp, w3cid 43194
 Editor: Botond Ballo, Mozilla, botond@mozilla.com
 Editor: Antoine Quint, Apple, graouts@apple.com, w3cid 51377
@@ -74,7 +74,7 @@ way that does not require script to run each time the effect is sampled. User
 agents that support asynchronous scrolling are allowed (but not required) to
 sample such effects asynchronously as well.
 
-## Value Definitions {#values}
+## Value Definitions ## {#values}
 
 This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
 using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
@@ -94,59 +94,8 @@ Note: Based on this <a
 href="https://github.com/WICG/scroll-animations/blob/master/Use%20cases.md">curated
 list of use cases</a>.
 
-## Scroll-triggered animations ## {#scroll-triggered-animations-usecases}
 
-### Navigation bar shrinking effect ### {#navigation-bar-shrinking-effect}
-
-It is common to trigger an animation to run when the scroll position
-reaches a certain point. For example, a navigation bar may shrink once
-the user begins to scroll a page.
-
-<figure>
-<img src="img/usecase1-2.svg" width="600"
-alt="Use case: Shrinking navigation bar">
- <figcaption>
-  Shrinking navigation bar<br>
-  The left figure shows the navigation bar before scrolling with
-  a large menu bar.<br>
-  The right figure shows the shrunken navigation bar after scrolling.
- </figcaption>
-</figure>
-
-Advisement: The proposal does not yet define CSS markup or programming
-            interfaces to express this use case.
-
-### Navigation highlight effect ### {#navigation-highlight-effect}
-
-Similarly, it is common to trigger an animation at certain fixed points
-in a element's scroll range. For example, a navigation bar that changes
-highlight based on the reader's position within the document.
-
-<figure>
-<img src="img/usecase1-1.svg" width="600"
-alt="Use case: A navigation highlight effect.">
- <figcaption>
-  A navigation highlight effect<br>
-  On the left, the &ldquo;Abstract&rdquo; section is scrolled into view
-  and hence the abstract menu item is highlighted.<br>
-  After scrolling down to the &ldquo;Background&rdquo; section (right),
-  the background menu item fades in while the abstract menu item fades
-  out.
- </figcaption>
-</figure>
-
-Advisement: The proposal does not yet define CSS markup or programming
-            interfaces to express this use case.
-
-## Scroll-triggered style changes ## {#scroll-triggered-style-changes-usecase}
-
-Advisement: The proposal does not yet define CSS markup or programming
-            interfaces to express this use case.
-
-
-## Scroll-linked animations ## {#scroll-linked-animations-usecase}
-
-### Scrollable picture-story show ### {#scrollable-animation-usecase}
+## Scrollable picture-story show ## {#scrollable-animation-usecase}
 
 Another pattern is an animation that tells a story where the user
 controls the progress of the animation by scrolling or some other
@@ -247,7 +196,7 @@ if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
 }
 </pre>
 
-### The content progress bar ### {#content-progress-bar-usecase}
+## The content progress bar ## {#content-progress-bar-usecase}
 
 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
@@ -449,7 +398,7 @@ not by wall-clock time, but by the progress of scrolling in a [=scroll container
 
 :   <dfn attribute for=ScrollTimeline>orientation</dfn>
 ::  Determines the direction of scrolling which triggers the activation and drives
-    the progress of the trigger.
+    the progress of the timeline.
 
 :   <dfn attribute for=ScrollTimeline>start</dfn>
 ::  A scroll offset, in the direction specified by {{orientation}}, which constitutes
@@ -472,7 +421,7 @@ not by wall-clock time, but by the progress of scrolling in a [=scroll container
 
 :   <dfn attribute for=ScrollTimeline>end</dfn>
 ::  A scroll offset, in the direction specified by {{orientation}}, which constitutes
-    the end of the range in which the trigger is activated.
+    the end of the range in which the timeline is activated.
 
     Recognized values are defined by the following grammar:
 
@@ -856,30 +805,6 @@ run), the user agent may likewise choose not to sample scroll-driven animations
 for that composited frame. In such cases, the rendered scroll offset and the
 state of a scroll-driven animation may be inconsistent in the composited frame.
 
-# Scroll-triggered (but time-driven) animations # {#scroll-triggered-animations}
-
-An earlier draft of this proposal also provided for animations whose progress
-was driven by time (as with existing animations), but whose activation was
-triggered by scrolling past a certain scroll offset or into a given scroll range.
-
-The main objective was to allow triggering the animation from the compositor
-thread. (The objective of scroll-linked animations is to make sure that
-the animation is in sync with the scroll position on each composited frame.
-If the triggering doesn't happen on the compositor thread, then it's possible
-that for a few frames the visual scroll position is such that the animation
-should have started, but it has not in fact started yet because the main thread,
-which is doing the triggering, is lagging behind.)
-
-However, we found that in the vast majority of cases where a web author would
-want to do this, they would want to do it for a CSS transition (as opposed to
-a CSS animation). Unfortunately, it's not possible to trigger CSS transitions from
-the compositor thread (because triggering a transition requires style resolution,
-which cannot be performed on the compositor thread). Given the extent to which
-triggering complicated the API, we decided it wasn't worth it if you can't use
-it for transitions, so this feature was removed.
-
-The design space for triggering animations is still open. We welcome input
-on this subject.
 
 <h2 id="appendix-a-considerations-for-security-and-privacy">Appendix A. Considerations for Security and Privacy</h2>
 

scroll-animations-1/Use cases.md

@@ -1,4 +1,49 @@
-1. Scroll-triggered animations
+1. Scroll-linked animations
+-----------------------------
+
+Scroll position controls progress:
+
+- http://alfredservice.com/ (controls animation progress, even movie progress)
+- http://www.flatvsrealism.com
+- http://makeyourmoneymatter.org/
+- http://www.dementialab.org/discovery-lab/
+- http://lostworldsfairs.com/atlantis/
+- http://everylastdrop.co.uk/
+- http://www.madwell.com/work
+- http://www.fannabee.com/
+- http://www.culturalsolutions.co.uk/
+- http://jason-kenny.com/
+- http://lamoulade.com/#!/home
+- http://www.nytimes.com/projects/2013/tomato-can-blues/?hp
+- http://www.unfold.no/
+- http://www.arnoldclark.com/challenge/
+- http://cyclemon.com/
+- http://www.bbc.co.uk/news/special/2014/newsspec_7617/index.html
+- http://johnpeelarchive.com/joe-boyd/#TOOTS
+- http://nasaprospect.com/
+- http://allout.org/en/
+- https://www.washingtonpost.com/graphics/sports/olympics/scale-of-the-olympics/?%3Ftid%3D=sm_pg&%3Ftid%3D=sm_pg (scroll → zoom)
+- https://www.invisionapp.com/product-design-industry-report-2016
+
+2. Combination scroll and time-based animations
+------------------------------------------------------
+
+- http://www.nytimes.com/projects/2012/snow-fall/#/?part=tunnel-creek
+- http://www.gestrandete-wale.info/
+- http://cuberto.com/
+
+
+
+# Deferred Usecases
+
+See [EXPLAINER](https://github.com/w3c/csswg-drafts/blob/master/scroll-animations-1/EXPLAINER.md#non-goals)
+for an explanation of why theses usecases are deferreing in the first version of this specification.
+The design space for triggering animations is still open. We welcome input on this subject for next
+revision of this specification.
+
+
+
+3. Scroll-triggered animations
 ---------------------------------
 
 Trigger an animation based on scroll position:
@@ -36,37 +81,3 @@ Multiple scroll-ranges:
 ------------------------------------
 
 - http://unformedbuilding.com/articles/fixed-nav-with-jquery/
-
-3. Scroll-linked animations
------------------------------
-
-Scroll position controls progress:
-
-- http://alfredservice.com/ (controls animation progress, even movie progress)
-- http://www.flatvsrealism.com
-- http://makeyourmoneymatter.org/
-- http://www.dementialab.org/discovery-lab/
-- http://lostworldsfairs.com/atlantis/
-- http://everylastdrop.co.uk/
-- http://www.madwell.com/work
-- http://www.fannabee.com/
-- http://www.culturalsolutions.co.uk/
-- http://jason-kenny.com/
-- http://lamoulade.com/#!/home
-- http://www.nytimes.com/projects/2013/tomato-can-blues/?hp
-- http://www.unfold.no/
-- http://www.arnoldclark.com/challenge/
-- http://cyclemon.com/
-- http://www.bbc.co.uk/news/special/2014/newsspec_7617/index.html
-- http://johnpeelarchive.com/joe-boyd/#TOOTS
-- http://nasaprospect.com/
-- http://allout.org/en/
-- https://www.washingtonpost.com/graphics/sports/olympics/scale-of-the-olympics/?%3Ftid%3D=sm_pg&%3Ftid%3D=sm_pg (scroll → zoom)
-- https://www.invisionapp.com/product-design-industry-report-2016
-
-4. Combination scroll and time-based animations
-------------------------------------------------------
-
-- http://www.nytimes.com/projects/2012/snow-fall/#/?part=tunnel-creek
-- http://www.gestrandete-wale.info/
-- http://cuberto.com/