Repository navigation
Page flashes when navigating between tree entries #2491
Description
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
Activity
Gerrit0 commentedon Jan 31, 2024
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 commentedon Feb 28, 2024
This is due to the deferred loading of the
main.jsscript and changing state of folders / accordions based on local storage state. It existed before the new navigation effort as well.Gerrit0 commentedon Mar 3, 2024
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:
Improve doc HTML output
typhonrt commentedon Mar 6, 2024
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
idso 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 commentedon Mar 11, 2024
@Gerrit0 thanks a lot for your efforts, really appreciate it! 😃 From my perspective, this change improved the UX quite a bit.
dom-rau commentedon Jul 5, 2024
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?