@equinor/fusion-framework-module-navigation 7.0.9-next.0 → 7.0.10

package/src/NavigationProvider.ts

@@ -1,436 +0,0 @@
-// TODO(#5158): 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 './NavigatedEvent';
-import { pathToString } from './lib/utils';
-import type { BaseHistory } from './lib';
-
-/**
- * Normalizes a pathname by:
- * - Collapsing multiple consecutive slashes into a single slash
- *
- * @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 slashes
- */
-const normalizePathname = (path: string): string => {
-  // Use iterative approach instead of regex to avoid potential ReDoS with untrusted input
-  let result = '';
-  let lastWasSlash = false;
-
-  // Walk each character once to collapse runs of slashes in a single pass
-  for (let i = 0; i < path.length; i++) {
-    const char = path[i];
-    // Only slashes need de-duplication; every other character passes through
-    if (char === '/') {
-      // Keep the first slash of a run, drop the rest
-      if (!lastWasSlash) {
-        result += char;
-        lastWasSlash = true;
-      }
-      // Skip consecutive slashes
-    } else {
-      result += char;
-      lastWasSlash = false;
-    }
-  }
-
-  return result;
-};
-
-/**
- * Removes trailing slashes from a path string.
- *
- * @param path - The path to trim
- * @returns The path without trailing slashes
- *
- * @example
- * stripTrailingSlashes("/apps/my-app/") // returns "/apps/my-app"
- * stripTrailingSlashes("/apps/my-app///") // returns "/apps/my-app"
- */
-const stripTrailingSlashes = (path: string): string => {
-  // Use iterative approach to avoid ReDoS vulnerability
-  let endIndex = path.length;
-  // Shrink endIndex past every trailing slash
-  while (endIndex > 0 && path[endIndex - 1] === '/') {
-    endIndex--;
-  }
-  return path.substring(0, endIndex);
-};
-
-/**
- * Navigation provider implementation.
- *
- * Manages routing and navigation state with automatic basename localization.
- * Wraps a {@link History} instance to expose observable state, path localization,
- * and router creation.
- *
- * @remarks
- * - 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
- *
- * @example
- * ```ts
- * const provider = new NavigationProvider({ version, config });
- * provider.push('/users');
- * console.log(provider.path.pathname); // '/users'
- * ```
- */
-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.
-   * @returns Observable of navigation updates.
-   *
-   * 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 prefix configured for this provider.
-   *
-   * @returns The basename string, or an empty string if none is configured
-   */
-  public get basename(): string {
-    return this.#basename ?? '';
-  }
-
-  /**
-   * @deprecated Use `history` instead
-   * @returns The underlying `History` instance.
-   */
-  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 underlying history instance.
-   * @returns The {@link History} instance used for navigation
-   *
-   * @returns The {@link History} instance used for navigation
-   */
-  public get history(): History {
-    return this.#history;
-  }
-
-  /**
-   * 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 instance is provided in the configuration
-   */
-  constructor(args: BaseModuleProviderCtorArgs<INavigationConfigurator>) {
-    super(args);
-
-    // Extract configuration values
-    const { basename, history, telemetry, eventProvider } = args.config;
-
-    // Normalize the basename to strip trailing slashes and collapse consecutive
-    // slashes. React Router requires the current URL to start with the exact
-    // basename string, so a basename of "/apps/my-app/" would fail to match
-    // the URL "/apps/my-app" and render nothing (blank page).
-    // Treat '/' as "no basename" (empty string) since all paths start with '/'.
-    const normalizedBasename = basename ? stripTrailingSlashes(normalizePathname(basename)) : '';
-    this.#basename = normalizedBasename || undefined;
-    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 Remix/React Router
-   * @returns A configured and initialized {@link Router} instance with basename applied
-   */
-  public createRouter(routes: AgnosticRouteObject[]) {
-    this.#telemetry?.trackEvent({
-      name: 'Navigation::createRouter',
-      level: TelemetryLevel.Warning,
-      scope: ['navigation', 'deprecated', TelemetryScope.Application],
-    });
-    // `this.#history` is typed as the framework's minimal history interface, but Remix Router
-    // requires its own richer `History` type — the two are runtime-compatible, so cast through
-    // `unknown`.
-    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 including the basename prefix.
-   *
-   * @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 {@link URL} object including the basename prefix.
-   *
-   * @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));
-  }
-
-  /**
-   * 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 whether a pathname falls within the configured basename scope.
-   *
-   * Uses a path-boundary check to avoid false positives from apps with
-   * overlapping name prefixes (e.g. `/apps/my-app` must not match
-   * `/apps/my-app-other/foo`).
-   *
-   * @param pathname - The pathname to check
-   * @returns `true` if the pathname matches the basename exactly or starts
-   *          with the basename followed by `/` (or no basename is set)
-   */
-  protected _isWithinBasenameScope(pathname: string): boolean {
-    // No basename means everything is in scope
-    if (!this.#basename) return true;
-
-    // Normalize the pathname for comparison (collapse consecutive slashes)
-    const normalized = normalizePathname(pathname);
-
-    // Check exact match or path-boundary prefix
-    return normalized === this.#basename || normalized.startsWith(`${this.#basename}/`);
-  }
-
-  /**
-   * Localizes a path by stripping the basename prefix from the pathname.
-   *
-   * Only removes the basename when it matches on a path boundary to avoid
-   * incorrectly stripping partial matches.
-   *
-   * @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;
-
-    // No basename - return normalized pathname as-is
-    if (!this.#basename) {
-      return {
-        pathname: normalizePathname(pathname) || '/',
-        search,
-        hash,
-      };
-    }
-
-    const normalized = normalizePathname(pathname);
-    let localized = normalized;
-
-    // Strip basename only if it matches at path boundary
-    if (normalized === this.#basename) {
-      localized = '/';
-    } else if (normalized.startsWith(`${this.#basename}/`)) {
-      localized = normalized.slice(this.#basename.length);
-    }
-
-    return {
-      pathname: localized || '/',
-      search,
-      hash,
-    };
-  }
-
-  /**
-   * 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
-    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

@@ -1,151 +0,0 @@
-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' });
-    });
-  });
-});