Page flashes when navigating between tree entries

[felix-hoc]

Search terms

flashing, rendering, tree, navigation

Expected Behavior

Selecting a different entry in the navigation sidebar does not cause a visible re-render of the tree

Actual Behavior

Selecting a different entry in the navigation sidebar causes a visible re-render of the tree

Steps to reproduce the bug

This can be reproduced on the official Typedoc API page: https://typedoc.org/api/index.html
In Chrome and Firefox. It is less noticeable on more powerful devices, but quite apparent on low-end and midrange devices.
This impacts the user experience.

Screencast.from.2024-01-29.08-07-56.webm

The same thing happens with Typedoc versions from 0.25.1 (tested locally). It is not reproducible with 0.25.0.

I'd appreciate any help on this, or any input on possible config changes to improve it :)

Environment

• Typedoc version: 0.25.7
• TypeScript version: 5.2.2
• Node.js version: v18
• OS: Ubuntu

[Gerrit0]

0.25.0 wrote the entire navigation tree to every page in the generated docs. For large projects, this could mean your generated docs being several gigabytes in size rather than 100mb, so 0.25.1 changed it.

We could hide the entire page until the navigation loads, with a <noscript> override to not hide it, which is what the default-modern-theme does...

[typhonrt]

This is due to the deferred loading of the main.js script and changing state of folders / accordions based on local storage state. It existed before the new navigation effort as well.

[Gerrit0]

Well that was a bit of an adventure I'd rather not repeat... people who think frontend is fun are insane.

I first tried just hiding the page body until the navigation loaded like DMT. This is mostly fine, but really sucks on slow network connections (firefox's regular 2G throttle setting) since it results in a 3-10 second slower page load when loading without a cache than TypeDoc's current method.

I played around with the different throttle options and delays and the best tradeoff that I arrived at is to:

1. With an inline script, hide the entire page (use an inline script rather than in main.js because otherwise the page might load enough to render for a split second, then hide itself)
2. In the same script, set a 500ms timeout. If the navigation hasn't loaded within this time, then it almost certainly isn't cached, and is taking some time to load, so show the page to avoid making people on really slow connections wait longer than they absolutely have to.
3. When the navigation loads and has been rendered to the page, show the page if it hasn't already been shown.

[typhonrt]

Yeah.. That is a little bit of a pain, but comes with the territory of adding dynamic elements to a static site. It sounds like things are robust enough. Can you mark this new inline script with an id so that it can be queried easily.

The DMT likely needs to provide a custom solution still, but I'll take a look at getting it closer to what you have come up with.

[felix-hoc]

@Gerrit0 thanks a lot for your efforts, really appreciate it! 😃 From my perspective, this change improved the UX quite a bit.

[dom-rau]

Hello @Gerrit0,

I have encountered an issue related to the navigation and the changes made in commit 9751e31. Specifically, the navigation scrollbar keeps scrolling up on each page refresh. You can see a demonstration of this issue in Issue #2624.

I saw you solved this issue, but I observed that the navigation scrolling happens only when the navigation is not visible, which seems to be due to the negation in the visibility check !pageLink.checkVisibility().

Does this negation serve a specific purpose?