@real-router/svelte 0.10.0 → 0.11.0

package/src/components/Streamed.svelte

@@ -0,0 +1,37 @@
+<!--
+  @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

@@ -0,0 +1,41 @@
+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

@@ -11,7 +11,7 @@ export function useIsActiveRoute(
   strict: boolean,
   ignoreQueryParams: boolean,
   hash?: string,
-): { readonly current: boolean } {
+) {
   const router = useRouter();
 
   // The `hash` argument (#532) participates in the cache key when defined.

package/src/composables/useRoute.svelte.ts

@@ -3,10 +3,16 @@ import { ROUTE_KEY, getContextOrThrow } from "../context";
 import type { RouteContext } from "../types";
 import type { Params, State } from "@real-router/core";
 
-export const useRoute = <P extends Params = Params>(): Omit<
-  RouteContext<P>,
-  "route"
-> & { route: { readonly current: State<P> } } => {
+/**
+ * `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) {
@@ -15,7 +21,5 @@ export const useRoute = <P extends Params = Params>(): Omit<
     );
   }
 
-  return ctx as Omit<RouteContext<P>, "route"> & {
-    route: { readonly current: State<P> };
-  };
+  return ctx as ActiveRouteContext<P>;
 };

package/src/context.ts

@@ -6,6 +6,8 @@ export const NAVIGATOR_KEY = "real-router:navigator";
 
 export const ROUTE_KEY = "real-router:route";
 
+export const HTTP_STATUS_KEY = "real-router:http-status-sink";
+
 // 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

package/src/ssr.ts

@@ -0,0 +1,28 @@
+// SSR-feature entry — Svelte 5+
+//
+// Server-side and SSR-aware components/composables. Mirror of `@real-router/react/ssr`
+// — same exports, Svelte-native idioms (`{#await}` block under the hood,
+// `$state` rune for ClientOnly/ServerOnly, useDeferred returns Promise<T>
+// for direct use with native `{#await}`).
+
+// Components
+export { default as ClientOnly } from "./components/ClientOnly.svelte";
+
+export { default as ServerOnly } from "./components/ServerOnly.svelte";
+
+export { default as Await } from "./components/Await.svelte";
+
+export { default as Streamed } from "./components/Streamed.svelte";
+
+export { default as HttpStatusCode } from "./components/HttpStatusCode.svelte";
+
+export { default as HttpStatusProvider } from "./components/HttpStatusProvider.svelte";
+
+// Composables
+export { useDeferred } from "./composables/useDeferred.svelte";
+
+// Utilities
+export { createHttpStatusSink } from "./utils/createHttpStatusSink";
+
+// Types
+export type { HttpStatusSink } from "./utils/createHttpStatusSink";

package/src/types.ts

@@ -4,6 +4,7 @@ import type {
   Params,
   State,
 } from "@real-router/core";
+import type { Snippet } from "svelte";
 
 export interface RouteContext<P extends Params = Params> {
   readonly navigator: Navigator;
@@ -11,7 +12,18 @@ export interface RouteContext<P extends Params = Params> {
   readonly previousRoute: { readonly current: State | undefined };
 }
 
+/**
+ * Props accepted by `<Link>`. Mirrors the inline prop shape in
+ * `src/components/Link.svelte` — any prop landed by `Link.svelte` is also
+ * declared here, including the rest-props index signature for arbitrary
+ * HTML attributes spread onto the rendered `<a>`.
+ */
 export interface LinkProps<P extends Params = Params> {
+  /**
+   * All other props are spread onto the rendered `<a>` element. Use this for
+   * `aria-*`, `data-*`, `id`, `title`, and any other native attributes.
+   */
+  readonly [key: string]: unknown;
   readonly routeName: string;
   readonly routeParams?: P;
   readonly routeOptions?: NavigationOptions;
@@ -19,5 +31,16 @@ export interface LinkProps<P extends Params = Params> {
   readonly activeClassName?: string;
   readonly activeStrict?: boolean;
   readonly ignoreQueryParams?: boolean;
+  /**
+   * URL fragment (decoded, no leading "#") — #532.
+   * - `undefined` → preserve current `state.context.url.hash` on click.
+   * - `""` → clear the hash.
+   * - `"value"` → set the hash; same-route different-hash clicks route through
+   *   `navigateWithHash`, which adds `force: true, hashChange: true` to
+   *   bypass core's SAME_STATES check.
+   */
+  readonly hash?: string;
   readonly target?: string;
+  readonly children?: Snippet;
+  readonly onclick?: (evt: MouseEvent) => void;
 }

package/src/utils/createHttpStatusSink.ts

@@ -0,0 +1,31 @@
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider sink={...}>`, and read after `await render()` from
+ * `svelte/server` to apply the value to the HTTP response.
+ *
+ * Last write wins: if the rendered tree mounts more than one
+ * `<HttpStatusCode />`, the value reflects the last component that ran during
+ * the render pass.
+ *
+ * No-op on the client — `<HttpStatusCode />` reads the optional injected sink
+ * and skips the write when no provider is mounted, so the same component tree
+ * can be hydrated without changing behaviour.
+ *
+ * Constraints:
+ * - **Per-request only.** Don't share a sink across requests; the rendered
+ *   tree mutates `code` in place. Module-level singletons leak status
+ *   between concurrent requests.
+ * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
+ *   freezing makes the assignment throw under ESM strict mode.
+ * - **Hydration is tolerant.** Svelte 5's hydration walker accepts
+ *   `{#if}`-branch asymmetry between server and client (verified by `ssr/`
+ *   e2e), so the example app uses a server-only provider wrapper. This
+ *   contrasts with Vue/Solid, which require symmetric provider mounting.
+ */
+export interface HttpStatusSink {
+  code: number | undefined;
+}
+
+export function createHttpStatusSink(): HttpStatusSink {
+  return { code: undefined };
+}