@equinor/fusion-framework-module-context 7.0.3 → 8.0.0

package/dist/types/ContextConfigBuilder.d.ts

@@ -3,6 +3,14 @@ import type { QueryCtorOptions, QueryFn } from '@equinor/fusion-query';
 import type { GetContextParameters } from './client/ContextClient';
 import type { ContextModuleConfig, ContextModuleConfigurator, IContextModuleConfigurator } from './configurator';
 import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
+/**
+ * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
+ *
+ * Receives a {@link ContextConfigBuilder} and may use its setter methods
+ * to populate the context module configuration. The callback may be async.
+ *
+ * @typeParam TDeps - Module dependency array inferred from the configurator.
+ */
 export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>(builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>) => void | Promise<void>;
 /**
  * A builder class for configuring and customizing context module behavior within the Fusion Framework.
@@ -87,6 +95,13 @@ export declare class ContextConfigBuilder<TModules extends Array<AnyModule> = []
      * @param fn - A function that takes a context and generates a corresponding path.
      */
     setContextPathGenerator(fn: ContextModuleConfig['generatePathFromContext']): void;
+    /**
+     * 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: ContextModuleConfig['resolveInitialContext']): void;
     /**
      * Sets the context client configuration for fetching context items.

package/dist/types/ContextProvider.d.ts

@@ -514,26 +514,63 @@ export declare class ContextProvider extends BaseModuleProvider<ContextModuleCon
 export default ContextProvider;
 declare module '@equinor/fusion-framework-module-event' {
     interface FrameworkEventMap {
+        /**
+         * Dispatched **before** the current context is changed.
+         *
+         * The event is cancelable — calling `event.preventDefault()` in a
+         * listener will abort the context change.
+         */
         onCurrentContextChange: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem | null;
         }, IContextProvider>>;
+        /**
+         * Dispatched **after** the current context has changed.
+         *
+         * Contains both the previous and next context items, enabling
+         * listeners to react to transitions.
+         */
         onCurrentContextChanged: FrameworkEvent<FrameworkEventInit<{
             next: ContextItem | null;
             previous?: ContextItem | null;
         }, IContextProvider>>;
+        /**
+         * Dispatched **before** a parent context change is applied locally.
+         *
+         * Cancelable — prevents the parent context from being mirrored into
+         * this provider.
+         */
         onParentContextChanged: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem | null;
         }, IContextProvider>>;
+        /**
+         * Dispatched **before** context resolution begins (when validation
+         * fails and the caller requested resolution).
+         *
+         * Cancelable — aborting prevents the resolution attempt.
+         */
         onSetContextResolve: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem;
         }, IContextProvider>>;
+        /**
+         * Dispatched **after** the context has been resolved to a new item.
+         *
+         * Cancelable — aborting prevents the resolved item from being
+         * set as the current context.
+         */
         onSetContextResolved: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem;
             resolved?: ContextItem | null;
         }, IContextProvider>>;
+        /**
+         * Dispatched when context validation fails and resolution is not
+         * enabled.
+         */
         onSetContextValidationFailed: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem;
         }, IContextProvider>>;
+        /**
+         * Dispatched when context resolution fails with an error.
+         */
         onSetContextResolveFailed: FrameworkEvent<FrameworkEventInit<{
             context: ContextItem;
             error: unknown;

package/dist/types/configurator.d.ts

@@ -7,46 +7,176 @@ import type { ContextFilterFn, ContextItem, QueryContextParameters, RelatedConte
 import type { GetContextParameters } from './client/ContextClient';
 import { type ContextConfigBuilderCallback } from './ContextConfigBuilder';
 import type { IContextProvider } from './ContextProvider';
+/**
+ * Resolved configuration for the context module.
+ *
+ * Holds query clients, type filters, parent-connection settings, and
+ * optional callbacks for validation, resolution, and path integration.
+ * Produced by {@link ContextModuleConfigurator.createConfig} after all
+ * {@link ContextConfigBuilder} callbacks have run.
+ *
+ * @see ContextConfigBuilder — fluent API for populating this config.
+ * @see ContextProvider — runtime consumer of this config.
+ */
 export interface ContextModuleConfig {
+    /**
+     * Query client options used to fetch, search, and resolve related context items.
+     *
+     * - `get` — retrieves a single context item by ID.
+     * - `query` — searches context items by text and optional type filter.
+     * - `related` — fetches context items related to a given item (used during resolution).
+     */
     client: {
         get: QueryCtorOptions<ContextItem, GetContextParameters>;
         query: QueryCtorOptions<ContextItem[], QueryContextParameters>;
         related?: QueryCtorOptions<ContextItem[], RelatedContextParameters>;
     };
+    /**
+     * Allowed context type IDs (e.g. `['ProjectMaster', 'Facility']`).
+     *
+     * When set, {@link ContextProvider.validateContext} only accepts items
+     * whose `type.id` matches one of these values (case-insensitive).
+     */
     contextType?: string[];
+    /**
+     * Optional post-query filter applied to the result set returned by
+     * {@link ContextProvider.queryContext}.
+     */
     contextFilter?: ContextFilterFn;
     /**
-     * connect context module to paren context module.
+     * Whether to connect the context module to a parent context module.
+     *
+     * When `true` (the default), the provider subscribes to the parent's
+     * `currentContext$` and mirrors changes into its own state.
      *
-     * _default: `true`_
+     * @defaultValue `true`
      */
     connectParentContext?: boolean;
-    /** set initial context from parent, will await resolve */
+    /**
+     * When `true`, skips resolving an initial context from the path or parent
+     * during module post-initialization.
+     */
     skipInitialContext?: boolean;
+    /**
+     * Extracts a context ID from a URL path segment.
+     *
+     * Used during initial context resolution and deep-link support.
+     * If not provided, the default GUID-based extractor is used.
+     *
+     * @param path - The URL path to inspect.
+     * @returns The extracted context ID, or `undefined` if none is found.
+     */
     extractContextIdFromPath?: (path: string) => string | undefined;
+    /**
+     * Generates a URL path that embeds the given context item's ID.
+     *
+     * Used by navigation integrations to update the browser URL when
+     * the context changes.
+     *
+     * @param context - The active context item.
+     * @param path - The current URL path.
+     * @returns The updated path, or `undefined` to leave it unchanged.
+     */
     generatePathFromContext?: (context: ContextItem, path: string) => string | undefined;
     /**
-     * Method for generating context query parameters.
+     * Transforms a user search string and the configured context type into
+     * the query parameters sent to the context API.
+     *
+     * Override this to customise how free-text searches are mapped to the
+     * backend query contract.
      */
     contextParameterFn?: (args: {
         search: string;
         type: ContextModuleConfig['contextType'];
     }) => string | QueryContextParameters;
+    /**
+     * Custom context resolution strategy.
+     *
+     * Called with `this` bound to the {@link IContextProvider} when a context
+     * item fails validation and the caller requests resolution.
+     *
+     * @param item - The context item to resolve, or `null`.
+     * @returns An observable emitting the resolved context item.
+     */
     resolveContext?: (this: IContextProvider, item: ContextItem | null) => ReturnType<IContextProvider['resolveContext']>;
+    /**
+     * Custom context validation strategy.
+     *
+     * Called with `this` bound to the {@link IContextProvider} to decide
+     * whether a candidate context item is acceptable.
+     *
+     * @param item - The context item to validate, or `null`.
+     * @returns `true` if the item is valid.
+     */
     validateContext?: (this: IContextProvider, item: ContextItem | null) => ReturnType<IContextProvider['validateContext']>;
+    /**
+     * Resolves the initial context during module post-initialization.
+     *
+     * The default implementation tries to extract a context ID from the
+     * current navigation path, falling back to the parent provider's context.
+     *
+     * @param args - Module reference and instance map.
+     * @returns An observable input emitting the initial context item, or void.
+     */
     resolveInitialContext?: (args: {
         ref?: AnyModuleInstance | any;
         modules: ModuleInstance;
     }) => ObservableInput<ContextItem | void>;
 }
+/**
+ * Public configurator contract for the context module.
+ *
+ * Consumers call {@link addConfigBuilder} to register one or more
+ * {@link ContextConfigBuilderCallback} functions that will run during
+ * module initialization to populate the {@link ContextModuleConfig}.
+ */
 export interface IContextModuleConfigurator {
+    /**
+     * Registers a configuration callback that receives a {@link ContextConfigBuilder}.
+     *
+     * Multiple builders can be added; they execute sequentially and merge
+     * their results into a single {@link ContextModuleConfig}.
+     *
+     * @param init - Builder callback invoked during module initialization.
+     */
     addConfigBuilder: (init: ContextConfigBuilderCallback) => void;
 }
+/**
+ * Default implementation of {@link IContextModuleConfigurator}.
+ *
+ * Collects {@link ContextConfigBuilderCallback} registrations and, when
+ * {@link createConfig} is called, runs them in order against a
+ * {@link ContextConfigBuilder} to produce the final {@link ContextModuleConfig}.
+ *
+ * If no custom client is configured, the configurator falls back to
+ * creating one from the {@link ServicesModule} API provider.
+ */
 export declare class ContextModuleConfigurator implements IContextModuleConfigurator {
     #private;
+    /** Default cache TTL (in ms) for context query results. */
     defaultExpireTime: number;
+    /** @inheritdoc */
     addConfigBuilder(init: ContextConfigBuilderCallback): void;
+    /**
+     * Resolves the services API provider, preferring the local module
+     * instance and falling back to the parent module.
+     *
+     * @param init - Module initializer arguments.
+     * @returns The resolved API provider.
+     * @throws Error if no services module is available.
+     */
     protected _getServiceProvider(init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule]>): Promise<IApiProvider>;
+    /**
+     * Runs all registered config builders and produces the final
+     * {@link ContextModuleConfig}.
+     *
+     * If no `resolveInitialContext` was set, the default path + parent
+     * resolver is used. If no `client` was set, one is created from the
+     * {@link ServicesModule} API provider.
+     *
+     * @param init - Module initializer arguments including dependency instances.
+     * @returns The fully resolved context module configuration.
+     */
     createConfig(init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>): Promise<ContextModuleConfig>;
 }
 export default ContextModuleConfigurator;

package/dist/types/index.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Context module for the Fusion Framework.
+ *
+ * Provides context management for Fusion-based applications and portals,
+ * including setting, querying, validating, and resolving context items.
+ *
+ * Use {@link enableContext} to register the module in a configurator,
+ * then access the {@link IContextProvider} from the module instance
+ * to interact with context state.
+ *
+ * @packageDocumentation
+ */
 export { ContextModuleConfigurator, IContextModuleConfigurator, ContextModuleConfig, } from './configurator';
 export { IContextProvider, ContextProvider } from './ContextProvider';
 export { default, ContextModule, module as contextModule, moduleKey as contextModuleKey, } from './module';

package/dist/types/module.d.ts

@@ -4,7 +4,18 @@ import type { ServicesModule } from '@equinor/fusion-framework-module-services';
 import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
 import { type IContextModuleConfigurator } from './configurator';
 import { type IContextProvider } from './ContextProvider';
+/**
+ * Literal type identifying the context module within the Fusion Framework module system.
+ *
+ * Used as the key when registering or looking up the module in a `Modules` map.
+ */
 export type ContextModuleKey = 'context';
+/**
+ * Module registration key for the context module.
+ *
+ * Pass this value—or reference it as `contextModuleKey`—when you need to
+ * identify the context module by name at runtime (e.g., `hasModule(contextModuleKey)`).
+ */
 export declare const moduleKey: ContextModuleKey;
 /**
  * Represents a module for managing context within the framework.

package/dist/types/types.d.ts

@@ -39,11 +39,33 @@ export type ContextItem<TType extends Record<string, unknown> = Record<string, u
         content: string;
     };
 };
+/**
+ * Describes the type classification of a {@link ContextItem}.
+ *
+ * Every context item carries a `type` that identifies what kind of
+ * entity it represents (e.g. `ProjectMaster`, `Facility`, `Contract`).
+ * The optional hierarchy fields indicate parent–child relationships
+ * between context types.
+ */
 export interface ContextItemType {
+    /** Unique identifier for the context type (e.g. `'ProjectMaster'`). */
     id: string;
+    /** Whether this type is a child of another context type. */
     isChildType?: boolean;
+    /** IDs of parent context types, when `isChildType` is `true`. */
     parentTypeIds?: string[];
 }
+/**
+ * Parameters for querying context items from the context API.
+ *
+ * Used by {@link ContextProvider.queryContext} and the underlying
+ * query client to search and filter context results.
+ *
+ * @property search - Free-text search term.
+ * @property filter - Optional structured filters.
+ * @property filter.type - Restrict results to specific context type IDs.
+ * @property filter.externalId - Filter by an external system identifier.
+ */
 export type QueryContextParameters = {
     search?: string;
     filter?: {

package/dist/types/utils/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Utility functions for context module configuration and initialization.
+ *
+ * - {@link enableContext} — register the context module on a configurator.
+ * - {@link resolveInitialContext} — default initial-context resolver (path → parent fallback).
+ * - {@link extractContextIdFromPath} — extract a GUID context ID from a URL path.
+ * - {@link resolveContextFromPath} — resolve a context item from a URL path.
+ *
+ * @packageDocumentation
+ */
 export { enableContext } from './enable-context';
 export { resolveInitialContext } from './resolve-initial-context';
 export { extractContextIdFromPath, resolveContextFromPath } from './resolve-context-from-path';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "7.0.3";
+export declare const version = "8.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-module-context",
-  "version": "7.0.3",
+  "version": "8.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "exports": {
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@equinor/fusion-query": "^6.0.4"
+    "@equinor/fusion-query": "^7.0.0"
   },
   "devDependencies": {
     "rxjs": "^7.8.1",
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-event": "^5.0.1",
-    "@equinor/fusion-framework-module": "^5.0.6",
-    "@equinor/fusion-framework-module-navigation": "^6.0.1",
-    "@equinor/fusion-framework-module-services": "^7.2.1"
+    "typescript": "^5.9.3",
+    "@equinor/fusion-framework-module-event": "^6.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0",
+    "@equinor/fusion-framework-module-services": "^8.0.0",
+    "@equinor/fusion-framework-module-navigation": "^7.0.0"
   },
   "peerDependencies": {
-    "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module": "^5.0.6"
+    "rxjs": "^7.0.0",
+    "@equinor/fusion-framework-module": "^6.0.0"
   },
   "scripts": {
     "build": "tsc -b"

package/src/ContextConfigBuilder.ts

@@ -17,6 +17,14 @@ import type {
 
 import type { ContextItem, QueryContextParameters, RelatedContextParameters } from './types';
 
+/**
+ * Callback passed to {@link IContextModuleConfigurator.addConfigBuilder}.
+ *
+ * Receives a {@link ContextConfigBuilder} and may use its setter methods
+ * to populate the context module configuration. The callback may be async.
+ *
+ * @typeParam TDeps - Module dependency array inferred from the configurator.
+ */
 export type ContextConfigBuilderCallback = <TDeps extends Array<AnyModule> = []>(
   builder: ContextConfigBuilder<TDeps, ModuleInitializerArgs<IContextModuleConfigurator, TDeps>>,
 ) => void | Promise<void>;
@@ -147,6 +155,13 @@ export class ContextConfigBuilder<
     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: ContextModuleConfig['resolveInitialContext']) {
     this.config.resolveInitialContext = fn;
   }

package/src/ContextProvider.ts

@@ -989,7 +989,12 @@ export default ContextProvider;
 
 declare module '@equinor/fusion-framework-module-event' {
   interface FrameworkEventMap {
-    // event which is dispatched before the context changes
+    /**
+     * Dispatched **before** the current context is changed.
+     *
+     * The event is cancelable — calling `event.preventDefault()` in a
+     * listener will abort the context change.
+     */
     onCurrentContextChange: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -998,7 +1003,12 @@ declare module '@equinor/fusion-framework-module-event' {
         IContextProvider
       >
     >;
-    // event which is dispatched after the context changes
+    /**
+     * Dispatched **after** the current context has changed.
+     *
+     * Contains both the previous and next context items, enabling
+     * listeners to react to transitions.
+     */
     onCurrentContextChanged: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1009,7 +1019,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched before the parent context changes
+    /**
+     * Dispatched **before** a parent context change is applied locally.
+     *
+     * Cancelable — prevents the parent context from being mirrored into
+     * this provider.
+     */
     onParentContextChanged: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1019,7 +1034,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched before the context will be resolved
+    /**
+     * Dispatched **before** context resolution begins (when validation
+     * fails and the caller requested resolution).
+     *
+     * Cancelable — aborting prevents the resolution attempt.
+     */
     onSetContextResolve: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1029,7 +1049,12 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched after the context was resolved
+    /**
+     * Dispatched **after** the context has been resolved to a new item.
+     *
+     * Cancelable — aborting prevents the resolved item from being
+     * set as the current context.
+     */
     onSetContextResolved: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1040,7 +1065,10 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched if the context validation failed
+    /**
+     * Dispatched when context validation fails and resolution is not
+     * enabled.
+     */
     onSetContextValidationFailed: FrameworkEvent<
       FrameworkEventInit<
         {
@@ -1050,7 +1078,9 @@ declare module '@equinor/fusion-framework-module-event' {
       >
     >;
 
-    // event which is dispatched if the context resolve failed
+    /**
+     * Dispatched when context resolution fails with an error.
+     */
     onSetContextResolveFailed: FrameworkEvent<
       FrameworkEventInit<
         {