Clean up toggle logic in rustdoc

[Manishearth]

I was working on #82114 and discovered that the toggle logic is written scattered all throughout main.js. This seems suboptimal; I'd rather not be generating HTML in main.js. A lot of the toggle logic does things like check the classes of nearby items, etc, which seems super brittle.

I propose we move the toggle logic to Rust code instead; writing a wrapToggle() method that wraps some HTML in a toggle.

Thoughts? @rust-lang/rustdoc

Might be worth creating a meta issue for reducing the size of main.js in general. We seem to do a fair amount of additional codegen there, not just for toggles.

[Manishearth]

Also the way toggles are handled is a global click event that bubbles down. There's a very complicated collapseDocs function that has a whole bunch of special logic, and furthermore the global click event handler basically reimplements a broken version of bubbling.

It feels to me that adding a toggle should just be a matter of wrapping the relevant block in a toggle div + toggle, and at runtime we simply need to hook up event listeners.

[Manishearth]

Also there are a whole bunch of hardcoded pixel values in the css that guess the sizes of toggle buttons. We ... shouldn't be doing that.

[Manishearth]

Overall the toggle code needs a major refactor, I think. I can make my changes without such a refactor but I think we need to redo the JS/CSS side of this entirely.

[camelid]

I propose we move the toggle logic to Rust code instead; writing a wrapToggle() method that wraps some HTML in a toggle.

I am definitely 👍 on moving JS code to Rust.

Might be worth creating a meta issue for reducing the size of main.js in general. We seem to do a fair amount of additional codegen there, not just for toggles.

Yeah, main.js is pretty complicated. It would be great to simplify it and move more to Rust.

Also there are a whole bunch of hardcoded pixel values in the css that guess the sizes of toggle buttons.

Hmm, what does that mean?

[Manishearth]

Also there are a whole bunch of hardcoded pixel values in the css that guess the sizes of toggle buttons.

Hmm, what does that mean?

This is used to keep the toggle block the same size. This seems to be related to attribute rendering but I can't be sure since I can't get rustdoc to render any attributes on enum variants or struct fields.

Those pixel values are roughly the size of the little +. We should never be doing this.

[camelid]

but I can't be sure since I can't get rustdoc to render any attributes on enum variants or struct fields.

That CSS that you linked to uses .enum > .toggle-wrapper and .struct > .toggle-wrapper which IIUC means it will only apply to toggle wrappers that are direct children of .enums or .structs. Is that why you can't get it rendering or is it unrelated?

[Manishearth]

It was just an example, there are lots of manual margins throughout to make abspos on the toggle wrappers work right, and I don't think it should be necessary?

[camelid]

Those pixel values are roughly the size of the little +. We should never be doing this.

Ah, I see what you mean. When I turn off the height: 25px in dev tools I get:

You're right, this code really does need redesigning!

[camelid]

So what do you think we should start with to clean this up?

[Manishearth]

I think we should first come up with a plan as to how it should work, get that reviewed by the team, and then work on it.

A very rough plan is:

• Tear out all JS toggle code. Perhaps all CSS as well.
• Anything that needs to be toggled should be wrapped in <div class=toggle-wrap data-toggle-text="Show foobar"> during Rust code generation. I kinda think this should always be a separate div so that we can have toggle_start and toggle_end in Rust, but I guess mixing it with other divs may be okay too. I'd prefer not to.
• We use a couple direct-descendant CSS selectors (>) where we shouldn't. These will break, fix them
  • Make sure this div renders cleanly
• Add very simple JS code that iterates through all of these and adds a toggle button sibling. There should be no special cases in this code. The codegen can later be moved into toggle_start in Rust if we want.
• Get this sibling to render correctly. All special cases should be handled by adding additional classes to the toggle-wrap element and using CSS, so we could have things like toggle-wrap toggle-section or whatever.
• Make the above JS hook up an event listener that can find the element to be toggled, and toggle it
• Make the above JS set defaults based on settings. We should use another css class for indicating which setting to pull from.
• The show/hide all button just does a getElementsByClassName to do its thing.

[GuillaumeGomez]

As extra information: we have four kind of toggles iirc:

• For documentation blocks
• For items' inner content (fields and variants for example)
• For attributes
• For default elements on implemented traits

I opened an issue to improve the toggles for the documentation blocks already (here: #56442). Currently, the documentation follows the item it documents. In my idea, it could be simplified by making it a child of the item instead (in the DOM). Then we could eventually try to handle the toggle through CSS only, which would allow us to remove a lot of JS.

I didn't look for the other toggles yet.