Story 2394: Version-aware Homepage Install Card (#2460)

Author: julioest

static/css/v3/install-card.css

@@ -170,6 +170,47 @@
 
 /* Per-option visibility rules are generated by Django in _install_card.html */
 
+/* ── Latest/older variant toggle ─────────────────────────── */
+/* Both variants are always rendered server-side; the wrapper's data-active-variant
+   attribute controls which one is visible. JS flips it on version-dropdown change;
+   with JS disabled, the server-rendered value stays and a full request swaps it. */
+[data-install-card-wrapper][data-active-variant="latest"] .install-card--older,
+[data-install-card-wrapper][data-active-variant="older"] .install-card:not(.install-card--older) {
+  display: none;
+}
+
+@keyframes install-card-fade-in {
+  from { opacity: 0; transform: translateY(4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.install-card--entering {
+  animation: install-card-fade-in 200ms ease-out;
+}
+
+/* ── Older-version variant ───────────────────────────────── */
+.install-card--older {
+  gap: var(--space-large);
+}
+
+.install-card__older-message {
+  margin: 0;
+  /* Override the site-wide `p { @apply py-5 }` from frontend/styles.css */
+  padding-top: 0;
+  padding-bottom: 0;
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height-loose);
+}
+
+.install-card__older-cta {
+  display: flex;
+}
+
+.install-card__older-cta .btn {
+  flex: 1 0 0;
+}
+
 /* ── Responsive ───────────────────────────────────────────── */
 @media (max-width: 767px) {
   .install-card__dropdown {

static/js/install-card-version-sync.js

@@ -0,0 +1,66 @@
+/**
+ * Install Card — In-place version sync
+ *
+ * Listens for the `boost:version-changed` CustomEvent dispatched by the header
+ * version-dropdown JS (see _header_v3.html) and swaps the install card between
+ * its "latest" and "older" variants without a page reload.
+ *
+ * Progressive enhancement: with JS disabled, the dropdown's form submits
+ * normally and the server's POST + 302 + GET roundtrip swaps the card.
+ *
+ * Requires:
+ *   - Wrapper element [data-install-card-wrapper][data-active-variant]
+ *     around each install card render (see _install_card.html).
+ *   - The header JS to dispatch `boost:version-changed` with detail
+ *     { slug, label, isLatest }.
+ */
+
+function _getOrCreateLiveRegion() {
+  var el = document.getElementById("install-card-live");
+  if (el) return el;
+  el = document.createElement("span");
+  el.id = "install-card-live";
+  el.setAttribute("aria-live", "polite");
+  el.style.cssText =
+    "position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;";
+  document.body.appendChild(el);
+  return el;
+}
+
+document.addEventListener("boost:version-changed", function (e) {
+  var detail = e.detail || {};
+  var isLatest = detail.isLatest === true;
+  var label = detail.label || "";
+
+  document
+    .querySelectorAll("[data-install-card-wrapper]")
+    .forEach(function (wrapper) {
+      var prev = wrapper.getAttribute("data-active-variant");
+      var next = isLatest ? "latest" : "older";
+
+      wrapper.setAttribute("data-active-variant", next);
+
+      if (prev !== next) {
+        var visible = isLatest
+          ? wrapper.querySelector(".install-card:not(.install-card--older)")
+          : wrapper.querySelector(".install-card--older");
+        if (visible) {
+          visible.classList.remove("install-card--entering");
+          void visible.offsetWidth;
+          visible.classList.add("install-card--entering");
+          visible.addEventListener(
+            "animationend",
+            function () {
+              visible.classList.remove("install-card--entering");
+            },
+            { once: true }
+          );
+        }
+      }
+    });
+
+  var liveRegion = _getOrCreateLiveRegion();
+  liveRegion.textContent = isLatest
+    ? "Showing install steps for the latest version."
+    : "Showing documentation link for Boost " + label + ".";
+});

templates/base.html

@@ -49,6 +49,7 @@
     <script src="{% static 'js/code-block.js' %}" defer></script>
     <script src="{% static 'js/boost-gecko/main.CsWsx5SC.js' %}" defer></script>
     <script src="{% static 'js/install-card.js' %}" defer></script>
+    <script src="{% static 'js/install-card-version-sync.js' %}" defer></script>
     {% else %}
     <script src="{% static 'js/boost-gecko/main.D1bdgn0u.js' %}" defer></script>
     {% endflag %}

templates/v3/includes/_code_block_card.html

@@ -11,14 +11,15 @@
     button_text   (optional) — if set, a button is shown
     button_url    (optional) — button href, default "#"
     button_aria_label (optional) — accessible name for the button; defaults to button_text if omitted
+    button_style  (optional) — forwarded to _button.html style (e.g. "teal", "yellow"); defaults to primary
 {% endcomment %}
 <div class="code-block-card code-block-card--{{ card_variant|default:'neutral' }}">
   <h2 class="card__title code-block-card__heading">{{ heading }}</h2>
   {% if description %}<p class="code-block-card__description">{{ description }}</p>{% endif %}
   {% if code or code_html %}{% include "v3/includes/_code_block.html" with code=code code_html=code_html language=language variant=block_variant|default:"grey-bg" %}{% endif %}
   {% if button_text %}
     <div class="card__cta_section">
-      {% include "v3/includes/_button.html" with label=button_text url=button_url|default:'#' aria_label=button_aria_label|default:button_text %}
+      {% include "v3/includes/_button.html" with label=button_text url=button_url|default:'#' aria_label=button_aria_label|default:button_text style=button_style %}
     </div>
   {% endif %}
 </div>

templates/v3/includes/_header_v3.html

@@ -136,6 +136,10 @@
    * Progressive enhancement for the cookie-mode version dropdown: send the
    * POST via fetch and update the UI in place, avoiding a full page reload.
    * Falls back to a normal form submit on any error.
+   *
+   * After a successful fetch, dispatch a `boost:version-changed` CustomEvent
+   * on document so other components (e.g. the install card) can react without
+   * a page reload. Detail: { slug, label, isLatest, docUrl }.
    */
   document.addEventListener('submit', function (e) {
     var form = e.target;
@@ -149,6 +153,8 @@
 
     var selectedValue = submitter.value;
     var newLabel = submitter.textContent.trim();
+    var isLatest = submitter.dataset.isLatest === 'true';
+    var docUrl = submitter.dataset.docUrl || '';
     var formData = new FormData(form);
     formData.set('version', selectedValue);
 
@@ -177,6 +183,10 @@
         var toggle = menu.querySelector('.header__version-toggle');
         if (toggle) toggle.checked = false;
       });
+
+      document.dispatchEvent(new CustomEvent('boost:version-changed', {
+        detail: { slug: selectedValue, label: newLabel, isLatest: isLatest, docUrl: docUrl }
+      }));
     }).catch(function () {
       form.submit();
     });

templates/v3/includes/_install_card.html

@@ -12,6 +12,13 @@
        are visible. Dynamic :checked ~ rules are generated in the inline <style>
        block below because the number of options is data-driven.
 
+    Both the latest-version and older-version variants are always rendered inside
+    a wrapper with data-active-variant="latest|older". CSS hides the inactive
+    one. install-card-version-sync.js (cookie-mode pages only) flips the
+    attribute on version-dropdown change so the swap happens without a page
+    refresh; with JS disabled, the server-rendered variant stays and the
+    dropdown's POST + redirect path handles the swap on the next request.
+
   Variables:
     title (optional) — card heading text; defaults to "Install Boost and get started in your terminal."
     card_id (IMPORTANT) — unique identifier to scope IDs/names when multiple cards appear on the same page; defaults to slugified title, then "install"
@@ -26,6 +33,7 @@
   Dependencies:
     CSS: card.css, tab.css, install-card.css, code-block.css, forms.css (.dropdown)
     JS:  install-card.js (keyboard nav + ARIA updates; optional — core works without it)
+         install-card-version-sync.js (in-place version swap; optional — server roundtrip works without it)
 
   Accessibility:
     - role="tablist" on tab container, role="tab" on labels, role="tabpanel" on panels
@@ -37,6 +45,25 @@
 {% endcomment %}
 {% with resolved_title=title|slugify|default:"install" %}
 {% with card_id=card_id|default:resolved_title %}
+<div class="install-card-wrapper"
+     data-install-card-wrapper
+     data-active-variant="{% if selected_version_is_non_latest %}older{% else %}latest{% endif %}">
+<section class="install-card install-card--older card"
+         aria-labelledby="{{ card_id }}-older-heading">
+  <div class="card__header">
+    <h2 id="{{ card_id }}-older-heading" class="card__title install-card__title">
+      {{ title|default:"Install Boost and get started in your terminal." }}
+    </h2>
+  </div>
+  <div class="install-card__body px-large">
+    <p class="install-card__older-message">
+      You are viewing an older version. See the documentation for installation steps.
+    </p>
+    <div class="install-card__older-cta">
+      {% include "v3/includes/_button.html" with label="See Documentation" url="/doc/user-guide/getting-started.html" style="teal" aria_label="See documentation for installation steps" only %}
+    </div>
+  </div>
+</section>
 {# Per-option visibility rules (generated from data, complements static rules in install-card.css) #}
 <style>
   {% for opt in install_card_pkg_managers %}
@@ -131,5 +158,6 @@ <h2 id="{{ card_id }}-heading" class="card__title install-card__title">
     </div>
   </div>
 </section>
+</div>
 {% endwith %}
 {% endwith %}

templates/v3/includes/header/_header_version_dropdown.html

@@ -42,12 +42,17 @@
         {% if latest_href %}
           <a href="{{ latest_href }}"
              class="header__version-option"
+             data-version-option
+             data-is-latest="true"
              {% if not selected_version_is_non_latest %}aria-current="true"{% endif %}>Latest</a>
         {% endif %}
         {% for v in version_dropdown_options %}
           {% if v.href %}
             <a href="{{ v.href }}"
                class="header__version-option"
+               data-version-option
+               data-is-latest="false"
+               data-doc-url="{{ v.documentation_url }}"
                {% if selected_version_is_non_latest and selected_version and v.slug == selected_version.slug %}aria-current="true"{% endif %}>
               {{ v.display_name }}
             </a>
@@ -62,12 +67,17 @@
                   name="version"
                   value="latest"
                   class="header__version-option"
+                  data-version-option
+                  data-is-latest="true"
                   {% if not selected_version_is_non_latest %}aria-current="true"{% endif %}>Latest</button>
           {% for v in version_dropdown_options %}
             <button type="submit"
                     name="version"
                     value="{{ v.slug }}"
                     class="header__version-option"
+                    data-version-option
+                    data-is-latest="false"
+                    data-doc-url="{{ v.documentation_url }}"
                     {% if selected_version_is_non_latest and selected_version and v.slug == selected_version.slug %}aria-current="true"{% endif %}>
               {{ v.display_name }}
             </button>