[scroll-animations] Support series of scroll offsets

[mattgperry]

Inspired by the proposal to allow Element-based offsets, I propose we can simplify the startScrollOffset and endScrollOffset props into a single scrollOffsets array.

This would allow us to leverage KeyframeEffect's ability to accept more than two keyframes in an animation.

Example

The "Example 1. Reveal / Unreveal" example in the above ticket shows the definition of two ScrollTimelines, like this:

const revealTimeline = new ScrollTimeline({
  startScrollOffset: { target: image, edge: 'start', threshold: 0 },
  endScrollOffset: { target: image, edge: 'start', threshold: 100 },
});

const unrevealTimeline = new ScrollTimeline({
  startScrollOffset:{ target: image, edge: 'end', threshold: 100}
  endScrollOffset:{ target: image, edge: 'end', threshold:0}
});

To create one conceptually unique effect (fade in while on screen), we create two timelines, two effects, and two animations.

Instead, we can half this to just one, with a single scrollOffset array:

const timeline = new ScrollTimeline({
  source: scroller,
  scrollOffsets: [100, 200, 800, 900]
});

Taken from @majido's example, this would change the above to:

const timeline = new ScrollTimeline({
  scrollOffsets: [
     { target: image, edge: 'start', threshold: 0 },
     { target: image, edge: 'start', threshold: 100 },
     { target: image, edge: 'end', threshold: 100 }, 
     { target: image, edge: 'end', threshold: 0 }
  ]
});

const effect = new KeyframeEffect(
  image,
  { opacity: [0, 1, 1, 0]},
  { duration: 1000, fill: both }
);

const revealUnrevleaAnimation = new Animation(effect, timeline);
revealUnrevleaAnimation.play();

[majido]

This is an interesting idea which I am in favor of. I can see how multiple scroll offsets can simplify the API and is more ergonomics due to the fact that it can be paired with multi-frame keyframe effects.

Follow the processing logic for keyframes here are some ideas on how to spec and implement this:

• Consider single-entry offsets as being the "end"

• We need to have the scroll offset in increasing order otherwise time can go negative in some sections which is almost definitely a bug (Issue [scroll-animations] End < Start offset can cause the ScrollTimeline to produce negative time #4351 but supercharged!). There are two options:

  1. require scroll offsets to be in increasing order and error if not otherwise. This is consistent and easy to debug behavior.
  2. allow scroll offsets to be provided in any order, sort them before using them to ensure the are in increasing offsets. This may work better with element-based offsets whose exact value may not be known before starting the animation.

• Treat these scroll offsets as equal-distanced in time. This is similar to having keyframes with no offset on them. See compute missing keyframes offsets in web-animations for how this works.

  • Note: While keyframes may have an additional offsets specified on them but it is not clear if we should allow these for scrollOffsets. The additional complexity is not justified at the moment and we can add it later. To this end I like the name scrollOffsets instead of offsets since it allows adding the offset to each entry in the future.

• Allow static and element-based offset to be mixed in the scrollOffsets array.

/cc @flackr @ogerchikov @birtles for awareness and in case they have suggestions here.

[birtles]

This makes sense. I think treating the scroll offsets as equidistant in time would mesh well with the proposal for an auto duration for scroll timelines (#4862 / #4890). I haven't really though through the mixing static and element-based offsets however.

[ogerchikov]

This comment summarizes offline discussion between @majido and @ogerchikov regarding handling unsorted offsets.

Below are presented options:

1. Sort offsets on every current time calculation.
2. Throw if offsets are in wrong order.
3. Produce unresolved time if offsets are in wrong order.
4. Define heuristics for keeping only sorted values and ignore unsorted.

We feel that options 1 and 4 are hard to reason about and debug, option 2 is not practical since layout can change.

For initial implementation we feel that option 3 is the most desirable as it lets unsorted offsets to exist and resolved current time to be produced once/if the offsets become sorted. It also allows for future modifications towards options 1 or 4 if practical needs arise.

[majido]

This was discussed in last F2F sync.

@birtles suggested an interesting approach based on clamping the offending values. The clamp value could be a middle value and neither of the two offending value. This can lead to an outcome that is closer to author intent.

Consider this example offsets: [100, 300, 200, 400]. Here 300 and 200 are in the invalid order so we replace them with 250 so the calculate offsets will be [100, 250, 250 400].

In the context of reveal/unreveal example a realistic case is when the item we want to reveal is larger than the viewport which would produce such a situation. The suggested clamping approach will cause the reveal to continue for 50% of total animation and unreveal to start to the remainder. While we never reach opacity 1 but it seems a better option than alternatives.

The consensus was that this looks like a promising approach instead of returning unresolved time.

Action Items:

• @ogerchikov is planning to spec this in more details
• @flackr was considering to prototype this in the polyfill to see how it will behave in practice.

[flackr]

Just a correction, my understanding is that we would in fact reach opacity 1 at exactly scroll offset 250. It's just that the time to get to opacity 1 would be only 150px instead of the requested 200px on either end.

[birtles]

My expectation is you would never get to opacity 1. That seems to me personally to be more in line with what the author intended rather than speeding up the effect.

[flackr]

Thanks for the clarification, I agree this is probably more in line with the developer intention, however I think this isn't equivalent to [100, 250, 250, 400], because it loses the information that 250 is only 2/3 of the way to the second / third keyframe.

Perhaps we should keep the conflicting scroll offsets in the calculated offsets and define a procedure for determining the current offset which applies this logic, e.g. something like

If offset i + 1 is less than offset i, find the first offset j which is greater than or equal to offset i. If the scroll offset falls between offset i and offset j then the resulting animation offset uses the pair [i, i + 1] or [j - 1, j] whichever of i or j is closer to the current position.

[majido]

Earlier in this thread I speculated if we should allow "offsets" for these scrollOffset similar to how we have these on keyframes.

My conclusion then was that perhaps its complexity is not justified but I wonder if having offset makes achieving the desired clamping behavior without unnecessary speed up actually simpler.

Consider if we actually have implied offsets for the current example. So [100, 300, 200, 400] is actually interpreted as the following map: {0 => 100, 0.33 => 300, 0.66 => 200, 1 => 400}. Notice the implied input offsets are equi-distance in the case where no offset is provided by the author.

The logic for clamping then detects any series of offsets that don't match the expected order then it clamps both the values and their offsets to the middle point.

So in the example case it will turn it into {0 => 100, 0.5 => 250, 0.5 => 250, 1 => 400} (or even {0 => 100, 0.5 => 250, 1 => 400} if we eliminate duplicate entries for 0.5 => 250)

The advantages are:

• Achieves the most preferred outcome where animations are not sped up.
• Easier to reason about since the output of scroll timeline can easily be determined given the calculated offset.
• More consistent with keyframes having offsets.
• We can allow authors to provide offset for better ergonomics in more complex cases.

[majido]

While at it perhaps it is also worth bikeshedding scrollOffsets name a bit more.

I think we should not include scroll in the name given that ScrollTimeline.scrollOffset does not read that well. Also we should not include offsets if we every plan to introduce offsets similar to Keyframes.

The only other good name that I have come up with so far is ScrollTimeline.thresholds where each threshold has a scroll position and an optional offset.

[flackr]

I'm confused, isn't the map we're trying to build scroll offset to animation offset, not the reverse?

My expectation would be that if we include animation offsets [100, 300, 200, 400] would produce {100 => 0, 250 => 0.22, 250 => 0.78, 400 => 1} where the 0.22 and 0.78 are the relative proportion of those interpolations that would be covered (e.g. 66% of the 33% animation progress achieved at offset 250). This clearly shows that we're skipping the entire animation between 22% and 78%.

If we strictly use the midpoint of the overlapping animation offsets we might in fact change the speed of the effect, consider:
[100, 300, 100, 400]
The midpoint is 150 with value 0.5. This means that at 151, we will be just over 51%, rather than the expected position of being well into the [100, 400] interpolation between keyframes 3 and 4.