@equinor/fusion-framework-module-navigation 7.0.0 → 7.0.2

package/dist/types/NavigationConfigurator.d.ts

@@ -28,10 +28,19 @@ export declare class NavigationConfigurator extends BaseConfigBuilder<INavigatio
     /**
      * 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
      */
-    setHistory(historyOrCallback?: History | ConfigBuilderCallback<History>): this;
+    setHistory(historyOrCallback?: History | ConfigBuilderCallback<History>, options?: {
+        proxy?: boolean;
+    }): this;
     /**
      * Sets telemetry configuration for navigation-specific events.
      *

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

@@ -0,0 +1,68 @@
+import type { Observable } from 'rxjs';
+import type { History, NavigateOptions, NavigationBlocker, NavigationListener, NavigationUpdate, Path, To } from './types';
+import type { Actions } from './state/history.actions';
+/**
+ * A lightweight proxy that delegates every {@link History} operation to an
+ * underlying target instance.
+ *
+ * Use this when you need to pass a conforming `History` object whose backing
+ * implementation can be swapped or is not yet available at construction time,
+ * or when you want a thin indirection layer without subclassing
+ * {@link BaseHistory}.
+ *
+ * The proxy does **not** own the underlying history; disposing it only tears
+ * down subscriptions and blockers registered through the proxy itself.
+ *
+ * @example
+ * ```ts
+ * const browser = createHistory('browser');
+ * const proxy = new ProxyHistory(browser);
+ * proxy.push('/dashboard'); // delegates to browser.push
+ * ```
+ */
+export declare class ProxyHistory implements History {
+    #private;
+    /**
+     * @param target - The history instance to delegate all operations to
+     */
+    constructor(target: History);
+    /** @inheritdoc */
+    get state$(): Observable<NavigationUpdate>;
+    /** @inheritdoc */
+    get action$(): Observable<Actions>;
+    /** @inheritdoc */
+    get action(): History['action'];
+    /** @inheritdoc */
+    get location(): History['location'];
+    /** @inheritdoc */
+    createHref(to: To): string;
+    /** @inheritdoc */
+    createURL(to: To): URL;
+    /** @inheritdoc */
+    encodeLocation(to: To): Path;
+    /** @inheritdoc */
+    push(to: To, state?: unknown): void;
+    /** @inheritdoc */
+    replace(to: To, state?: unknown): void;
+    /** @inheritdoc */
+    navigate(to: To, options?: NavigateOptions): void;
+    /** @inheritdoc */
+    go(delta: number): void;
+    /**
+     * Triggers a POP action on the underlying history to notify framework
+     * listeners (e.g. React Router) after programmatic navigation.
+     *
+     * Delegates to the target's `pop()` when it is a {@link BaseHistory}
+     * instance; otherwise this is a no-op.
+     */
+    pop(): void;
+    /** @inheritdoc */
+    listen(listener: NavigationListener): () => void;
+    /** @inheritdoc */
+    block(blocker: NavigationBlocker): VoidFunction;
+    /**
+     * Disposes all listeners and blockers registered through this proxy.
+     * Does **not** dispose the underlying history.
+     */
+    [Symbol.dispose](): void;
+}

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

@@ -10,6 +10,7 @@
 export { BaseHistory } from './BaseHistory';
 export { BrowserHistory } from './BrowserHistory';
 export { MemoryHistory } from './MemoryHistory';
+export { ProxyHistory } from './ProxyHistory';
 export { BrowserHistoryStack } from './BrowserHistoryStack';
 export { BrowserHistoryHashStack as HashHistoryStack } from './BrowserHistoryHashStack';
 export { MemoryHistoryStack } from './MemoryStack';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.0";
+export declare const version = "7.0.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-navigation",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "description": "Navigation module for Fusion Framework providing routing and navigation capabilities using React Router 7",
   "sideEffects": false,
   "main": "dist/esm/index.js",
@@ -32,24 +32,24 @@
   },
   "dependencies": {
     "@remix-run/router": "^1.23.0",
-    "uuid": "^13.0.0",
+    "uuid": "^14.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "jsdom": "^27.1.0",
+    "jsdom": "^29.0.2",
     "rxjs": "^7.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@equinor/fusion-framework-module": "^6.0.0",
     "@equinor/fusion-framework-module-event": "^6.0.0",
-    "@equinor/fusion-framework-module-telemetry": "^5.0.0",
-    "@equinor/fusion-observable": "^9.0.0"
+    "@equinor/fusion-observable": "^9.0.1",
+    "@equinor/fusion-framework-module-telemetry": "^5.0.1",
+    "@equinor/fusion-framework-module": "^6.0.0"
   },
   "peerDependencies": {
     "@remix-run/router": "^1.0.0",
     "rxjs": "^7.0.0",
     "@equinor/fusion-framework-module": "^6.0.0",
-    "@equinor/fusion-observable": "^9.0.0"
+    "@equinor/fusion-observable": "^9.0.1"
   },
   "scripts": {
     "build": "tsc -b",

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/__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/lib/ProxyHistory.ts

@@ -0,0 +1,144 @@
+import { Subscription } from 'rxjs';
+import type { Observable } from 'rxjs';
+
+import type { BaseHistory } from './BaseHistory';
+import type {
+  History,
+  NavigateOptions,
+  NavigationBlocker,
+  NavigationListener,
+  NavigationUpdate,
+  Path,
+  To,
+} from './types';
+import type { Actions } from './state/history.actions';
+
+/**
+ * A lightweight proxy that delegates every {@link History} operation to an
+ * underlying target instance.
+ *
+ * Use this when you need to pass a conforming `History` object whose backing
+ * implementation can be swapped or is not yet available at construction time,
+ * or when you want a thin indirection layer without subclassing
+ * {@link BaseHistory}.
+ *
+ * The proxy does **not** own the underlying history; disposing it only tears
+ * down subscriptions and blockers registered through the proxy itself.
+ *
+ * @example
+ * ```ts
+ * const browser = createHistory('browser');
+ * const proxy = new ProxyHistory(browser);
+ * proxy.push('/dashboard'); // delegates to browser.push
+ * ```
+ */
+export class ProxyHistory implements History {
+  /** The underlying history instance all calls are forwarded to. */
+  readonly #target: History;
+
+  /** Teardowns owned by this proxy, cleaned up on dispose. */
+  readonly #teardowns = new Subscription();
+
+  /**
+   * @param target - The history instance to delegate all operations to
+   */
+  constructor(target: History) {
+    this.#target = target;
+  }
+
+  /** @inheritdoc */
+  get state$(): Observable<NavigationUpdate> {
+    return this.#target.state$;
+  }
+
+  /** @inheritdoc */
+  get action$(): Observable<Actions> {
+    return this.#target.action$;
+  }
+
+  /** @inheritdoc */
+  get action(): History['action'] {
+    return this.#target.action;
+  }
+
+  /** @inheritdoc */
+  get location(): History['location'] {
+    return this.#target.location;
+  }
+
+  /** @inheritdoc */
+  createHref(to: To): string {
+    return this.#target.createHref(to);
+  }
+
+  /** @inheritdoc */
+  createURL(to: To): URL {
+    return this.#target.createURL(to);
+  }
+
+  /** @inheritdoc */
+  encodeLocation(to: To): Path {
+    return this.#target.encodeLocation(to);
+  }
+
+  /** @inheritdoc */
+  push(to: To, state?: unknown): void {
+    this.#target.push(to, state);
+  }
+
+  /** @inheritdoc */
+  replace(to: To, state?: unknown): void {
+    this.#target.replace(to, state);
+  }
+
+  /** @inheritdoc */
+  navigate(to: To, options?: NavigateOptions): void {
+    this.#target.navigate(to, options);
+  }
+
+  /** @inheritdoc */
+  go(delta: number): void {
+    this.#target.go(delta);
+  }
+
+  /**
+   * Triggers a POP action on the underlying history to notify framework
+   * listeners (e.g. React Router) after programmatic navigation.
+   *
+   * Delegates to the target's `pop()` when it is a {@link BaseHistory}
+   * instance; otherwise this is a no-op.
+   */
+  pop(): void {
+    if ('pop' in this.#target && typeof this.#target.pop === 'function') {
+      (this.#target as BaseHistory).pop();
+    }
+  }
+
+  /** @inheritdoc */
+  listen(listener: NavigationListener): () => void {
+    const unlisten = this.#target.listen(listener);
+    this.#teardowns.add(unlisten);
+    return () => {
+      unlisten();
+      this.#teardowns.remove(unlisten);
+    };
+  }
+
+  /** @inheritdoc */
+  block(blocker: NavigationBlocker): VoidFunction {
+    const unblock = this.#target.block(blocker);
+    this.#teardowns.add(unblock);
+    return () => {
+      unblock();
+      this.#teardowns.remove(unblock);
+    };
+  }
+
+  /**
+   * Disposes all listeners and blockers registered through this proxy.
+   * Does **not** dispose the underlying history.
+   */
+  [Symbol.dispose](): void {
+    this.#teardowns.unsubscribe();
+  }
+}

package/src/lib/index.ts

@@ -12,6 +12,7 @@
 export { BaseHistory } from './BaseHistory';
 export { BrowserHistory } from './BrowserHistory';
 export { MemoryHistory } from './MemoryHistory';
+export { ProxyHistory } from './ProxyHistory';
 
 // History stacks
 export { BrowserHistoryStack } from './BrowserHistoryStack';

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.0.0';
+export const version = '7.0.2';