Track if users has dismissed a version warning banner for a given ver…

…sion. (#1763)

See #1384

See #1384

If a user dismiss the banner it should apply to all pages.
One remaining questions is :

 - does it apply to all versions ?

This implement a dismiss button and store in local storage which
version and when the user has dismissed it.

This is enough informations to refine the logic later with what/when we want to show.

This also has a rough implementation of not showing banner for current dismissed version for the next 14 days following any banner dismissal.

Co-authored-by: Daniel McCloy <dan@mccloy.info>

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -323,6 +323,28 @@ var getCurrentUrlPath = () => {
   return `${DOCUMENTATION_OPTIONS.pagename}.html`;
 };
 
+/**
+ * Allow user to dismiss the warning banner about the docs version being dev / old.
+ * We store the dismissal date and version, to give us flexibility about making the
+ * dismissal last for longer than one browser session, if we decide to do that.
+ *
+ * @param {event} event the event that trigger the check
+ */
+async function DismissBannerAndStorePref(event) {
+  const banner = document.querySelector("#bd-header-version-warning");
+  banner.remove();
+  const version = DOCUMENTATION_OPTIONS.VERSION;
+  const now = new Date();
+  const banner_pref = JSON.parse(
+    localStorage.getItem("pst_banner_pref") || "{}",
+  );
+  console.debug(
+    `[PST] Dismissing the version warning banner on ${version} starting ${now}.`,
+  );
+  banner_pref[version] = now;
+  localStorage.setItem("pst_banner_pref", JSON.stringify(banner_pref));
+}
+
 /**
  * Check if corresponding page path exists in other version of docs
  * and, if so, go there instead of the homepage of the other docs version
@@ -485,23 +507,50 @@ function showVersionWarningBanner(data) {
   // if already on preferred version, nothing to do
   const versionsAreComparable = validate(version) && validate(preferredVersion);
   if (versionsAreComparable && compare(version, preferredVersion, "=")) {
+    console.log(
+      "This is the prefered version of the docs, not showing the warning banner.",
+    );
     return;
   }
+  // check if banner has been dismissed recently
+  const dismiss_date_str = JSON.parse(
+    localStorage.getItem("pst_banner_pref") || "{}",
+  )[version];
+  if (dismiss_date_str != null) {
+    const dismiss_date = new Date(dismiss_date_str);
+    const now = new Date();
+    const milliseconds_in_a_day = 24 * 60 * 60 * 1000;
+    const days_passed = (now - dismiss_date) / milliseconds_in_a_day;
+    const timeout_in_days = 14;
+    if (days_passed < timeout_in_days) {
+      console.info(
+        `[PST] Suppressing version warning banner; was dismissed ${Math.floor(days_passed)} day(s) ago`,
+      );
+      return;
+    }
+  }
+
   // now construct the warning banner
-  const banner = document.querySelector(".bd-header-version-warning");
+  const banner = document.querySelector("#bd-header-version-warning");
   const middle = document.createElement("div");
   const inner = document.createElement("div");
   const bold = document.createElement("strong");
   const button = document.createElement("a");
+  const close_btn = document.createElement("a");
   // these classes exist since pydata-sphinx-theme v0.10.0
   // the init class is used for animation
-  middle.classList = "bd-header-announcement__content";
+  middle.classList = "bd-header-announcement__content  ms-auto me-auto";
   inner.classList = "sidebar-message";
   button.classList =
     "btn text-wrap font-weight-bold ms-3 my-1 align-baseline pst-button-link-to-stable-version";
   button.href = `${preferredURL}${getCurrentUrlPath()}`;
   button.innerText = "Switch to stable version";
   button.onclick = checkPageExistsAndRedirect;
+  close_btn.classList = "ms-3 my-1 align-baseline";
+  const close_x = document.createElement("i");
+  close_btn.append(close_x);
+  close_x.classList = "fa-solid fa-xmark";
+  close_btn.onclick = DismissBannerAndStorePref;
   // add the version-dependent text
   inner.innerText = "This is documentation for ";
   const isDev =
@@ -520,6 +569,7 @@ function showVersionWarningBanner(data) {
     bold.innerText = `version ${version}`;
   }
   banner.appendChild(middle);
+  banner.append(close_btn);
   middle.appendChild(inner);
   inner.appendChild(bold);
   inner.appendChild(document.createTextNode("."));

src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss

@@ -12,7 +12,7 @@
   }
 }
 
-.bd-header-version-warning,
+#bd-header-version-warning,
 .bd-header-announcement {
   min-height: 3rem;
   width: 100%;
@@ -69,6 +69,6 @@
   background-color: var(--pst-color-secondary-bg);
 }
 
-.bd-header-version-warning {
+#bd-header-version-warning {
   background-color: var(--pst-color-danger-bg);
 }

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html

@@ -1,7 +1,7 @@
 {#- The "revealer" allows async banners to be loaded, revealed, and animated together in a controlled way -#}
 <div class="pst-async-banner-revealer d-none">
 {#- Version warning banner is always loaded remotely/asynchronously #}
-  <aside class="bd-header-version-warning d-none d-print-none" aria-label="{{ _('Version warning') }}"></aside>
+  <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="{{ _('Version warning') }}"></aside>
 {#- But the announcement banner might be loaded locally or remotely -#}
 {%- set announcement_banner_label = _("Announcement") -%}
 {%- set announcement_banner_classes = "bd-header-announcement d-print-none" -%}