Add initial scroll position hook to HTML spec

[DavMila]

scroll-initial-target is a CSS property which affects an element's initial scroll position. A scroll container's initial scroll position determines what scroll offset that scroll container should be at before any "explicit" scrolling (e.g. user gesture, programmatic scroll API) occurs on it. This initial scroll position is affected by CSS properties such as scroll-initial-target and might change as a document is loaded.

This patch adds a step in the "Updating the document" section of the HTML spec to direct user agents on when to re-evaluate initial scroll positions and adjust accordingly.

• At least two implementers are interested (and none opposed):
  • Chrome
  • Mozilla Request pending
  • WebKit Request pending
• Tests are written and can be reviewed and commented upon at:
  • web-platform-tests
• Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/u/1/issues/40909052
  • Gecko: TBD
  • WebKit: TBD
  • Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): N/A
  • Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): N/A
• MDN issue is filed: TBD
• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

/acknowledgements.html ( diff )
/browsing-the-web.html ( diff )
/infrastructure.html ( diff )

[annevk]

@dbaron would you be willing to review this as well?

[domenic]

I worry about where this integrates into the page lifecycle. It's in "update document for history step application", and occurs in both documentIsNew = true and false cases.

This means:

• It will run for bfcache traversals. This is probably not correct; bfcache traversals should probably just leave the document as it was, instead of performing extra scroll adjustments.

• For new documents, it will run before most of the document content is loaded. This is probably not correct; documents will generally have no scroll containers at this early stage of the process.

Can I ask how you are implementing this in Chromium, and in particular, at what point in the document lifecycle? Do you do so immediately (like this spec), and just ignore the fact that there probably will be no scrollers at this early point? Do you wait for the load or DOMContentLoaded events? Do you do periodic polling and retrying, like the spec's current "try to scroll to the fragment"?

[DavMila]

• It will run for bfcache traversals. This is probably not correct; bfcache traversals should probably just leave the document as it was, instead of performing extra scroll adjustments.
• For new documents, it will run before most of the document content is loaded. This is probably not correct; documents will generally have no scroll containers at this early stage of the process.

Can I ask how you are implementing this in Chromium, and in particular, at what point in the document lifecycle? Do you do so immediately (like this spec), and just ignore the fact that there probably will be no scrollers at this early point? Do you wait for the load or DOMContentLoaded events? Do you do periodic polling and retrying, like the spec's current "try to scroll to the fragment"?

I think you're right that the placement of the step is not correct. I ought to have placed the step within the "If documentIsNew is true" block, and I've done so now. The intent is for it to have similar timing to (but lower priority than) "try to scroll to the fragment" so that user agents treat late-arriving scroll containers and/or their scroll-start-target elements the same way as late-arriving fragments which I believe would still be scrolled to.

[domenic]

The issue is that "try to scroll to the fragment" does a periodic polling operation, which your spec does not. Your spec only tries once, at initial document load, at which point no scrollers will exist.

Again, can I ask how you implemented this in Chromium?

[DavMila]

The issue is that "try to scroll to the fragment" does a periodic polling operation, which your spec does not. Your spec only tries once, at initial document load, at which point no scrollers will exist.

Ah thanks, that's clear to me now.

Again, can I ask how you implemented this in Chromium?

The implementation in Chromium does periodically poll like you asked. I guess the hook I'm adding should follow a similar pattern to "try to scroll to the fragment"?
Perhaps I should:

• keep the placement of the new step ("update the initial scroll positions for scroll containers") in "If documentIsNew is true", and
• modify the new step to periodically poll each scroll container until the user agent believes the user is no longer interested in the initial scroll position.

Let me know if this sounds reasonable or there's a totally different better approach, thanks!

[domenic]

That strategy does sound reasonable, although I wonder if you should merge the algorithm with "try to scroll to the fragment" so that they're not competing with each other. Again, I wonder what you do in Chromium; do you have two separate periodic polling algorithms running, one for fragment and one for scroll containers? Or just one?

[DavMila]

That strategy does sound reasonable, although I wonder if you should merge the algorithm with "try to scroll to the fragment" so that they're not competing with each other. Again, I wonder what you do in Chromium; do you have two separate periodic polling algorithms running, one for fragment and one for scroll containers? Or just one?

In Chromium we poll separately for scrolling to the fragment and scroll containers. And we treat scrolling to the fragment as an "explicit scroll" (like a scroll gesture) as a way of giving it precedence over initial-scroll-position-affecting properties like scroll-start-target.
So a scroll to a fragment would be a reason why the user agent "believes the user is no longer interested in the initial scroll position" (like with a gesture scroll).

[domenic]

LGTM. We can merge after all the checkboxes in the OP are filled out.

Can you be sure that the following are tested in the web platform tests?

• That scrollers inside shadow trees are included
• That the order is shadow-including tree order, not e.g. flat tree order

[skobes-chromium]

@domenic is there a reason you think we should avoid using flat tree order?

[domenic]

I'm not sure what the best order is, but the order specified in this PR is shadow-including tree order, so that's what I would expect to be tested.

[DavMila]

Learned a bit here :) ... I now realize that the difference between flat tree order and shadow-including order is not whether the shadow DOM is included. Rather, it relates to the order of slot-related elements.

I think what we want here is flat tree order since it matches the top-level DOM tree, includes the shadow DOM and traverses through slots in a way that more closely matches what is displayed/layout. I've updated the PR.

[domenic]

The spec is still using shadow-including tree-order though to iterate.

Unlike "shadow-including tree order", which has a clear definition we can link to, I don't see a similar thing for the flat tree. I did find one instance in https://html.spec.whatwg.org/#focus-processing-model which says

pre-order, depth-first traversal of the flat tree

so maybe we can say something similar like

For each scroller of scrollers, in the same order in which they appear during a pre-order, depth-first traversal of the flat tree.

Or we could change the step that assembles scrollers, and then just use the normal list order? Something like this:

Let scrollers be the list obtained by performing a pre-order, depth-first traversal of document's flat tree, and filtering to keep only elements that establish a scrolling box.

For each scroller of scrollers:

Of course, this is all assuming that pre-order, depth-first traversal is the order you want.

---

Also, it unfortunately looks like a merge conflict came into effect over the holidays. If you could try to resolve that, it would be appreciated; if it's giving you trouble though you can leave it to the editors.

[DavMila]

Or we could change the step that assembles scrollers, and then just use the normal list order? Something like this:

Let scrollers be the list obtained by performing a pre-order, depth-first traversal of document's flat tree, and filtering to keep only elements that establish a scrolling box.
For each scroller of scrollers:

Thanks for the suggestion. Yes, pre-order depth-first traversal, which is tree order, is what we want. I've adopted this suggestion.

Also, it unfortunately looks like a merge conflict came into effect over the holidays. If you could try to resolve that, it would be appreciated; if it's giving you trouble though you can leave it to the editors.

I believe I've been able to fix the conflicts.

[domenic]

OK, nice work, this looks good! Please ping me when all the boxes in the OP are checked, and we can get this merged.