Left Side Panel Very Slow

[bhelyer]

Description

(Apologies for using the Apple hosted documentation rather than reproducing locally. I'm not much of web developer.)

If I look at a documentation page for Swift's libraries, let's take https://developer.apple.com/documentation/swift/string/subsequence as our example, the time taken to scroll the left frame is longer than I would expect. On my slower machine (AMD A6, 8 gigs of RAM) scrolling a single new line of content takes 4-6 seconds. Scrolling one line up takes a further 4-6 seconds. Then scrolling one line down takes yet another delay.

On a faster machine (M2, 16 gigs of RAM) if I scroll multiple lines there's a delay of two seconds or so before content is drawn. If I then scroll up (to the place it was before) there's another delay, and then scroll down there's another delay.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

The frame should draw almost instantly if all the user is doing is scrolling, as it's static text. If there are technical reasons as to why it takes so much processing time, what I would say is that I would expect content that had previously been rendered to not take the same full time to display every time.

Actual behavior

Content takes a long time to render (visible pause with no content while scrolling) and subsequent scrolls around the area doesn't change the render time of the content.

Steps To Reproduce

1. Visit https://developer.apple.com/documentation/swift/string/subsequence (I was using Firefox 133) (using an older PC and not a top-end development machine ideally, but it's probably noticable on anything)
2. Scroll the left panel up and down.
3. Observe the redraw behaviour -- how long it takes, and if it gets any faster if rendering content it's already rendered.
4. Move your mouse over the labels, noting how long it takes for the blue highlight to catch up with your mouse cursor.
5. Enter text into the filter area. There should be a noticable lag. (On my slow machine, this takes four seconds for each keystroke!)

Swift-DocC-Render Version Information

No response

[mportiz08]

Interesting. We do utilize the vue-virtual-scroller library that uses a windowing technique for displaying/scrolling the items in the sidebar because these navigation trees can be huge (like in the given example), and we don't want to create a huge amount of static DOM nodes that may introduce performance issues. It sounds like even with the library, we are still experiencing some performance issues here though.

For me, the issue with the delay in hovering over items is especially noticeable in Firefox, even with a decently fast machine. Maybe there is an issue with the way we have configured the virtual scroller or a browser specific bug with the library itself...

It may take some time to investigate possible improvements here. Thanks for bringing attention to this issue!

[dodongo]

Any updates on this? My team maintains a package with a pretty high amount of targets and their docs are merged with docc merge. There is very noticeable degradation in both the sidebar scroll performance, highlighting over items, and also the sidebar search - which may be a separate issue.

[mportiz08]

No updates as of yet—sorry. It would be valuable to get some feedback from you on a couple of items though:

• Are you still experiencing these performance issues with a version of docc from the latest Swift toolchain?
• Are you mostly seeing performance issues with Firefox or are things slow in for you in all browsers?
• Do you have an estimate on the number of distinct items in the sidebar when you're hitting these perf issues?

[dodongo]

@mportiz08 Thank you for the fast reply.

Are you still experiencing these performance issues with a version of docc from the latest Swift toolchain?

We are building docc from source from https://github.com/apple/swift-docc.git at the 1ad9b6a commit (very recent commit on main) with a release build. We are also using https://github.com/apple/swift-docc-render-artifact with this commit 1fe16ce, and are passing that via the DOCC_HTML_DIR env variable to docc.

Are you mostly seeing performance issues with Firefox or are things slow in for you in all browsers?

We have mainly tested on latest versions of Chrome and Safari, but I just tested on latest Firefox and it seems similar across the board.

Do you have an estimate on the number of distinct items in the sidebar when you're hitting these perf issues?

Right now we have ~50 targets in our package (this used to be a multi repo project that has since been combined into a single package), and the scrolling / highlighting issues are immediate - even without expanding any of these targets' docs. I can try to reduce this number just to see if I can determine the point where it gets particularly bad and get back to you.

[dodongo]

I know this is not really scientific - I have no idea if the documentation contents of the targets influence this performance, and this is just on a single M3 Pro, but in my testing:

• 50 targets is borderline unusable - very slow link hover, scrolling and global search.
• 40 targets is sluggish but somewhat usable.
• 20 targets is pretty usable - a little noticeable but not awful
• 10 targets and under is pretty smooth

I saw similar performance across browsers.

[mportiz08]

I think I pinned this down to a large refactoring PR for the sidebar that may have introduced this performance issue: #904

I'll continue to investigate and see if there's a reasonable fix to improve the performance here.

[mportiz08]

Went on a deep dive today investigating this issue, and I think I'm on track to finally finding a fix.

I was able to find a way to reliably reproduce the issue with some example content, and I discovered that commit a0186a1 introduced this with the merging of #904.

Also, it took me a while, but I discovered that this is the problematic CSS selector causing the issue:

swift-docc-render/src/components/Navigator/BaseNavigatorCardItem.vue

Line 78 in 6990af9

&:not(.is-group) {

Although, it's not totally obvious to me yet how the changes in the PR are affecting that selector since the CSS didn't actually change in that commit. I'm guessing that something in that PR introduced a large number of additional DOM elements to where the not selector is taking much longer to execute, but I'm not totally sure where that's coming from based on the PR changes yet...

Oh well, at least I have an idea as to how to fix this now by rewriting that rule without a not selector—will continue tomorrow and should have a PR ready pretty soon 😅

[mportiz08]

My hunch from yesterday actually turned out to be wrong. While the not selector could certainly be optimized for better performance, it wasn't actually the main culprit here. The main issue is that #904 introduced a huge spike in the memory usage for the data used to render the sidebar. I was able to utilize Object.freeze in the way we were using it before that PR to address that regression, which has resulted in a much snappier sidebar hover animation from my testing with large projects.

Sorry for the delay in figuring this out!

#934

[mportiz08]

I believe this should be resolved now by #934 but feel free to re-open if you're still experiencing significant performance issues with the sidebar.