@equinor/fusion-framework-module-context 7.0.4-next.0 → 8.0.1

package/CHANGELOG.md

@@ -1,14 +1,45 @@
 # Change Log
 
-## 7.0.4-next.0
+## 8.0.1
 
 ### Patch Changes
 
-- [#3820](https://github.com/equinor/fusion-framework/pull/3820) [`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78) Thanks [@odinr](https://github.com/odinr)! - relase next
+- 80c3e4a: Internal: resolve `noExplicitAny`/`noConfusingVoidType` Biome warnings in `ContextConfigBuilder` and `ContextModuleConfigurator`'s `resolveInitialContext` callback type, using explanatory `biome-ignore` comments for load-bearing `any`/`void` usages. No public API or behavior change.
+- 80c3e4a: Internal: move `FusionContextSearchError` into `src/errors/FusionContextSearchError.ts` with an `errors/index.ts` barrel, resolving a `filename-convention` lint violation; no public API changes.
+- 80c3e4a: Internal: add a required fusion-lint intent comment explaining an `as unknown as T` cast in `ContextProvider`. No behavior change.
+- 80c3e4a: Resolve fusion-lint warnings: add missing TSDoc (constructors, getters, setters, overload implementations, `@throws`/`@template` tags), add intent comments above control-flow and RxJS/iterator chains, and split multi-export files to satisfy `single-export-per-file`.
+  - Split `selectors.ts` into `query-context-selector.ts` and `related-context-selector.ts` (re-exported from `selectors.ts`), and extracted `parseContextItem` into `parse-context-item.ts`.
+  - Split `extractContextIdFromPath` out of `utils/resolve-context-from-path.ts` into `utils/extract-context-id-from-path.ts` (re-exported from the original file).
+  - Deferred work items are now tracked as GitHub issues #5115–#5122.
 
-- Updated dependencies [[`f647825`](https://github.com/equinor/fusion-framework/commit/f647825cb5712763b09dafda21fd996211c78b78)]:
-  - @equinor/fusion-query@6.0.5-next.0
-  - @equinor/fusion-framework-module@5.0.7-next.0
+- 80c3e4a: Internal: renamed 45 source files across these packages to comply with the `filename-convention` lint rule (e.g. `AIConfigurator.ts` → `AiConfigurator.ts`, `BookmarkProvider.actions.ts` → `bookmark-actions.ts`, `errors/app-build-error.ts` → `errors/AppBuildError.ts`, `plugins/api/plugin.ts` → `plugins/api/ApiPlugin.ts`, `errors.ts` → `UnsupportedApiVersion.ts`, etc.). Also added `enable-signalr.ts` to the `filename-convention` exclude list since the suggested rename would incorrectly split the "SignalR" brand name. No public API changes.
+- 80c3e4a: Internal: added missing intent comments ahead of non-obvious control flow, RxJS `.pipe()` chains, iterator calls, and multi-source object merges to comply with the `require-intent-comment` and `require-tsdoc` lint rules. Also removed dead duplicate files left over from an earlier refactor in `navigation` (`events.ts`, `navigated-event.ts`, `history.flows.ts` — all fully superseded by their split replacements) and renamed `bookmarks/schemas.ts` to `bookmarks/bookmark.schemas.ts` in `services` to match the `*.schemas.ts` filename convention. No public API changes.
+
+## 8.0.0
+
+### Major Changes
+
+- abffa53: Major version bump for Fusion Framework React 19 release.
+
+  All packages are bumped to the next major version as part of the React 19 upgrade. This release drops support for React versions below 18 and includes breaking changes across the framework.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React Router upgraded from v6 to v7
+  - Navigation module refactored with new history API
+  - `renderComponent` and `renderApp` now use `createRoot` API
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading
+  - Replace `NavigationProvider.createRouter()` with `@equinor/fusion-framework-react-router`
+  - See individual package changelogs for package-specific migration steps
+
+### Patch Changes
+
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+  - @equinor/fusion-framework-module@6.0.0
+  - @equinor/fusion-query@7.0.0
 
 ## 7.0.3
 
@@ -20,16 +51,6 @@
   - @equinor/fusion-framework-module@5.0.6
   - @equinor/fusion-query@6.0.4
 
-## 7.0.3-next.0
-
-### Patch Changes
-
-- [#3820](https://github.com/equinor/fusion-framework/pull/3820) [`265bb76`](https://github.com/equinor/fusion-framework/commit/265bb767249989eeb1971e83f3fba94879e0813b) Thanks [@odinr](https://github.com/odinr)! - relase next
-
-- Updated dependencies [[`265bb76`](https://github.com/equinor/fusion-framework/commit/265bb767249989eeb1971e83f3fba94879e0813b), [`75c068f`](https://github.com/equinor/fusion-framework/commit/75c068fea13c32435ac26bd9043cc156482bfaf1)]:
-  - @equinor/fusion-query@7.0.0-next.0
-  - @equinor/fusion-framework-module@5.0.6-next.0
-
 ## 7.0.2
 
 ### Patch Changes

package/README.md

@@ -1,33 +1,185 @@
-## Overview
+# @equinor/fusion-framework-module-context
 
-The `@equinor/fusion-framework-module-context` package is a core module of the Fusion Framework, designed to manage contextual data within Fusion-based applications and portals.
-It provides a structured way to handle context information to enrich user experiences and facilitate data sharing across different components of the application.
+Context module for the Fusion Framework. Manages the active context (project, facility, contract, etc.) within Fusion-based applications and portals, providing query, validation, resolution, and parent–child synchronization out of the box.
 
-## Configuration
+## When to use
+
+Use this module when your application or portal needs to:
+
+- set, read, or clear the active context (e.g. selecting a project)
+- search and filter available context items from the Fusion context API
+- validate whether a given context item matches the allowed context types
+- resolve context across parent–child provider boundaries (portal → app)
+- deep-link by extracting a context ID from the URL path
+
+> **Application developers** will typically use the higher-level
+> `@equinor/fusion-framework-react-app/context` package, which wraps this
+> module with React hooks and providers.
+>
+> **Portal developers** will use `@equinor/fusion-framework-react/context`
+> for the same purpose at the portal level.
+
+## Key concepts
+
+| Concept | Description |
+|---|---|
+| **ContextItem** | A typed record representing a single context entity (project, facility, etc.). |
+| **ContextProvider** | Runtime service exposing query, set, validate, resolve, and event APIs. |
+| **ContextConfigBuilder** | Fluent builder for configuring context types, filters, clients, and hooks. |
+| **enableContext** | Helper that registers the module on a modules configurator. |
+| **Context resolution** | Automatic lookup of related context items when a context type does not match the configured types. |
+| **Parent connection** | Bi-directional sync between a parent portal context and a child app context. |
+
+## Quick start
 
 ```ts
 import { enableContext } from '@equinor/fusion-framework-module-context';
 
-const configure = (configurator: IModulesConfigurator<any, any>) => {
+export const configure = (configurator) => {
   enableContext(configurator, (builder) => {
-    // configure the context module here
+    // only accept ProjectMaster context items
+    builder.setContextType(['ProjectMaster']);
   });
 };
 ```
 
-## Features
+Once initialized, access the provider from the module instance:
+
+```ts
+// observe context changes
+modules.context.currentContext$.subscribe((ctx) => {
+  console.log('context changed', ctx);
+});
+
+// search for context items
+const items = await modules.context.queryContextAsync('Johan');
+
+// set context by item
+await modules.context.setCurrentContextAsync(items[0]);
+
+// set context by ID
+await modules.context.setCurrentContextByIdAsync('7fd97952-...');
+
+// clear the active context
+modules.context.clearCurrentContext();
+```
+
+## Configuration
+
+All configuration flows through `enableContext` → `ContextConfigBuilder`:
+
+```ts
+enableContext(configurator, (builder) => {
+  // restrict accepted context types
+  builder.setContextType(['ProjectMaster', 'Facility']);
+
+  // post-query filter
+  builder.setContextFilter((items) => items.filter((i) => i.isActive));
+
+  // custom parameter mapping for the search API
+  builder.setContextParameterFn(({ search, type }) => ({
+    search,
+    filter: { type },
+  }));
+
+  // custom validation logic
+  builder.setValidateContext(function (item) {
+    return item !== null && this.validateContext(item);
+  });
+
+  // custom context resolution
+  builder.setResolveContext(function (item) {
+    return this.relatedContexts({ item, filter: { type: ['ProjectMaster'] } });
+  });
+
+  // connect (or disconnect) from parent context
+  // when enabled (default), onParentContextChanged fires before mirroring the parent's context locally
+  builder.connectParentContext(false);
+
+  // path ↔ context integration
+  // the default resolver uses extractContextIdFromPath to pull a GUID from the URL,
+  // then fetches the matching context item — see resolveInitialContext in utils
+  builder.setContextPathExtractor((path) => path.split('/')[2]);
+  builder.setContextPathGenerator((ctx, path) =>
+    path.replace(/\/context\/[^/]+/, `/context/${ctx.id}`),
+  );
+
+  // provide a fully custom context client
+  builder.setContextClient({
+    get: (args) => fetch(`/api/context/${args.id}`).then((r) => r.json()),
+    query: (args) => fetch(`/api/context?q=${args.search}`).then((r) => r.json()),
+  });
+});
+```
+
+### Configuration reference
+
+| Builder method | Purpose |
+|---|---|
+| `setContextType(types)` | Allowed context type IDs for validation |
+| `setContextFilter(fn)` | Post-query result filter |
+| `setContextParameterFn(fn)` | Maps search + type to API query params |
+| `setValidateContext(fn)` | Custom validation (`this` = provider) |
+| `setResolveContext(fn)` | Custom resolution (`this` = provider) |
+| `connectParentContext(bool)` | Enable/disable parent context sync (fires `onParentContextChanged` on change) |
+| `setContextPathExtractor(fn)` | Extract context ID from URL path |
+| `setContextPathGenerator(fn)` | Generate URL path from context item |
+| `setResolveInitialContext(fn)` | Override initial context resolution (default uses `extractContextIdFromPath` → `resolveContextFromPath`) |
+| `setContextClient(client)` | Custom get/query/related clients |
+
+## Events
+
+The context module dispatches events via the `@equinor/fusion-framework-module-event` system. All events are scoped to the `ContextProvider` source.
+
+| Event | When | Cancelable |
+|---|---|---|
+| `onCurrentContextChange` | Before the current context is updated | Yes |
+| `onCurrentContextChanged` | After the current context has changed | No |
+| `onParentContextChanged` | Before a parent context change is mirrored locally | Yes |
+| `onSetContextResolve` | Before context resolution begins | Yes |
+| `onSetContextResolved` | After context resolution completes | Yes |
+| `onSetContextValidationFailed` | When validation fails (no resolution) | No |
+| `onSetContextResolveFailed` | When resolution fails with an error | No |
+
+```ts
+modules.event.addEventListener('onCurrentContextChanged', (e) => {
+  console.log('previous:', e.detail.previous);
+  console.log('next:', e.detail.next);
+});
+```
+
+## Errors
+
+The module exports `FusionContextSearchError` (from `@equinor/fusion-framework-module-context/errors.js`) for search-related failures:
+
+```ts
+import { FusionContextSearchError } from '@equinor/fusion-framework-module-context/errors.js';
+
+try {
+  await modules.context.queryContextAsync('...');
+} catch (err) {
+  if (err instanceof FusionContextSearchError) {
+    console.error(err.title, err.description);
+  }
+}
+```
 
-- set and retrieve context items
-- query context items based on search strings
-- filter context items based on type
-- validate context items against allowed types
-- resolving related context items
+## Utilities
 
-## Usage
+Additional helpers are available from `@equinor/fusion-framework-module-context/utils`:
 
-This module is the core of the context management system in Fusion Framework applications, but there are several packages which has additional functionality or provide a more convenient API for specific use cases.
+| Export | Purpose |
+|---|---|
+| `enableContext` | Register the context module on a configurator |
+| `resolveInitialContext` | Default initial-context resolver (path → parent fallback) |
+| `extractContextIdFromPath` | Extract a GUID-format context ID from a URL path |
+| `resolveContextFromPath` | Create a resolver function that fetches a context item from a URL path |
 
-When developing applications, the `@equinor/fusion-framework-react-app/context` package is typically used to provide a React context provider that integrates with this module.
+## Package exports
 
-When building portals, the `@equinor/fusion-framework-react/context` package is used to provide a context provider that integrates with this module.
+| Specifier | Description |
+|---|---|
+| `@equinor/fusion-framework-module-context` | Main entry — module, provider, configurator, types |
+| `@equinor/fusion-framework-module-context/errors.js` | `FusionContextSearchError` |
+| `@equinor/fusion-framework-module-context/utils` | Utility functions for path resolution and enablement |
 

package/dist/esm/ContextConfigBuilder.js

@@ -21,7 +21,7 @@
  * - The builder pattern allows chaining configuration methods for clarity and convenience.
  * - The `requireInstance` method enables asynchronous retrieval of module instances by name.
  *
- * @todo - this should extend the BaseConfigBuilder
+ * @todo(#5120) - this should extend the BaseConfigBuilder
  *
  * @see ContextModuleConfig
  * @see ModuleInitializerArgs
@@ -29,10 +29,20 @@
 export class ContextConfigBuilder {
     config;
     #init;
+    /**
+     * Creates a new `ContextConfigBuilder`.
+     * @param init - Module initializer arguments used to resolve module instances.
+     * @param config - The partial context module config to build upon.
+     */
     constructor(init, config = {}) {
         this.config = config;
         this.#init = init;
     }
+    /**
+     * Requires a module instance by key or name.
+     * @param module - The key or name of the module to resolve.
+     * @returns A promise that resolves to the requested module instance.
+     */
     requireInstance(module) {
         return this.#init.requireInstance(module);
     }
@@ -101,6 +111,13 @@ export class ContextConfigBuilder {
     setContextPathGenerator(fn) {
         this.config.generatePathFromContext = fn;
     }
+    /**
+     * Sets the function used to resolve the initial context during module post-initialization.
+     *
+     * @param fn - A function that returns an observable input emitting the initial context item.
+     *             The default resolver extracts a context ID from the navigation path, falling
+     *             back to the parent provider's current context.
+     */
     setResolveInitialContext(fn) {
         this.config.resolveInitialContext = fn;
     }
@@ -117,7 +134,7 @@ export class ContextConfigBuilder {
      * @param expire - Optional. The expiration time (in milliseconds) for cached query results. Defaults to 1 minute.
      */
     setContextClient(client, expire = 1 * 60 * 1000) {
-        this.config.client = {
+        const clientConfig = {
             get: typeof client.get === 'function'
                 ? {
                     key: ({ id }) => id,
@@ -129,7 +146,7 @@ export class ContextConfigBuilder {
                 : client.get,
             query: typeof client.query === 'function'
                 ? {
-                    // TODO - might cast to checksum
+                    // TODO(#5118) - might cast to checksum
                     key: (args) => JSON.stringify(args),
                     client: {
                         fn: client.query,
@@ -138,12 +155,13 @@ export class ContextConfigBuilder {
                 }
                 : client.query,
         };
+        this.config.client = clientConfig;
+        // only override the related-context client config if one was provided
         if (client.related) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this.config.client.related =
+            clientConfig.related =
                 typeof client.related === 'function'
                     ? {
-                        // TODO - might cast to checksum
+                        // TODO(#5118) - might cast to checksum
                         key: (args) => JSON.stringify(args),
                         client: {
                             fn: client.related,

package/dist/esm/ContextConfigBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextConfigBuilder.js","sourceRoot":"","sources":["../../src/ContextConfigBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ContextConfigBuilder.js","sourceRoot":"","sources":["../../src/ContextConfigBuilder.ts"],"names":[],"mappings":"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"}

package/dist/esm/ContextProvider.js

@@ -44,29 +44,59 @@ export class ContextProvider extends BaseModuleProvider {
     #contextFilter;
     #contextParameterFn;
     #contextQueue = new Subject();
+    /**
+     * The underlying context client used to resolve and hold the current context item.
+     * @returns The internal {@link ContextClient} instance.
+     */
     get contextClient() {
         return this.#contextClient;
     }
+    /**
+     * The query client used to search for context items.
+     * @returns The internal `Query` instance used by {@link queryContext}.
+     */
     get queryClient() {
         return this.#contextQuery;
     }
+    /**
+     * Observable stream emitting the current context item.
+     * @returns Observable that emits the current `ContextItem`, `null`, or `undefined`.
+     */
     get currentContext$() {
         return this.#contextClient.currentContext$;
     }
+    /**
+     * Snapshot of the current context item.
+     * @returns The current `ContextItem`, or `null`/`undefined` if not set.
+     */
     get currentContext() {
         return this.#contextClient.currentContext;
     }
-    /** @deprecated do not use, will be removed */
+    /**
+     * Sets the current context item.
+     * @deprecated do not use, will be removed
+     * @param context - The context item to set as current. Must not be `undefined`.
+     * @throws Error if `context` is `undefined`.
+     */
     set currentContext(context) {
         console.warn('@deprecated', 'ContextProvider.currentContext', 'use setCurrentContextById|setCurrentContext|clearCurrentContext');
+        // undefined is reserved to mean "not yet initialized", so it cannot be set explicitly
         if (context === undefined) {
             throw Error('not allowed to set current context as undefined undefined!');
         }
         this.setCurrentContextAsync(context);
     }
+    /**
+     * Creates a new instance of `ContextProvider`.
+     * @param args - Constructor arguments.
+     * @param args.config - The context module configuration.
+     * @param args.event - Optional event module instance for dispatching context change events.
+     * @param args.parentContext - Optional parent context provider. Deprecated, use {@link connectParentContext}.
+     */
     constructor(args) {
         const { config, event } = args;
         super({ version, config });
+        // warn about deprecated parentContext constructor arg
         if (args.parentContext) {
             console.warn('@deprecated', 'parentContext as arg is deprecated, use ContextProvider.connectParentContext');
         }
@@ -75,15 +105,18 @@ export class ContextProvider extends BaseModuleProvider {
         if (config.resolveContext) {
             this.resolveContext = config.resolveContext?.bind(this);
         }
+        // override validateContext if configured
         if (config.validateContext) {
             this.validateContext = config.validateContext?.bind(this);
         }
+        // override extractContextIdFromPath if configured
         if (config.extractContextIdFromPath) {
-            // @ts-ignore
+            // @ts-expect-error
             this.extractContextIdFromPath = config.extractContextIdFromPath;
         }
+        // override generatePathFromContext if configured
         if (config.generatePathFromContext) {
-            // @ts-ignore
+            // @ts-expect-error
             this.generatePathFromContext = config.generatePathFromContext;
         }
         this.#contextType = config.contextType;
@@ -91,6 +124,7 @@ export class ContextProvider extends BaseModuleProvider {
         // create clients
         this.#contextClient = new ContextClient(config.client.get);
         this.#contextQuery = new Query(config.client.query);
+        // only create the related-context query when the config provides one
         if (config.client.related) {
             this.#contextRelated = new Query(config.client.related);
         }
@@ -107,9 +141,8 @@ export class ContextProvider extends BaseModuleProvider {
             this.#subscriptions.add(
             // observe current context changes
             this.currentContext$
-                .pipe(
-            // emit previous and next context
-            pairwise())
+                // emit previous and next context together for change comparisons
+                .pipe(pairwise())
                 .subscribe(([previous, next]) => {
                 this.#event?.dispatchEvent('onCurrentContextChanged', {
                     source: this,
@@ -153,11 +186,12 @@ export class ContextProvider extends BaseModuleProvider {
      * @returns A `Subscription` object representing the connection to the parent context.
      */
     connectParentContext(provider, opt) {
+        // build a stream of validated context changes from the parent provider
         const parentContext$ = provider.currentContext$.pipe(
         // do not set context if parent has not initialized
         filter((x) => x !== undefined), filter((next, index) => {
             // skip first item if opt.skipFirst is true
-            // TODO: this is a bit hacky, should be handled in a better way
+            // TODO(#5121): this is a bit hacky, should be handled in a better way
             if (opt?.skipFirst && index <= 1) {
                 console.debug('ContextProvider::connectParentContext', 'skipping first item', next);
                 return false;
@@ -165,8 +199,8 @@ export class ContextProvider extends BaseModuleProvider {
             // only set context if it has changed
             return this.currentContext?.id !== next?.id;
         }), switchMap(async (next) => {
+            // if parent context is null, just return
             if (!next) {
-                // if parent context is null, just return
                 return { next };
             }
             // notify event observers that parent context is about to change and await for cancelation
@@ -180,14 +214,16 @@ export class ContextProvider extends BaseModuleProvider {
         // filter out canceled context changes
         filter((x) => !x.canceled), switchMap(({ next }) => {
             // set current context with validation and resolution
-            return this.setCurrentContext(next, {
+            return (this.setCurrentContext(next, {
                 validate: true,
                 resolve: true,
-            }).pipe(catchError((err) => {
+            })
+                // swallow errors so a failed context change doesn't break the parent subscription
+                .pipe(catchError((err) => {
                 console.warn('ContextProvider::onParentContextChanged', 'setCurrentContext', err);
                 // do not emit any value if an error occurs
                 return EMPTY;
-            }));
+            })));
         }), catchError((err) => {
             console.warn('ContextProvider::onParentContextChanged', 'unhandled exception', err);
             // do not emit any value if an error occurs
@@ -217,6 +253,7 @@ export class ContextProvider extends BaseModuleProvider {
                 this.#contextClient
                     // resolve context item by id
                     .resolveContext(id)
+                    // filter out invalid items and set as current context
                     .pipe(
                 // filter out invalid context items
                 filter((item) => !!item), 
@@ -256,12 +293,18 @@ export class ContextProvider extends BaseModuleProvider {
      * If the observable is subscribe, unsubscribing __WILL__ abort the task and remove it from queue
      *
      * @param context context item which would be queue to set as current
+     * @param opt Optional settings.
+     * @param opt.validate Whether to validate the context item before setting it.
+     * @param opt.resolve Whether to attempt to resolve the context item if validation fails.
+     * @template T The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+     * @returns An observable that emits the context item once the queued task completes.
      */
     setCurrentContext(context, opt) {
         // signal for aborting the queue entry
         const abort$ = new Subject();
         // wrapper for returning an observable to the caller
         const subject$ = new Subject();
+        // run the actual context-setting logic and relay results/errors to the caller's subject
         const task$ = this._setCurrentContext(context, opt).pipe(
         // send context item which was set to the caller
         tap((x) => subject$.next(x)), 
@@ -278,6 +321,7 @@ export class ContextProvider extends BaseModuleProvider {
         }));
         // add task to internal queue
         this.#contextQueue.next(task$);
+        // tear down the queued task if the caller unsubscribes
         return subject$.pipe(
         // if caller subscribes, unsubscribe should abort queue entry
         finalize(() => abort$.next(true)));
@@ -311,7 +355,7 @@ export class ContextProvider extends BaseModuleProvider {
      *    - Emit the context and complete the observable.
      *
      * @protected
-     * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+     * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
      * @param context - The new context to set.
      * @param opt - Optional settings:
      *   - `validate`: Whether to validate the context before setting.
@@ -342,7 +386,10 @@ export class ContextProvider extends BaseModuleProvider {
                     // emit error and complete
                     return subscriber.error(Error('failed to validate provided context'));
                 }
+                // if resolve is enabled, attempt to resolve the invalid context before setting it
                 if (opt.resolve) {
+                    // the recursive `_setCurrentContext` call below is re-entered with the already
+                    // validated/resolved context, so the generic `T` cast is safe here.
                     return of(context)
                         .pipe(
                     // notify event observers that context is about to get resolved
@@ -360,7 +407,9 @@ export class ContextProvider extends BaseModuleProvider {
                         return context;
                     }), 
                     // resolve context
-                    switchMap((context) => this.resolveContext(context).pipe(map((resolved) => ({
+                    switchMap((context) => 
+                    // Pair the resolved context alongside the original for downstream consumers.
+                    this.resolveContext(context).pipe(map((resolved) => ({
                         context,
                         resolved,
                     })))), 
@@ -413,7 +462,7 @@ export class ContextProvider extends BaseModuleProvider {
      *
      * @see {@link setCurrentContext} for more details.
      *
-     * @typeParam T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
+     * @template T - The type of the context item, which extends `ContextItem<Record<string, unknown>>` or can be `null`.
      * @param context - The context item to set as the current context, or `null` to clear it.
      * @param opt - Optional settings for context handling.
      * @param opt.validate - If `true`, validates the context before setting it.
@@ -433,6 +482,7 @@ export class ContextProvider extends BaseModuleProvider {
      *
      * @param search - The search string to filter context items.
      * @returns An Observable that emits an array of `ContextItem` objects matching the search criteria.
+     * @throws Re-throws the underlying cause of a `QueryClientError`, otherwise re-throws the original error.
      */
     queryContext(search) {
         const query$ = this.queryClient
@@ -442,6 +492,7 @@ export class ContextProvider extends BaseModuleProvider {
             search,
             type: this.#contextType,
         }))
+            // unwrap query-client errors and expose the underlying cause to subscribers
             .pipe(catchError((err) => {
             // if query client throws a QueryClientError, extract the cause and throw it
             if (err.name === 'QueryClientError') {
@@ -470,8 +521,10 @@ export class ContextProvider extends BaseModuleProvider {
      * @returns `true` if the context type is not set or if the item's type ID matches one of the allowed types (case-insensitive); otherwise, `false`.
      */
     validateContext(item) {
+        // no context type configured means every context item is considered valid
         if (!this.#contextType)
             return true;
+        // normalize allowed types for a case-insensitive comparison
         return this.#contextType.map((x) => x.toLowerCase()).includes(item.type.id.toLowerCase());
     }
     /**
@@ -492,7 +545,9 @@ export class ContextProvider extends BaseModuleProvider {
         // request related context items for the given context item with the same context type which the provider is configured with
         return this.relatedContexts({ item, filter: { type: this.#contextType } }).pipe(
         // filter out invalid context items
-        map((x) => x.filter((item) => this.validateContext(item))), map((values) => {
+        map((x) => 
+        // keep only context items that validate against the provider's context type
+        x.filter((item) => this.validateContext(item))), map((values) => {
             // related context should be resolved to a single context item
             const value = values.shift();
             // if no value is found, throw an error
@@ -536,6 +591,7 @@ export class ContextProvider extends BaseModuleProvider {
         }
         // request related context items
         return this.#contextRelated.query(args).pipe(map(({ value }) => value), catchError((err) => {
+            // unwrap the underlying cause so callers see the original error
             if (err.cause) {
                 throw err.cause;
             }