@matthesketh/utopia-router 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -31,9 +31,14 @@ __export(index_exports, {
   destroy: () => destroy,
   filePathToRoute: () => filePathToRoute,
   forward: () => forward,
+  getQueryParam: () => getQueryParam,
+  getRouteParam: () => getRouteParam,
   isNavigating: () => isNavigating,
   matchRoute: () => matchRoute,
-  navigate: () => navigate
+  navigate: () => navigate,
+  queryParams: () => queryParams,
+  setQueryParam: () => setQueryParam,
+  setQueryParams: () => setQueryParams
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -401,33 +406,41 @@ function createRouterView() {
   container.setAttribute("data-utopia-router-view", "");
   let currentCleanup = null;
   let currentMatch = null;
+  let loadId = 0;
   (0, import_utopia_core2.effect)(() => {
     const match = currentRoute();
     if (match === currentMatch) {
       return;
     }
     currentMatch = match;
-    if (currentCleanup) {
-      currentCleanup();
-      currentCleanup = null;
-    }
-    while (container.firstChild) {
-      container.removeChild(container.firstChild);
-    }
+    const thisLoadId = ++loadId;
     if (!match) {
+      if (currentCleanup) {
+        currentCleanup();
+        currentCleanup = null;
+      }
+      clearContainer(container);
       const notFound = document.createElement("div");
       notFound.setAttribute("data-utopia-not-found", "");
       notFound.textContent = "Page not found";
       container.appendChild(notFound);
       return;
     }
-    loadRouteComponent(match, container).then((cleanupFn) => {
-      currentCleanup = cleanupFn;
+    loadRouteComponent(match).then((result) => {
+      if (thisLoadId !== loadId) return;
+      if (!result) return;
+      if (currentCleanup) {
+        currentCleanup();
+        currentCleanup = null;
+      }
+      clearContainer(container);
+      container.appendChild(result.node);
+      currentCleanup = result.cleanup;
     });
   });
   return container;
 }
-async function loadRouteComponent(match, container) {
+async function loadRouteComponent(match) {
   try {
     const promises = [match.route.component()];
     if (match.route.layout) {
@@ -441,26 +454,26 @@ async function loadRouteComponent(match, container) {
     }
     const PageComponent = pageModule.default ?? pageModule;
     const LayoutComponent = layoutModule ? layoutModule.default ?? layoutModule : null;
-    while (container.firstChild) {
-      container.removeChild(container.firstChild);
-    }
     const pageNode = renderComponent(PageComponent, {
       params: match.params,
       url: match.url
     });
+    let node;
     if (LayoutComponent) {
-      const layoutNode = renderComponent(LayoutComponent, {
+      node = renderComponent(LayoutComponent, {
         params: match.params,
         url: match.url,
         children: pageNode
       });
-      container.appendChild(layoutNode);
     } else {
-      container.appendChild(pageNode);
+      node = pageNode;
     }
-    return () => {
-      while (container.firstChild) {
-        container.removeChild(container.firstChild);
+    return {
+      node,
+      cleanup: () => {
+        if (node.parentNode) {
+          node.parentNode.removeChild(node);
+        }
       }
     };
   } catch (err) {
@@ -468,26 +481,33 @@ async function loadRouteComponent(match, container) {
       try {
         const errorModule = await match.route.error();
         const ErrorComponent = errorModule.default ?? errorModule;
-        while (container.firstChild) {
-          container.removeChild(container.firstChild);
-        }
         const errorNode = renderComponent(ErrorComponent, {
           error: err,
           params: match.params,
           url: match.url
         });
-        container.appendChild(errorNode);
+        return {
+          node: errorNode,
+          cleanup: () => {
+            if (errorNode.parentNode) {
+              errorNode.parentNode.removeChild(errorNode);
+            }
+          }
+        };
       } catch {
-        renderFallbackError(container, err);
+        return {
+          node: createFallbackErrorNode(err),
+          cleanup: () => {
+          }
+        };
       }
     } else {
-      renderFallbackError(container, err);
+      return {
+        node: createFallbackErrorNode(err),
+        cleanup: () => {
+        }
+      };
     }
-    return () => {
-      while (container.firstChild) {
-        container.removeChild(container.firstChild);
-      }
-    };
   }
 }
 function renderComponent(component, props) {
@@ -510,10 +530,7 @@ function renderComponent(component, props) {
   div.textContent = "[Component render error]";
   return div;
 }
-function renderFallbackError(container, error) {
-  while (container.firstChild) {
-    container.removeChild(container.firstChild);
-  }
+function createFallbackErrorNode(error) {
   const errorDiv = document.createElement("div");
   errorDiv.setAttribute("data-utopia-error", "");
   errorDiv.style.cssText = "padding:2rem;color:#dc2626;font-family:monospace;";
@@ -523,7 +540,7 @@ function renderFallbackError(container, error) {
     error instanceof Error ? error.message : String(error)
   )}</pre>
   `;
-  container.appendChild(errorDiv);
+  return errorDiv;
 }
 function createLink(props) {
   const anchor = document.createElement("a");
@@ -550,9 +567,62 @@ function createLink(props) {
   }
   return anchor;
 }
+function clearContainer(container) {
+  while (container.firstChild) {
+    container.removeChild(container.firstChild);
+  }
+}
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
 }
+
+// src/query.ts
+var import_utopia_core3 = require("@matthesketh/utopia-core");
+var queryParams = (0, import_utopia_core3.computed)(() => {
+  const match = currentRoute();
+  if (!match) return {};
+  const result = {};
+  match.url.searchParams.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+});
+function getQueryParam(name) {
+  return (0, import_utopia_core3.computed)(() => {
+    const match = currentRoute();
+    if (!match) return null;
+    return match.url.searchParams.get(name);
+  });
+}
+function setQueryParam(name, value) {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (value === null) {
+    url.searchParams.delete(name);
+  } else {
+    url.searchParams.set(name, value);
+  }
+  navigate(url.pathname + url.search + url.hash, { replace: true });
+}
+function setQueryParams(params) {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null) {
+      url.searchParams.delete(key);
+    } else {
+      url.searchParams.set(key, value);
+    }
+  }
+  navigate(url.pathname + url.search + url.hash, { replace: true });
+}
+function getRouteParam(name) {
+  return (0, import_utopia_core3.computed)(() => {
+    const match = currentRoute();
+    if (!match) return null;
+    return match.params[name] ?? null;
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   back,
@@ -566,7 +636,12 @@ function escapeHtml(str) {
   destroy,
   filePathToRoute,
   forward,
+  getQueryParam,
+  getRouteParam,
   isNavigating,
   matchRoute,
-  navigate
+  navigate,
+  queryParams,
+  setQueryParam,
+  setQueryParams
 });

package/dist/index.d.cts

@@ -171,8 +171,8 @@ declare function destroy(): void;
  * Creates a DOM node that renders the current route's component.
  *
  * When the route changes:
- * 1. The old component is unmounted (removed from DOM)
- * 2. The new component is lazily loaded
+ * 1. The new component is lazily loaded (old content stays visible)
+ * 2. Once loaded, the old component is swapped out atomically
  * 3. If the route has a layout, the page is wrapped in the layout
  * 4. If loading fails and an error component exists, it is shown instead
  *
@@ -214,4 +214,29 @@ declare function createLink(props: {
     activeClass?: string;
 }): HTMLAnchorElement;
 
-export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, isNavigating, matchRoute, navigate };
+/**
+ * Reactive computed signal returning all current query parameters as a plain object.
+ */
+declare const queryParams: _matthesketh_utopia_core.ReadonlySignal<Record<string, string>>;
+/**
+ * Returns a computed signal for a specific query parameter.
+ * Returns null if the parameter is not present.
+ */
+declare function getQueryParam(name: string): _matthesketh_utopia_core.ReadonlySignal<string | null>;
+/**
+ * Update a single query parameter and navigate (replace mode).
+ * Pass null to remove the parameter.
+ */
+declare function setQueryParam(name: string, value: string | null): void;
+/**
+ * Update multiple query parameters in a single navigation.
+ * Pass null for a value to remove that parameter.
+ */
+declare function setQueryParams(params: Record<string, string | null>): void;
+/**
+ * Returns a computed signal for a specific route path parameter.
+ * Returns null if the parameter is not present.
+ */
+declare function getRouteParam(name: string): _matthesketh_utopia_core.ReadonlySignal<string | null>;
+
+export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, getQueryParam, getRouteParam, isNavigating, matchRoute, navigate, queryParams, setQueryParam, setQueryParams };

package/dist/index.d.ts

@@ -171,8 +171,8 @@ declare function destroy(): void;
  * Creates a DOM node that renders the current route's component.
  *
  * When the route changes:
- * 1. The old component is unmounted (removed from DOM)
- * 2. The new component is lazily loaded
+ * 1. The new component is lazily loaded (old content stays visible)
+ * 2. Once loaded, the old component is swapped out atomically
  * 3. If the route has a layout, the page is wrapped in the layout
  * 4. If loading fails and an error component exists, it is shown instead
  *
@@ -214,4 +214,29 @@ declare function createLink(props: {
     activeClass?: string;
 }): HTMLAnchorElement;
 
-export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, isNavigating, matchRoute, navigate };
+/**
+ * Reactive computed signal returning all current query parameters as a plain object.
+ */
+declare const queryParams: _matthesketh_utopia_core.ReadonlySignal<Record<string, string>>;
+/**
+ * Returns a computed signal for a specific query parameter.
+ * Returns null if the parameter is not present.
+ */
+declare function getQueryParam(name: string): _matthesketh_utopia_core.ReadonlySignal<string | null>;
+/**
+ * Update a single query parameter and navigate (replace mode).
+ * Pass null to remove the parameter.
+ */
+declare function setQueryParam(name: string, value: string | null): void;
+/**
+ * Update multiple query parameters in a single navigation.
+ * Pass null for a value to remove that parameter.
+ */
+declare function setQueryParams(params: Record<string, string | null>): void;
+/**
+ * Returns a computed signal for a specific route path parameter.
+ * Returns null if the parameter is not present.
+ */
+declare function getRouteParam(name: string): _matthesketh_utopia_core.ReadonlySignal<string | null>;
+
+export { type BeforeNavigateHook, type Route, type RouteMatch, type RouterState, back, beforeNavigate, buildRouteTable, compilePattern, createLink, createRouter, createRouterView, currentRoute, destroy, filePathToRoute, forward, getQueryParam, getRouteParam, isNavigating, matchRoute, navigate, queryParams, setQueryParam, setQueryParams };

package/dist/index.js

@@ -362,33 +362,41 @@ function createRouterView() {
   container.setAttribute("data-utopia-router-view", "");
   let currentCleanup = null;
   let currentMatch = null;
+  let loadId = 0;
   effect(() => {
     const match = currentRoute();
     if (match === currentMatch) {
       return;
     }
     currentMatch = match;
-    if (currentCleanup) {
-      currentCleanup();
-      currentCleanup = null;
-    }
-    while (container.firstChild) {
-      container.removeChild(container.firstChild);
-    }
+    const thisLoadId = ++loadId;
     if (!match) {
+      if (currentCleanup) {
+        currentCleanup();
+        currentCleanup = null;
+      }
+      clearContainer(container);
       const notFound = document.createElement("div");
       notFound.setAttribute("data-utopia-not-found", "");
       notFound.textContent = "Page not found";
       container.appendChild(notFound);
       return;
     }
-    loadRouteComponent(match, container).then((cleanupFn) => {
-      currentCleanup = cleanupFn;
+    loadRouteComponent(match).then((result) => {
+      if (thisLoadId !== loadId) return;
+      if (!result) return;
+      if (currentCleanup) {
+        currentCleanup();
+        currentCleanup = null;
+      }
+      clearContainer(container);
+      container.appendChild(result.node);
+      currentCleanup = result.cleanup;
     });
   });
   return container;
 }
-async function loadRouteComponent(match, container) {
+async function loadRouteComponent(match) {
   try {
     const promises = [match.route.component()];
     if (match.route.layout) {
@@ -402,26 +410,26 @@ async function loadRouteComponent(match, container) {
     }
     const PageComponent = pageModule.default ?? pageModule;
     const LayoutComponent = layoutModule ? layoutModule.default ?? layoutModule : null;
-    while (container.firstChild) {
-      container.removeChild(container.firstChild);
-    }
     const pageNode = renderComponent(PageComponent, {
       params: match.params,
       url: match.url
     });
+    let node;
     if (LayoutComponent) {
-      const layoutNode = renderComponent(LayoutComponent, {
+      node = renderComponent(LayoutComponent, {
         params: match.params,
         url: match.url,
         children: pageNode
       });
-      container.appendChild(layoutNode);
     } else {
-      container.appendChild(pageNode);
+      node = pageNode;
     }
-    return () => {
-      while (container.firstChild) {
-        container.removeChild(container.firstChild);
+    return {
+      node,
+      cleanup: () => {
+        if (node.parentNode) {
+          node.parentNode.removeChild(node);
+        }
       }
     };
   } catch (err) {
@@ -429,26 +437,33 @@ async function loadRouteComponent(match, container) {
       try {
         const errorModule = await match.route.error();
         const ErrorComponent = errorModule.default ?? errorModule;
-        while (container.firstChild) {
-          container.removeChild(container.firstChild);
-        }
         const errorNode = renderComponent(ErrorComponent, {
           error: err,
           params: match.params,
           url: match.url
         });
-        container.appendChild(errorNode);
+        return {
+          node: errorNode,
+          cleanup: () => {
+            if (errorNode.parentNode) {
+              errorNode.parentNode.removeChild(errorNode);
+            }
+          }
+        };
       } catch {
-        renderFallbackError(container, err);
+        return {
+          node: createFallbackErrorNode(err),
+          cleanup: () => {
+          }
+        };
       }
     } else {
-      renderFallbackError(container, err);
+      return {
+        node: createFallbackErrorNode(err),
+        cleanup: () => {
+        }
+      };
     }
-    return () => {
-      while (container.firstChild) {
-        container.removeChild(container.firstChild);
-      }
-    };
   }
 }
 function renderComponent(component, props) {
@@ -471,10 +486,7 @@ function renderComponent(component, props) {
   div.textContent = "[Component render error]";
   return div;
 }
-function renderFallbackError(container, error) {
-  while (container.firstChild) {
-    container.removeChild(container.firstChild);
-  }
+function createFallbackErrorNode(error) {
   const errorDiv = document.createElement("div");
   errorDiv.setAttribute("data-utopia-error", "");
   errorDiv.style.cssText = "padding:2rem;color:#dc2626;font-family:monospace;";
@@ -484,7 +496,7 @@ function renderFallbackError(container, error) {
     error instanceof Error ? error.message : String(error)
   )}</pre>
   `;
-  container.appendChild(errorDiv);
+  return errorDiv;
 }
 function createLink(props) {
   const anchor = document.createElement("a");
@@ -511,9 +523,62 @@ function createLink(props) {
   }
   return anchor;
 }
+function clearContainer(container) {
+  while (container.firstChild) {
+    container.removeChild(container.firstChild);
+  }
+}
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#x27;");
 }
+
+// src/query.ts
+import { computed } from "@matthesketh/utopia-core";
+var queryParams = computed(() => {
+  const match = currentRoute();
+  if (!match) return {};
+  const result = {};
+  match.url.searchParams.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+});
+function getQueryParam(name) {
+  return computed(() => {
+    const match = currentRoute();
+    if (!match) return null;
+    return match.url.searchParams.get(name);
+  });
+}
+function setQueryParam(name, value) {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  if (value === null) {
+    url.searchParams.delete(name);
+  } else {
+    url.searchParams.set(name, value);
+  }
+  navigate(url.pathname + url.search + url.hash, { replace: true });
+}
+function setQueryParams(params) {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null) {
+      url.searchParams.delete(key);
+    } else {
+      url.searchParams.set(key, value);
+    }
+  }
+  navigate(url.pathname + url.search + url.hash, { replace: true });
+}
+function getRouteParam(name) {
+  return computed(() => {
+    const match = currentRoute();
+    if (!match) return null;
+    return match.params[name] ?? null;
+  });
+}
 export {
   back,
   beforeNavigate,
@@ -526,7 +591,12 @@ export {
   destroy,
   filePathToRoute,
   forward,
+  getQueryParam,
+  getRouteParam,
   isNavigating,
   matchRoute,
-  navigate
+  navigate,
+  queryParams,
+  setQueryParam,
+  setQueryParams
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matthesketh/utopia-router",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "File-based routing for UtopiaJS",
   "type": "module",
   "license": "MIT",
@@ -40,8 +40,8 @@
     "dist"
   ],
   "dependencies": {
-    "@matthesketh/utopia-core": "0.3.0",
-    "@matthesketh/utopia-runtime": "0.3.0"
+    "@matthesketh/utopia-core": "0.4.0",
+    "@matthesketh/utopia-runtime": "0.4.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",