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

package/src/__tests__/MemoryHistory.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { firstValueFrom, skip } from 'rxjs';
+import { MemoryHistory } from '../lib/MemoryHistory';
+
+describe('MemoryHistory', () => {
+  let history: MemoryHistory;
+
+  beforeEach(() => {
+    history = new MemoryHistory();
+  });
+
+  afterEach(() => {
+    history[Symbol.dispose]();
+  });
+
+  describe('initialization', () => {
+    it('should initialize with default location', () => {
+      expect(history.location.pathname).toBe('/');
+      expect(history.action).toBe('POP');
+    });
+
+    it('should initialize with custom initial location', () => {
+      const customHistory = new MemoryHistory({
+        initialLocation: {
+          action: 'POP',
+          location: {
+            pathname: '/custom',
+            search: '',
+            hash: '',
+            key: 'custom-key',
+            state: { test: 'value' },
+          },
+        },
+      });
+
+      expect(customHistory.location.pathname).toBe('/custom');
+      expect(customHistory.location.state).toEqual({ test: 'value' });
+      expect(customHistory.action).toBe('POP');
+
+      customHistory[Symbol.dispose]();
+    });
+  });
+
+  describe('in-memory navigation', () => {
+    it('should push without affecting browser', async () => {
+      const initialPathname = window.location.pathname;
+      const initialHash = window.location.hash;
+
+      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' });
+      // Browser should not be affected
+      expect(window.location.pathname).toBe(initialPathname);
+      expect(window.location.hash).toBe(initialHash);
+    });
+
+    it('should replace without affecting browser', async () => {
+      const initialPathname = window.location.pathname;
+      const initialHash = window.location.hash;
+
+      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 });
+      // Browser should not be affected
+      expect(window.location.pathname).toBe(initialPathname);
+      expect(window.location.hash).toBe(initialHash);
+    });
+
+    it('should maintain in-memory history stack', async () => {
+      // Push multiple entries
+      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');
+
+      history.push('/page3', { page: 3 });
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page3');
+
+      // Go back
+      const goBackPromise1 = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(-1);
+      await goBackPromise1;
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 2 });
+
+      // Go back again
+      const goBackPromise2 = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(-1);
+      await goBackPromise2;
+      expect(history.location.pathname).toBe('/page1');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 1 });
+
+      // Go forward
+      const goForwardPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(1);
+      await goForwardPromise;
+      expect(history.location.pathname).toBe('/page2');
+      expect(history.action).toBe('POP');
+      expect(history.location.state).toEqual({ page: 2 });
+    });
+
+    it('should clamp go() to history bounds', async () => {
+      history.push('/page1');
+      await firstValueFrom(history.state$.pipe(skip(1)));
+      expect(history.location.pathname).toBe('/page1');
+
+      // Try to go back beyond start
+      const goBackPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(-10);
+      await goBackPromise;
+      // Should clamp to first entry
+      expect(history.location.pathname).toBe('/');
+      expect(history.action).toBe('POP');
+
+      // Try to go forward beyond end
+      const goForwardPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(10);
+      await goForwardPromise;
+      // Should clamp to last entry
+      expect(history.location.pathname).toBe('/page1');
+      expect(history.action).toBe('POP');
+    });
+  });
+
+  describe('createURL', () => {
+    it('should create URLs with memory:// protocol', () => {
+      const url = history.createURL('/test');
+      expect(url.protocol).toBe('memory:');
+      expect(url.pathname).toBe('/test');
+      expect(url.href).toContain('memory://');
+    });
+
+    it('should create URLs with search and hash', () => {
+      const url = history.createURL('/test?query=1#section');
+      expect(url.protocol).toBe('memory:');
+      expect(url.pathname).toBe('/test');
+      expect(url.search).toBe('?query=1');
+      expect(url.hash).toBe('#section');
+      expect(url.href).toContain('memory://');
+    });
+  });
+
+  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' });
+    });
+
+    it('should emit state updates on go()', 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');
+
+      const goPromise = firstValueFrom(history.state$.pipe(skip(1)));
+      history.go(-1);
+      const update = await goPromise;
+
+      expect(update.action).toBe('POP');
+      expect(update.location.pathname).toBe('/page1');
+    });
+  });
+});

package/src/__tests__/NavigationProvider.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NavigationProvider } from '../NavigationProvider';
+import { MemoryHistory } from '../lib/MemoryHistory';
+import type { INavigationConfigurator } from '../NavigationConfigurator.interface';
+import type { History } from '../lib/types';
+
+describe('NavigationProvider', () => {
+  let history: History;
+  let provider: NavigationProvider;
+  let config: INavigationConfigurator;
+
+  beforeEach(() => {
+    history = new MemoryHistory();
+    config = { history };
+    provider = new NavigationProvider({
+      version: '1.0.0',
+      config,
+    });
+  });
+
+  afterEach(() => {
+    provider?.dispose();
+    history[Symbol.dispose]();
+  });
+
+  it('should have version', () => {
+    expect(provider.version).toBeDefined();
+    expect(provider.version.toString()).toBe('1.0.0');
+  });
+
+  it('should have history property', () => {
+    expect(provider.history).toBe(history);
+  });
+
+  it('should have path property', () => {
+    expect(provider.path).toBeDefined();
+    expect(provider.path.pathname).toBeDefined();
+  });
+
+  it('should have state$ observable', () => {
+    expect(provider.state$).toBeDefined();
+    expect(typeof provider.state$.subscribe).toBe('function');
+  });
+
+  it('should throw error if no history provided', () => {
+    config = {};
+    expect(() => {
+      new NavigationProvider({
+        version: '1.0.0',
+        config,
+      });
+    }).toThrow('no history provided!');
+  });
+
+  it('should dispose correctly', () => {
+    const disposeSpy = vi.spyOn(history as { [Symbol.dispose]: () => void }, Symbol.dispose);
+    provider.dispose();
+    expect(disposeSpy).toHaveBeenCalled();
+  });
+});

package/src/__tests__/setup.ts

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

package/src/enable-navigation.ts

@@ -0,0 +1,59 @@
+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) {
+      if (typeof basenameOrOptions === 'string') {
+        config.setBasename(basenameOrOptions);
+      } else if (typeof basenameOrOptions === 'object' && 'configure' in basenameOrOptions) {
+        basenameOrOptions.configure(config, ref);
+      }
+    },
+  });
+};
+
+export default enableNavigation;

package/src/events.ts

@@ -0,0 +1,65 @@
+import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
+
+import type { INavigationProvider } from './NavigationProvider.interface';
+import type { Action, NavigationUpdate, Path } from './lib/types';
+
+/**
+ * Event detail for navigation events (before navigation).
+ */
+export interface NavigateEventDetail {
+  /** The target path or location to navigate to */
+  location: NavigationUpdate;
+  /** Optional current location before navigation */
+  currentLocation?: Path;
+}
+
+/**
+ * Event emitted before navigation occurs.
+ * Can be canceled by calling `preventDefault()`.
+ */
+export class NavigateEvent extends FrameworkEvent<
+  FrameworkEventInit<NavigateEventDetail, INavigationProvider>
+> {
+  constructor(detail: NavigateEventDetail, source: INavigationProvider) {
+    super('onNavigate', {
+      detail,
+      source,
+    });
+  }
+}
+
+/**
+ * Event detail for navigated events (after navigation).
+ */
+export interface NavigatedEventDetail {
+  /** The navigation action that occurred (PUSH, POP, REPLACE) */
+  action: Action;
+  /** The new location after navigation */
+  current: NavigationUpdate;
+  /** The previous location before navigation */
+  previous: NavigationUpdate;
+}
+
+/**
+ * Event emitted after navigation occurs.
+ * Contains the navigation action and location details.
+ */
+export class NavigatedEvent extends FrameworkEvent<
+  FrameworkEventInit<NavigatedEventDetail, INavigationProvider>
+> {
+  constructor(detail: NavigatedEventDetail, source: INavigationProvider) {
+    super('onNavigated', { detail, source });
+  }
+}
+
+/**
+ * Declares navigation events in the FrameworkEventMap for type safety.
+ */
+declare module '@equinor/fusion-framework-module-event' {
+  interface FrameworkEventMap {
+    /** Event emitted before navigation occurs, can be canceled to prevent navigation */
+    onNavigate: NavigateEvent;
+    /** Event emitted after navigation occurs */
+    onNavigated: NavigatedEvent;
+  }
+}

package/src/index.ts

@@ -1,10 +1,31 @@
-export type { Action, Path } from '@remix-run/router';
+export type { INavigationConfigurator } from './NavigationConfigurator.interface';
+export { NavigationConfigurator } from './NavigationConfigurator';
 
-export { INavigationConfigurator, NavigationConfigurator } from './configurator';
+export { NavigationModule, module, moduleKey } from './module';
+export { enableNavigation } from './enable-navigation';
 
-export { NavigationModule, enableNavigation, module, moduleKey } from './module';
+export type { INavigationProvider } from './NavigationProvider.interface';
+export { NavigationProvider } from './NavigationProvider';
 
-export { createHistory } from './createHistory';
+export { createHistory } from './lib/create-history';
 
-export * from './lib';
-export * from './types';
+export {
+  NavigateEvent,
+  NavigatedEvent,
+  type NavigateEventDetail,
+  type NavigatedEventDetail,
+} from './events';
+
+export type {
+  Path,
+  To,
+  Location,
+  History,
+  NavigationBlocker,
+  NavigationListener,
+} from './lib/types';
+
+/**
+ * @deprecated use History instead
+ */
+export type { History as INavigator } from './lib';

package/src/lib/BaseHistory.ts

@@ -0,0 +1,229 @@
+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 and navigation logic that can be shared
+ * across different history implementations (browser, memory, etc.).
+ */
+export abstract class BaseHistory implements History {
+  // Subscriptions for cleanup
+  #teardowns = new Subscription();
+
+  // internal state
+  #state: HistoryState;
+
+  /**
+   * Gets the current location.
+   */
+  public get location(): History['location'] {
+    return this.#state.subject.value.current.location;
+  }
+
+  /**
+   * Gets the current action.
+   */
+  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).
+   */
+  public get state$(): History['state$'] {
+    return this.#state.subject.select((state) => state.current);
+  }
+
+  /**
+   * Observable stream of navigation actions.
+   */
+  public get action$(): History['action$'] {
+    return this.#state.subject.action$;
+  }
+
+  /**
+   * Checks if there are any active navigation blockers.
+   */
+  public get hasBlockers(): boolean {
+    return this.#state.subject.value.blockers.length > 0;
+  }
+
+  protected constructor(state: HistoryState) {
+    this.#state = state;
+  }
+
+  /**
+   * Creates a valid href string for a given path.
+   */
+  public createHref(to: To): string {
+    return this.createURL(to).href;
+  }
+
+  /**
+   * Creates a URL object for a given path.
+   */
+  public createURL(to: To): URL {
+    return this.#state.stack.createURL(to);
+  }
+
+  /**
+   * Encodes a location by properly URL-encoding the pathname.
+   */
+  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.
+   */
+  public push(to: To, state?: unknown): void {
+    this.navigate(to, { state });
+  }
+
+  /**
+   * Replaces the current location in the history stack.
+   */
+  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 });
+  }
+
+  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 () => {
+      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);
+  }
+}