@equinor/fusion-framework-module-navigation 7.0.0-next.2 → 7.0.1

package/dist/types/lib/types.d.ts

@@ -38,11 +38,15 @@ export type Path = {
 };
 /**
  * Location object representing a navigation entry.
- * Extends Path with state and a unique key.
+ * Extends {@link Path} with arbitrary state data and a unique key.
+ *
+ * @template T - The type of the state payload stored in this location entry
  */
 export type Location<T = any> = Path & {
     state: T;
     key: string;
+    /** Masked path used by react-router 7.13+ for unstable view-transition masking. */
+    unstable_mask: Path | undefined;
 };
 /**
  * Internal state for history management.
@@ -57,7 +61,10 @@ export type LocationState = {
  */
 export type NavigationListener = (update: Readonly<NavigationUpdate>) => void;
 /**
- * Navigation update event containing action and location.
+ * Navigation update event containing the action, location, and stack delta.
+ *
+ * @template A - The type of navigation action (defaults to {@link Action})
+ * @template T - The type of the state payload in the location
  */
 export type NavigationUpdate<A extends string = Action, T = unknown> = {
     delta: number;
@@ -96,7 +103,16 @@ export interface NavigateOptions {
 }
 /**
  * History interface for managing navigation state.
- * Compatible with industry-standard routers (Remix/React Router) and provides observable state management.
+ *
+ * Compatible with Remix / React Router and provides observable
+ * state management via RxJS.
+ *
+ * @example
+ * ```ts
+ * const history = createHistory('browser');
+ * history.push('/dashboard');
+ * history.state$.subscribe(update => console.log(update.location.pathname));
+ * ```
  */
 export interface History extends Disposable {
     /** Observable stream of navigation state updates. */
@@ -107,11 +123,20 @@ export interface History extends Disposable {
     readonly action: Action;
     /** Current location in the history stack. */
     readonly location: Location;
-    /** Creates a valid href string for a given path. */
+    /** Creates a valid href string for a given path.
+     * @param to - Target path or partial path object
+     * @returns Fully-qualified href string
+     */
     createHref(to: To): string;
-    /** Creates a URL object for a given path. */
+    /** Creates a {@link URL} object for a given path.
+     * @param to - Target path or partial path object
+     * @returns Resolved {@link URL} instance
+     */
     createURL(to: To): URL;
-    /** Encodes a location by properly URL-encoding the pathname. */
+    /** Encodes a location by properly URL-encoding the pathname.
+     * @param to - Target path or partial path object
+     * @returns A {@link Path} with URL-encoded components
+     */
     encodeLocation(to: To): Path;
     /** Pushes a new navigation entry onto the history stack. */
     push(to: To, state?: unknown): void;
@@ -121,9 +146,15 @@ export interface History extends Disposable {
     navigate(to: To, options?: NavigateOptions): void;
     /** Navigates backward or forward in the history stack. */
     go(delta: number): void;
-    /** Sets up a listener for navigation changes. */
+    /** Sets up a listener for navigation changes.
+     * @param listener - Callback invoked on POP actions (browser back/forward)
+     * @returns A function that unsubscribes the listener when called
+     */
     listen(listener: NavigationListener): () => void;
-    /** Registers a blocker to intercept navigation attempts. */
+    /** Registers a blocker to intercept navigation attempts.
+     * @param blocker - Callback invoked before each navigation to allow or prevent it
+     * @returns A function that removes the blocker when called
+     */
     block(blocker: NavigationBlocker): VoidFunction;
 }
 /**

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.0-next.2";
+export declare const version = "7.0.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-navigation",
-  "version": "7.0.0-next.2",
+  "version": "7.0.1",
   "description": "Navigation module for Fusion Framework providing routing and navigation capabilities using React Router 7",
   "sideEffects": false,
   "main": "dist/esm/index.js",
@@ -33,24 +33,23 @@
   "dependencies": {
     "@remix-run/router": "^1.23.0",
     "uuid": "^13.0.0",
-    "zod": "^4.1.11"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/uuid": "^11.0.0",
-    "jsdom": "^27.1.0",
+    "jsdom": "^29.0.2",
     "rxjs": "^7.8.1",
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-framework-module-event": "^5.0.2-next.0",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.5-next.0",
-    "@equinor/fusion-observable": "^8.5.9-next.0"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module-telemetry": "^5.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-observable": "^9.0.0"
   },
   "peerDependencies": {
-    "@remix-run/router": "^1.23.0",
+    "@remix-run/router": "^1.0.0",
     "rxjs": "^7.0.0",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-observable": "^8.5.9-next.0"
+    "@equinor/fusion-observable": "^9.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/NavigationConfigurator.interface.ts

@@ -4,15 +4,38 @@ import type { IEventModuleProvider } from '@equinor/fusion-framework-module-even
 
 /**
  * Configuration object for the navigation module.
- * Provides options for customizing history, basename, telemetry, and event settings.
+ *
+ * Provides options for customizing the history implementation, basename prefix,
+ * telemetry tracking, and event dispatching used by the {@link NavigationProvider}.
  */
 export interface INavigationConfigurator {
-  /** Optional base pathname for the application (e.g., "/app") */
+  /**
+   * Base pathname prefix for the application (e.g. `"/apps/my-app"`).
+   *
+   * When set, the navigation provider automatically prepends this prefix to
+   * outgoing paths and strips it from incoming paths, so consumer code
+   * operates on clean, basename-free paths.
+   */
   basename?: string;
-  /** Optional custom history instance (browser, hash, or memory). If not provided, defaults to browser history. */
+
+  /**
+   * Custom {@link History} instance for navigation.
+   *
+   * If not provided, defaults to browser history in browser environments
+   * or memory history in Node.js environments. Create instances with
+   * {@link createHistory}.
+   */
   history?: History;
-  /** Optional telemetry provider for tracking navigation events */
+
+  /**
+   * Telemetry provider for tracking navigation events, location changes,
+   * and errors for monitoring and debugging.
+   */
   telemetry?: ITelemetryProvider;
-  /** Optional event provider for dispatching navigation events */
+
+  /**
+   * Event provider for dispatching {@link NavigateEvent} and {@link NavigatedEvent}.
+   * Allows other modules to listen for and react to navigation changes.
+   */
   eventProvider?: IEventModuleProvider;
 }

package/src/NavigationConfigurator.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { of, type ObservableInput } from 'rxjs';
+import { of, from, type ObservableInput } from 'rxjs';
+import { map } from 'rxjs/operators';
 import {
   BaseConfigBuilder,
   type ModulesInstance,
@@ -12,6 +13,7 @@ import type { INavigationConfigurator } from './NavigationConfigurator.interface
 
 import type { History } from './lib/types';
 import { createHistory } from './lib/create-history';
+import { ProxyHistory } from './lib/ProxyHistory';
 import type { NavigationModule } from './module';
 
 /**
@@ -72,16 +74,21 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
         return await args.requireInstance('event');
       }
     });
-    this.setHistory(async (args) => {
-      const history = (args.ref as ModulesInstance<[NavigationModule]>)?.navigation?.history;
-      if (history) {
-        return history;
-      }
-      if (typeof window !== 'undefined') {
-        return createHistory('browser');
-      }
-      return createHistory('memory');
-    });
+    this.setHistory(
+      async (args) => {
+        const history = (args.ref as ModulesInstance<[NavigationModule]>)?.navigation?.history;
+        if (history) {
+          // Wrap the provided history in a ProxyHistory to ensure the module can manage its own teardowns without affecting the original instance.
+          return new ProxyHistory(history);
+        }
+        if (typeof window !== 'undefined') {
+          return createHistory('browser');
+        }
+        return createHistory('memory');
+      },
+      // Don't wrap the default history in a ProxyHistory since it's already owned by the module and will be properly disposed.
+      { proxy: false },
+    );
   }
   /**
    * @deprecated Use `setBasename()` method instead
@@ -121,13 +128,38 @@ export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigu
   /**
    * Sets a custom history instance for the navigation module.
    *
+   * By default the resolved history is wrapped in a {@link ProxyHistory} so the
+   * module gets its own disposable handle without owning (or accidentally
+   * disposing) the original instance. Set `proxy` to `false` to use the
+   * history as-is.
+   *
    * @param historyOrCallback - History instance or configuration callback
+   * @param options - Optional settings for history wrapping
+   * @param options.proxy - Wrap the history in a {@link ProxyHistory} (default: `true`)
    * @returns The configurator instance for method chaining
    */
-  public setHistory(historyOrCallback?: History | ConfigBuilderCallback<History>): this {
-    const fn =
-      typeof historyOrCallback === 'function' ? historyOrCallback : async () => historyOrCallback;
-    this._set('history', fn);
+  public setHistory(
+    historyOrCallback?: History | ConfigBuilderCallback<History>,
+    options?: { proxy?: boolean },
+  ): this {
+    const { proxy = true } = options ?? {};
+    const resolve =
+      typeof historyOrCallback === 'function'
+        ? historyOrCallback
+        : // Normalize a direct instance to a callback for consistent handling.
+          async () => historyOrCallback;
+
+    if (proxy) {
+      // Wrap each emitted history in a ProxyHistory so dispose only tears down
+      // proxy-owned listeners/blockers, never the underlying history itself.
+      this._set('history', (args) =>
+        from(resolve(args) as ObservableInput<History | undefined>).pipe(
+          map((history) => (history ? new ProxyHistory(history) : undefined)),
+        ),
+      );
+    } else {
+      this._set('history', resolve);
+    }
     return this;
   }
 

package/src/NavigationProvider.interface.ts

@@ -9,7 +9,17 @@ import type { IModuleProvider } from '@equinor/fusion-framework-module';
 
 /**
  * Navigation provider interface.
- * Provides routing and navigation capabilities with basename localization.
+ *
+ * Provides routing and navigation capabilities with automatic basename
+ * localization. Consumers work with clean paths (e.g. `/users`) while the
+ * underlying history operates on full paths (e.g. `/apps/my-app/users`).
+ *
+ * @example
+ * ```ts
+ * const nav: INavigationProvider = framework.modules.navigation;
+ * nav.push('/users');
+ * console.log(nav.path.pathname); // '/users'
+ * ```
  */
 export interface INavigationProvider extends IModuleProvider {
   /**
@@ -41,22 +51,25 @@ export interface INavigationProvider extends IModuleProvider {
   /**
    * Creates a router instance from route configuration.
    *
-   * @param routes - Route configuration objects compatible with industry-standard routers (Remix/React Router)
-   * @returns A configured and initialized router instance
+   * @deprecated Use `@equinor/fusion-framework-react-router` instead.
+   * @param routes - Route configuration objects compatible with Remix/React Router
+   * @returns A configured and initialized {@link Router} instance with basename applied
    */
   createRouter(routes: AgnosticRouteObject[]): Router;
 
   /**
-   * Creates a localized href string for navigation.
+   * Creates a localized href string including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns Fully-qualified href string with basename included
    */
   createHref(to?: To): string;
 
   /**
-   * Creates a full URL object for navigation.
+   * Creates a full {@link URL} object including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns A {@link URL} instance representing the resolved navigation target
    */
   createURL(to?: To): URL;
 

package/src/NavigationProvider.ts

@@ -37,17 +37,23 @@ const normalizePathname = (path: string) => path.replace(/\/+/g, '/').replace(/\
 
 /**
  * Navigation provider implementation.
- * Manages routing and navigation state with basename localization.
+ *
+ * Manages routing and navigation state with automatic basename localization.
+ * Wraps a {@link History} instance to expose observable state, path localization,
+ * and router creation.
  *
  * @remarks
- * This provider:
- * - Wraps the Navigator to provide observable navigation state
- * - Localizes paths by removing basename prefix
- * - Creates routers compatible with industry-standard routers (Remix/React Router)
- * - Handles navigation actions (push, replace, createHref, etc.)
+ * - Emits localized paths (basename removed) to consumers via {@link NavigationProvider.state$ | state$}
+ * - Internally prefixes paths with the basename before forwarding to the history stack
+ * - Creates routers compatible with Remix / React Router via {@link NavigationProvider.createRouter | createRouter}
+ * - Dispatches {@link NavigatedEvent} and telemetry on navigation changes
  *
- * Path localization ensures that consumers receive paths relative to the basename,
- * while internally we work with full paths including basename.
+ * @example
+ * ```ts
+ * const provider = new NavigationProvider({ version, config });
+ * provider.push('/users');
+ * console.log(provider.path.pathname); // '/users'
+ * ```
  */
 export class NavigationProvider
   extends BaseModuleProvider<INavigationConfigurator>
@@ -62,14 +68,19 @@ export class NavigationProvider
 
   /**
    * Observable stream of navigation state updates.
-   * Emits localized paths (with basename removed) for consumers.
+   *
+   * Emits localized paths (with basename removed) and filters to only
+   * paths within the basename scope. Late subscribers receive the last
+   * emitted value immediately.
    */
   public get state$(): Observable<NavigationUpdate> {
     return this.#state$;
   }
 
   /**
-   * Gets the basename.
+   * Gets the basename prefix configured for this provider.
+   *
+   * @returns The basename string, or an empty string if none is configured
    */
   public get basename(): string {
     return this.#basename ?? '';
@@ -89,22 +100,28 @@ export class NavigationProvider
   }
 
   /**
-   * Gets the history instance.
+   * Gets the underlying history instance.
+   *
+   * @returns The {@link History} instance used for navigation
    */
   public get history(): History {
     return this.#history;
   }
 
   /**
-   * Gets the current localized path (basename removed).
+   * Gets the current localized path with the basename prefix removed.
+   *
+   * @returns A {@link Path} object representing the current location without basename
    */
   public get path(): Path {
     return this._localizePath(this.#history.location);
   }
 
   /**
+   * Creates a new {@link NavigationProvider}.
+   *
    * @param args - Configuration arguments containing module config
-   * @throws {Error} If no history is provided in the configuration
+   * @throws {Error} If no history instance is provided in the configuration
    */
   constructor(args: BaseModuleProviderCtorArgs<INavigationConfigurator>) {
     super(args);
@@ -201,10 +218,10 @@ export class NavigationProvider
   /**
    * Creates a router instance from route configuration.
    *
-   * @deprecated Use `@equinor/fusion-framework-react-router` instead
+   * @deprecated Use `@equinor/fusion-framework-react-router` instead.
    *
-   * @param routes - Route configuration objects compatible with industry-standard routers (Remix/React Router)
-   * @returns A configured and initialized router instance
+   * @param routes - Route configuration objects compatible with Remix/React Router
+   * @returns A configured and initialized {@link Router} instance with basename applied
    */
   public createRouter(routes: AgnosticRouteObject[]) {
     this.#telemetry?.trackEvent({
@@ -225,18 +242,26 @@ export class NavigationProvider
   }
 
   /**
-   * Creates a localized href string for navigation.
+   * Creates a localized href string including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns Fully-qualified href string with basename included
+   *
+   * @example
+   * ```ts
+   * // basename = '/apps/my-app'
+   * provider.createHref('/users'); // '/apps/my-app/users'
+   * ```
    */
   public createHref(to?: To): string {
     return this.#history.createHref(this._createToPath(to ?? this.path));
   }
 
   /**
-   * Creates a full URL object for navigation.
+   * Creates a full {@link URL} object including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns A {@link URL} instance representing the resolved navigation target
    */
   public createURL(to?: To): URL {
     return this.#history.createURL(this._createToPath(to ?? this.path));
@@ -277,14 +302,20 @@ export class NavigationProvider
     (this.#history as BaseHistory).pop();
   }
   /**
-   * Checks if a pathname is within the basename scope.
+   * Checks whether a pathname falls within the configured basename scope.
+   *
+   * @param pathname - The pathname to check
+   * @returns `true` if the pathname starts with the basename (or no basename is set)
    */
   protected _isWithinBasenameScope(pathname: string): boolean {
     return this.#basename ? pathname.startsWith(this.#basename) : true;
   }
 
   /**
-   * Localizes a path by removing the basename prefix.
+   * Localizes a path by stripping the basename prefix from the pathname.
+   *
+   * @param location - The full path to localize
+   * @returns A new {@link Path} with the basename removed from the pathname
    */
   protected _localizePath(location: Path): Path {
     const { pathname, search, hash } = location;
@@ -296,7 +327,10 @@ export class NavigationProvider
   }
 
   /**
-   * Creates a full path object from a target location, adding basename prefix.
+   * Creates a full path object from a target location, prepending the basename prefix.
+   *
+   * @param to - The target location (string path or partial {@link Path} object)
+   * @returns A partial {@link Path} with basename prepended to the pathname
    */
   protected _createToPath(to: To): Partial<Path> {
     // Parse the 'to' parameter into path components

package/src/__tests__/ProxyHistory.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { firstValueFrom, skip } from 'rxjs';
+import { MemoryHistory } from '../lib/MemoryHistory';
+import { ProxyHistory } from '../lib/ProxyHistory';
+
+/**
+ * Awaits the next state emission after performing a navigation action.
+ * MemoryHistory processes state updates asynchronously through the subject.
+ */
+const awaitNavigation = async (
+  history: MemoryHistory | ProxyHistory,
+  action: () => void,
+): Promise<void> => {
+  const next = firstValueFrom(history.state$.pipe(skip(1)));
+  action();
+  await next;
+};
+
+describe('ProxyHistory', () => {
+  let target: MemoryHistory;
+  let proxy: ProxyHistory;
+
+  beforeEach(() => {
+    target = new MemoryHistory();
+    proxy = new ProxyHistory(target);
+  });
+
+  afterEach(() => {
+    proxy[Symbol.dispose]();
+    target[Symbol.dispose]();
+  });
+
+  describe('delegation', () => {
+    it('should delegate location to the target', () => {
+      expect(proxy.location).toBe(target.location);
+    });
+
+    it('should delegate action to the target', () => {
+      expect(proxy.action).toBe(target.action);
+    });
+
+    it('should delegate push to the target', async () => {
+      await awaitNavigation(proxy, () => proxy.push('/test'));
+
+      expect(target.location.pathname).toBe('/test');
+      expect(proxy.location.pathname).toBe('/test');
+    });
+
+    it('should delegate replace to the target', async () => {
+      await awaitNavigation(proxy, () => proxy.replace('/replaced'));
+
+      expect(target.location.pathname).toBe('/replaced');
+      expect(proxy.location.pathname).toBe('/replaced');
+    });
+
+    it('should delegate navigate to the target', async () => {
+      await awaitNavigation(proxy, () =>
+        proxy.navigate('/nav', { replace: true, state: { foo: 1 } }),
+      );
+
+      expect(target.location.pathname).toBe('/nav');
+      expect(target.location.state).toEqual({ foo: 1 });
+    });
+
+    it('should delegate createHref to the target', () => {
+      expect(proxy.createHref('/path')).toBe(target.createHref('/path'));
+    });
+
+    it('should delegate createURL to the target', () => {
+      expect(proxy.createURL('/path').href).toBe(target.createURL('/path').href);
+    });
+
+    it('should delegate encodeLocation to the target', () => {
+      const encoded = proxy.encodeLocation('/path');
+      expect(encoded).toEqual(target.encodeLocation('/path'));
+    });
+  });
+
+  describe('pop()', () => {
+    it('should delegate pop to the target when target supports it', () => {
+      const popSpy = vi.spyOn(target, 'pop');
+      proxy.pop();
+      expect(popSpy).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('teardown isolation', () => {
+    it('should not dispose the target when proxy is disposed', async () => {
+      // Dispose the proxy
+      proxy[Symbol.dispose]();
+
+      // Target should still be functional — push should work
+      await awaitNavigation(target, () => target.push('/after-proxy-dispose'));
+      expect(target.location.pathname).toBe('/after-proxy-dispose');
+    });
+
+    it('should clean up proxy-owned listeners on dispose', async () => {
+      const proxyListener = vi.fn();
+      proxy.listen(proxyListener);
+
+      // Dispose the proxy — listener teardown should be called on the target
+      proxy[Symbol.dispose]();
+
+      // Target is still alive, push something — the disposed proxy listener
+      // should not fire (listen only triggers on POP, but the underlying
+      // subscription should be removed entirely)
+      await awaitNavigation(target, () => target.push('/after-dispose'));
+      expect(target.location.pathname).toBe('/after-dispose');
+    });
+
+    it('should not affect target listeners when proxy is disposed', async () => {
+      // Register a listener directly on the target
+      const targetListener = vi.fn();
+      target.listen(targetListener);
+
+      // Register a listener through the proxy
+      proxy.listen(vi.fn());
+
+      // Dispose proxy — only proxy listener should be removed
+      proxy[Symbol.dispose]();
+
+      // Target should still be functional
+      await awaitNavigation(target, () => target.push('/still-works'));
+      expect(target.location.pathname).toBe('/still-works');
+    });
+  });
+
+  describe('listen/block unsubscribe', () => {
+    it('should allow manual unsubscribe of a listener', () => {
+      const listener = vi.fn();
+      const unlisten = proxy.listen(listener);
+
+      unlisten();
+
+      // No error on dispose — the listener was already removed
+      proxy[Symbol.dispose]();
+    });
+
+    it('should allow manual unsubscribe of a blocker', () => {
+      const blocker = vi.fn();
+      const unblock = proxy.block(blocker);
+
+      unblock();
+
+      // No error on dispose — the blocker was already removed
+      proxy[Symbol.dispose]();
+    });
+  });
+});

package/src/events.ts

@@ -15,7 +15,16 @@ export interface NavigateEventDetail {
 
 /**
  * Event emitted before navigation occurs.
- * Can be canceled by calling `preventDefault()`.
+ * Can be canceled by calling `preventDefault()` to block the navigation.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigate', (event) => {
+ *   if (hasUnsavedChanges) {
+ *     event.preventDefault();
+ *   }
+ * });
+ * ```
  */
 export class NavigateEvent extends FrameworkEvent<
   FrameworkEventInit<NavigateEventDetail, INavigationProvider>
@@ -41,8 +50,16 @@ export interface NavigatedEventDetail {
 }
 
 /**
- * Event emitted after navigation occurs.
- * Contains the navigation action and location details.
+ * Event emitted after navigation completes.
+ * Contains the navigation action type and both current and previous locations.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigated', (event) => {
+ *   const { action, current, previous } = event.detail;
+ *   console.log(`${action}: ${previous.location.pathname} → ${current.location.pathname}`);
+ * });
+ * ```
  */
 export class NavigatedEvent extends FrameworkEvent<
   FrameworkEventInit<NavigatedEventDetail, INavigationProvider>