@real-router/angular 0.6.1 → 0.8.0

package/src/dom-utils/link-utils.ts

@@ -1,4 +1,9 @@
-import type { Router, Params } from "@real-router/core";
+import type {
+  NavigationOptions,
+  Params,
+  Router,
+  State,
+} from "@real-router/core";
 
 export function shouldNavigate(evt: MouseEvent): boolean {
   return (
@@ -10,25 +15,67 @@ export function shouldNavigate(evt: MouseEvent): boolean {
   );
 }
 
-type BuildUrlFn = (name: string, params: Params) => string | undefined;
+/**
+ * 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: string): string {
+  return encodeURI(decoded).replaceAll("#", "%23");
+}
 
+type BuildUrlFn = (
+  name: string,
+  params: Params,
+  options?: { hash?: string },
+) => 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 function buildHref(
   router: Router,
   routeName: string,
   routeParams: Params,
+  options?: { hash?: string },
 ): string | undefined {
   try {
+    const rawHash = options?.hash;
+    let normHash: string | undefined;
+
+    if (rawHash !== undefined) {
+      normHash = rawHash.startsWith("#") ? rawHash.slice(1) : rawHash;
+    }
+
     const buildUrl = router.buildUrl as BuildUrlFn | undefined;
 
     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.`,
@@ -38,6 +85,65 @@ export function buildHref(
   }
 }
 
+/**
+ * `<Link>` click-handler navigation helper (#532).
+ *
+ * Wraps `router.navigate(name, params, opts)` with same-route different-hash
+ * detection: when the consumer clicks a hash-bearing Link that targets the
+ * current route with the same params but a different fragment, core's
+ * SAME_STATES check would otherwise reject the navigation. The helper adds
+ * `force: true` and `hashChange: true` automatically — subscribers can then
+ * disambiguate via `state.context.url.hashChanged`.
+ *
+ * For pure programmatic same-route hash-only navigation, callers are
+ * documented to pass `{ force: true }` themselves; the auto-bypass here is
+ * a UX convenience for `<Link hash>` that all 6 framework adapters share.
+ */
+/**
+ * Local extended-options type. Adapters that depend only on `@real-router/core`
+ * (without a URL plugin) do not see the `NavigationOptions` augmentation that
+ * declares `hash` / `hashChange`. Casting to this widened type inside the
+ * helper keeps shared/dom-utils self-contained — adapters do not need to
+ * augment NavigationOptions themselves to consume `<Link hash>`.
+ */
+type HashAwareNavigationOptions = NavigationOptions & {
+  hash?: string;
+  hashChange?: boolean;
+};
+
+export function navigateWithHash(
+  router: Router,
+  routeName: string,
+  routeParams: Params,
+  hash: string | undefined,
+  extraOptions?: NavigationOptions,
+): Promise<State> {
+  const opts: HashAwareNavigationOptions = { ...extraOptions };
+
+  if (hash !== undefined) {
+    opts.hash = hash;
+  }
+
+  const current = router.getState();
+
+  if (
+    current?.name === routeName &&
+    shallowEqual(current.params, routeParams)
+  ) {
+    const currentHash =
+      (current.context as { url?: { hash?: string } } | undefined)?.url?.hash ??
+      "";
+    const newHash = hash ?? currentHash;
+
+    if (currentHash !== newHash) {
+      opts.force = true;
+      opts.hashChange = true;
+    }
+  }
+
+  return router.navigate(routeName, routeParams, opts);
+}
+
 function parseTokens(value: string | undefined): string[] {
   return value ? (value.match(/\S+/g) ?? []) : [];
 }

package/src/dom-utils/scroll-restore.ts

@@ -1,6 +1,6 @@
 import type { Router, State } from "@real-router/core";
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 
 const NOOP_INSTANCE: { destroy: () => void } = Object.freeze({
   destroy: () => {
@@ -8,12 +8,33 @@ const NOOP_INSTANCE: { destroy: () => void } = Object.freeze({
   },
 });
 
-export type ScrollRestorationMode = "restore" | "top" | "manual";
+export type ScrollRestorationMode = "restore" | "top" | "native";
 
 export interface ScrollRestorationOptions {
   mode?: ScrollRestorationMode | undefined;
   anchorScrolling?: boolean | undefined;
   scrollContainer?: (() => HTMLElement | null) | undefined;
+  /**
+   * Scroll behavior passed to `scrollTo({ behavior })` and
+   * `scrollIntoView({ behavior })`.
+   *
+   * - `"auto"` (default) — browser-defined, usually instant.
+   * - `"instant"` — explicit instant jump (no animation).
+   * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+   *   can feel disorienting if the user expects to land at the saved position
+   *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+   *
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+   */
+  behavior?: ScrollBehavior | undefined;
+  /**
+   * sessionStorage key used to persist saved scroll positions. Default:
+   * `"real-router:scroll"`. Override only when multiple independent
+   * `RouterProvider` instances share the same document and you need to
+   * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+   * or testing). For a single app with one provider the default is fine.
+   */
+  storageKey?: string | undefined;
 }
 
 interface NavigationContext {
@@ -31,15 +52,41 @@ export function createScrollRestoration(
 
   const mode = options?.mode ?? "restore";
 
-  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
-  // don't subscribe, don't register pagehide — leave the browser's native
-  // auto-restore intact for the app to override if it wants to.
-  if (mode === "manual") {
+  // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — `history.scrollRestoration`
+  // stays at the browser default ("auto") so the browser handles scroll
+  // restore natively. (Note: this is the OPPOSITE of `history.scrollRestoration
+  // === "manual"` — utility's "native" leaves the DOM property at "auto" so
+  // the browser is in charge.)
+  if (mode === "native") {
     return NOOP_INSTANCE;
   }
 
   const anchorEnabled = options?.anchorScrolling ?? true;
   const getContainer = options?.scrollContainer;
+  const behavior: ScrollBehavior = options?.behavior ?? "auto";
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const loadStore = (): Record<string, number> => {
+    try {
+      const raw = sessionStorage.getItem(storageKey);
+
+      return raw ? (JSON.parse(raw) as Record<string, number>) : {};
+    } catch {
+      return {};
+    }
+  };
+
+  const putPos = (key: string, pos: number): void => {
+    try {
+      const store = loadStore();
+
+      store[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(store));
+    } catch {
+      // Ignore quota / security errors.
+    }
+  };
 
   const prevScrollRestoration = history.scrollRestoration;
 
@@ -62,19 +109,44 @@ export function createScrollRestoration(
     const element = getContainer?.();
 
     if (element) {
-      element.scrollTop = top;
+      element.scrollTo({ top, left: 0, behavior });
     } else {
-      globalThis.scrollTo(0, top);
+      globalThis.scrollTo({ top, left: 0, behavior });
     }
   };
 
-  const scrollToHashOrTop = (): void => {
+  const scrollToHashOrTop = (route: State): void => {
+    // 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 as { url?: { hash?: string } } | undefined)
+      ?.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({ behavior });
+
+          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: string;
 
       try {
@@ -87,7 +159,7 @@ export function createScrollRestoration(
       const element = document.getElementById(id);
 
       if (element) {
-        element.scrollIntoView();
+        element.scrollIntoView({ behavior });
 
         return;
       }
@@ -117,7 +189,7 @@ export function createScrollRestoration(
       }
 
       if (mode === "top" || !nav) {
-        scrollToHashOrTop();
+        scrollToHashOrTop(route);
 
         return;
       }
@@ -136,7 +208,7 @@ export function createScrollRestoration(
         return;
       }
 
-      scrollToHashOrTop();
+      scrollToHashOrTop(route);
     });
   });
 
@@ -173,27 +245,6 @@ function keyOf(state: State): string {
   return `${state.name}:${canonicalJson(state.params)}`;
 }
 
-function loadStore(): Record<string, number> {
-  try {
-    const raw = sessionStorage.getItem(STORAGE_KEY);
-
-    return raw ? (JSON.parse(raw) as Record<string, number>) : {};
-  } catch {
-    return {};
-  }
-}
-
-function putPos(key: string, pos: number): void {
-  try {
-    const store = loadStore();
-
-    store[key] = pos;
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-  } catch {
-    // Ignore quota / security errors.
-  }
-}
-
 function canonicalJson(value: unknown): string {
   return JSON.stringify(value, canonicalReplacer);
 }

package/src/functions/injectIsActiveRoute.ts

@@ -9,13 +9,22 @@ import type { Params } from "@real-router/core";
 export function injectIsActiveRoute(
   routeName: string,
   params?: Params,
-  options?: { strict?: boolean; ignoreQueryParams?: boolean },
+  options?: { strict?: boolean; ignoreQueryParams?: boolean; hash?: string },
 ): Signal<boolean> {
   const router = injectRouter();
-  const source = createActiveRouteSource(router, routeName, params, {
-    strict: options?.strict ?? false,
-    ignoreQueryParams: options?.ignoreQueryParams ?? true,
-  });
+  const strict = options?.strict ?? false;
+  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
+  const hash = options?.hash;
+  // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — pass
+  // the field only when a value was provided. (#532)
+  const source = createActiveRouteSource(
+    router,
+    routeName,
+    params,
+    hash === undefined
+      ? { strict, ignoreQueryParams }
+      : { strict, ignoreQueryParams, hash },
+  );
 
   return sourceToSignal(source);
 }