@equinor/fusion-framework-plugin-context-navigation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Equinor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# 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`:
+
+```jsonc
+// app.manifest.config.ts
+export default defineAppManifest((env) => ({
+  // ...
+  build: {
+    options: {
+      contextRouting: 'query',  // or 'path', or omit for default path behavior
+    },
+  },
+}));
+```
+
+| Value | URL Shape | When to Use |
+|---|---|---|
+| `'path'` (or omitted) | `/apps/{appKey}/{contextId}/sub-route` | Default — simple apps without complex routing |
+| `'query'` | `/apps/{appKey}/route?$contextId={id}` | Apps with path-based sub-routes that conflict with a context segment |
+
+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 regardless of the `contextRouting` value.
+
+### 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:
+
+```ts
+// 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.
+
+## For Portal Developers
+
+The rest of this README covers portal-level setup and configuration.
+
+## Key Concepts
+
+| Concept | Description |
+|---|---|
+| **Adapter** | A self-selecting URL encoder/decoder. Each adapter declares `canHandle()` and provides `encode()` / `decode()` methods. |
+| **Reconciler** | The reactive loop that watches context + app changes and triggers navigation when the URL is out of sync. |
+| **URL Guard** | An optional secondary subscription that re-applies context encoding if an external navigation drops the context from the URL. |
+| **Source** | The observable factory that drives the reconciler — determines whether app switches or context changes take priority. |
+
+### 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
+
+```sh
+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.
+
+```ts
+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.
+
+```ts
+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:
+
+| Adapter | URL Shape | When Selected |
+|---|---|---|
+| **custom** | App-defined (via `generatePathFromContext` / `extractContextIdFromPath` hooks) | App provides `generatePathFromContext` and/or `extractContextIdFromPath` hooks on its context provider |
+| **query** | `/apps/{appKey}/route?$contextId={id}` | App manifest declares `build.options.contextRouting: 'query'` |
+| **path** | `/apps/{appKey}/{contextId}/sub-route` | Default fallback — matches when `contextRouting` is `'path'`, `null`, or omitted |
+
+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).
+
+```ts
+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
+
+| Builder Method | Default | Description |
+|---|---|---|
+| `registerAdapter(adapter)` | Built-in set | Register a navigation adapter (object or factory). First match wins. |
+| `setPortalName(name)` | `'Portal'` | Name used in debug log output. |
+| `setOrigin(origin)` | `window.location.origin` | Origin for constructing absolute URLs. |
+| `setUrlGuard(enabled)` | `true` | Re-sync context if an external navigation drops it from the URL. With `replace: false`, back/forward navigations update context from the URL instead of overwriting it. |
+| `setDebug(enabled)` | `false` | Enable verbose `console.debug` output. |
+| `setNullContextUrl(urlOrFn)` | — | Function (or static string) that returns the URL to navigate to when context is cleared. Receives `{ appKey, currentURL }`. |
+| `setNavigationOptions(options)` | `{ replace: true }` | Options passed to `navigation.navigate()` during URL updates. Set `{ replace: false }` to push history entries — back/forward will then sync context from the URL rather than re-asserting the active context. |
+| `setOnTransition(fn)` | — | Side-effect hook called after each successful navigation. |
+| `setSourceFactory(factory)` | `createAppFirstSource()` | Observable source factory that drives the reconciler. |
+
+## Events
+
+The plugin dispatches events through the Fusion Framework event system. Subscribe via `framework.event.addEventListener()`.
+
+| Event | When | Cancelable |
+|---|---|---|
+| `onContextNavigationNavigate` | Before navigation — adapter resolved, target URL computed | **Yes** |
+| `onContextNavigationNavigated` | After navigation completes | No |
+| `onContextNavigationAdapterResolved` | When an adapter is selected for an app | No |
+| `onContextNavigationSkipped` | When reconciliation decides NOT to navigate | No |
+
+### Skip Reasons
+
+The `onContextNavigationSkipped` event includes a `reason` field:
+
+| Reason | Meaning |
+|---|---|
+| `'url-matches'` | Target URL already matches the current URL |
+| `'no-context'` | Context is `undefined` (still initializing) |
+| `'no-adapter'` | No adapter could handle the current app |
+| `'encode-returned-null'` | Adapter's `encode()` returned `null` |
+| `'canceled'` | A listener called `preventDefault()` on the navigate event |
+
+### Intercepting Navigation
+
+```ts
+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
+
+```ts
+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
+
+| Specifier | Description |
+|---|---|
+| `@equinor/fusion-framework-plugin-context-navigation` | Plugin runtime, configurator, enable helper, types, events |
+| `@equinor/fusion-framework-plugin-context-navigation/adapters` | Built-in adapter factories (`createPathAdapter`, `createQueryAdapter`, `createCustomAdapter`) |
+| `@equinor/fusion-framework-plugin-context-navigation/sources` | Source factories (`createAppFirstSource`, `createContextFirstSource`) and reconciler types |
+| `@equinor/fusion-framework-plugin-context-navigation/utils` | URL utility functions |
+
+## Peer Dependencies
+
+| Package | Purpose |
+|---|---|
+| `@equinor/fusion-framework-module` | Base module contract |
+| `@equinor/fusion-framework-module-app` | App switching and instance loading |
+| `@equinor/fusion-framework-module-context` | Context state management |
+| `@equinor/fusion-framework-module-navigation` | URL navigation |
+| `@equinor/fusion-framework-module-event` | Event dispatch |
+| `rxjs` | Reactive streams |
+
+## See Also
+
+- [`@equinor/fusion-framework-module-context`](../../modules/context/) — context module for query, validation, and resolution
+- [`@equinor/fusion-framework-module-app`](../../modules/app/) — app module defining `FrameworkOptions.contextRouting` in build manifest

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@equinor/fusion-framework-plugin-context-navigation",
+  "version": "0.1.0",
+  "description": "Adapter-based context-to-URL reconciler for Fusion Framework portals",
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/esm/adapters/index.js",
+      "types": "./dist/types/adapters/index.d.ts"
+    },
+    "./sources": {
+      "import": "./dist/esm/sources/index.js",
+      "types": "./dist/types/sources/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/esm/utils/url/index.js",
+      "types": "./dist/types/utils/url/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "rxjs": "^7.8.1",
+    "@equinor/fusion-framework-module": "^6.1.2",
+    "@equinor/fusion-framework-module-app": "^8.0.4",
+    "@equinor/fusion-framework-module-context": "^8.0.2",
+    "@equinor/fusion-framework-module-event": "^6.0.1",
+    "@equinor/fusion-framework-module-navigation": "^7.0.7"
+  },
+  "devDependencies": {
+    "rxjs": "^7.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@equinor/fusion-framework-module": "^6.1.2",
+    "@equinor/fusion-framework-module-app": "^8.0.4",
+    "@equinor/fusion-framework-module-context": "^8.0.2",
+    "@equinor/fusion-framework-module-event": "^6.0.1",
+    "@equinor/fusion-framework-module-navigation": "^7.0.7"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}