@real-router/angular 0.6.1 → 0.8.0

package/README.md

@@ -320,6 +320,16 @@ Navigation directive for `<a>` elements. Handles click events, sets `href`, and
 | `activeClassName`   | `string`            | `"active"` | CSS class applied when route is active |
 | `activeStrict`      | `boolean`           | `false`    | Exact match only (no ancestor match)   |
 | `ignoreQueryParams` | `boolean`           | `true`     | Query params don't affect active state |
+| `hash`              | `string`            | `undefined`| URL fragment (decoded). Tri-state: undefined preserves, `""` clears, value sets. (#532) |
+
+#### `hash` input — URL fragment / tab-style UIs
+
+```html
+<a [realLink]="'settings'" [hash]="'profile'">Profile</a>
+<a [realLink]="'settings'" [hash]="'account'">Account</a>
+```
+
+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.
 
 ### `[realLinkActive]`
 
@@ -404,7 +414,7 @@ interface RealRouterOptions {
 }
 ```
 
-Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
+Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"native"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
 ## View Transitions
 

package/dist/README.md

@@ -320,6 +320,16 @@ Navigation directive for `<a>` elements. Handles click events, sets `href`, and
 | `activeClassName`   | `string`            | `"active"` | CSS class applied when route is active |
 | `activeStrict`      | `boolean`           | `false`    | Exact match only (no ancestor match)   |
 | `ignoreQueryParams` | `boolean`           | `true`     | Query params don't affect active state |
+| `hash`              | `string`            | `undefined`| URL fragment (decoded). Tri-state: undefined preserves, `""` clears, value sets. (#532) |
+
+#### `hash` input — URL fragment / tab-style UIs
+
+```html
+<a [realLink]="'settings'" [hash]="'profile'">Profile</a>
+<a [realLink]="'settings'" [hash]="'account'">Account</a>
+```
+
+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.
 
 ### `[realLinkActive]`
 
@@ -404,7 +414,7 @@ interface RealRouterOptions {
 }
 ```
 
-Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
+Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"native"`. Custom containers via `scrollContainer: () => HTMLElement | null`. The utility is created by `provideEnvironmentInitializer` and torn down via `inject(DestroyRef)`. Options are a snapshot at bootstrap — not reactive to runtime changes. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
 ## View Transitions
 

package/dist/fesm2022/real-router-angular.mjs

@@ -177,7 +177,7 @@ function manageFocus(h1) {
     h1.focus({ preventScroll: true });
 }
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE$1 = Object.freeze({
     destroy: () => {
         /* no-op */
@@ -188,14 +188,38 @@ function createScrollRestoration(router, options) {
         return NOOP_INSTANCE$1;
     }
     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$1;
     }
     const anchorEnabled = options?.anchorScrolling ?? true;
     const getContainer = options?.scrollContainer;
+    const behavior = options?.behavior ?? "auto";
+    const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+    const loadStore = () => {
+        try {
+            const raw = sessionStorage.getItem(storageKey);
+            return raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            return {};
+        }
+    };
+    const putPos = (key, pos) => {
+        try {
+            const store = loadStore();
+            store[key] = pos;
+            sessionStorage.setItem(storageKey, JSON.stringify(store));
+        }
+        catch {
+            // Ignore quota / security errors.
+        }
+    };
     const prevScrollRestoration = history.scrollRestoration;
     try {
         history.scrollRestoration = "manual";
@@ -213,18 +237,37 @@ function createScrollRestoration(router, options) {
     const writePos = (top) => {
         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 = () => {
+    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({ 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;
             try {
                 id = decodeURIComponent(hash.slice(1));
@@ -235,7 +278,7 @@ function createScrollRestoration(router, options) {
             // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
             const element = document.getElementById(id);
             if (element) {
-                element.scrollIntoView();
+                element.scrollIntoView({ behavior });
                 return;
             }
         }
@@ -258,7 +301,7 @@ function createScrollRestoration(router, options) {
                 return;
             }
             if (mode === "top" || !nav) {
-                scrollToHashOrTop();
+                scrollToHashOrTop(route);
                 return;
             }
             if (nav.navigationType === "replace") {
@@ -270,7 +313,7 @@ function createScrollRestoration(router, options) {
                 writePos(loadStore()[keyOf(route)] ?? 0);
                 return;
             }
-            scrollToHashOrTop();
+            scrollToHashOrTop(route);
         });
     });
     const onPageHide = () => {
@@ -300,25 +343,6 @@ function createScrollRestoration(router, options) {
 function keyOf(state) {
     return `${state.name}:${canonicalJson(state.params)}`;
 }
-function loadStore() {
-    try {
-        const raw = sessionStorage.getItem(STORAGE_KEY);
-        return raw ? JSON.parse(raw) : {};
-    }
-    catch {
-        return {};
-    }
-}
-function putPos(key, pos) {
-    try {
-        const store = loadStore();
-        store[key] = pos;
-        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-    }
-    catch {
-        // Ignore quota / security errors.
-    }
-}
 function canonicalJson(value) {
     return JSON.stringify(value, canonicalReplacer);
 }
@@ -461,22 +485,69 @@ function shouldNavigate(evt) {
         !evt.ctrlKey &&
         !evt.shiftKey);
 }
-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.
+ */
+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;
     }
 }
+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) ?? []) : [];
 }
@@ -650,10 +721,14 @@ function injectRouterTransition() {
 
 function injectIsActiveRoute(routeName, params, options) {
     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);
 }
 
@@ -1021,18 +1096,37 @@ class RealLink {
     activeClassName = input("active", ...(ngDevMode ? [{ debugName: "activeClassName" }] : /* istanbul ignore next */ []));
     activeStrict = input(false, ...(ngDevMode ? [{ debugName: "activeStrict" }] : /* istanbul ignore next */ []));
     ignoreQueryParams = input(true, ...(ngDevMode ? [{ debugName: "ignoreQueryParams" }] : /* istanbul ignore next */ []));
+    /**
+     * URL fragment (decoded form, no leading "#") (#532).
+     * - omitted/`undefined` → preserve current fragment on same-route navigation
+     * - `""` → clear fragment
+     * - non-empty → set fragment
+     */
+    hash = input(undefined, ...(ngDevMode ? [{ debugName: "hash" }] : /* istanbul ignore next */ []));
     router = injectRouter();
     destroyRef = inject(DestroyRef);
     anchor = inject(ElementRef)
         .nativeElement;
     isActive = signal(false, ...(ngDevMode ? [{ debugName: "isActive" }] : /* istanbul ignore next */ []));
-    href = computed(() => buildHref(this.router, this.routeName(), this.routeParams()), ...(ngDevMode ? [{ debugName: "href" }] : /* istanbul ignore next */ []));
+    href = computed(() => {
+        const hashValue = this.hash();
+        return buildHref(this.router, this.routeName(), this.routeParams(), hashValue === undefined ? undefined : { hash: hashValue });
+    }, ...(ngDevMode ? [{ debugName: "href" }] : /* istanbul ignore next */ []));
     prevActiveClass = "";
     ngOnInit() {
-        const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), {
-            strict: this.activeStrict(),
-            ignoreQueryParams: this.ignoreQueryParams(),
-        });
+        // Hash-aware active state (#532): pass `hash` so that tab-style links
+        // (same routeName, different `hash` input) only mark the active variant.
+        const hashValue = this.hash();
+        const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), hashValue === undefined
+            ? {
+                strict: this.activeStrict(),
+                ignoreQueryParams: this.ignoreQueryParams(),
+            }
+            : {
+                strict: this.activeStrict(),
+                ignoreQueryParams: this.ignoreQueryParams(),
+                hash: hashValue,
+            });
         this.isActive.set(source.getSnapshot());
         this.updateDom();
         const unsub = source.subscribe(() => {
@@ -1049,9 +1143,7 @@ class RealLink {
             return;
         }
         event.preventDefault();
-        this.router
-            .navigate(this.routeName(), this.routeParams(), this.routeOptions())
-            .catch(() => { });
+        navigateWithHash(this.router, this.routeName(), this.routeParams(), this.hash(), this.routeOptions()).catch(() => { });
     }
     updateDom() {
         const href = this.href();
@@ -1068,7 +1160,7 @@ class RealLink {
         this.prevActiveClass = activeClass;
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLink, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: RealLink, isStandalone: true, selector: "a[realLink]", inputs: { routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, routeOptions: { classPropertyName: "routeOptions", publicName: "routeOptions", isSignal: true, isRequired: false, transformFunction: null }, activeClassName: { classPropertyName: "activeClassName", publicName: "activeClassName", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "click": "onClick($event)" } }, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: RealLink, isStandalone: true, selector: "a[realLink]", inputs: { routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, routeOptions: { classPropertyName: "routeOptions", publicName: "routeOptions", isSignal: true, isRequired: false, transformFunction: null }, activeClassName: { classPropertyName: "activeClassName", publicName: "activeClassName", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null }, hash: { classPropertyName: "hash", publicName: "hash", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "click": "onClick($event)" } }, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLink, decorators: [{
             type: Directive,
@@ -1078,7 +1170,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
                         "(click)": "onClick($event)",
                     },
                 }]
-        }], propDecorators: { routeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeName", required: false }] }], routeParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeParams", required: false }] }], routeOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeOptions", required: false }] }], activeClassName: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeClassName", required: false }] }], activeStrict: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeStrict", required: false }] }], ignoreQueryParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "ignoreQueryParams", required: false }] }] } });
+        }], propDecorators: { routeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeName", required: false }] }], routeParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeParams", required: false }] }], routeOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeOptions", required: false }] }], activeClassName: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeClassName", required: false }] }], activeStrict: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeStrict", required: false }] }], ignoreQueryParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "ignoreQueryParams", required: false }] }], hash: [{ type: i0.Input, args: [{ isSignal: true, alias: "hash", required: false }] }] } });
 
 class RealLinkActive {
     realLinkActive = input("", ...(ngDevMode ? [{ debugName: "realLinkActive" }] : /* istanbul ignore next */ []));