POC Monkey-patch history pushState and replaceState to listen to location changes

public/index.html

@@ -41,6 +41,21 @@ <h2 id="search">Search</h2>
       <p>Hit <code>/</code> to trigger the search modal, or click on the input from the flyout.</p>
       <readthedocs-search></readthedocs-search>
 
+      <h2>Test URL changes</h2>
+
+      <p>Quick check to see if the SPA url changes using "pushState" are correctly picked up using our utils (check console).</p>
+      <button id="change-url-button" type="button">Change URL</button>
+
+      <script>
+        const button = document.getElementById("change-url-button");
+        button.addEventListener("click", () => {
+          const randomHash = (Math.random() + 1).toString(36).substring(7);
+          history.pushState({}, "", `#url-${randomHash}`);
+        });
+
+        window.addEventListener("readthedocsUrlChanged", (ev) => {console.log("URL Change detected!", ev)});
+      </script>
+
       <h2>Link Previews</h2>
       <div role="main">
         <ul>

src/index.js

@@ -16,6 +16,7 @@ import {
   IS_PRODUCTION,
   setupLogging,
   getMetadataValue,
+  setupHistoryEvents,
 } from "./utils";
 
 export function setup() {
@@ -36,6 +37,7 @@ export function setup() {
     domReady
       .then(() => {
         setupLogging();
+        setupHistoryEvents();
 
         let sendUrlParam = false;
         for (const addon of addons) {

src/utils.js

@@ -24,6 +24,8 @@ export const IS_TESTING =
 export const IS_PRODUCTION =
   typeof WEBPACK_IS_PRODUCTION === "undefined" ? false : WEBPACK_IS_PRODUCTION;
 
+export const READTHEDOCS_URL_CHANGED_EVENT = "readthedocsUrlChanged";
+
 export const domReady = new Promise((resolve) => {
   if (
     document.readyState === "interactive" ||
@@ -155,6 +157,44 @@ export class AddonBase {
   }
 }
 
+/**
+ * Setup events firing on history `pushState` and `replaceState`
+ *
+ * This is needed when addons are used in SPA. A lot of addons rely
+ * on the current URL. However in the SPA, the pages are not reloaded, so
+ * the addons never get notified of the changes in the URL.
+ *
+ * While History API does have `popstate` event, the only way to listen to
+ * changes via `pushState` and `replaceState` is using monkey-patching, which is
+ * what this function does. (See https://stackoverflow.com/a/4585031)
+ * It will fire a `READTHEDOCS_URL_CHANGED` event, on `pushState` and `replaceState`.
+ *
+ */
+export function setupHistoryEvents() {
+  // Let's ensure that the history will be patched only once, so we create a Symbol to check by
+  const patchKey = Symbol.for("addons_history");
+
+  if (
+    typeof history !== "undefined" &&
+    typeof window[patchKey] === "undefined"
+  ) {
+    for (const methodName of ["pushState", "replaceState"]) {
+      const originalMethod = history[methodName];
+      history[methodName] = function () {
+        const result = originalMethod.apply(this, arguments);
+        const event = new Event(READTHEDOCS_URL_CHANGED_EVENT);
+        event.arguments = arguments;
+
+        dispatchEvent(event);
+        return result;
+      };
+    }
+
+    // Let's leave a flag, so we know that history has been patched
+    Object.defineProperty(window, patchKey, { value: true });
+  }
+}
+
 /**
  * Debounce a function.
  *