@solidjs/router 1.0.0-next.9 → 2.0.0-next.12

package/dist/routers/factory.jsx

@@ -8,6 +8,7 @@ import { createBranches, createRouterContext, getRouteMatches, registerFlightRou
 import { mockBase } from "../utils.js";
 import { Root, Routes } from "./components.jsx";
 import { browserHistory } from "./history.js";
+import { createScrollRestoration, withScrollRestoration } from "./scrollRestoration.js";
 /**
  * Identity helper that preserves literal types when the route tree is
  * declared as a separate variable. `createRouter` infers literally from
@@ -18,6 +19,9 @@ import { browserHistory } from "./history.js";
 export function defineRoutes(routes) {
     return routes;
 }
+export function defineRoute(route) {
+    return route;
+}
 /** Wraps a history adapter in the integration signal the router core consumes. Must run under a reactive owner. */
 function createIntegration(history) {
     let ignore = false;
@@ -45,22 +49,22 @@ function createIntegration(history) {
 }
 /**
  * Server default: a static view of the request URL — no signal machinery, a
- * server render never navigates. Without a request event (SSG scripts,
- * server-side tests) the configured history adapter provides the location,
- * so e.g. `memoryHistory("/page")` works isomorphically.
+ * server render never navigates. The request event (when the harness scopes
+ * one) wins; the provider's `url` prop is the fallback for renders outside a
+ * request scope (SSG scripts, server-side tests, runtimes without
+ * `node:async_hooks`). History adapters are a client navigation concern and
+ * play no part in locating a server render.
  */
-function staticIntegration(history) {
+function staticIntegration(url, utils) {
     const e = getRequestEvent();
+    const source = e ? e.request.url : url;
     let value = "";
-    if (e) {
-        const url = new URL(e.request.url);
-        value = url.pathname + url.search;
-    }
-    else if (history) {
-        value = history.get();
+    if (source) {
+        const u = new URL(source, mockBase);
+        value = u.pathname + u.search;
     }
-    const obj = typeof value === "string" ? { value } : { ...value };
-    return { signal: [() => obj, next => Object.assign(obj, next)], utils: history && history.utils };
+    const obj = { value };
+    return { signal: [() => obj, next => Object.assign(obj, next)], utils };
 }
 export function createRouter(config) {
     const basePath = config.base || "";
@@ -90,9 +94,15 @@ export function createRouter(config) {
                 "Compose route trees in one createRouter config instead.");
         }
         const root = untrack(() => props.children);
+        let restoration;
+        let history = config.history;
+        if (!isServer && (config.scrollRestoration ?? !history)) {
+            restoration = createScrollRestoration();
+            history = withScrollRestoration(history || browserHistory(), restoration);
+        }
         const integration = isServer
-            ? staticIntegration(config.history)
-            : createIntegration(config.history || browserHistory());
+            ? staticIntegration(props.url, config.history && config.history.utils)
+            : createIntegration(history || browserHistory());
         let context;
         const routerState = createRouterContext(integration, branches, () => context, {
             base: basePath,
@@ -109,6 +119,7 @@ export function createRouter(config) {
             setupLinkClaims(routerState, config.explicitLinks);
             if (routerState.singleFlight)
                 onCleanup(registerFlightRouter(routerState));
+            restoration && restoration.create(routerState);
         }
         return (<RouterContextObj value={routerState}>
         <Root routerState={routerState} root={root} preload={config.preload}>

package/dist/routers/history.d.ts

@@ -1,4 +1,6 @@
 import type { LocationChange, RouterUtils } from "../types.js";
+export declare function bindEvent(target: EventTarget, type: string, handler: EventListener): () => void;
+export declare function saveCurrentDepth(): void;
 /**
  * A history adapter: the source of truth for the current URL and how
  * navigations write back to it. Adapters are plain imported values so

package/dist/routers/history.js

@@ -1,5 +1,5 @@
 import { isServer } from "@solidjs/web";
-function bindEvent(target, type, handler) {
+export function bindEvent(target, type, handler) {
     target.addEventListener(type, handler);
     return () => target.removeEventListener(type, handler);
 }
@@ -8,7 +8,7 @@ function bindEvent(target, type, handler) {
 // so blocking stays exact no matter when the first guard subscribes, while the
 // guard machinery itself lives behind the lazy `beforeLeave` slot.
 let depth;
-function saveCurrentDepth() {
+export function saveCurrentDepth() {
     if (!window.history.state || window.history.state._depth == null) {
         window.history.replaceState({ ...window.history.state, _depth: window.history.length - 1 }, "");
     }

package/dist/routers/index.d.ts

@@ -1,4 +1,5 @@
-export { createRouter, defineRoutes } from "./factory.jsx";
-export type { RouterConfig, RouterInstance } from "./factory.jsx";
+export { createRouter, defineRoute, defineRoutes } from "./factory.jsx";
+export type { DefinedRoute } from "./factory.jsx";
+export type { RouterConfig, RouterInstance, RouterProps } from "./factory.jsx";
 export { browserHistory, hashHistory, memoryHistory } from "./history.js";
 export type { RouterHistory, MemoryHistoryAdapter } from "./history.js";

package/dist/routers/index.js

@@ -1,2 +1,2 @@
-export { createRouter, defineRoutes } from "./factory.jsx";
+export { createRouter, defineRoute, defineRoutes } from "./factory.jsx";
 export { browserHistory, hashHistory, memoryHistory } from "./history.js";

package/dist/routers/scrollRestoration.d.ts

@@ -0,0 +1,41 @@
+import type { RouterContext } from "../types.js";
+import type { RouterHistory } from "./history.js";
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables.
+ *
+ * Restoration is a single scroll once routing settles — the same strategy
+ * SvelteKit, TanStack Router and React Router use. Settling after the
+ * transition commits is what makes the offset reachable; chasing a still-
+ * growing document afterwards (a ResizeObserver re-asserting the offset as
+ * content arrives) was tried and removed: no peer router does it, an
+ * unbounded observer re-clamps the viewport to the bottom when the target is
+ * never reachable (a list that is genuinely shorter now), and scroll-induced
+ * layout changes can feed it back into itself. Content that commits after the
+ * transition settles — an image without reserved space, a boundary below the
+ * fold — keeps whatever offset the document can hold.
+ */
+export declare function createScrollRestoration(): {
+    /** When the adapter notifies a traversal: mark the target for restoration. */
+    onPop(): void;
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush(): void;
+    create(router: RouterContext): void;
+};
+export type ScrollRestoration = ReturnType<typeof createScrollRestoration>;
+/**
+ * Threads restoration through a history adapter: pushes prune dead forward
+ * entries, and adapter notifications (unblocked pops) mark the traversal
+ * target. Notification runs after the adapter's depth bookkeeping, so the
+ * marked depth is the entry being restored to.
+ */
+export declare function withScrollRestoration(history: RouterHistory, restoration: ScrollRestoration): RouterHistory;

package/dist/routers/scrollRestoration.js

@@ -0,0 +1,134 @@
+import { createEffect, onCleanup } from "solid-js";
+import { bindEvent, saveCurrentDepth } from "./history.js";
+const STORAGE_KEY = "solid-router:scroll";
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables.
+ *
+ * Restoration is a single scroll once routing settles — the same strategy
+ * SvelteKit, TanStack Router and React Router use. Settling after the
+ * transition commits is what makes the offset reachable; chasing a still-
+ * growing document afterwards (a ResizeObserver re-asserting the offset as
+ * content arrives) was tried and removed: no peer router does it, an
+ * unbounded observer re-clamps the viewport to the bottom when the target is
+ * never reachable (a list that is genuinely shorter now), and scroll-induced
+ * layout changes can feed it back into itself. Content that commits after the
+ * transition settles — an image without reserved space, a boundary below the
+ * fold — keeps whatever offset the document can hold.
+ */
+export function createScrollRestoration() {
+    window.history.scrollRestoration = "manual";
+    // the current entry needs its depth stamp for captures to have a key, even
+    // if something replaced history.state after the adapter stamped it
+    saveCurrentDepth();
+    let positions = {};
+    try {
+        positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)) || {};
+    }
+    catch { }
+    const depth = () => window.history.state && window.history.state._depth;
+    let programmatic = false;
+    let pending;
+    const unbind = [
+        bindEvent(window, "scroll", () => {
+            const d = depth();
+            if (d != null)
+                positions[d] = window.scrollY;
+            // the user took over — a pending restore would yank them
+            if (!programmatic)
+                pending = undefined;
+        }),
+        bindEvent(window, "pagehide", () => {
+            try {
+                sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+            }
+            catch { }
+        })
+    ];
+    const restore = () => {
+        if (pending == null)
+            return;
+        const y = positions[pending];
+        pending = undefined;
+        if (y == null)
+            return;
+        // flagged so the resulting scroll event is not mistaken for the user
+        // taking over (which cancels a pending restore)
+        programmatic = true;
+        window.scrollTo(0, y);
+        programmatic = false;
+    };
+    return {
+        /** When the adapter notifies a traversal: mark the target for restoration. */
+        onPop() {
+            pending = depth();
+        },
+        /** After a push: forward entries died, and this depth may be reused. */
+        onPush() {
+            const d = depth();
+            if (d != null)
+                for (const k in positions)
+                    +k >= d && delete positions[k];
+        },
+        create(router) {
+            // Restore once the traversal has settled: key on the location (a fully
+            // synchronous pop commits without isRouting ever flipping) and on
+            // isRouting, which reports in-flight transitions — native pops
+            // included — and holds the restore until they commit. restore() no-ops
+            // unless a traversal marked a target, so push navigations are inert.
+            // `transparent` keeps the effect invisible to the hydration id scheme —
+            // same reasoning as the link-claims effect (claims.ts): this setup is
+            // client-only, so an id-consuming node here has no server counterpart
+            // and every hydration id allocated after it shifts by one child slot.
+            // The visible failure is any <Loading> content that settled before the
+            // shell flush (a cache hit, a preloaded query): its serialized value and
+            // inlined markup are keyed under the server's ids, the shifted client
+            // misses both, recomputes, and re-renders the route fresh — duplicating
+            // the server DOM and leaving it inert.
+            createEffect(() => ({
+                url: router.location.pathname + router.location.search + router.location.hash,
+                routing: router.isRouting()
+            }), current => {
+                if (!current.routing)
+                    restore();
+            }, { transparent: true });
+            onCleanup(() => unbind.forEach(u => u()));
+            // reload/back_forward document loads land on an existing entry (a fresh
+            // navigation starts a new one and belongs at the top); the effect's
+            // initial run performs the restore after first render
+            const [nav] = (performance.getEntriesByType &&
+                performance.getEntriesByType("navigation"));
+            if (nav && nav.type !== "navigate")
+                pending = depth();
+        }
+    };
+}
+/**
+ * Threads restoration through a history adapter: pushes prune dead forward
+ * entries, and adapter notifications (unblocked pops) mark the traversal
+ * target. Notification runs after the adapter's depth bookkeeping, so the
+ * marked depth is the entry being restored to.
+ */
+export function withScrollRestoration(history, restoration) {
+    return {
+        ...history,
+        set(next) {
+            history.set(next);
+            next.replace || restoration.onPush();
+        },
+        init: history.init &&
+            (notify => history.init(value => {
+                restoration.onPop();
+                notify(value);
+            }))
+    };
+}

package/dist/routing.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from "@solidjs/web";
-import type { Branch, Intent, LazyBoundary, Location, MatchFilters, NavigateOptions, Navigator, Params, RouteDescription, RouteContext, RouteDefinition, RouteMatch, RouterContext, RouterIntegration, SearchParams, SetSearchParams, TypedPath, TypedSearchPath } from "./types.js";
-import type { FlashSubmission } from "./data/flash.js";
+import type { Branch, Intent, LazyBoundary, Location, MatchFilters, NavigateOptions, Navigator, Params, PathMatch, RouteDescription, RouteContext, RouteDefinition, RouteMatch, RouteParams, RouterContext, RouterIntegration, SearchParams, SetSearchParams, TypedPath, TypedSearchPath } from "./types.js";
+import type { FlashSubmission } from "@solidjs/web/server-functions/server";
 /** Consider this API opaque and internal. It is likely to change in the future. */
 export declare const RouterContextObj: import("solid-js").Context<RouterContext>;
 export declare const RouteContextObj: import("solid-js").Context<RouteContext>;
@@ -62,14 +62,22 @@ export declare const useIsRouting: () => () => boolean;
  * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
  * Useful for determining if a given path matches the current route.
  *
+ * Accepts a pattern string — the match's `params` are typed from it — or a
+ * typed path node (a concrete URL, so no params to speak of):
+ *
  * @example
  * ```js
  * const match = useMatch(() => props.href);
  *
  * return <div classList={{ active: Boolean(match()) }} />;
+ *
+ * const section = useMatch(() => "/docs/:page");
+ * section()?.params.page; // string
+ *
+ * const here = useMatch(() => paths.users(2));
  * ```
  */
-export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S>) => import("solid-js").SourceAccessor<import("./types.js").PathMatch | undefined>;
+export declare const useMatch: <S extends string | TypedPath>(path: () => S, matchFilters?: MatchFilters<S extends string ? S : string>) => (() => PathMatch<S extends string ? RouteParams<S> : Params> | undefined);
 /**
  * `useRouteMatches` returns an accessor of the router's resolved matches for
  * the current location — the chain of route definitions producing the current

package/dist/routing.js

@@ -1,8 +1,8 @@
 import { flush, runWithOwner } from "solid-js";
-import { createComponent, createContext, createMemo, createSignal, NotReadyError, untrack, useContext } from "solid-js";
+import { createComponent, createContext, createMemo, createSignal, isPending, NotReadyError, untrack, useContext } from "solid-js";
 import { isServer, getRequestEvent } from "@solidjs/web";
 import { mockBase, comparablePath, createMemoObject, extractSearchParams, invariant, resolvePath, createMatcher, joinPaths, scoreRoute, mergeSearchString, expandOptionals } from "./utils.js";
-import { clearFlashCookie, hasFlashCookie } from "./data/flashCookie.js";
+import { clearFlashCookie, hasFlashCookie } from "@solidjs/web/server-functions";
 const MAX_REDIRECTS = 100;
 /** Consider this API opaque and internal. It is likely to change in the future. */
 export const RouterContextObj = createContext();
@@ -80,16 +80,26 @@ export const useIsRouting = () => useRouter().isRouting;
  * `useMatch` takes an accessor that returns the path and creates a `Memo` that returns match information if the current path matches the provided path.
  * Useful for determining if a given path matches the current route.
  *
+ * Accepts a pattern string — the match's `params` are typed from it — or a
+ * typed path node (a concrete URL, so no params to speak of):
+ *
  * @example
  * ```js
  * const match = useMatch(() => props.href);
  *
  * return <div classList={{ active: Boolean(match()) }} />;
+ *
+ * const section = useMatch(() => "/docs/:page");
+ * section()?.params.page; // string
+ *
+ * const here = useMatch(() => paths.users(2));
  * ```
  */
 export const useMatch = (path, matchFilters) => {
     const location = useLocation();
-    const matchers = createMemo(() => expandOptionals(path()).map(path => createMatcher(path, undefined, matchFilters)));
+    const matchers = createMemo(() => 
+    // `String()` folds typed path nodes to their URL
+    expandOptionals(String(path())).map(path => createMatcher(path, undefined, matchFilters)));
     return createMemo(() => {
         for (const matcher of matchers()) {
             const match = matcher(location.pathname);
@@ -496,7 +506,7 @@ export function provideFlightConsumer(factory) {
 /**
  * The flash-cookie codec, provided by the action side (data/action.ts) so
  * the router core never carries it: the core consumes the cookie eagerly
- * per request (detection + one-shot clear via the tiny flashCookie.ts half)
+ * per request (detection + one-shot clear via the runtime's isomorphic half)
  * but defers decoding to this slot, read when the submissions signal
  * initializes. Actions are created at module scope, so on the server the
  * decoder is always installed before useSubmission can read — and a
@@ -532,7 +542,7 @@ export function createRouterContext(integration, branches, getContext, options =
     else if (basePath && !initialSource.value) {
         setSource({ value: basePath, replace: true, scroll: false });
     }
-    const [isRouting, setIsRouting] = createSignal(false, { ownedWrite: true });
+    const [isNavigating, setIsRouting] = createSignal(false, { ownedWrite: true });
     // Navigate override written from event handlers.
     const [navigateTarget, setNavigateTarget] = createSignal(undefined, {
         ownedWrite: true
@@ -547,7 +557,7 @@ export function createRouterContext(integration, branches, getContext, options =
     // The flash cookie is consumed eagerly: its one-shot clear (Set-Cookie)
     // must be appended before streaming flushes the response headers, and an
     // unread outcome must not haunt a later request's render. Only detection
-    // and clearing happen here (the tiny flashCookie.ts half); the raw header
+    // and clearing happen here (the runtime's isomorphic half); the raw header
     // is stashed and decoding waits for the action-provided codec, read when
     // the lazily allocated submissions signal below first initializes.
     let flashCookieHeader;
@@ -581,6 +591,13 @@ export function createRouterContext(integration, branches, getContext, options =
             throw new NotReadyError(Promise.all(pending.map(resolveLazySubtree)));
         return m;
     });
+    // Every write is a transition in Solid 2, so a native history pop forks the
+    // source signal exactly like programmatic navigation does. isRouting is
+    // therefore derived: the manual flag covers navigateFromRoute's explicit
+    // window, and isPending over the location/matches read reports any
+    // in-flight fork — including popstate traversals and the lazy-subtree
+    // resolution matches() parks on.
+    const isRouting = createMemo(() => isNavigating() || isPending(() => (matches(), location.search, location.hash)));
     const buildParams = () => mergeParams(matches());
     const wrapParams = utils.paramsWrapper
         ? (getParams) => utils.paramsWrapper(getParams, branches)
@@ -739,8 +756,8 @@ export function createRouterContext(integration, branches, getContext, options =
         intent = prevIntent;
     }
     // Seeds the initial submission from a no-JS form post: the server
-    // function handler redirected back with the outcome in a one-shot flash
-    // cookie (see src/server.ts's handleNoJS), consumed eagerly above and
+    // function runtime redirected back with the outcome in a one-shot flash
+    // cookie (its default no-JS convention), consumed eagerly above and
     // decoded here — so the post-redirect SSR renders useSubmission() state
     // exactly as a scripted submission would. An explicitly pre-seeded
     // `event.router.submission` (framework integrations) takes precedence.

package/dist/server.d.ts

@@ -1,7 +1,6 @@
 import type { JSX } from "@solidjs/web";
 import type { CollectFlightDataHook, ServerFunctionOutcome } from "@solidjs/web/server-functions/server";
 import type { RouteDefinition, RoutePreloadFunc } from "./types.js";
-export type { FlashSubmission } from "./data/flash.js";
 export type { CollectFlightDataHook, ServerFunctionOutcome };
 export interface FlightDataCollectorOptions {
     /**
@@ -19,7 +18,7 @@ export interface FlightDataCollectorOptions {
      * render: the merged params of every match and `intent: "initial"`.
      */
     rootPreload?: RoutePreloadFunc;
-    /** The app's base path, for resolving redirect `Location`s and matching. */
+    /** The app's base path, for compiling the route tree's matchers. */
     base?: string;
 }
 /** A `createRouter` instance carries everything the collector needs. */
@@ -38,38 +37,11 @@ interface RouterInstanceLike {
  * and `preload` are the single source of truth — or an options object for
  * trees not created through the factory.
  *
- * Strategy: rerun the route data for the URL the client will show
- * after the mutation — the redirect `Location` when the outcome carries
- * one, the referring page otherwise — collecting each `query` result under
- * its cache key, scoped to the outcome's `X-Revalidate` keys when present
- * (routes newly entered via redirect always collect fully). The returned
- * payload seeds the client router's cache through its registered
- * flight-data consumer.
+ * Strategy: rerun the route data for the URL the client will show after
+ * the mutation (the outcome's pre-digested `targetUrl`), collecting each
+ * `query` result under its cache key, scoped to the outcome's
+ * `revalidateKeys` when present (routes newly entered via redirect always
+ * collect fully). The returned payload seeds the client router's cache
+ * through its registered flight-data consumer.
  */
 export declare function createFlightDataCollector(options: FlightDataCollectorOptions | RouterInstanceLike): CollectFlightDataHook;
-/**
- * The request headers for the flight-data collection pass: the source
- * request's headers with the mutation's `Set-Cookie` mutations folded into
- * the `Cookie` header, so preloads observe the post-mutation cookie state
- * (deletions honored via Max-Age/Expires).
- */
-export declare function createSingleFlightHeaders(sourceEvent: {
-    request: Request;
-    response?: {
-        headers?: Headers;
-    };
-}): Headers;
-export interface NoJSHandlerOptions {
-    /** The app's base path, for resolving redirect `Location`s. */
-    base?: string;
-}
-/**
- * Produces the `handleNoJS` implementation for
- * `handleServerFunctionRequest` options: form posts made without the client
- * runtime redirect back to the referring page (or to the result's
- * `Location`) with the outcome riding a one-shot `flash` cookie. The
- * router's SSR initialization reads the cookie into submission state, so
- * `useSubmission()` renders the result exactly as a scripted submission
- * would — progressive enhancement with no app code.
- */
-export declare function createNoJSHandler(options?: NoJSHandlerOptions): (result: unknown, request: Request, args: unknown[], thrown?: boolean) => Response;