@real-router/svelte 0.13.1 → 0.13.3

package/src/components/Link.svelte

@@ -1,95 +0,0 @@
-<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,
-    buildActiveClassName,
-    navigateWithHash,
-  } from "../dom-utils";
-
-  import type { NavigationOptions, Params } from "@real-router/core";
-  import type { Snippet } from "svelte";
-
-  let {
-    routeName,
-    routeParams = EMPTY_PARAMS,
-    routeOptions = EMPTY_OPTIONS,
-    class: className = undefined,
-    activeClassName = "active",
-    activeStrict = false,
-    ignoreQueryParams = true,
-    hash = undefined,
-    target = undefined,
-    children = undefined,
-    onclick: userOnClick = undefined,
-    ...restProps
-  }: {
-    routeName: string;
-    routeParams?: Params;
-    routeOptions?: NavigationOptions;
-    class?: string;
-    activeClassName?: string;
-    activeStrict?: boolean;
-    ignoreQueryParams?: boolean;
-    /**
-     * URL fragment (decoded form, no leading "#") (#532).
-     * - omitted/`undefined` → preserve current fragment on same-route navigation
-     * - `""` → clear fragment
-     * - non-empty → set fragment
-     */
-    hash?: string;
-    target?: string;
-    children?: Snippet;
-    onclick?: (evt: MouseEvent) => void;
-    [key: string]: unknown;
-  } = $props();
-
-  const router = useRouter();
-  // Hash-aware active (#532): tab links sharing routeName but differing in
-  // hash should only light up the matching variant.
-  const activeState = useIsActiveRoute(
-    routeName,
-    routeParams,
-    activeStrict,
-    ignoreQueryParams,
-    hash,
-  );
-
-  const href = $derived(
-    buildHref(
-      router,
-      routeName,
-      routeParams,
-      hash !== undefined ? { hash } : undefined,
-    ),
-  );
-
-  const finalClassName = $derived(
-    buildActiveClassName(activeState.current, activeClassName, className),
-  );
-
-  function handleClick(evt: MouseEvent) {
-    if (userOnClick) {
-      userOnClick(evt);
-
-      if (evt.defaultPrevented) {
-        return;
-      }
-    }
-
-    if (!shouldNavigate(evt) || target === "_blank") {
-      return;
-    }
-
-    evt.preventDefault();
-    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(
-      NOOP,
-    );
-  }
-</script>
-
-<a {href} class={finalClassName} {target} onclick={handleClick} {...restProps}>
-  {@render children?.()}
-</a>

package/src/components/RouteView.helpers.ts

@@ -1,24 +0,0 @@
-import { startsWithSegment } from "@real-router/route-utils";
-
-// Snippet names reserved by RouteView for non-segment slots. Iteration in
-// `getActiveSegment` skips these so they don't accidentally match a route.
-const RESERVED_SLOT_NAMES = new Set(["self", "notFound"]);
-
-export function getActiveSegment(
-  routeName: string,
-  node: string,
-  snippets: Record<string, unknown>,
-): string {
-  const prefix = node ? `${node}.` : "";
-
-  for (const segment in snippets) {
-    if (RESERVED_SLOT_NAMES.has(segment)) {
-      continue;
-    }
-    if (startsWithSegment(routeName, prefix + segment)) {
-      return segment;
-    }
-  }
-
-  return "";
-}

package/src/components/RouteView.svelte

@@ -1,35 +0,0 @@
-<script lang="ts">
-  import { UNKNOWN_ROUTE } from "@real-router/core";
-
-  import { useRouteNode } from "../composables/useRouteNode.svelte";
-  import { getActiveSegment } from "./RouteView.helpers";
-
-  import type { Snippet } from "svelte";
-
-  let {
-    nodeName,
-    self,
-    notFound,
-    ...segmentSnippets
-  }: {
-    nodeName: string;
-    self?: Snippet;
-    notFound?: Snippet;
-    [key: string]: Snippet | string | undefined;
-  } = $props();
-
-  const routeContext = useRouteNode(nodeName);
-</script>
-
-{#if routeContext.route.current}
-  {@const route = routeContext.route.current}
-  {@const segment = getActiveSegment(route.name, nodeName, segmentSnippets)}
-  {#if segment}
-    {@const snippet = segmentSnippets[segment] as Snippet}
-    {@render snippet()}
-  {:else if self && route.name === nodeName}
-    {@render self()}
-  {:else if route.name === UNKNOWN_ROUTE && notFound}
-    {@render notFound()}
-  {/if}
-{/if}

package/src/components/RouterErrorBoundary.svelte

@@ -1,47 +0,0 @@
-<script lang="ts">
-  import { createDismissableError } from "@real-router/sources";
-  import { untrack } from "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";
-
-  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 router = useRouter();
-  const snapshot = createReactiveSource(createDismissableError(router));
-
-  $effect(() => {
-    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 snapshot.current.error}
-  {@render fallback(snapshot.current.error, snapshot.current.resetError)}
-{/if}

package/src/components/ServerOnly.svelte

@@ -1,22 +0,0 @@
-<script lang="ts">
-  import type { Snippet } from "svelte";
-
-  interface Props {
-    children: Snippet;
-    fallback?: Snippet;
-  }
-
-  let { children, fallback }: Props = $props();
-
-  let mounted = $state(false);
-
-  $effect(() => {
-    mounted = true;
-  });
-</script>
-
-{#if !mounted}
-  {@render children()}
-{:else if fallback}
-  {@render fallback()}
-{/if}

package/src/components/Streamed.svelte

@@ -1,37 +0,0 @@
-<!--
-  @component
-  Cross-adapter alias for Svelte's `{#await}` boundary. Renders the `fallback`
-  snippet while a `pending` Promise prop is unresolved, then `children` (with
-  the resolved value) once it settles. Symmetric naming with the
-  React/Preact/Solid/Vue/Angular `<Streamed>` components — pick `<Streamed>`
-  for cross-framework consistency, or use `{#await}` directly when team
-  conventions prefer that.
-
-  Svelte 5 has **no progressive HTTP-flush** in SSR (one TCP frame, late-
-  resolving promises ship in the final body) — the `{#await}` block on the
-  client retains its native streaming-after-hydration semantics. See
-  `examples/web/svelte/ssr-examples/ssr-streaming/README.md` for the
-  end-to-end story.
--->
-<script lang="ts" generics="T">
-  import type { Snippet } from "svelte";
-
-  interface Props {
-    /** Promise to await — typically `useDeferred(key)`. */
-    pending: Promise<T>;
-    /** Render snippet for the resolved value. */
-    children: Snippet<[T]>;
-    /** Snippet shown while the promise is pending. */
-    fallback?: Snippet;
-  }
-
-  let { pending, children, fallback }: Props = $props();
-</script>
-
-{#await pending}
-  {#if fallback}
-    {@render fallback()}
-  {/if}
-{:then value}
-  {@render children(value)}
-{/await}

package/src/composables/useDeferred.svelte.ts

@@ -1,41 +0,0 @@
-import { useRoute } from "./useRoute.svelte";
-
-interface DeferredContext {
-  ssrDataDeferred?: Record<string, Promise<unknown>>;
-}
-
-const NEVER_PROMISE = new Promise<never>(() => {
-  // Intentionally never resolves — surfaces a forever-pending {#await} block
-  // when a key is requested that the loader never declared.
-});
-
-/**
- * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
- * inside an SSR data loader. Returns the Promise — feed straight into Svelte's
- * native `{#await}` block, or use `<Await name="key">` (this package) for the
- * cross-adapter shape.
- *
- * ```svelte
- * <script>
- *   import { useDeferred } from "@real-router/svelte/ssr";
- *   const reviewsPromise = useDeferred("reviews");
- * </script>
- *
- * {#await reviewsPromise}
- *   <Spinner />
- * {:then reviews}
- *   <ReviewList items={reviews} />
- * {/await}
- * ```
- *
- * Returns a forever-pending promise when the key is missing — surfaces
- * loader/consumer key drift as a visible {#await} loading state rather than
- * a silent runtime error.
- */
-export function useDeferred<T = unknown>(key: string): Promise<T> {
-  const { route } = useRoute();
-  const context = route.current.context as DeferredContext;
-  const deferred = context.ssrDataDeferred;
-
-  return (deferred?.[key] ?? NEVER_PROMISE) as Promise<T>;
-}

package/src/composables/useIsActiveRoute.svelte.ts

@@ -1,30 +0,0 @@
-import { createActiveRouteSource } from "@real-router/sources";
-
-import { createReactiveSource } from "../createReactiveSource.svelte";
-import { useRouter } from "./useRouter.svelte";
-
-import type { Params } from "@real-router/core";
-
-export function useIsActiveRoute(
-  routeName: string,
-  params: Params | undefined,
-  strict: boolean,
-  ignoreQueryParams: boolean,
-  hash?: string,
-) {
-  const router = useRouter();
-
-  // The `hash` argument (#532) participates in the cache key when defined.
-  // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — we
-  // conditionally include the key only when a value is provided.
-  const source = createActiveRouteSource(
-    router,
-    routeName,
-    params,
-    hash === undefined
-      ? { strict, ignoreQueryParams }
-      : { strict, ignoreQueryParams, hash },
-  );
-
-  return createReactiveSource(source);
-}

package/src/composables/useNavigator.svelte.ts

@@ -1,6 +0,0 @@
-import { NAVIGATOR_KEY, getContextOrThrow } from "../context";
-
-import type { Navigator } from "@real-router/core";
-
-export const useNavigator = (): Navigator =>
-  getContextOrThrow<Navigator>(NAVIGATOR_KEY, "useNavigator");

package/src/composables/useRoute.svelte.ts

@@ -1,25 +0,0 @@
-import { ROUTE_KEY, getContextOrThrow } from "../context";
-
-import type { RouteContext } from "../types";
-import type { Params, State } from "@real-router/core";
-
-/**
- * `useRoute()`'s return type: same shape as `RouteContext<P>` but with
- * `route.current` narrowed to non-nullable `State<P>` (the composable's
- * `if (!ctx.route.current) throw` guard makes this safe).
- */
-type ActiveRouteContext<P extends Params> = Omit<RouteContext<P>, "route"> & {
-  route: { readonly current: State<P> };
-};
-
-export const useRoute = <P extends Params = Params>(): ActiveRouteContext<P> => {
-  const ctx = getContextOrThrow<RouteContext>(ROUTE_KEY, "useRoute");
-
-  if (!ctx.route.current) {
-    throw new Error(
-      "useRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?",
-    );
-  }
-
-  return ctx as ActiveRouteContext<P>;
-};

package/src/composables/useRouteEnter.svelte.ts

@@ -1,120 +0,0 @@
-import { useRoute } from "./useRoute.svelte";
-
-import type { State } from "@real-router/core";
-
-export interface RouteEnterContext {
-  /** The route that was just activated. */
-  route: State;
-  /** The route that was active immediately before this navigation. */
-  previousRoute: State;
-}
-
-export type RouteEnterHandler = (context: RouteEnterContext) => void;
-
-export interface UseRouteEnterOptions {
-  /**
-   * Skip the handler when `route.name === previousRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`. Symmetric with `useRouteExit`'s same-name option.
-   */
-  skipSameRoute?: boolean;
-}
-
-/**
- * Fire `handler` once when the component mounts as a result of a
- * navigation. Mirror of `useRouteExit` for the entry side.
- *
- * What this composable covers that an ad-hoc `$effect` + `useRoute()`
- * doesn't:
- *
- *   - **Skip-initial**: handler is skipped when there is no
- *     `route.transition.from` (i.e. first-load mount). Most consumers
- *     want to fire side effects only on real navigations, not on
- *     hydration.
- *   - **Same-route skip** (default): handler is skipped when
- *     `route.transition.from === route.name`. Sort/filter/query-only
- *     navigations re-run the effect (because the `route` reference
- *     changes), but they are not "entries" in the animation / analytics
- *     sense. Opt out with `skipSameRoute: false`.
- *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
- *     the values that were live at the moment of effect activation.
- *
- * **Handler reactivity (Svelte):** Svelte composables run **once** at
- * component init; `handler` is captured in closure at the call site. To
- * vary behavior over time, read `$state` / `$derived` values inside the
- * handler body.
- *
- * @example Direction-aware entry animation
- * ```svelte
- * <script lang="ts">
- *   import { useRouteEnter } from "@real-router/svelte";
- *   let el: HTMLDivElement;
- *
- *   useRouteEnter(({ route }) => {
- *     const direction = route.context.browser?.direction;
- *     el?.classList.add(
- *       direction === "back" ? "slide-from-left" : "slide-from-right",
- *     );
- *   });
- * </script>
- * ```
- *
- * @example Analytics page-enter event (skip-initial built-in)
- * ```svelte
- * <script lang="ts">
- *   useRouteEnter(({ route, previousRoute }) => {
- *     analytics.track("page_enter", {
- *       route: route.name,
- *       from: previousRoute.name,
- *     });
- *   });
- * </script>
- * ```
- */
-export function useRouteEnter(
-  handler: RouteEnterHandler,
-  options?: UseRouteEnterOptions,
-): void {
-  const { route, previousRoute } = useRoute();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-  let lastHandledRoute: State | null = null;
-
-  $effect(() => {
-    const currentRoute = route.current;
-    const prev = previousRoute.current;
-
-    // Early-exit guards, top-down:
-    //
-    //   - **Defensive**: `route.current` may be undefined during SSR or
-    //     pre-start hydration. Not testable from vitest, v8-ignored.
-    //   - **Skip-initial**: `state.transition.from` is undefined only
-    //     for the very first state committed by `router.start()`.
-    //   - **Skip-same-route**: query-only navigations have
-    //     `transition.from === route.name`. Opt-out via
-    //     `skipSameRoute: false`.
-    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
-    //     ref between `$effect` re-runs is unexpected (createSubscriber
-    //     only fires on real reference changes); `!prev` is unreachable
-    //     once `transition.from` is set (core populates them together).
-    //     Both kept for parity with React; v8-ignored.
-    /* v8 ignore start */
-    if (!currentRoute) {
-      return;
-    }
-    /* v8 ignore stop */
-    if (!currentRoute.transition.from) {
-      return;
-    }
-    if (skipSameRoute && currentRoute.transition.from === currentRoute.name) {
-      return;
-    }
-    /* v8 ignore start */
-    if (lastHandledRoute === currentRoute || !prev) {
-      return;
-    }
-    /* v8 ignore stop */
-
-    lastHandledRoute = currentRoute;
-    handler({ route: currentRoute, previousRoute: prev });
-  });
-}

package/src/composables/useRouteExit.svelte.ts

@@ -1,113 +0,0 @@
-import { onDestroy } from "svelte";
-
-import { useRouter } from "./useRouter.svelte";
-
-import type { State } from "@real-router/core";
-
-export interface RouteExitContext {
-  /** The route being left. */
-  route: State;
-  /** The route being navigated to. */
-  nextRoute: State;
-  /**
-   * AbortSignal that fires when this navigation is superseded by a later
-   * one (rapid clicks). Already filtered: when the handler runs,
-   * `signal.aborted` is guaranteed to be `false`. Use
-   * `signal.addEventListener("abort", cleanup, { once: true })` for
-   * cleanup that must run on cancellation.
-   */
-  signal: AbortSignal;
-}
-
-export interface UseRouteExitOptions {
-  /**
-   * Skip the handler when `route.name === nextRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`.
-   */
-  skipSameRoute?: boolean;
-}
-
-export type RouteExitHandler = (
-  context: RouteExitContext,
-) => void | Promise<void>;
-
-/**
- * Subscribe to the router's leave-window with the universal guards baked
- * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
- * boilerplate every time:
- *
- *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
- *     when the handler would run (rapid navigation superseded a slower
- *     one), the handler is skipped entirely.
- *   - **Same-route skip**: by default, `route.name === nextRoute.name`
- *     short-circuits the handler — query-only navigations skip the work.
- *     Opt out with `skipSameRoute: false`.
- *
- * Cleanup is bound to the component via `onDestroy`. Must be called
- * during component initialization (synchronous in `<script>`).
- *
- * If the handler returns a Promise, the router blocks on it. If the
- * Promise resolves, navigation proceeds. If it rejects, the router emits
- * `TRANSITION_CANCELLED`.
- *
- * **Handler reactivity (Svelte):** Svelte composables run **once** at
- * component init; `handler` is captured in closure at the call site. To
- * vary behavior over time, read `$state` / `$derived` values inside the
- * handler body — do not rely on swapping the handler reference.
- *
- * @example Animation
- * ```svelte
- * <script lang="ts">
- *   import { useRouteExit } from "@real-router/svelte";
- *   let el: HTMLDivElement;
- *
- *   useRouteExit(async ({ signal }) => {
- *     if (!el) return;
- *     el.classList.add("fade-out");
- *     const cleanup = () => el.classList.remove("fade-out");
- *     signal.addEventListener("abort", cleanup, { once: true });
- *     try {
- *       el.getBoundingClientRect();
- *       await Promise.allSettled(el.getAnimations().map((a) => a.finished));
- *     } finally {
- *       cleanup();
- *     }
- *   });
- * </script>
- *
- * <div bind:this={el}>...</div>
- * ```
- *
- * @example Reading rich transition metadata via `nextRoute.transition`
- * ```svelte
- * <script lang="ts">
- *   useRouteExit(({ nextRoute }) => {
- *     if (nextRoute.transition.segments.deactivated.includes("products")) {
- *       productCache.clear();
- *     }
- *   });
- * </script>
- * ```
- */
-export function useRouteExit(
-  handler: RouteExitHandler,
-  options?: UseRouteExitOptions,
-): void {
-  const router = useRouter();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
-    if (skipSameRoute && route.name === nextRoute.name) {
-      return;
-    }
-
-    if (signal.aborted) {
-      return;
-    }
-
-    return handler({ route, nextRoute, signal });
-  });
-
-  onDestroy(off);
-}

package/src/composables/useRouteNode.svelte.ts

@@ -1,18 +0,0 @@
-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";
-
-export function useRouteNode(nodeName: string): RouteContext {
-  const router = useRouter();
-  const navigator = getNavigator(router);
-
-  const source = createRouteNodeSource(router, nodeName);
-  const reactive = createReactiveSource(source);
-
-  return createRouteContext(navigator, reactive);
-}

package/src/composables/useRouteUtils.svelte.ts

@@ -1,12 +0,0 @@
-import { getPluginApi } from "@real-router/core/api";
-import { getRouteUtils } from "@real-router/route-utils";
-
-import { useRouter } from "./useRouter.svelte";
-
-import type { RouteUtils } from "@real-router/route-utils";
-
-export const useRouteUtils = (): RouteUtils => {
-  const router = useRouter();
-
-  return getRouteUtils(getPluginApi(router).getTree());
-};

package/src/composables/useRouter.svelte.ts

@@ -1,6 +0,0 @@
-import { ROUTER_KEY, getContextOrThrow } from "../context";
-
-import type { Router } from "@real-router/core";
-
-export const useRouter = (): Router =>
-  getContextOrThrow<Router>(ROUTER_KEY, "useRouter");

package/src/composables/useRouterTransition.svelte.ts

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

package/src/constants.ts

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