MAINT: Drop jQuery and use Bootstrap 5 (#1029)

Co-authored-by: Chris Holdgraf <choldgraf@gmail.com>
Fix #953
Fix #764

docs/community/bootstrap.rst

@@ -0,0 +1,60 @@
+Upgrade to bootstrap 5
+======================
+
+Since *v0.13*, ``pydata-sphinx-theme`` has moved from Bootstrap 4 to `Bootstrap 5 <https://getbootstrap.com/docs/5.1/getting-started/introduction/>`_.
+This documentation will guide you through the changes we made and how you could follow the same steps in your existing documentation.
+
+Dropping **JQuery**
+-------------------
+
+Bootstrap Dropped its **JQuery** dependency and rewrote plugins to be in regular JavaScript.
+Sphinx *v6* will do the same (https://github.com/sphinx-doc/sphinx/issues/10070).
+As a consequence, we also rewrote all our javascript to only use vanilla **JavaScript**.
+Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite it or specifically import **JQuery**.
+
+Breaking changes
+----------------
+
+‼️ Relevant for those using a ``custom.css`` and/or a ``custom.js`` file!
+
+Bootstrap changed a number of CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.
+
+All of the changes from *v4* to *v5* are `listed in their documentation <https://getbootstrap.com/docs/5.0/migration/>`_.
+Below list the ones that had consequences on ``pydata-sphinx-theme`` components.
+
+Sass
+^^^^
+
+-   Media query mixins parameters have changed for a more logical approach.
+
+    -   ``media-breakpoint-down()`` uses the breakpoint itself instead of the next breakpoint (e.g., ``media-breakpoint-down(lg)`` instead of ``media-breakpoint-down(md)`` targets viewports smaller than lg).
+    -   Similarly, the second parameter in ``media-breakpoint-between()`` also uses the breakpoint itself instead of the next breakpoint (e.g., ``media-between(sm, lg)`` instead of ``media-breakpoint-between(sm, md)`` targets viewports between sm and lg).
+
+-   ``box-shadow`` mixins now allow ``null`` values and drop ``none`` from multiple arguments.
+
+Content, Reboot, etc
+^^^^^^^^^^^^^^^^^^^^
+
+-   Nested tables do not inherit styles anymore.
+
+-   ``.thead-light`` and ``.thead-dark`` are dropped in favor of the ``.table-*`` variant classes which can be used for all table elements (``thead``, ``tbody``, ``tfoot``, ``tr``, ``th`` and ``td``).
+
+-   Dropped ``.text-justify`` class. See https://github.com/twbs/bootstrap/pull/29793
+
+Utilities
+^^^^^^^^^
+
+-   Renamed several utilities to use logical property names instead of directional names with the addition of RTL support:
+
+    -   Renamed ``.left-*`` and ``.right-*`` to ``.start-*`` and ``.end-*``.
+    -   Renamed ``.float-left`` and ``.float-right`` to ``.float-start`` and ``.float-end``.
+    -   Renamed ``.border-left`` and ``.border-right`` to ``.border-start`` and ``.border-end``.
+    -   Renamed ``.rounded-left`` and ``.rounded-right`` to ``.rounded-start`` and ``.rounded-end``.
+    -   Renamed ``.ml-*`` and ``.mr-*`` to ``.ms-*`` and ``.me-*``.
+    -   Renamed ``.pl-*`` and ``.pr-*`` to ``.ps-*`` and ``.pe-*``.
+    -   Renamed ``.text-left`` and ``.text-right`` to ``.text-start`` and ``.text-end``.
+
+JavaScript
+^^^^^^^^^^
+
+-   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.

docs/community/index.md

@@ -16,7 +16,7 @@ setup
 structure
 topics
 manual
-
+bootstrap
 ```
 
 ```{toctree}

docs/user_guide/web-components.rst

@@ -105,7 +105,7 @@ Cards
 
     .. grid-item-card:: A card with a dropdown menu
 
-        .. dropdown:: :fa:`eye,mr-1` third card
+        .. dropdown:: :fa:`eye me-1` third card
 
             Hidden content
 

package.json

@@ -28,9 +28,8 @@
   },
   "dependencies": {
     "@fortawesome/fontawesome-free": "6.1.2",
-    "bootstrap": "^4.4.1",
-    "jquery": "3.5.1",
-    "optimize-css-assets-webpack-plugin": "^6.0.1",
-    "popper.js": "^1.16.1"
+    "@popperjs/core": "^2.11.6",
+    "bootstrap": "^5.2.2",
+    "optimize-css-assets-webpack-plugin": "^6.0.1"
   }
 }

src/pydata_sphinx_theme/__init__.py

@@ -373,7 +373,7 @@ def generate_header_nav_html(n_links_before_dropdown=5):
             links_dropdown_html = "\n".join(links_dropdown)
             out += f"""
             <div class="nav-item dropdown">
-                <button class="btn dropdown-toggle nav-item" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+                <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
                     More
                 </button>
                 <div class="dropdown-menu">
@@ -541,9 +541,9 @@ def navbar_align_class():
         """Return the class that aligns the navbar based on config."""
         align = context.get("theme_navbar_align", "content")
         align_options = {
-            "content": ("col-lg-9", "mr-auto"),
-            "left": ("", "mr-auto"),
-            "right": ("", "ml-auto"),
+            "content": ("col-lg-9", "me-auto"),
+            "left": ("", "me-auto"),
+            "right": ("", "ms-auto"),
         }
         if align not in align_options:
             raise ValueError(

src/pydata_sphinx_theme/assets/scripts/bootstrap.js

@@ -1,18 +1,28 @@
-/* Import and setup functions to control Bootstrap's behavior.
- * Sphinx injects the html output with jquery and other javascript files. To enable
- * Popper.js (and other jQuery plugins) to hook into the same instance of jQuery,
- * jQuery is defined as a Webpack external, thus this import uses the externally defined jquery dependency.
- */
-import "jquery";
-import "popper.js";
-import "bootstrap";
+// Import and setup functions to control Bootstrap's behavior.
+import "@popperjs/core";
+import { Tooltip } from "bootstrap";
+import { documentReady } from "./mixin";
 
 import "../styles/bootstrap.scss";
 
+/*******************************************************************************
+ * Trigger tooltips
+ */
+
+/**
+ * Add tooltip to each element with the "tooltip" data-bs-toogle class
+ */
+function TriggerTooltip() {
+  var tooltipTriggerList = [].slice.call(
+    document.querySelectorAll('[data-bs-toggle="tooltip"]')
+  );
+  tooltipTriggerList.map(function (tooltipTriggerEl) {
+    return new Tooltip(tooltipTriggerEl, { delay: { show: 500, hide: 100 } });
+  });
+}
+
 /*******************************************************************************
  * Call functions after document loading.
- * This is equivalent to the .ready() function as described in
- * https://api.jquery.com/ready/
  */
 
-$('[data-toggle="tooltip"]').tooltip({ delay: { show: 500, hide: 100 } });
+documentReady(TriggerTooltip);

src/pydata_sphinx_theme/assets/scripts/mixin.js

@@ -0,0 +1,13 @@
+/* define several functions to replace jQuery methods
+ * inspired by https://tobiasahlin.com/blog/move-from-jquery-to-vanilla-javascript/
+ */
+
+/**
+ * Execute a method if DOM has finished loading
+ *
+ * @param {function} callback the method to execute
+ */
+export function documentReady(callback) {
+  if (document.readyState != "loading") callback();
+  else document.addEventListener("DOMContentLoaded", callback());
+}