Make the table of contents more useful/less dense

[domenic]

Streams is a bit different in structure from other specifications in that it uses a heading for every API surface and abstract operation. This leads to a much larger table of contents than other specifications, and as such, I think the TOC is not very useful in its current form.

I think we should omit:

• Everything under "Class X"
• Every abstract operation (but keep the categories, e.g. keep "General Readable Stream Abstract Operations")

This can be done by adding class="no-toc" to the appropriate headings in the index.bs document.

Marking this as a "good first issue" in case anyone wants to help out.

[anthumchris]

What about a show/hide feature that meets 2 goals: de-clutter TOC; make info quickly available if needed? Similar to examples below (but finalized by proper designer). Expanded states would stay persistent with localStorage for revisits.

Default

Open

[domenic]

That would be a pretty nice bonus! Probably a decent bit of work though, as our TOC is generated by our spec tooling, and this would need to hook into that. (Or fix it up afterward using JS, I guess?)

[anthumchris]

True, I noticed Bikeshed is building. Python's not my forte, but I hacked a "toc-collapsible" detection to add the scaffolding needed by implementing spec pages. The implementing spec page could add CSS for all layout and a small JS click handler. This allows per-page customization and decouples presentation/functionality from Bikeshed.

https://dev.anthum.com/pub/whatwg-streams-toc-expand.html

https://github.com/AnthumChris/bikeshed/commit/d04732bae6b3e861d2de50b7d548f7cc72fb19c1
https://github.com/AnthumChris/streams/commit/530917c6834094261a5006b2e03746c53a5e3a08

[domenic]

That looks like a pretty nice UX and design! The JS doesn't work in Firefox (due to using window.event), and I left some suggestions for factoring the Bikeshed part out a bit, but I'd love to get this integrated. Sorry for the delay in response time.

[domenic]

/cc @tabatkins so he knows we're plotting to add this collapsible-sections-in-the-TOC support to Bikeshed.

[anthumchris]

I can create an issue in Bikeshed that I originate changes from to ensure this is described and documented in the BS docs.

I added a second design prototype with arrows on left. Both use the same Bikeshed codebase while providing unique CSS for design variants:

https://dev.anthum.com/pub/whatwg-streams-toc-expand-right-text.html
https://dev.anthum.com/pub/whatwg-streams-toc-expand-left-arrows.html

[tabatkins]

Ooh, I'm down for this. I've been wanting to do some improvements to ToC anyway - I very much like Tobie's "indicate what section of the spec you're currently looking at" stuff too.

[tabatkins]

Might we just want to use details tho? With each heading level being the summary. Then you get all the stuff for free, with a11y built-in.

[domenic]

Hmm yeah I was thinking that would have some issues mixing into the ul/li structure, but on second thought it seems like it'd work great.