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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-navigation",
-  "version": "7.0.0-next.2",
+  "version": "7.0.0",
   "description": "Navigation module for Fusion Framework providing routing and navigation capabilities using React Router 7",
   "sideEffects": false,
   "main": "dist/esm/index.js",
@@ -33,24 +33,23 @@
   "dependencies": {
     "@remix-run/router": "^1.23.0",
     "uuid": "^13.0.0",
-    "zod": "^4.1.11"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/uuid": "^11.0.0",
     "jsdom": "^27.1.0",
     "rxjs": "^7.8.1",
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-framework-module-event": "^5.0.2-next.0",
-    "@equinor/fusion-framework-module-telemetry": "^4.6.5-next.0",
-    "@equinor/fusion-observable": "^8.5.9-next.0"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module-telemetry": "^5.0.0",
+    "@equinor/fusion-observable": "^9.0.0"
   },
   "peerDependencies": {
-    "@remix-run/router": "^1.23.0",
+    "@remix-run/router": "^1.0.0",
     "rxjs": "^7.0.0",
-    "@equinor/fusion-framework-module": "^5.0.7-next.0",
-    "@equinor/fusion-observable": "^8.5.9-next.0"
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-observable": "^9.0.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/NavigationConfigurator.interface.ts

@@ -4,15 +4,38 @@ import type { IEventModuleProvider } from '@equinor/fusion-framework-module-even
 
 /**
  * Configuration object for the navigation module.
- * Provides options for customizing history, basename, telemetry, and event settings.
+ *
+ * Provides options for customizing the history implementation, basename prefix,
+ * telemetry tracking, and event dispatching used by the {@link NavigationProvider}.
  */
 export interface INavigationConfigurator {
-  /** Optional base pathname for the application (e.g., "/app") */
+  /**
+   * Base pathname prefix for the application (e.g. `"/apps/my-app"`).
+   *
+   * When set, the navigation provider automatically prepends this prefix to
+   * outgoing paths and strips it from incoming paths, so consumer code
+   * operates on clean, basename-free paths.
+   */
   basename?: string;
-  /** Optional custom history instance (browser, hash, or memory). If not provided, defaults to browser history. */
+
+  /**
+   * Custom {@link History} instance for navigation.
+   *
+   * If not provided, defaults to browser history in browser environments
+   * or memory history in Node.js environments. Create instances with
+   * {@link createHistory}.
+   */
   history?: History;
-  /** Optional telemetry provider for tracking navigation events */
+
+  /**
+   * Telemetry provider for tracking navigation events, location changes,
+   * and errors for monitoring and debugging.
+   */
   telemetry?: ITelemetryProvider;
-  /** Optional event provider for dispatching navigation events */
+
+  /**
+   * Event provider for dispatching {@link NavigateEvent} and {@link NavigatedEvent}.
+   * Allows other modules to listen for and react to navigation changes.
+   */
   eventProvider?: IEventModuleProvider;
 }

package/src/NavigationProvider.interface.ts

@@ -9,7 +9,17 @@ import type { IModuleProvider } from '@equinor/fusion-framework-module';
 
 /**
  * Navigation provider interface.
- * Provides routing and navigation capabilities with basename localization.
+ *
+ * Provides routing and navigation capabilities with automatic basename
+ * localization. Consumers work with clean paths (e.g. `/users`) while the
+ * underlying history operates on full paths (e.g. `/apps/my-app/users`).
+ *
+ * @example
+ * ```ts
+ * const nav: INavigationProvider = framework.modules.navigation;
+ * nav.push('/users');
+ * console.log(nav.path.pathname); // '/users'
+ * ```
  */
 export interface INavigationProvider extends IModuleProvider {
   /**
@@ -41,22 +51,25 @@ export interface INavigationProvider extends IModuleProvider {
   /**
    * Creates a router instance from route configuration.
    *
-   * @param routes - Route configuration objects compatible with industry-standard routers (Remix/React Router)
-   * @returns A configured and initialized router instance
+   * @deprecated Use `@equinor/fusion-framework-react-router` instead.
+   * @param routes - Route configuration objects compatible with Remix/React Router
+   * @returns A configured and initialized {@link Router} instance with basename applied
    */
   createRouter(routes: AgnosticRouteObject[]): Router;
 
   /**
-   * Creates a localized href string for navigation.
+   * Creates a localized href string including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns Fully-qualified href string with basename included
    */
   createHref(to?: To): string;
 
   /**
-   * Creates a full URL object for navigation.
+   * Creates a full {@link URL} object including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns A {@link URL} instance representing the resolved navigation target
    */
   createURL(to?: To): URL;
 

package/src/NavigationProvider.ts

@@ -37,17 +37,23 @@ const normalizePathname = (path: string) => path.replace(/\/+/g, '/').replace(/\
 
 /**
  * Navigation provider implementation.
- * Manages routing and navigation state with basename localization.
+ *
+ * Manages routing and navigation state with automatic basename localization.
+ * Wraps a {@link History} instance to expose observable state, path localization,
+ * and router creation.
  *
  * @remarks
- * This provider:
- * - Wraps the Navigator to provide observable navigation state
- * - Localizes paths by removing basename prefix
- * - Creates routers compatible with industry-standard routers (Remix/React Router)
- * - Handles navigation actions (push, replace, createHref, etc.)
+ * - Emits localized paths (basename removed) to consumers via {@link NavigationProvider.state$ | state$}
+ * - Internally prefixes paths with the basename before forwarding to the history stack
+ * - Creates routers compatible with Remix / React Router via {@link NavigationProvider.createRouter | createRouter}
+ * - Dispatches {@link NavigatedEvent} and telemetry on navigation changes
  *
- * Path localization ensures that consumers receive paths relative to the basename,
- * while internally we work with full paths including basename.
+ * @example
+ * ```ts
+ * const provider = new NavigationProvider({ version, config });
+ * provider.push('/users');
+ * console.log(provider.path.pathname); // '/users'
+ * ```
  */
 export class NavigationProvider
   extends BaseModuleProvider<INavigationConfigurator>
@@ -62,14 +68,19 @@ export class NavigationProvider
 
   /**
    * Observable stream of navigation state updates.
-   * Emits localized paths (with basename removed) for consumers.
+   *
+   * Emits localized paths (with basename removed) and filters to only
+   * paths within the basename scope. Late subscribers receive the last
+   * emitted value immediately.
    */
   public get state$(): Observable<NavigationUpdate> {
     return this.#state$;
   }
 
   /**
-   * Gets the basename.
+   * Gets the basename prefix configured for this provider.
+   *
+   * @returns The basename string, or an empty string if none is configured
    */
   public get basename(): string {
     return this.#basename ?? '';
@@ -89,22 +100,28 @@ export class NavigationProvider
   }
 
   /**
-   * Gets the history instance.
+   * Gets the underlying history instance.
+   *
+   * @returns The {@link History} instance used for navigation
    */
   public get history(): History {
     return this.#history;
   }
 
   /**
-   * Gets the current localized path (basename removed).
+   * Gets the current localized path with the basename prefix removed.
+   *
+   * @returns A {@link Path} object representing the current location without basename
    */
   public get path(): Path {
     return this._localizePath(this.#history.location);
   }
 
   /**
+   * Creates a new {@link NavigationProvider}.
+   *
    * @param args - Configuration arguments containing module config
-   * @throws {Error} If no history is provided in the configuration
+   * @throws {Error} If no history instance is provided in the configuration
    */
   constructor(args: BaseModuleProviderCtorArgs<INavigationConfigurator>) {
     super(args);
@@ -201,10 +218,10 @@ export class NavigationProvider
   /**
    * Creates a router instance from route configuration.
    *
-   * @deprecated Use `@equinor/fusion-framework-react-router` instead
+   * @deprecated Use `@equinor/fusion-framework-react-router` instead.
    *
-   * @param routes - Route configuration objects compatible with industry-standard routers (Remix/React Router)
-   * @returns A configured and initialized router instance
+   * @param routes - Route configuration objects compatible with Remix/React Router
+   * @returns A configured and initialized {@link Router} instance with basename applied
    */
   public createRouter(routes: AgnosticRouteObject[]) {
     this.#telemetry?.trackEvent({
@@ -225,18 +242,26 @@ export class NavigationProvider
   }
 
   /**
-   * Creates a localized href string for navigation.
+   * Creates a localized href string including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns Fully-qualified href string with basename included
+   *
+   * @example
+   * ```ts
+   * // basename = '/apps/my-app'
+   * provider.createHref('/users'); // '/apps/my-app/users'
+   * ```
    */
   public createHref(to?: To): string {
     return this.#history.createHref(this._createToPath(to ?? this.path));
   }
 
   /**
-   * Creates a full URL object for navigation.
+   * Creates a full {@link URL} object including the basename prefix.
    *
-   * @param to - Optional path or location (defaults to current path)
+   * @param to - Path or location to resolve (defaults to current path)
+   * @returns A {@link URL} instance representing the resolved navigation target
    */
   public createURL(to?: To): URL {
     return this.#history.createURL(this._createToPath(to ?? this.path));
@@ -277,14 +302,20 @@ export class NavigationProvider
     (this.#history as BaseHistory).pop();
   }
   /**
-   * Checks if a pathname is within the basename scope.
+   * Checks whether a pathname falls within the configured basename scope.
+   *
+   * @param pathname - The pathname to check
+   * @returns `true` if the pathname starts with the basename (or no basename is set)
    */
   protected _isWithinBasenameScope(pathname: string): boolean {
     return this.#basename ? pathname.startsWith(this.#basename) : true;
   }
 
   /**
-   * Localizes a path by removing the basename prefix.
+   * Localizes a path by stripping the basename prefix from the pathname.
+   *
+   * @param location - The full path to localize
+   * @returns A new {@link Path} with the basename removed from the pathname
    */
   protected _localizePath(location: Path): Path {
     const { pathname, search, hash } = location;
@@ -296,7 +327,10 @@ export class NavigationProvider
   }
 
   /**
-   * Creates a full path object from a target location, adding basename prefix.
+   * Creates a full path object from a target location, prepending the basename prefix.
+   *
+   * @param to - The target location (string path or partial {@link Path} object)
+   * @returns A partial {@link Path} with basename prepended to the pathname
    */
   protected _createToPath(to: To): Partial<Path> {
     // Parse the 'to' parameter into path components

package/src/events.ts

@@ -15,7 +15,16 @@ export interface NavigateEventDetail {
 
 /**
  * Event emitted before navigation occurs.
- * Can be canceled by calling `preventDefault()`.
+ * Can be canceled by calling `preventDefault()` to block the navigation.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigate', (event) => {
+ *   if (hasUnsavedChanges) {
+ *     event.preventDefault();
+ *   }
+ * });
+ * ```
  */
 export class NavigateEvent extends FrameworkEvent<
   FrameworkEventInit<NavigateEventDetail, INavigationProvider>
@@ -41,8 +50,16 @@ export interface NavigatedEventDetail {
 }
 
 /**
- * Event emitted after navigation occurs.
- * Contains the navigation action and location details.
+ * Event emitted after navigation completes.
+ * Contains the navigation action type and both current and previous locations.
+ *
+ * @example
+ * ```ts
+ * eventProvider.addEventListener('onNavigated', (event) => {
+ *   const { action, current, previous } = event.detail;
+ *   console.log(`${action}: ${previous.location.pathname} → ${current.location.pathname}`);
+ * });
+ * ```
  */
 export class NavigatedEvent extends FrameworkEvent<
   FrameworkEventInit<NavigatedEventDetail, INavigationProvider>

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

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,