Reposition the admonition title icon to the top of the paragraph in m… (#2100)

…ulti-line titles

Fixes #2099

---------

Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: gabalafou <[email protected]>
Co-authored-by: Tania Allard <[email protected]>

Author: 4 people

docs/examples/index.rst

@@ -28,6 +28,7 @@ See the sections in the primary sidebar and below to explore.
     :numbered:
     :caption: Reference and test section. Mostly meant for developers to check that things look OK.
 
+    regressions
     no-sidebar
     persistent-search-field
     in-page-toc

docs/examples/regressions.rst

@@ -0,0 +1,20 @@
+===========
+Regressions
+===========
+
+Whenever a corner case is reported and fixed that the theme got wrong, it should
+be added to this page. That way it can be inspected against current and upcoming
+versions of the theme to help prevent the bug from reappearing in a release.
+
+Admonition with multi-line title
+================================
+
+Issue `#2099 <https://github.com/pydata/pydata-sphinx-theme/issues/2099>`_
+
+In the following example, the admonition title should span multiple lines and
+the icon should be aligned with the top line of the admonition title text.
+
+.. admonition:: Warning! This feature is experimental and only applies to registering routes for React Router 7 applications. Click to accept the risks and read details.
+   :class: warning, toggle
+
+   Uh-oh, now you're in trouble!

src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss

@@ -40,8 +40,12 @@ div.admonition,
 
   // Defaults for all admonitions
   > .admonition-title {
+    $padding-top: 0.4rem;
+    $icon-width: 1rem;
+    $icon-margin-x: 0.5rem;
+
     margin: 0 -0.6rem;
-    padding: 0.4rem 0.6rem 0.4rem 2rem;
+    padding: 0.4rem 0.6rem $padding-top calc($icon-width + 2 * $icon-margin-x);
     font-weight: var(--pst-admonition-font-weight-heading);
     position: relative;
 
@@ -54,8 +58,10 @@ div.admonition,
 
     &::after {
       position: absolute;
-      left: 0.5rem;
-      width: 1rem;
+      top: $padding-top; // align icon with title text
+      left: 0;
+      margin: 0 $icon-margin-x;
+      width: $icon-width;
       height: 1rem;
       color: var(--pst-color-info);
       font: var(--fa-font-solid);