doc: weird scrolling/anchor behavior in Chrome and Firefox

[mscdex]

📗 API Reference Docs Problem

Location

Affected URL(s):

• https://nodejs.org/docs/latest/api/modules.html

Description

At least on Linux and with Chrome, if you load a very long page, like the CommonJS modules API page, and you either press the End key or otherwise scroll to the bottom and then attempt to scroll up or hold down the Page Up key, the scroll bar makes a lot of strange jumps (backwards and forwards). Even starting at the top of the page and scrolling down causes the scroll bar to do some large, sudden, and unexpected jumps. However, using the Home and End keys seemingly work just fine.

My guess is there is either some javascript on the page listening for scrolling events in general or on particular elements (like code blocks) and that is somehow causing the weird issues.

[aduh95]

We're using the CSS property content-visibility (https://web.dev/content-visibility/) on the HTML version of the docs so it doesn't take forever to render pages on Chromium-based browsers. One of the downside of using this property is the scroll bar makes indeed some strange jumps. It was introduced in #37301.

[mscdex]

I wonder if the kind of solution described here or something similar would solve these problems?

It's very frustrating not being able to properly navigate the documentation a page at a time or by sliding the scroll bar. It seems to me like the browser should keep elements rendered after it's rendered the first time, which should solve the scrolling problem. It seems like the solution I linked to explicitly does this?

[aduh95]

Yep that looks promising indeed. Would you be interested in sending a PR? On the mean time (and I know this is not a satisfactory answer to that issue, more a temporary workaround), you may find Firefox more suitable to browse the docs as they haven't implemented content-visibility and they also able to render large pages in a reasonable time.

[himself65]

It works fine on macOS Chrome

[szmarczak]

I think this also causes an issue if you try to open any URL with a hash in a new tab. It doesn't scroll to the desired method / property.

[saltybuckets]

I am working on this rn

[noinkling]

I hate to pile on but this issue has made browsing the API docs an exercise in frustration for a while now. The scrollbar jumps all over the place when trying to drag it, as well as the yellow indicators when you do a ctrl+f. I never end up in the correct place when following an anchor link.

I'm surprised there haven't been more reports after all this time, surely it's more than just a handful of us affected? Chrome on Windows here. Firefox seems fine as mentioned.

[ovflowd]

@mscdex, for reading the current open Issue, for me, the takes are the following:

• The original content-visibility was introduced to reduce the re-paint on resizing of pages or other shenanigans
• It also had the benefit of a smaller initial rendering footprint

Then there's the discussion about if it should be removed:

• It would fix anchor link positioning behaviour, which is an important aspect of the experience
• It would allow scrolling behaviour to be respected

There's, of course, the approach of doing some JavaScript spaghetti, as I saw in some random blog post. Still, I'm severely against having arbitrary JavaScript code that tries to "fix" the web (by inherently trying to change how certain behaviours happen).

What I imagine as an "ideal" solution for now:

• Remove the content-visibility API.
  • 99th percentile of devices nowadays are efficient enough to render even the longest pages hassle-free. Of course, constant resizes of the page on desktop browsers will increase the CPU heap during the resize by a lot, but that's an OKAY outcome. People will only sometimes resize their pages; that is an edge case, imho.
• Add CSS grids for the two columns.
  • This page was probably done before the time of CSS grids.
  • It would allow us to remove a few margin-padding hacks
  • It would fix the width issue that happens due to content-visibility being removed
  • Enforces the maximum width of the second column and respects the page size

Regarding modern technologies:

Modern browsers and rendering engines are already smart enough to offload computing from complex parts.

I did some synthetic loads on the current API website with content-visibility disabled and requested Chrome to profile the page. I tried to do intensive scrolling behaviour to check for bottlenecks. I saw no significant bottlenecks, CPU-heap increase or significant delays/increase on the repainting/re-rendering of the page.

Moreover, disabling content-visibility shouldn't be a problem. I tried the same behaviour on an iPhone by using remote DevTools to disable those CSS rules. Didn't see any noticeable lag.

Of course, some real old phones or hardware would struggle a little. But given that technology is ever-evolving, I doubt someone would consistently open our API docs on a tiny smartphone from 7 years ago...

I feel inclined toward the approach/solution I mentioned above.

[aduh95]

• 99th percentile of devices nowadays are efficient enough to render even the longest pages hassle-free.

I wonder where you get that figure from, in my experience loading the all.html on a Chromium browser was a real struggle for my 2019 MBP, and I’m pretty sure that’s not the lowest spec you’ll find out there. But maybe Google or Microsoft fixed that since I made the measurements reported in #37301 (comment)