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

package/src/index.ts

@@ -1,3 +1,27 @@
+/**
+ * @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';
 
@@ -26,6 +50,6 @@ export type {
 } from './lib/types';
 
 /**
- * @deprecated use History instead
+ * @deprecated Use {@link History} instead.
  */
 export type { History as INavigator } from './lib';

package/src/lib/BaseHistory.ts

@@ -16,8 +16,10 @@ import type {
 
 /**
  * Abstract base class for history implementations.
- * Provides common state management and navigation logic that can be shared
- * across different history implementations (browser, memory, etc.).
+ *
+ * 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
@@ -27,14 +29,18 @@ export abstract class BaseHistory implements History {
   #state: HistoryState;
 
   /**
-   * Gets the current location.
+   * 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 action.
+   * 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;
@@ -56,7 +62,9 @@ export abstract class BaseHistory implements History {
   }
 
   /**
-   * Checks if there are any active navigation blockers.
+   * 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;
@@ -68,13 +76,19 @@ export abstract class BaseHistory implements History {
 
   /**
    * 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 URL object for a given path.
+   * 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);
@@ -82,6 +96,9 @@ export abstract class BaseHistory implements History {
 
   /**
    * 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);

package/src/lib/BrowserHistoryStack.ts

@@ -2,17 +2,16 @@ import { pathToString, resolvePath, resolveWindowLocation } from './utils';
 import type { HistoryStack, Location, To } from './types';
 
 /**
- * Browser history stack implementation using native browser APIs.
+ * Browser history stack implementation using the native History API.
  *
- * 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.
+ * 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', key: 'abc123', state: { userId: 1 } });
- * // Updates URL to /users and adds entry to history
+ * stack.push({ pathname: '/users', search: '', hash: '', key: 'abc', state: null });
  * ```
  */
 export class BrowserHistoryStack implements HistoryStack {

package/src/lib/MemoryHistory.ts

@@ -10,7 +10,14 @@ import { createHistoryReducer, createStore } from './state';
 const defaultInitialLocation: NavigationUpdate = {
   delta: 0,
   action: Action.Pop,
-  location: { pathname: '/', search: '', hash: '', key: 'unknown', state: null },
+  location: {
+    pathname: '/',
+    search: '',
+    hash: '',
+    key: 'unknown',
+    state: null,
+    unstable_mask: undefined,
+  },
 };
 
 /**
@@ -26,11 +33,11 @@ export type MemoryHistoryOptions = {
 /**
  * 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
+ * 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 {
   public constructor(options?: MemoryHistoryOptions) {

package/src/lib/MemoryStack.ts

@@ -39,6 +39,7 @@ export class MemoryHistoryStack implements HistoryStack {
       hash: '',
       state: null,
       key: '',
+      unstable_mask: undefined,
     };
   }
 

package/src/lib/ProxyHistory.ts

@@ -0,0 +1,144 @@
+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/history.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 {
+    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

@@ -13,25 +13,19 @@ type HistoryCtorMap = {
  * 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)
+ * - `'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
  *
- * 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)
+ * @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
- * // Regular browser routing
  * const history = createHistory('browser');
- *
- * // Hash-based routing
  * const hashHistory = createHistory('hash');
- *
- * // In-memory history for testing
  * const memoryHistory = createHistory('memory', { initialLocation: { ... } });
  * ```
  */

package/src/lib/index.ts

@@ -1,7 +1,18 @@
+/**
+ * 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';

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

@@ -47,7 +47,7 @@ export const navigate: HistoryFlowCreator =
         const path = resolvePath(payload.to);
         const key = meta.key;
         const { replace, state } = payload.options;
-        const nextLocation = { ...path, key, state } satisfies Location;
+        const nextLocation = { ...path, key, state, unstable_mask: undefined } satisfies Location;
         // prevent death loop navigation
         if (compareLocation(nextLocation, stack.current)) {
           return actions.abortNavigate('Location is the same as the current location');
@@ -233,19 +233,14 @@ export const validateCurrentLocation: HistoryFlowCreator =
 /**
  * Creates a combined history flow from multiple flow creators.
  *
- * Execution flow:
- * 1. Creates a preprocessing step that applies blocker checking (unless skipped)
- * 2. Initializes each flow creator with the stack to create individual flows
- * 3. Merges all flows so they process actions in parallel
- * 4. Returns a combined flow that:
- *    - First applies preprocessing (blocker checking)
- *    - Then processes actions through all merged flows
- *    - Emits results from any flow that matches the action
+ * Merges all provided flows so they process actions in parallel.
+ * Optionally prepends a blocker-checking step that gates navigation
+ * actions through registered {@link NavigationBlocker | blockers}.
  *
  * @param flowCreators - Array of flow creators to combine
- * @param options - Optional configuration options
- * @param options.skipBlockCheck - If true, skip blocker checking
- * @returns A combined history flow creator
+ * @param options - Optional configuration
+ * @param options.skipBlockCheck - If `true`, skip blocker checking
+ * @returns A combined {@link HistoryFlowCreator} that merges all provided flows
  */
 export const createFlow = (
   flowCreators: HistoryFlowCreator[],

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

@@ -14,10 +14,14 @@ const findIndex = (state: LocationState) => {
 /**
  * Creates a reducer for history state management.
  *
- * @param initial - Initial navigation update or function that returns initial state
- * @param options - Optional configuration options
- * @param options.maxHistory - Maximum number of history entries to keep (default: 100)
- * @returns A reducer for history state
+ * Handles navigate, go, and pop success actions by updating the
+ * history array and current location. Enforces a maximum history
+ * length to prevent unbounded memory growth.
+ *
+ * @param initial - Initial navigation update or factory returning initial state
+ * @param options - Optional configuration
+ * @param options.maxHistory - Maximum number of history entries to keep (default: `100`)
+ * @returns A reducer with initial state for use with {@link createStore}
  */
 export const createHistoryReducer = (
   initial: NavigationUpdate | (() => LocationState),

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

@@ -22,10 +22,16 @@ export const defaultFlows = [flowCreators.navigate, flowCreators.go, flowCreator
 /**
  * Creates a history store with the specified stack and reducer.
  *
- * @param stack - The history stack implementation
- * @param reducer - The reducer for history state
+ * Combines the reactive state container with a {@link HistoryStack} and wires
+ * up navigation flows for action processing.
+ *
+ * @param stack - The history stack implementation (browser, hash, or memory)
+ * @param reducer - The reducer that handles state transitions
  * @param options - Optional configuration options
- * @returns A HistoryState instance
+ * @param options.flows - Custom flow creators (defaults to {@link defaultFlows})
+ * @param options.skipBlockCheck - Skip blocker checking in flows
+ * @param options.validateCurrentLocation - Add location validation flow
+ * @returns A fully-initialized {@link HistoryState} with flows attached
  */
 export const createStore = (
   stack: HistoryStack,

package/src/lib/types.ts

@@ -42,12 +42,16 @@ export type Path = {
 
 /**
  * Location object representing a navigation entry.
- * Extends Path with state and a unique key.
+ * Extends {@link Path} with arbitrary state data and a unique key.
+ *
+ * @template T - The type of the state payload stored in this location entry
  */
 // biome-ignore lint/suspicious/noExplicitAny: necessary
 export type Location<T = any> = Path & {
   state: T;
   key: string;
+  /** Masked path used by react-router 7.13+ for unstable view-transition masking. */
+  unstable_mask: Path | undefined;
 };
 
 /**
@@ -65,7 +69,10 @@ export type LocationState = {
 export type NavigationListener = (update: Readonly<NavigationUpdate>) => void;
 
 /**
- * Navigation update event containing action and location.
+ * Navigation update event containing the action, location, and stack delta.
+ *
+ * @template A - The type of navigation action (defaults to {@link Action})
+ * @template T - The type of the state payload in the location
  */
 export type NavigationUpdate<A extends string = Action, T = unknown> = {
   delta: number;
@@ -108,7 +115,16 @@ export interface NavigateOptions {
 
 /**
  * History interface for managing navigation state.
- * Compatible with industry-standard routers (Remix/React Router) and provides observable state management.
+ *
+ * Compatible with Remix / React Router and provides observable
+ * state management via RxJS.
+ *
+ * @example
+ * ```ts
+ * const history = createHistory('browser');
+ * history.push('/dashboard');
+ * history.state$.subscribe(update => console.log(update.location.pathname));
+ * ```
  */
 export interface History extends Disposable {
   /** Observable stream of navigation state updates. */
@@ -120,11 +136,20 @@ export interface History extends Disposable {
   /** Current location in the history stack. */
   readonly location: Location;
 
-  /** Creates a valid href string for a given path. */
+  /** Creates a valid href string for a given path.
+   * @param to - Target path or partial path object
+   * @returns Fully-qualified href string
+   */
   createHref(to: To): string;
-  /** Creates a URL object for a given path. */
+  /** Creates a {@link URL} object for a given path.
+   * @param to - Target path or partial path object
+   * @returns Resolved {@link URL} instance
+   */
   createURL(to: To): URL;
-  /** Encodes a location by properly URL-encoding the pathname. */
+  /** 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
+   */
   encodeLocation(to: To): Path;
   /** Pushes a new navigation entry onto the history stack. */
   push(to: To, state?: unknown): void;
@@ -134,9 +159,15 @@ export interface History extends Disposable {
   navigate(to: To, options?: NavigateOptions): void;
   /** Navigates backward or forward in the history stack. */
   go(delta: number): void;
-  /** Sets up a listener for navigation changes. */
+  /** Sets up a listener for navigation changes.
+   * @param listener - Callback invoked on POP actions (browser back/forward)
+   * @returns A function that unsubscribes the listener when called
+   */
   listen(listener: NavigationListener): () => void;
-  /** Registers a blocker to intercept navigation attempts. */
+  /** Registers a blocker to intercept navigation attempts.
+   * @param blocker - Callback invoked before each navigation to allow or prevent it
+   * @returns A function that removes the blocker when called
+   */
   block(blocker: NavigationBlocker): VoidFunction;
 }
 

package/src/lib/utils/resolve-browser-location.ts

@@ -31,7 +31,7 @@ const resolveState = (target?: { state: unknown }): { state: unknown; key: strin
 export const resolveWindowLocation = (window: Window, target?: { state: unknown }): Location => {
   const { pathname, search, hash } = resolvePath(window.location);
   const { state, key } = resolveState(target);
-  return { pathname, search, hash, state, key };
+  return { pathname, search, hash, state, key, unstable_mask: undefined };
 };
 
 /**
@@ -56,5 +56,5 @@ export const resolveHashLocation = (window: Window, target?: { state: unknown })
   const location = resolveWindowLocation(window, target);
   const { pathname, search, hash } = resolvePath(location.hash?.replace('#', '') ?? '');
   const { state, key } = resolveState(target);
-  return { pathname, search, hash, state, key };
+  return { pathname, search, hash, state, key, unstable_mask: undefined };
 };

package/src/module.ts

@@ -46,16 +46,16 @@ export const module: NavigationModule = {
   version: new SemanticVersion(version),
   name: moduleKey,
   /**
-   * Configures the navigation module.
+   * Creates a new {@link NavigationConfigurator} for the module.
    *
-   * @returns A new NavigationConfigurator instance
+   * @returns A fresh {@link NavigationConfigurator} instance with default settings
    */
   configure: () => new NavigationConfigurator(),
   /**
    * Initializes the navigation module with validated configuration.
    *
-   * @param init - Module initialization arguments
-   * @returns A Promise that resolves to a new NavigationProvider instance
+   * @param init - Module initialization arguments containing config and refs
+   * @returns A promise that resolves to a configured {@link NavigationProvider}
    */
   initialize: async (init) => {
     const config = await init.config.createConfigAsync(init);

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.0.0-next.2';
+export const version = '7.0.1';