@ecopages/core 0.2.0-beta.30 → 0.2.0-beta.32

package/src/client/navigation-scripts/rerun-queue.js

@@ -1,73 +1,90 @@
-import { RERUN_SRC_ATTR, getRegisteredRerunScript } from "./registry.js";
+/**
+ * Queueing and replay of `data-eco-rerun` scripts after navigation.
+ * @module
+ */
+import { RERUN_SRC_ATTR, getRegisteredRerunScript } from './registry.js';
 let rerunNonce = 0;
-function collectRerunScripts(document2, filter) {
-  return Array.from(document2.querySelectorAll("script[data-eco-rerun]")).filter((script) => filter ? filter(script) : true).map((script) => ({
-    parent: script.closest("body") ? "body" : "head",
-    attributes: Array.from(script.attributes).map((attribute) => [attribute.name, attribute.value]),
-    textContent: script.textContent ?? "",
-    src: script.getAttribute("src"),
-    scriptId: script.getAttribute("data-eco-script-id")
-  }));
+/**
+ * Collects rerun scripts from an incoming document.
+ */
+export function collectRerunScripts(document, filter) {
+    return Array.from(document.querySelectorAll('script[data-eco-rerun]'))
+        .filter((script) => (filter ? filter(script) : true))
+        .map((script) => ({
+        parent: script.closest('body') ? 'body' : 'head',
+        attributes: Array.from(script.attributes).map((attribute) => [attribute.name, attribute.value]),
+        textContent: script.textContent ?? '',
+        src: script.getAttribute('src'),
+        scriptId: script.getAttribute('data-eco-script-id'),
+    }));
 }
-function isExternalModuleRerunScript(script) {
-  if (!script.src) {
-    return false;
-  }
-  return script.attributes.some(([name, value]) => name === "type" && value === "module");
+/**
+ * Returns whether a rerun script is an external ES module that needs cache busting.
+ */
+export function isExternalModuleRerunScript(script) {
+    if (!script.src) {
+        return false;
+    }
+    return script.attributes.some(([name, value]) => name === 'type' && value === 'module');
 }
-function findExistingRerunScript(root, script) {
-  const scripts = Array.from(root.querySelectorAll("script"));
-  if (script.scriptId) {
-    return scripts.find((candidate) => candidate.getAttribute("data-eco-script-id") === script.scriptId) ?? null;
-  }
-  return scripts.find(
-    (candidate) => (candidate.getAttribute(RERUN_SRC_ATTR) ?? candidate.getAttribute("src")) === script.src && (candidate.textContent ?? "") === script.textContent
-  ) ?? null;
+/**
+ * Finds an existing rerun script in `root` by id or by src and inline content.
+ */
+export function findExistingRerunScript(root, script) {
+    const scripts = Array.from(root.querySelectorAll('script'));
+    if (script.scriptId) {
+        return scripts.find((candidate) => candidate.getAttribute('data-eco-script-id') === script.scriptId) ?? null;
+    }
+    return (scripts.find((candidate) => (candidate.getAttribute(RERUN_SRC_ATTR) ?? candidate.getAttribute('src')) === script.src &&
+        (candidate.textContent ?? '') === script.textContent) ?? null);
 }
-function createRerunScriptUrl(src) {
-  const url = new URL(src, document.baseURI);
-  url.searchParams.set("__eco_rerun", String(++rerunNonce));
-  return url.toString();
+/**
+ * Appends a nonce query parameter so module scripts re-execute after navigation.
+ */
+export function createRerunScriptUrl(src) {
+    const url = new URL(src, document.baseURI);
+    url.searchParams.set('__eco_rerun', String(++rerunNonce));
+    return url.toString();
 }
-function flushPendingRerunScripts(scripts) {
-  for (const script of scripts) {
-    const targetParent = script.parent === "body" ? document.body : document.head;
-    const registeredRerun = getRegisteredRerunScript(script.scriptId);
-    const replacement = document.createElement("script");
-    const shouldBustModuleSrc = isExternalModuleRerunScript(script) && !registeredRerun;
-    for (const [name, value] of script.attributes) {
-      if (name === "src" && shouldBustModuleSrc) {
-        replacement.setAttribute(RERUN_SRC_ATTR, value);
-        replacement.setAttribute("src", createRerunScriptUrl(value));
-        continue;
-      }
-      replacement.setAttribute(name, value);
-    }
-    replacement.textContent = script.textContent;
-    const existingScript = findExistingRerunScript(targetParent, script);
-    if (registeredRerun) {
-      const needsScriptElement = isExternalModuleRerunScript(script);
-      if (!existingScript && needsScriptElement) {
+/**
+ * Replays queued rerun scripts after the incoming page body is in place.
+ *
+ * @remarks
+ * Flushed elements keep `data-eco-rerun` so head cleanup does not treat them
+ * as persistable inline scripts on the next navigation.
+ */
+export function flushPendingRerunScripts(scripts) {
+    for (const script of scripts) {
+        const targetParent = script.parent === 'body' ? document.body : document.head;
+        const registeredRerun = getRegisteredRerunScript(script.scriptId);
+        const replacement = document.createElement('script');
+        const shouldBustModuleSrc = isExternalModuleRerunScript(script) && !registeredRerun;
+        for (const [name, value] of script.attributes) {
+            if (name === 'src' && shouldBustModuleSrc) {
+                replacement.setAttribute(RERUN_SRC_ATTR, value);
+                replacement.setAttribute('src', createRerunScriptUrl(value));
+                continue;
+            }
+            replacement.setAttribute(name, value);
+        }
+        replacement.textContent = script.textContent;
+        const existingScript = findExistingRerunScript(targetParent, script);
+        if (registeredRerun) {
+            const needsScriptElement = isExternalModuleRerunScript(script);
+            if (!existingScript && needsScriptElement) {
+                targetParent.appendChild(replacement);
+            }
+            registeredRerun();
+            continue;
+        }
+        if (existingScript) {
+            existingScript.replaceWith(replacement);
+            continue;
+        }
         targetParent.appendChild(replacement);
-      }
-      registeredRerun();
-      continue;
-    }
-    if (existingScript) {
-      existingScript.replaceWith(replacement);
-      continue;
     }
-    targetParent.appendChild(replacement);
-  }
 }
-function resetRerunNonceForTests() {
-  rerunNonce = 0;
+/** @remarks Test-only reset for nonce sequencing. */
+export function resetRerunNonceForTests() {
+    rerunNonce = 0;
 }
-export {
-  collectRerunScripts,
-  createRerunScriptUrl,
-  findExistingRerunScript,
-  flushPendingRerunScripts,
-  isExternalModuleRerunScript,
-  resetRerunNonceForTests
-};

package/src/client/scroll.js

@@ -1,25 +1,33 @@
-function manageWindowScroll(newUrl, previousUrl, options) {
-  const { scrollBehavior, smoothScroll } = options;
-  if (newUrl.hash) {
-    const target = document.getElementById(newUrl.hash.slice(1));
-    target?.scrollIntoView({ behavior: smoothScroll ? "smooth" : "instant" });
-    return;
-  }
-  const behavior = smoothScroll ? "smooth" : "instant";
-  switch (scrollBehavior) {
-    case "preserve":
-      break;
-    case "auto":
-      if (newUrl.pathname !== previousUrl.pathname) {
-        window.scrollTo({ top: 0, left: 0, behavior });
-      }
-      break;
-    case "top":
-    default:
-      window.scrollTo({ top: 0, left: 0, behavior });
-      break;
-  }
+/**
+ * Window scroll behavior during client-side navigations.
+ * @module
+ */
+/**
+ * Updates window scroll position after a navigation commit.
+ *
+ * @remarks
+ * Hash navigations always scroll to the target element and ignore `scrollBehavior`.
+ * Fragment targets are resolved by element id (`#section` → `getElementById('section')`).
+ */
+export function manageWindowScroll(newUrl, previousUrl, options) {
+    const { scrollBehavior, smoothScroll } = options;
+    if (newUrl.hash) {
+        const target = document.getElementById(newUrl.hash.slice(1));
+        target?.scrollIntoView({ behavior: smoothScroll ? 'smooth' : 'instant' });
+        return;
+    }
+    const behavior = smoothScroll ? 'smooth' : 'instant';
+    switch (scrollBehavior) {
+        case 'preserve':
+            break;
+        case 'auto':
+            if (newUrl.pathname !== previousUrl.pathname) {
+                window.scrollTo({ top: 0, left: 0, behavior });
+            }
+            break;
+        case 'top':
+        default:
+            window.scrollTo({ top: 0, left: 0, behavior });
+            break;
+    }
 }
-export {
-  manageWindowScroll
-};

package/src/client/scroll.test.browser.js

@@ -1,37 +1,31 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { manageWindowScroll } from "./scroll.js";
-const options = { scrollBehavior: "top", smoothScroll: false };
-describe("manageWindowScroll", () => {
-  afterEach(() => {
-    history.replaceState({}, "", "/");
-    document.body.replaceChildren();
-    vi.restoreAllMocks();
-  });
-  it("scrolls to top by default", () => {
-    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { manageWindowScroll } from './scroll.js';
+const options = { scrollBehavior: 'top', smoothScroll: false };
+describe('manageWindowScroll', () => {
+    afterEach(() => {
+        history.replaceState({}, '', '/');
+        document.body.replaceChildren();
+        vi.restoreAllMocks();
     });
-    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), options);
-    expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: "instant" });
-  });
-  it("preserves scroll when scrollBehavior is preserve", () => {
-    const scrollTo = vi.spyOn(window, "scrollTo").mockImplementation(() => {
+    it('scrolls to top by default', () => {
+        const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => { });
+        manageWindowScroll(new URL('/next', window.location.origin), new URL('/prev', window.location.origin), options);
+        expect(scrollTo).toHaveBeenCalledWith({ top: 0, left: 0, behavior: 'instant' });
     });
-    manageWindowScroll(new URL("/next", window.location.origin), new URL("/prev", window.location.origin), {
-      ...options,
-      scrollBehavior: "preserve"
+    it('preserves scroll when scrollBehavior is preserve', () => {
+        const scrollTo = vi.spyOn(window, 'scrollTo').mockImplementation(() => { });
+        manageWindowScroll(new URL('/next', window.location.origin), new URL('/prev', window.location.origin), {
+            ...options,
+            scrollBehavior: 'preserve',
+        });
+        expect(scrollTo).not.toHaveBeenCalled();
+    });
+    it('scrolls to hash target by element id', () => {
+        const section = document.createElement('section');
+        section.id = 'section';
+        section.scrollIntoView = vi.fn();
+        document.body.append(section);
+        manageWindowScroll(new URL('/page#section', window.location.origin), new URL('/page', window.location.origin), options);
+        expect(section.scrollIntoView).toHaveBeenCalledWith({ behavior: 'instant' });
     });
-    expect(scrollTo).not.toHaveBeenCalled();
-  });
-  it("scrolls to hash target by element id", () => {
-    const section = document.createElement("section");
-    section.id = "section";
-    section.scrollIntoView = vi.fn();
-    document.body.append(section);
-    manageWindowScroll(
-      new URL("/page#section", window.location.origin),
-      new URL("/page", window.location.origin),
-      options
-    );
-    expect(section.scrollIntoView).toHaveBeenCalledWith({ behavior: "instant" });
-  });
 });

package/src/client/view-transitions.js

@@ -1,63 +1,76 @@
-const VIEW_TRANSITION_ATTR = "data-view-transition";
-const VIEW_TRANSITION_ANIMATE_ATTR = "data-view-transition-animate";
-const VIEW_TRANSITION_DURATION_ATTR = "data-view-transition-duration";
-const DYNAMIC_STYLES_ID = "eco-vt-dynamic-styles";
-function applyViewTransitionNames() {
-  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
-  const morphNames = [];
-  const customDurations = [];
-  elements.forEach((el) => {
-    const name = el.getAttribute(VIEW_TRANSITION_ATTR);
-    if (!name) {
-      return;
+/**
+ * View Transition API helpers for `data-view-transition` markup.
+ * @module
+ */
+const VIEW_TRANSITION_ATTR = 'data-view-transition';
+const VIEW_TRANSITION_ANIMATE_ATTR = 'data-view-transition-animate';
+const VIEW_TRANSITION_DURATION_ATTR = 'data-view-transition-duration';
+const DYNAMIC_STYLES_ID = 'eco-vt-dynamic-styles';
+/**
+ * Assigns `view-transition-name` from `data-view-transition` and injects morph styles.
+ *
+ * @remarks
+ * Elements without `data-view-transition-animate="fade"` get a geometric morph:
+ * the old snapshot is hidden so cross-fade ghosting does not appear.
+ */
+export function applyViewTransitionNames() {
+    const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+    const morphNames = [];
+    const customDurations = [];
+    elements.forEach((el) => {
+        const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+        if (!name) {
+            return;
+        }
+        el.style.viewTransitionName = name;
+        const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+        if (animate !== 'fade') {
+            morphNames.push(name);
+        }
+        const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+        if (duration) {
+            customDurations.push({ name, duration });
+        }
+    });
+    if (morphNames.length > 0 || customDurations.length > 0) {
+        injectDynamicStyles(morphNames, customDurations);
     }
-    el.style.viewTransitionName = name;
-    const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
-    if (animate !== "fade") {
-      morphNames.push(name);
-    }
-    const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
-    if (duration) {
-      customDurations.push({ name, duration });
-    }
-  });
-  if (morphNames.length > 0 || customDurations.length > 0) {
-    injectDynamicStyles(morphNames, customDurations);
-  }
 }
-function clearViewTransitionNames() {
-  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
-  elements.forEach((el) => {
-    el.style.viewTransitionName = "";
-  });
-  const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
-  if (styleEl) {
-    styleEl.textContent = "";
-  }
+/**
+ * Clears inline transition names and dynamic morph styles after a transition ends.
+ */
+export function clearViewTransitionNames() {
+    const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+    elements.forEach((el) => {
+        el.style.viewTransitionName = '';
+    });
+    const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+    if (styleEl) {
+        styleEl.textContent = '';
+    }
 }
 function injectDynamicStyles(morphNames, customDurations) {
-  let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
-  if (!styleEl) {
-    styleEl = document.createElement("style");
-    styleEl.id = DYNAMIC_STYLES_ID;
-    styleEl.setAttribute("data-eco-persist", "");
-    document.head.append(styleEl);
-  }
-  const morphCss = morphNames.map(
-    (name) => `
+    let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+    if (!styleEl) {
+        styleEl = document.createElement('style');
+        styleEl.id = DYNAMIC_STYLES_ID;
+        /**
+         * @remarks
+         * Head morphing must not drop this tag between navigations.
+         */
+        styleEl.setAttribute('data-eco-persist', '');
+        document.head.append(styleEl);
+    }
+    const morphCss = morphNames
+        .map((name) => `
 		::view-transition-old(${name}) { display: none !important; }
 		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
-	`
-  ).join("\n");
-  const durationCss = customDurations.map(
-    ({ name, duration }) => `
+	`)
+        .join('\n');
+    const durationCss = customDurations
+        .map(({ name, duration }) => `
 		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
-	`
-  ).join("\n");
-  styleEl.textContent = `${morphCss}
-${durationCss}`;
+	`)
+        .join('\n');
+    styleEl.textContent = `${morphCss}\n${durationCss}`;
 }
-export {
-  applyViewTransitionNames,
-  clearViewTransitionNames
-};

package/src/config/config-builder.d.ts

@@ -148,6 +148,14 @@ export declare class ConfigBuilder {
      * during static generation (not by this config merge).
      */
     setSitemap(sitemap: SitemapConfig): this;
+    /**
+     * Configures the in-browser development toolbar shown during watch mode.
+     *
+     * @remarks
+     * Requires `package` to point at a browser bootstrap module installed in the app.
+     * Prefer {@link defineDevTool} for config authoring.
+     */
+    setDevToolbar(devToolbar: NonNullable<EcoPagesAppConfig['devToolbar']>): this;
     /**
      * Sets the integration plugins to use.
      * These plugins provide additional functionality to the application.