@real-router/svelte 0.2.13 → 0.3.1

package/dist/dom-utils/route-announcer.js

@@ -10,32 +10,57 @@ export function createRouteAnnouncer(router, options) {
     let isReady = false;
     let isDestroyed = false;
     let lastAnnouncedText = "";
+    let pendingText = null;
     let clearTimeoutId;
     const announcer = getOrCreateAnnouncer();
+    const doAnnounce = (text, h1) => {
+        lastAnnouncedText = text;
+        clearTimeout(clearTimeoutId);
+        announcer.textContent = text;
+        clearTimeoutId = setTimeout(() => {
+            announcer.textContent = "";
+            lastAnnouncedText = "";
+        }, CLEAR_DELAY);
+        manageFocus(h1);
+    };
+    // Safari-ready delay: announcing before VoiceOver wires up the aria-live region
+    // causes the first announcement to be silently dropped. Wait SAFARI_READY_DELAY ms
+    // before marking the announcer "ready" — any navigation during that window is
+    // buffered in pendingText and flushed once the delay expires.
     const safariTimeoutId = setTimeout(() => {
         isReady = true;
+        if (pendingText !== null && !isDestroyed) {
+            const text = pendingText;
+            pendingText = null;
+            doAnnounce(text, document.querySelector("h1"));
+        }
     }, SAFARI_READY_DELAY);
     const unsubscribe = router.subscribe(({ route }) => {
         if (isInitialNavigation) {
             isInitialNavigation = false;
             return;
         }
+        // Double rAF: waits for two paint frames so the incoming route's DOM
+        // (including the new <h1>) is fully rendered before resolveText reads it.
+        // Single rAF fires before the new route's template has been attached,
+        // which would cause resolveText to pick up the OLD h1 or fall back to
+        // document.title / route.name prematurely.
         requestAnimationFrame(() => {
             requestAnimationFrame(() => {
                 if (isDestroyed) {
                     return;
                 }
-                const text = resolveText(route, prefix, getCustomText);
-                if (text && text !== lastAnnouncedText && isReady) {
-                    lastAnnouncedText = text;
-                    clearTimeout(clearTimeoutId);
-                    announcer.textContent = text;
-                    clearTimeoutId = setTimeout(() => {
-                        announcer.textContent = "";
-                        lastAnnouncedText = "";
-                    }, CLEAR_DELAY);
-                    manageFocus();
+                const h1 = document.querySelector("h1");
+                const text = resolveText(route, prefix, getCustomText, h1);
+                if (!text || text === lastAnnouncedText) {
+                    return;
+                }
+                if (!isReady) {
+                    // Defer announcement until Safari-ready window elapses (see safariTimeoutId).
+                    pendingText = text;
+                    return;
                 }
+                doAnnounce(text, h1);
             });
         });
     });
@@ -65,11 +90,10 @@ function getOrCreateAnnouncer() {
 function removeAnnouncer() {
     document.querySelector(`[${ANNOUNCER_ATTR}]`)?.remove();
 }
-function resolveText(route, prefix, getCustomText) {
+function resolveText(route, prefix, getCustomText, h1) {
     if (getCustomText) {
         return getCustomText(route);
     }
-    const h1 = document.querySelector("h1");
     const h1Text = h1?.textContent.trim() ?? "";
     const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
         ? ""
@@ -77,8 +101,7 @@ function resolveText(route, prefix, getCustomText) {
     const rawText = h1Text || document.title || routeName || globalThis.location.pathname;
     return `${prefix}${rawText}`;
 }
-function manageFocus() {
-    const h1 = document.querySelector("h1");
+function manageFocus(h1) {
     if (!h1) {
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.2.13",
+  "version": "0.3.1",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -46,7 +46,7 @@
   "dependencies": {
     "@real-router/core": "^0.48.0",
     "@real-router/route-utils": "^0.2.1",
-    "@real-router/sources": "^0.5.1"
+    "@real-router/sources": "^0.6.0"
   },
   "devDependencies": {
     "@sveltejs/package": "2.5.7",
@@ -58,17 +58,17 @@
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.12.1"
+    "@real-router/browser-plugin": "^0.13.0"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"
   },
   "scripts": {
-    "build": "svelte-package -i src -o dist",
     "test": "vitest",
     "test:properties": "vitest run --config vitest.config.properties.mts",
     "test:stress": "vitest run --config vitest.config.stress.mts",
     "type-check": "svelte-check --tsconfig ./tsconfig.json",
-    "lint": "eslint --cache src/ tests/ --fix --max-warnings 0"
+    "lint": "eslint --cache src/ tests/ --fix --max-warnings 0",
+    "bundle": "svelte-package -i src -o dist"
   }
 }

package/src/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/src/actions/link.svelte.ts

@@ -1,7 +1,7 @@
-import { getContext } from "svelte";
 import type { ActionReturn } from "svelte/action";
 import type { Router, Params, NavigationOptions } from "@real-router/core";
-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";
 
 export interface LinkActionParams {
@@ -10,6 +10,11 @@ export interface LinkActionParams {
   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).
@@ -28,15 +33,8 @@ export interface LinkActionParams {
  * <a use:link={{ name: 'users', params: { id: '123' } }}>User Profile</a>
  * ```
  */
-export function createLinkAction(): (
-  node: HTMLElement,
-  params: LinkActionParams,
-) => ActionReturn<LinkActionParams> {
-  const router = getContext<Router | undefined>(ROUTER_KEY);
-
-  if (!router) {
-    throw new Error("createLinkAction must be called inside a RouterProvider");
-  }
+export function createLinkAction(): LinkAction {
+  const router = getContextOrThrow<Router>(ROUTER_KEY, "createLinkAction");
 
   return function link(
     node: HTMLElement,
@@ -46,31 +44,31 @@ export function createLinkAction(): (
 
     applyLinkA11y(node);
 
-    function handleClick(evt: MouseEvent) {
-      if (!shouldNavigate(evt)) return;
-      evt.preventDefault();
-      // router is guaranteed to exist due to check in factory
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      router!
+    function navigate() {
+      router
         .navigate(
           currentParams.name,
-          currentParams.params ?? {},
-          currentParams.options ?? {},
+          currentParams.params ?? EMPTY_PARAMS,
+          currentParams.options ?? EMPTY_OPTIONS,
         )
-        .catch(() => {});
+        .catch(NOOP);
+    }
+
+    function handleClick(evt: MouseEvent) {
+      if (!shouldNavigate(evt)) return;
+      if (
+        node instanceof HTMLAnchorElement &&
+        node.getAttribute("target") === "_blank"
+      ) {
+        return;
+      }
+      evt.preventDefault();
+      navigate();
     }
 
     function handleKeyDown(evt: KeyboardEvent) {
       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();
       }
     }
 

package/src/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/src/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/src/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/src/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/src/composables/useIsActiveRoute.svelte.ts

@@ -7,9 +7,9 @@ import type { Params } from "@real-router/core";
 
 export function useIsActiveRoute(
   routeName: string,
-  params?: Params,
-  strict = false,
-  ignoreQueryParams = true,
+  params: Params | undefined,
+  strict: boolean,
+  ignoreQueryParams: boolean,
 ): { readonly current: boolean } {
   const router = useRouter();
 

package/src/composables/useNavigator.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { NAVIGATOR_KEY } from "../context";
+import { NAVIGATOR_KEY, getContextOrThrow } from "../context";
 
 import type { Navigator } from "@real-router/core";
 
-export const useNavigator = (): Navigator => {
-  const navigator = getContext<Navigator | undefined>(NAVIGATOR_KEY);
-
-  if (!navigator) {
-    throw new Error("useNavigator must be used within a RouterProvider");
-  }
-
-  return navigator;
-};
+export const useNavigator = (): Navigator =>
+  getContextOrThrow<Navigator>(NAVIGATOR_KEY, "useNavigator");

package/src/composables/useRoute.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { ROUTE_KEY } from "../context";
+import { ROUTE_KEY, getContextOrThrow } from "../context";
 
 import type { RouteContext } from "../types";
 
-export const useRoute = (): RouteContext => {
-  const routeContext = getContext<RouteContext | undefined>(ROUTE_KEY);
-
-  if (!routeContext) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
-
-  return routeContext;
-};
+export const useRoute = (): RouteContext =>
+  getContextOrThrow<RouteContext>(ROUTE_KEY, "useRoute");

package/src/composables/useRouteNode.svelte.ts

@@ -2,6 +2,7 @@ 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";
 
 import type { RouteContext } from "../types";
@@ -13,21 +14,5 @@ export function useRouteNode(nodeName: string): RouteContext {
   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/src/composables/useRouter.svelte.ts

@@ -1,15 +1,6 @@
-import { getContext } from "svelte";
-
-import { ROUTER_KEY } from "../context";
+import { ROUTER_KEY, getContextOrThrow } from "../context";
 
 import type { Router } from "@real-router/core";
 
-export const useRouter = (): Router => {
-  const router = getContext<Router | undefined>(ROUTER_KEY);
-
-  if (!router) {
-    throw new Error("useRouter must be used within a RouterProvider");
-  }
-
-  return router;
-};
+export const useRouter = (): Router =>
+  getContextOrThrow<Router>(ROUTER_KEY, "useRouter");

package/src/composables/useRouterTransition.svelte.ts

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

package/src/constants.ts

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

package/src/context.ts

@@ -1,5 +1,22 @@
+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<T>(key: string, consumerName: string): T {
+  const value = getContext<T | undefined>(key);
+
+  if (!value) {
+    throw new Error(`${consumerName} must be used within a RouterProvider`);
+  }
+
+  return value;
+}

package/src/createRouteContext.svelte.ts

@@ -0,0 +1,27 @@
+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 function createRouteContext(
+  navigator: Navigator,
+  reactive: { readonly current: RouteSnapshot },
+): RouteContext {
+  const route = {
+    get current(): State | undefined {
+      return reactive.current.route;
+    },
+  };
+
+  const previousRoute = {
+    get current(): State | undefined {
+      return reactive.current.previousRoute;
+    },
+  };
+
+  return { navigator, route, previousRoute };
+}

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

@@ -1,4 +0,0 @@
-import type { RouterErrorSnapshot } from "@real-router/sources";
-export declare function useRouterError(): {
-    readonly current: RouterErrorSnapshot;
-};

package/dist/composables/useRouterError.svelte.js

@@ -1,13 +0,0 @@
-import { createErrorSource } from "@real-router/sources";
-import { createReactiveSource } from "../createReactiveSource.svelte";
-import { useRouter } from "./useRouter.svelte";
-const cache = new WeakMap();
-export function useRouterError() {
-    const router = useRouter();
-    let source = cache.get(router);
-    if (!source) {
-        source = createErrorSource(router);
-        cache.set(router, source);
-    }
-    return createReactiveSource(source);
-}