Context Navigation Plugin (@equinor/fusion-framework-plugin-context-navigation)

Event-driven context-to-URL reconciler plugin for Fusion Framework portals. It keeps the active context synchronized with the browser URL by reacting to context changes and app switches, encoding context into the URL, and optionally guarding against manual URL edits that drop context.

When to Use

Use this plugin when your portal needs to:

• Reflect the active context (project, facility, etc.) in the browser URL automatically
• Support multiple URL encoding strategies (path segment, query parameter, or app-defined custom encoding)
• Preserve context across app switches and page reloads
• Prevent users from accidentally losing context by editing the URL manually

[!NOTE] This plugin is intended for portal hosts, not individual applications. Applications declare their preferred routing strategy via the app manifest's build.options.contextRouting field — the portal's context-navigation plugin picks up that declaration and applies the correct URL encoding automatically.

For App Developers

You don't need to install or configure this plugin. The portal handles it. Your only responsibility is to declare how context should appear in your URL.

Declare a routing strategy

Set contextRouting in your app manifest's build.options:

// app.manifest.config.ts
export default defineAppManifest((env) => ({
  // ...
  build: {
    options: {
      contextRouting: 'query',  // or 'path', or omit for default path behavior
    },
  },
}));

Apps with custom URL shapes should omit contextRouting and register custom hooks instead (see below).

[!NOTE] When contextRouting is not set (or set to null), the portal defaults to the path adapter which encodes context as a path segment after the app key. If the app registers custom hooks (setContextPathExtractor / setContextPathGenerator), the custom adapter takes priority over the path adapter for path/default routing. An explicit contextRouting: 'query' selects the query adapter even when custom path hooks are registered.

Custom URL shapes

If your app encodes context in a non-standard position (e.g. /route-a/{contextId} instead of /{contextId}/route-a), register custom hooks in your app's context configuration:

// app config
builder.setContextPathExtractor((pathname) => {
  // Extract context id from your custom URL position
  const segments = pathname.split('/').filter(Boolean);
  return segments[1]; // e.g. /route-a/{contextId} → contextId
});

builder.setContextPathGenerator((context, pathname) => {
  // Generate a URL with context in your custom position
  const segments = pathname.split('/').filter(Boolean);
  const route = segments[0] ?? '';
  return `/${route}/${context.id}`;
});

When these hooks are registered, the plugin's custom adapter picks them up automatically — no manifest contextRouting declaration needed.

The app owns its URL shape, so the URL is the source of truth for the URL guard:

• A route where the extractor returns no context (e.g. a list page such as /categories) is a route without context. The URL guard does not put the active context back into it.
• A route where the extractor returns a context that is not active (e.g. a link from a list page to /app/{key}) applies that context, in both push and replace mode and also when no context is active.
• Clearing context while on a route without context keeps the user there. Clearing context on a route that has context navigates to the app root.
• Selecting a context while on a route without context still navigates to the path from generatePathFromContext.

The extracted value does not have to be the context id. If it is a key or slug, the URL guard treats the URL as in sync when generatePathFromContext writes that same value for the active context. So navigating within the same context does not resolve it again. A generator that returns the path unchanged doesn't prove anything, so the guard resolves the value from the URL instead. Repeated keys in unrelated route segments do not trigger another lookup.

When the URL guard resolves a context from the URL, the lookup belongs to that URL. If the user navigates elsewhere before the lookup finishes, the guard cancels it: a late result neither changes the context nor redirects the user. App dismissal, app switches, and module loading also cancel pending lookups, even before the next navigation event or when the destination has no context module.

For Portal Developers

The rest of this README covers portal-level setup and configuration.

Key Concepts

How It Works

1. Observe — The reconciler watches the current app and current context via a configurable source factory.
2. Resolve adapter — For each app, the first adapter whose canHandle() returns true is selected.
3. Encode — The selected adapter encodes the context into a target URL.
4. Compare — If the target URL differs from the current URL, navigation proceeds.
5. Dispatch — A cancelable onContextNavigationNavigate event fires. Listeners can call preventDefault() to abort.
6. Navigate — The framework navigation module performs the URL update.
7. Confirm — An onContextNavigationNavigated event fires after navigation completes.

Installation

pnpm add @equinor/fusion-framework-plugin-context-navigation

Quick Start

App-portal (app switches lead)

An app-portal shows one app at a time. When the user switches apps, the reconciler picks up the new app's context and encodes it into the URL. This is the default behavior.

import { enableContextNavigation } from '@equinor/fusion-framework-plugin-context-navigation';

export const configure = (configurator) => {
  enableContextNavigation(configurator, (builder) => {
    builder.setPortalName('app-portal');
    builder.setDebug(true);
  });
};

The default source factory (createAppFirstSource) watches app.current$ and resolves the app's context modules before emitting to the reconciler. When an app switch happens, the new app's active context drives the URL update.

Context-portal (context changes lead)

A context-portal is organized around a shared context (e.g. a project). When the user selects a context, navigation updates the URL immediately — regardless of which app is active. Clearing context navigates back to the portal root.

import { enableContextNavigation } from '@equinor/fusion-framework-plugin-context-navigation';
import { createContextFirstSource } from '@equinor/fusion-framework-plugin-context-navigation/sources';

export const configure = (configurator) => {
  enableContextNavigation(configurator, (builder) => {
    builder.setPortalName('context-portal');
    builder.setSourceFactory(createContextFirstSource());
    builder.setNullContextUrl('/');
    builder.setDebug(true);
  });
};

Key differences from app-portal:

• createContextFirstSource() — context changes are the primary trigger; app modules are resolved as a dependency.
• setNullContextUrl('/') — when context is cleared, navigate to the portal landing page instead of delegating to the adapter.

Built-in Adapters

The plugin ships with three adapters evaluated in priority order:

When no custom adapters are registered, all three built-in adapters are available. The first whose canHandle() returns true for the current app wins.

Registering a Custom Adapter

You can register your own adapters for URL shapes not covered by the built-in set. The canHandle predicate controls when your adapter is selected — use any signal available in AdapterResolutionContext (app key, URL, context provider, routing strategy).

import type { ContextNavigationAdapter } from '@equinor/fusion-framework-plugin-context-navigation/adapters';

const hashAdapter: ContextNavigationAdapter = {
  id: 'hash',
  // Select this adapter for a specific app that uses hash-based context
  canHandle: ({ appKey }) => appKey === 'my-hash-app',
  encode: ({ context, currentURL }) => {
    const url = new URL(currentURL.href);
    url.hash = context ? `#ctx=${context.id}` : '';
    return url;
  },
  decode: (url) => {
    const match = url.hash.match(/^#ctx=(.+)$/);
    return match?.[1] ?? null;
  },
};

enableContextNavigation(configurator, (builder) => {
  builder.registerAdapter(hashAdapter);
  // NOTE: registering any adapter disables built-in defaults.
  // Register all adapters you need explicitly.
});

Configuration

Events

The plugin dispatches events through the Fusion Framework event system. Subscribe via framework.event.addEventListener().

Skip Reasons

The onContextNavigationSkipped event includes a reason field:

Intercepting Navigation

framework.event.addEventListener('onContextNavigationNavigate', (event) => {
  console.log('About to navigate:', event.detail.targetURL.pathname);

  // Cancel navigation conditionally
  if (shouldBlock(event.detail)) {
    event.preventDefault();
  }
});

Adapter Interface

interface ContextNavigationAdapter {
  /** Unique identifier for logging and diagnostics. */
  id: string;
  /** Return `true` if this adapter handles the given app/URL combination. */
  canHandle(ctx: AdapterResolutionContext): boolean;
  /** Encode context into a URL. Return `null` to skip navigation. */
  encode(args: { context: ContextItem | null; currentURL: URL }): URL | null;
  /** Decode a context ID from a URL. Return `null` if not present. */
  decode(url: URL): string | null;
}

interface AdapterResolutionContext {
  appKey: string;
  appContext: IContextProvider;
  routingStrategy?: 'path' | 'query' | null;
  currentURL: URL;
}

Exports

Peer Dependencies

See Also

• @equinor/fusion-framework-module-context — context module for query, validation, and resolution
• @equinor/fusion-framework-module-app — app module defining FrameworkOptions.contextRouting in build manifest