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

package/src/NavigationProvider.ts

@@ -0,0 +1,313 @@
+// TODO: Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
+import { type AgnosticRouteObject, createRouter } from '@remix-run/router';
+import type { Observable } from 'rxjs';
+import { filter, pairwise, shareReplay } from 'rxjs/operators';
+
+import {
+  BaseModuleProvider,
+  type BaseModuleProviderCtorArgs,
+} from '@equinor/fusion-framework-module/provider';
+
+import type { INavigationProvider } from './NavigationProvider.interface';
+import type { INavigationConfigurator } from './NavigationConfigurator.interface';
+import type { History, NavigateOptions, NavigationUpdate, Path, To } from './lib/types';
+import {
+  TelemetryLevel,
+  TelemetryScope,
+  type ITelemetryProvider,
+} from '@equinor/fusion-framework-module-telemetry';
+import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
+import { NavigatedEvent } from './events';
+import { pathToString } from './lib/utils';
+import type { BaseHistory } from './lib';
+
+/**
+ * Normalizes a pathname by:
+ * - Collapsing multiple consecutive slashes into a single slash
+ * - Removing trailing slashes
+ *
+ * @example
+ * normalizePathname("/app//users///profile/") // returns "/app/users/profile"
+ * normalizePathname("///multiple///slashes///") // returns "/multiple/slashes"
+ *
+ * @param path - The pathname to normalize
+ * @returns The normalized pathname without consecutive or trailing slashes
+ */
+const normalizePathname = (path: string) => path.replace(/\/+/g, '/').replace(/\/$/, '');
+
+/**
+ * Navigation provider implementation.
+ * Manages routing and navigation state with basename localization.
+ *
+ * @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.)
+ *
+ * Path localization ensures that consumers receive paths relative to the basename,
+ * while internally we work with full paths including basename.
+ */
+export class NavigationProvider
+  extends BaseModuleProvider<INavigationConfigurator>
+  implements INavigationProvider
+{
+  #history: History;
+  #basename?: string;
+  #state$: Observable<NavigationUpdate>;
+
+  #telemetry?: ITelemetryProvider;
+  #event?: IEventModuleProvider;
+
+  /**
+   * Observable stream of navigation state updates.
+   * Emits localized paths (with basename removed) for consumers.
+   */
+  public get state$(): Observable<NavigationUpdate> {
+    return this.#state$;
+  }
+
+  /**
+   * Gets the basename.
+   */
+  public get basename(): string {
+    return this.#basename ?? '';
+  }
+
+  /**
+   * @deprecated Use `history` instead
+   */
+  public get navigator(): History {
+    this.#telemetry?.trackException({
+      name: 'Navigation::navigator.deprecated',
+      exception: new Error('navigator is deprecated, use history instead'),
+      level: TelemetryLevel.Warning,
+      scope: ['navigation', TelemetryScope.Framework],
+    });
+    return this.#history;
+  }
+
+  /**
+   * Gets the history instance.
+   */
+  public get history(): History {
+    return this.#history;
+  }
+
+  /**
+   * Gets the current localized path (basename removed).
+   */
+  public get path(): Path {
+    return this._localizePath(this.#history.location);
+  }
+
+  /**
+   * @param args - Configuration arguments containing module config
+   * @throws {Error} If no history is provided in the configuration
+   */
+  constructor(args: BaseModuleProviderCtorArgs<INavigationConfigurator>) {
+    super(args);
+
+    // Extract configuration values
+    const { basename, history, telemetry, eventProvider } = args.config;
+
+    this.#basename = basename;
+    this.#event = eventProvider;
+    this.#telemetry = telemetry;
+
+    // History is required - validate and track error if missing
+    if (!history) {
+      this.#telemetry?.trackException({
+        name: 'Navigation::history.required',
+        exception: new Error('no history provided!'),
+        level: TelemetryLevel.Error,
+        scope: ['navigation', TelemetryScope.Application],
+      });
+      throw Error('no history provided!');
+    }
+
+    this.#history = history;
+
+    // Create state$ observable that filters for paths within basename scope
+    // shareReplay ensures subscribers get the latest value and share the subscription
+    this.#state$ = this.#history.state$.pipe(
+      filter((update: NavigationUpdate) => this._isWithinBasenameScope(update.location.pathname)),
+      shareReplay({ bufferSize: 1, refCount: true }),
+    );
+
+    this._initialize();
+  }
+
+  /**
+   * Sets up navigation subscriptions for events and telemetry.
+   *
+   * Configures subscriptions for:
+   * - NavigatedEvent dispatching when navigation changes
+   * - Telemetry tracking for navigation actions and events
+   * - History disposal cleanup
+   */
+  protected _initialize(): void {
+    // Dispatch NavigatedEvent and track telemetry when navigation changes
+    // pairwise() gives us [previous, current] pairs to compare navigation state
+    this._addTeardown(
+      this.#state$.pipe(pairwise()).subscribe(([previous, current]) => {
+        // emit NavigatedEvent for other modules to listen to when navigation changes
+        this.#event?.dispatchEvent(
+          new NavigatedEvent(
+            {
+              action: current.action,
+              current,
+              previous,
+            },
+            this,
+          ),
+        );
+        // track telemetry for navigation changes
+        this.#telemetry?.trackEvent({
+          name: 'Navigation::navigated',
+          level: TelemetryLevel.Information,
+          scope: ['navigation', TelemetryScope.Application],
+          properties: {
+            action: current.action,
+            location: pathToString(current.location),
+            previousLocation: pathToString(previous.location),
+          },
+        });
+      }),
+    );
+
+    // Track all navigation actions for debugging (if telemetry is enabled)
+    if (this.#telemetry) {
+      this._addTeardown(
+        this.#history.action$.subscribe((action) => {
+          this.#telemetry?.trackEvent({
+            name: `Navigation::action:${action.type}`,
+            level: TelemetryLevel.Debug,
+            scope: ['navigation', TelemetryScope.Framework],
+            properties: {
+              type: action.type,
+              action: action,
+            },
+          });
+        }),
+      );
+    }
+
+    // Clean up history instance when provider is disposed
+    this._addTeardown(() => this.#history[Symbol.dispose]());
+  }
+
+  /**
+   * Creates a router instance from route configuration.
+   *
+   * @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
+   */
+  public createRouter(routes: AgnosticRouteObject[]) {
+    this.#telemetry?.trackEvent({
+      name: 'Navigation::createRouter',
+      level: TelemetryLevel.Warning,
+      scope: ['navigation', 'deprecated', TelemetryScope.Application],
+    });
+    const router = createRouter({
+      basename: this.#basename,
+      history: this.#history as unknown as import('@remix-run/router').History,
+      routes,
+      future: {
+        v7_prependBasename: true,
+      },
+    });
+    router.initialize();
+    return router;
+  }
+
+  /**
+   * Creates a localized href string for navigation.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   */
+  public createHref(to?: To): string {
+    return this.#history.createHref(this._createToPath(to ?? this.path));
+  }
+
+  /**
+   * Creates a full URL object for navigation.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   */
+  public createURL(to?: To): URL {
+    return this.#history.createURL(this._createToPath(to ?? this.path));
+  }
+
+  /**
+   * Pushes a new navigation entry onto the history stack.
+   *
+   * @param to - Path or location to navigate to (relative to basename)
+   * @param state - Optional state to associate with the navigation
+   */
+  public push(to: To, state?: unknown): void {
+    this.navigate(to, { state });
+  }
+
+  /**
+   * Replaces the current history entry with a new one.
+   *
+   * @param to - Path or location to navigate to (relative to basename)
+   * @param state - Optional state to associate with the navigation
+   */
+  public replace(to: To, state?: unknown): void {
+    this.navigate(to, { replace: true, state });
+  }
+
+  /**
+   * Navigate to a location with explicit options.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   * @param options - Optional navigation options
+   */
+  public navigate(to?: To, options?: Partial<NavigateOptions>): void {
+    const { replace = false, state } = options ?? {};
+    this.#history.navigate(this._createToPath(to ?? this.path), { replace, state });
+    // we need to pop the history to update the notify history listeners
+    // Frameworks as react router have their internal state management,
+    // so we need to force a pop to notify the framework that the history has changed
+    (this.#history as BaseHistory).pop();
+  }
+  /**
+   * Checks if a pathname is within the basename scope.
+   */
+  protected _isWithinBasenameScope(pathname: string): boolean {
+    return this.#basename ? pathname.startsWith(this.#basename) : true;
+  }
+
+  /**
+   * Localizes a path by removing the basename prefix.
+   */
+  protected _localizePath(location: Path): Path {
+    const { pathname, search, hash } = location;
+    return {
+      pathname: normalizePathname(pathname.replace(this.#basename ?? '', '')),
+      search,
+      hash,
+    };
+  }
+
+  /**
+   * Creates a full path object from a target location, adding basename prefix.
+   */
+  protected _createToPath(to: To): Partial<Path> {
+    // Parse the 'to' parameter into path components
+    const pathComponents = typeof to === 'string' ? { pathname: to } : to;
+
+    // Extract path parts, defaulting to current path values
+    const rawPathname = pathComponents.pathname ?? this.path.pathname;
+    const pathname = normalizePathname(`${this.#basename ?? ''}/${rawPathname}`);
+    const search = pathComponents.search ?? this.path.search;
+    const hash = pathComponents.hash ?? this.path.hash;
+
+    return { pathname, search, hash };
+  }
+}

package/src/__tests__/BrowserHistory.test.ts

@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { firstValueFrom, skip } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import { NavigationProvider } from '../NavigationProvider';
+import { createHistory } from '../lib/create-history';
+import type { History } from '../lib/types';
+
+describe('BrowserHistory', () => {
+  let provider: NavigationProvider;
+  let history: History;
+
+  beforeEach(() => {
+    history = createHistory('browser');
+    provider = new NavigationProvider({
+      version: '1.0.0',
+      config: { history },
+    });
+  });
+
+  afterEach(() => {
+    provider?.dispose();
+    history[Symbol.dispose]();
+  });
+
+  describe('push', () => {
+    it('should navigate when push is called', async () => {
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      provider.push('/about', { test: 'test' });
+      await updatePromise;
+
+      expect(provider.path.pathname).toBe(history.location.pathname);
+
+      expect(history.location.pathname).toBe('/about');
+      expect(history.action).toBe('PUSH');
+      expect(history.location.state).toEqual({ test: 'test' });
+      expect(window.location.pathname).toBe('/about');
+    });
+
+    it('should support browser back/forward navigation', async () => {
+      history.push('/page1', { page: 1 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page1');
+
+      history.push('/page2', { page: 2 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page2');
+
+      // Go back
+      const backPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      window.history.back();
+      await backPromise;
+      expect(history.location.pathname).toBe('/page1');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 1 });
+
+      // Go forward
+      const forwardPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      window.history.forward();
+      await forwardPromise;
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 2 });
+    });
+
+    it('should support go() method', async () => {
+      history.push('/page1');
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page1');
+
+      history.push('/page2');
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page2');
+
+      history.push('/page3');
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page3');
+
+      // Go back - wait for state update to /page2
+      const goBackPromise = firstValueFrom(
+        history.state$.pipe(
+          skip(1),
+          filter((update) => update.location.pathname === '/page2'),
+        ),
+      );
+      history.go(-1);
+      await goBackPromise;
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('POP');
+
+      // Go forward - wait for state update to /page3
+      const goForwardPromise = firstValueFrom(
+        history.state$.pipe(
+          skip(1),
+          filter((update) => update.location.pathname === '/page3'),
+        ),
+      );
+      history.go(1);
+      await goForwardPromise;
+      expect(history.location.pathname).toBe('/page3');
+      expect(history.action).toBe('POP');
+    });
+  });
+
+  describe('replace', () => {
+    it('should navigate when replace is called', async () => {
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      provider.replace('/about', { test: 'test' });
+      await updatePromise;
+
+      expect(history.location.pathname).toBe('/about');
+      expect(history.action).toBe('REPLACE');
+      expect(history.location.state).toEqual({ test: 'test' });
+      expect(window.location.pathname).toBe('/about');
+    });
+
+    it('should replace current entry without adding to history stack', async () => {
+      // Start at root
+      expect(history.location.pathname).toBe('/');
+
+      // Push an entry
+      history.push('/page1', { page: 1 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page1');
+
+      // Replace current entry
+      history.replace('/page2', { page: 2 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('REPLACE');
+
+      // Go back - should go to root, not page1 (because page1 was replaced)
+      const backPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      window.history.back();
+      await backPromise;
+      expect(history.location.pathname).toBe('/');
+      expect(history.action).toBe('POP');
+    });
+  });
+
+  describe('state$ observable', () => {
+    it('should emit state updates on navigation', async () => {
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.push('/test', { data: 'test' });
+      const update = await updatePromise;
+
+      expect(update.action).toBe('PUSH');
+      expect(update.location.pathname).toBe('/test');
+      expect(update.location.state).toEqual({ data: 'test' });
+    });
+  });
+});

package/src/__tests__/HashHistory.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { firstValueFrom, skip } from 'rxjs';
+import { createHistory } from '../lib/create-history';
+import type { History } from '../lib/types';
+
+describe('HashHistory', () => {
+  let history: History;
+
+  beforeEach(() => {
+    history = createHistory('hash');
+  });
+
+  afterEach(() => {
+    history[Symbol.dispose]();
+  });
+
+  describe('hash-based navigation', () => {
+    it('should update hash instead of pathname on push', async () => {
+      const initialPathname = window.location.pathname;
+
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.push('/about', { test: 'test' });
+      await updatePromise;
+
+      expect(history.location.pathname).toBe('/about');
+      expect(history.action).toBe('PUSH');
+      expect(history.location.state).toEqual({ test: 'test' });
+      // Pathname should remain unchanged
+      expect(window.location.pathname).toBe(initialPathname);
+      // Hash should contain the route
+      expect(window.location.hash).toBe('#/about');
+    });
+
+    it('should update hash instead of pathname on replace', async () => {
+      const initialPathname = window.location.pathname;
+
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.replace('/profile', { userId: 123 });
+      await updatePromise;
+
+      expect(history.location.pathname).toBe('/profile');
+      expect(history.action).toBe('REPLACE');
+      expect(history.location.state).toEqual({ userId: 123 });
+      // Pathname should remain unchanged
+      expect(window.location.pathname).toBe(initialPathname);
+      // Hash should contain the route
+      expect(window.location.hash).toBe('#/profile');
+    });
+
+    it('should resolve location from hash', async () => {
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.push('/test?query=1#section');
+      await updatePromise;
+
+      const location = history.location;
+      expect(location.pathname).toBe('/test');
+      expect(location.search).toBe('?query=1');
+      expect(location.hash).toBe('#section');
+      expect(window.location.hash).toBe('#/test?query=1#section');
+    });
+
+    it('should handle hashchange events for back/forward', async () => {
+      const initialPathname = window.location.pathname;
+
+      // Push multiple entries
+      history.push('/page1', { page: 1 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(window.location.hash).toBe('#/page1');
+
+      history.push('/page2', { page: 2 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(window.location.hash).toBe('#/page2');
+
+      // Go back - should trigger hashchange event
+      const backPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      window.history.back();
+      await backPromise;
+      expect(history.location.pathname).toBe('/page1');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 1 });
+      expect(window.location.hash).toBe('#/page1');
+      expect(window.location.pathname).toBe(initialPathname);
+
+      // Go forward
+      const forwardPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      window.history.forward();
+      await forwardPromise;
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 2 });
+      expect(window.location.hash).toBe('#/page2');
+      expect(window.location.pathname).toBe(initialPathname);
+    });
+
+    it('should handle hash with search and hash fragments', async () => {
+      const initialPathname = window.location.pathname;
+
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.push('/users?filter=active#list', { filter: 'active' });
+      await updatePromise;
+
+      expect(history.location.pathname).toBe('/users');
+      expect(history.location.search).toBe('?filter=active');
+      expect(history.location.hash).toBe('#list');
+      // Hash should contain full path with search and hash
+      expect(window.location.hash).toBe('#/users?filter=active#list');
+      expect(window.location.pathname).toBe(initialPathname);
+    });
+  });
+
+  describe('state$ observable', () => {
+    it('should emit state updates on navigation', async () => {
+      const updatePromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.push('/test');
+      const update = await updatePromise;
+
+      expect(update.action).toBe('PUSH');
+      expect(update.location.pathname).toBe('/test');
+    });
+  });
+});