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

package/src/lib/BrowserHistory.ts

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

package/src/lib/BrowserHistoryHashStack.ts

@@ -0,0 +1,56 @@
+import { BrowserHistoryStack } from './BrowserHistoryStack';
+import type { Location, To } from './types';
+import { resolveHashLocation, resolvePath, pathToString } from './utils';
+
+/**
+ * Browser history hash stack implementation using hash-based routing.
+ *
+ * Uses URL hash fragment (#) instead of pathname. The hash is not sent to the server,
+ * allowing routing without server configuration.
+ *
+ * @example
+ * ```ts
+ * // Regular routing: https://example.com/users
+ * // Hash routing: https://example.com/#/users
+ * const stack = new BrowserHistoryHashStack(window);
+ * ```
+ */
+export class BrowserHistoryHashStack extends BrowserHistoryStack {
+  /**
+   * Gets the current location from window.location.hash.
+   */
+  public get current(): Readonly<Location> {
+    return resolveHashLocation(this._window);
+  }
+
+  /**
+   * Creates a URL object for a given path with hash-based routing.
+   *
+   * Uses the current window location as the base and only modifies the hash fragment.
+   * The path is normalized to ensure it starts with '#' if not already present.
+   *
+   * @param to - The target path (string, Path object, or Location object)
+   * @returns A URL object with the path in the hash fragment
+   *
+   * @example
+   * ```ts
+   * // If current URL is 'https://example.com/app'
+   * createURL('/users?id=1')
+   * // URL { href: 'https://example.com/app#/users?id=1', ... }
+   *
+   * createURL({ pathname: '/dashboard', search: '?tab=settings' })
+   * // URL { href: 'https://example.com/app#/dashboard?tab=settings', ... }
+   * ```
+   */
+  public override createURL(to: To): URL {
+    const path = resolvePath(to);
+    const fullPath = pathToString(path);
+    // Normalize: ensure path starts with '#' for hash routing
+    const hashPath = fullPath.startsWith('#') ? fullPath : `#${fullPath}`;
+    // Use current location as base, only modify hash
+    const url = new URL(this._window.location.href, this.origin);
+    url.hash = hashPath;
+
+    return url;
+  }
+}

package/src/lib/BrowserHistoryStack.ts

@@ -0,0 +1,82 @@
+import { pathToString, resolvePath, resolveWindowLocation } from './utils';
+import type { HistoryStack, Location, To } from './types';
+
+/**
+ * Browser history stack implementation using native browser APIs.
+ *
+ * Manages navigation state using the browser's History API (pushState/replaceState).
+ * Stores location state in history.state and uses relative paths for navigation.
+ * This is the base implementation for regular (non-hash) routing.
+ *
+ * @example
+ * ```ts
+ * const stack = new BrowserHistoryStack(window);
+ * stack.push({ pathname: '/users', key: 'abc123', state: { userId: 1 } });
+ * // Updates URL to /users and adds entry to history
+ * ```
+ */
+export class BrowserHistoryStack implements HistoryStack {
+  /**
+   * @param _window - The window object to use for history operations
+   */
+  public constructor(protected readonly _window: Window) {}
+
+  /**
+   * Gets the origin of the history stack.
+   */
+  public get origin(): string {
+    return this._window.location.origin;
+  }
+
+  /**
+   * Gets the current location.
+   */
+  public get current(): Location {
+    return resolveWindowLocation(this._window);
+  }
+
+  /**
+   * Pushes a new entry onto the history stack.
+   */
+  public push(location: Location): void {
+    this.navigate(location, 'PUSH');
+  }
+
+  /**
+   * Replaces the current entry in the history stack.
+   */
+  public replace(location: Location): void {
+    this.navigate(location, 'REPLACE');
+  }
+
+  /**
+   * Navigates to a location with the specified action.
+   */
+  public navigate(location: Location, action: 'PUSH' | 'REPLACE'): void {
+    const relativePath = this._createRelativePath(location);
+    const state = { value: location.state, key: location.key };
+    if (action === 'PUSH') {
+      this._window.history.pushState(state, '', relativePath);
+    } else {
+      this._window.history.replaceState(state, '', relativePath);
+    }
+  }
+
+  /**
+   * Navigates backward or forward in the history stack.
+   */
+  public go(delta: number): void {
+    this._window.history.go(delta);
+  }
+
+  /**
+   * Creates a URL object for a given path.
+   */
+  public createURL(to: To): URL {
+    return new URL(pathToString(resolvePath(to)), this.origin);
+  }
+
+  protected _createRelativePath(to: To): string {
+    return pathToString(this.createURL(to));
+  }
+}

package/src/lib/MemoryHistory.ts

@@ -0,0 +1,66 @@
+import { type To, type LocationState, type NavigationUpdate, Action } from './types';
+import { pathToString, resolvePath } from './utils';
+import { MemoryHistoryStack } from './MemoryStack';
+import { BaseHistory } from './BaseHistory';
+import { createHistoryReducer, createStore } from './state';
+
+/**
+ * Default initial location for memory history.
+ */
+const defaultInitialLocation: NavigationUpdate = {
+  delta: 0,
+  action: Action.Pop,
+  location: { pathname: '/', search: '', hash: '', key: 'unknown', state: null },
+};
+
+/**
+ * Options for configuring a MemoryHistory instance.
+ */
+export type MemoryHistoryOptions = {
+  /** Optional initial location */
+  initialLocation?: NavigationUpdate;
+  /** Optional initial history entries */
+  initialHistory?: NavigationUpdate[];
+};
+
+/**
+ * Memory history implementation using in-memory storage.
+ *
+ * Useful for:
+ * - Testing: Control navigation state in tests without browser APIs
+ * - SSR: Server-side rendering where window is not available
+ * - Widgets: Serving applications as widgets without affecting the main browser history
+ * - Node.js environments: Environments without browser APIs
+ */
+export class MemoryHistory extends BaseHistory {
+  public constructor(options?: MemoryHistoryOptions) {
+    const { initialLocation, initialHistory } = options ?? {};
+    const initial = initialLocation ?? defaultInitialLocation;
+
+    // create initial state for memory history
+    const initialState: LocationState = {
+      current: initial,
+      history: initialHistory ?? [initial],
+      blockers: [],
+    };
+
+    // create stack for memory history
+    const stack = new MemoryHistoryStack({ initialLocation: initialState.current.location });
+
+    // initialize state with stack and reducer
+    const state = createStore(
+      stack,
+      createHistoryReducer(() => initialState, { maxHistory: 100 }),
+    );
+
+    super(state);
+  }
+
+  /**
+   * Creates a URL object for a given path using memory:// origin.
+   */
+  public createURL(to: To): URL {
+    const path = pathToString(resolvePath(to));
+    return new URL(path, 'memory://');
+  }
+}

package/src/lib/MemoryStack.ts

@@ -0,0 +1,106 @@
+import type { HistoryStack, Location, LocationState, To } from './types';
+import { pathToString, resolvePath } from './utils';
+
+/**
+ * Memory-based history stack implementation.
+ *
+ * Stores navigation state in memory instead of using browser APIs.
+ * Unlike BrowserHistoryStack, push/replace only update the current location
+ * (history entries are managed by the reducer, not the stack).
+ */
+export class MemoryHistoryStack implements HistoryStack {
+  #current: Location;
+
+  /**
+   * Gets the origin of the history stack.
+   * Always returns 'memory://' for in-memory storage.
+   */
+  get origin(): string {
+    return 'memory://';
+  }
+
+  /**
+   * Gets the current location.
+   */
+  get current(): Location {
+    return this.#current;
+  }
+
+  /**
+   * Creates a memory history stack instance.
+   *
+   * @param options - Configuration options
+   * @param options.initialLocation - Optional initial location (defaults to '/')
+   */
+  constructor(options?: { initialLocation?: Location }) {
+    this.#current = options?.initialLocation ?? {
+      pathname: '/',
+      search: '',
+      hash: '',
+      state: null,
+      key: '',
+    };
+  }
+
+  /**
+   * Pushes a new entry onto the history stack.
+   *
+   * Only updates the current location. History entries are managed by the reducer.
+   */
+  push(location: Location): void {
+    this.#current = location;
+  }
+
+  /**
+   * Replaces the current entry in the history stack.
+   *
+   * Only updates the current location. History entries are managed by the reducer.
+   */
+  replace(location: Location): void {
+    this.#current = location;
+  }
+
+  /**
+   * Navigates backward or forward in the history stack.
+   *
+   * Uses the history state to find the target location by index.
+   * Clamps to valid range (first or last entry if out of bounds).
+   *
+   * @param delta - Number of steps to move (negative for back, positive for forward)
+   * @param state - Current location state with history entries
+   */
+  go(delta: number, state: Readonly<LocationState>): void {
+    const { history, current } = state;
+    const currentLocation = current.location ?? this.#current;
+    // Find current location in history by key
+    const currentIndex = history.findIndex((entry) => entry.location.key === currentLocation.key);
+
+    // If current location not found, use last entry
+    if (currentIndex === -1) {
+      if (history.length > 0) {
+        this.#current = history[history.length - 1].location;
+      }
+      return;
+    }
+
+    // Calculate target index and clamp to valid range
+    const newIndex = currentIndex + delta;
+    if (newIndex < 0) {
+      this.#current = state.history[0].location;
+    } else if (newIndex >= state.history.length) {
+      this.#current = state.history[state.history.length - 1].location;
+    } else {
+      this.#current = state.history[newIndex].location;
+    }
+  }
+
+  /**
+   * Creates a URL object for a given path.
+   *
+   * All URLs use the 'memory://' origin since this is in-memory storage.
+   */
+  createURL(to: To): URL {
+    const path = resolvePath(to);
+    return new URL(pathToString(path), this.origin);
+  }
+}

package/src/lib/create-history.ts

@@ -0,0 +1,63 @@
+import { MemoryHistory, type MemoryHistoryOptions } from './MemoryHistory';
+import { BrowserHistory, type BrowserHistoryOptions } from './BrowserHistory';
+import { BrowserHistoryStack } from './BrowserHistoryStack';
+import { BrowserHistoryHashStack } from './BrowserHistoryHashStack';
+
+type HistoryCtorMap = {
+  memory: (options?: MemoryHistoryOptions) => MemoryHistory;
+  browser: (options?: Omit<BrowserHistoryOptions, 'stack'>) => BrowserHistory;
+  hash: (options?: Omit<BrowserHistoryOptions, 'stack'>) => BrowserHistory;
+};
+
+/**
+ * Creates a history instance based on the specified type.
+ *
+ * Factory function for creating different history implementations:
+ * - `'browser'`: Creates a {@link BrowserHistory} instance using regular routing (pathname-based)
+ * - `'hash'`: Creates a {@link BrowserHistory} instance using hash routing (hash-based)
+ * - `'memory'`: Creates a {@link MemoryHistory} instance for testing or SSR (in-memory)
+ *
+ * All returned instances are compatible with industry-standard routers (Remix/React Router).
+ *
+ * @param type - The type of history to create ('browser', 'hash', or 'memory')
+ * @param args - Optional arguments for the history type
+ * @returns A History instance compatible with industry-standard routers (Remix/React Router)
+ *
+ * @example
+ * ```ts
+ * // Regular browser routing
+ * const history = createHistory('browser');
+ *
+ * // Hash-based routing
+ * const hashHistory = createHistory('hash');
+ *
+ * // In-memory history for testing
+ * const memoryHistory = createHistory('memory', { initialLocation: { ... } });
+ * ```
+ */
+export const createHistory = <T extends keyof HistoryCtorMap>(
+  type: T,
+  ...args: Parameters<HistoryCtorMap[T]>
+): ReturnType<HistoryCtorMap[T]> => {
+  switch (type) {
+    case 'memory':
+      return new MemoryHistory(...(args as [MemoryHistoryOptions])) as ReturnType<
+        HistoryCtorMap[T]
+      >;
+    case 'browser': {
+      const options = args[0] as Omit<BrowserHistoryOptions, 'stack'>;
+      return new BrowserHistory({ ...options, stack: BrowserHistoryStack }) as ReturnType<
+        HistoryCtorMap[T]
+      >;
+    }
+    case 'hash': {
+      const options = args[0] as Omit<BrowserHistoryOptions, 'stack'>;
+      return new BrowserHistory({ ...options, stack: BrowserHistoryHashStack }) as ReturnType<
+        HistoryCtorMap[T]
+      >;
+    }
+    default: {
+      throw new Error(`Invalid history type: ${type}`);
+    }
+  }
+};

package/src/lib/index.ts

@@ -1 +1,22 @@
-export * from './provider';
+// History implementations
+export { BaseHistory } from './BaseHistory';
+export { BrowserHistory } from './BrowserHistory';
+export { MemoryHistory } from './MemoryHistory';
+
+// History stacks
+export { BrowserHistoryStack } from './BrowserHistoryStack';
+export { BrowserHistoryHashStack as HashHistoryStack } from './BrowserHistoryHashStack';
+export { MemoryHistoryStack } from './MemoryStack';
+
+// Types
+export type {
+  Action,
+  History,
+  HistoryStack,
+  Location,
+  NavigateOptions,
+  NavigationListener,
+  NavigationUpdate,
+  Path,
+  To,
+} from './types';

package/src/lib/state/history.actions.ts

@@ -0,0 +1,108 @@
+import { createAction, createAsyncAction } from '@equinor/fusion-observable/actions';
+import type { ActionTypes } from '@equinor/fusion-observable/actions';
+import { v7 as generateId } from 'uuid';
+import type { To, NavigateOptions, NavigationBlocker, NavigationUpdate } from '../types';
+
+/**
+ * Action for navigating to a new location (push or replace).
+ */
+const navigateAction = createAsyncAction(
+  'navigation/navigate',
+  (to: To, options: NavigateOptions) => ({
+    payload: { to, options },
+    meta: { key: generateId() },
+  }),
+  (update: NavigationUpdate) => ({
+    payload: { update },
+  }),
+  (error: Error) => ({
+    payload: { error },
+  }),
+);
+
+const abortNavigateAction = createAction('navigation/navigate::abort', (reason?: string) => ({
+  payload: { reason },
+}));
+
+/**
+ * Action for navigating backward or forward in history.
+ */
+const goDeltaAction = createAsyncAction(
+  'navigation/go',
+  (delta: number) => ({
+    payload: { delta },
+  }),
+  (update: NavigationUpdate) => ({
+    payload: { update },
+  }),
+  (error: Error) => ({
+    payload: { error },
+  }),
+);
+
+/**
+ * Action for handling browser back/forward navigation (popstate events).
+ */
+const popStateAction = createAsyncAction(
+  'navigation/pop',
+  (update?: NavigationUpdate) => ({
+    payload: { update },
+  }),
+  (update: NavigationUpdate) => ({
+    payload: { update },
+  }),
+  (error: Error) => ({
+    payload: { error },
+  }),
+);
+
+/**
+ * Action for validating the current location against history state.
+ */
+const validateLocationAction = createAsyncAction(
+  'navigation/navigationValidation',
+  () => ({
+    payload: {},
+  }),
+  (update: NavigationUpdate) => ({
+    payload: { update },
+  }),
+  (error: Error) => ({
+    payload: { error },
+  }),
+);
+
+/**
+ * Action for adding a navigation blocker.
+ */
+const addBlockerAction = createAction('navigation/addBlocker', (blocker: NavigationBlocker) => ({
+  payload: { blocker },
+}));
+
+/**
+ * Action for removing a navigation blocker.
+ */
+const removeBlockerAction = createAction(
+  'navigation/removeBlocker',
+  (blocker: NavigationBlocker) => ({
+    payload: { blocker },
+  }),
+);
+
+/**
+ * Navigation actions for history state management.
+ */
+export const actions = {
+  navigate: navigateAction,
+  abortNavigate: abortNavigateAction,
+  go: goDeltaAction,
+  pop: popStateAction,
+  validateLocation: validateLocationAction,
+  addBlocker: addBlockerAction,
+  removeBlocker: removeBlockerAction,
+};
+
+/**
+ * Union type of all navigation actions.
+ */
+export type Actions = ActionTypes<typeof actions>;