@solidjs/router 1.0.0 → 2.0.0-next.13

package/dist/routing.d.ts

@@ -1,11 +1,15 @@
-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";
+import type { JSX } from "@solidjs/web";
+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 | undefined>;
-export declare const RouteContextObj: import("solid-js").Context<RouteContext | undefined>;
+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 useRouter: () => RouterContext;
 export declare const useRoute: () => RouteContext;
-export declare const useResolvedPath: (path: () => string) => Accessor<string | undefined>;
+export declare const useResolvedPath: (path: () => string) => import("solid-js").SourceAccessor<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:
@@ -39,8 +43,8 @@ export declare const useNavigate: () => Navigator;
  */
 export declare const useLocation: <S = unknown>() => Location<S>;
 /**
- * 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.
+ * 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.
  *
  * @example
  * ```js
@@ -55,43 +59,55 @@ export declare const useLocation: <S = unknown>() => Location<S>;
  */
 export declare const useIsRouting: () => () => boolean;
 /**
- * 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.
+ * `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 preload = usePreloadRoute();
+ * const match = useMatch(() => props.href);
+ *
+ * return <div classList={{ active: Boolean(match()) }} />;
  *
- * preload(`/users/settings`, { preloadData: true });
+ * const section = useMatch(() => "/docs/:page");
+ * section()?.params.page; // string
+ *
+ * const here = useMatch(() => paths.users(2));
  * ```
  */
-export declare const usePreloadRoute: () => (url: string | URL, options?: {
-    preloadData?: boolean;
-}) => void;
+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);
 /**
- * `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.
+ * `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.
  *
  * @example
  * ```js
- * const match = useMatch(() => props.href);
+ * const matches = useRouteMatches();
  *
- * return <div classList={{ active: Boolean(match()) }} />;
+ * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb));
  * ```
  */
-export declare const useMatch: <S extends string>(path: () => S, matchFilters?: MatchFilters<S>) => Accessor<import("./types.js").PathMatch | undefined>;
+export declare const useRouteMatches: () => () => RouteMatch[];
 /**
- * `useCurrentMatches` returns all the matches for the current matched route.
- * Useful for getting all the route information.
+ * `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.
  *
  * @example
  * ```js
- * const matches = useCurrentMatches();
+ * const preload = usePreloadRoute();
  *
- * const breadcrumbs = createMemo(() => matches().map(m => m.route.info.breadcrumb))
+ * preload(paths.users(2).settings, { preloadData: true });
  * ```
  */
-export declare const useCurrentMatches: () => () => RouteMatch[];
+export declare const usePreloadRoute: () => (url: string | URL | TypedPath, options?: {
+    preloadData?: boolean;
+}) => void;
 /**
  * Retrieves a reactive, store-like object containing the current route path parameters as defined in the Route.
  *
@@ -100,10 +116,13 @@ export declare const useCurrentMatches: () => () => RouteMatch[];
  * const params = useParams();
  *
  * // fetch user based on the id path parameter
- * const [user] = createResource(() => params.id, fetchUser);
+ * const getUser = query(() => fetchUser(params.id), "user");
  * ```
  */
-export declare const useParams: <T extends Params>() => T;
+export declare function useParams<T extends Params>(): T;
+export declare function useParams<P extends Params>(path: TypedPath<P>): {
+    [K in keyof P]: P[K];
+};
 /**
  * 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.
@@ -131,39 +150,64 @@ export declare const useParams: <T extends Params>() => T;
  * );
  * ```
  */
-export declare const useSearchParams: <T extends SearchParams>() => [Partial<T>, (params: SetSearchParams, options?: Partial<NavigateOptions>) => void];
+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;
+}
 /**
- * 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).
+ * Reactive link state for custom link components — the programmatic
+ * counterpart of the attribute vocabulary plain anchors receive
+ * (`aria-current`, `data-active`, `data-pending`).
  *
  * @example
- * ```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);
- *   }
- * });
+ * ```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>
+ *   );
+ * }
  * ```
  */
-export declare const useBeforeLeave: (listener: (e: BeforeLeaveEventArgs) => void) => void;
+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 function createRoutes(routeDef: RouteDefinition, base?: string): RouteDescription[];
 export declare function createBranch(routes: RouteDescription[], index?: number): Branch;
-export declare function createBranches(routeDef: RouteDefinition | RouteDefinition[], base?: string, stack?: RouteDescription[], branches?: Branch[]): Branch[];
+export declare function createBranches(routeDef: RouteDefinition | readonly 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;
@@ -172,4 +216,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): RouteContext;
+export declare function createRouteContext(router: RouterContext, parent: RouteContext, outlet: () => JSX.Element, match: () => RouteMatch, matches?: () => RouteMatch[]): RouteContext;