ToC is cumbersome, especially when ToC is long

[joyously]

Go to https://developer.wordpress.org/reference/classes/wp_query/

I have to make my window at least 1188px wide to get the Table of Contents to open and be on the right.

On narrower windows (my normal is about 1040px), the ToC is closed and inline. There is a tiny > to open it (instead of using the friendlier details element).

Whether open or closed, the width of the ToC is quite wide. It looks crowded when next to the content on a wider window.

On the WP Query page on a wide window, the ToC is longer than my window is high, so I can't scroll it to click the last few links (like Source or User Notes), which is the whole point of having the ToC.

[ndiego]

Thanks for reporting @joyously

There is a tiny > to open it (instead of using the friendlier details element).

This issue has been reported here.

On the WP Query page on a wide window, the ToC is longer than my window is high, so I can't scroll it to click the last few links (like Source or User Notes), which is the whole point of having the ToC.

Yes, I am seeing the same thing on a small browser window. In this situation, I think the TOC should scroll independently. The React Docs have a similar implementation that we could use as inspiration.

[ndiego]

cc @jasmussen @fcoveram for TOC design thoughts.

[StevenDufresne]

On the WP Query page on a wide window, the ToC is longer than my window is high, so I can't scroll it to click the last few links (like Source or User Notes), which is the whole point of having the ToC.

When the Table of Contents is longer than the window height, it shouldn't be fixed. Is it currently fixed?

It should look like this:

[joyously]

My browser is Firefox 121.0 on Ubuntu 22.04. On a wide window, the ToC is stationary and the content is scrolled.

[fcoveram]

I have to make my window at least 1188px wide to get the Table of Contents to open and be on the right… Whether open or closed, the width of the ToC is quite wide. It looks crowded when next to the content on a wider window.

If I remember correctly, @jasmussen @ndiego and I talked about this when revisiting the layout. In this mockup note, available in the designs, we discussed above placing the TOC out of the main content wrapper so TOC's margin-right is tighter, and therefore, it changes to inline in a smaller viewport.

The white space on the right is currently caused by an empty padding and empty margin on the right.

On the WP Query page on a wide window, the ToC is longer than my window is high, so I can't scroll it to click the last few links (like Source or User Notes), which is the whole point of having the ToC.

I think we can address this from the content rather than removing H3 headings. "Parameters" is the longest section with multiple H3 headings. Does it need to be like that? If so, does it make sense to move all that content to a new post?

The above should not stop us from implementing the scrollable TOC like in @ndiego's example from React Docs, but a copy review may solve this issue as long posts sometimes require a scope reivisit.

[ndiego]

I think we can address this from the content rather than removing H3 headings. "Parameters" is the longest section with multiple H3 headings. Does it need to be like that?

Yup, this is documentation for WP_Query, and it all needs to live on that one page. We are going to run into situations like this a lot in the developer docs, so I think we should ensure the TOC can efficiently support this setup. There are definitely copy improvements that can be made throughout, but it will be quicker to modify the TOC to support these situations 😅

[ndiego]

I did a bit of testing, and I think the issue is the scroll/sticky nature of the TOC does not take into account manual resizing of the browser window.

In the video below, I start with a large browser window and the TOC is sticky. I then manually make the window small, and the TOC remains sticky and I cannot see the bottom portion of it.

However, when I refresh the page, the TOC is not sticky (as expected due to the window size). When I make the window large again, the TOC remains fixed at the top of the page and scrolls with the content.

So perhaps we just need to detect if the window has been resized?

scroll-resizing-toc.mp4

[joyously]

Somehow, the test with resizing the window seems opposite of what I experience.
My window is normally about 1040px, so the first load shows the ToC inline. Making the window larger to get the ToC on the right leaves me with a sticky ToC that I can't scroll.

[jasmussen]

Agreed this needs to be addressed, though I think it's largely captured in this followup: #365 (comment)

That is to say, the TOC should be sticky, and scroll independently if need be.

[adamwoodnz]

These issues have been addressed in #469

Included in this is a resize handler, so changing the screen size after page load or changing orientation should work now.

Please let us know if problems persist.

There is also a related issue for the ToC breakpoint open and in discussion.