|
1 | 1 | /** |
2 | 2 | * Sphinx togglebutton |
| 3 | + * |
| 4 | + * The rules in this style sheet are meant to tweak the |
| 5 | + * [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/index.html) |
| 6 | + * extension so that it matches the look and feel of this theme. |
3 | 7 | */ |
4 | 8 |
|
5 | 9 | .bd-content { |
|
17 | 21 | } |
18 | 22 | } |
19 | 23 |
|
20 | | - // Admonition toggles |
21 | | - .admonition { |
| 24 | + // Apply this mixin to the element that will be hovered. These styles are |
| 25 | + // intended to match what sphinx-design does for its dropdown admonitions. |
| 26 | + @mixin icon-hover-effects { |
| 27 | + &:hover .tb-icon { |
| 28 | + opacity: 1; |
| 29 | + scale: 1.1; |
| 30 | + } |
| 31 | + |
| 32 | + .tb-icon { |
| 33 | + opacity: 0.6; |
| 34 | + } |
| 35 | + } |
| 36 | + |
| 37 | + // Collapsible admonition, implemented as <div> + <button> |
| 38 | + .dropdown.admonition.toggle { |
| 39 | + // The title is visible when the admonition is collapsed and expanded |
| 40 | + .admonition-title { |
| 41 | + @include icon-hover-effects; |
| 42 | + @include hover-darken-lighten; |
| 43 | + |
| 44 | + &:hover { |
| 45 | + box-shadow: none; |
| 46 | + } |
| 47 | + } |
| 48 | + |
22 | 49 | button.toggle-button { |
23 | 50 | color: inherit; |
24 | 51 |
|
|
34 | 61 | // Focus ring |
35 | 62 | // ---------- |
36 | 63 | // Sphinx-togglebutton makes the entire admonition header clickable, but |
37 | | - // only the button within the header is focusable. We want the entire |
38 | | - // clickable area to be surrounded with a focus ring, so that's why we use |
39 | | - // the :focus-within selector, rather than a :focus-visible selector on the |
40 | | - // button. |
41 | | - &:focus-within { |
| 64 | + // only the button within the header is focusable. But we want the entire |
| 65 | + // header and not just the button inside the header to be surrounded by a |
| 66 | + // a focus ring. |
| 67 | + &:has(:focus-visible) { |
| 68 | + /* Override Sphinx Toggle Button. Make the overflow visible, otherwise the |
| 69 | + focus ring is hidden. */ |
42 | 70 | overflow: visible; |
43 | 71 |
|
44 | | - // The complicated focus ring styles here are a consequence of the markup |
45 | | - // and border styles for this particular admonition class. (For the other |
46 | | - // type of admonition on this site, the focus ring style is achieved with |
47 | | - // simple `outline` and `outline-offset` rules on the admonition's |
48 | | - // header.) The problem is that Sphinx-togglebutton puts the admonition's |
49 | | - // left border on the outermost container (rather than separately setting |
50 | | - // the left border on the container's children). This makes it complicated |
51 | | - // to get the focus ring to simultaneously cover the left border in the |
52 | | - // header and align perfectly on the right with the body. |
53 | | - .admonition-title:focus-within::before { |
| 72 | + /* |
| 73 | + Why not just do the following? |
| 74 | +
|
| 75 | + ``` |
| 76 | + .admonition-title { |
| 77 | + outline: $focus-ring-outline; |
| 78 | + } |
| 79 | + ``` |
| 80 | +
|
| 81 | + Why use ::before? If we put the focus ring on the ::before pseudo-element, |
| 82 | + we can reposition the focus ring by repositioning the pseudo-element. |
| 83 | +
|
| 84 | + Why reposition? The left edge of the admonition title box does not align |
| 85 | + with the left edge of the overall admonition box. There is a left border |
| 86 | + that belongs to the overall box. The border is outside of the admonition |
| 87 | + title, which means it is also outside of a focus ring around the title. We |
| 88 | + can make the focus ring bigger, with `outline-offset`, but this will |
| 89 | + result in a ring that looks off-centered. So we have to pull the ring left |
| 90 | + and stretch it right. That's what the pseudo-element allows us to do. |
| 91 | +
|
| 92 | + Note: we do not have to do this for collapsible admonitions made with |
| 93 | + Sphinx Design (as opposed to sphinx-togglebutton). |
| 94 | + */ |
| 95 | + .admonition-title::before { |
54 | 96 | content: ""; |
55 | | - transform: translateX( |
56 | | - -$admonition-left-border-width |
57 | | - ); // align left edges of admonition and ring |
58 | 97 |
|
59 | | - width: calc(100% + $admonition-left-border-width); // align right edges |
| 98 | + // pull the focus ring left and expand it right to be perfectly centered |
| 99 | + // between the left border and the right edge of the admonition title |
| 100 | + left: -$admonition-left-border-width; |
| 101 | + width: calc(100% + $admonition-left-border-width); |
60 | 102 | height: 100%; |
61 | | - border: $focus-ring-outline; |
| 103 | + outline: $focus-ring-outline; |
| 104 | + outline-offset: $focus-ring-offset; |
62 | 105 | border-radius: $focus-ring-width; |
63 | 106 | } |
64 | 107 |
|
65 | 108 | // When expanded, sharpen the bottom left and right corners of the focus ring |
66 | | - &:not(.toggle-hidden) .admonition-title:focus-within::before { |
| 109 | + &:not(.toggle-hidden) .admonition-title::before { |
67 | 110 | border-bottom-left-radius: 0; |
68 | 111 | border-bottom-right-radius: 0; |
69 | 112 | } |
70 | 113 | } |
71 | 114 | } |
72 | 115 |
|
73 | | - // Details buttons |
| 116 | + // Collapsible component, implemented as <details> + <summary> |
74 | 117 | details.toggle-details { |
75 | 118 | // Over-ride border color to re-use our primary color |
76 | 119 | summary { |
77 | 120 | border-left: 3px solid var(--pst-color-primary); |
78 | 121 |
|
79 | 122 | @include chevron-down; |
| 123 | + @include icon-hover-effects; |
| 124 | + @include hover-darken-lighten; |
| 125 | + |
| 126 | + &:hover { |
| 127 | + box-shadow: none; |
| 128 | + } |
| 129 | + |
| 130 | + &:focus-visible { |
| 131 | + outline-offset: $focus-ring-offset; |
| 132 | + } |
80 | 133 | } |
81 | 134 |
|
82 | 135 | // When expanded, sharpen the bottom left and right corners of the focus ring |
|
0 commit comments