Update scss from pst (#661)

Author: jarrodmillman

assets/theme-css/pst/abstracts/_links.scss

@@ -217,6 +217,6 @@ $link-hover-decoration-thickness: string.unquote(
   &:focus-visible {
     box-shadow: none; // override Bootstrap
     outline: 3px solid var(--pst-color-accent);
-    outline-offset: 3px;
+    outline-offset: $focus-ring-width;
   }
 }

assets/theme-css/pst/abstracts/_mixins.scss

@@ -50,10 +50,6 @@
       &:nth-child(even) {
         background-color: var(--pst-color-table-row-zebra-high-bg);
       }
-
-      &:hover {
-        background-color: var(--pst-color-table-row-hover-bg);
-      }
     }
   }
 }
@@ -68,3 +64,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);
+    }
+  }
+}

assets/theme-css/pst/base/_base.scss

@@ -72,33 +72,36 @@ a {
   line-height: 1.15;
 }
 
+// From 0.16.1, the preferred variable for headings is --pst-color-heading
+// if you have --pst-heading-color, this variable will be used, otherwise the default
+// --pst-color-heading will be used.
 h1 {
   @extend %heading-style;
 
   margin-top: 0;
   font-size: var(--pst-font-size-h1);
-  color: var(--pst-heading-color);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h2 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h2);
-  color: var(--pst-heading-color);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h3 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h3);
-  color: var(--pst-heading-color);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h4 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h4);
-  color: var(--pst-heading-color);
+  color: var(--pst-heading-color, --pst-color-heading);
 }
 
 h5 {
@@ -168,6 +171,7 @@ pre {
 
 // the back to top btn
 #pst-back-to-top {
+  // zindex-tooltip comes from Bootstrap https://getbootstrap.com/docs/5.2/layout/z-index/
   // z-index: $zindex-tooltip;
   position: fixed;
   display: none;

assets/theme-css/pst/content/_code.scss

@@ -59,6 +59,10 @@ code.literal {
 
 a > code {
   color: var(--pst-color-inline-code-links);
+
+  &:hover {
+    color: var(--pst-color-link-hover);
+  }
 }
 
 // Minimum opacity needed for linenos to be WCAG AA conformant

assets/theme-css/pst/extensions/_sphinx_design.scss

@@ -151,19 +151,18 @@ html[data-theme="light"] {
 .bd-content .sd-card {
   border: 1px solid var(--pst-color-border);
 
-  // TODO - --pst-color-panel-background is not defined... where is this coming from?
   .sd-card-header {
-    background-color: var(--pst-color-panel-background);
+    background-color: var(--pst-color-on-background);
     border-bottom: 1px solid var(--pst-color-border);
   }
 
   .sd-card-footer {
-    background-color: var(--pst-color-panel-background);
+    background-color: var(--pst-color-on-background);
     border-top: 1px solid var(--pst-color-border);
   }
 
   .sd-card-body {
-    background-color: var(--pst-color-panel-background);
+    background-color: var(--pst-color-on-background);
   }
 
   // Focus ring for link-cards
@@ -323,12 +322,20 @@ 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-offset;
+      border-radius: $focus-ring-width;
     }
   }
+
+  &[open] summary.sd-card-header:focus:focus-visible {
+    border-bottom-left-radius: 0;
+    border-bottom-right-radius: 0;
+  }
 }
 
 /*******************************************************************************
@@ -359,14 +366,16 @@ html {
     .sd-btn-#{$name},
     .sd-btn-outline-#{$name} {
       &:focus-visible {
+        outline: var(--sd-color-#{$name}) solid $focus-ring-width;
+        outline-offset: $focus-ring-offset;
+        border-radius: $focus-ring-width;
+
         // Override Sphinx Design's use of -highlight colors. The -highlight
         // colors are 15% darker, so this would create the effect of darkening
         // the button when focused but we just want the button to have a focus
         // ring of the same (non-highlight) color.
         background-color: var(--sd-color-#{$name}) !important;
         border-color: var(--sd-color-#{$name}) !important;
-        outline: var(--sd-color-#{$name}) solid $focus-ring-width;
-        outline-offset: $focus-ring-width;
       }
     }
   }

assets/theme-css/pst/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,31 @@
     }
   }
 
-  // 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;
+
+      &:hover {
+        box-shadow: none;
+      }
+    }
+
     button.toggle-button {
       color: inherit;
 
@@ -34,49 +61,75 @@
     // 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) {
+      /* Override Sphinx Toggle Button. Make the overflow visible, otherwise the
+      focus ring is hidden. */
       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.
+
+      Note: we do not have to do this for collapsible admonitions made with
+      Sphinx Design (as opposed to sphinx-togglebutton).
+      */
+      .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-offset;
         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;
+
+      &:hover {
+        box-shadow: none;
+      }
+
+      &:focus-visible {
+        outline-offset: $focus-ring-offset;
+      }
     }
 
     // When expanded, sharpen the bottom left and right corners of the focus ring

assets/theme-css/pst/variables/_bootstrap.scss

@@ -26,6 +26,11 @@ $focus-ring-color: var(--pst-color-accent);
 $focus-ring-blur: 0;
 $focus-ring-box-shadow: 0 0 $focus-ring-blur $focus-ring-width $focus-ring-color;
 
+// For many elements, we do not use `outline-offset`. For some we set the offset
+// equal to the focus ring width (either outwards or inwards). But for some
+// other elements (e.g., collapsible admonitions) we set it to this value.
+$focus-ring-offset: 0.125rem; // 2px at 100% zoom (0.125 * 16px base font = 2px)
+
 // outline creates the same style of focus ring, it just uses CSS outline instead of box shadow
 $focus-ring-outline: $focus-ring-color solid $focus-ring-width;
 $btn-focus-box-shadow: $focus-ring-box-shadow;

assets/theme-css/pst/variables/_color.scss

@@ -177,10 +177,6 @@ $pst-semantic-colors: (
     "light": #{map-deep-get($color-palette, "gray", "600")},
     "dark": #{map-deep-get($color-palette, "gray", "400")},
   ),
-  "heading-color": (
-    "light": #{$foundation-white},
-    "dark": #{$foundation-black},
-  ),
   "shadow": (
     "light": rgba(0, 0, 0, 0.1),
     "dark": rgba(0, 0, 0, 0.2),
@@ -218,8 +214,8 @@ $pst-semantic-colors: (
     "dark": #{map-deep-get($color-palette, "foundation", "white")},
   ),
   "table-row-hover": (
-    "bg-light": #{map-deep-get($color-palette, "violet", "300")},
-    "bg-dark": #{map-deep-get($color-palette, "violet", "600")},
+    "bg-light": #{map-deep-get($color-palette, "violet", "200")},
+    "bg-dark": #{map-deep-get($color-palette, "violet", "700")},
   ),
   "table-inner-border": (
     "light": #{map-deep-get($color-palette, "gray", "200")},
@@ -282,6 +278,10 @@ $pst-semantic-colors: (
 
   // assign the "duplicate" colors (ones that just reference other variables)
   & {
+    // From 0.16.1, the preferred variable for headings is --pst-color-heading
+    // if you have --pst-heading-color, this variable will be used, otherwise the default
+    // --pst-color-heading will be used
+    --pst-color-heading: var(--pst-color-text-base);
     --pst-color-link: var(--pst-color-primary);
     --pst-color-link-hover: var(--pst-color-secondary);
     --pst-color-table-outer-border: var(--pst-color-surface);