Re-align toggle chevrons with right edge of sidebar

[gabalafou]

Note: this PR is against feature-focus branch not main. Style fixes related to interaction state (focus, hover, current) will be collected in small increments into feature-focus before being merged into main.

This PR introduces a few code changes:

1. Negative right margin on TOC toggle chevrons so they align with sidebar edge like before.
2. Modify markup tree when TOC entry is togglable (.has-children). Previously: li > a ~ input ~ label ~ ul. Now: li > (div > a ~ label) ~ input ~ ul. This was done so that the chevron label element would not have to be absolutely positioned.
3. Refactor some of the styles as a consequence of the markup change

These changes are explained in greater detail in the inline comments.

Backstory

@jorisvandenbossche left a comment on #1549 showing chevrons not aligning with the sidebar edge.

This was the result of removing a margin-right: -1rem rule on the nav.bd-links element. I removed that rule because it was causing the right edge of the focus rings to get clipped (the sidebar's overflow rules do not permit the part of the focus ring that goes outside the sidebar to be shown). The unintended consequence of removing the negative margin on the container was the chevrons no longer right-aligning with the edge of the sidebar.

Test plan

1. Go to /examples, use the tab key to move focus through all of the links in the left sidebar. Expand and collapse all of the chevrons with the mouse. Keep checking the look and feel of the focus ring with the chevrons expanded or collapsed. Check the behavior when the focus ring is adjacent to a chevron—above, below, and on the same line.
2. Do the same at /community
3. Check 1 and 2 for both desktop and mobile (sidebar overlay)

[gabalafou]

Done self-reviewing!

[gabalafou]

This needed to be moved onto the a-tags, because it was targeting other links in the sidebar that it shouldn't, as shown in the following screenshot:

[gabalafou]

This is necessary given the change to the markup structure in toctree.py.

[gabalafou]

Absolutely positioning the toggle chevron so that it lays on top of and right-aligned with the TOC link creates a hard-to-fix visual issue: when the user focus a link then hovers its chevron, the HTML box of the chevron turns a solid gray, and this solid gray box blocks out a portion of the focus ring, since the chevron's box is absolutely positioned to lay on top of the link's box.

If you try to give the link box a positive z-index or the chevron a negative z-index, in order to send it behind the focus ring so that it doesn't visually block the focus ring, then in that case the link's box is laid over the chevron's box and therefore the chevron can no longer receive hover or click events, rendering it useless.

I think it's better to not have these two elements stacked on each other and instead have them laid out side by side. I think that also sets a better stage for how the focus ring will move when we make the chevrons focusable and keyboard-operable. Because instead of the focus ring moving from surrounding the link + chevron to shrinking to surround the chevron, it will go from surrounding just the link, then move right to surround the chevron.

[gabalafou]

We don't want the chevron's box to be squished or expanded.

[gabalafou]

For TOC entries that span two lines, this ensures that the chevron is aligned with the first line.

[gabalafou]

This sends the link and chevron to opposite sides of the flex box.

[gabalafou]

I'm a little bit concerned about this change. Mostly I'm concerned about downstream users of the theme who may have applied custom styles, copying our rules.

[drammock]

it is needed because of the wrapping heading-name and chevron nodes into a flex container, right? I wouldn't worry about it too much --- we're not yet at v1.0 so we aren't guaranteeing stability (especially CSS/classnames) and if there were downstream overrides, they should be easy to fix (by copying this change) right?

[gabalafou]

Another change due to the change in the markup tree in toctree.py

[gabalafou]

There are a couple things I don't like with this change.

It creates an inconsistency. TOC entries with children will have the following markup tree:

li
  input
  div
    a
    label
  ul

Whereas other TOC entries will look like:

li
  a

There is an additional level of depth in the tree, whereas previously all entries, whether they had children or not, had only one level of tree depth.

I'm worried about two things:

1. Inconsistency (just because inconsistencies like these make me uneasy)
2. Messing up consumers' sites because they customized the theme expecting a direct child relationship between the li and the link (or other elements like the chevron)

However, if I don't put the link and the chevron together in a row-flex div, then I don't know how to lay out the link and chevron in the same row without using absolute positioning, which as I mention in another inline comment, creates a hard-to-fix visual aberration.

[drammock]

I can see why this is troublesome. I guess you could wrap even the non-expanding headings in a similar div? As mentioned in another comment I think we shouldn't be too fretful about breaking downstream customizations as long as the fix is a straightforward one. Wrapping all headings in an extra div seems like it would facilitate those fixes being easier.

[gabalafou]

Is this a good classname?

[drammock]

I think "heading" is better than "header" here. Also technically the primary sidebar nav is not really a toctree, so maybe sidebar-primary-collapsible-heading? Or something along those lines; tweak as needed to achieve similarity to related class names.

[choldgraf]

Not sure if this is related to the current PR, but just wanted to note that chevrons no longer seem to change their orientation based on whether a sub-menu is collapsed:

It is hard to know if this is fixed because all this work is being done on a branch that isn't deployed to our latest/ docs, but wanted to note it here in case it's relevant to this PR.

[gabalafou]

@choldgraf I do have another PR that fixes this, but it's such a simple two-line fix, your comment made me think I might as well open a PR to fix this sooner rather than later: #1584

[gabalafou]

Superseded by #1582