evolit 0.1.0-alpha.22 → 0.1.0-alpha.24

package/README.md

@@ -105,8 +105,10 @@ export default function CollectionControls() {
 
 The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, createHref }`:
 
-- `push(target)` adds a browser-history entry.
-- `replace(target)` updates the current entry, useful for visual-only query state.
+- `push(target, { scroll: false })` adds a browser-history entry. Pass
+  `scroll: false` to keep the current viewport position.
+- `replace(target, { scroll: false })` updates the current entry, useful for
+  visual-only query state. It accepts the same scroll option.
 - `refresh()` bypasses the client delta cache for the current URL.
 - `createHref(pathname, searchParams)` creates a relative internal URL. It accepts standard
   `URLSearchParams`, preserving repeated keys such as `facet=brand&facet=material`.
@@ -115,6 +117,20 @@ The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, crea
 share with server-evaluated route code. `useNavigation()` itself is browser-only and must only run
 from a connected client component.
 
+Client components can also read the active route state with browser-only hooks:
+
+```jsx
+import { useParams, useSearchParams } from "evolit/navigation";
+
+const { slug = [] } = useParams();
+const searchParams = useSearchParams();
+const selectedFacets = searchParams.getAll("facet");
+```
+
+Both hooks update after client navigation. `useParams()` returns a read-only snapshot; the
+`URLSearchParams` from `useSearchParams()` is a local snapshot, so build a new href and navigate to
+it to update the URL.
+
 ### Progressive links and forms
 
 Links work without JavaScript. With JavaScript, Evolit intercepts ordinary same-origin left-clicks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

package/src/navigation-client.js

@@ -18,6 +18,20 @@ function readRoute(documentRef) {
   try { return source ? JSON.parse(source) : null; } catch { return null; }
 }
 
+function readRouteParams(documentRef) {
+  const params = readRoute(documentRef)?.params;
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return Object.freeze({});
+  }
+
+  return Object.freeze(Object.fromEntries(
+    Object.entries(params).map(([key, value]) => [
+      key,
+      Array.isArray(value) ? Object.freeze([...value]) : value,
+    ]),
+  ));
+}
+
 function findMarkers(root, segmentId, matches = []) {
   const documentRef = root.ownerDocument ?? root;
   const walker = documentRef.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
@@ -309,14 +323,16 @@ function findHashTarget(documentRef, href) {
   }
 }
 
-function restoreScrollAndFocus(windowRef, href, position) {
-  const target = findHashTarget(windowRef.document, href);
-  if (target?.scrollIntoView) {
-    target.scrollIntoView();
-  } else if (position) {
-    windowRef.scrollTo?.(position.x, position.y);
-  } else {
-    windowRef.scrollTo?.(0, 0);
+function restoreScrollAndFocus(windowRef, href, position, preserveScroll = false) {
+  if (!preserveScroll) {
+    const target = findHashTarget(windowRef.document, href);
+    if (target?.scrollIntoView) {
+      target.scrollIntoView();
+    } else if (position) {
+      windowRef.scrollTo?.(position.x, position.y);
+    } else {
+      windowRef.scrollTo?.(0, 0);
+    }
   }
 
   const main = windowRef.document.querySelector?.("main");
@@ -410,6 +426,9 @@ export function createBrowserNavigation(options = {}) {
   async function navigate(target, mode = "push", fromPopState = false, options = {}) {
     const href = toHref(target, windowRef.location);
     const cacheKey = toCacheKey(href);
+    const scrollPosition = options.scroll === false
+      ? currentScrollPosition(windowRef)
+      : options.scrollPosition;
     controller?.abort();
     const navigationController = new AbortController();
     controller = navigationController;
@@ -475,14 +494,19 @@ export function createBrowserNavigation(options = {}) {
           {
             ...(mode === "replace" ? windowRef.history.state : {}),
             __evolitNavigationEntry: entryId,
-            __evolitScroll: { x: 0, y: 0 },
+            __evolitScroll: scrollPosition ?? { x: 0, y: 0 },
           },
           "",
           canonicalHref,
         );
       }
       cacheDelta(entryId, toCacheKey(canonicalHref), delta);
-      restoreScrollAndFocus(windowRef, canonicalHref, options.scrollPosition);
+      restoreScrollAndFocus(
+        windowRef,
+        canonicalHref,
+        scrollPosition,
+        options.scroll === false,
+      );
       state = { status: "idle", url: canonicalHref, pendingUrl: null, error: null };
       emit();
       return delta;
@@ -519,9 +543,9 @@ export function createBrowserNavigation(options = {}) {
   return {
     getState: () => state,
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
-    push: (target) => navigate(target, "push"),
-    replace: (target) => navigate(target, "replace"),
-    refresh: () => navigate(windowRef.location.href, "replace", false, { force: true }),
+    push: (target, options) => navigate(target, "push", false, options),
+    replace: (target, options) => navigate(target, "replace", false, options),
+    refresh: (options) => navigate(windowRef.location.href, "replace", false, { ...options, force: true }),
     createHref,
   };
 }
@@ -544,3 +568,22 @@ export function useNavigation() {
     createHref: navigation.createHref,
   };
 }
+
+/**
+ * Returns the dynamic route parameters for the active client route.
+ * The returned object is a read-only snapshot and updates after navigation.
+ */
+export function useParams() {
+  useNavigation();
+  return readRouteParams(globalThis.document);
+}
+
+/**
+ * Returns a URLSearchParams snapshot for the active client route.
+ * Mutating it is local only; use createHref() and navigation.push()/replace()
+ * to update the URL.
+ */
+export function useSearchParams() {
+  const navigation = useNavigation();
+  return new URL(navigation.url).searchParams;
+}

package/src/navigation-server.js

@@ -1,3 +1,5 @@
 export function getNavigation() { throw new Error("Navigation is only available in a browser context."); }
 export { createHref } from "./navigation-url.js";
 export function useNavigation() { throw new Error("useNavigation() is only available in a browser component."); }
+export function useParams() { throw new Error("useParams() is only available in a browser component."); }
+export function useSearchParams() { throw new Error("useSearchParams() is only available in a browser component."); }

package/src/route-segments.js

@@ -73,6 +73,9 @@ export function createRouteSegmentPayload(routeResult) {
     version: 1,
     url: routeResult.cacheKey ?? routeResult.route?.pathname ?? null,
     pathname: routeResult.cacheKey?.split("?")[0] ?? routeResult.route?.pathname ?? null,
+    params: routeResult.params && typeof routeResult.params === "object"
+      ? routeResult.params
+      : {},
     cachePolicy: routeResult.cachePolicy
       ? {
         mode: routeResult.cachePolicy.mode,