History, URL & Navigation

const u = new URL("/docs/a?q=ts#top", "https://ex.com");
u.href;       // "https://ex.com/docs/a?q=ts#top"
u.pathname = "/docs/b c"; // setters percent-encode: b%20c
u.hash = "";  // drops the fragment
 
new URL("nope");        // throws TypeError
URL.canParse("nope");   // false
URL.parse("nope");      // null (no throw)
URL.parse("x", "https://ex.com/")?.href;

const p = new URLSearchParams("?tag=a&tag=b&q=hi+there");
p.get("q");          // "hi there" (+ decodes to space)
p.getAll("tag");     // ["a", "b"]
p.has("tag", "b");   // true (value overload)
p.size;              // 3
p.set("page", "2");  // replaces every "page"
p.append("tag", "c");
p.delete("tag", "a"); // only that pair
p.sort();
p.toString();        // "page=2&q=hi+there&tag=b&tag=c"
 
// Constructors: string, record, or pairs (for repeats)
new URLSearchParams({ q: "ts", page: String(2) });
new URLSearchParams([["tag", "a"], ["tag", "b"]]);

const post = new URLPattern({
  pathname: "/blog/:year(\\d{4})/:slug",
});
post.test("https://ex.com/blog/2026/hello"); // true
const m = post.exec("https://ex.com/blog/2026/hello");
m?.pathname.groups; // { year: "2026", slug: "hello" }
 
// String form needs a base for relative patterns
const files = new URLPattern("/files/*", location.origin);
files.exec(location.href)?.pathname.groups[0]; // rest
 
// Case-insensitive
new URLPattern({ pathname: "/Help" }, { ignoreCase: true });

type PageState = { scrollY: number; tab: string };
 
history.pushState(
  { scrollY: 0, tab: "a" } satisfies PageState,
  "", // title: unused, pass ""
  "/settings?tab=a",
);
history.replaceState({ ...history.state, tab: "b" }, "");
 
addEventListener("popstate", (e: PopStateEvent) => {
  const s = e.state as PageState | null; // any in lib.dom
  render(location.pathname, s);
});
declare function render(p: string, s: unknown): void;

navigation.addEventListener("navigate", (e) => {
  if (!e.canIntercept || e.hashChange) return;
  if (e.downloadRequest !== null) return;
  const url = new URL(e.destination.url);
  if (!url.pathname.startsWith("/app/")) return;
 
  e.intercept({
    async handler() {
      const html = await loadView(url, e.signal);
      document.querySelector("main")!.innerHTML = html;
    },
  });
});
declare function loadView(
  u: URL, s: AbortSignal,
): Promise<string>;

const { committed, finished } = navigation.navigate(
  "/app/inbox",
  { state: { from: "home" }, history: "push" },
);
await finished; // handler promise settled
 
navigation.currentEntry?.getState();
navigation.updateCurrentEntry({ state: { tab: 2 } });
navigation.entries().map((en) => en.url);
navigation.canGoBack && (await navigation.back().finished);

function route(): void {
  const path = location.hash.slice(1) || "/";
  view(path); // "#/users/7" gives "/users/7"
}
addEventListener("hashchange", route);
route();
declare function view(p: string): void;

const warn = (e: BeforeUnloadEvent) => {
  e.preventDefault();
  e.returnValue = true; // legacy browsers
};
function setDirty(dirty: boolean): void {
  if (dirty) addEventListener("beforeunload", warn);
  else removeEventListener("beforeunload", warn);
}

import { z } from "zod";
 
const Search = z.object({
  q: z.string().trim().default(""),
  page: z.coerce.number().int().min(1).catch(1),
  sort: z.enum(["new", "top"]).catch("new"),
  tag: z.array(z.string()).default([]),
});
type Search = z.infer<typeof Search>;

type QueryPatch = Record<string, string | number | null>;
 
export function setQuery(
  patch: QueryPatch,
  mode: "push" | "replace" = "replace",
): void {
  const url = new URL(location.href);
  for (const [k, v] of Object.entries(patch)) {
    if (v === null || v === "") url.searchParams.delete(k);
    else url.searchParams.set(k, String(v));
  }
  if (url.href === location.href) return;
  const s: unknown = history.state;
  if (mode === "push") history.pushState(s, "", url);
  else history.replaceState(s, "", url);
}
 
setQuery({ q: "zod", page: null }); // while typing
setQuery({ page: 2 }, "push");      // on click

type Params = Record<string, string | undefined>;
type View = (p: Params) => Promise<void>;
const routes: Array<[URLPattern, View]> = [];
export const on = (path: string, v: View) =>
  routes.push([new URLPattern({ pathname: path }), v]);
 
function match(href: string): (() => Promise<void>) | null {
  for (const [pat, view] of routes) {
    const m = pat.exec(href);
    if (m) return () => view(m.pathname.groups);
  }
  return null;
}
 
export function start(): void {
  if ("navigation" in window) {
    navigation.addEventListener("navigate", (e) => {
      const run = match(e.destination.url);
      if (!e.canIntercept || e.hashChange || !run) return;
      e.intercept({ handler: run });
    });
  } else {
    addEventListener("popstate", () => {
      void match(location.href)?.();
    });
    document.addEventListener("click", onClick);
  }
  void match(location.href)?.(); // first render
}

function onClick(e: MouseEvent): void {
  const a = (e.target as Element | null)?.closest("a");
  if (!a || a.target || a.hasAttribute("download")) return;
  if (e.defaultPrevented || e.button !== 0) return;
  if (e.metaKey || e.ctrlKey) return;
  if (e.shiftKey || e.altKey) return;
  if (a.origin !== location.origin) return;
  const run = match(a.href);
  if (!run) return;
  e.preventDefault();
  history.pushState(null, "", a.href);
  void run();
}

type QueryValue = string | number | boolean | undefined;
 
export function buildUrl(
  base: string,
  path: readonly string[],
  query: Record<string, QueryValue | QueryValue[]> = {},
): URL {
  const url = new URL(base);
  const segs = path.map(encodeURIComponent).join("/");
  url.pathname = url.pathname.replace(/\/?$/, "/") + segs;
  for (const [k, v] of Object.entries(query)) {
    for (const item of [v].flat()) {
      if (item !== undefined) {
        url.searchParams.append(k, String(item));
      }
    }
  }
  return url;
}
 
buildUrl("https://api.ex.com/v1", ["users", "a/b"], {
  tag: ["x", "y"], active: true,
}).href; // .../v1/users/a%2Fb?tag=x&tag=y&active=true

import { z } from "zod";
 
export function parseSearch<S extends z.ZodType>(
  schema: S,
  params: URLSearchParams,
): z.infer<S> {
  const raw: Record<string, string | string[]> = {};
  for (const key of new Set(params.keys())) {
    const all = params.getAll(key);
    raw[key] = all.length > 1 ? all : all[0]!;
  }
  return schema.parse(raw);
}
 
const Search = z.object({
  page: z.coerce.number().int().min(1).catch(1),
  tag: z.array(z.string())
    .or(z.string().transform((s) => [s]))
    .default([]),
});
const s = parseSearch(
  Search,
  new URL(location.href).searchParams,
);

export function safeNext(
  raw: string | null,
  fallback = "/",
): string {
  if (!raw) return fallback;
  const url = URL.parse(raw, location.origin);
  if (!url || url.origin !== location.origin) {
    return fallback;
  }
  return url.pathname + url.search + url.hash;
}
 
const q = new URLSearchParams(location.search);
const next = q.get("next");
location.replace(safeNext(next));