Add Feature to expand/collapse Table of Contents

anthumchris commented 6 years ago

Originally discussed with @domenic, @tabatkins in https://github.com/whatwg/streams/issues/885, this feature would add expand/collapse functionality to specific TOC lines. Pages wishing to implement this feature could add class "toc-collapsible" to the header markup. For example, the markup below would produce the expand/collapse functionality in the TOC for those headers:

<h3 class="toc-collapsible">General writable stream abstract operations</h3>
<h3 class="toc-collapsible">Writable stream abstract operations used by controllers</h3>

collapsed:

expanded:

Which design should be used?

I created prototypes for designs and would need to know which one everyone would like to move forward with. This affects the hard-coded markup Bikeshed would add:

Where should the CSS/Javascript go?

I'm new to this project and would need to know where to put the required CSS/JS that this functionality requires. Should it be inline or in external files? I'll add inline to start and will modify as needed.

Other Requirements?

I can add this to the TOC documentation and create tests in the tests folder. Anything else needed? @tabatkins mentioned using details, summary, and a11y which I didn't understand and went over my head.

And what browsers are supported/unsupported? I'll need to do CSS/JS testing on your support matrix.

Feel free to assign this to me if you'd like.

tabatkins commented 6 years ago

The <details> and <summary> elements are built-in "expand to see more" elements in HTML. I could use these directly in the TOC, with a markup like:

<ol>
  <li>
    <details>
      <summary><a>1. Introduction</a></summary>
      <ol>
        <li><a>1.1 Module Interactions</a>
      </ol>
    </details>
  </li>
</ol>

(Leaf nodes can be left as just a elements, but if they have sub-sections they'll be put into a details instead.)

tabatkins commented 6 years ago

Live example: http://software.hixie.ch/utilities/js/live-dom-viewer/saved/5828

anthumchris commented 6 years ago

@tabatkins very cool, I had no idea and never used them before. Just tested on win VMs and...

\<details> is not supported in Edge 16 (nor IE 11). Seems a JS work-around may be needed if moving forward with this structure. But GitHub likes it 👻

domenic commented 6 years ago

I'm quite happy with this being a progressive enhancement that doesn't work in Edge yet.

tabatkins commented 6 years ago

Yeah, they'll just fail-open, looking identical to how things are formatted today. That's 100% okay with me.

anthumchris commented 6 years ago

Here's the first round prototyping implementation with Streams page. You'll notice differences in <details> UI behavior that aren't consistent across browsers: clicking header <a> navigates in Firefox, while other browsers don't navigate. This may not be ideal and removes navigability to the expandible TOC line.

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

https://github.com/tabatkins/bikeshed/compare/master...AnthumChris:toc-collapsible-details https://github.com/whatwg/streams/compare/master...AnthumChris:toc-collapsible-headers

tabatkins commented 6 years ago

Whoa, there's some non-determinism going on here in Chrome - I was able to navigate one of the links once, then when I returned it refused to navigate again and just toggled it open/close.

Anyway, boo on this not working in Chrome. Maybe we can add a tiny bit of JS to capture the click and dispatch properly?

(However, the link is definitely clickable in my demo linked above. There's something weird going on here.)

speced / bikeshed