@solidjs/router 0.17.0-next.6 → 1.0.0-next.11

package/dist/routers/factory.jsx

@@ -0,0 +1,151 @@
+/*@refresh skip*/
+import { createSignal, getOwner, onCleanup, sharedConfig, untrack } from "solid-js";
+import { getRequestEvent, isServer } from "@solidjs/web";
+import { setupLinkClaims } from "../claims.js";
+import { setupNativeEvents } from "../data/events.js";
+import { createPathsProxy } from "../paths.js";
+import { createBranches, createRouterContext, getRouteMatches, registerFlightRouter, RouterContextObj, trackLazySubtrees, useOptionalContext } from "../routing.js";
+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
+ * inline arrays, but an extracted `const routes = [...]` widens paths to
+ * `string` and silently degrades `paths` and the typed hooks unless it is
+ * declared `as const` — `defineRoutes` makes that impossible to forget.
+ */
+export function defineRoutes(routes) {
+    return routes;
+}
+/** Wraps a history adapter in the integration signal the router core consumes. Must run under a reactive owner. */
+function createIntegration(history) {
+    let ignore = false;
+    const wrap = (value) => (typeof value === "string" ? { value } : value);
+    const [read, write] = createSignal(wrap(history.get()), {
+        equals: (a, b) => a.value === b.value && a.state === b.state,
+        ownedWrite: true
+    });
+    const signal = [
+        read,
+        (next) => {
+            !ignore && history.set(next);
+            if (sharedConfig.registry && !sharedConfig.done)
+                sharedConfig.done = true;
+            write(next);
+        }
+    ];
+    history.init &&
+        onCleanup(history.init((value = history.get()) => {
+            ignore = true;
+            signal[1](wrap(value));
+            ignore = false;
+        }));
+    return { signal, utils: history.utils };
+}
+/**
+ * Server default: a static view of the request URL — no signal machinery, a
+ * 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(url, utils) {
+    const e = getRequestEvent();
+    const source = e ? e.request.url : url;
+    let value = "";
+    if (source) {
+        const u = new URL(source, mockBase);
+        value = u.pathname + u.search;
+    }
+    const obj = { value };
+    return { signal: [() => obj, next => Object.assign(obj, next)], utils };
+}
+export function createRouter(config) {
+    const basePath = config.base || "";
+    // Routes are immutable per instance, so compilation is shared by every
+    // mount, request, and `match()` call — recompiled only when a lazy subtree
+    // resolves (append-only: resolution, not mutation). Reading the version
+    // inside a computation subscribes it; plain calls just see current state.
+    let compiled;
+    let compiledVersion = -1;
+    const branches = () => {
+        const version = trackLazySubtrees();
+        if (!compiled || compiledVersion !== version) {
+            compiled = createBranches(config.routes, basePath);
+            compiledVersion = version;
+        }
+        return compiled;
+    };
+    const renderPath = (config.history && config.history.utils && config.history.utils.renderPath) || undefined;
+    function RouterComponent(props) {
+        // One router per app: the session (location, history, delegation, link
+        // claims, preloading) has a single owner, and a second instance would
+        // fight it — stale content on click navigations, conflicting link
+        // attributes. Compose route trees instead; lazy subtrees are the planned
+        // answer for definitions unknown at build time.
+        if (useOptionalContext(RouterContextObj)) {
+            console.warn("Mounting a router inside another router is not supported. " +
+                "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(props.url, config.history && config.history.utils)
+            : createIntegration(history || browserHistory());
+        let context;
+        const routerState = createRouterContext(integration, branches, () => context, {
+            base: basePath,
+            singleFlight: config.singleFlight,
+            transformUrl: config.transformUrl
+        });
+        if (!isServer) {
+            setupNativeEvents({
+                preload: config.preloadLinks,
+                explicitLinks: config.explicitLinks,
+                actionBase: config.actionBase,
+                transformUrl: config.transformUrl
+            })(routerState);
+            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}>
+          {(context = getOwner()) && null}
+          <Routes routerState={routerState} branches={branches}/>
+        </Root>
+      </RouterContextObj>);
+    }
+    const instance = Object.assign(RouterComponent, {
+        routes: config.routes,
+        config,
+        match(url) {
+            const u = new URL(url, mockBase);
+            const pathname = config.transformUrl ? config.transformUrl(u.pathname) : u.pathname;
+            return getRouteMatches(branches(), pathname).map(({ route, path, params }) => ({
+                path: route.originalPath,
+                pattern: route.pattern,
+                match: path,
+                params,
+                info: route.info
+            }));
+        }
+    });
+    // Built on first access (a getter via Object.assign would run during the
+    // copy) so runtimes without Proxy — some older TVs — can still route as
+    // long as they never touch typed paths.
+    let paths;
+    Object.defineProperty(instance, "paths", {
+        get: () => paths || (paths = createPathsProxy(renderPath, basePath))
+    });
+    return instance;
+}

package/dist/routers/history.d.ts

@@ -0,0 +1,26 @@
+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
+ * unused ones never enter the bundle — `createRouter` defaults to browser
+ * history on the client and the request URL on the server.
+ */
+export interface RouterHistory {
+    get: () => string | LocationChange;
+    set: (next: LocationChange) => void;
+    init?: (notify: (value?: string | LocationChange) => void) => () => void;
+    utils?: Partial<RouterUtils>;
+}
+export declare function browserHistory(): RouterHistory;
+export declare function hashParser(str: string): string;
+export declare function hashHistory(): RouterHistory;
+export interface MemoryHistoryAdapter extends RouterHistory {
+    get: () => string;
+    go: (delta: number) => void;
+    back: () => void;
+    forward: () => void;
+    listen: (listener: (value: string) => void) => () => void;
+}
+export declare function memoryHistory(initial?: string): MemoryHistoryAdapter;

package/dist/routers/history.js

@@ -0,0 +1,180 @@
+import { isServer } from "@solidjs/web";
+export function bindEvent(target, type, handler) {
+    target.addEventListener(type, handler);
+    return () => target.removeEventListener(type, handler);
+}
+// Depth stamping supports blocking browser-initiated navigation (back/forward)
+// for `useBeforeLeave`. It stays always-on — a couple of history.state writes —
+// so blocking stays exact no matter when the first guard subscribes, while the
+// guard machinery itself lives behind the lazy `beforeLeave` slot.
+let depth;
+export function saveCurrentDepth() {
+    if (!window.history.state || window.history.state._depth == null) {
+        window.history.replaceState({ ...window.history.state, _depth: window.history.length - 1 }, "");
+    }
+    depth = window.history.state._depth;
+}
+function keepDepth(state) {
+    return {
+        ...state,
+        _depth: window.history.state && window.history.state._depth
+    };
+}
+function notifyIfNotBlocked(notify, block) {
+    let ignore = false;
+    return () => {
+        const prevDepth = depth;
+        saveCurrentDepth();
+        const delta = prevDepth == null ? null : depth - prevDepth;
+        if (ignore) {
+            ignore = false;
+            return;
+        }
+        if (delta && block(delta)) {
+            ignore = true;
+            window.history.go(-delta);
+        }
+        else {
+            notify();
+        }
+    };
+}
+function scrollToHash(hash, fallbackTop) {
+    const el = hash && document.getElementById(hash);
+    if (el) {
+        el.scrollIntoView();
+    }
+    else if (fallbackTop) {
+        window.scrollTo(0, 0);
+    }
+}
+export function browserHistory() {
+    const getSource = () => {
+        const url = window.location.pathname + window.location.search;
+        const state = window.history.state &&
+            window.history.state._depth &&
+            Object.keys(window.history.state).length === 1
+            ? undefined
+            : window.history.state;
+        return {
+            value: url + window.location.hash,
+            state
+        };
+    };
+    const beforeLeave = {};
+    if (!isServer)
+        saveCurrentDepth();
+    return {
+        get: getSource,
+        set({ value, replace, scroll, state }) {
+            if (replace) {
+                window.history.replaceState(keepDepth(state), "", value);
+            }
+            else {
+                window.history.pushState(state, "", value);
+            }
+            scrollToHash(decodeURIComponent(window.location.hash.slice(1)), scroll);
+            saveCurrentDepth();
+        },
+        init: notify => bindEvent(window, "popstate", notifyIfNotBlocked(notify, delta => {
+            const guard = beforeLeave.current;
+            if (!guard)
+                return false;
+            if (delta) {
+                return !guard.confirm(delta);
+            }
+            else {
+                const s = getSource();
+                return !guard.confirm(s.value, { state: s.state });
+            }
+        })),
+        utils: {
+            go: delta => window.history.go(delta),
+            beforeLeave
+        }
+    };
+}
+export function hashParser(str) {
+    const to = str.replace(/^.*?#/, "");
+    // Hash-only hrefs like `#foo` from plain anchors will come in as `/#foo` whereas a link to
+    // `/foo` will be `/#/foo`. Check if the to starts with a `/` and if not append it as a hash
+    // to the current path so we can handle these in-page anchors correctly.
+    if (!to.startsWith("/")) {
+        const [, path = "/"] = window.location.hash.split("#", 2);
+        return `${path}#${to}`;
+    }
+    return to;
+}
+export function hashHistory() {
+    const getSource = () => window.location.hash.slice(1);
+    const beforeLeave = {};
+    if (!isServer)
+        saveCurrentDepth();
+    return {
+        get: getSource,
+        set({ value, replace, scroll, state }) {
+            if (replace) {
+                window.history.replaceState(keepDepth(state), "", "#" + value);
+            }
+            else {
+                window.history.pushState(state, "", "#" + value);
+            }
+            const hashIndex = value.indexOf("#");
+            const hash = hashIndex >= 0 ? value.slice(hashIndex + 1) : "";
+            scrollToHash(hash, scroll);
+            saveCurrentDepth();
+        },
+        init: notify => bindEvent(window, "hashchange", notifyIfNotBlocked(notify, delta => {
+            const guard = beforeLeave.current;
+            return !!guard && !guard.confirm(delta && delta < 0 ? delta : getSource());
+        })),
+        utils: {
+            go: delta => window.history.go(delta),
+            renderPath: path => `#${path}`,
+            parsePath: hashParser,
+            beforeLeave
+        }
+    };
+}
+export function memoryHistory(initial = "/") {
+    const entries = [initial];
+    let index = 0;
+    const listeners = [];
+    const go = (n) => {
+        // https://github.com/remix-run/react-router/blob/682810ca929d0e3c64a76f8d6e465196b7a2ac58/packages/router/history.ts#L245
+        index = Math.max(0, Math.min(index + n, entries.length - 1));
+        const value = entries[index];
+        listeners.forEach(listener => listener(value));
+    };
+    const listen = (listener) => {
+        listeners.push(listener);
+        return () => {
+            const i = listeners.indexOf(listener);
+            listeners.splice(i, 1);
+        };
+    };
+    return {
+        get: () => entries[index],
+        set: ({ value, scroll, replace }) => {
+            if (replace) {
+                entries[index] = value;
+            }
+            else {
+                entries.splice(index + 1, entries.length - index, value);
+                index++;
+            }
+            listeners.forEach(listener => listener(value));
+            setTimeout(() => {
+                if (scroll) {
+                    scrollToHash(value.split("#")[1] || "", true);
+                }
+            }, 0);
+        },
+        back: () => go(-1),
+        forward: () => go(1),
+        go,
+        listen,
+        init: listen,
+        utils: { go }
+    };
+}

package/dist/routers/index.d.ts

@@ -1,11 +1,4 @@
-export { Route } from "./components.jsx";
-export type { BaseRouterProps, RouteProps } from "./components.jsx";
-export { createRouter } from "./createRouter.js";
-export { Router } from "./Router.js";
-export type { RouterProps } from "./Router.js";
-export { HashRouter } from "./HashRouter.js";
-export type { HashRouterProps } from "./HashRouter.js";
-export { MemoryRouter, createMemoryHistory } from "./MemoryRouter.js";
-export type { MemoryRouterProps, MemoryHistory } from "./MemoryRouter.js";
-export { StaticRouter } from "./StaticRouter.js";
-export type { StaticRouterProps } from "./StaticRouter.js";
+export { createRouter, defineRoutes } 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,6 +1,2 @@
-export { Route } from "./components.jsx";
-export { createRouter } from "./createRouter.js";
-export { Router } from "./Router.js";
-export { HashRouter } from "./HashRouter.js";
-export { MemoryRouter, createMemoryHistory } from "./MemoryRouter.js";
-export { StaticRouter } from "./StaticRouter.js";
+export { createRouter, 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);
+            }))
+    };
+}