[css-animationworklet] Update README

- Add new SpringTiming example
- Make sure all classes in example extend StatelessAnimator
- Add Animator to core concept and move GroupEffect and ScrollTimeline
to their own section
- other minor edits

Author: majido

css-animationworklet/README.md

@@ -4,7 +4,7 @@
 # Overview
 
 Animation Worklet is a new primitive that provides extensibility in web animations and enables high
-performance procedural animations on the web. The feature is developed as part of the  
+performance procedural animations on the web. The feature is developed as part of the
 [CSS Houdini task force](https://github.com/w3c/css-houdini-drafts/wiki).
 
 The Animation Worklet API provides a method to create scripted animations that control a set of
@@ -43,7 +43,6 @@ address this problem.
     *   Custom scrollbars.
     *   High-fidelity location tracking and positioning
     *   [More examples](https://github.com/w3c/css-houdini-drafts/blob/master/scroll-customization-api/UseCases.md) of scroll-driven effects.
-    
 *   Gesture driven effects:
     *   [Image manipulator](https://github.com/w3c/csswg-drafts/issues/2493#issuecomment-422153926) that scales, rotates etc.
     *   Swipe to dismiss.
@@ -65,11 +64,11 @@ address this problem.
 
 Not all of these usecases are immediately enabled by the current proposed API. However Animation
 Worklet provides a powerfull primitive (off main-thread scriped animation) which when combined with
-other upcoming features (e.g., 
+other upcoming features (e.g.,
 [Event in Worklets](https://github.com/w3c/css-houdini-drafts/issues/834),
 [ScrollTimeline](https://wicg.github.io/scroll-animations/),
-[GroupEffect](https://github.com/w3c/csswg-drafts/issues/2071)) can address all these usecases and 
-allows many of currently main-thread rAF-based animations to move off thread with significant 
+[GroupEffect](https://github.com/w3c/csswg-drafts/issues/2071)) can address all these usecases and
+allows many of currently main-thread rAF-based animations to move off thread with significant
 improvement to their smoothness.
 See [Animation Worklet design principles and goals](principles.md) for a more extended discussion
 of this.
@@ -86,21 +85,29 @@ flag) otherwise they fallback to using main thread rAF to emulate the behaviour.
 ## Animation Worklet Global Scope
 A [worklet global scope](https://drafts.css-houdini.org/worklets/#the-global-scope) that is created
 by Animation Worklet. Note that Animation Worklet creates multiple such scopes and uses them to
-execute user defined effects.
+execute user defined effects. In particular global scopes are regularly switched to enforce
+stateless and stateful animator contracts.
+
+
+## Animator
+
+Animator is a Javascript class that encapsulates the custom animation logic. Similar to other
+Houdinig worklets, animators are registered inside the worklet global scope with a unique name which
+can be used to uniquely identify them.
+
 
 ## WorkletAnimation
-`WorkletAnimation` is a subclass of Animation that can be used to create an custom animation effect
-that runs inside a standalone animation worklet scope. A worklet animation has a corresponding
-animator instance in a animation worklet scope which is responsible to drive its keyframe effects.
-Here are the key differences compared to a regular web animation:
-  - AnimationId should match a specific animator class registered in the animation worklet scope.
-  - `WorkletAnimation` may have multiple timelines (including `ScrollTimeline`s).
-  - `WorkletAnimation` may have a custom properties bag that can be cloned and provided to animator
-    constructor when it is being instantiated.
+`WorkletAnimation` is a subclass of Animation that can be used to create an custom animation that
+runs inside a standalone animation worklet scope. A worklet animation has a corresponding animator
+instance in a animation worklet scope which is responsible to drive its keyframe effects. Here are
+the key differences compared to a regular web animation:
+  - Name: The name identifies the custom animator class registered in the animation worklet scope.
+  - Options: `WorkletAnimation` may have a custom properties bag that is cloned and provided to the
+    corresponding animator constructor when it is being instantiated.
 
 Note that worklet animations expose same API surface as other web animations and thus they may be
-created, played, paused, inspected, and generally controlled from main document scope. Here is how
-various methods roughly translate:
+created, played, paused, inspected, and generally controlled from the main document scope. Here is
+how various methods roughly translate:
 
   - `cancel()`: cancels the animation and the corresponding animator instance is removed.
   - `play()`: starts the animation and the corresponding animator instance gets constructed and
@@ -111,39 +118,8 @@ various methods roughly translate:
      the animator instance. (We are considering possiblity of having a `onPlaybackRateChanged`
      callback)
 
-## ScrollTimeline
-[ScrollTimeline](https://wicg.github.io/scroll-animations/#scrolltimeline) is a concept introduced in
-scroll-linked animation proposal. It defines an animation timeline whose time value depends on
-scroll position of a scroll container. `ScrollTimeline` can be used an an input timeline for
-worklet animations and it is the intended mechanisms to give read access to scroll position.
-
-## GroupEffect
-[GroupEffect](https://w3c.github.io/web-animations/level-2/#the-animationgroup-interfaces) is a
-concept introduced in Web Animation Level 2 specification. It provides a way to group multiple
-effects in a tree structure. `GroupEffect` can be used as the output for worklet animations. It
-makes it possible for worklet animation to drive effects spanning multiple elements.
-
-**TODO**: At the moment, `GroupEffect` only supports just two different scheduling models (i.e.,
-parallel, sequence). These models governs how the group effect time is translated to its children
-effect times by modifying the child effect start time. Animation Worklet allows a much more
-flexible scheduling model by making it possible to to set children effect's local time directly. In
-other words we allow arbitrary start time for child effects. This is something that needs to be
-added to level 2 spec.
-
-## ~~Multiple Timelines~~
-Unlike typical animations, worklet animations can be attached to multiple timelines. This is
-necessary to implement key usecases where the effect needs to smoothly animate across different
-timelines (e.g., scroll and wall clock).
-
-**NOTE**: We have decided to drop this piece in favor of alternative ideas. Most recent
-[promising idea](https://docs.google.com/document/d/1byDy6IZqvaci-FQoiRzkeAmTSVCyMF5UuaSeGJRHpJk/edit#heading=h.dc7o68szgx2r)
-revolves around allowing worklet and workers to receive input events directly.  (here are some
-earlier alternative design: [1](https://docs.google.com/document/d/1-APjTs9fn4-E7pFeFSfiWV8tYitO84VpmKuNpE-25Qk/edit), [2](https://github.com/w3c/csswg-drafts/issues/2493), [3](https://github.com/w3c/csswg-drafts/issues/2493#issuecomment-422109535)
-
-
 ## Statefull and Statelss Animators
 
-
 Sometimes animation effects require maintaining internal state (e.g., when animation needs to depend
 on velocity). Such animators have to explicitly declare their statefulness but by inheritting from
 `StatefulAnimator` superclass.
@@ -153,7 +129,6 @@ lifetime duration. For example user agents are free to initially run the animato
 but later decide to migrate it off main thread to get certain performance optimizations or to tear
 down scopes to save resources.
 
-
 Animation Worklet helps stateful animators to maintain their state across such migration events.
 This is done through a state() function which is called and animator exposes its state. Here is
 an example:
@@ -199,82 +174,98 @@ registerAnimator('animation-with-local-state', class FoorAnimator extends Statef
 });
 ```
 
-# Examples
+# Related Concepts
+
+The following concepts are not part of Animation Worklet specification but animation worklet is
+designed to take advantage of them to enable a richer set of usecases.
+
+## ScrollTimeline
+[ScrollTimeline](https://wicg.github.io/scroll-animations/#scrolltimeline) is a concept introduced in
+scroll-linked animation proposal. It defines an animation timeline whose time value depends on
+scroll position of a scroll container. `ScrollTimeline` can be used an an input timeline for
+worklet animations and it is the intended mechanisms to give read access to scroll position.
+
+## GroupEffect
+[GroupEffect](https://w3c.github.io/web-animations/level-2/#the-animationgroup-interfaces) is a
+concept introduced in Web Animation Level 2 specification. It provides a way to group multiple
+effects in a tree structure. `GroupEffect` can be used as the output for worklet animations. It
+makes it possible for worklet animation to drive effects spanning multiple elements.
 
-**TODO**: Add gifs that visualize these effects
+**TODO**: At the moment, `GroupEffect` only supports just two different scheduling models (i.e.,
+parallel, sequence). These models governs how the group effect time is translated to its children
+effect times by modifying the child effect start time. Animation Worklet allows a much more
+flexible scheduling model by making it possible to to set children effect's local time directly. In
+other words we allow arbitrary start time for child effects. This is something that needs to be
+added to level 2 spec.
 
-## Hidey Bar
-An example of header effect where a header is moved with scroll and as soon as finger is lifted
-it animates fully to close or open position depending on its current position.
 
+# Examples
 
-``` html
-<div id='scrollingContainer'>
-  <div id='header'>Some header</div>
-  <div>content</div>
-</div>
+## Custom Spring Timing
 
-<script>
-await CSS.animationWorklet.addModule('hidey-bar-animator.js');
+Use Animation Worklet to create animation with a custom spring timing.
 
-const scrollTimeline = new ScrollTimeline({
-  scrollSource: $scrollingContainer,
-  orientation: 'block',
-  timeRange: 100
-});
-const documentTimeline = document.timeline;
 
+```html
 
-const animation = new WorkletAnimation('hidey-bar',
-  new KeyframeEffect($header,
-                      [{transform: 'translateX(100px)'}, {transform: 'translateX(0px)'}],
-                      {duration: 100, iterations: 1, fill: 'both' })
-  scrollTimeline,
-  {scrollTimeline, documentTimeline},
-);
+<div id='target'></div>
+
+<script>
+await CSS.animationWorklet.addModule('spring-animator.js');
+
+const effect = new KeyframeEffect($target,{transform: ['translateX(0)', 'translateX(50vw)'}], {duration: 1000});
+const animation = new WorkletAnimation('spring', effect, document.timeline, {k: 2, ratio: 0.7);
 animation.play();
 </script>
 ```
 
-hidey-bar-animator.js:
-```js
-registerAnimator('hidey-bar', class {
+spring-animator.js:
 
-  constructor(options) {
-    this.scrollTimeline_ = options.scrollTimeline;
-    this.documentTimeline_ = options.documentTimeline;
+```js
+registerAnimator('spring', class SpringAnimator extends StatelessAnimator {
+  constructor(options = {k: 1, ratio: 0.5}) {
+    this.timing = createSpring(options.k, options.ratio);
   }
 
   animate(currentTime, effect) {
-    const scroll = this.scrollTimeline_.currentTime;  // [0, 100]
-    const time = this.documentTimeline_.currentTime;
-
-    // **TODO**: use a hypothetical 'phase' property on timeline as a way to detect when user is no
-    // longer actively scrolling. This is a reasonable thing to have on scroll timeline but we can
-    // fallback to using a timeout based approach as well.
-    const activelyScrolling = this.scrollTimeline_.phase == 'active';
-
-    let localTime;
-    if (activelyScrolling) {
-      this.startTime_ = undefined;
-      localTime = scroll;
-    } else {
-      this.startTime_ = this.startTime_ || time;
-      // Decide on close/open direction depending on how far we have scrolled the header
-      // This can even do more sophisticated animation curve by computing the scroll velocity and
-      // using it.
-      this.direction_ = scroll >= 50 ? +1 : -1;
-      localTime = this.direction_ * (time - this.startTime_);
-    }
-
-    // Drive the output effects by setting its local time.
-    effect.localTime = localTime;
+    let delta = this.timing(currentTime);
+    // scale this by target duration
+    delta = delta * (effect.getTimings().duration / 2);
+    effect.localTime = delta;
+    // TODO: Provide a method for animate to mark animation as finished once
+    // spring simulation is complete, e.g., this.finish()
+    // See issue https://github.com/w3c/css-houdini-drafts/issues/808
+  }
 });
 
+function createSpring(springConstant, ratio) {
+  // Normalize mass and distance to 1 and assume a reasonable init velocit
+  // but these can also become options to this animator.
+  const velocity = 0.2;
+  const mass = 1;
+  const distance = 1;
+
+  // Keep ratio < 1 to ensure it is under-damped.
+  ratio = Math.min(ratio, 1 - 1e-5);
+
+  const damping = ratio * 2.0 * Math.sqrt(springConstant);
+  const w = Math.sqrt(4.0 * springConstant - damping * damping) / (2.0 * mass);
+  const r = -(damping / 2.0);
+  const c1 = distance;
+  const c2 = (velocity - r * distance) / w;
+
+  // return a value in [0..distance]
+  return function springTiming(timeMs) {
+    const time = timeMs / 1000; // in seconds
+    const result = Math.pow(Math.E, r * time) *
+                  (c1 * Math.cos(w * time) + c2 * Math.sin(w * time));
+    return distance - result;
+  }
+}
 ```
 
-
 ## Twitter Header
+
 An example of twitter profile header effect where two elements (avatar, and header) are updated in
 sync with scroll offset.
 
@@ -307,7 +298,7 @@ animation.play();
 
 twitter-header-animator.js:
 ```js
-registerAnimator('twitter-header', class {
+registerAnimator('twitter-header', class TwitterHeader extends StatelessAnimator {
   constructor(options) {
     this.timing_ = new CubicBezier('ease-out');
   }
@@ -329,6 +320,7 @@ registerAnimator('twitter-header', class {
 ```
 
 ### Parallax
+
 ```html
 <style>
 .parallax {
@@ -375,7 +367,7 @@ parallax-animator.js:
 
 ```js
 // Inside AnimationWorkletGlobalScope.
-registerAnimator('parallax', class {
+registerAnimator('parallax', class Parallax extends StatelessAnimator{
   constructor(options) {
     this.rate_ = options.rate;
   }
@@ -386,7 +378,6 @@ registerAnimator('parallax', class {
 });
 ```
 
-
 # WEBIDL
 
 `WorkletAnimation` extends `Animation` and adds a getter for its timelines.
@@ -424,7 +415,6 @@ partial interface AnimationEffectReadOnly {
 
 ```
 
-
 # Specification
 The [draft specification](https://drafts.css-houdini.org/css-animationworklet) is
 the most recent version.