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

package/dist/types/lib/utils/resolve-path.d.ts

@@ -0,0 +1,17 @@
+import type { Path, To } from '../types';
+/**
+ * Resolves a 'to' value into a Path object.
+ *
+ * @param to - The target path (string, Path object, or Location object)
+ * @returns A Path object with the pathname, search, and hash components
+ *
+ * @example
+ * ```ts
+ * resolvePath('/users?id=1#section')
+ * // { pathname: '/users', search: '?id=1', hash: '#section' }
+ *
+ * resolvePath({ pathname: '/users', search: 'id=1', hash: 'section' })
+ * // { pathname: '/users', search: '?id=1', hash: '#section' }
+ * ```
+ */
+export declare const resolvePath: (to: To) => Path;

package/dist/types/module.d.ts

@@ -1,10 +1,38 @@
-import { type IModuleConfigurator, type IModulesConfigurator, type Module } from '@equinor/fusion-framework-module';
-import { type INavigationConfigurator } from './configurator';
-import { type INavigationProvider } from './lib';
+import { type Module } from '@equinor/fusion-framework-module';
+import { NavigationConfigurator } from './NavigationConfigurator';
+import type { INavigationProvider } from './NavigationProvider.interface';
+/**
+ * Module key identifier for the navigation module.
+ */
 export declare const moduleKey = "navigation";
-export type NavigationModule = Module<typeof moduleKey, INavigationProvider, INavigationConfigurator>;
+/**
+ * Type definition for the navigation module.
+ *
+ * This is the main type definition for the navigation module. It represents the complete
+ * module structure with its key identifier, provider interface, and configurator class.
+ *
+ * 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. It integrates with the Fusion Framework module
+ * system and provides a {@link INavigationProvider} instance that can be used to
+ * access navigation functionality.
+ *
+ * @see {@link INavigationProvider} - The provider interface for accessing navigation
+ * @see {@link NavigationConfigurator} - The configurator class for setting up navigation
+ * @see {@link enableNavigation} - Helper function to enable the navigation module
+ * @see {@link module} - The module implementation instance
+ */
+export type NavigationModule = Module<typeof moduleKey, INavigationProvider, NavigationConfigurator>;
+/**
+ * Navigation module implementation.
+ * Provides routing and navigation capabilities compatible with industry-standard routers (Remix/React Router).
+ *
+ * @remarks
+ * - Uses BaseConfigBuilder pattern with Zod validation
+ * - Basename must match the URL path prefix where your app is served
+ * - The router requires URL pathname to start with the basename
+ */
 export declare const module: NavigationModule;
-export declare const enableNavigation: <TRef = unknown>(configurator: IModulesConfigurator<any, any>, basenameOrOptions?: string | Omit<IModuleConfigurator<NavigationModule, TRef>, "module">) => void;
 export default module;
 declare module '@equinor/fusion-framework-module' {
     interface Modules {

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "6.0.1";
+export declare const version = "7.0.0-next.2";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@equinor/fusion-framework-module-navigation",
-  "version": "6.0.1",
-  "description": "",
+  "version": "7.0.0-next.2",
+  "description": "Navigation module for Fusion Framework providing routing and navigation capabilities using React Router 7",
   "sideEffects": false,
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -9,6 +9,14 @@
     ".": {
       "import": "./dist/esm/index.js",
       "types": "./dist/types/index.d.ts"
+    },
+    "./lib": {
+      "import": "./dist/esm/lib/index.js",
+      "types": "./dist/types/lib/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/esm/utils/index.js",
+      "types": "./dist/types/utils/index.d.ts"
     }
   },
   "keywords": [],
@@ -23,19 +31,29 @@
     "directory": "packages/modules/navigation"
   },
   "dependencies": {
-    "@remix-run/router": "^1.8.0"
+    "@remix-run/router": "^1.23.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.1.11"
   },
   "devDependencies": {
+    "@types/uuid": "^11.0.0",
+    "jsdom": "^27.1.0",
     "rxjs": "^7.8.1",
     "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module": "^5.0.6"
+    "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"
   },
   "peerDependencies": {
-    "@remix-run/router": "^1.8.0",
+    "@remix-run/router": "^1.23.0",
     "rxjs": "^7.0.0",
-    "@equinor/fusion-framework-module": "^5.0.6"
+    "@equinor/fusion-framework-module": "^5.0.7-next.0",
+    "@equinor/fusion-observable": "^8.5.9-next.0"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest"
   }
 }

package/src/NavigationConfigurator.interface.ts

@@ -0,0 +1,18 @@
+import type { History } from './lib/types';
+import type { ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
+import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
+
+/**
+ * Configuration object for the navigation module.
+ * Provides options for customizing history, basename, telemetry, and event settings.
+ */
+export interface INavigationConfigurator {
+  /** Optional base pathname for the application (e.g., "/app") */
+  basename?: string;
+  /** Optional custom history instance (browser, hash, or memory). If not provided, defaults to browser history. */
+  history?: History;
+  /** Optional telemetry provider for tracking navigation events */
+  telemetry?: ITelemetryProvider;
+  /** Optional event provider for dispatching navigation events */
+  eventProvider?: IEventModuleProvider;
+}

package/src/NavigationConfigurator.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { of, type ObservableInput } from 'rxjs';
+import {
+  BaseConfigBuilder,
+  type ModulesInstance,
+  type ConfigBuilderCallback,
+  type ConfigBuilderCallbackArgs,
+} from '@equinor/fusion-framework-module';
+import type { ITelemetryProvider } from '@equinor/fusion-framework-module-telemetry';
+import type { IEventModuleProvider } from '@equinor/fusion-framework-module-event';
+import type { INavigationConfigurator } from './NavigationConfigurator.interface';
+
+import type { History } from './lib/types';
+import { createHistory } from './lib/create-history';
+import type { NavigationModule } from './module';
+
+/**
+ * Zod schema for navigation module configuration validation.
+ *
+ * @internal
+ */
+const navigationConfigSchema = z
+  .object({
+    basename: z
+      .string()
+      .optional()
+      .describe(
+        'Base pathname for the application (e.g., "/app"). Must match the URL path prefix where your app is served. The router requires the pathname to start with this basename.',
+      ),
+    history: z
+      .custom<History>()
+      .describe(
+        'Custom history instance implementing the History interface. Defaults to browser history if not provided. Use createHistory("browser"|"hash"|"memory") to create instances.',
+      ),
+    telemetry: z
+      .custom<ITelemetryProvider>()
+      .optional()
+      .describe(
+        'Telemetry provider for tracking navigation events. Used to log navigation actions, location changes, and errors for monitoring and debugging.',
+      ),
+    eventProvider: z
+      .custom<IEventModuleProvider>()
+      .optional()
+      .describe(
+        'Event provider for dispatching navigation events (NavigateEvent, NavigatedEvent). Allows other modules to listen for navigation changes and block navigation attempts.',
+      ),
+  })
+  .describe(
+    'Validates navigation module configuration settings for routing and navigation capabilities.',
+  );
+
+/**
+ * Parses and validates a navigation configuration object.
+ *
+ * @param config - The configuration object to parse
+ * @returns Validated navigation configuration
+ * @throws {z.ZodError} If the configuration is invalid
+ */
+const parseNavigationConfig = (config: unknown): INavigationConfigurator => {
+  return navigationConfigSchema.parse(config);
+};
+
+/**
+ * Configurator class for navigation module settings.
+ * Extends BaseConfigBuilder to provide fluent configuration API with Zod validation.
+ */
+export class NavigationConfigurator extends BaseConfigBuilder<INavigationConfigurator> {
+  constructor() {
+    super();
+    this.setEventProvider(async (args) => {
+      if (args.hasModule('event')) {
+        return await args.requireInstance('event');
+      }
+    });
+    this.setHistory(async (args) => {
+      const history = (args.ref as ModulesInstance<[NavigationModule]>)?.navigation?.history;
+      if (history) {
+        return history;
+      }
+      if (typeof window !== 'undefined') {
+        return createHistory('browser');
+      }
+      return createHistory('memory');
+    });
+  }
+  /**
+   * @deprecated Use `setBasename()` method instead
+   */
+  public set basename(value: string | undefined) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('NavigationConfigurator.basename', 'use setBasename() method instead');
+    }
+    this.setBasename(value);
+  }
+
+  /**
+   * @deprecated Use `setHistory()` method instead
+   */
+  public set history(value: History | undefined) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('NavigationConfigurator.history', 'use setHistory() method instead');
+    }
+    this.setHistory(value);
+  }
+
+  /**
+   * Sets the basename for the application.
+   *
+   * @param basenameOrCallback - Basename string or configuration callback
+   * @returns The configurator instance for method chaining
+   */
+  public setBasename(basenameOrCallback?: string | ConfigBuilderCallback<string>): this {
+    const fn =
+      typeof basenameOrCallback === 'function'
+        ? basenameOrCallback
+        : async () => basenameOrCallback;
+    this._set('basename', fn);
+    return this;
+  }
+
+  /**
+   * Sets a custom history instance for the navigation module.
+   *
+   * @param historyOrCallback - History instance or configuration callback
+   * @returns The configurator instance for method chaining
+   */
+  public setHistory(historyOrCallback?: History | ConfigBuilderCallback<History>): this {
+    const fn =
+      typeof historyOrCallback === 'function' ? historyOrCallback : async () => historyOrCallback;
+    this._set('history', fn);
+    return this;
+  }
+
+  /**
+   * Sets telemetry configuration for navigation-specific events.
+   *
+   * @param telemetryOrCallback - Telemetry provider instance or configuration callback
+   * @returns The configurator instance for method chaining
+   */
+  public setTelemetry(
+    telemetryOrCallback: ITelemetryProvider | ConfigBuilderCallback<ITelemetryProvider>,
+  ): this {
+    const fn =
+      typeof telemetryOrCallback === 'function'
+        ? telemetryOrCallback
+        : async () => telemetryOrCallback;
+    this._set('telemetry', fn);
+    return this;
+  }
+
+  /**
+   * Sets event provider for dispatching navigation events.
+   *
+   * @param eventProviderOrCallback - Event provider instance or configuration callback
+   * @returns The configurator instance for method chaining
+   */
+  public setEventProvider(
+    eventProviderOrCallback: IEventModuleProvider | ConfigBuilderCallback<IEventModuleProvider>,
+  ): this {
+    const fn =
+      typeof eventProviderOrCallback === 'function'
+        ? eventProviderOrCallback
+        : async () => eventProviderOrCallback;
+    this._set('eventProvider', fn);
+    return this;
+  }
+
+  /**
+   * Processes and validates the configuration using Zod schema.
+   *
+   * @param config - Raw configuration object from builder
+   * @param _init - Configuration builder callback arguments (unused)
+   * @returns Observable that emits validated and processed configuration object
+   * @throws {z.ZodError} If the configuration is invalid
+   *
+   * @protected
+   */
+  protected _processConfig(
+    config: Partial<INavigationConfigurator>,
+    _init: ConfigBuilderCallbackArgs,
+  ): ObservableInput<INavigationConfigurator> {
+    return of(parseNavigationConfig(config));
+  }
+}

package/src/NavigationProvider.interface.ts

@@ -0,0 +1,86 @@
+// TODO: Remove @remix-run/router dependency once all apps have migrated to @equinor/fusion-framework-react-router
+import type { AgnosticRouteObject, Router } from '@remix-run/router';
+
+import type { History, NavigateOptions } from './lib/types';
+import type { Action, Path, To } from './lib/types';
+
+import type { Observable } from 'rxjs';
+import type { IModuleProvider } from '@equinor/fusion-framework-module';
+
+/**
+ * Navigation provider interface.
+ * Provides routing and navigation capabilities with basename localization.
+ */
+export interface INavigationProvider extends IModuleProvider {
+  /**
+   * Observable stream of navigation state updates.
+   * Emits localized paths (with basename removed) for consumers.
+   */
+  readonly state$: Observable<{ action: Action; location: Path }>;
+
+  /**
+   * Gets the basename.
+   */
+  readonly basename: string;
+
+  /**
+   * Gets the current localized path (basename removed).
+   */
+  readonly path: Path;
+
+  /**
+   * @deprecated Use `history` instead
+   */
+  readonly navigator: History;
+
+  /**
+   * Gets the history instance.
+   */
+  readonly history: History;
+
+  /**
+   * 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
+   */
+  createRouter(routes: AgnosticRouteObject[]): Router;
+
+  /**
+   * Creates a localized href string for navigation.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   */
+  createHref(to?: To): string;
+
+  /**
+   * Creates a full URL object for navigation.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   */
+  createURL(to?: To): URL;
+
+  /**
+   * Navigates to a location with explicit options.
+   *
+   * @param to - Optional path or location (defaults to current path)
+   * @param options - Optional navigation options
+   */
+  navigate(to?: To, options?: Partial<NavigateOptions>): void;
+
+  /**
+   * Pushes a new navigation entry onto the history stack.
+   *
+   * @param to - Path or location to navigate to (relative to basename)
+   * @param state - Optional state to associate with the navigation
+   */
+  push(to: To, state?: unknown): void;
+
+  /**
+   * Replaces the current history entry with a new one.
+   *
+   * @param to - Path or location to navigate to (relative to basename)
+   * @param state - Optional state to associate with the navigation
+   */
+  replace(to: To, state?: unknown): void;
+}