@real-router/solid 0.5.2 → 0.7.0

package/README.md

@@ -320,18 +320,30 @@ Enable screen reader announcements for route changes:
 
 When enabled, a visually hidden `aria-live` region announces each navigation. Focus moves to the first `<h1>` on the new page. See [Accessibility guide](https://github.com/greydragon888/real-router/wiki/Accessibility) for details.
 
+## Scroll Restoration
+
+Opt-in preservation of scroll position across navigations:
+
+```tsx
+<RouterProvider router={router} scrollRestoration={{ mode: "restore" }}>
+  {/* Your app */}
+</RouterProvider>
+```
+
+Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Options are read once on mount — changing the prop at runtime does not reconfigure the utility (Solid `onMount` is non-reactive). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
+
 ## Documentation
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
 - [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition)
 
 ## Examples
 
-14 runnable examples — each is a standalone Vite app. Run: `cd examples/solid/basic && pnpm dev`
+14 runnable examples — each is a standalone Vite app. Run: `cd examples/web/solid/basic && pnpm dev`
 
-[basic](../../examples/solid/basic) · [nested-routes](../../examples/solid/nested-routes) · [auth-guards](../../examples/solid/auth-guards) · [data-loading](../../examples/solid/data-loading) · [lazy-loading](../../examples/solid/lazy-loading) · [async-guards](../../examples/solid/async-guards) · [hash-routing](../../examples/solid/hash-routing) · [persistent-params](../../examples/solid/persistent-params) · [error-handling](../../examples/solid/error-handling) · [dynamic-routes](../../examples/solid/dynamic-routes) · [store-based-state](../../examples/solid/store-based-state) · [use-link-directive](../../examples/solid/use-link-directive) · [signal-primitives](../../examples/solid/signal-primitives) · [combined](../../examples/solid/combined)
+[basic](../../examples/web/solid/basic) · [nested-routes](../../examples/web/solid/nested-routes) · [auth-guards](../../examples/web/solid/auth-guards) · [data-loading](../../examples/web/solid/data-loading) · [lazy-loading](../../examples/web/solid/lazy-loading) · [async-guards](../../examples/web/solid/async-guards) · [hash-routing](../../examples/web/solid/hash-routing) · [persistent-params](../../examples/web/solid/persistent-params) · [error-handling](../../examples/web/solid/error-handling) · [dynamic-routes](../../examples/web/solid/dynamic-routes) · [store-based-state](../../examples/web/solid/store-based-state) · [use-link-directive](../../examples/web/solid/use-link-directive) · [signal-primitives](../../examples/web/solid/signal-primitives) · [combined](../../examples/web/solid/combined)
 
 ## Related Packages
 

package/dist/cjs/index.d.ts

@@ -17,6 +17,12 @@ interface MatchProps {
     readonly fallback?: JSX.Element;
     readonly children: JSX.Element;
 }
+interface SelfProps {
+    /** Fallback content while children are suspended. */
+    readonly fallback?: JSX.Element;
+    /** Content to render when the active route name equals the parent RouteView's nodeName. */
+    readonly children: JSX.Element;
+}
 interface NotFoundProps {
     readonly children: JSX.Element;
 }
@@ -25,6 +31,10 @@ declare function Match(props: MatchProps): JSX.Element;
 declare namespace Match {
     var displayName: string;
 }
+declare function Self(props: SelfProps): JSX.Element;
+declare namespace Self {
+    var displayName: string;
+}
 declare function NotFound(props: NotFoundProps): JSX.Element;
 declare namespace NotFound {
     var displayName: string;
@@ -36,6 +46,7 @@ declare namespace RouteViewRoot {
 }
 declare const RouteView: typeof RouteViewRoot & {
     Match: typeof Match;
+    Self: typeof Self;
     NotFound: typeof NotFound;
 };
 
@@ -89,9 +100,17 @@ declare function useRouteNodeStore(nodeName: string): RouteState;
 
 declare function useRouterTransition(): Accessor<RouterTransitionSnapshot>;
 
+type ScrollRestorationMode = "restore" | "top" | "manual";
+interface ScrollRestorationOptions {
+    mode?: ScrollRestorationMode | undefined;
+    anchorScrolling?: boolean | undefined;
+    scrollContainer?: (() => HTMLElement | null) | undefined;
+}
+
 interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
+    scrollRestoration?: ScrollRestorationOptions;
 }
 declare function RouterProvider(props: ParentProps<RouteProviderProps>): JSX.Element;
 
@@ -108,4 +127,4 @@ declare function createSignalFromSource<T>(source: RouterSource<T>): Accessor<T>
 declare function createStoreFromSource<T extends object>(source: RouterSource<T>): T;
 
 export { Link, RouteContext, RouteView, RouterContext, RouterErrorBoundary, RouterProvider, createSignalFromSource, createStoreFromSource, link, useNavigator, useRoute, useRouteNode, useRouteNodeStore, useRouteStore, useRouteUtils, useRouter, useRouterTransition };
-export type { LinkDirectiveOptions, LinkProps, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, RouterErrorBoundaryProps };
+export type { LinkDirectiveOptions, LinkProps, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, SelfProps as RouteViewSelfProps, RouterErrorBoundaryProps };

package/dist/cjs/index.js

@@ -11,6 +11,7 @@ var core = require('@real-router/core');
 // Local (non-global) Symbols — Symbol.for() would expose markers to spoofing
 // via the global Symbol registry. See Gotchas section "RouteView Marker Objects".
 const MATCH_MARKER = Symbol("RouteView.Match");
+const SELF_MARKER = Symbol("RouteView.Self");
 const NOT_FOUND_MARKER = Symbol("RouteView.NotFound");
 function Match(props) {
   const result = {
@@ -29,6 +30,19 @@ function Match(props) {
   return result;
 }
 Match.displayName = "RouteView.Match";
+function Self(props) {
+  const result = {
+    $$type: SELF_MARKER,
+    fallback: props.fallback,
+    get children() {
+      return props.children;
+    }
+  };
+
+  // See Match for the marker-pattern rationale.
+  return result;
+}
+Self.displayName = "RouteView.Self";
 function NotFound(props) {
   const result = {
     $$type: NOT_FOUND_MARKER,
@@ -51,6 +65,9 @@ function isSegmentMatch(routeName, fullSegmentName, exact) {
 function isMatchMarker(value) {
   return value != null && typeof value === "object" && "$$type" in value && value.$$type === MATCH_MARKER;
 }
+function isSelfMarker(value) {
+  return value != null && typeof value === "object" && "$$type" in value && value.$$type === SELF_MARKER;
+}
 function isNotFoundMarker(value) {
   return value != null && typeof value === "object" && "$$type" in value && value.$$type === NOT_FOUND_MARKER;
 }
@@ -64,11 +81,48 @@ function collectElements(children, result) {
     }
     return;
   }
-  if (isMatchMarker(children) || isNotFoundMarker(children)) {
+  if (isMatchMarker(children) || isSelfMarker(children) || isNotFoundMarker(children)) {
     result.push(children);
   }
 }
+
+// child.children is a getter — read it INSIDE the JSX expression so Solid
+// creates a reactive dependency. Pulling it into a variable freezes the
+// value at template-build time and breaks Suspense fallback transitions
+// (lazy() resolution).
+function renderMatch(child) {
+  return child.fallback === undefined ? child.children : web.createComponent(solidJs.Suspense, {
+    get fallback() {
+      return child.fallback;
+    },
+    get children() {
+      return child.children;
+    }
+  });
+}
+function renderSelf(self) {
+  return self.fallback === undefined ? self.children : web.createComponent(solidJs.Suspense, {
+    get fallback() {
+      return self.fallback;
+    },
+    get children() {
+      return self.children;
+    }
+  });
+}
+function processMatchChild(child, routeName, nodeName) {
+  const {
+    segment,
+    exact
+  } = child;
+  const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+  if (!isSegmentMatch(routeName, fullSegmentName, exact)) {
+    return null;
+  }
+  return renderMatch(child);
+}
 function buildRenderList(elements, routeName, nodeName) {
+  let selfMarker = null;
   let notFoundChildren = null;
   let activeMatchFound = false;
   const rendered = [];
@@ -77,28 +131,25 @@ function buildRenderList(elements, routeName, nodeName) {
       notFoundChildren = child.children;
       continue;
     }
-    if (activeMatchFound) {
+    if (isSelfMarker(child)) {
+      selfMarker ??= child;
       continue;
     }
-    const {
-      segment,
-      exact,
-      fallback
-    } = child;
-    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-    if (!isSegmentMatch(routeName, fullSegmentName, exact)) {
+    if (activeMatchFound) {
       continue;
     }
-    activeMatchFound = true;
-    rendered.push(fallback === undefined ? child.children : web.createComponent(solidJs.Suspense, {
-      fallback: fallback,
-      get children() {
-        return child.children;
-      }
-    }));
+    const matchRendered = processMatchChild(child, routeName, nodeName);
+    if (matchRendered !== null) {
+      activeMatchFound = true;
+      rendered.push(matchRendered);
+    }
   }
-  if (!activeMatchFound && routeName === core.UNKNOWN_ROUTE && notFoundChildren !== null) {
-    rendered.push(notFoundChildren);
+  if (!activeMatchFound) {
+    if (selfMarker !== null && routeName === nodeName) {
+      rendered.push(renderSelf(selfMarker));
+    } else if (routeName === core.UNKNOWN_ROUTE && notFoundChildren !== null) {
+      rendered.push(notFoundChildren);
+    }
   }
   return rendered;
 }
@@ -157,6 +208,7 @@ function RouteViewRoot(props) {
 RouteViewRoot.displayName = "RouteView";
 const RouteView = Object.assign(RouteViewRoot, {
   Match,
+  Self,
   NotFound
 });
 
@@ -284,6 +336,163 @@ function manageFocus(h1) {
   });
 }
 
+const STORAGE_KEY = "real-router:scroll";
+const NOOP_INSTANCE = Object.freeze({
+  destroy: () => {
+    /* no-op */
+  }
+});
+function createScrollRestoration(router, options) {
+  if (typeof globalThis.window === "undefined") {
+    return NOOP_INSTANCE;
+  }
+  const mode = options?.mode ?? "restore";
+
+  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — leave the browser's native
+  // auto-restore intact for the app to override if it wants to.
+  if (mode === "manual") {
+    return NOOP_INSTANCE;
+  }
+  const anchorEnabled = options?.anchorScrolling ?? true;
+  const getContainer = options?.scrollContainer;
+  const prevScrollRestoration = history.scrollRestoration;
+  try {
+    history.scrollRestoration = "manual";
+  } catch {
+    // Ignore — some embedded contexts may reject the assignment.
+  }
+
+  // Resolve the container lazily on every event so containers mounted AFTER
+  // the provider still get correct scroll handling. Falls back to window when
+  // the getter is absent or returns null (pre-mount).
+  const readPos = () => {
+    const element = getContainer?.();
+    return element ? element.scrollTop : globalThis.scrollY;
+  };
+  const writePos = top => {
+    const element = getContainer?.();
+    if (element) {
+      element.scrollTop = top;
+    } else {
+      globalThis.scrollTo(0, top);
+    }
+  };
+  const scrollToHashOrTop = () => {
+    const hash = globalThis.location.hash;
+    if (anchorEnabled && hash.length > 1) {
+      // location.hash is percent-encoded; ids in the DOM are the raw string.
+      // Decode for the match. Fall back to the raw slice if the hash contains
+      // a malformed escape sequence (decodeURIComponent throws on those).
+      let id;
+      try {
+        id = decodeURIComponent(hash.slice(1));
+      } catch {
+        id = hash.slice(1);
+      }
+
+      // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
+      const element = document.getElementById(id);
+      if (element) {
+        element.scrollIntoView();
+        return;
+      }
+    }
+    writePos(0);
+  };
+  let destroyed = false;
+  const unsubscribe = router.subscribe(({
+    route,
+    previousRoute
+  }) => {
+    const nav = route.context.navigation;
+
+    // Browsers dispatch reload as the initial navigation after refresh, so
+    // previousRoute is undefined and capture is naturally skipped. The
+    // pre-refresh position was already persisted via pagehide.
+    if (previousRoute) {
+      putPos(keyOf(previousRoute), readPos());
+    }
+
+    // Single rAF so DOM is committed before we read anchors / write scroll.
+    // Guard against destroy() racing with the callback.
+    requestAnimationFrame(() => {
+      if (destroyed) {
+        return;
+      }
+      if (mode === "top" || !nav) {
+        scrollToHashOrTop();
+        return;
+      }
+      if (nav.navigationType === "replace") {
+        return;
+      }
+      if (nav.direction === "back" || nav.navigationType === "traverse" || nav.navigationType === "reload") {
+        writePos(loadStore()[keyOf(route)] ?? 0);
+        return;
+      }
+      scrollToHashOrTop();
+    });
+  });
+  const onPageHide = () => {
+    const current = router.getState();
+    if (current) {
+      putPos(keyOf(current), readPos());
+    }
+  };
+  globalThis.addEventListener("pagehide", onPageHide);
+  return {
+    destroy: () => {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      unsubscribe();
+      globalThis.removeEventListener("pagehide", onPageHide);
+      try {
+        history.scrollRestoration = prevScrollRestoration;
+      } catch {
+        // Ignore.
+      }
+    }
+  };
+}
+function keyOf(state) {
+  return `${state.name}:${canonicalJson(state.params)}`;
+}
+function loadStore() {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+function putPos(key, pos) {
+  try {
+    const store = loadStore();
+    store[key] = pos;
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
+  } catch {
+    // Ignore quota / security errors.
+  }
+}
+function canonicalJson(value) {
+  return JSON.stringify(value, canonicalReplacer);
+}
+function canonicalReplacer(_key, val) {
+  if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+    const sorted = {};
+    // eslint-disable-next-line unicorn/no-array-sort -- ng-packagr uses pre-ES2023 lib; toSorted unavailable
+    const keys = Object.keys(val).sort((left, right) => left.localeCompare(right));
+    for (const key of keys) {
+      sorted[key] = val[key];
+    }
+    return sorted;
+  }
+  return val;
+}
+
 function shouldNavigate(evt) {
   return evt.button === 0 && !evt.metaKey && !evt.altKey && !evt.ctrlKey && !evt.shiftKey;
 }
@@ -514,6 +723,15 @@ function RouterProvider(props) {
       announcer.destroy();
     });
   });
+  solidJs.onMount(() => {
+    if (!props.scrollRestoration) {
+      return;
+    }
+    const sr = createScrollRestoration(props.router, props.scrollRestoration);
+    solidJs.onCleanup(() => {
+      sr.destroy();
+    });
+  });
   const navigator = core.getNavigator(props.router);
   const routeSource = sources.createRouteSource(props.router);
   const routeSignal = createSignalFromSource(routeSource);

package/dist/esm/index.d.mts

@@ -17,6 +17,12 @@ interface MatchProps {
     readonly fallback?: JSX.Element;
     readonly children: JSX.Element;
 }
+interface SelfProps {
+    /** Fallback content while children are suspended. */
+    readonly fallback?: JSX.Element;
+    /** Content to render when the active route name equals the parent RouteView's nodeName. */
+    readonly children: JSX.Element;
+}
 interface NotFoundProps {
     readonly children: JSX.Element;
 }
@@ -25,6 +31,10 @@ declare function Match(props: MatchProps): JSX.Element;
 declare namespace Match {
     var displayName: string;
 }
+declare function Self(props: SelfProps): JSX.Element;
+declare namespace Self {
+    var displayName: string;
+}
 declare function NotFound(props: NotFoundProps): JSX.Element;
 declare namespace NotFound {
     var displayName: string;
@@ -36,6 +46,7 @@ declare namespace RouteViewRoot {
 }
 declare const RouteView: typeof RouteViewRoot & {
     Match: typeof Match;
+    Self: typeof Self;
     NotFound: typeof NotFound;
 };
 
@@ -89,9 +100,17 @@ declare function useRouteNodeStore(nodeName: string): RouteState;
 
 declare function useRouterTransition(): Accessor<RouterTransitionSnapshot>;
 
+type ScrollRestorationMode = "restore" | "top" | "manual";
+interface ScrollRestorationOptions {
+    mode?: ScrollRestorationMode | undefined;
+    anchorScrolling?: boolean | undefined;
+    scrollContainer?: (() => HTMLElement | null) | undefined;
+}
+
 interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
+    scrollRestoration?: ScrollRestorationOptions;
 }
 declare function RouterProvider(props: ParentProps<RouteProviderProps>): JSX.Element;
 
@@ -108,4 +127,4 @@ declare function createSignalFromSource<T>(source: RouterSource<T>): Accessor<T>
 declare function createStoreFromSource<T extends object>(source: RouterSource<T>): T;
 
 export { Link, RouteContext, RouteView, RouterContext, RouterErrorBoundary, RouterProvider, createSignalFromSource, createStoreFromSource, link, useNavigator, useRoute, useRouteNode, useRouteNodeStore, useRouteStore, useRouteUtils, useRouter, useRouterTransition };
-export type { LinkDirectiveOptions, LinkProps, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, RouterErrorBoundaryProps };
+export type { LinkDirectiveOptions, LinkProps, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, SelfProps as RouteViewSelfProps, RouterErrorBoundaryProps };