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

package/src/NavigateEvent.ts

@@ -1,47 +0,0 @@
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-import type { INavigationProvider } from './NavigationProvider.interface';
-import type { NavigationUpdate, Path } from './lib/types';
-
-/** Event detail for navigation events (before navigation). */
-export interface NavigateEventDetail {
-  /** The target path or location to navigate to */
-  location: NavigationUpdate;
-  /** Optional current location before navigation */
-  currentLocation?: Path;
-}
-
-/**
- * Event emitted before navigation occurs.
- * 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>
-> {
-  /** @param detail - Navigation target details. @param source - Provider dispatching the event. */
-  constructor(detail: NavigateEventDetail, source: INavigationProvider) {
-    super('onNavigate', {
-      detail,
-      source,
-    });
-  }
-}
-
-/** Declares navigation events in the FrameworkEventMap for type safety. */
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    /** Event emitted before navigation occurs, can be canceled to prevent navigation */
-    onNavigate: NavigateEvent;
-    /** Event emitted after navigation occurs */
-    onNavigated: import('./NavigatedEvent').NavigatedEvent;
-  }
-}

package/src/NavigatedEvent.ts

@@ -1,35 +0,0 @@
-import { FrameworkEvent, type FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-import type { INavigationProvider } from './NavigationProvider.interface';
-import type { Action, NavigationUpdate } from './lib/types';
-
-/** Event detail for navigated events (after navigation). */
-export interface NavigatedEventDetail {
-  /** The navigation action that occurred (PUSH, POP, REPLACE) */
-  action: Action;
-  /** The new location after navigation */
-  current: NavigationUpdate;
-  /** The previous location before navigation */
-  previous: NavigationUpdate;
-}
-
-/**
- * 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>
-> {
-  /** @param detail - Completed navigation details. @param source - Provider dispatching the event. */
-  constructor(detail: NavigatedEventDetail, source: INavigationProvider) {
-    super('onNavigated', { detail, source });
-  }
-}

package/src/NavigationConfigurator.interface.ts

@@ -1,41 +0,0 @@
-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 the history implementation, basename prefix,
- * telemetry tracking, and event dispatching used by the {@link NavigationProvider}.
- */
-export interface INavigationConfigurator {
-  /**
-   * 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;
-
-  /**
-   * 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;
-
-  /**
-   * Telemetry provider for tracking navigation events, location changes,
-   * and errors for monitoring and debugging.
-   */
-  telemetry?: ITelemetryProvider;
-
-  /**
-   * Event provider for dispatching {@link NavigateEvent} and {@link NavigatedEvent}.
-   * Allows other modules to listen for and react to navigation changes.
-   */
-  eventProvider?: IEventModuleProvider;
-}

package/src/NavigationConfigurator.ts

@@ -1,226 +0,0 @@
-import { z } from 'zod';
-import { of, from, type ObservableInput } from 'rxjs';
-import { map } from 'rxjs/operators';
-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 { ProxyHistory } from './lib/ProxyHistory';
-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> {
-  /** Creates a navigation configurator with default history and event providers. */
-  constructor() {
-    super();
-    this.setEventProvider(async (args) => {
-      // Only resolve the optional provider when the event module participates in this framework.
-      if (args.hasModule('event')) {
-        return await args.requireInstance('event');
-      }
-    });
-    this.setHistory(
-      async (args) => {
-        const history = (args.ref as ModulesInstance<[NavigationModule]>)?.navigation?.history;
-        // Wrap supplied history so the module owns only the proxy lifecycle.
-        if (history) {
-          // Wrap the provided history in a ProxyHistory to ensure the module can manage its own teardowns without affecting the original instance.
-          return new ProxyHistory(history);
-        }
-        // Prefer browser history when a DOM is available, otherwise use memory history for SSR.
-        if (typeof window !== 'undefined') {
-          return createHistory('browser');
-        }
-        return createHistory('memory');
-      },
-      // Don't wrap the default history in a ProxyHistory since it's already owned by the module and will be properly disposed.
-      { proxy: false },
-    );
-  }
-  /**
-   * @deprecated Use `setBasename()` method instead
-   * @param value - Deprecated basename value to configure.
-   */
-  public set basename(value: string | undefined) {
-    // Warn only during development so deprecated setters remain silent in production.
-    if (process.env.NODE_ENV === 'development') {
-      console.warn('NavigationConfigurator.basename', 'use setBasename() method instead');
-    }
-    this.setBasename(value);
-  }
-
-  /**
-   * @deprecated Use `setHistory()` method instead
-   * @param value - Deprecated history value to configure.
-   */
-  public set history(value: History | undefined) {
-    // Warn only during development so deprecated setters remain silent in production.
-    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.
-   *
-   * By default the resolved history is wrapped in a {@link ProxyHistory} so the
-   * module gets its own disposable handle without owning (or accidentally
-   * disposing) the original instance. Set `proxy` to `false` to use the
-   * history as-is.
-   *
-   * @param historyOrCallback - History instance or configuration callback
-   * @param options - Optional settings for history wrapping
-   * @param options.proxy - Wrap the history in a {@link ProxyHistory} (default: `true`)
-   * @returns The configurator instance for method chaining
-   */
-  public setHistory(
-    historyOrCallback?: History | ConfigBuilderCallback<History>,
-    options?: { proxy?: boolean },
-  ): this {
-    const { proxy = true } = options ?? {};
-    const resolve =
-      typeof historyOrCallback === 'function'
-        ? historyOrCallback
-        : // Normalize a direct instance to a callback for consistent handling.
-          async () => historyOrCallback;
-
-    // Proxying isolates teardown ownership when callers provide an existing history instance.
-    if (proxy) {
-      // Wrap each emitted history in a ProxyHistory so dispose only tears down
-      // proxy-owned listeners/blockers, never the underlying history itself.
-      this._set('history', (args) =>
-        from(resolve(args) as ObservableInput<History | undefined>)
-          // Transform each resolved history into an independently disposable proxy.
-          .pipe(map((history) => (history ? new ProxyHistory(history) : undefined))),
-      );
-      // Direct histories are already owned by the navigation module and can be used unchanged.
-    } else {
-      this._set('history', resolve);
-    }
-    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

@@ -1,99 +0,0 @@
-// TODO(#5158): 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 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 {
-  /**
-   * 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.
-   *
-   * @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 including the basename prefix.
-   *
-   * @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 {@link URL} object including the basename prefix.
-   *
-   * @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;
-
-  /**
-   * 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;
-}