@real-router/svelte 0.2.13 → 0.3.1

package/README.md

@@ -142,6 +142,7 @@ Navigation link with automatic active state detection. Uses `$derived` for href
 | `activeStrict`      | `boolean`           | `false`     | Exact match only (no ancestor matching) |
 | `ignoreQueryParams` | `boolean`           | `true`      | Query params don't affect active state  |
 | `target`            | `string`            | `undefined` | Link target (`_blank`, etc.)            |
+| `onclick`           | `(evt: MouseEvent) => void` | `undefined` | Custom click handler. Runs **before** the navigation logic — call `evt.preventDefault()` to suppress navigation. |
 
 All other props are spread onto the `<a>` element.
 
@@ -206,7 +207,13 @@ Declarative error handling for navigation errors. Shows a fallback **alongside**
 </script>
 
 <RouterErrorBoundary
-  onError={(error) => analytics.track("nav_error", { code: error.code })}
+  onError={(error, toRoute, fromRoute) =>
+    analytics.track("nav_error", {
+      code: error.code,
+      to: toRoute?.name,
+      from: fromRoute?.name,
+    })
+  }
 >
   {#snippet fallback(error, resetError)}
     <div class="toast">
@@ -220,6 +227,8 @@ Declarative error handling for navigation errors. Shows a fallback **alongside**
 
 Auto-resets on next successful navigation. Works with both `<Link>` and imperative `router.navigate()`.
 
+**`onError` signature:** `(error, toRoute, fromRoute) => void`. Receives the `RouterError`, the attempted destination (`State | null`), and the previously active route (`State | null`). A throwing `onError` is caught by the boundary, logged via `console.error`, and never breaks reactivity.
+
 ## Actions
 
 ### `createLinkAction`
@@ -363,9 +372,9 @@ Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
 ## Examples
 
-15 runnable examples — each is a standalone Vite app. Run: `cd examples/svelte/basic && pnpm dev`
+16 runnable examples — each is a standalone Vite app. Run: `cd examples/svelte/basic && pnpm dev`
 
-[basic](../../examples/svelte/basic) · [nested-routes](../../examples/svelte/nested-routes) · [auth-guards](../../examples/svelte/auth-guards) · [data-loading](../../examples/svelte/data-loading) · [lazy-loading](../../examples/svelte/lazy-loading) · [async-guards](../../examples/svelte/async-guards) · [hash-routing](../../examples/svelte/hash-routing) · [persistent-params](../../examples/svelte/persistent-params) · [error-handling](../../examples/svelte/error-handling) · [dynamic-routes](../../examples/svelte/dynamic-routes) · [link-action](../../examples/svelte/link-action) · [lazy-loading-svelte](../../examples/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/svelte/snippets-routing) · [reactive-source](../../examples/svelte/reactive-source) · [combined](../../examples/svelte/combined)
+[basic](../../examples/svelte/basic) · [nested-routes](../../examples/svelte/nested-routes) · [auth-guards](../../examples/svelte/auth-guards) · [data-loading](../../examples/svelte/data-loading) · [lazy-loading](../../examples/svelte/lazy-loading) · [async-guards](../../examples/svelte/async-guards) · [hash-routing](../../examples/svelte/hash-routing) · [persistent-params](../../examples/svelte/persistent-params) · [error-handling](../../examples/svelte/error-handling) · [dynamic-routes](../../examples/svelte/dynamic-routes) · [link-action](../../examples/svelte/link-action) · [lazy-loading-svelte](../../examples/svelte/lazy-loading-svelte) · [snippets-routing](../../examples/svelte/snippets-routing) · [reactive-source](../../examples/svelte/reactive-source) · [search-schema](../../examples/svelte/search-schema) · [combined](../../examples/svelte/combined)
 
 ## Related Packages
 

package/dist/RouterProvider.svelte

@@ -5,6 +5,7 @@
   import { setContext } from "svelte";
 
   import { createReactiveSource } from "./createReactiveSource.svelte";
+  import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
   import type { Router } from "@real-router/core";
@@ -26,26 +27,11 @@
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);
+  const routeContext = createRouteContext(navigator, reactive);
 
   setContext(ROUTER_KEY, router);
   setContext(NAVIGATOR_KEY, navigator);
-  setContext(ROUTE_KEY, {
-    navigator,
-    get route() {
-      return {
-        get current() {
-          return reactive.current.route;
-        },
-      };
-    },
-    get previousRoute() {
-      return {
-        get current() {
-          return reactive.current.previousRoute;
-        },
-      };
-    },
-  });
+  setContext(ROUTE_KEY, routeContext);
 </script>
 
 {@render children()}

package/dist/actions/link.svelte.d.ts

@@ -5,6 +5,7 @@ export interface LinkActionParams {
     params?: Params;
     options?: NavigationOptions;
 }
+type LinkAction = (node: HTMLElement, params: LinkActionParams) => ActionReturn<LinkActionParams>;
 /**
  * Factory function that captures router context during component initialization.
  * Must be called during component init (not inside event handlers or effects).
@@ -23,4 +24,5 @@ export interface LinkActionParams {
  * <a use:link={{ name: 'users', params: { id: '123' } }}>User Profile</a>
  * ```
  */
-export declare function createLinkAction(): (node: HTMLElement, params: LinkActionParams) => ActionReturn<LinkActionParams>;
+export declare function createLinkAction(): LinkAction;
+export {};

package/dist/actions/link.svelte.js

@@ -1,5 +1,5 @@
-import { getContext } from "svelte";
-import { ROUTER_KEY } from "../context";
+import { ROUTER_KEY, getContextOrThrow } from "../context";
+import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
 import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
 /**
  * Factory function that captures router context during component initialization.
@@ -20,30 +20,28 @@ import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
  * ```
  */
 export function createLinkAction() {
-    const router = getContext(ROUTER_KEY);
-    if (!router) {
-        throw new Error("createLinkAction must be called inside a RouterProvider");
-    }
+    const router = getContextOrThrow(ROUTER_KEY, "createLinkAction");
     return function link(node, params) {
         let currentParams = params;
         applyLinkA11y(node);
+        function navigate() {
+            router
+                .navigate(currentParams.name, currentParams.params ?? EMPTY_PARAMS, currentParams.options ?? EMPTY_OPTIONS)
+                .catch(NOOP);
+        }
         function handleClick(evt) {
             if (!shouldNavigate(evt))
                 return;
+            if (node instanceof HTMLAnchorElement &&
+                node.getAttribute("target") === "_blank") {
+                return;
+            }
             evt.preventDefault();
-            // router is guaranteed to exist due to check in factory
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            router
-                .navigate(currentParams.name, currentParams.params ?? {}, currentParams.options ?? {})
-                .catch(() => { });
+            navigate();
         }
         function handleKeyDown(evt) {
             if (evt.key === "Enter" && !(node instanceof HTMLButtonElement)) {
-                // router is guaranteed to exist due to check in factory
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                router
-                    .navigate(currentParams.name, currentParams.params ?? {}, currentParams.options ?? {})
-                    .catch(() => { });
+                navigate();
             }
         }
         node.addEventListener("click", handleClick);

package/dist/components/Lazy.svelte

@@ -9,26 +9,33 @@
     fallback?: Component | undefined;
   } = $props();
 
-  let LoadedComponent = $state<Component | null>(null);
-  let error = $state<Error | null>(null);
-  let loading = $state(true);
+  type LazyState =
+    | { status: "loading" }
+    | { status: "ready"; component: Component }
+    | { status: "error"; error: Error };
+
+  let state = $state<LazyState>({ status: "loading" });
 
   $effect(() => {
-    loading = true;
-    error = null;
-    LoadedComponent = null;
+    state = { status: "loading" };
     let active = true;
 
     loader()
       .then((module) => {
         if (!active) return;
-        LoadedComponent = module.default;
-        loading = false;
+        if (!module || typeof module.default === "undefined") {
+          throw new Error(
+            "[real-router] Lazy loader resolved without a `default` export.",
+          );
+        }
+        state = { status: "ready", component: module.default };
       })
-      .catch((err) => {
+      .catch((err: unknown) => {
         if (!active) return;
-        error = err;
-        loading = false;
+        state = {
+          status: "error",
+          error: err instanceof Error ? err : new Error(String(err)),
+        };
       });
 
     return () => {
@@ -37,11 +44,12 @@
   });
 </script>
 
-{#if loading && fallback}
+{#if state.status === "loading" && fallback}
   {@const Fallback = fallback}
   <Fallback />
-{:else if error}
-  <p>Error loading component: {error.message}</p>
-{:else if LoadedComponent}
+{:else if state.status === "error"}
+  <p>Error loading component: {state.error.message}</p>
+{:else if state.status === "ready"}
+  {@const LoadedComponent = state.component}
   <LoadedComponent />
 {/if}

package/dist/components/Link.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { useIsActiveRoute } from "../composables/useIsActiveRoute.svelte";
   import { useRouter } from "../composables/useRouter.svelte";
+  import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
   import {
     shouldNavigate,
     buildHref,
@@ -12,8 +13,8 @@
 
   let {
     routeName,
-    routeParams = {} as Params,
-    routeOptions = {} as NavigationOptions,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
     class: className = undefined,
     activeClassName = "active",
     activeStrict = false,
@@ -64,7 +65,7 @@
     }
 
     evt.preventDefault();
-    router.navigate(routeName, routeParams, routeOptions).catch(() => {});
+    router.navigate(routeName, routeParams, routeOptions).catch(NOOP);
   }
 </script>
 

package/dist/components/RouteView.svelte

@@ -1,6 +1,26 @@
+<script lang="ts" module>
+  import { startsWithSegment } from "@real-router/route-utils";
+
+  export function getActiveSegment(
+    routeName: string,
+    node: string,
+    snippets: Record<string, unknown>,
+  ): string {
+    const prefix = node ? `${node}.` : "";
+
+    for (const segment in snippets) {
+      if (segment === "notFound") continue;
+      if (startsWithSegment(routeName, prefix + segment)) {
+        return segment;
+      }
+    }
+
+    return "";
+  }
+</script>
+
 <script lang="ts">
   import { UNKNOWN_ROUTE } from "@real-router/core";
-  import { startsWithSegment } from "@real-router/route-utils";
 
   import { useRouteNode } from "../composables/useRouteNode.svelte";
 
@@ -17,29 +37,14 @@
   } = $props();
 
   const routeContext = useRouteNode(nodeName);
-
-  function getActiveSegment(
-    routeName: string,
-    node: string,
-    snippets: Record<string, unknown>,
-  ): string {
-    for (const segment of Object.keys(snippets)) {
-      const fullSegmentName = node ? `${node}.${segment}` : segment;
-
-      if (startsWithSegment(routeName, fullSegmentName)) {
-        return segment;
-      }
-    }
-
-    return "";
-  }
 </script>
 
 {#if routeContext.route.current}
   {@const route = routeContext.route.current}
   {@const segment = getActiveSegment(route.name, nodeName, segmentSnippets)}
-  {#if segment && segmentSnippets[segment]}
-    {@render (segmentSnippets[segment] as Snippet)()}
+  {#if segment}
+    {@const snippet = segmentSnippets[segment] as Snippet}
+    {@render snippet()}
   {:else if route.name === UNKNOWN_ROUTE && notFound}
     {@render notFound()}
   {/if}

package/dist/components/RouteView.svelte.d.ts

@@ -1,3 +1,4 @@
+export declare function getActiveSegment(routeName: string, node: string, snippets: Record<string, unknown>): string;
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     nodeName: string;

package/dist/components/RouterErrorBoundary.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
+  import { createDismissableError } from "@real-router/sources";
   import { untrack } from "svelte";
 
-  import { useRouterError } from "../composables/useRouterError.svelte";
+  import { useRouter } from "../composables/useRouter.svelte";
+  import { createReactiveSource } from "../createReactiveSource.svelte";
 
   import type { RouterError, State } from "@real-router/core";
   import type { Snippet } from "svelte";
@@ -18,30 +20,28 @@
 
   let { children, fallback, onError }: Props = $props();
 
-  const snapshot = useRouterError();
-  let dismissedVersion = $state(-1);
-
-  const visibleError = $derived(
-    snapshot.current.version > dismissedVersion
-      ? snapshot.current.error
-      : null,
-  );
-
-  function resetError(): void {
-    dismissedVersion = snapshot.current.version;
-  }
+  const router = useRouter();
+  const snapshot = createReactiveSource(createDismissableError(router));
 
   $effect(() => {
-    if (snapshot.current.error) {
-      const { error, toRoute, fromRoute } = snapshot.current;
-      untrack(() => {
+    const snap = snapshot.current;
+    if (!snap.error) return;
+
+    const { error, toRoute, fromRoute } = snap;
+    untrack(() => {
+      try {
         onError?.(error, toRoute, fromRoute);
-      });
-    }
+      } catch (callbackError) {
+        console.error(
+          "[real-router] RouterErrorBoundary onError handler threw:",
+          callbackError,
+        );
+      }
+    });
   });
 </script>
 
 {@render children?.()}
-{#if visibleError}
-  {@render fallback(visibleError, resetError)}
+{#if snapshot.current.error}
+  {@render fallback(snapshot.current.error, snapshot.current.resetError)}
 {/if}

package/dist/composables/useIsActiveRoute.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { Params } from "@real-router/core";
-export declare function useIsActiveRoute(routeName: string, params?: Params, strict?: boolean, ignoreQueryParams?: boolean): {
+export declare function useIsActiveRoute(routeName: string, params: Params | undefined, strict: boolean, ignoreQueryParams: boolean): {
     readonly current: boolean;
 };

package/dist/composables/useIsActiveRoute.svelte.js

@@ -1,7 +1,7 @@
 import { createActiveRouteSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
 import { useRouter } from "./useRouter.svelte";
-export function useIsActiveRoute(routeName, params, strict = false, ignoreQueryParams = true) {
+export function useIsActiveRoute(routeName, params, strict, ignoreQueryParams) {
     const router = useRouter();
     const source = createActiveRouteSource(router, routeName, params, {
         strict,

package/dist/composables/useNavigator.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { NAVIGATOR_KEY } from "../context";
-export const useNavigator = () => {
-    const navigator = getContext(NAVIGATOR_KEY);
-    if (!navigator) {
-        throw new Error("useNavigator must be used within a RouterProvider");
-    }
-    return navigator;
-};
+import { NAVIGATOR_KEY, getContextOrThrow } from "../context";
+export const useNavigator = () => getContextOrThrow(NAVIGATOR_KEY, "useNavigator");

package/dist/composables/useRoute.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { ROUTE_KEY } from "../context";
-export const useRoute = () => {
-    const routeContext = getContext(ROUTE_KEY);
-    if (!routeContext) {
-        throw new Error("useRoute must be used within a RouterProvider");
-    }
-    return routeContext;
-};
+import { ROUTE_KEY, getContextOrThrow } from "../context";
+export const useRoute = () => getContextOrThrow(ROUTE_KEY, "useRoute");

package/dist/composables/useRouteNode.svelte.js

@@ -1,27 +1,12 @@
 import { getNavigator } from "@real-router/core";
 import { createRouteNodeSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
+import { createRouteContext } from "../createRouteContext.svelte";
 import { useRouter } from "./useRouter.svelte";
 export function useRouteNode(nodeName) {
     const router = useRouter();
     const navigator = getNavigator(router);
     const source = createRouteNodeSource(router, nodeName);
     const reactive = createReactiveSource(source);
-    return {
-        navigator,
-        get route() {
-            return {
-                get current() {
-                    return reactive.current.route;
-                },
-            };
-        },
-        get previousRoute() {
-            return {
-                get current() {
-                    return reactive.current.previousRoute;
-                },
-            };
-        },
-    };
+    return createRouteContext(navigator, reactive);
 }

package/dist/composables/useRouter.svelte.js

@@ -1,9 +1,2 @@
-import { getContext } from "svelte";
-import { ROUTER_KEY } from "../context";
-export const useRouter = () => {
-    const router = getContext(ROUTER_KEY);
-    if (!router) {
-        throw new Error("useRouter must be used within a RouterProvider");
-    }
-    return router;
-};
+import { ROUTER_KEY, getContextOrThrow } from "../context";
+export const useRouter = () => getContextOrThrow(ROUTER_KEY, "useRouter");

package/dist/composables/useRouterTransition.svelte.js

@@ -1,8 +1,8 @@
-import { createTransitionSource } from "@real-router/sources";
+import { getTransitionSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
 import { useRouter } from "./useRouter.svelte";
 export function useRouterTransition() {
     const router = useRouter();
-    const source = createTransitionSource(router);
+    const source = getTransitionSource(router);
     return createReactiveSource(source);
 }

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+import type { NavigationOptions, Params } from "@real-router/core";
+export declare const EMPTY_PARAMS: Params;
+export declare const EMPTY_OPTIONS: NavigationOptions;
+export declare const NOOP: () => void;

package/dist/constants.js

@@ -0,0 +1,3 @@
+export const EMPTY_PARAMS = Object.freeze({});
+export const EMPTY_OPTIONS = Object.freeze({});
+export const NOOP = () => { };

package/dist/context.d.ts

@@ -1,3 +1,4 @@
 export declare const ROUTER_KEY = "real-router:router";
 export declare const NAVIGATOR_KEY = "real-router:navigator";
 export declare const ROUTE_KEY = "real-router:route";
+export declare function getContextOrThrow<T>(key: string, consumerName: string): T;

package/dist/context.js

@@ -1,3 +1,16 @@
+import { getContext } from "svelte";
 export const ROUTER_KEY = "real-router:router";
 export const NAVIGATOR_KEY = "real-router:navigator";
 export const ROUTE_KEY = "real-router:route";
+// The type parameter is used by the caller to narrow the return type.
+// ESLint's no-unnecessary-type-parameters sees only a single textual use of T
+// (the return type) — but each call site supplies a different T, so it is not
+// unnecessary. Inline generic helpers are a standard pattern for typed context.
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function getContextOrThrow(key, consumerName) {
+    const value = getContext(key);
+    if (!value) {
+        throw new Error(`${consumerName} must be used within a RouterProvider`);
+    }
+    return value;
+}

package/dist/createRouteContext.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Navigator, State } from "@real-router/core";
+import type { RouteContext } from "./types";
+export interface RouteSnapshot {
+    readonly route: State | undefined;
+    readonly previousRoute: State | undefined;
+}
+export declare function createRouteContext(navigator: Navigator, reactive: {
+    readonly current: RouteSnapshot;
+}): RouteContext;

package/dist/createRouteContext.svelte.js

@@ -0,0 +1,13 @@
+export function createRouteContext(navigator, reactive) {
+    const route = {
+        get current() {
+            return reactive.current.route;
+        },
+    };
+    const previousRoute = {
+        get current() {
+            return reactive.current.previousRoute;
+        },
+    };
+    return { navigator, route, previousRoute };
+}

package/dist/dom-utils/index.d.ts

@@ -1,3 +1,3 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
-export { shouldNavigate, buildHref, buildActiveClassName, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";

package/dist/dom-utils/index.js

@@ -1,2 +1,2 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
-export { shouldNavigate, buildHref, buildActiveClassName, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";

package/dist/dom-utils/link-utils.d.ts

@@ -2,4 +2,5 @@ import type { Router, Params } from "@real-router/core";
 export declare function shouldNavigate(evt: MouseEvent): boolean;
 export declare function buildHref(router: Router, routeName: string, routeParams: Params): string | undefined;
 export declare function buildActiveClassName(isActive: boolean, activeClassName: string | undefined, baseClassName: string | undefined): string | undefined;
-export declare function applyLinkA11y(element: HTMLElement): void;
+export declare function shallowEqual(prev: object | undefined, next: object | undefined): boolean;
+export declare function applyLinkA11y(element: HTMLElement | null | undefined): void;

package/dist/dom-utils/link-utils.js

@@ -9,7 +9,10 @@ export function buildHref(router, routeName, routeParams) {
     try {
         const buildUrl = router.buildUrl;
         if (buildUrl) {
-            return buildUrl(routeName, routeParams);
+            const url = buildUrl(routeName, routeParams);
+            if (url !== undefined) {
+                return url;
+            }
         }
         return router.buildPath(routeName, routeParams);
     }
@@ -18,23 +21,62 @@ export function buildHref(router, routeName, routeParams) {
         return undefined;
     }
 }
+function parseTokens(value) {
+    return value ? (value.match(/\S+/g) ?? []) : [];
+}
 export function buildActiveClassName(isActive, activeClassName, baseClassName) {
     if (isActive && activeClassName) {
-        return baseClassName
-            ? `${baseClassName} ${activeClassName}`.trim()
-            : activeClassName;
+        const activeTokens = parseTokens(activeClassName);
+        if (activeTokens.length === 0) {
+            return baseClassName ?? undefined;
+        }
+        if (!baseClassName) {
+            return activeTokens.join(" ");
+        }
+        const baseTokens = parseTokens(baseClassName);
+        const seen = new Set(baseTokens);
+        for (const token of activeTokens) {
+            if (!seen.has(token)) {
+                seen.add(token);
+                baseTokens.push(token);
+            }
+        }
+        return baseTokens.join(" ");
     }
     return baseClassName ?? undefined;
 }
+export function shallowEqual(prev, next) {
+    if (Object.is(prev, next)) {
+        return true;
+    }
+    if (!prev || !next) {
+        return false;
+    }
+    const prevKeys = Object.keys(prev);
+    if (prevKeys.length !== Object.keys(next).length) {
+        return false;
+    }
+    const prevRecord = prev;
+    const nextRecord = next;
+    for (const key of prevKeys) {
+        if (!Object.is(prevRecord[key], nextRecord[key])) {
+            return false;
+        }
+    }
+    return true;
+}
 export function applyLinkA11y(element) {
+    if (!element) {
+        return;
+    }
     if (element instanceof HTMLAnchorElement ||
         element instanceof HTMLButtonElement) {
         return;
     }
-    if (!element.getAttribute("role")) {
+    if (!element.hasAttribute("role")) {
         element.setAttribute("role", "link");
     }
-    if (!element.getAttribute("tabindex")) {
+    if (!element.hasAttribute("tabindex")) {
         element.setAttribute("tabindex", "0");
     }
 }