feat: support options.replace in hash router

packages/wouter-preact/types/use-hash-location.d.ts

@@ -1,6 +1,9 @@
 import { Path } from "./location-hook.js";
 
-export function navigate<S = any>(to: Path, options?: { state: S }): void;
+export function navigate<S = any>(
+  to: Path,
+  options?: { state?: S; replace?: boolean }
+): void;
 
 export function useHashLocation(options?: {
   ssrPath?: Path;

packages/wouter/src/use-hash-location.js

@@ -22,21 +22,26 @@ const subscribeToHashUpdates = (callback) => {
 // leading '#' is ignored, leading '/' is optional
 const currentHashLocation = () => "/" + location.hash.replace(/^#?\/?/, "");
 
-export const navigate = (to, { state = null } = {}) => {
-  // calling `replaceState` allows us to set the history
-  // state without creating an extra entry
+export const navigate = (to, { state = null, replace = false } = {}) => {
   const [hash, search] = to.replace(/^#?\/?/, "").split("?");
 
-  history.replaceState(
-    state,
-    "",
-    // keep the current pathname, but replace query string and hash
-    location.pathname +
-      (search ? `?${search}` : location.search) +
-      // update location hash, this will cause `hashchange` event to fire
-      // normalise the value before updating, so it's always preceeded with "#/"
-      (location.hash = `#/${hash}`)
-  );
+  const newRelativePath =
+    location.pathname + (search ? `?${search}` : location.search) + `#/${hash}`;
+  const oldURL = location.href;
+  const newURL = new URL(newRelativePath, location.origin).href;
+
+  if (replace) {
+    history.replaceState(state, "", newRelativePath);
+  } else {
+    history.pushState(state, "", newRelativePath);
+  }
+
+  const event =
+    typeof HashChangeEvent !== "undefined"
+      ? new HashChangeEvent("hashchange", { oldURL, newURL })
+      : new Event("hashchange", { detail: { oldURL, newURL } });
+
+  dispatchEvent(event);
 };
 
 export const useHashLocation = ({ ssrPath = "/" } = {}) => [

packages/wouter/test/use-hash-location.test.tsx

@@ -1,4 +1,4 @@
-import { it, expect, beforeEach } from "vitest";
+import { it, expect, beforeEach, vi } from "vitest";
 import { renderHook, render } from "@testing-library/react";
 import { renderToStaticMarkup } from "react-dom/server";
 
@@ -208,3 +208,69 @@ it("defines a custom way of rendering link hrefs", () => {
 
   expect(getByTestId("link")).toHaveAttribute("href", "#/app");
 });
+
+it("interacts properly with the history stack", () => {
+  const { result } = renderHook(() => useHashLocation());
+  const [, navigate] = result.current;
+
+  // case: replace, expect no history stack changes
+  const historyStackCountBeforeReplace = history.length;
+  navigate("/app/users", { replace: true });
+  expect(location.hash).toBe("#/app/users");
+  expect(history.length).toBe(historyStackCountBeforeReplace);
+
+  // case: push, expect history stack increase by 1
+  const historyStackCountBeforePush = history.length;
+  navigate("/app/users/2");
+  expect(location.hash).toBe("#/app/users/2");
+  expect(history.length).toBe(historyStackCountBeforePush + 1);
+});
+
+it("dispatches hashchange event when options.replace is true", () => {
+  const { result } = renderHook(() => useHashLocation());
+  const [, navigate] = result.current;
+
+  const hashChangeFn = vi.fn();
+  addEventListener("hashchange", hashChangeFn);
+
+  navigate("/foo/bar", { replace: true });
+  expect(hashChangeFn).toBeCalled();
+
+  removeEventListener("hashchange", hashChangeFn);
+});
+
+it("detects history change when navigate with options.replace is called", async () => {
+  const nextTick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+  const { result } = renderHook(() => useHashLocation());
+  const [, navigate] = result.current;
+
+  const newPath = "/foo/bar/baz";
+  navigate(newPath, { replace: true });
+  await nextTick();
+  expect(result.current[0]).toBe(newPath);
+});
+
+it("uses string URLs as hashchange event payload", () => {
+  const { result } = renderHook(() => useHashLocation());
+  const [, navigate] = result.current;
+
+  const relativeOldPath = "/foo";
+  const relativeNewPath = "/foo/bar/#hash";
+  const baseURL = "http://localhost:3000/#";
+
+  navigate(relativeOldPath);
+
+  let changeEvent = new HashChangeEvent("hashchange");
+  const hashChangeFn = (event: HashChangeEvent) => {
+    changeEvent = event;
+  };
+
+  addEventListener("hashchange", hashChangeFn);
+
+  navigate(relativeNewPath);
+  expect(changeEvent?.newURL).toBe(`${baseURL}${relativeNewPath}`);
+  expect(changeEvent?.oldURL).toBe(`${baseURL}${relativeOldPath}`);
+
+  removeEventListener("hashchange", hashChangeFn);
+});

packages/wouter/types/use-hash-location.d.ts

@@ -1,6 +1,9 @@
 import { Path } from "./location-hook.js";
 
-export function navigate<S = any>(to: Path, options?: { state: S }): void;
+export function navigate<S = any>(
+  to: Path,
+  options?: { state?: S; replace?: boolean }
+): void;
 
 export function useHashLocation(options?: {
   ssrPath?: Path;