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

package/src/__tests__/ProxyHistory.test.ts

@@ -1,149 +0,0 @@
-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/__tests__/setup.ts

@@ -1,8 +0,0 @@
-import { beforeEach } from 'vitest';
-
-// Mock history and location
-beforeEach(() => {
-  // Reset history state
-  window.history.pushState({}, '', '/');
-  window.history.replaceState({}, '', '/');
-});

package/src/enable-navigation.ts

@@ -1,60 +0,0 @@
-import type { IModulesConfigurator, ModuleConfigType } from '@equinor/fusion-framework-module';
-import { module, type NavigationModule } from './module';
-
-/**
- * Helper function to enable the navigation module.
- *
- * This is the main entry point for consumers to add navigation capabilities to their
- * framework configuration. It registers the navigation module and allows configuration
- * of basename and other navigation settings.
- *
- * The navigation module provides routing and navigation capabilities compatible with
- * industry-standard routers (Remix/React Router), with support for browser history,
- * hash routing, and memory history.
- *
- * @param configurator - The modules configurator to add navigation to
- * @param basenameOrOptions - Optional basename string or configuration object
- * @param basenameOrOptions.configure - Configuration callback for advanced setup
- * @typeParam TRef - Reference type for module composition
- *
- * @example
- * ```ts
- * // Simple usage with basename
- * enableNavigation(configurator, '/app');
- *
- * // Advanced configuration
- * enableNavigation(configurator, {
- *   configure(config, ref) {
- *     config.setBasename('/app');
- *     config.setHistory(createHistory('browser'));
- *   }
- * });
- * ```
- *
- * @see {@link NavigationModule} - The navigation module type
- * @see {@link INavigationConfigurator} - Configuration interface
- * @see {@link INavigationProvider} - Provider interface for accessing navigation
- */
-export const enableNavigation = <TRef = unknown>(
-  // biome-ignore lint/suspicious/noExplicitAny: must be any to support all module types
-  configurator: IModulesConfigurator<any, any>,
-  basenameOrOptions?:
-    | string
-    | {
-        configure: (config: ModuleConfigType<NavigationModule>, ref: TRef) => void;
-      },
-): void => {
-  configurator.addConfig({
-    module,
-    configure(config, ref) {
-      // A string shortcut sets the basename directly; otherwise defer to the caller's configure callback.
-      if (typeof basenameOrOptions === 'string') {
-        config.setBasename(basenameOrOptions);
-      } else if (typeof basenameOrOptions === 'object' && 'configure' in basenameOrOptions) {
-        basenameOrOptions.configure(config, ref);
-      }
-    },
-  });
-};
-
-export default enableNavigation;

package/src/index.ts

@@ -1,51 +0,0 @@
-/**
- * @module @equinor/fusion-framework-module-navigation
- *
- * Navigation module for Fusion Framework providing routing and navigation capabilities.
- *
- * Manages observable navigation state with automatic basename localization,
- * so consumers work with clean paths while the underlying history receives
- * full paths including the basename prefix.
- *
- * @remarks
- * Supports browser, hash, and memory history types. Integrates with
- * `@remix-run/router` for router creation and is compatible with
- * industry-standard routers (Remix / React Router).
- *
- * @example
- * ```ts
- * import { enableNavigation, createHistory } from '@equinor/fusion-framework-module-navigation';
- *
- * enableNavigation(configurator, '/apps/my-app');
- * ```
- *
- * @packageDocumentation
- */
-
-export type { INavigationConfigurator } from './NavigationConfigurator.interface';
-export { NavigationConfigurator } from './NavigationConfigurator';
-
-export { NavigationModule, module, moduleKey } from './module';
-export { enableNavigation } from './enable-navigation';
-
-export type { INavigationProvider } from './NavigationProvider.interface';
-export { NavigationProvider } from './NavigationProvider';
-
-export { createHistory } from './lib/create-history';
-
-export { NavigateEvent, type NavigateEventDetail } from './NavigateEvent';
-export { NavigatedEvent, type NavigatedEventDetail } from './NavigatedEvent';
-
-export type {
-  Path,
-  To,
-  Location,
-  History,
-  NavigationBlocker,
-  NavigationListener,
-} from './lib/types';
-
-/**
- * @deprecated Use {@link History} instead.
- */
-export type { History as INavigator } from './lib';

package/src/lib/BaseHistory.ts

@@ -1,255 +0,0 @@
-import { Subscription } from 'rxjs';
-import { filter } from 'rxjs/operators';
-
-import type { Actions, HistoryState } from './state';
-
-import { Action } from './types';
-import type {
-  NavigateOptions,
-  NavigationListener,
-  NavigationUpdate,
-  Path,
-  To,
-  History,
-  NavigationBlocker,
-} from './types';
-
-/**
- * Abstract base class for history implementations.
- *
- * Provides common state management, navigation logic, and subscription
- * lifecycle that is shared across different history backends (browser,
- * hash, memory).
- */
-export abstract class BaseHistory implements History {
-  // Subscriptions for cleanup
-  #teardowns = new Subscription();
-
-  // internal state
-  #state: HistoryState;
-
-  /**
-   * Gets the current location in the history stack.
-   *
-   * @returns The current {@link Location} including pathname, search, hash, state, and key
-   */
-  public get location(): History['location'] {
-    return this.#state.subject.value.current.location;
-  }
-
-  /**
-   * Gets the current navigation action type.
-   *
-   * @returns The most recent {@link Action} (`Pop`, `Push`, or `Replace`)
-   */
-  public get action(): History['action'] {
-    return this.#state.subject.value.current.action;
-  }
-
-  /**
-   * Observable stream of navigation state changes.
-   * Emits on all navigation events (push, replace, pop).
-   * @returns Observable of the current navigation update.
-   */
-  public get state$(): History['state$'] {
-    return this.#state.subject.select((state) => state.current);
-  }
-
-  /**
-   * Observable stream of navigation actions.
-   * @returns Observable of navigation actions.
-   */
-  public get action$(): History['action$'] {
-    return this.#state.subject.action$;
-  }
-
-  /**
-   * Checks whether there are any active navigation blockers.
-   *
-   * @returns `true` if one or more blockers are registered
-   */
-  public get hasBlockers(): boolean {
-    return this.#state.subject.value.blockers.length > 0;
-  }
-
-  /** @param state - Reactive history state backing this implementation. */
-  protected constructor(state: HistoryState) {
-    this.#state = state;
-  }
-
-  /**
-   * Creates a valid href string for a given path.
-   *
-   * @param to - Target path or partial path object
-   * @returns Fully-qualified href string
-   */
-  public createHref(to: To): string {
-    return this.createURL(to).href;
-  }
-
-  /**
-   * Creates a {@link URL} object for a given path.
-   *
-   * @param to - Target path or partial path object
-   * @returns Resolved {@link URL} instance
-   */
-  public createURL(to: To): URL {
-    return this.#state.stack.createURL(to);
-  }
-
-  /**
-   * 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
-   */
-  public encodeLocation(to: To): Path {
-    return this.#state.stack.createURL(to);
-  }
-
-  /**
-   * Navigate to a location with explicit options.
-   *
-   * @param to - The target path (string, Path object, or Location object)
-   * @param options - Navigation options specifying action (PUSH/REPLACE) and optional state
-   */
-  public navigate(to: To, options: NavigateOptions): void {
-    const action = this.#state.actions.navigate(to, options);
-    this.#state.subject.next(action);
-  }
-
-  /**
-   * Pushes a new location onto the history stack.
-   * @param to - Target path or partial path object.
-   * @param state - Optional state associated with the new location.
-   */
-  public push(to: To, state?: unknown): void {
-    this.navigate(to, { state });
-  }
-
-  /**
-   * Replaces the current location in the history stack.
-   * @param to - Target path or partial path object.
-   * @param state - Optional state associated with the replacement location.
-   */
-  public replace(to: To, state?: unknown): void {
-    this.navigate(to, { replace: true, state });
-  }
-
-  /**
-   * Navigates backward or forward in the history stack.
-   *
-   * @param delta - The number of steps to move (negative for backward, positive for forward)
-   */
-  public go(delta: number): void {
-    const action = this.#state.actions.go(delta);
-    this.#state.subject.next(action);
-  }
-
-  /**
-   * Sets up a listener for navigation changes.
-   *
-   * Only listens for POP actions (browser back/forward navigation). PUSH/REPLACE
-   * actions are programmatic and synchronous - the caller already knows about them.
-   * POP actions come from browser events and are asynchronous, so we need to listen.
-   * This matches industry-standard router behavior (Remix/React Router).
-   *
-   * @param listener - Function to call on navigation changes
-   * @returns Function to unsubscribe the listener
-   */
-  public listen(listener: NavigationListener): () => void {
-    // Filter for POP actions only - PUSH/REPLACE are handled synchronously
-    const subscription = this.#state.subject
-      .select((state) => state.current)
-      .pipe(
-        filter((update): update is NavigationUpdate<Action.Pop> => update.action === Action.Pop),
-      )
-      .subscribe((update) => {
-        listener(update);
-      });
-
-    // Register subscription for cleanup on dispose
-    this._addTeardown(subscription);
-
-    // Return unsubscribe function
-    return () => {
-      subscription.unsubscribe();
-      this._removeTeardown(subscription);
-    };
-  }
-
-  /**
-   * Registers a blocker to intercept navigation attempts.
-   *
-   * @param blocker - Navigation blocker function to register
-   * @returns Function to unsubscribe the blocker
-   */
-  public block(blocker: NavigationBlocker): VoidFunction {
-    this.#state.subject.next(this.#state.actions.addBlocker(blocker));
-    const removeBlocker = () => {
-      this.#state.subject.next(this.#state.actions.removeBlocker(blocker));
-    };
-    return this._addTeardown(removeBlocker, { executeOnRemove: true });
-  }
-
-  /** Triggers a POP action for the current history location. */
-  public pop(): void {
-    this.#state.subject.next(this.#state.actions.pop());
-  }
-
-  /**
-   * Disposes of the history instance and cleans up all subscriptions.
-   */
-  public [Symbol.dispose](): void {
-    this.#teardowns.unsubscribe();
-  }
-
-  /**
-   * Dispatches an action to trigger state updates.
-   *
-   * Use this to dispatch actions when external events occur (e.g., browser popstate).
-   * The action will be processed by flows and update the history state.
-   *
-   * @param action - The action to dispatch
-   */
-  protected _dispatch(action: Actions): void {
-    this.#state.subject.next(action);
-  }
-
-  /**
-   * Registers a cleanup function or subscription for automatic disposal.
-   *
-   * All teardowns are automatically cleaned up when the history instance is disposed.
-   * Use `executeOnRemove: true` if the teardown should run when manually removed.
-   *
-   * @param teardown - Function or subscription to clean up
-   * @param options - Optional configuration
-   * @param options.executeOnRemove - Execute teardown when removed (default: false)
-   * @returns Function to manually remove the teardown
-   */
-  protected _addTeardown(
-    teardown: VoidFunction | Subscription,
-    options?: { executeOnRemove: boolean },
-  ): VoidFunction {
-    this.#teardowns.add(teardown);
-    return () => {
-      // Execute teardown callbacks immediately when callers explicitly request removal side effects.
-      if (options?.executeOnRemove) {
-        typeof teardown === 'function' ? teardown() : teardown.unsubscribe();
-      }
-      return this._removeTeardown(teardown);
-    };
-  }
-
-  /**
-   * Removes a teardown from the cleanup collection.
-   *
-   * Typically called automatically by the function returned from `_addTeardown`.
-   * Only call directly if you need to remove a teardown without executing it.
-   *
-   * @param teardown - The teardown to remove
-   */
-  protected _removeTeardown(teardown: VoidFunction | Subscription) {
-    this.#teardowns.remove(teardown);
-  }
-}

package/src/lib/BrowserHistory.ts

@@ -1,124 +0,0 @@
-import { fromEvent } from 'rxjs';
-import { map } from 'rxjs/operators';
-import { BaseHistory } from './BaseHistory';
-import { BrowserHistoryStack } from './BrowserHistoryStack';
-import { BrowserHistoryHashStack } from './BrowserHistoryHashStack';
-import { resolveWindowLocation } from './utils';
-import { Action, type HistoryStack, type NavigationBlocker } from './types';
-import { createStore, createHistoryReducer, actions } from './state';
-
-/**
- * Handler for beforeunload events.
- * Prevents page unload when navigation blockers are active.
- */
-const onBeforeUnload = (event: BeforeUnloadEvent) => {
-  event.preventDefault();
-  event.returnValue = '';
-};
-/**
- * Constructor for a HistoryStack implementation.
- *
- * @param window - The window object to use for history operations
- * @returns A new instance of the HistoryStack implementation
- */
-export interface StackConstructor {
-  new (window: Window): HistoryStack;
-}
-
-/**
- * Options for configuring a BrowserHistory instance.
- */
-export type BrowserHistoryOptions = {
-  /** Optional window object (defaults to global window) */
-  window?: Window;
-  /** Optional stack constructor (defaults to BrowserHistoryStack, use BrowserHistoryHashStack for hash routing) */
-  stack?: StackConstructor;
-};
-
-/**
- * Browser history implementation using native browser APIs.
- *
- * Uses the browser's History API (pushState/replaceState) for navigation.
- * Automatically listens for popstate/hashchange events to detect browser back/forward navigation.
- * Compatible with industry-standard routers (Remix/React Router).
- */
-export class BrowserHistory extends BaseHistory {
-  #window: Window;
-  /**
-   * Creates a browser history instance.
-   *
-   * Initializes with the current window location and sets up listeners for
-   * browser navigation events (popstate for regular routing, hashchange for hash routing).
-   *
-   * @param options - Configuration options
-   * @param options.window - Window object to use (defaults to global window)
-   * @param options.stack - Stack implementation (defaults to BrowserHistoryStack, use BrowserHistoryHashStack for hash routing)
-   * @throws {Error} If window is not available
-   */
-  constructor(options: BrowserHistoryOptions = {}) {
-    // Use provided stack or default to BrowserHistoryStack
-    const Stack: StackConstructor = options.stack ?? BrowserHistoryStack;
-    const browserWindow = options.window ?? document.defaultView;
-    // Fail fast without a window since the browser stack depends on the DOM history API.
-    if (!browserWindow) {
-      throw new Error('Window is required');
-    }
-
-    // Initialize state with current window location
-    const state = createStore(
-      new Stack(browserWindow),
-      createHistoryReducer({
-        delta: 0,
-        action: Action.Pop,
-        location: resolveWindowLocation(browserWindow, browserWindow.history),
-      }),
-    );
-    super(state);
-
-    this.#window = browserWindow;
-
-    // Determine event type based on stack implementation
-    // Hash routing uses 'hashchange', regular routing uses 'popstate'
-    const isHashHistory = state.stack instanceof BrowserHistoryHashStack;
-    const eventName = isHashHistory ? 'hashchange' : 'popstate';
-
-    // Listen for browser navigation events and dispatch POP actions
-    // This handles browser back/forward button clicks
-    this._addTeardown(
-      fromEvent(browserWindow, eventName)
-        .pipe(
-          map(() => {
-            const location = state.stack.current;
-            return actions.pop({ delta: 0, action: Action.Pop, location });
-          }),
-        )
-        .subscribe(this._dispatch.bind(this)),
-    );
-  }
-
-  /**
-   * Registers a blocker to intercept navigation attempts.
-   *
-   * Adds a beforeunload event listener when blockers are active to prevent
-   * page unload (e.g., when user tries to close the tab). This provides
-   * browser-level protection in addition to in-app navigation blocking.
-   *
-   * @param blocker - Navigation blocker function to register
-   * @returns Function to unsubscribe the blocker
-   */
-  public override block(blocker: NavigationBlocker): VoidFunction {
-    const unblock = super.block(blocker);
-    // Add beforeunload listener when blockers are active
-    // This shows browser's "Leave site?" dialog on page unload
-    if (this.hasBlockers) {
-      window.addEventListener('beforeunload', onBeforeUnload);
-    }
-    return () => {
-      unblock();
-      // Remove beforeunload listener if no blockers remain
-      if (this.hasBlockers) {
-        window.removeEventListener('beforeunload', onBeforeUnload);
-      }
-    };
-  }
-}