@equinor/fusion-framework-module-navigation 7.0.9 → 7.0.10

package/src/lib/BrowserHistoryHashStack.ts

@@ -1,57 +0,0 @@
-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.
-   * @returns The current hash-derived navigation location.
-   */
-  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

@@ -1,96 +0,0 @@
-import { pathToString, resolvePath, resolveWindowLocation } from './utils';
-import type { HistoryStack, Location, To } from './types';
-
-/**
- * Browser history stack implementation using the native History API.
- *
- * Manages navigation state via `pushState` / `replaceState` and stores
- * location state in `history.state`. This is the default stack for
- * pathname-based (non-hash) routing.
- *
- * @example
- * ```ts
- * const stack = new BrowserHistoryStack(window);
- * stack.push({ pathname: '/users', search: '', hash: '', key: 'abc', state: null });
- * ```
- */
-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.
-   * @returns The browser origin used as the URL base.
-   */
-  public get origin(): string {
-    return this._window.location.origin;
-  }
-
-  /**
-   * Gets the current location.
-   * @returns The current browser location converted to a navigation location.
-   */
-  public get current(): Location {
-    return resolveWindowLocation(this._window);
-  }
-
-  /**
-   * Pushes a new entry onto the history stack.
-   * @param location - Location to append to browser history.
-   */
-  public push(location: Location): void {
-    this.navigate(location, 'PUSH');
-  }
-
-  /**
-   * Replaces the current entry in the history stack.
-   * @param location - Location to replace in browser history.
-   */
-  public replace(location: Location): void {
-    this.navigate(location, 'REPLACE');
-  }
-
-  /**
-   * Navigates to a location with the specified action.
-   * @param location - Location to navigate to.
-   * @param action - Native history action to perform.
-   */
-  public navigate(location: Location, action: 'PUSH' | 'REPLACE'): void {
-    const relativePath = this._createRelativePath(location);
-    const state = { value: location.state, key: location.key };
-    // Select the native operation matching the requested navigation action.
-    if (action === 'PUSH') {
-      this._window.history.pushState(state, '', relativePath);
-    } else {
-      this._window.history.replaceState(state, '', relativePath);
-    }
-  }
-
-  /**
-   * Navigates backward or forward in the history stack.
-   * @param delta - Number of entries to move backward or forward.
-   */
-  public go(delta: number): void {
-    this._window.history.go(delta);
-  }
-
-  /**
-   * Creates a URL object for a given path.
-   * @param to - Target path or partial path object.
-   * @returns URL resolved against the browser origin.
-   */
-  public createURL(to: To): URL {
-    return new URL(pathToString(resolvePath(to)), this.origin);
-  }
-
-  /**
-   * Creates the relative URL path used by native browser history.
-   * @param to - Target path or partial path object.
-   * @returns Relative URL path for browser history.
-   */
-  protected _createRelativePath(to: To): string {
-    return pathToString(this.createURL(to));
-  }
-}

package/src/lib/MemoryHistory.ts

@@ -1,76 +0,0 @@
-import { type To, type LocationState, type NavigationUpdate, Action } from './types';
-import { pathToString, resolvePath } from './utils';
-import { MemoryHistoryStack } from './MemoryHistoryStack';
-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,
-    unstable_mask: undefined,
-  },
-};
-
-/**
- * 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.
- *
- * Does not touch browser APIs, making it suitable for:
- * - **Testing** — deterministic navigation state without a DOM
- * - **SSR** — server-side rendering where `window` is unavailable
- * - **Widgets** — embedded apps that must not alter the host page URL
- * - **Node.js** — any environment without browser history APIs
- */
-export class MemoryHistory extends BaseHistory {
-  /** @param options - Optional initial location and history entries. */
-  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.
-   * @param to - Target path or partial path object.
-   * @returns URL resolved against memory://.
-   */
-  public createURL(to: To): URL {
-    const path = pathToString(resolvePath(to));
-    return new URL(path, 'memory://');
-  }
-}

package/src/lib/MemoryHistoryStack.ts

@@ -1,118 +0,0 @@
-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.
-   * @returns The fixed origin used for in-memory URLs.
-   */
-  get origin(): string {
-    return 'memory://';
-  }
-
-  /**
-   * Gets the current location.
-   * @returns The current in-memory navigation 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: '',
-      unstable_mask: undefined,
-    };
-  }
-
-  /**
-   * Pushes a new entry onto the history stack.
-   *
-   * Only updates the current location. History entries are managed by the reducer.
-   * @param location - Location to make current.
-   */
-  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.
-   * @param location - Location to make current.
-   */
-  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
-    // Locate the current entry so relative navigation can preserve stack boundaries.
-    const currentIndex = history.findIndex((entry) => entry.location.key === currentLocation.key);
-
-    // If current location not found, use last entry
-    // Fall back to the newest entry when the stack cannot identify the current location.
-    if (currentIndex === -1) {
-      // Restore the latest known entry when the history cannot locate the current key.
-      if (history.length > 0) {
-        this.#current = history[history.length - 1].location;
-      }
-      return;
-    }
-
-    // Calculate target index and clamp to valid range
-    const newIndex = currentIndex + delta;
-    // Clamp the destination to the available history range.
-    if (newIndex < 0) {
-      this.#current = state.history[0].location;
-      // Use the oldest entry when navigation moves beyond the end of the stack.
-    } 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.
-   * @param to - Target path or partial path object.
-   * @returns URL resolved against memory://.
-   */
-  createURL(to: To): URL {
-    const path = resolvePath(to);
-    return new URL(pathToString(path), this.origin);
-  }
-}

package/src/lib/ProxyHistory.ts

@@ -1,145 +0,0 @@
-import { Subscription } from 'rxjs';
-import type { Observable } from 'rxjs';
-
-import type { BaseHistory } from './BaseHistory';
-import type {
-  History,
-  NavigateOptions,
-  NavigationBlocker,
-  NavigationListener,
-  NavigationUpdate,
-  Path,
-  To,
-} from './types';
-import type { Actions } from './state/actions';
-
-/**
- * A lightweight proxy that delegates every {@link History} operation to an
- * underlying target instance.
- *
- * Use this when you need to pass a conforming `History` object whose backing
- * implementation can be swapped or is not yet available at construction time,
- * or when you want a thin indirection layer without subclassing
- * {@link BaseHistory}.
- *
- * The proxy does **not** own the underlying history; disposing it only tears
- * down subscriptions and blockers registered through the proxy itself.
- *
- * @example
- * ```ts
- * const browser = createHistory('browser');
- * const proxy = new ProxyHistory(browser);
- * proxy.push('/dashboard'); // delegates to browser.push
- * ```
- */
-export class ProxyHistory implements History {
-  /** The underlying history instance all calls are forwarded to. */
-  readonly #target: History;
-
-  /** Teardowns owned by this proxy, cleaned up on dispose. */
-  readonly #teardowns = new Subscription();
-
-  /**
-   * @param target - The history instance to delegate all operations to
-   */
-  constructor(target: History) {
-    this.#target = target;
-  }
-
-  /** @inheritdoc */
-  get state$(): Observable<NavigationUpdate> {
-    return this.#target.state$;
-  }
-
-  /** @inheritdoc */
-  get action$(): Observable<Actions> {
-    return this.#target.action$;
-  }
-
-  /** @inheritdoc */
-  get action(): History['action'] {
-    return this.#target.action;
-  }
-
-  /** @inheritdoc */
-  get location(): History['location'] {
-    return this.#target.location;
-  }
-
-  /** @inheritdoc */
-  createHref(to: To): string {
-    return this.#target.createHref(to);
-  }
-
-  /** @inheritdoc */
-  createURL(to: To): URL {
-    return this.#target.createURL(to);
-  }
-
-  /** @inheritdoc */
-  encodeLocation(to: To): Path {
-    return this.#target.encodeLocation(to);
-  }
-
-  /** @inheritdoc */
-  push(to: To, state?: unknown): void {
-    this.#target.push(to, state);
-  }
-
-  /** @inheritdoc */
-  replace(to: To, state?: unknown): void {
-    this.#target.replace(to, state);
-  }
-
-  /** @inheritdoc */
-  navigate(to: To, options?: NavigateOptions): void {
-    this.#target.navigate(to, options);
-  }
-
-  /** @inheritdoc */
-  go(delta: number): void {
-    this.#target.go(delta);
-  }
-
-  /**
-   * Triggers a POP action on the underlying history to notify framework
-   * listeners (e.g. React Router) after programmatic navigation.
-   *
-   * Delegates to the target's `pop()` when it is a {@link BaseHistory}
-   * instance; otherwise this is a no-op.
-   */
-  pop(): void {
-    // Only BaseHistory implementations expose pop(); anything else is a no-op.
-    if ('pop' in this.#target && typeof this.#target.pop === 'function') {
-      (this.#target as BaseHistory).pop();
-    }
-  }
-
-  /** @inheritdoc */
-  listen(listener: NavigationListener): () => void {
-    const unlisten = this.#target.listen(listener);
-    this.#teardowns.add(unlisten);
-    return () => {
-      unlisten();
-      this.#teardowns.remove(unlisten);
-    };
-  }
-
-  /** @inheritdoc */
-  block(blocker: NavigationBlocker): VoidFunction {
-    const unblock = this.#target.block(blocker);
-    this.#teardowns.add(unblock);
-    return () => {
-      unblock();
-      this.#teardowns.remove(unblock);
-    };
-  }
-
-  /**
-   * Disposes all listeners and blockers registered through this proxy.
-   * Does **not** dispose the underlying history.
-   */
-  [Symbol.dispose](): void {
-    this.#teardowns.unsubscribe();
-  }
-}

package/src/lib/create-history.ts

@@ -1,58 +0,0 @@
-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} using pathname-based routing
- * - `'hash'`: Creates a {@link BrowserHistory} using hash-based routing (`#/path`)
- * - `'memory'`: Creates a {@link MemoryHistory} for testing, SSR, or widget apps
- *
- * @param type - The type of history to create (`'browser'`, `'hash'`, or `'memory'`)
- * @param args - Optional arguments forwarded to the history constructor
- * @returns A {@link History} instance of the requested type
- * @throws {Error} If `type` is not one of `'browser'`, `'hash'`, or `'memory'`
- *
- * @example
- * ```ts
- * const history = createHistory('browser');
- * const hashHistory = createHistory('hash');
- * const memoryHistory = createHistory('memory', { initialLocation: { ... } });
- * ```
- */
-export const createHistory = <T extends keyof HistoryCtorMap>(
-  type: T,
-  ...args: Parameters<HistoryCtorMap[T]>
-): ReturnType<HistoryCtorMap[T]> => {
-  // Dispatch to the history implementation matching the requested type.
-  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,33 +0,0 @@
-/**
- * Internal history implementations, stacks, and types.
- *
- * @remarks
- * This sub-module is re-exported as `@equinor/fusion-framework-module-navigation/lib`
- * and provides the low-level building blocks for navigation state management.
- *
- * @packageDocumentation
- */
-
-// History implementations
-export { BaseHistory } from './BaseHistory';
-export { BrowserHistory } from './BrowserHistory';
-export { MemoryHistory } from './MemoryHistory';
-export { ProxyHistory } from './ProxyHistory';
-
-// History stacks
-export { BrowserHistoryStack } from './BrowserHistoryStack';
-export { BrowserHistoryHashStack as HashHistoryStack } from './BrowserHistoryHashStack';
-export { MemoryHistoryStack } from './MemoryHistoryStack';
-
-// Types
-export type {
-  Action,
-  History,
-  HistoryStack,
-  Location,
-  NavigateOptions,
-  NavigationListener,
-  NavigationUpdate,
-  Path,
-  To,
-} from './types';

package/src/lib/state/actions.ts

@@ -1,108 +0,0 @@
-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>;