@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/router/client/link-intent.test.browser.js

@@ -1,54 +1,54 @@
-import { describe, expect, it } from "vitest";
-import { getAnchorFromNavigationEvent, isStaticAssetHref, recoverPendingNavigationHref } from "./link-intent.js";
-describe("getAnchorFromNavigationEvent", () => {
-  it("returns the anchor when the event target is a text node inside it", () => {
-    const anchor = document.createElement("a");
-    anchor.href = "/fast";
-    anchor.setAttribute("data-eco-link", "true");
-    const textNode = document.createTextNode("fast-link");
-    anchor.append(textNode);
-    document.body.append(anchor);
-    const event = new MouseEvent("click", { bubbles: true, cancelable: true, composed: true });
-    Object.defineProperty(event, "target", {
-      configurable: true,
-      value: textNode
+import { describe, expect, it } from 'vitest';
+import { getAnchorFromNavigationEvent, isStaticAssetHref, recoverPendingNavigationHref } from './link-intent.js';
+describe('getAnchorFromNavigationEvent', () => {
+    it('returns the anchor when the event target is a text node inside it', () => {
+        const anchor = document.createElement('a');
+        anchor.href = '/fast';
+        anchor.setAttribute('data-eco-link', 'true');
+        const textNode = document.createTextNode('fast-link');
+        anchor.append(textNode);
+        document.body.append(anchor);
+        const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
+        Object.defineProperty(event, 'target', {
+            configurable: true,
+            value: textNode,
+        });
+        expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
     });
-    expect(getAnchorFromNavigationEvent(event, "a[data-eco-link]")).toBe(anchor);
-  });
-  it("returns the closest matching anchor for nested element targets", () => {
-    const anchor = document.createElement("a");
-    anchor.href = "/fast";
-    anchor.setAttribute("data-eco-link", "true");
-    const span = document.createElement("span");
-    span.textContent = "fast-link";
-    anchor.append(span);
-    document.body.append(anchor);
-    const event = new MouseEvent("click", { bubbles: true, cancelable: true, composed: true });
-    Object.defineProperty(event, "target", {
-      configurable: true,
-      value: span
+    it('returns the closest matching anchor for nested element targets', () => {
+        const anchor = document.createElement('a');
+        anchor.href = '/fast';
+        anchor.setAttribute('data-eco-link', 'true');
+        const span = document.createElement('span');
+        span.textContent = 'fast-link';
+        anchor.append(span);
+        document.body.append(anchor);
+        const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
+        Object.defineProperty(event, 'target', {
+            configurable: true,
+            value: span,
+        });
+        expect(getAnchorFromNavigationEvent(event, 'a[data-eco-link]')).toBe(anchor);
     });
-    expect(getAnchorFromNavigationEvent(event, "a[data-eco-link]")).toBe(anchor);
-  });
 });
-describe("isStaticAssetHref", () => {
-  it("returns true for known static asset paths", () => {
-    expect(isStaticAssetHref("/skill.txt")).toBe(true);
-    expect(isStaticAssetHref("/skill/reference/full-stack.md")).toBe(true);
-    expect(isStaticAssetHref("/assets/logo.png")).toBe(true);
-  });
-  it("returns false for application routes", () => {
-    expect(isStaticAssetHref("/docs/getting-started/introduction")).toBe(false);
-    expect(isStaticAssetHref("/")).toBe(false);
-  });
+describe('isStaticAssetHref', () => {
+    it('returns true for known static asset paths', () => {
+        expect(isStaticAssetHref('/skill.txt')).toBe(true);
+        expect(isStaticAssetHref('/skill/reference/full-stack.md')).toBe(true);
+        expect(isStaticAssetHref('/assets/logo.png')).toBe(true);
+    });
+    it('returns false for application routes', () => {
+        expect(isStaticAssetHref('/docs/getting-started/introduction')).toBe(false);
+        expect(isStaticAssetHref('/')).toBe(false);
+    });
 });
-describe("recoverPendingNavigationHref", () => {
-  it("returns null for stale or missing pending intent state", () => {
-    expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();
-    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 0 }, false, 10)).toBeNull();
-    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 0 }, true, 2e3, 1e3)).toBeNull();
-  });
-  it("returns the captured href while a navigation is still in flight", () => {
-    expect(recoverPendingNavigationHref({ href: "/fast", timestamp: 10 }, true, 20, 1e3)).toBe("/fast");
-  });
+describe('recoverPendingNavigationHref', () => {
+    it('returns null for stale or missing pending intent state', () => {
+        expect(recoverPendingNavigationHref(null, true, 10)).toBeNull();
+        expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, false, 10)).toBeNull();
+        expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 0 }, true, 2000, 1000)).toBeNull();
+    });
+    it('returns the captured href while a navigation is still in flight', () => {
+        expect(recoverPendingNavigationHref({ href: '/fast', timestamp: 10 }, true, 20, 1000)).toBe('/fast');
+    });
 });

package/src/router/client/link-navigation-policy.js

@@ -1,101 +1,122 @@
-import { isStaticAssetHref } from "./link-intent.js";
+import { isStaticAssetHref } from './link-intent.js';
+/**
+ * Shared anchor/href checks for navigation interception and prefetch eligibility.
+ */
 function getLinkIneligibilityReason(link, options) {
-  if (options.noPrefetchAttribute && link.hasAttribute(options.noPrefetchAttribute)) {
-    return "no-prefetch";
-  }
-  if (options.reloadAttribute && link.hasAttribute(options.reloadAttribute)) {
-    return "explicit-reload";
-  }
-  if (link.hasAttribute("download")) {
-    return "download";
-  }
-  const href = link.getAttribute("href");
-  if (!href || href.startsWith("#") || href.startsWith("javascript:")) {
-    return "invalid-href";
-  }
-  const url = new URL(href, window.location.origin);
-  if (url.origin !== window.location.origin) {
-    return "cross-origin";
-  }
-  if (isStaticAssetHref(href)) {
-    return "static-asset";
-  }
-  return null;
+    if (options.noPrefetchAttribute && link.hasAttribute(options.noPrefetchAttribute)) {
+        return 'no-prefetch';
+    }
+    if (options.reloadAttribute && link.hasAttribute(options.reloadAttribute)) {
+        return 'explicit-reload';
+    }
+    if (link.hasAttribute('download')) {
+        return 'download';
+    }
+    const href = link.getAttribute('href');
+    if (!href || href.startsWith('#') || href.startsWith('javascript:')) {
+        return 'invalid-href';
+    }
+    const url = new URL(href, window.location.origin);
+    if (url.origin !== window.location.origin) {
+        return 'cross-origin';
+    }
+    if (isStaticAssetHref(href)) {
+        return 'static-asset';
+    }
+    return null;
 }
-function isSamePageHashNavigationHref(href) {
-  if (!href) {
-    return false;
-  }
-  const currentUrl = new URL(window.location.href);
-  const targetUrl = new URL(href, currentUrl);
-  return targetUrl.origin === currentUrl.origin && targetUrl.hash.length > 0 && targetUrl.pathname === currentUrl.pathname && targetUrl.search === currentUrl.search;
+/**
+ * Returns whether an href only adds a hash fragment on the current page.
+ */
+export function isSamePageHashNavigationHref(href) {
+    if (!href) {
+        return false;
+    }
+    const currentUrl = new URL(window.location.href);
+    const targetUrl = new URL(href, currentUrl);
+    return (targetUrl.origin === currentUrl.origin &&
+        targetUrl.hash.length > 0 &&
+        targetUrl.pathname === currentUrl.pathname &&
+        targetUrl.search === currentUrl.search);
 }
-function getLinkNavigationDecision(event, link, options) {
-  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-    return { shouldIntercept: false, reason: "modified-click" };
-  }
-  if (event.button !== 0) {
-    return { shouldIntercept: false, reason: "non-left-click" };
-  }
-  const target = link.getAttribute("target");
-  if (target && target !== "_self") {
-    return { shouldIntercept: false, reason: "external-target" };
-  }
-  const ineligibility = getLinkIneligibilityReason(link, options);
-  if (ineligibility) {
-    return { shouldIntercept: false, reason: ineligibility };
-  }
-  const href = link.getAttribute("href");
-  if (isSamePageHashNavigationHref(href)) {
-    return { shouldIntercept: false, reason: "same-page-hash" };
-  }
-  return { shouldIntercept: true, href };
+/**
+ * Decides whether a pointer or click on an anchor should be handled as SPA navigation.
+ */
+export function getLinkNavigationDecision(event, link, options) {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+        return { shouldIntercept: false, reason: 'modified-click' };
+    }
+    if (event.button !== 0) {
+        return { shouldIntercept: false, reason: 'non-left-click' };
+    }
+    const target = link.getAttribute('target');
+    if (target && target !== '_self') {
+        return { shouldIntercept: false, reason: 'external-target' };
+    }
+    const ineligibility = getLinkIneligibilityReason(link, options);
+    if (ineligibility) {
+        return { shouldIntercept: false, reason: ineligibility };
+    }
+    const href = link.getAttribute('href');
+    if (isSamePageHashNavigationHref(href)) {
+        return { shouldIntercept: false, reason: 'same-page-hash' };
+    }
+    return { shouldIntercept: true, href };
 }
-function getNavigableHrefFromClick(event, link, options) {
-  const decision = getLinkNavigationDecision(event, link, options);
-  return decision.shouldIntercept ? decision.href : null;
+/**
+ * Returns the href when SPA navigation should intercept the click, otherwise `null`.
+ */
+export function getNavigableHrefFromClick(event, link, options) {
+    const decision = getLinkNavigationDecision(event, link, options);
+    return decision.shouldIntercept ? decision.href : null;
 }
-function shouldPrefetchLink(link, options) {
-  if (getLinkIneligibilityReason(link, options)) {
-    return false;
-  }
-  const href = link.getAttribute("href");
-  try {
-    const url = new URL(href, window.location.origin);
-    const currentPath = window.location.pathname + window.location.search;
-    const targetPath = url.pathname + url.search;
-    return currentPath !== targetPath;
-  } catch {
-    return false;
-  }
+/**
+ * Returns whether a link is eligible for hover or viewport prefetch.
+ */
+export function shouldPrefetchLink(link, options) {
+    if (getLinkIneligibilityReason(link, options)) {
+        return false;
+    }
+    const href = link.getAttribute('href');
+    try {
+        const url = new URL(href, window.location.origin);
+        const currentPath = window.location.pathname + window.location.search;
+        const targetPath = url.pathname + url.search;
+        return currentPath !== targetPath;
+    }
+    catch {
+        return false;
+    }
 }
-function isHtmlPageResponse(response) {
-  const contentType = response.headers.get("Content-Type");
-  if (!contentType) {
-    return false;
-  }
-  const normalized = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-  return normalized === "text/html" || normalized === "application/xhtml+xml";
+/**
+ * @remarks
+ * Prefetch and SPA fetches request HTML. Only explicit `text/html` and
+ * `application/xhtml+xml` responses are accepted; missing or asset types are rejected.
+ */
+export function isHtmlPageResponse(response) {
+    const contentType = response.headers.get('Content-Type');
+    if (!contentType) {
+        return false;
+    }
+    const normalized = contentType.split(';')[0]?.trim().toLowerCase() ?? '';
+    return normalized === 'text/html' || normalized === 'application/xhtml+xml';
 }
-async function assertHtmlPageResponse(response) {
-  if (isHtmlPageResponse(response)) {
-    return;
-  }
-  const contentType = response.headers.get("Content-Type");
-  const normalized = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
-  if (normalized === "text/plain" || normalized === "") {
-    const sample = (await response.clone().text()).trimStart();
-    if (sample.startsWith("<")) {
-      return;
-    }
-  }
-  throw new Error(`Expected HTML page response, received ${contentType ?? "unknown content type"}`);
+/**
+ * @remarks
+ * Servers should send `text/html`. When the type is missing or the runtime
+ * defaults to `text/plain` (common in tests), a document-shaped body is accepted.
+ */
+export async function assertHtmlPageResponse(response) {
+    if (isHtmlPageResponse(response)) {
+        return;
+    }
+    const contentType = response.headers.get('Content-Type');
+    const normalized = contentType?.split(';')[0]?.trim().toLowerCase() ?? '';
+    if (normalized === 'text/plain' || normalized === '') {
+        const sample = (await response.clone().text()).trimStart();
+        if (sample.startsWith('<')) {
+            return;
+        }
+    }
+    throw new Error(`Expected HTML page response, received ${contentType ?? 'unknown content type'}`);
 }
-export {
-  assertHtmlPageResponse,
-  getLinkNavigationDecision,
-  getNavigableHrefFromClick,
-  isHtmlPageResponse,
-  isSamePageHashNavigationHref,
-  shouldPrefetchLink
-};

package/src/router/client/link-navigation-policy.test.browser.js

@@ -1,92 +1,82 @@
-import { describe, expect, it } from "vitest";
-import {
-  getLinkNavigationDecision,
-  getNavigableHrefFromClick,
-  isHtmlPageResponse,
-  isSamePageHashNavigationHref,
-  shouldPrefetchLink
-} from "./link-navigation-policy.js";
+import { describe, expect, it } from 'vitest';
+import { getLinkNavigationDecision, getNavigableHrefFromClick, isHtmlPageResponse, isSamePageHashNavigationHref, shouldPrefetchLink, } from './link-navigation-policy.js';
 function createLink(href, attributes = {}) {
-  const link = document.createElement("a");
-  link.href = href;
-  for (const [key, value] of Object.entries(attributes)) {
-    link.setAttribute(key, value);
-  }
-  document.body.append(link);
-  return link;
+    const link = document.createElement('a');
+    link.href = href;
+    for (const [key, value] of Object.entries(attributes)) {
+        link.setAttribute(key, value);
+    }
+    document.body.append(link);
+    return link;
 }
 function createMouseEvent(button = 0, modifiers = {}) {
-  return new MouseEvent("click", { bubbles: true, cancelable: true, button, ...modifiers });
+    return new MouseEvent('click', { bubbles: true, cancelable: true, button, ...modifiers });
 }
-const policy = { reloadAttribute: "data-eco-reload", noPrefetchAttribute: "data-eco-no-prefetch" };
-describe("isSamePageHashNavigationHref", () => {
-  it("returns true for same pathname with a new hash", () => {
-    history.replaceState({}, "", "/docs/page");
-    expect(isSamePageHashNavigationHref("/docs/page#section")).toBe(true);
-  });
+const policy = { reloadAttribute: 'data-eco-reload', noPrefetchAttribute: 'data-eco-no-prefetch' };
+describe('isSamePageHashNavigationHref', () => {
+    it('returns true for same pathname with a new hash', () => {
+        history.replaceState({}, '', '/docs/page');
+        expect(isSamePageHashNavigationHref('/docs/page#section')).toBe(true);
+    });
 });
-describe("getLinkNavigationDecision", () => {
-  it("allows same-origin page links", () => {
-    const link = createLink("/page");
-    const decision = getLinkNavigationDecision(createMouseEvent(), link, policy);
-    expect(decision).toEqual({ shouldIntercept: true, href: "/page" });
-  });
-  it("rejects static asset links", () => {
-    const link = createLink("/skill.txt");
-    expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
-      shouldIntercept: false,
-      reason: "static-asset"
+describe('getLinkNavigationDecision', () => {
+    it('allows same-origin page links', () => {
+        const link = createLink('/page');
+        const decision = getLinkNavigationDecision(createMouseEvent(), link, policy);
+        expect(decision).toEqual({ shouldIntercept: true, href: '/page' });
+    });
+    it('rejects static asset links', () => {
+        const link = createLink('/skill.txt');
+        expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+            shouldIntercept: false,
+            reason: 'static-asset',
+        });
     });
-  });
-  it("rejects explicit reload links", () => {
-    const link = createLink("/logout", { "data-eco-reload": "" });
-    expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
-      shouldIntercept: false,
-      reason: "explicit-reload"
+    it('rejects explicit reload links', () => {
+        const link = createLink('/logout', { 'data-eco-reload': '' });
+        expect(getLinkNavigationDecision(createMouseEvent(), link, policy)).toEqual({
+            shouldIntercept: false,
+            reason: 'explicit-reload',
+        });
     });
-  });
 });
-describe("getNavigableHrefFromClick", () => {
-  it("returns href when navigation should be intercepted", () => {
-    const link = createLink("/page");
-    expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBe("/page");
-  });
-  it("returns null for static assets", () => {
-    const link = createLink("/llms.txt");
-    expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBeNull();
-  });
+describe('getNavigableHrefFromClick', () => {
+    it('returns href when navigation should be intercepted', () => {
+        const link = createLink('/page');
+        expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBe('/page');
+    });
+    it('returns null for static assets', () => {
+        const link = createLink('/llms.txt');
+        expect(getNavigableHrefFromClick(createMouseEvent(), link, policy)).toBeNull();
+    });
 });
-describe("shouldPrefetchLink", () => {
-  it("prefetches internal page links", () => {
-    history.replaceState({}, "", "/");
-    const link = createLink("/docs/intro");
-    expect(shouldPrefetchLink(link, policy)).toBe(true);
-  });
-  it("skips static assets and opt-outs", () => {
-    history.replaceState({}, "", "/");
-    expect(shouldPrefetchLink(createLink("/skill.txt"), policy)).toBe(false);
-    expect(shouldPrefetchLink(createLink("/page", { "data-eco-no-prefetch": "" }), policy)).toBe(false);
-  });
+describe('shouldPrefetchLink', () => {
+    it('prefetches internal page links', () => {
+        history.replaceState({}, '', '/');
+        const link = createLink('/docs/intro');
+        expect(shouldPrefetchLink(link, policy)).toBe(true);
+    });
+    it('skips static assets and opt-outs', () => {
+        history.replaceState({}, '', '/');
+        expect(shouldPrefetchLink(createLink('/skill.txt'), policy)).toBe(false);
+        expect(shouldPrefetchLink(createLink('/page', { 'data-eco-no-prefetch': '' }), policy)).toBe(false);
+    });
 });
-describe("isHtmlPageResponse", () => {
-  it("accepts html content types", () => {
-    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/html; charset=utf-8" } }))).toBe(
-      true
-    );
-  });
-  it("rejects plain text responses", () => {
-    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/plain" } }))).toBe(false);
-  });
+describe('isHtmlPageResponse', () => {
+    it('accepts html content types', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/html; charset=utf-8' } }))).toBe(true);
+    });
+    it('rejects plain text responses', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/plain' } }))).toBe(false);
+    });
 });
-describe("isHtmlPageResponse", () => {
-  it("accepts html and xhtml content types", () => {
-    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "text/html" } }))).toBe(true);
-    expect(isHtmlPageResponse(new Response("", { headers: { "Content-Type": "application/xhtml+xml" } }))).toBe(
-      true
-    );
-  });
-  it("rejects plain text and markdown responses", () => {
-    expect(isHtmlPageResponse(new Response("text", { headers: { "Content-Type": "text/plain" } }))).toBe(false);
-    expect(isHtmlPageResponse(new Response("# doc", { headers: { "Content-Type": "text/markdown" } }))).toBe(false);
-  });
+describe('isHtmlPageResponse', () => {
+    it('accepts html and xhtml content types', () => {
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'text/html' } }))).toBe(true);
+        expect(isHtmlPageResponse(new Response('', { headers: { 'Content-Type': 'application/xhtml+xml' } }))).toBe(true);
+    });
+    it('rejects plain text and markdown responses', () => {
+        expect(isHtmlPageResponse(new Response('text', { headers: { 'Content-Type': 'text/plain' } }))).toBe(false);
+        expect(isHtmlPageResponse(new Response('# doc', { headers: { 'Content-Type': 'text/markdown' } }))).toBe(false);
+    });
 });