@barefootjs/router 0.14.0

package/dist/index.js

@@ -0,0 +1,655 @@
+// src/router.ts
+import { BF_REGION as BF_REGION2 } from "@barefootjs/shared";
+
+// src/cache.ts
+var REFRESH_JITTER = 0.3;
+function fetchSnapshot(state, url) {
+  return (async () => {
+    try {
+      const res = await state.fetchFn(url, { headers: { Accept: "text/html" }, credentials: "same-origin" });
+      if (!res.ok)
+        return null;
+      const finalUrl = res.redirected && res.url ? res.url : url;
+      const html = await res.text();
+      return { html, finalUrl };
+    } catch {
+      return null;
+    }
+  })();
+}
+function storeEntry(state, url, snap) {
+  const now = Date.now();
+  const jitter = 1 + (Math.random() * 2 - 1) * REFRESH_JITTER;
+  state.cache.set(url, {
+    snap,
+    refreshAt: now + state.cacheFreshMs * jitter,
+    staleAt: now + state.cacheStaleMs,
+    refreshing: false
+  });
+  snap.then((result) => {
+    if (result === null && state.cache.get(url)?.snap === snap)
+      state.cache.delete(url);
+  });
+  while (state.cache.size > state.cacheCap) {
+    const lru = state.cache.keys().next().value;
+    if (lru === undefined)
+      break;
+    state.cache.delete(lru);
+  }
+}
+function loadPage(state, url) {
+  const hit = state.cache.get(url);
+  const now = Date.now();
+  if (hit && now < hit.staleAt) {
+    if (now >= hit.refreshAt && !hit.refreshing) {
+      hit.refreshing = true;
+      const fresh = fetchSnapshot(state, url);
+      fresh.then((result) => {
+        if (result !== null)
+          storeEntry(state, url, fresh);
+        else if (state.cache.get(url) === hit)
+          hit.refreshing = false;
+      });
+    }
+    state.cache.delete(url);
+    state.cache.set(url, hit);
+    return hit.snap;
+  }
+  const snap = fetchSnapshot(state, url);
+  storeEntry(state, url, snap);
+  return snap;
+}
+
+// src/region.ts
+import { BF_HOST, BF_PROPS, BF_REGION, BF_SCOPE, BF_SCOPE_COMMENT_PREFIX } from "@barefootjs/shared";
+function parseDocument(html) {
+  return new DOMParser().parseFromString(html, "text/html");
+}
+function collectModuleScripts(root, baseUrl) {
+  const out = new Set;
+  for (const s of root.querySelectorAll('script[type="module"][src]')) {
+    const src = s.getAttribute("src");
+    if (!src)
+      continue;
+    try {
+      const url = new URL(src, baseUrl);
+      if (url.origin === window.location.origin)
+        out.add(url.href);
+    } catch {}
+  }
+  return out;
+}
+function indexRegions(root, selector) {
+  const map = new Map;
+  for (const el of root.querySelectorAll(selector)) {
+    const id = el.getAttribute(BF_REGION) ?? "";
+    if (map.has(id))
+      return null;
+    map.set(id, el);
+  }
+  return map;
+}
+function ownedContentKey(region, selector) {
+  const clone = region.cloneNode(true);
+  for (const nested of Array.from(clone.querySelectorAll(selector))) {
+    if (!clone.contains(nested))
+      continue;
+    const mask = (clone.ownerDocument ?? document).createElement("bf-region-mask");
+    mask.setAttribute("data-id", nested.getAttribute(BF_REGION) ?? "");
+    nested.replaceWith(mask);
+  }
+  stripVolatileHydration(clone);
+  return clone.innerHTML;
+}
+var VOLATILE_ATTRS = [BF_SCOPE, BF_HOST];
+function stripVolatileHydration(root) {
+  for (const a of VOLATILE_ATTRS)
+    root.removeAttribute(a);
+  normalizePropsAttr(root);
+  const walker = (root.ownerDocument ?? document).createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_COMMENT);
+  while (walker.nextNode()) {
+    const node = walker.currentNode;
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      for (const a of VOLATILE_ATTRS)
+        node.removeAttribute(a);
+      normalizePropsAttr(node);
+    } else if (node.data.startsWith(BF_SCOPE_COMMENT_PREFIX)) {
+      node.data = normalizeScopeComment(node.data);
+    }
+  }
+}
+function normalizePropsAttr(el) {
+  const raw = el.getAttribute(BF_PROPS);
+  if (raw === null)
+    return;
+  try {
+    const obj = JSON.parse(raw);
+    if (obj && typeof obj === "object" && "scopeID" in obj) {
+      obj.scopeID = "";
+      el.setAttribute(BF_PROPS, JSON.stringify(obj));
+    }
+  } catch {}
+}
+function normalizeScopeComment(data) {
+  const parts = data.slice(BF_SCOPE_COMMENT_PREFIX.length).split("|");
+  parts[0] = "";
+  const kept = parts.filter((p, i) => i === 0 || !p.startsWith("h="));
+  return BF_SCOPE_COMMENT_PREFIX + kept.join("|");
+}
+function planRegionSwaps(currentRoot, incomingRoot, selector, baselines) {
+  const cur = indexRegions(currentRoot, selector);
+  const inc = indexRegions(incomingRoot, selector);
+  if (!cur || !inc || !sameKeys(cur, inc))
+    return { mode: "broadest" };
+  const incomingKeys = new Map;
+  const candidates = [];
+  for (const [id, current] of cur) {
+    const incoming = inc.get(id);
+    const incomingKey = ownedContentKey(incoming, selector);
+    incomingKeys.set(id, incomingKey);
+    const baseline = baselines.get(id) ?? ownedContentKey(current, selector);
+    if (incomingKey !== baseline)
+      candidates.push({ current, incoming });
+  }
+  const targets = candidates.filter((c) => !candidates.some((o) => o !== c && o.current.contains(c.current)));
+  return { mode: "regions", targets, incomingKeys };
+}
+function captureRegionBaselines(root, selector) {
+  const out = new Map;
+  for (const el of root.querySelectorAll(selector)) {
+    out.set(el.getAttribute(BF_REGION) ?? "", ownedContentKey(el, selector));
+  }
+  return out;
+}
+function sameKeys(a, b) {
+  if (a.size !== b.size)
+    return false;
+  for (const k of a.keys())
+    if (!b.has(k))
+      return false;
+  return true;
+}
+function isRootRegion(region, selector) {
+  const root = region.ownerDocument ?? document;
+  for (const el of root.querySelectorAll(selector)) {
+    if (el !== region && !region.contains(el))
+      return false;
+  }
+  return true;
+}
+function importRegionChildren(incoming) {
+  return Array.from(incoming.childNodes).map((n) => document.importNode(n, true));
+}
+function collectRegionModuleSrcs(html, selector, baseUrl) {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  if (!doc.querySelector(selector))
+    return null;
+  return [...collectModuleScripts(doc, baseUrl)];
+}
+async function loadNewModules(state, srcs) {
+  const fresh = srcs.filter((s) => !state.loadedModules.has(s));
+  await Promise.all(fresh.map(async (src) => {
+    try {
+      await state.loadModule(src);
+      state.loadedModules.add(src);
+    } catch {}
+  }));
+}
+
+// src/morph.ts
+function permanentKey(el) {
+  const attr = el.getAttribute("data-bf-permanent");
+  if (attr)
+    return attr;
+  if (el.id)
+    return el.id;
+  return null;
+}
+function buildMorphedContent(current, incoming) {
+  const fragment = document.createDocumentFragment();
+  for (const node of incoming)
+    fragment.appendChild(node);
+  const liveByKey = new Map;
+  for (const el of current.querySelectorAll("[data-bf-permanent]")) {
+    const key = permanentKey(el);
+    if (key && !liveByKey.has(key))
+      liveByKey.set(key, el);
+  }
+  if (liveByKey.size === 0)
+    return fragment;
+  for (const placeholder of Array.from(fragment.querySelectorAll("[data-bf-permanent]"))) {
+    if (!fragment.contains(placeholder))
+      continue;
+    const key = permanentKey(placeholder);
+    if (!key)
+      continue;
+    const live = liveByKey.get(key);
+    if (!live)
+      continue;
+    placeholder.replaceWith(live);
+    liveByKey.delete(key);
+  }
+  return fragment;
+}
+
+// src/seams.ts
+import {
+  BF_HOST as BF_HOST2,
+  BF_SCOPE as BF_SCOPE2,
+  BF_SEAM_DISPOSE_WITHIN,
+  BF_SEAM_HYDRATE,
+  BF_SEAM_HYDRATE_WITHIN,
+  BF_SEAM_PUSH_SEARCH
+} from "@barefootjs/shared";
+function pushSearchSeam(search) {
+  const w = window;
+  const push = w[BF_SEAM_PUSH_SEARCH];
+  if (typeof push !== "function")
+    return false;
+  push(search);
+  return true;
+}
+async function defaultRehydrate(region) {
+  const w = window;
+  const hydrateWithin = w[BF_SEAM_HYDRATE_WITHIN];
+  if (typeof hydrateWithin === "function") {
+    hydrateWithin(region);
+    return;
+  }
+  const hydrateAll = w[BF_SEAM_HYDRATE];
+  if (typeof hydrateAll === "function") {
+    hydrateAll();
+    return;
+  }
+  try {
+    const spec = "@barefootjs/client/runtime";
+    const mod = await import(spec);
+    if (mod.rehydrateScope)
+      mod.rehydrateScope(region);
+    else
+      mod.rehydrateAll?.();
+  } catch {
+    warnIfIslandsUnreachable(region, "re-hydrate");
+  }
+}
+async function defaultDispose(region) {
+  const w = window;
+  const disposeWithin = w[BF_SEAM_DISPOSE_WITHIN];
+  if (typeof disposeWithin === "function") {
+    disposeWithin(region);
+    return;
+  }
+  try {
+    const spec = "@barefootjs/client/runtime";
+    const mod = await import(spec);
+    mod.disposeScope?.(region);
+  } catch {
+    warnIfIslandsUnreachable(region, "dispose");
+  }
+}
+function regionHasIslands(region) {
+  return region.hasAttribute(BF_SCOPE2) || region.hasAttribute(BF_HOST2) || region.querySelector(`[${BF_SCOPE2}],[${BF_HOST2}]`) !== null;
+}
+function warnIfIslandsUnreachable(region, op) {
+  if (!regionHasIslands(region))
+    return;
+  console.error(`[barefootjs/router] could not load @barefootjs/client/runtime to ${op} a region that contains islands. ` + `The swapped content may leak handlers or not be interactive — ensure the runtime is served and mapped in the page's import map.`);
+}
+function hardNavigate(url) {
+  window.location.assign(url);
+}
+
+// src/a11y.ts
+var LIVE_REGION_ID = "bf-route-announcer";
+function focusRegion(region) {
+  if (typeof document === "undefined")
+    return;
+  const target = region.querySelector('h1, h2, [role="heading"]') ?? region;
+  if (!target)
+    return;
+  if (!target.hasAttribute("tabindex"))
+    target.setAttribute("tabindex", "-1");
+  try {
+    target.focus({ preventScroll: true });
+  } catch {
+    target.focus();
+  }
+}
+function announceNavigation(title) {
+  if (typeof document === "undefined")
+    return;
+  const message = (title ?? document.title ?? "").trim();
+  if (!message)
+    return;
+  const announcer = ensureAnnouncer();
+  announcer.textContent = "";
+  announcer.textContent = message;
+}
+function ensureAnnouncer() {
+  const existing = document.getElementById(LIVE_REGION_ID);
+  if (existing)
+    return existing;
+  const el = document.createElement("div");
+  el.id = LIVE_REGION_ID;
+  el.setAttribute("aria-live", "polite");
+  el.setAttribute("aria-atomic", "true");
+  el.setAttribute("role", "status");
+  el.style.cssText = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0";
+  document.body.appendChild(el);
+  return el;
+}
+
+// src/router.ts
+var active = null;
+function startRouter(options = {}) {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return { stop() {}, navigate: async () => {}, prefetch() {} };
+  }
+  if (active)
+    active.stop();
+  const state = {
+    regionSelector: options.region ?? `[${BF_REGION2}]`,
+    rehydrate: options.rehydrate ?? defaultRehydrate,
+    dispose: options.dispose ?? defaultDispose,
+    loadModule: options.loadModule ?? ((src) => import(src)),
+    fetchFn: options.fetch ?? ((input, init) => fetch(input, init)),
+    loadedModules: collectModuleScripts(document, window.location.href),
+    prefetchEnabled: options.prefetch ?? true,
+    prefetchDelay: options.prefetchDelay ?? 65,
+    cacheFreshMs: options.cacheFreshMs ?? 15000,
+    cacheStaleMs: options.cacheStaleMs ?? 60000,
+    cacheCap: options.cacheCap ?? 30,
+    cache: new Map,
+    preloaded: new Set,
+    shouldIntercept: options.shouldIntercept ?? defaultShouldIntercept,
+    scrollToTop: options.scrollToTop ?? true,
+    manageFocus: options.manageFocus ?? true,
+    morph: options.morph ?? true,
+    regionBaselines: captureRegionBaselines(document, options.region ?? `[${BF_REGION2}]`),
+    currentPath: window.location.pathname,
+    inflight: null,
+    hoverTimer: null,
+    hoverAnchor: null,
+    stop: () => {}
+  };
+  document.addEventListener("click", onClick);
+  window.addEventListener("popstate", onPopState);
+  if (state.prefetchEnabled) {
+    document.addEventListener("mouseover", onPointerOver);
+    document.addEventListener("mouseout", onPointerOut);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("pointerdown", onPointerDown);
+  }
+  commitHistory("replace", window.location.href);
+  state.stop = () => {
+    document.removeEventListener("click", onClick);
+    window.removeEventListener("popstate", onPopState);
+    document.removeEventListener("mouseover", onPointerOver);
+    document.removeEventListener("mouseout", onPointerOut);
+    document.removeEventListener("focusin", onFocusIn);
+    document.removeEventListener("pointerdown", onPointerDown);
+    clearHoverTimer(state);
+    state.inflight?.abort();
+    if (active === state)
+      active = null;
+  };
+  active = state;
+  return { stop: state.stop, navigate, prefetch: (url) => prefetch(url) };
+}
+function toFragment(nodes) {
+  const frag = document.createDocumentFragment();
+  for (const node of nodes)
+    frag.appendChild(node);
+  return frag;
+}
+function commitHistory(mode, url) {
+  if (mode === "push") {
+    window.history.pushState({ bfRouter: true }, "", url);
+  } else {
+    const prev = window.history.state ?? {};
+    window.history.replaceState({ ...prev, bfRouter: true }, "", url);
+  }
+}
+function onClick(event) {
+  if (!active)
+    return;
+  if (event.defaultPrevented)
+    return;
+  if (event.button !== 0)
+    return;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+    return;
+  const target = event.target;
+  const anchor = target?.closest?.("a");
+  if (!anchor || !anchor.getAttribute("href"))
+    return;
+  if (!active.shouldIntercept(anchor, event))
+    return;
+  event.preventDefault();
+  navigate(anchor.href);
+}
+function defaultShouldIntercept(anchor) {
+  if (anchor.dataset.bfRouter === "false")
+    return false;
+  if (anchor.hasAttribute("download"))
+    return false;
+  const linkTarget = anchor.getAttribute("target");
+  if (linkTarget && linkTarget !== "_self")
+    return false;
+  const rel = anchor.getAttribute("rel") ?? "";
+  if (rel.split(/\s+/).includes("external"))
+    return false;
+  let url;
+  try {
+    url = new URL(anchor.href, window.location.href);
+  } catch {
+    return false;
+  }
+  if (url.origin !== window.location.origin)
+    return false;
+  if (url.pathname === window.location.pathname && url.search === window.location.search && url.hash) {
+    return false;
+  }
+  return true;
+}
+function onPopState() {
+  if (!active)
+    return;
+  if (window.location.pathname === active.currentPath && pushSearchSeam(window.location.search)) {
+    return;
+  }
+  navigate(window.location.href, { history: false });
+}
+async function navigate(url, options = {}) {
+  if (typeof window === "undefined" || typeof document === "undefined")
+    return;
+  const mode = options.history ?? "push";
+  const state = active;
+  if (!state) {
+    hardNavigate(url);
+    return;
+  }
+  const target = new URL(url, window.location.href);
+  if (target.origin !== window.location.origin) {
+    hardNavigate(url);
+    return;
+  }
+  if (target.pathname === window.location.pathname && target.search !== window.location.search && pushSearchSeam(target.search)) {
+    state.inflight?.abort();
+    if (mode === "push")
+      commitHistory("push", target.href);
+    else if (mode === "replace")
+      commitHistory("replace", target.href);
+    return;
+  }
+  state.inflight?.abort();
+  const controller = new AbortController;
+  state.inflight = controller;
+  try {
+    const snap = await loadPage(state, target.href);
+    if (controller.signal.aborted)
+      return;
+    if (!snap) {
+      hardNavigate(target.href);
+      return;
+    }
+    const finalUrl = snap.finalUrl;
+    const incomingDoc = parseDocument(snap.html);
+    const title = incomingDoc.querySelector("title")?.textContent ?? null;
+    const moduleSrcs = [...collectModuleScripts(incomingDoc, finalUrl)];
+    const plan = planRegionSwaps(document, incomingDoc, state.regionSelector, state.regionBaselines);
+    let targets;
+    if (plan.mode === "regions") {
+      targets = plan.targets;
+    } else {
+      const current = document.querySelector(state.regionSelector);
+      const incoming = incomingDoc.querySelector(state.regionSelector);
+      if (!current || !incoming || !isRootRegion(current, state.regionSelector)) {
+        hardNavigate(finalUrl);
+        return;
+      }
+      targets = [{ current, incoming }];
+    }
+    const swapped = [];
+    for (const { current, incoming } of targets) {
+      const nodes = importRegionChildren(incoming);
+      const fragment = state.morph ? buildMorphedContent(current, nodes) : toFragment(nodes);
+      const outgoing = current.cloneNode(false);
+      while (current.firstChild)
+        outgoing.append(current.firstChild);
+      current.replaceChildren(fragment);
+      swapped.push({ region: current, outgoing });
+    }
+    if (title !== null)
+      document.title = title;
+    if (plan.mode === "regions") {
+      for (const [id, key] of plan.incomingKeys)
+        state.regionBaselines.set(id, key);
+    } else {
+      state.regionBaselines = captureRegionBaselines(document, state.regionSelector);
+    }
+    for (const { outgoing } of swapped)
+      await state.dispose(outgoing);
+    if (controller.signal.aborted)
+      return;
+    await loadNewModules(state, moduleSrcs);
+    if (controller.signal.aborted)
+      return;
+    if (mode === "push")
+      commitHistory("push", finalUrl);
+    else if (mode === "replace")
+      commitHistory("replace", finalUrl);
+    const committed = new URL(finalUrl, window.location.href);
+    state.currentPath = committed.pathname;
+    pushSearchSeam(committed.search);
+    if (state.scrollToTop)
+      window.scrollTo(0, 0);
+    for (const { region } of swapped)
+      await state.rehydrate(region);
+    if (controller.signal.aborted)
+      return;
+    if (state.manageFocus && swapped.length > 0) {
+      focusRegion(swapped[0].region);
+      announceNavigation(title);
+    }
+  } finally {
+    if (state.inflight === controller)
+      state.inflight = null;
+  }
+}
+function prefetch(url) {
+  const state = active;
+  if (!state)
+    return;
+  let target;
+  try {
+    target = new URL(url, window.location.href);
+  } catch {
+    return;
+  }
+  if (target.origin !== window.location.origin)
+    return;
+  if (target.href === window.location.href)
+    return;
+  loadPage(state, target.href).then((snap) => {
+    if (snap)
+      preloadModules(state, snap);
+  });
+}
+function preloadModules(state, snap) {
+  const srcs = collectRegionModuleSrcs(snap.html, state.regionSelector, snap.finalUrl) ?? [];
+  for (const src of srcs) {
+    if (state.loadedModules.has(src) || state.preloaded.has(src))
+      continue;
+    state.preloaded.add(src);
+    const link = document.createElement("link");
+    link.rel = "modulepreload";
+    link.href = src;
+    document.head.appendChild(link);
+  }
+}
+function clearHoverTimer(state) {
+  if (state.hoverTimer !== null) {
+    clearTimeout(state.hoverTimer);
+    state.hoverTimer = null;
+  }
+  state.hoverAnchor = null;
+}
+function prefetchableAnchor(event) {
+  const state = active;
+  if (!state)
+    return null;
+  const anchor = event.target?.closest?.("a");
+  if (!anchor || !anchor.getAttribute("href"))
+    return null;
+  if (!state.shouldIntercept(anchor, event))
+    return null;
+  return anchor;
+}
+function onPointerOver(event) {
+  const state = active;
+  if (!state)
+    return;
+  const anchor = prefetchableAnchor(event);
+  if (!anchor)
+    return;
+  if (anchor === state.hoverAnchor)
+    return;
+  clearHoverTimer(state);
+  state.hoverAnchor = anchor;
+  const href = anchor.href;
+  state.hoverTimer = setTimeout(() => {
+    state.hoverTimer = null;
+    state.hoverAnchor = null;
+    prefetch(href);
+  }, state.prefetchDelay);
+}
+function onPointerOut(event) {
+  const state = active;
+  if (!state || !state.hoverAnchor)
+    return;
+  const to = event.relatedTarget;
+  if (to && state.hoverAnchor.contains(to))
+    return;
+  clearHoverTimer(state);
+}
+function onFocusIn(event) {
+  const anchor = prefetchableAnchor(event);
+  if (anchor)
+    prefetch(anchor.href);
+}
+function onPointerDown(event) {
+  if (event.button !== 0)
+    return;
+  const anchor = prefetchableAnchor(event);
+  if (anchor)
+    prefetch(anchor.href);
+}
+
+// src/index.ts
+import { BF_REGION as BF_REGION3 } from "@barefootjs/shared";
+export {
+  startRouter,
+  navigate,
+  BF_REGION3 as BF_REGION
+};

package/dist/morph.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Permanent-node preservation during a region swap (spec/router.md **v1**,
+ * "persistence within a region": `data-bf-permanent` + idiomorph-style
+ * morphing).
+ *
+ * A plain swap (`replaceChildren`) tears the whole region down and rebuilds it,
+ * so anything with live state inside the region — a playing `<video>`, a
+ * scrolled list, an open `<details>`, an input's value — is lost across a
+ * navigation. An element marked `data-bf-permanent` is instead **preserved**:
+ * its *live* DOM node (with its state, media playback, scroll, and already-
+ * hydrated reactive scope) is moved into the incoming tree at the matching
+ * position, rather than disposed and recreated. (Focus is not preserved when
+ * the router's default `manageFocus` moves it to the region heading post-swap.)
+ *
+ * The match is keyed by the `data-bf-permanent` value (falling back to `id`),
+ * so the same logical element is recognised across the two page documents —
+ * idiomorph's id-keyed node reuse, scoped to the nodes the author marked.
+ */
+/**
+ * Assemble the incoming region nodes, moving any **live** `[data-bf-permanent]`
+ * node from `current` into the matching position of the new tree. Returns the
+ * fragment to insert.
+ *
+ * Call this **before** disposing `current`: moving the live nodes out first is
+ * exactly what spares them from the dispose walk, and re-inserting them keeps
+ * their hydrated scope marks so the subsequent re-hydration walk skips them
+ * (`hydrateElementScope` is a no-op on an already-hydrated node).
+ */
+export declare function buildMorphedContent(current: Element, incoming: Node[]): DocumentFragment;
+//# sourceMappingURL=morph.d.ts.map

package/dist/morph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph.d.ts","sourceRoot":"","sources":["../src/morph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,gBAAgB,CA+BxF"}