Match Sphinx toggle button and Sphinx Design hover and focus styles

Author: gabalafou

src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss

@@ -68,3 +68,15 @@
   min-width: 24px;
   min-height: 24px;
 }
+
+// Meant to darken the element on hover in light mode, or
+// lighten on hover in dark mode.
+@mixin hover-darken-lighten {
+  &:hover {
+    filter: brightness(0.9);
+
+    html[data-theme="dark"] & {
+      filter: brightness(1.1);
+    }
+  }
+}

src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss

@@ -322,10 +322,12 @@ details.sd-dropdown {
       top: 0.7rem;
     }
 
+    @include hover-darken-lighten;
+
     // Focus ring
-    &:focus-visible {
+    &:focus:focus-visible {
       outline: $focus-ring-outline;
-      outline-offset: -$focus-ring-width;
+      outline-offset: $focus-ring-width;
     }
   }
 }

src/pydata_sphinx_theme/assets/styles/extensions/_togglebutton.scss

@@ -1,5 +1,9 @@
 /**
  * Sphinx togglebutton
+ *
+ * The rules in this style sheet are meant to tweak the
+ * [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/index.html)
+ * extension so that it matches the look and feel of this theme.
  */
 
 .bd-content {
@@ -17,8 +21,27 @@
     }
   }
 
-  // Admonition toggles
-  .admonition {
+  // Apply this mixin to the element that will be hovered. These styles are
+  // intended to match what sphinx-design does for its dropdown admonitions.
+  @mixin icon-hover-effects {
+    &:hover .tb-icon {
+      opacity: 1;
+      scale: 1.1;
+    }
+
+    .tb-icon {
+      opacity: 0.6;
+    }
+  }
+
+  // Collapsible admonition, implemented as <div> + <button>
+  .dropdown.admonition.toggle {
+    // The title is visible when the admonition is collapsed and expanded
+    .admonition-title {
+      @include icon-hover-effects;
+      @include hover-darken-lighten;
+    }
+
     button.toggle-button {
       color: inherit;
 
@@ -34,49 +57,70 @@
     // Focus ring
     // ----------
     // Sphinx-togglebutton makes the entire admonition header clickable, but
-    // only the button within the header is focusable. We want the entire
-    // clickable area to be surrounded with a focus ring, so that's why we use
-    // the :focus-within selector, rather than a :focus-visible selector on the
-    // button.
-    &:focus-within {
+    // only the button within the header is focusable. But we want the entire
+    // header and not just the button inside the header to be surrounded by a
+    // a focus ring.
+    &:has(:focus-visible) {
       overflow: visible;
 
-      // The complicated focus ring styles here are a consequence of the markup
-      // and border styles for this particular admonition class. (For the other
-      // type of admonition on this site, the focus ring style is achieved with
-      // simple `outline` and `outline-offset` rules on the admonition's
-      // header.) The problem is that Sphinx-togglebutton puts the admonition's
-      // left border on the outermost container (rather than separately setting
-      // the left border on the container's children). This makes it complicated
-      // to get the focus ring to simultaneously cover the left border in the
-      // header and align perfectly on the right with the body.
-      .admonition-title:focus-within::before {
+      /*
+      Why not just do the following?
+
+      ```
+      .admonition-title {
+        outline: $focus-ring-outline;
+      }
+      ```
+
+      Why use ::before? If we put the focus ring on the ::before pseudo-element,
+      we can reposition the focus ring by repositioning the pseudo-element.
+
+      Why reposition? The left edge of the admonition title box does not align
+      with the left edge of the overall admonition box. There is a left border
+      that belongs to the overall box. The border is outside of the admonition
+      title, which means it is also outside of a focus ring around the title. We
+      can make the focus ring bigger, with `outline-offset`, but this will
+      result in a ring that looks off-centered. So we have to pull the ring left
+      and stretch it right. That's what the pseudo-element allows us to do.
+
+      We do not have to do this with the other collapsible admonitions because
+      those implementations put the left border and the title together so that a
+      focus ring surrounds them both.
+      */
+      .admonition-title::before {
         content: "";
-        transform: translateX(
-          -$admonition-left-border-width
-        ); // align left edges of admonition and ring
 
-        width: calc(100% + $admonition-left-border-width); // align right edges
+        // pull the focus ring left and expand it right to be perfectly centered
+        // between the left border and the right edge of the admonition title
+        left: -$admonition-left-border-width;
+        width: calc(100% + $admonition-left-border-width);
         height: 100%;
-        border: $focus-ring-outline;
+        outline: $focus-ring-outline;
+        outline-offset: $focus-ring-width;
         border-radius: $focus-ring-width;
       }
 
       // When expanded, sharpen the bottom left and right corners of the focus ring
-      &:not(.toggle-hidden) .admonition-title:focus-within::before {
+      &:not(.toggle-hidden) .admonition-title::before {
         border-bottom-left-radius: 0;
         border-bottom-right-radius: 0;
       }
     }
   }
 
-  // Details buttons
+  // Collapsible component, implemented as <details> + <summary>
   details.toggle-details {
     // Over-ride border color to re-use our primary color
     summary {
       border-left: 3px solid var(--pst-color-primary);
 
       @include chevron-down;
+      @include icon-hover-effects;
+      @include hover-darken-lighten;
+
+      &:focus-visible {
+        outline-offset: $focus-ring-width;
+      }
     }
 
     // When expanded, sharpen the bottom left and right corners of the focus ring