@solidjs/router 1.0.0-next.8 → 1.0.0

package/dist/routers/index.d.ts

@@ -1,4 +1,11 @@
-export { createRouter, defineRoutes } from "./factory.jsx";
-export type { RouterConfig, RouterInstance } from "./factory.jsx";
-export { browserHistory, hashHistory, memoryHistory } from "./history.js";
-export type { RouterHistory, MemoryHistoryAdapter } from "./history.js";
+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";

package/dist/routers/index.js

@@ -1,2 +1,6 @@
-export { createRouter, defineRoutes } from "./factory.jsx";
-export { browserHistory, hashHistory, memoryHistory } from "./history.js";
+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";

package/dist/routers/scrollRestoration.d.ts

@@ -0,0 +1,32 @@
+import type { RouterContext } from "../types.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(): {
+    /** Before the router reacts to a popstate: mark the traversal target. */
+    onPop(): void;
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush(): void;
+    create(router: RouterContext): void;
+};

package/dist/routers/scrollRestoration.js

@@ -0,0 +1,96 @@
+import { createEffect, on, onCleanup } from "solid-js";
+import { saveCurrentDepth } from "../lifecycle.js";
+import { bindEvent } from "./createRouter.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 lifecycle module loaded
+    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 {
+        /** Before the router reacts to a popstate: mark the traversal target. */
+        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) {
+            createEffect(on(router.isRouting, routing => routing || restore(), { defer: 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
+            const [nav] = (performance.getEntriesByType &&
+                performance.getEntriesByType("navigation"));
+            if (nav && nav.type !== "navigate") {
+                pending = depth();
+                restore();
+            }
+        }
+    };
+}

package/dist/routing.d.ts

@@ -1,15 +1,11 @@
-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 { JSX, Accessor } from "solid-js";
+import type { BeforeLeaveEventArgs, Branch, Intent, Location, MatchFilters, NavigateOptions, Navigator, Params, RouteDescription, RouteContext, RouteDefinition, RouteMatch, RouterContext, RouterIntegration, SearchParams, SetSearchParams } from "./types.js";
 /** 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>;
-export declare function useOptionalContext<T>(context: {
-    defaultValue?: T;
-}): T | undefined;
+export declare const RouterContextObj: import("solid-js").Context<RouterContext | undefined>;
+export declare const RouteContextObj: import("solid-js").Context<RouteContext | undefined>;
 export declare const useRouter: () => RouterContext;
 export declare const useRoute: () => RouteContext;
-export declare const useResolvedPath: (path: () => string) => import("solid-js").SourceAccessor<string | undefined>;
+export declare const useResolvedPath: (path: () => string) => Accessor<string | undefined>;
 export declare const useHref: <T extends string | undefined>(to: () => T) => () => string | T;
 /**
  * Retrieves method to do navigation. The method accepts a path to navigate to and an optional object with the following options:
@@ -43,8 +39,8 @@ export declare const useNavigate: () => Navigator;
  */
 export declare const useLocation: <S = unknown>() => Location<S>;
 /**
- * Retrieves a signal that indicates whether the router is currently processing a navigation.
- * Useful for showing pending navigation state while the next route and its data settle.
+ * Retrieves signal that indicates whether the route is currently in a *Transition*.
+ * Useful for showing stale/pending state when the route resolution is *Suspended* during concurrent rendering.
  *
  * @example
  * ```js
@@ -59,47 +55,43 @@ export declare const useLocation: <S = unknown>() => Location<S>;
  */
 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.
+ * usePreloadRoute returns a function that can be used to preload a route manual.
+ * This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
  *
  * @example
  * ```js
- * const match = useMatch(() => props.href);
+ * const preload = usePreloadRoute();
  *
- * return <div classList={{ active: Boolean(match()) }} />;
+ * preload(`/users/settings`, { preloadData: true });
  * ```
  */
-export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S>) => import("solid-js").SourceAccessor<import("./types.js").PathMatch | undefined>;
+export declare const usePreloadRoute: () => (url: string | URL, options?: {
+    preloadData?: boolean;
+}) => void;
 /**
- * `useRouteMatches` returns an accessor of the router's resolved matches for
- * the current location — the chain of route definitions producing the current
- * render, outermost first. Useful for reading `info` metadata off the matched
- * chain. Unlike `useMatch`, which tests a path pattern you supply against the
- * location, this reflects the route tree itself.
+ * `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.
  *
  * @example
  * ```js
- * const matches = useRouteMatches();
+ * const match = useMatch(() => props.href);
  *
- * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
+ * return <div classList={{ active: Boolean(match()) }} />;
  * ```
  */
-export declare const useRouteMatches: () => () => RouteMatch[];
+export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S>) => Accessor<import("./types.js").PathMatch | undefined>;
 /**
- * `usePreloadRoute` returns a function for warming a route by hand — the same
- * work link hover/focus intent triggers automatically: the matched routes'
- * lazy components load, and with `preloadData` their `preload` functions run.
+ * `useCurrentMatches` returns all the matches for the current matched route.
+ * Useful for getting all the route information.
  *
  * @example
  * ```js
- * const preload = usePreloadRoute();
+ * const matches = useCurrentMatches();
  *
- * preload(paths.users(2).settings, { preloadData: true });
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
  * ```
  */
-export declare const usePreloadRoute: () => (url: string | URL | TypedPath, options?: {
-    preloadData?: boolean;
-}) => void;
+export declare const useCurrentMatches: () => () => RouteMatch[];
 /**
  * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
  *
@@ -108,13 +100,10 @@ export declare const usePreloadRoute: () => (url: string | URL | TypedPath, opti
  * const params = useParams();
  *
  * // fetch user based on the id path parameter
- * const getUser = query(() => fetchUser(params.id), "user");
+ * const [user] = createResource(() => params.id, fetchUser);
  * ```
  */
-export declare function useParams<T extends Params>(): T;
-export declare function useParams<P extends Params>(path: TypedPath<P>): {
-    [K in keyof P]: P[K];
-};
+export declare const useParams: <T extends Params>() => T;
 /**
  * Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them.
  * The object is a proxy so you must access properties to subscribe to reactive updates.
@@ -142,64 +131,39 @@ export declare function useParams<P extends Params>(path: TypedPath<P>): {
  * );
  * ```
  */
-export declare function useSearchParams<In, Out>(path: TypedSearchPath<In, Out>): [Out, (params: Partial<In>, options?: Partial<NavigateOptions>) => void];
-export declare function useSearchParams<T extends SearchParams>(): [
-    Partial<T>,
-    (params: SetSearchParams, options?: Partial<NavigateOptions>) => void
-];
-export interface LinkState {
-    /** The location matches this link or lives under it (exact-only when `end`). Styling: `data-active`. */
-    active: () => boolean;
-    /** The location matches this link exactly — what `aria-current="page"` reflects. */
-    current: () => boolean;
-    /** This link is the target of an in-flight navigation. Styling: `data-pending`. */
-    pending: () => boolean;
-}
+export declare const useSearchParams: <T extends SearchParams>() => [Partial<T>, (params: SetSearchParams, options?: Partial<NavigateOptions>) => void];
 /**
- * Reactive link state for custom link components — the programmatic
- * counterpart of the attribute vocabulary plain anchors receive
- * (`aria-current`, `data-active`, `data-pending`).
+ * useBeforeLeave takes a function that will be called prior to leaving a route.
+ * The function will be called with:
+ *
+ * - from (*Location*): current location (before change).
+ * - to (*string | number*): path passed to `navigate`.
+ * - options (*NavigateOptions*): options passed to navigate.
+ * - preventDefault (*function*): call to block the route change.
+ * - defaultPrevented (*readonly boolean*): `true` if any previously called leave handlers called `preventDefault`.
+ * - retry (*function*, force?: boolean ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (i.e. force navigate without confirming).
  *
  * @example
- * ```tsx
- * function TabLink(props: { href: string; children: JSX.Element }) {
- *   const link = useLinkState(() => props.href);
- *   return (
- *     <a href={props.href} class="tab" data-selected={link.active() || undefined}>
- *       {props.children}
- *     </a>
- *   );
- * }
+ * ```js
+ * useBeforeLeave((e: BeforeLeaveEventArgs) => {
+ *   if (form.isDirty && !e.defaultPrevented) {
+ *     // preventDefault to block immediately and prompt user async
+ *     e.preventDefault();
+ *     setTimeout(() => {
+ *       if (window.confirm("Discard unsaved changes - are you sure?")) {
+ *         // user wants to proceed anyway so retry with force=true
+ *         e.retry(true);
+ *       }
+ *     }, 100);
+ *   }
+ * });
  * ```
  */
-export declare const useLinkState: (href: () => string | TypedPath, options?: {
-    end?: boolean;
-}) => LinkState;
-/** Reactive read of the lazy-subtree version — recompile compiled branches when it changes. */
-export declare function trackLazySubtrees(): number;
-/** Non-reactive read, for cache-busting outside the reactive graph (server collectors). */
-export declare function peekLazySubtrees(): number;
-/**
- * Kicks (or joins) a boundary's resolution. Returns the resolved routes
- * synchronously once available, the in-flight promise otherwise. Commit is
- * always async — even for thunks returning arrays — so the version bump
- * never writes a signal from inside a render computation.
- */
-export declare function resolveLazySubtree(record: LazyBoundary): readonly RouteDefinition[] | Promise<readonly RouteDefinition[]>;
-/**
- * The unresolved boundaries in a match chain. Rendering gates on these (the
- * route-states memo suspends until they land — see routers/components.tsx)
- * and the server's flight collector awaits them before its preload pass.
- */
-export declare function unresolvedLazyMatches(matches: RouteMatch[]): LazyBoundary[];
+export declare const useBeforeLeave: (listener: (e: BeforeLeaveEventArgs) => void) => void;
 export declare function createRoutes(routeDef: RouteDefinition, base?: string): RouteDescription[];
 export declare function createBranch(routes: RouteDescription[], index?: number): Branch;
-export declare function createBranches(routeDef: RouteDefinition | readonly RouteDefinition[], base?: string, stack?: RouteDescription[], branches?: Branch[]): Branch[];
+export declare function createBranches(routeDef: RouteDefinition | RouteDefinition[], base?: string, stack?: RouteDescription[], branches?: Branch[]): Branch[];
 export declare function getRouteMatches(branches: Branch[], location: string): RouteMatch[];
-export declare function mergeParams(matches: RouteMatch[]): Params;
-export declare function registerFlightRouter(router: RouterContext): () => void;
-export declare function provideFlightConsumer(factory: (router: RouterContext) => () => void): void;
-export declare function provideFlashDecoder(decoder: (cookieHeader: string | null) => FlashSubmission | undefined): void;
 export declare function getIntent(): Intent | undefined;
 export declare function getInPreloadFn(): boolean;
 export declare function setInPreloadFn(value: boolean): void;
@@ -208,4 +172,4 @@ export declare function createRouterContext(integration: RouterIntegration, bran
     singleFlight?: boolean;
     transformUrl?: (url: string) => string;
 }): RouterContext;
-export declare function createRouteContext(router: RouterContext, parent: RouteContext, outlet: () => JSX.Element, match: () => RouteMatch, matches?: () => RouteMatch[]): RouteContext;
+export declare function createRouteContext(router: RouterContext, parent: RouteContext, outlet: () => JSX.Element, match: () => RouteMatch): RouteContext;