docs(css): Add module landing page for overscroll behavior #30981
Conversation
dipikabh
requested review from
chrisdavidmills
and removed request for
a team
github-actions
bot
added
Content:CSS
Preview URLs (8 pages)
External URLs (2)URL:
URL:
(comment last updated: 2024-01-19 04:27:37) |
|
I'm putting this PR in draft mode as I will be away for a bit and won't be able to attend to any review comments during this time. I plan to open it up for review once I'm back. |
|
Hi @estelle, I'd appreciate if you can review this work when you get the chance. Thanks! |
|
|
||
| {{GlossarySidebar}} | ||
|
|
||
| **Scroll chaining** refers to the behavior observed when scrolling within a scrollable element, such as a `<div>` or `<textarea>`, triggers scrolling in its parent element or the underlying page. This propagation results in a "chained effect", where there is a seamless transition of the scroll action to the parent element when the [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) boundary (top or bottom) of the scrollable element is reached. This behavior creates a continuous scrolling experience. |
There was a problem hiding this comment.
horizontal scrolling is less common as most sites are responsive, but doesn't this also apply to horizontal scrolling?
There was a problem hiding this comment.
Makes sense. Updated those last bits to:
....when the scrollport boundary (top, bottom, left or right) of the scrollable element is reached. This behavior creates a continuous scrolling experience, both vertically and horizontally.
|
|
||
| **Scroll chaining** refers to the behavior observed when scrolling within a scrollable element, such as a `<div>` or `<textarea>`, triggers scrolling in its parent element or the underlying page. This propagation results in a "chained effect", where there is a seamless transition of the scroll action to the parent element when the [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) boundary (top or bottom) of the scrollable element is reached. This behavior creates a continuous scrolling experience. | ||
|
|
||
| You can use the shorthand {{CSSxRef("overscroll-behavior")}} CSS property to customize or disable the browser's default behavior. |
There was a problem hiding this comment.
i think we may want to leave this out, but add the link to see also.
In glossary we generally define terms without explaining how to fix issues regarding the topic at hand.
the module landing page has not yet been written, so we can't link to that. yet.
There was a problem hiding this comment.
Oh, yay, you wrote it. I really should read ahead before commenting ;)
add the module to the see also on this page.
There was a problem hiding this comment.
Done, added both the property and the module to "See also"
|
|
||
| You can use the shorthand {{CSSxRef("overscroll-behavior")}} CSS property to customize or disable the browser's default behavior. | ||
|
|
||
| ## Related terms |
There was a problem hiding this comment.
I would only include the "scroll chain" on this page, without adding the "related terms" header or even "scroll chain" header, since the term is contained in the title of the page, while making the term bold, so it can be viewed as a slightly different term.
the boundary default terms don't necessarily need to be defined in the glossary, though a guide would be good. The scroll boundary should be it's own glossary entry, with a link from overscroll behavior:
Description
By default, mobile browsers tend to provide a "bounce" effect or even a page refresh when the top or bottom of a page (or other scroll area) is reached. You may also have noticed that when you have a dialog box with scrolling content at the top of a page that also has scrolling content, once the dialog box's {{glossary("scroll boundary")}} is reached, the underlying page will then start to scroll — this is called {{glossary("scroll chaining")}}.
There was a problem hiding this comment.
ah, you already committed that second link. great minds think alike.
The same paragraph appears in 4 places: the one you did (overscroll-behavior), overscroll-behavior-x, overscroll-behavior-inline, and overscroll-behavior-block
There was a problem hiding this comment.
I did not find the same paragraph as is on those pages, but I've added a link to the glossary scroll chaining wherever the term appeared on those pages as well as in overscroll-behavior-y
There was a problem hiding this comment.
I've created a new glossary page for scroll boundary and moved the content from scroll chaining over to scroll boundary
There was a problem hiding this comment.
the boundary default terms don't necessarily need to be defined in the glossary, though a guide would be good.
The way they are written now, I think it would be best to keep them here in the glossary in the new scroll boundary glossary page. And then we can link to these terms when we have guides. WDYT?
| It also covers the following terms: | ||
| - [Scroll boundary](/en-US/docs/Glossary/Scroll_chaining#scroll_boundary) | ||
| - [Boundary default action](/en-US/docs/Glossary/Scroll_chaining#boundary_default_action) | ||
| - [Local and non-local boundary defaults](/en-US/docs/Glossary/Scroll_chaining#local_and_non-local_boundary_defaults) |
There was a problem hiding this comment.
| It also covers the following terms: | |
| - [Scroll boundary](/en-US/docs/Glossary/Scroll_chaining#scroll_boundary) | |
| - [Boundary default action](/en-US/docs/Glossary/Scroll_chaining#boundary_default_action) | |
| - [Local and non-local boundary defaults](/en-US/docs/Glossary/Scroll_chaining#local_and_non-local_boundary_defaults) |
we can add scroll boundary when it has it's own page.
There was a problem hiding this comment.
Added link to the new scroll boundary glossary page.
While I can remove links to the terms "Boundary default action" and "Local and non-local boundary defaults" from here, I think we should still have them around in the glossary page because they are terms defined in this spec: https://drafts.csswg.org/css-overscroll/#index-defined-here
| - {{Glossary("Scroll_container")}} glossary term | ||
| It also covers the following term: | ||
| - [Scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) |
There was a problem hiding this comment.
| - {{Glossary("Scroll_container")}} glossary term | |
| It also covers the following term: | |
| - [Scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) | |
| - {{Glossary("Scroll_container")}} glossary term | |
| - [Scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) glossary term |
or, alternatively,
- {{Glossary("Scroll_container")}} and [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) glossary terms
There was a problem hiding this comment.
I've gone with your second suggestion because I wanted to somehow convey that "scrollport' is on the same page that describes scroll containers.
| - [CSS building blocks: Overflowing content](/en-US/docs/Learn/CSS/Building_blocks/Overflowing_content) | ||
| - : Learn what overflow is and how to manage it. | ||
|
|
||
| ## Related concepts |
There was a problem hiding this comment.
Alternatively, we can include a list like in https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations without listing the specs.
It does make sense to include all the concepts you have included. But we just have one item from each spec and they're not necessarily a "feature" (a feature being a property, at rule, data type) of that spec. My thought is that if we didn't have "related concepts" and only had a "see also", the only one of these modules i would add to the see also is overflow, though i would also include box model and box-sizing (module page for this doesn't seem to exist) and possible CSS_logical_properties_and_values (though not sure that's necessary)
There was a problem hiding this comment.
For the "Related concepts" section, I went with the guidance of "Terms defined by reference" section from the spec. Because for the sake of the module landing page template guideline, we should be able to say what the source or inspiration for "Related concepts" section is. This makes it easier for other authors to determine objectively what to add here.
Even in https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations#related_concepts, I think it might be nice to indicate what modules/specs the listed concepts/features are part of. This was my attempt to try to do that. 🙂 And by grouping them module-wise, I was trying to avoid repeating the module name for each.
What do you think about the following format. They're listed here in the order of concepts, properties, methods, and glossary terms. You can see the preview in this commit 5980812:
## Related concepts
- Containing block concept (CSS display module)
- overflow CSS property (CSS overflow module)
- position CSS property (CSS positioned layout module)
- getBoundingClientRect method (CSSOM view module)
- Scroll container and scrollport glossary terms (CSS overflow module)
though i would also include box model and box-sizing (module page for this doesn't seem to exist) and possible CSS_logical_properties_and_values (though not sure that's necessary)
👍
I can add these to "See also"
There was a problem hiding this comment.
The reason a term is in any of the "Terms defined by reference" sections of a spec is not because they are necessarily related, but because they were mentioned, often just in passing as an example.
|
|
||
| ## Guides | ||
|
|
||
| - [CSS building blocks: Overflowing content](/en-US/docs/Learn/CSS/Building_blocks/Overflowing_content) |
There was a problem hiding this comment.
until we have a guide on MDN, we should consider adding an extern guide maybe https://developer.chrome.com/blog/overscroll-behavior/ or https://css-tricks.com/almanac/properties/o/overscroll-behavior/. Note css tricks is no longer maintained. so i think the chrome one is likely better. You may have a better suggestion.
There was a problem hiding this comment.
Thanks. I added the chrome blog link to "See also".
It is already linked in the "See also" on overscroll-behavior property page (https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior#see_also)
|
|
||
| {{CSSRef}} | ||
|
|
||
| The **CSS overscroll behavior** module properties enable you to control the behavior of a scroll container when its scroll position reaches the scroll boundary. Controlling this aspect is particularly useful in scenarios where embedded scrollable areas should not trigger scrolling of the parent container. |
There was a problem hiding this comment.
It would be good to describe what occurs by default, and what experience the features in this module enable. Readers may not fully understand these terms: scroll containe, scroll position, scroll boundary, embedded , scrollable areas, or trigger scrolling (hopefully they understand parent container.
Here's a very rough draft of a possible outline
| The **CSS overscroll behavior** module properties enable you to control the behavior of a scroll container when its scroll position reaches the scroll boundary. Controlling this aspect is particularly useful in scenarios where embedded scrollable areas should not trigger scrolling of the parent container. | |
| The **CSS overscroll behavior** module provides properties to enable or prevent scroll chaining and overscroll. | |
| If you have ever commented on a blog, you may have noticed if your comment is longer than the few lines provided by the {{htmlement("textarea")}}, scrolling past the end of the text area makes the whole blog scroll. Reaching the end of a scroll, known as a scroll boundary, may cause other content or the full page to scroll. This continuous scrolling experience is called scroll chaining. | |
| If you've ever quickly scrolled through a website's terms and conditions to enable a checkbox, reaching the end of the content may not force the page scroll (or bounce if you're reading on your phone). You can control this overscroll behavior and prevent scroll chaining is preventable. This module defines the overscroll behavior, enabling you to define what should happen when the user scrolls beyond the boundaries of a scollable element. | |
| If the contents of an element are larger than its container, and {{cssxref("overflow")}} is set to or defaults to allow scrolling as with `<textarea>`, when the user continues scrolling past the end of that elements scrollable area, the parent element or the underlying page will start scrolling. | |
| ## Overscroll behavior in action | |
| To enable and disable overscroll behavior in the box below, click the checkbox 'Toggle overscroll' then scroll the inner box. When overscroll is contained, the parent box will not start scrolling when your scroll to the edge of the inner box. When it isn't contained, the outer box will start scrolling. |
Then include a prettified version of the interactive example at the top of https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior
There was a problem hiding this comment.
Not sure if you saw the above....
There was a problem hiding this comment.
That's because I wasn't done addressing all of your review comments 😄. I left adding fixes mid-way last night with plans to resume with addressing the two remaining comments
There was a problem hiding this comment.
For the intro para here, I think for the module page, we can let it be a more expanded version because this won't show up in other tools like property descriptions. I would prefer to not have a new, unexplained term (scroll chaining) in the intro para or we would need to link it to its glossary page. By saying "where embedded scrollable areas should not trigger scrolling of the parent container", we're essentially referring to "scroll chaining" without mentioning the term. WDYT?
There was a problem hiding this comment.
I've included the next three paragraphs you wrote (thank you!!), in slightly edited and reorganized way though (8eddc78). LMK what you think. I hope I haven't introduced any technical inaccuracy.
When commenting on a blog, you might notice that if your comment exceeds the length of the provided {{htmlement("textarea")}}, scrolling beyond the end of the text area causes the entire blog to scroll. This is because reaching the end of a scrollable area, known as the scroll boundary, can lead to scrolling other content or the entire page. This continuous scrolling experience is called {{Glossary("Scroll_chaining", "scroll chaining")}}.
In situations where the contents of an element are larger than its container, and {{cssxref("overflow")}} allows or defaults to scrolling (like in
<textarea>), continued scrolling past the element's scrollable area will initiate scrolling in the parent element or the underlying page.
Conversely, scrolling through a website's terms and conditions and reaching the end of the content to enable a checkbox, may not force the page to scroll or bounce (as on a phone). This example shows that you can control overscroll behavior and prevent scroll chaining.
This module defines the overscroll behavior, enabling you to specify the actions when a user scrolls beyond the boundaries of a scrollable element.
There was a problem hiding this comment.
Like I mentioned in the PR description, I'd like to skip the "Overscroll behavior in action" section in this PR and attempt it in a follow up PR.
|
This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size. |
dipikabh
removed request for
a team,
pepelsbey,
fred-wang,
willdurand,
Ryuno-Ki,
wbamberg and
teoli2003
|
This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size. |
|
This PR exceeds the recommended size of 1000 lines. Please make sure you are NOT addressing multiple issues with one PR. Note this PR might be rejected due to its size. |
|
|
||
| {{CSSRef}} | ||
|
|
||
| The **CSS overscroll behavior** module properties enable you to control the behavior of a scroll container when its scroll position reaches the scroll boundary. Controlling this aspect is particularly useful in scenarios where embedded scrollable areas should not trigger scrolling of the parent container. |
There was a problem hiding this comment.
Not sure if you saw the above....
| ## See also | ||
|
|
||
| - [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module | ||
| - [Take control of your scroll - customizing pull-to-refresh and overflow effects](https://developer.chrome.com/blog/overscroll-behavior) on developer.chrome.com (2017) |
There was a problem hiding this comment.
I meant to add the guide under guides. If it's already linked from an internal page, we don't need to link here. We need to write a guide 😐
There was a problem hiding this comment.
IMO we should list MDN guides in the Guides section, that's why I added this link in "See also" instead (my comment).
I don't think it hurts to keep it in the "See also" here as well, at least until we have our own guide.
| - [CSSOM view](/en-US/docs/Web/CSS/CSSOM_view) module: | ||
|
|
||
| - [getBoundingClientRect](/en-US/docs/Web/API/Element/getBoundingClientRect) method | ||
|
|
||
| - [CSS display](/en-US/docs/Web/CSS/CSS_display) module: | ||
|
|
||
| - [Containing block](/en-US/docs/Web/CSS/Containing_block) | ||
|
|
||
| - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module: | ||
|
|
||
| - {{cssxref("overflow")}} CSS property | ||
| - {{Glossary("Scroll_container", "Scroll container")}} and [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) glossary terms | ||
|
|
||
| - [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module: | ||
|
|
||
| - {{CSSxref("position")}} property |
There was a problem hiding this comment.
| - [CSSOM view](/en-US/docs/Web/CSS/CSSOM_view) module: | |
| - [getBoundingClientRect](/en-US/docs/Web/API/Element/getBoundingClientRect) method | |
| - [CSS display](/en-US/docs/Web/CSS/CSS_display) module: | |
| - [Containing block](/en-US/docs/Web/CSS/Containing_block) | |
| - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module: | |
| - {{cssxref("overflow")}} CSS property | |
| - {{Glossary("Scroll_container", "Scroll container")}} and [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) glossary terms | |
| - [CSS positioned layout](/en-US/docs/Web/CSS/CSS_positioned_layout) module: | |
| - {{CSSxref("position")}} property | |
| - [`scrollbar`](/en-US/docs/Web/Accessibility/ARIA/Roles/scrollbar_role) ARIA role | |
| - [Containing block](/en-US/docs/Web/CSS/Containing_block) concept | |
| - [CSS overflow](/en-US/docs/Web/CSS/CSS_overflow) module: | |
| - {{cssxref("overflow")}} shorthand property | |
| - {{Cssxref("overflow-x")}} | |
| - {{Cssxref("overflow-y")}} | |
| - {{CSSxRef("overflow-block")}} | |
| - {{CSSxRef("overflow-inline")}} | |
| - {{CSSxRef("overflow-clip-margin")}} property | |
| - {{CSSxRef("scroll-behavior")}} property | |
| - {{CSSxRef("text-overflow")}} property | |
| - {{Glossary("Scroll_container", "Scroll container")}} and [scrollport](/en-US/docs/Glossary/Scroll_container#scrollport) glossary terms | |
| - [CSS scroll snap](/en-US/docs/Web/CSS/CSS_scroll_snap) module: | |
| - {{cssxref("scroll-padding")}} shorthand property | |
| - {{cssxref("scroll-snap-type")}} property | |
| - {{cssxref("scroll-margin")}} shorthand property | |
| - {{cssxref("scroll-snap-stop")}} property | |
| - {{cssxref("scroll-snap-align")}} property | |
| - [CSSOM view](/en-US/docs/Web/CSS/CSSOM_view) module: | |
| - {{domxref("Element.getBoundingClientRect()")}} method | |
| - {{domxref("Element.scroll()")}} method | |
| - {{domxref("Element.scrollBy()")}} method | |
| - {{domxref("Element.scrollIntoView()")}} method | |
| - {{domxref("Element.scrollTo()")}} method | |
| - {{domxref("Document.scroll_event", "scroll")}} Document event |
There was a problem hiding this comment.
The idea is to include features that someone interested in this module may find relevant, not just to cover what is in the specification. We also don't need to include all therms in the specification; otherwise <color> and <length> would likely be on every module page. We want to surface stuff that is important to web developers over browser devs. (The spec is geared in the opposite: what is important to browser (rather than "web") developers as the focus)
There was a problem hiding this comment.
the scroll snap is in that weird order b/c i put parent properties first then child properties.
That said, this suggestion needs work, but hoping it provides a good start.
There was a problem hiding this comment.
Uh oh, I just redid this to undo my previous format based on your earlier feedback - see my comment #30981 (comment). I wasn't done addressing your comments from last week.
The idea is to include features that someone interested in this module may find relevant, not just to cover what is in the specification. We also don't need to include all therms in the specification; otherwise and would likely be on every module page. We want to surface stuff that is important to web developers over browser devs. (The spec is geared in the opposite: what is important to browser (rather than "web") developers as the focus)
I see what you're saying but it also makes the process of updating this section very subjective.
Some of the additional and relevant concepts and properties can be moved to "See also", for example the scrollbar ARIA role in your list here.
|
@estelle Thanks for the review and your valuable inputs! I've now incorporated your feedback from both last week and today. I've left some comments unresolved so you can check if the fixes/responses adequately answer your feedback.
|
There was a problem hiding this comment.
Two small edits other than the related concepts. With some specs, the "by reference" makes sense, such as with https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_syntax. Other specs, the concepts are very related, but not necessarily mentioned in the spec. Related concepts is where we achieve the goal of "surfacing content" (the goal from the 2023 London mtg). All the scroll modules are related; though not all of all of the features introduced,
| - [CSS building blocks: Overflowing content](/en-US/docs/Learn/CSS/Building_blocks/Overflowing_content) | ||
| - : Learn what overflow is and how to manage it. | ||
|
|
||
| ## Related concepts |
There was a problem hiding this comment.
The reason a term is in any of the "Terms defined by reference" sections of a spec is not because they are necessarily related, but because they were mentioned, often just in passing as an example.
|
Thanks @estelle for taking a look again. I've fixed the last two edit suggestions. I've also updated the "Related concepts" section as per your suggestion in this comment. |
Description
This PR creates a new module landing page for the overscroll behavior module. It also creates a new glossary page to explain some related relevant terms.
Note that at this moment the module landing page does not include the "in action" section. I hope it can be taken up in a subsequent PR.
Spec: https://drafts.csswg.org/css-overscroll/
Motivation
Scrolling is a focus area in Interop 2023. Overscroll behavior is one of the features covered in scrolling.
Related issues and pull requests
This work is being tracked through the doc issue mdn/mdn#416.
TO DO