From b3ca756de8dec95fc6616c3b4b29ee2aaccb070e Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Tue, 12 Nov 2024 10:45:40 -0500 Subject: [PATCH 01/10] Add initial scroll position hook to HTML spec 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 and may change as a document is loaded, fetches content/stylesheets, and runs script. 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. --- source | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/source b/source index 9d45f686ac5..75828949bda 100644 --- a/source +++ b/source @@ -3904,6 +3904,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
  • The 'overflow' property and its 'hidden' value
  • The 'text-overflow' property
  • The term scroll container +
  • The term initial scroll position

    The following terms and features are defined in CSS Positioned Layout: @@ -103718,6 +103719,8 @@ location.href = '#foo';

    • +
  • Update the initial scroll positions for scroll containers in document.
    • +

  • If documentIsNew is true, then: @@ -103879,6 +103882,27 @@ location.href = '#foo';

    • +

    To update the initial scroll positions for scroll containers in a + Document document, + perform the following steps:

    + +
      +

    1. Let scrollers be the list of all + scroll containers within document.

      2. + +
    2. +

      For each scroller in scrollers:

      +
        +

      1. If the user agent has reason to believe the user is no longer interested in scrolling + to scroller's initial scroll + position, then abort these steps.

        2. + +

      2. Update scroller's initial scroll + position and scroll scroller to it.

        3. +
      +
      3. +
    +

    To make document unsalvageable, given a Document document and a string reason:

    @@ -145050,6 +145074,7 @@ INSERT INTERFACES HERE Dave Singer, Dave Tapuska, Dave Townsend, + David Awogbemila, David Baron, David Bloom, David Bokan, From 9d8f00bb2a70dd1a2290dcb4fb07d8cdba7e2ba5 Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Thu, 14 Nov 2024 10:00:43 -0500 Subject: [PATCH 02/10] Fix indentation; improve references & links --- source | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/source b/source index 569699053ad..68eab592ed8 100644 --- a/source +++ b/source @@ -4062,6 +4062,8 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
  • The scrollend event
  • set up browsing context features
  • The clientX and clientY extension attributes of the MouseEvent interface
    • +
  • The term perform a scroll
    • +
  • The term scrolling box

    • The following features and terms are defined in CSS Syntax: @@ -104729,22 +104731,26 @@ location.href = '#foo';

    To update the initial scroll positions for scroll containers in a - Document document, - perform the following steps:

    + Document document:

      -

    1. Let scrollers be the list of all - scroll containers within document.

      2. +

    2. Let scrollers be a list of all + scroll containers of document.

    3. -

      For each scroller in scrollers:

      +

      For each scroller of scrollers: +

      +

      1. If the user agent has reason to believe the user is no longer interested in scrolling - to scroller's initial scroll - position, then abort these steps.

        2. + to scroller's initial scroll position + , then abort these steps.

        + +

      2. Let position be the initial scroll + position of scroller.

        3. -

      3. Update scroller's initial scroll - position and scroll scroller to it.

        4. +

      4. Perform a scroll of scroller's scrolling box to position.

    From 591aab44ba5a36126d8e3ace1d43df63b629b01c Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Fri, 15 Nov 2024 12:33:31 -0500 Subject: [PATCH 03/10] Fix step placement Step should happen within "If documentIsNew" block like fragment-scroll. --- source | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source b/source index 68eab592ed8..1128586728b 100644 --- a/source +++ b/source @@ -104567,12 +104567,13 @@ location.href = '#foo'; -
  • Update the initial scroll positions for scroll containers in document.
    • -

  • If documentIsNew is true, then:

      +

    1. Update the initial scroll positions for scroll containers in + document.

      2. +

    2. Try to scroll to the fragment for document.

    3. At this point scripts may run for the newly-created document From 956e7aed780183599678ae728ed03a520b2790e0 Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Mon, 2 Dec 2024 10:44:04 -0500 Subject: [PATCH 04/10] Poll scroll containers separately and repeatedly There might be no scroll containers the first time the algorithm runs, so we need to keep polling until the user agent believes the user is no longer interested in the initial scroll position. --- source | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/source b/source index 1128586728b..7a595bb36eb 100644 --- a/source +++ b/source @@ -104734,7 +104734,7 @@ location.href = '#foo';

      To update the initial scroll positions for scroll containers in a Document document:

      -
        +

        1. Let scrollers be a list of all scroll containers of document.

          2. @@ -104743,19 +104743,38 @@ location.href = '#foo';

            -

          1. If the user agent has reason to believe the user is no longer interested in scrolling - to scroller's initial scroll position - , then abort these steps.

            2. - -

          2. Let position be the initial scroll - position of scroller.

            3. - -

          3. Perform a scroll of scroller's scrolling box to position.

            4. +

          4. Update the initial scroll position for scroller.

        +

        To update the initial scroll position for a + scroll container scroller perform the following + steps in parallel:

        + +
          +

        1. Wait for an implementation-defined amount of time. (This is intended to allow + the user agent to optimize the user experience in the face of performance concerns.)

          2. + +
        2. +

          Queue a global task on the navigation and traversal task source + given document's relevant global object to run these steps:

          + +
            +

          1. If the user agent has reason to believe the user is no longer interested in scrolling + to scroller's initial scroll position + , then abort these steps.

            2. + +

          2. Let position be the initial scroll + position of scroller.

            3. + +

          3. Perform a scroll of scroller's scrolling box to position.

            4. + +

          4. Update the initial scroll position for scroller.

            5. +
          +
        +

        To make document unsalvageable, given a Document document and a string reason:

        From f9e3e2d55b4c5ab87e58292d4db67befab8167cd Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Fri, 6 Dec 2024 14:07:54 -0500 Subject: [PATCH 05/10] Add initial scroll position hook to html spec. A few improvements. --- source | 39 ++++++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/source b/source index 7a595bb36eb..47fd2109177 100644 --- a/source +++ b/source @@ -3910,6 +3910,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      1. The 'text-overflow' property
      2. The term scroll container
      3. The term initial scroll position +
      4. The term scrollable overflow rectangle

        The following terms and features are defined in CSS Positioned Layout: @@ -104734,23 +104735,24 @@ location.href = '#foo';

        To update the initial scroll positions for scroll containers in a Document document:

        -
          -

        1. Let scrollers be a list of all - scroll containers of document.

          2. +
            +

          1. Let scrollers be a list of every element which is a + shadow-including descendant of + document and establishes a scrolling box.

            2. -
          2. -

            For each scroller of scrollers: -

            +
          3. +

            For each scroller of + scrollers, in tree order:

            -
              -

            1. Update the initial scroll position for scroller.

              2. -
            -
            4. +
              +

            1. Update the initial scroll position for scroller.

            + +
          -

          To update the initial scroll position for a - scroll container scroller perform the following - steps in parallel:

          +

          To update the initial scroll position for an element scroller, + perform the following steps in parallel:

          1. Wait for an implementation-defined amount of time. (This is intended to allow @@ -104762,14 +104764,17 @@ location.href = '#foo';

            1. If the user agent has reason to believe the user is no longer interested in scrolling - to scroller's initial scroll position - , then abort these steps.

              2. + to the initial scroll position of the + scrollable overflow rectangle of scroller's scrolling box, + then abort these steps.

            2. Let position be the initial scroll - position of scroller.

              3. + position of the scrollable overflow rectangle of scroller's + scrolling box.

            3. Perform a scroll of scroller's scrolling box to position.

              4. + data-x="scrolling box">scrolling box to position, with scroller + as the associated element.

            4. Update the initial scroll position for scroller.

            From e7f8f0f4b43b78436a50abcb4ee74905bae16ad4 Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Mon, 9 Dec 2024 09:20:40 -0500 Subject: [PATCH 06/10] Specify shadow-including order and note difference in scrolling goals The search for scroll containers includes shadow trees, so the list traversal order should account for shadow trees. Adds a note to clarify the recursive nature of "update initial scroll positions for scroll containers" as it differs from "try to scroll to the fragment." --- source | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/source b/source index 47fd2109177..f775a85e6a0 100644 --- a/source +++ b/source @@ -104743,7 +104743,7 @@ location.href = '#foo';

          2. For each scroller of - scrollers, in tree order:

            + scrollers, in shadow-including tree order:

            1. Update the initial scroll position for scroller.

              2. @@ -104754,6 +104754,17 @@ location.href = '#foo';

              To update the initial scroll position for an element scroller, perform the following steps in parallel:

              +

              Although try to scroll to the fragment and + update the initial scroll positions for scroll containers take place at the same + point, and both use a polling system to prediodically re-attempt the scrolling, their goals are + different. Try to scroll to the fragment polls repeatedly until the + indicated part is found since it might take a while for the element to show up during + the document load. Update the initial scroll positions for scroll containers does not + have such a finish condition; it can run indefinitely, as long as the user does not indicate + disinterest. This is necessary to achieve the desired behavior of keeping a + scroll container anchored to the position indicated by CSS properties that determine + the initial scroll position.

              +

              1. Wait for an implementation-defined amount of time. (This is intended to allow the user agent to optimize the user experience in the face of performance concerns.)

                2. From cbe1546f46c82b99b83b56ec9cc4c6e91064e55b Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Mon, 9 Dec 2024 09:31:42 -0500 Subject: [PATCH 07/10] Position note aobut recursion better --- source | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source b/source index f775a85e6a0..90523ba33f2 100644 --- a/source +++ b/source @@ -104754,17 +104754,6 @@ location.href = '#foo';

                To update the initial scroll position for an element scroller, perform the following steps in parallel:

                -

                Although try to scroll to the fragment and - update the initial scroll positions for scroll containers take place at the same - point, and both use a polling system to prediodically re-attempt the scrolling, their goals are - different. Try to scroll to the fragment polls repeatedly until the - indicated part is found since it might take a while for the element to show up during - the document load. Update the initial scroll positions for scroll containers does not - have such a finish condition; it can run indefinitely, as long as the user does not indicate - disinterest. This is necessary to achieve the desired behavior of keeping a - scroll container anchored to the position indicated by CSS properties that determine - the initial scroll position.

                -

                1. Wait for an implementation-defined amount of time. (This is intended to allow the user agent to optimize the user experience in the face of performance concerns.)

                  2. @@ -104788,6 +104777,17 @@ location.href = '#foo'; as the associated element.

                2. Update the initial scroll position for scroller.

                  3. + +

                  Although try to scroll to the fragment and + update the initial scroll positions for scroll containers take place at the same + point, and both use a polling system to prediodically re-attempt the scrolling, their goals are + different. Try to scroll to the fragment polls repeatedly until the + indicated part is found since it might take a while for the element to show up during + the document load. Update the initial scroll positions for scroll containers does not + have such a finish condition; it can run indefinitely, as long as the user does not indicate + disinterest. This is necessary to achieve the desired behavior of keeping a + scroll container anchored to the position indicated by CSS properties that determine + the initial scroll position.

              From 11bb2ae815876baa7374c2209785793a7c3bbb9f Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Tue, 10 Dec 2024 11:20:34 +0900 Subject: [PATCH 08/10] Tweaks, mostly wrapping --- source | 53 ++++++++++++++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/source b/source index 90523ba33f2..86dc9cd8177 100644 --- a/source +++ b/source @@ -104707,6 +104707,8 @@ location.href = '#foo';
            +
            +

            To try to scroll to the fragment for a Document document, perform the following steps in parallel:

            @@ -104736,14 +104738,13 @@ location.href = '#foo'; Document document:

              -

            1. Let scrollers be a list of every element which is a - shadow-including descendant of - document and establishes a scrolling box.

              2. +

            2. Let scrollers be a list of every element which is a shadow-including descendant of document + and establishes a scrolling box.

            3. -

              For each scroller of - scrollers, in shadow-including tree order:

              +

              For each scroller of scrollers, in + shadow-including tree order:

              1. Update the initial scroll position for scroller.

                2. @@ -104751,8 +104752,8 @@ location.href = '#foo';
              -

              To update the initial scroll position for an element scroller, - perform the following steps in parallel:

              +

              To update the initial scroll position for an element scroller, perform + the following steps in parallel:

              1. Wait for an implementation-defined amount of time. (This is intended to allow @@ -104762,35 +104763,37 @@ location.href = '#foo';

                Queue a global task on the navigation and traversal task source given document's relevant global object to run these steps:

                -
                  -

                1. If the user agent has reason to believe the user is no longer interested in scrolling - to the initial scroll position of the +

                    +

                  1. If the user agent has reason to believe the user is no longer interested in scrolling to + the initial scroll position of the scrollable overflow rectangle of scroller's scrolling box, then abort these steps.

                  2. Let position be the initial scroll position of the scrollable overflow rectangle of scroller's scrolling box.

                    3. - +

                  3. Perform a scroll of scroller's scrolling box to position, with scroller - as the associated element.

                    4. + data-x="scrolling box">scrolling box to position, with scroller as + the associated element.

                  4. Update the initial scroll position for scroller.

                    5. - -

                    Although try to scroll to the fragment and - update the initial scroll positions for scroll containers take place at the same - point, and both use a polling system to prediodically re-attempt the scrolling, their goals are - different. Try to scroll to the fragment polls repeatedly until the - indicated part is found since it might take a while for the element to show up during - the document load. Update the initial scroll positions for scroll containers does not - have such a finish condition; it can run indefinitely, as long as the user does not indicate - disinterest. This is necessary to achieve the desired behavior of keeping a - scroll container anchored to the position indicated by CSS properties that determine - the initial scroll position.

                  +
                +

                Although try to scroll to the fragment and update the initial + scroll positions for scroll containers take place at the same point, and both use a polling + system to prediodically re-attempt the scrolling, their goals are different. Try to scroll + to the fragment polls repeatedly until the indicated part is found since it + might take a while for the element to show up during the document load. Update the initial + scroll positions for scroll containers does not have such a finish condition; it can run + indefinitely, as long as the user does not indicate disinterest. This is necessary to achieve the + desired behavior of keeping a scroll container anchored to the position indicated by + CSS properties that determine the initial scroll position.

                + +
                +

                To make document unsalvageable, given a Document document and a string reason:

                From 50a9b55e0c3895f750f6e52b15f684388135491c Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Mon, 13 Jan 2025 13:53:36 -0500 Subject: [PATCH 09/10] Use flat tree instead of shadow-including --- source | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source b/source index 86dc9cd8177..2424800bd56 100644 --- a/source +++ b/source @@ -104738,8 +104738,8 @@ location.href = '#foo'; Document document:

                  -

                1. Let scrollers be a list of every element which is a shadow-including descendant of document +

                2. Let scrollers be a list of every element which is a + flat tree descendant of document and establishes a scrolling box.

                3. From aef780c3c6658bedfc0007c52e6759a257252e14 Mon Sep 17 00:00:00 2001 From: David Awogbemila Date: Mon, 20 Jan 2025 10:00:39 -0500 Subject: [PATCH 10/10] Iterate flat tree with tree order --- source | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/source b/source index 2424800bd56..993ecb58413 100644 --- a/source +++ b/source @@ -104738,13 +104738,12 @@ location.href = '#foo'; Document document:

                    -

                  1. Let scrollers be a list of every element which is a - flat tree descendant of document - and establishes a scrolling box.

                    2. +

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

                  3. -

                    For each scroller of scrollers, in - shadow-including tree order:

                    +

                    For each scroller of scrollers:

                    1. Update the initial scroll position for scroller.