ENH: Enhance toggle button design and layout

[choldgraf]

This makes a few major design updates to our toggle buttons with the following goals:

• Make the toggle buttons flow with our content, rather than popping out to the side
• Make the toggle buttons a bit easier to notice and click on, without attracting too much attention/space
• Make the toggle buttons use <details> where possible, to simplify the toggling process
• Follow patterns from similar elements in other themes (specifically, mkdocs and quarto in this case)
• Follow patterns from sphinx-design, so that we could switch over to re-using that here in the future relatively easily if we wish

Major updates

Using chevrons for buttons

This swaps out our "+/-" sign to instead use a chevron > that rotates. We had some discussion of this in the EBP meeting today and everybody agreed this was a nicer pattern than the +/- combo we were using before.

cc @rkdarst as this might change the behavior of your admonitions slightly. Let me know what you think!

Old behavior

New behavior

The non-admonition toggle button will now wrap elements in a <details> block

If somebody puts a CSS class with a toggle button selector, then it will be wrapped in a <details> block and hidden by default. Note that this is done with JS, and likely a better long-term fix is to make this happen on the Sphinx build side, but this is meant to be a step in the right direction.

Old behavior

New behavior

closes #28
closes #26

[choldgraf]

It would be great if either @AakashGfude or @chrisjsewell could give this a quick look to see if:

1. This is a reasonable improvement (even if not a perfect end-point)
2. There's any low-hanging fruit we could improve

[AakashGfude]

Looks like a reasonable improvement to me @choldgraf, Do you think we can utilize the grey area of <details> block in any other way apart from Click to Toggle text?

[choldgraf]

Good question - this could certainly be configurable in Sphinx. Though ideally you'd be able to map class names to promote text (eg so .hide-input would map to "Show cell input" and .hide-output would map to "Show cell output"). That might be possible to configure is the copybutton_selector could be a dictionary of "selector: text" mappings

[AakashGfude]

Not exactly based on changes in this PR. But might be low-hanging fruit. I think we can leverage the toggle() function of DOMTokenList https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle , to add remove classes, in toggleHidden function. It will look a bit cleaner I think.
But we can do it in a separate PR as well.

[AakashGfude]

Though ideally you'd be able to map class names to promote text (eg so .hide-input would map to "Show cell input" and .hide-output would map to "Show cell output"). That might be possible to configure is the copybutton_selector could be a dictionary of "selector: text" mappings

This sounds like a good idea.

[choldgraf]

Question

Another option we discussed was to use an ellipsis as the open/close button. For example, here's a not-quite-polished ellipsis in action:

Benefits:

• Takes up much less space
• Is a less busy / opinionated UI element
• Aligns with how Jupyter Notebook/Lab do show/hide
• No need for customized text for different kinds of elements (I think "Click to toggle visibility" is probably still needed for a tooltip)

Cons:

• Perhaps not as obvious that it can be clicked on (?)
• Is less in-line with other design elements like admonitions
• Perhaps less "document-focused"?
• Feels less "designey" (whatever that means)

Preferences?

Anybody have opinions in either direction? (would also love thoughts from folks like @psychemedia @pradyunsg @mmcky if they have any opinions :-) )

[AakashGfude]

Another option we discussed was to use an ellipsis as the open/close button. For example, here's a not-quite-polished ellipsis in action:

Doesn't feel intuitive. Quite less "designy" in my opinion.

[rkdarst]

The rotateable chevron looks great to me! It seems like the right long-term design choice.

It's been sort of magic how the toggle button has worked across the different themes well - it would be nice if that was still possible. That seems to be one nice thing about doing it in pure-javascript (though I don't know how generalizable the sphinx-build side is?) I'll test with sphinx_rtd_theme when I can.

[rkdarst]

Update: it works and looks very nice with sphinx_rtd_theme. The only possible thing is the color of the button: it would be nice if it could adopt the color of the font of the title. I've seen this with SVG buttons before, but I'd say it's not a big enough of an issue to make it worth it (text+button works well for color accessibility).

[mmcky]

@choldgraf I am +1 on the chevron. I think they look really nice and I like visual cues they provide. The elipsis is one of the design choices in many iOS apps I actually don't like :-)

[psychemedia]

I don't really like the ellipsis - it's no overly suggestive (to me) of what happens next...

I wonder if a "drop-up" mechanic would work, where there is an indicator eg top right of an output cell that appears on hover and then lets you click to view the code above the output cell, or even below the output cell (a bit like a caption, with the code explaining the above...)

[choldgraf]

Thanks for the feedback everybody, that is super helpful. It sounds like the dropdown is the way to go. I wonder if there's a way we can make it take up less visual space and still use the dropdown slider.

What if we reduced the width to max at 25% of the page, then it would look like the following, what do people think?

or even with the arrow on the left, like a traditional details button?

Also @psychemedia I love your idea for some kind of hover-able menu to toggle the display...I think that might require more assumptions about the structure than we can make in sphinx-togglebutton, but maybe we can special case that in myst-nb somehow?

[chrisjsewell]

Yep cheers, as I reference a lot in https://sphinx-design.readthedocs.io/en/furo-theme/, https://material.io is Google's user interface best practice and is a great reference point, and also https://material-ui.com/, https://getbootstrap.com/ and https://primer.style/

(but looking good)

[choldgraf]

Update: more compact toggle button

After some feedback from you all (and others on twitter) I've made the block-level toggle button more compact. here are the changes:

• The arrow is now on the left
• Width of the button fits the content of whatever is inside.
• The "show" and "hide" text is now configurable via conf.py
• We now directly embed the SVG so that you can style it with color: somecolor (cc @rkdarst)
• Cleaned up the spacing and padding a little bit

Here's a gif of the new behavior:

I think that this one is ready to go from my end, unless there is other low-hanging fruit others would like to suggest. I'll leave it for a day or two to give others a chance to comment or make suggestions!

[AakashGfude]

Looks smooth @choldgraf .🚀

[psychemedia]

How easy would it be to optionally allow user customisable toggle messages at a local or global level?

[rkdarst]

It looks very nice! Thanks for all of your work on this.
One advantage of current format is that if javascript is blocked, nothing is hidden (though that's probably esoteric enough that it's not worth making a design philosophy...).

[choldgraf]

@psychemedia - the toggle button message is already customizable at a global level (see https://sphinx-togglebutton--32.org.readthedocs.build/en/32/use.html#control-the-togglebutton-hint-text). At a local level, I can think of two ways we could do this (in a follow up PR probably):

• Use a data attribute for the element that is being hidden. For example, look for data-toggle-hint-show and data-toggle-hint-hide, and if those exist in the element, use them to populate the toggle message.
• Add options to the {toggle} directive to provide custom images when it is used (maybe that leverage the data attributes described above?)
• Define a mapping of selectors -> messages to use (e.g. {".cell": "Toggle code cell"}). Though I could see this getting confusing and messy to configure.

Thanks all for your comments - Unless others suggest we should hold off merging, I'll try and take another look at the code today and will give it a merge if I can't find anything major to improve.