@real-router/svelte 0.1.1 → 0.2.0

package/README.md

@@ -196,6 +196,30 @@ Snippet names must be valid JavaScript identifiers and match the first segment o
 
 > **Note:** `keepAlive` is not supported. Svelte has no equivalent of React's `<Activity>` API or Vue's `<KeepAlive>`. Components are destroyed when navigating away.
 
+### `<RouterErrorBoundary>`
+
+Declarative error handling for navigation errors. Shows a fallback **alongside** children (not instead of) when a guard rejects or a route is not found.
+
+```svelte
+<script lang="ts">
+  import { RouterErrorBoundary } from "@real-router/svelte";
+</script>
+
+<RouterErrorBoundary
+  onError={(error) => analytics.track("nav_error", { code: error.code })}
+>
+  {#snippet fallback(error, resetError)}
+    <div class="toast">
+      {error.code} <button onclick={resetError}>Dismiss</button>
+    </div>
+  {/snippet}
+
+  <Link routeName="protected">Go to Protected</Link>
+</RouterErrorBoundary>
+```
+
+Auto-resets on next successful navigation. Works with both `<Link>` and imperative `router.navigate()`.
+
 ## Actions
 
 ### `createLinkAction`
@@ -334,7 +358,7 @@ When enabled, a visually hidden `aria-live` region announces each navigation. Fo
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [Link](https://github.com/greydragon888/real-router/wiki/Link)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link)
 - [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition)
 
 ## Examples

package/dist/components/RouterErrorBoundary.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { untrack } from "svelte";
+
+  import { useRouterError } from "../composables/useRouterError.svelte";
+
+  import type { RouterError, State } from "@real-router/core";
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    children: Snippet;
+    fallback: Snippet<[RouterError, () => void]>;
+    onError?: (
+      error: RouterError,
+      toRoute: State | null,
+      fromRoute: State | null,
+    ) => void;
+  }
+
+  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;
+  }
+
+  $effect(() => {
+    if (snapshot.current.error) {
+      const { error, toRoute, fromRoute } = snapshot.current;
+      untrack(() => {
+        onError?.(error, toRoute, fromRoute);
+      });
+    }
+  });
+</script>
+
+{@render children?.()}
+{#if visibleError}
+  {@render fallback(visibleError, resetError)}
+{/if}

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

@@ -0,0 +1,10 @@
+import type { RouterError, State } from "@real-router/core";
+import type { Snippet } from "svelte";
+interface Props {
+    children: Snippet;
+    fallback: Snippet<[RouterError, () => void]>;
+    onError?: (error: RouterError, toRoute: State | null, fromRoute: State | null) => void;
+}
+declare const RouterErrorBoundary: import("svelte").Component<Props, {}, "">;
+type RouterErrorBoundary = ReturnType<typeof RouterErrorBoundary>;
+export default RouterErrorBoundary;

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

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

package/dist/composables/useRouterError.svelte.js

@@ -0,0 +1,13 @@
+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);
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { default as RouteView } from "./components/RouteView.svelte";
 export { default as Link } from "./components/Link.svelte";
 export { default as Lazy } from "./components/Lazy.svelte";
+export { default as RouterErrorBoundary } from "./components/RouterErrorBoundary.svelte";
 export { createReactiveSource } from "./createReactiveSource.svelte";
 export { useRouter } from "./composables/useRouter.svelte";
 export { useNavigator } from "./composables/useNavigator.svelte";
@@ -14,4 +15,4 @@ export { default as RouterProvider } from "./RouterProvider.svelte";
 export { ROUTER_KEY, NAVIGATOR_KEY, ROUTE_KEY } from "./context";
 export type { LinkProps, RouteContext } from "./types";
 export type { Navigator } from "@real-router/core";
-export type { RouterTransitionSnapshot } from "@real-router/sources";
+export type { RouterTransitionSnapshot, RouterErrorSnapshot, } from "@real-router/sources";

package/dist/index.js

@@ -2,6 +2,7 @@
 export { default as RouteView } from "./components/RouteView.svelte";
 export { default as Link } from "./components/Link.svelte";
 export { default as Lazy } from "./components/Lazy.svelte";
+export { default as RouterErrorBoundary } from "./components/RouterErrorBoundary.svelte";
 // Reactive Primitives
 export { createReactiveSource } from "./createReactiveSource.svelte";
 // Composables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -44,10 +44,10 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.39.0",
+    "@real-router/core": "^0.40.1",
     "@real-router/route-utils": "^0.1.6",
-    "@real-router/sources": "^0.2.6",
-    "dom-utils": "^0.2.1"
+    "@real-router/sources": "^0.3.0",
+    "dom-utils": "^0.2.2"
   },
   "devDependencies": {
     "@sveltejs/package": "2.5.7",
@@ -59,7 +59,7 @@
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.10.4"
+    "@real-router/browser-plugin": "^0.10.6"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"
@@ -69,6 +69,7 @@
     "test": "vitest",
     "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",
+    "build:dist-only": "svelte-package -i src -o dist"
   }
 }

package/src/components/RouterErrorBoundary.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { untrack } from "svelte";
+
+  import { useRouterError } from "../composables/useRouterError.svelte";
+
+  import type { RouterError, State } from "@real-router/core";
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    children: Snippet;
+    fallback: Snippet<[RouterError, () => void]>;
+    onError?: (
+      error: RouterError,
+      toRoute: State | null,
+      fromRoute: State | null,
+    ) => void;
+  }
+
+  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;
+  }
+
+  $effect(() => {
+    if (snapshot.current.error) {
+      const { error, toRoute, fromRoute } = snapshot.current;
+      untrack(() => {
+        onError?.(error, toRoute, fromRoute);
+      });
+    }
+  });
+</script>
+
+{@render children?.()}
+{#if visibleError}
+  {@render fallback(visibleError, resetError)}
+{/if}

package/src/composables/useRouterError.svelte.ts

@@ -0,0 +1,21 @@
+import { createErrorSource } from "@real-router/sources";
+
+import { createReactiveSource } from "../createReactiveSource.svelte";
+import { useRouter } from "./useRouter.svelte";
+
+import type { Router } from "@real-router/core";
+import type { RouterErrorSnapshot, RouterSource } from "@real-router/sources";
+
+const cache = new WeakMap<Router, RouterSource<RouterErrorSnapshot>>();
+
+export function useRouterError(): { readonly current: RouterErrorSnapshot } {
+  const router = useRouter();
+
+  let source = cache.get(router);
+  if (!source) {
+    source = createErrorSource(router);
+    cache.set(router, source);
+  }
+
+  return createReactiveSource(source);
+}

package/src/index.ts

@@ -5,6 +5,8 @@ export { default as Link } from "./components/Link.svelte";
 
 export { default as Lazy } from "./components/Lazy.svelte";
 
+export { default as RouterErrorBoundary } from "./components/RouterErrorBoundary.svelte";
+
 // Reactive Primitives
 export { createReactiveSource } from "./createReactiveSource.svelte";
 
@@ -36,4 +38,7 @@ export type { LinkProps, RouteContext } from "./types";
 
 export type { Navigator } from "@real-router/core";
 
-export type { RouterTransitionSnapshot } from "@real-router/sources";
+export type {
+  RouterTransitionSnapshot,
+  RouterErrorSnapshot,
+} from "@real-router/sources";