@real-router/svelte 0.8.0 → 0.9.0

package/README.md

@@ -183,11 +183,21 @@ Navigation link with automatic active state detection. Uses `$derived` for href
 | `activeClassName`   | `string`            | `"active"`  | Class added when route is active        |
 | `activeStrict`      | `boolean`           | `false`     | Exact match only (no ancestor matching) |
 | `ignoreQueryParams` | `boolean`           | `true`      | Query params don't affect active state  |
+| `hash`              | `string`            | `undefined` | URL fragment (decoded). Tri-state: undefined preserves, `""` clears, value sets. (#532) |
 | `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.
 
+#### `hash` — URL fragment / tab-style UIs
+
+```svelte
+<Link routeName="settings" hash="profile">Profile</Link>
+<Link routeName="settings" hash="account">Account</Link>
+```
+
+Active class is hash-aware — only the matching tab lights up. Live demo: [`examples/web/react/link-hash/`](../../examples/web/react/link-hash/) — behavior is identical across adapters, only template syntax differs. See the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page for the full surface.
+
 ### `<Lazy>`
 
 Lazy-load route content with a fallback component while loading. Useful for code-splitting and dynamic imports.

package/dist/components/Link.svelte

@@ -6,6 +6,7 @@
     shouldNavigate,
     buildHref,
     buildActiveClassName,
+    navigateWithHash,
   } from "../dom-utils";
 
   import type { NavigationOptions, Params } from "@real-router/core";
@@ -19,6 +20,7 @@
     activeClassName = "active",
     activeStrict = false,
     ignoreQueryParams = true,
+    hash = undefined,
     target = undefined,
     children = undefined,
     onclick: userOnClick = undefined,
@@ -31,6 +33,13 @@
     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;
@@ -38,14 +47,24 @@
   } = $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));
+  const href = $derived(
+    buildHref(
+      router,
+      routeName,
+      routeParams,
+      hash !== undefined ? { hash } : undefined,
+    ),
+  );
 
   const finalClassName = $derived(
     buildActiveClassName(activeState.current, activeClassName, className),
@@ -65,7 +84,9 @@
     }
 
     evt.preventDefault();
-    router.navigate(routeName, routeParams, routeOptions).catch(NOOP);
+    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(
+      NOOP,
+    );
   }
 </script>
 

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

@@ -8,6 +8,13 @@ type $$ComponentProps = {
     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;

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 | undefined, strict: boolean, ignoreQueryParams: boolean): {
+export declare function useIsActiveRoute(routeName: string, params: Params | undefined, strict: boolean, ignoreQueryParams: boolean, hash?: string): {
     readonly current: boolean;
 };

package/dist/composables/useIsActiveRoute.svelte.js

@@ -1,11 +1,13 @@
 import { createActiveRouteSource } from "@real-router/sources";
 import { createReactiveSource } from "../createReactiveSource.svelte";
 import { useRouter } from "./useRouter.svelte";
-export function useIsActiveRoute(routeName, params, strict, ignoreQueryParams) {
+export function useIsActiveRoute(routeName, params, strict, ignoreQueryParams, hash) {
     const router = useRouter();
-    const source = createActiveRouteSource(router, routeName, params, {
-        strict,
-        ignoreQueryParams,
-    });
+    // 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/dist/dom-utils/index.d.ts

@@ -2,7 +2,7 @@ export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
 export { createViewTransitions } from "./view-transitions.js";
-export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, navigateWithHash, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";
 export type { ScrollRestorationOptions, ScrollRestorationMode, } from "./scroll-restore.js";
 export type { DirectionTracker } from "./direction-tracker.js";

package/dist/dom-utils/index.js

@@ -2,4 +2,4 @@ export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
 export { createViewTransitions } from "./view-transitions.js";
-export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
+export { shouldNavigate, buildHref, buildActiveClassName, navigateWithHash, shallowEqual, applyLinkA11y, } from "./link-utils.js";

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

@@ -1,6 +1,22 @@
-import type { Router, Params } from "@real-router/core";
+import type { NavigationOptions, Params, Router, State } from "@real-router/core";
 export declare function shouldNavigate(evt: MouseEvent): boolean;
-export declare function buildHref(router: Router, routeName: string, routeParams: Params): string | undefined;
+/**
+ * Builds an href for a `<Link>` element.
+ *
+ * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
+ *   hash-plugin) when present.
+ * - Falls back to `router.buildPath` for runtimes without a URL plugin
+ *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
+ *   is appended manually so the rendered href is still correct.
+ * - The optional 4th argument is an options object so the contract stays
+ *   extensible. The `hash` option is a decoded fragment without leading "#";
+ *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
+ *   Frozen API: previous 3-arg call sites continue to work unchanged.
+ */
+export declare function buildHref(router: Router, routeName: string, routeParams: Params, options?: {
+    hash?: string;
+}): string | undefined;
+export declare function navigateWithHash(router: Router, routeName: string, routeParams: Params, hash: string | undefined, extraOptions?: NavigationOptions): Promise<State>;
 export declare function buildActiveClassName(isActive: boolean, activeClassName: string | undefined, baseClassName: string | undefined): string | undefined;
 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

@@ -5,22 +5,69 @@ export function shouldNavigate(evt) {
         !evt.ctrlKey &&
         !evt.shiftKey);
 }
-export function buildHref(router, routeName, routeParams) {
+/**
+ * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
+ * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
+ * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
+ * `shared/browser-env/url-context.ts` — duplicated here because the
+ * shared/dom-utils symlink graph does not reach shared/browser-env.
+ */
+function encodeFragmentInline(decoded) {
+    return encodeURI(decoded).replaceAll("#", "%23");
+}
+/**
+ * Builds an href for a `<Link>` element.
+ *
+ * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
+ *   hash-plugin) when present.
+ * - Falls back to `router.buildPath` for runtimes without a URL plugin
+ *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
+ *   is appended manually so the rendered href is still correct.
+ * - The optional 4th argument is an options object so the contract stays
+ *   extensible. The `hash` option is a decoded fragment without leading "#";
+ *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
+ *   Frozen API: previous 3-arg call sites continue to work unchanged.
+ */
+export function buildHref(router, routeName, routeParams, options) {
     try {
+        const rawHash = options?.hash;
+        let normHash;
+        if (rawHash !== undefined) {
+            normHash = rawHash.startsWith("#") ? rawHash.slice(1) : rawHash;
+        }
         const buildUrl = router.buildUrl;
         if (buildUrl) {
-            const url = buildUrl(routeName, routeParams);
+            const url = buildUrl(routeName, routeParams, normHash === undefined ? undefined : { hash: normHash });
             if (url !== undefined) {
                 return url;
             }
         }
-        return router.buildPath(routeName, routeParams);
+        const path = router.buildPath(routeName, routeParams);
+        return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
     }
     catch {
         console.error(`[real-router] Route "${routeName}" is not defined. The element will render without an href attribute.`);
         return undefined;
     }
 }
+export function navigateWithHash(router, routeName, routeParams, hash, extraOptions) {
+    const opts = { ...extraOptions };
+    if (hash !== undefined) {
+        opts.hash = hash;
+    }
+    const current = router.getState();
+    if (current?.name === routeName &&
+        shallowEqual(current.params, routeParams)) {
+        const currentHash = current.context?.url?.hash ??
+            "";
+        const newHash = hash ?? currentHash;
+        if (currentHash !== newHash) {
+            opts.force = true;
+            opts.hashChange = true;
+        }
+    }
+    return router.navigate(routeName, routeParams, opts);
+}
 function parseTokens(value) {
     return value ? (value.match(/\S+/g) ?? []) : [];
 }

package/dist/dom-utils/scroll-restore.js

@@ -40,12 +40,31 @@ export function createScrollRestoration(router, options) {
             globalThis.scrollTo(0, top);
         }
     };
-    const scrollToHashOrTop = () => {
+    const scrollToHashOrTop = (route) => {
+        // URL plugin path (#532): `state.context.url.hash` is the source of truth
+        // when one of the URL plugins (browser-plugin / navigation-plugin) is
+        // installed. The value is already DECODED — feeding it through
+        // `decodeURIComponent` again would throw on a bare `%`.
+        const ctxHash = route.context
+            ?.url?.hash;
+        if (ctxHash !== undefined) {
+            if (anchorEnabled && ctxHash.length > 0) {
+                // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
+                const element = document.getElementById(ctxHash);
+                if (element) {
+                    element.scrollIntoView();
+                    return;
+                }
+            }
+            writePos(0);
+            return;
+        }
+        // Fallback path: no URL plugin, read the DOM. `location.hash` is
+        // percent-encoded; ids in the DOM are the raw string, so decode for the
+        // match. Fall back to the raw slice if the hash contains a malformed
+        // escape sequence (decodeURIComponent throws on those).
         const hash = globalThis.location.hash;
         if (anchorEnabled && hash.length > 1) {
-            // location.hash is percent-encoded; ids in the DOM are the raw string.
-            // Decode for the match. Fall back to the raw slice if the hash contains
-            // a malformed escape sequence (decodeURIComponent throws on those).
             let id;
             try {
                 id = decodeURIComponent(hash.slice(1));
@@ -79,7 +98,7 @@ export function createScrollRestoration(router, options) {
                 return;
             }
             if (mode === "top" || !nav) {
-                scrollToHashOrTop();
+                scrollToHashOrTop(route);
                 return;
             }
             if (nav.navigationType === "replace") {
@@ -91,7 +110,7 @@ export function createScrollRestoration(router, options) {
                 writePos(loadStore()[keyOf(route)] ?? 0);
                 return;
             }
-            scrollToHashOrTop();
+            scrollToHashOrTop(route);
         });
     });
     const onPageHide = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -44,9 +44,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.50.2",
-    "@real-router/route-utils": "^0.2.1",
-    "@real-router/sources": "^0.7.2"
+    "@real-router/core": "^0.51.0",
+    "@real-router/route-utils": "^0.2.2",
+    "@real-router/sources": "^0.8.0"
   },
   "devDependencies": {
     "@sveltejs/package": "2.5.7",
@@ -58,7 +58,7 @@
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.16.0"
+    "@real-router/browser-plugin": "^0.17.0"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"

package/src/components/Link.svelte

@@ -6,6 +6,7 @@
     shouldNavigate,
     buildHref,
     buildActiveClassName,
+    navigateWithHash,
   } from "../dom-utils";
 
   import type { NavigationOptions, Params } from "@real-router/core";
@@ -19,6 +20,7 @@
     activeClassName = "active",
     activeStrict = false,
     ignoreQueryParams = true,
+    hash = undefined,
     target = undefined,
     children = undefined,
     onclick: userOnClick = undefined,
@@ -31,6 +33,13 @@
     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;
@@ -38,14 +47,24 @@
   } = $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));
+  const href = $derived(
+    buildHref(
+      router,
+      routeName,
+      routeParams,
+      hash !== undefined ? { hash } : undefined,
+    ),
+  );
 
   const finalClassName = $derived(
     buildActiveClassName(activeState.current, activeClassName, className),
@@ -65,7 +84,9 @@
     }
 
     evt.preventDefault();
-    router.navigate(routeName, routeParams, routeOptions).catch(NOOP);
+    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(
+      NOOP,
+    );
   }
 </script>
 

package/src/composables/useIsActiveRoute.svelte.ts

@@ -10,13 +10,21 @@ export function useIsActiveRoute(
   params: Params | undefined,
   strict: boolean,
   ignoreQueryParams: boolean,
+  hash?: string,
 ): { readonly current: boolean } {
   const router = useRouter();
 
-  const source = createActiveRouteSource(router, routeName, params, {
-    strict,
-    ignoreQueryParams,
-  });
+  // 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);
 }