feat: Implement popstate support for history navigation

Author: JohananOppongAmoateng

src/django_unicorn/static/unicorn/js/component.js

@@ -54,6 +54,7 @@ export class Component {
     this.attachedModelEvents = [];
 
     this.init();
+    this.initHistoryState();
     this.refreshEventListeners();
     this.initVisibility();
     this.initPolling();
@@ -373,6 +374,33 @@ export class Component {
     }
   }
 
+  /**
+   * Listens for browser `popstate` events (Back/Forward navigation) and restores
+   * the component state that was stored in the history entry. When a `LocationUpdate`
+   * is used, the component state is saved in `history.pushState`; this method
+   * retrieves that state and triggers `$refresh` so the server re-renders the
+   * component with the restored data.
+   */
+  initHistoryState() {
+    this.window.addEventListener("popstate", (event) => {
+      if (
+        event.state &&
+        event.state.unicorn &&
+        event.state.unicorn.componentId === this.id
+      ) {
+        // Merge the stored state back into the component data
+        Object.assign(this.data, event.state.unicorn.data);
+
+        // Ask the server to re-render with the restored data
+        this.callMethod("$refresh", 0, null, (err) => {
+          if (err) {
+            console.error(err);
+          }
+        });
+      }
+    });
+  }
+
   /**
    * Starts polling and handles stopping the polling if there is an error.
    */

src/django_unicorn/static/unicorn/js/messageSender.js

@@ -108,7 +108,12 @@ export function send(component, callback) {
             }
 
             component.window.history.pushState(
-              {},
+              {
+                unicorn: {
+                  componentId: component.id,
+                  data: component.data,
+                },
+              },
               "",
               responseJson.redirect.url
             );

tests/js/component/historyState.test.js

@@ -0,0 +1,82 @@
+import test from "ava";
+import { getComponent } from "../utils.js";
+
+const html = `
+<input type="hidden" name="csrfmiddlewaretoken" value="asdf">
+<div unicorn:id="5jypjiyb" unicorn:name="text-inputs" unicorn:checksum="GXzew3Km">
+    <input unicorn:model='name'></input>
+    <button unicorn:click='test()'><span id="clicker">Click</span></button>
+</div>
+`;
+
+test("popstate listener is registered on window", (t) => {
+    const component = getComponent(html);
+
+    // The initHistoryState() call should have registered a popstate listener
+    t.truthy(component._windowEventListeners["popstate"]);
+    t.is(component._windowEventListeners["popstate"].length, 1);
+});
+
+test("popstate ignores events with no unicorn state", (t) => {
+    const component = getComponent(html);
+
+    // Fire a popstate event with no state — should not trigger any refresh
+    const listeners = component._windowEventListeners["popstate"];
+    t.truthy(listeners);
+
+    // actionQueue should be empty before and after
+    t.is(component.actionQueue.length, 0);
+
+    listeners[0]({ state: null });
+    t.is(component.actionQueue.length, 0);
+});
+
+test("popstate ignores events with non-matching component id", (t) => {
+    const component = getComponent(html);
+    const listeners = component._windowEventListeners["popstate"];
+
+    t.is(component.actionQueue.length, 0);
+
+    // Fire with a different componentId — should be ignored
+    listeners[0]({
+        state: {
+            unicorn: {
+                componentId: "different-id",
+                data: { name: "OldValue" },
+            },
+        },
+    });
+
+    t.is(component.actionQueue.length, 0);
+});
+
+test("popstate restores data and triggers refresh for matching component", (t) => {
+    const component = getComponent(html);
+    const listeners = component._windowEventListeners["popstate"];
+
+    // Spy on callMethod so we can verify $refresh is called without needing
+    // a working HTTP endpoint
+    const calledMethods = [];
+    component.callMethod = (methodName) => {
+        calledMethods.push(methodName);
+    };
+
+    const previousData = { name: "PreviousName" };
+
+    // Fire popstate with a matching componentId and stored previous state
+    listeners[0]({
+        state: {
+            unicorn: {
+                componentId: component.id,
+                data: previousData,
+            },
+        },
+    });
+
+    // The stored data should have been merged back into the component
+    t.is(component.data.name, "PreviousName");
+
+    // $refresh should have been called to trigger a server re-render
+    t.is(calledMethods.length, 1);
+    t.is(calledMethods[0], "$refresh");
+});

tests/js/component/messageSender.test.js

@@ -80,6 +80,13 @@ test("call_method refresh redirect", async (t) => {
       t.true(err === null);
       t.is(component.window.history.get(), "/test/text-inputs?some=query");
       t.is(component.window.document.title, "new title");
+
+      // The history state should contain the component id and data
+      const state = component.window.history.getState();
+      t.truthy(state.unicorn);
+      t.is(state.unicorn.componentId, component.id);
+      t.deepEqual(state.unicorn.data, component.data);
+
       fetchMock.reset();
       resolve();
     });

tests/js/utils.js

@@ -103,13 +103,20 @@ export function getComponent(html, id, name, data) {
     data = { name: "World" };
   }
 
-  const mockHistory = { urls: [] };
+  const mockHistory = { urls: [], states: [] };
   mockHistory.pushState = (state, title, url) => {
     mockHistory.urls.push(url);
+    mockHistory.states.push(state);
   };
   mockHistory.get = () => {
     return mockHistory.urls[0];
   };
+  mockHistory.getState = () => {
+    return mockHistory.states[0];
+  };
+
+  // Track registered event listeners so tests can fire popstate manually
+  const windowEventListeners = {};
 
   const component = new Component({
     id,
@@ -123,9 +130,18 @@ export function getComponent(html, id, name, data) {
       document: { title: "" },
       history: mockHistory,
       location: { href: "" },
+      addEventListener: (type, handler) => {
+        if (!windowEventListeners[type]) {
+          windowEventListeners[type] = [];
+        }
+        windowEventListeners[type].push(handler);
+      },
     },
   });
 
+  // Expose so tests can trigger window events (e.g. popstate)
+  component._windowEventListeners = windowEventListeners;
+
   // Set the document explicitly for unit test purposes
   component.document = getDocument(html);