From 7aee62e905a46b699cf14be044b1dc2d13da69eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Z=CC=8Can=20Anderle?= <zan.anderle@gmail.com>
Date: Fri, 29 Nov 2024 14:45:31 +0100
Subject: [PATCH 1/5] Monkey-patch history pushState and replaceState to listen
 to location changes

---
 src/index.js |  2 ++
 src/utils.js | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/src/index.js b/src/index.js
index ad761db6..8c011684 100644
--- a/src/index.js
+++ b/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) {
diff --git a/src/utils.js b/src/utils.js
index 46c11cd5..34519196 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -155,6 +155,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 "pushState" or "replaceState" event, depending on which method was called.
+ *
+ */
+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(methodName);
+        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.
  *

From eca74eb80e5df759e0eb12ea5793d908873d4ed7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=BDan=20Anderle?= <zan.anderle@gmail.com>
Date: Fri, 10 Jan 2025 14:55:02 +0100
Subject: [PATCH 2/5] Update src/utils.js

Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
---
 src/utils.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/utils.js b/src/utils.js
index 34519196..af43f168 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -156,16 +156,16 @@ export class AddonBase {
 }
 
 /**
- * Setup events firing on history pushState and replaceState
+ * 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
+ * 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 "pushState" or "replaceState" event, depending on which method was called.
+ * It will fire a `READTHEDOCS_URL_CHANGED` event, on `pushState` and `replaceState`.
  *
  */
 export function setupHistoryEvents() {

From 861e2c29b86834b330bad34e929f8b81583d1780 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Z=CC=8Can=20Anderle?= <zan.anderle@gmail.com>
Date: Fri, 10 Jan 2025 14:57:26 +0100
Subject: [PATCH 3/5] Change the name of the event triggered when url is
 changed

---
 src/utils.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/utils.js b/src/utils.js
index af43f168..99481106 100644
--- a/src/utils.js
+++ b/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" ||
@@ -180,7 +182,7 @@ export function setupHistoryEvents() {
       const originalMethod = history[methodName];
       history[methodName] = function () {
         const result = originalMethod.apply(this, arguments);
-        const event = new Event(methodName);
+        const event = new Event(READTHEDOCS_URL_CHANGED_EVENT);
         event.arguments = arguments;
 
         dispatchEvent(event);

From bae8d79256f80aab3487d18adce22b131b87e66c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Z=CC=8Can=20Anderle?= <zan.anderle@gmail.com>
Date: Fri, 10 Jan 2025 15:13:20 +0100
Subject: [PATCH 4/5] Add a simple check on index.html to confirm it works

---
 public/index.html | 15 +++++++++++++++
 src/utils.js      |  2 +-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/public/index.html b/public/index.html
index f24ff41a..01ea0a2e 100644
--- a/public/index.html
+++ b/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>
diff --git a/src/utils.js b/src/utils.js
index 99481106..8d4492a8 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -24,7 +24,7 @@ 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 READTHEDOCS_URL_CHANGED_EVENT = "readthedocsUrlChanged";
 
 export const domReady = new Promise((resolve) => {
   if (

From a08340a9f56f60fec4e0a33097ef968132a07b09 Mon Sep 17 00:00:00 2001
From: Manuel Kaufmann <humitos@gmail.com>
Date: Wed, 22 Jan 2025 13:01:42 +0100
Subject: [PATCH 5/5] Minor updates from review feedback

---
 public/index.html | 2 +-
 src/events.js     | 5 +++++
 src/utils.js      | 5 ++---
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/public/index.html b/public/index.html
index 01ea0a2e..8d786473 100644
--- a/public/index.html
+++ b/public/index.html
@@ -53,7 +53,7 @@ <h2>Test URL changes</h2>
           history.pushState({}, "", `#url-${randomHash}`);
         });
 
-        window.addEventListener("readthedocsUrlChanged", (ev) => {console.log("URL Change detected!", ev)});
+        window.addEventListener("readthedocs-url-changed", (ev) => {console.log("URL Change detected!", ev)});
       </script>
 
       <h2>Link Previews</h2>
diff --git a/src/events.js b/src/events.js
index 740bed97..02cba032 100644
--- a/src/events.js
+++ b/src/events.js
@@ -8,6 +8,11 @@ export const EVENT_READTHEDOCS_DOCDIFF_HIDE = "readthedocs-docdiff-hide";
 export const EVENT_READTHEDOCS_FLYOUT_SHOW = "readthedocs-flyout-show";
 export const EVENT_READTHEDOCS_FLYOUT_HIDE = "readthedocs-flyout-hide";
 
+/**
+ * Event triggered when the URL has changed dynamically (modifying the history object)
+ */
+export const EVENT_READTHEDOCS_URL_CHANGED = "readthedocs-url-changed";
+
 /**
  * Event triggered when the Read the Docs data is ready to be consumed.
  *
diff --git a/src/utils.js b/src/utils.js
index ca4035e6..ff7b2962 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -17,6 +17,7 @@ import {
   ANTORA,
   DOCSIFY,
 } from "./constants";
+import { EVENT_READTHEDOCS_URL_CHANGED } from "./events";
 
 export const ADDONS_API_VERSION = "1";
 export const ADDONS_API_ENDPOINT = "/_/addons/";
@@ -29,8 +30,6 @@ 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" ||
@@ -187,7 +186,7 @@ export function setupHistoryEvents() {
       const originalMethod = history[methodName];
       history[methodName] = function () {
         const result = originalMethod.apply(this, arguments);
-        const event = new Event(READTHEDOCS_URL_CHANGED_EVENT);
+        const event = new Event(EVENT_READTHEDOCS_URL_CHANGED);
         event.arguments = arguments;
 
         dispatchEvent(event);