Intent to implement: CSSOM-View scroll-behavior property

[Kip Gilbert]

Summary:

CSSOM-View defines a new css property, 'scroll-behavior'. When set to
'smooth', scrolling boxes will be scrolled in a smooth fashion using a
user-agent-defined function.

Implementing this property will enable more fluid scrolling interfaces
consistent with modern UI paradigms without needing to update the
position manually on a frame-by-frame basis in Javascript. In much the
same way as APZ's fling gestures, the fluid scrolling will take over the
scroll position updates when CSSOM methods or navigation set the scroll
position.

Other effects such as smooth-scroll-snapping can be built upon this
property by setting the scroll position for a smooth scrolling box at
the end of a dragging event. This is beneficial to applications such as
the B2G home screen and image carousels.

Bug:

https://bugzilla.mozilla.org/show_bug.cgi?id=1010538

Link to standard:

http://dev.w3.org/csswg/cssom-view/#smooth-scrolling:-the-%27scroll-behavior%27-property

Platform coverage:

Android, Desktop, Firefox OS

This functionality is beneficial on all platforms. The implementation
fits naturally within the APZ classes; however, APZ may not be available
for some time outside of B2G. I would like to gauge the demand for this
functionality outside of B2G to determine if it should be implemented
independently of APZ and land earlier on other platforms.

Estimated or target release:

TBD

Preference behind which this will be implemented:

layout.css.scroll-behavior.enabled

[Jonas Sicking]

On Thu, May 22, 2014 at 1:50 PM, Kip Gilbert <kgil...@mozilla.com> wrote:
> Link to standard:
>
> http://dev.w3.org/csswg/cssom-view/#smooth-scrolling:-the-%27scroll-behavior%27-property

How will "scroll-behavior: instant" work on platforms that use APZ? I
worry about authors expect it to enable them to do a bunch of DOM
mutations and then set the scroll position and allow them to be sure
that rendering can't happen of the new DOM but at the old scroll
position (or the old DOM but at the new scroll position). Can we
promise that when using APZ?

One use case that has come up for us in FirefoxOS is the ability to
add a few elements to the top of a page, shifting down the contents of
the page, but then make that transparent to the user by adjusting the
scroll position accordingly.

That isn't possible with APZ since the user might be actively
scrolling and so if we just do something like

div.scrollTop += hightOfNewContent;

then the newly set scroll position will be based off of an old value
which has already changed on the compositing thread.

Basically we need an API like

div.addToScrollPosition(hightOfNewContent);

This would allow the browser to send this delta to the compositing
thread along with the newly updated painting of the DOM.

I wonder if we need something similar for smooth-scrolling. So rather
than a CSS property, have something like something like:

div.smoothScrollTo(pos, n); // does a smooth scroll over n ms.

div.setScrollPosition(pos); // ensures that the next time we paint, we
paint at scroll position pos

div.immediatelyScrollTo(pos); // sends a signal immediately to the
composition thread to jump to pos, possibly before any painting has
happened. I'm not sure if this one has use cases.

/ Jonas

[Ben Kelly]

On 5/23/2014 6:12 AM, Jonas Sicking wrote:
> That isn't possible with APZ since the user might be actively
> scrolling and so if we just do something like
>
> div.scrollTop += hightOfNewContent;
>
> then the newly set scroll position will be based off of an old value
> which has already changed on the compositing thread.
>
> Basically we need an API like
>
> div.addToScrollPosition(hightOfNewContent);
>
> This would allow the browser to send this delta to the compositing
> thread along with the newly updated painting of the DOM.

Would this allow us to avoid the sync reflow currently required with the
scrollTop approach as well? It would seem the platform would not need
to calculate an exact position in order to apply a delta like this.

Ben

[Robert O'Callahan]

On Fri, May 23, 2014 at 10:12 PM, Jonas Sicking <jo...@sicking.cc> wrote:

> How will "scroll-behavior: instant" work on platforms that use APZ? I
> worry about authors expect it to enable them to do a bunch of DOM
> mutations and then set the scroll position and allow them to be sure
> that rendering can't happen of the new DOM but at the old scroll
> position (or the old DOM but at the new scroll position). Can we
> promise that when using APZ?
>

Yes. Of course, the user can scroll in such a way that the content is never
visible at the new scroll position, but we can ensure that the DOM changes
and the scroll position change happen atomically.

Note that "instant" is our current behavior for all scripted scroll
position changes.

One use case that has come up for us in FirefoxOS is the ability to
> add a few elements to the top of a page, shifting down the contents of
> the page, but then make that transparent to the user by adjusting the
> scroll position accordingly.
>

> That isn't possible with APZ since the user might be actively
> scrolling and so if we just do something like
>
> div.scrollTop += hightOfNewContent;
>
> then the newly set scroll position will be based off of an old value
> which has already changed on the compositing thread.
>
> Basically we need an API like
>
> div.addToScrollPosition(hightOfNewContent);
>

On the viewport, we have scrollBy. CSSOM doesn't define that on elements
but it should. I guess they should both take an optional ScrollOptions
parameter.

div.smoothScrollTo(pos, n); // does a smooth scroll over n ms.
>

Better to not take a duration parameter if there isn't a clear use-case.
(Or is there?)

div.setScrollPosition(pos); // ensures that the next time we paint, we
> paint at scroll position pos
>

scrollLeft/scrollTop do this. Though I think elements should have the same
scrollTo method that Window does, as well.

div.immediatelyScrollTo(pos); // sends a signal immediately to the
> composition thread to jump to pos, possibly before any painting has
> happened. I'm not sure if this one has use cases.
>

Then let's not add it :-)

Rob
--
Jtehsauts tshaei dS,o n" Wohfy Mdaon yhoaus eanuttehrotraiitny eovni
le atrhtohu gthot sf oirng iyvoeu rs ihnesa.r"t sS?o Whhei csha iids teoa
stiheer :p atroa lsyazye,d 'mYaonu,r "sGients uapr,e tfaokreg iyvoeunr,
'm aotr atnod sgaoy ,h o'mGee.t" uTph eann dt hwea lmka'n? gBoutt uIp
waanndt wyeonut thoo mken.o w

[Kartikaya Gupta]

On 23/5/2014, 6:12, Jonas Sicking wrote:
> Basically we need an API like
>
> div.addToScrollPosition(hightOfNewContent);
>
> This would allow the browser to send this delta to the compositing
> thread along with the newly updated painting of the DOM.

This is certainly a valid use case, and it has come up before. We have
bug 959793 on file for tracking this issue. However I tend to think it
is a separate problem from what this spec is trying to address (i.e.
scroll to a specific scroll offset, but smoothly).

kats

[Jonas Sicking]

On Fri, May 23, 2014 at 3:47 AM, Robert O'Callahan <rob...@ocallahan.org> wrote:
>
>> One use case that has come up for us in FirefoxOS is the ability to
>> add a few elements to the top of a page, shifting down the contents of
>> the page, but then make that transparent to the user by adjusting the
>> scroll position accordingly.
>>
>> That isn't possible with APZ since the user might be actively
>> scrolling and so if we just do something like
>>
>> div.scrollTop += hightOfNewContent;
>>
>> then the newly set scroll position will be based off of an old value
>> which has already changed on the compositing thread.
>>

>> Basically we need an API like
>>
>> div.addToScrollPosition(hightOfNewContent);
>
>

> On the viewport, we have scrollBy. CSSOM doesn't define that on elements but
> it should. I guess they should both take an optional ScrollOptions
> parameter.
>
>> div.smoothScrollTo(pos, n); // does a smooth scroll over n ms.
>
>
> Better to not take a duration parameter if there isn't a clear use-case. (Or
> is there?)
>
>> div.setScrollPosition(pos); // ensures that the next time we paint, we
>> paint at scroll position pos
>
>
> scrollLeft/scrollTop do this. Though I think elements should have the same
> scrollTo method that Window does, as well.

I guess what I'm arguing is that smooth-scrolling vs. instant
scrolling shouldn't be a per-element CSS property, but rather a
per-callsite API argument.

It seems to me that it will be the case that for a given element
you'll sometimes want to do smooth scrolling operations and sometimes
instant operations.

For example in a list of emails you might want to enable
smooth-scrolling down 50 emails, but if additional emails come in, you
want to be able to add to the top of the list and atomically "add to
scroll scroll position" to compensate for the added elements.

I'm not sure if that means treating the current .scrollBy() and
.scrollLeft/.scrollTop API as instant (and make sure it applies to
elements in addition to windows) and adding smooth scrolling versions.
Or if we should add wholly new API which is more explicit about if it
intends to perform smooth vs. instant scrolling.

The only use-case I could see for the CSS property would be as a way
to indicate if a <a href="#..."> should perform an instant or a smooth
scroll.

/ Jonas

[Dao]

On 25.05.2014 05:00, Jonas Sicking wrote:
> I guess what I'm arguing is that smooth-scrolling vs. instant
> scrolling shouldn't be a per-element CSS property, but rather a
> per-callsite API argument.
>
> It seems to me that it will be the case that for a given element
> you'll sometimes want to do smooth scrolling operations and sometimes
> instant operations.
>
> For example in a list of emails you might want to enable
> smooth-scrolling down 50 emails, but if additional emails come in, you
> want to be able to add to the top of the list and atomically "add to
> scroll scroll position" to compensate for the added elements.

FWIW, XUL scrollboxes support both smooth scrolling (JS implementation
using requestAnimationFrame) and instant scrolling. The tabstrip on
Firefox desktop uses both methods. Which one is used varies from case to
case and is controlled by the callsites. I agree that a CSS property
doesn't satisfy this use case well.

[L. David Baron]

On Saturday 2014-05-24 20:00 -0700, Jonas Sicking wrote:
> I guess what I'm arguing is that smooth-scrolling vs. instant
> scrolling shouldn't be a per-element CSS property, but rather a
> per-callsite API argument.

I think I tend to agree; I noticed the same thing during the CSS WG
meeting last week and sent:
http://lists.w3.org/Archives/Public/www-style/2014May/0255.html

-David

--
𝄞 L. David Baron http://dbaron.org/ 𝄂
𝄢 Mozilla https://www.mozilla.org/ 𝄂
Before I built a wall I'd ask to know
What I was walling in or walling out,
And to whom I was like to give offense.
- Robert Frost, Mending Wall (1914)

[Robert O'Callahan]

On Sun, May 25, 2014 at 4:59 PM, L. David Baron <dba...@dbaron.org> wrote:

> On Saturday 2014-05-24 20:00 -0700, Jonas Sicking wrote:
> > I guess what I'm arguing is that smooth-scrolling vs. instant
> > scrolling shouldn't be a per-element CSS property, but rather a
> > per-callsite API argument.
>
> I think I tend to agree; I noticed the same thing during the CSS WG
> meeting last week and sent:
> http://lists.w3.org/Archives/Public/www-style/2014May/0255.html
>
>

I agree also.

[Robert O'Callahan]

On Mon, May 26, 2014 at 9:47 AM, Robert O'Callahan <rob...@ocallahan.org>wrote:

> On Sun, May 25, 2014 at 4:59 PM, L. David Baron <dba...@dbaron.org> wrote:
>
>> On Saturday 2014-05-24 20:00 -0700, Jonas Sicking wrote:
>> > I guess what I'm arguing is that smooth-scrolling vs. instant
>> > scrolling shouldn't be a per-element CSS property, but rather a
>> > per-callsite API argument.
>>
>> I think I tend to agree; I noticed the same thing during the CSS WG
>> meeting last week and sent:
>> http://lists.w3.org/Archives/Public/www-style/2014May/0255.html
>>
>>
> I agree also.
>

Actually non-auto values for the ScrollBehavior DOM API override the
scroll-behavior CSS property per spec. So I think the real question for us
is whether to implement the scroll-behavior property, or the ScrollBehavior
DOM API, or both. I think for now we should just implement the
ScrollBehavior DOM API.

[Dao]

On 25.05.2014 05:00, Jonas Sicking wrote:

> I guess what I'm arguing is that smooth-scrolling vs. instant
> scrolling shouldn't be a per-element CSS property, but rather a
> per-callsite API argument.
>
> It seems to me that it will be the case that for a given element
> you'll sometimes want to do smooth scrolling operations and sometimes
> instant operations.
>
> For example in a list of emails you might want to enable
> smooth-scrolling down 50 emails, but if additional emails come in, you
> want to be able to add to the top of the list and atomically "add to
> scroll scroll position" to compensate for the added elements.

[Kearwood Gilbert]

The ScrollBehavior DOM API would certainly be useful by itself and solve some of our immediate needs (paged B2G home page, for example). I also imagine that it would not preclude us from implementing the css property in the future if we implement it carefully.

I would like to hear feedback regarding the motion of the scrolling itself...

The spec describes the motion as "The scrolling box is scrolled in a smooth fashion using a user-agent-defined timing function over a user-agent-defined period of time. User agents should follow platform convensions, if any.".

Should we implement a separate model for any of the platforms we support, or is resolution independence and platform-specific tuning of the "critically-damped-motion" model I proposed sufficient?

In the Bug 1010538 (https://bugzilla.mozilla.org/show_bug.cgi?id=1010538) I am proposing that this movement model would inherit the velocity of the scroll resulting from fling gestures or prior smooth scroll operations that are interrupted. This would be needed to implement "scroll snapping" like behaviors for carousels and paged navigation that allow manual dragging (Including the B2G home page). The W3C scroll-behavior spec does not require this behavior, but also does not preclude it.

My greatest concern is that as platform conventions change, this behavior could (or should) be updated to match. Web developers that depend on particular acceleration / deceleration curves or time to completion may see their web applications behave differently in the future. If they treat it as a black-box; however, their applications may continue to feel modern, as opposed to movement implemented within their own Javascript.

Does this raise any concerns or need for further dialogue before implementation?

[kgil...@mozilla.com]

>
> Actually non-auto values for the ScrollBehavior DOM API override the
>
> scroll-behavior CSS property per spec. So I think the real question for us
>
> is whether to implement the scroll-behavior property, or the ScrollBehavior
>
> DOM API, or both. I think for now we should just implement the
>
> ScrollBehavior DOM API.
>
>

I would also like feedback on the concept of the scrolling behavior being a "write-only" property in much the same way that position: sticky was implemented.

Initial conversations on implementation of scroll-behavior: smooth
considered that the property would effectively be "write-only", much like how
position: sticky has been implemented. When smooth scrolling is enabled for
an element, CSSOM methods would return the target location immediately as
though the scrolling has already completed. Effectively, Javascript would
not be aware of any effect from enabling smooth scrolling.

In the event that a scroll operation is cancelled, either by user interaction (scroll wheel, touch gestures, etc) or through script, the "write-only" nature proposed will have "lied" to scripts about the ending position at the start of the animation. Once the animation is cancelled, the DOM methods would need to return the true scroll position, which may appear to scripts as scrolling in the reverse direction.

Is this behavior acceptable or would it be more desirable to always return the actual scroll position in DOM methods?

[Robert O'Callahan]

On Wed, May 28, 2014 at 5:36 AM, Kearwood Gilbert <
kearwood...@gmail.com> wrote:

> My greatest concern is that as platform conventions change, this behavior
> could (or should) be updated to match. Web developers that depend on
> particular acceleration / deceleration curves or time to completion may see
> their web applications behave differently in the future. If they treat it
> as a black-box; however, their applications may continue to feel modern, as
> opposed to movement implemented within their own Javascript.
>
> Does this raise any concerns or need for further dialogue before
> implementation?
>

I believe we don't currently make any attempt to match platform smooth
scrolling behavior, and I don't think we need to start now. I do think it's
a good idea to retain the option of matching platform behavior in the
future.

[Robert O'Callahan]

On Wed, May 28, 2014 at 6:14 AM, <kgil...@mozilla.com> wrote:

> Is this behavior acceptable or would it be more desirable to always return
> the actual scroll position in DOM methods?
>

All DOM methods that depend on the scroll position (not just
scrollLeft/scrollTop but getBoundingClientRect etc too) should always use
the most up-to-date value of the actual scroll position that the main
thread has. That's how our existing smooth scrolling behaves. I.e., we
don't lie :-). I'm pretty sure the CSSOM spec requires that for the
ScrollBehavior "smooth" value, too.

[Kearwood Gilbert]

On Tuesday, 27 May 2014 15:12:56 UTC-7, Robert O'Callahan wrote:
> On Wed, May 28, 2014 at 6:14 AM, <kgil...@mozilla.com> wrote:
>
>
>
> > Is this behavior acceptable or would it be more desirable to always return
> > the actual scroll position in DOM methods?
>
> All DOM methods that depend on the scroll position (not just
> scrollLeft/scrollTop but getBoundingClientRect etc too) should always use
> the most up-to-date value of the actual scroll position that the main
> thread has. That's how our existing smooth scrolling behaves. I.e., we
> don't lie :-). I'm pretty sure the CSSOM spec requires that for the
> ScrollBehavior "smooth" value, too.

I agree and have added a comment to the bug (Bug 101538 / Comment 17) to indicate that the property should not have the "write-only" effects that I described earlier.

- Kip

[Kearwood Gilbert]

On Sunday, 25 May 2014 14:57:13 UTC-7, Robert O'Callahan wrote:
> On Mon, May 26, 2014 at 9:47 AM, Robert O'Callahan <ro...t@ocallahan.org>wrote:

>
>
>
> > On Sun, May 25, 2014 at 4:59 PM, L. David Baron <db...n@dbaron.org> wrote:
>
> >
>
> >> On Saturday 2014-05-24 20:00 -0700, Jonas Sicking wrote:
>
> >> > I guess what I'm arguing is that smooth-scrolling vs. instant
> >> > scrolling shouldn't be a per-element CSS property, but rather a
> >> > per-callsite API argument.
> >>
>
> >> I think I tend to agree; I noticed the same thing during the CSS WG
> >> meeting last week and sent:
> >> http://lists.w3.org/Archives/Public/www-style/2014May/0255.html
> >>
> >>
> > I agree also.
> >
>
>
>
> Actually non-auto values for the ScrollBehavior DOM API override the
> scroll-behavior CSS property per spec. So I think the real question for us
> is whether to implement the scroll-behavior property, or the ScrollBehavior
> DOM API, or both. I think for now we should just implement the
> ScrollBehavior DOM API.
>
>
>
> Rob
>

Agreed. I have added a comment to the bug (Bug 1010538 / Comment 18) which reflects this:

To address the feedback on dev-platform regarding the uncertainty of use cases for the scroll-behavior css property, the CSSOM scrolling API's can be implemented first as they appear to provide the most immediate value. If the updated scrolling API lands without the scroll-behavior css property, then a separate bug will be filed to track the scroll-behavior css property independently.

Also, it is expected that the smooth scrolling will land in two stages. First will be an implementation based on APZ to solve our immediate use case (B2G home page) with a follow-up bug tracking an implementation independent of APZ.

- Kip

[Kip Gilbert]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

The bug has been split up to track individual parts of the implementation:

Bug 1010538 - Implement CSSOM-View scroll-behavior CSS property
Bug 1022818 - Implement CSSOM-View smooth scrolling DOM Methods
Bug 1022825 - Implement CSSOM-View smooth scrolling movement for APZ

My intent is to first implement minimal support for smooth scrolling
dependent on APZ with DOM Methods (Bug 1022818 and Bug 1022825). This
would be followed by implementing the CSS property.

If there is enough demand to land smooth scrolling on other platforms
prior to APZ support, then a new bug will be created to track a
non-APZ-dependent implementation.

- - Kip

On 2014-05-22, 1:50 PM, Kip Gilbert wrote:
> Summary:
>
> CSSOM-View defines a new css property, 'scroll-behavior'. When set
> to 'smooth', scrolling boxes will be scrolled in a smooth fashion
> using a user-agent-defined function.
>
> Implementing this property will enable more fluid scrolling
> interfaces consistent with modern UI paradigms without needing to
> update the position manually on a frame-by-frame basis in
> Javascript. In much the same way as APZ's fling gestures, the
> fluid scrolling will take over the scroll position updates when
> CSSOM methods or navigation set the scroll position.
>
> Other effects such as smooth-scroll-snapping can be built upon
> this property by setting the scroll position for a smooth scrolling
> box at the end of a dragging event. This is beneficial to
> applications such as the B2G home screen and image carousels.
>
> Bug:
>
> https://bugzilla.mozilla.org/show_bug.cgi?id=1010538
>

> Link to standard:
>
> http://dev.w3.org/csswg/cssom-view/#smooth-scrolling:-the-%27scroll-behavior%27-property
>
>
>

> Platform coverage:
>
> Android, Desktop, Firefox OS
>
> This functionality is beneficial on all platforms. The
> implementation fits naturally within the APZ classes; however, APZ
> may not be available for some time outside of B2G. I would like to
> gauge the demand for this functionality outside of B2G to determine
> if it should be implemented independently of APZ and land earlier
> on other platforms.
>
> Estimated or target release:
>
> TBD
>
> Preference behind which this will be implemented:
>
> layout.css.scroll-behavior.enabled
>
>
>

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJTl2MZAAoJEHziBT1mB5A7j8sIAI9y9pNSibrAIXJdWeLm3j7T
Vtjt5UgbYvjLxAV9UwT0exTcCV1f8/TV31ixpDJdLFmhiPwGq5xHYx5FRE6INlVb
K7PR+fY5fSWbE49MNqRcMH8398lxl1aCZW1QuBI97Z9zthJjeFhFHiF9TZmXN9EP
hQZJTVgWZYerNoraQ31EPjyTOqdek6pRjyFFCGaEdU7quBQqn//YMVo8wCMkX2Wv
xvikXC+uliTFM6xjZAgvu9o+dU95kIrR8XGbpQnuE8vcqnqp2jnxzR0mBDHiq8Xe
ZwSrxjvOzuJXWfqHZkGVZhlLKf3FKgVvNtByWoDoP8vl/pOvq5jz6JSLvYleGao=
=uBE1
-----END PGP SIGNATURE-----

[Kip Gilbert]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

While beginning implementation I noticed that there is smooth
scrolling functionality already implemented within
ScrollFrameHelper::AsyncScroll, using simple splines via
nsSMILKeySpline. This smooth scrolling behavior is used internally
and not exposed with XPCOM or WebIDL bindings.

I would like feedback to determine if this same routine should be
re-cycled, updated to match the proposed movement model, or kept as-is
as a separate implementation for these internal use-cases.

Would it be helpful if I mocked up a visualization to compare the kind
of movement it has to the movement model I proposed for the smooth
scroll behavior?

- - Kip

iQEcBAEBAgAGBQJTl4mPAAoJEHziBT1mB5A7CFYH/i199IyB9p+ckvV7IpQ88JY9
nsWcsdeF4+DHAElNZQoeq6Q5BTzWg4/TVNspQMLwGiZVzE0dy5M35imLMAPE/2ih
fcreDzGe4jAd3LoUb04/Voxob0aEB1wvhpd8DPIUqP1mb1QL2V5HuU5v+y99hgot
ZKL/cOHbg5KgAZk+smQutVLKI2ruAxvUveFVZBvLZ+n+1mz4BmlhE16DDKdSOcwk
AE7PpM7SvAHc2sl/hVOqsCBkPmQ2DiJv7hxQmsq1HZCXwjNQAbhV9bqN2R4yBRNO
yzDua59+eyIMa4toyLxC69QQGhz1bXxDC7RmieSUMoyx0Yxk408XV0omwNFgjvU=
=7eEN
-----END PGP SIGNATURE-----

[Robert O'Callahan]

On Wed, Jun 11, 2014 at 10:41 AM, Kip Gilbert <kgil...@mozilla.com> wrote:

> While beginning implementation I noticed that there is smooth
> scrolling functionality already implemented within
> ScrollFrameHelper::AsyncScroll, using simple splines via
> nsSMILKeySpline. This smooth scrolling behavior is used internally
> and not exposed with XPCOM or WebIDL bindings.
>
> I would like feedback to determine if this same routine should be
> re-cycled, updated to match the proposed movement model, or kept as-is
> as a separate implementation for these internal use-cases.
>

I think we should replace it with your new approach. Where APZC is not
enabled, we should have a version of your new code which works on the main
thread. This would be similar to how AsyncScroll is currently organized.

I don't know of any UX reason to keep the current scrolling feel.