Scroll customization update

[Timothy Dresser]

We (rbyers@ and I) are considering a slight re-scoping of scroll customization, which will clarify its role in the web platform, minimize its API surface, and simplify its implementation.

In particular, we've come to believe that programmatic scrolls should not be customizable using scroll customization. The role of scroll customization is to map a user’s intent to scroll into concrete requests to scroll specific scrollable areas[1]. As programmatic scroll requests aren't communicating user intent, but are already concrete requests to scroll specific scrollable areas, scroll customization should not apply to them. This is reflected in the updated scrolling architecture diagram. Anecdotally, this aligns well with IE’s implementation of snap points, which customizes scrolling via user input, but doesn't effect programmatic scrolling.

Many scrolling related APIs cause a scroll to an absolute location, such as element.scrollIntoView(). It isn’t adequate to map directly from absolute locations to deltas, since scroll customization might modify the deltas, resulting in a call to element.scrollIntoView not scrolling the element into view. Scrolling by a delta and scrolling to an absolute location are distinct operations, which must be handled differently. In order to enable scroll customization to customize scrolls to absolute locations, we’d need to add additional API surface. If we choose not to let scroll customization apply to programmatic scrolling, a developer can customize the behavior of programmatic scrolling apis by overriding the programmatic scrolling methods (which could call into scroll customization logic if similar behavior is required).

This results in three categories of scrolling related effects:

• Scroll response:
  
• Opting into synchronous scrolling and adding a scroll event listener enables responding to programmatic and user input triggered scrolls.
• Scroll application customization:
  
• Overriding the applyScroll[2] method enables responding to and possibly modifying how a user’s intent to scroll is applied to an element.
• Scroll distribution customization
  
• Overriding the distributeScroll method enables changing how a user’s intent to scroll is distributed among the elements in the scroll chain.

Any thoughts on this change in scope? If there are no objections, I'll start performing some related renaming shortly.

[1] Some user input results in concrete requests to scroll specific scrollable areas to specific locations (the HOME and END keys). These inputs should not trigger scroll customization.

[2] We may rename this to indicate that it doesn't deal with programmatic scrolls. Any ideas? I’m partial to applyScrollIntent.

[Rick Byers]

Thanks Tim, I agree with everything you've said.  In particular, most of the value we're trying to achieve here is in this mapping of user scroll intents to the scroll action that will occur - trying to add hooks into parts of the system below this has become a huge distraction.  We can simplify our lives with clearer architectural layering, with our system strictly on top of the programmatic scroll APIs.

Couple nits on the architectural diagram:

• We eventually need to get the updated names for 'scroll state' in there (distinguishing between the object that contains a chain and that which doesn't).  It's definitely not correct to have "scroll state" past the apply scroll steps. 
  
• I'd somehow like the line above 'possibly initiate smooth scroll' to pop more.  This is a key architectural layering boundary - that below deals in terms of scroll positions, that above deals in terms of scroll updates.  Perhaps we should have this box be simply "programmatic scrolling APIs", and make it red, with a line coming in without any particular source?  I.e. the output of the scroll customization system is calls into the scrolling APIs.
  
• As discussed in the meeting, we should get home/end in here (which probably means moving keyboard to the right side and splitting after the JS key handlers).
  

Rick

[Alexandre Elias]

This adjustment SGTM.

[Timothy Dresser]

I've put an updated version of the architectural diagram here.
Rick, I had a hard time interpreting your second point - does this seems reasonable to you?

I'm not entirely happy with these naming choices, but I think it's at least a step in the right direction.

[Rick Byers]

Looks great, thanks!

[Timothy Dresser]

Another update to the diagram, which adds scrollbar scrolling.

Scrollbar scrolling is problematic, as its the only method of scrolling which invokes _no_ customization points.
This may mean we need an additional API to implement native quality snap points, as we need to be able to know when the user drops the scroll thumb.

[Steve Kobes]

This diagram shows smooth scrolling underneath applyScroll... but this doc says it will actually sit above Element, meaning we would call distributeScroll / applyScroll for each tick of the animation, right?

Everything else LGTM.

[Rick Byers]

Yes, this is one of the main architectural changes.  Having smooth scroll call applyScroll on each tick caused a number of problems, leading (among other things) to the design change here.  The diagram reflects are current thinking on that front and Tim is working on a major update to the design doc (temporarily forked to avoid the doc being too inconsistent temporarily).

Rick

[Steve Kobes]

I'm probably misunderstanding it, but... if applyScroll receives the target offset instead of the current offset, won't effects linked to the scroll offset be out of sync?  Unless devs reimplement the smooth scrolling physics, which I think we want to avoid.

[Rick Byers]

Scroll customization doesn't operate in terms of scroll offsets, it operates in terms of scroll deltas (like wheel and GestureScrollUpdate events).  It let's you transform those deltas and how they're applied to elements.

Effects that are linked to scroll positions (eg. position sticky / scroll headers - "scroll response effects") don't generally need scroll customization at all.  They just need synchronization (so scroll event handlers and a mechanism like scroll-blocks-on to ensure they run in sync with scroll application).  That said, applyScroll is what updates the element scroll offset, so I think you can still have a custom applyScroll method which reads the old offset, invokes the default applyScroll then reads (and possibly responds somehow to) the new scroll offset.  But the new plan is this will get triggered only for input-driven scrolls, if you want to respond to all types of scroll (including the smooth scroll APIs) you should be relying just on synchronous scroll events.

Rick

[Steve Kobes]

Sorry, my concern is about input-driven smooth scrolls.  For programmatic scrolls I agree with the reasoning here.

[Rick Byers]

Ah, sorry - my confusion (we've been stuck on issues with the smooth scrolling API, I assumed that's what you were talking about).  I believe what Tim has labeled as 'smooth scroll' in the diagram are just the JS APIs.

It looks like fling and other input-driven smooth scrolls are now missing from the diagram (we had hoped to unify them with programatic smooth scroll but it seems clear now that was wrong).  Tim, can you add them please?  I wonder if fling and wheel/keyboard smooth scroll could all be considered as a pre-step to distributeScroll (some shared logic between different input devices), or if they should really be per-input-device as part of generating the events?  Certainly trackpad scrolling on Mac is per-input-device (comes from the OS), but maybe it's OK to ignore that as an implementation detail.

Rick

[Timothy Dresser]

Thanks, I've added smooth scrolling back to the diagram. The diagram isn't quite as clear as I'd like: it may help to look at the diagram for ScrollAnimationManager as well. (Let me know if you have any thoughts on how to clarify things.) The ScrollAnimationManager will be responsible for driving all ScrollAnimators, and providing a way to cancel a scroll animation for a given ScrollableArea. It needs to be shared between input driven smooth scroll and programmatic smooth scroll, as any scroll will cancel any in progress smooth scroll on its element.

[Rick Byers]

Looks really good, thanks.  Tim and I talked about a couple ways to simplify this a bit further.  The goal here is to show the scrolling architecture and how data flows through the system, not necessarily implementation details (like code sharing).  With this in mind we can simplify the reasoning around scroll animations by decoupling the input-driven animations from the programmatic ones (even if they do end up sharing some code).

[Timothy Dresser]

Update here.

[Rick Byers]

Love it, thank you!

[Timothy Dresser]

I've updated the doc here.