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

package/src/configurator.ts

@@ -21,46 +21,133 @@ import { ContextConfigBuilder, type ContextConfigBuilderCallback } from './Conte
 import type { IContextProvider } from './ContextProvider';
 import resolveInitialContext from './utils/resolve-initial-context';
 
+/**
+ * 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: {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ref?: AnyModuleInstance | any;
@@ -68,19 +155,54 @@ export interface ContextModuleConfig {
   }) => 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 class ContextModuleConfigurator implements IContextModuleConfigurator {
+  /** Default cache TTL (in ms) for context query results. */
   defaultExpireTime = 1 * 60 * 1000;
 
   #configBuilders: Array<ContextConfigBuilderCallback> = [];
 
+  /** @inheritdoc */
   addConfigBuilder(init: ContextConfigBuilderCallback): void {
     this.#configBuilders.push(init);
   }
 
+  /**
+   * 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 async _getServiceProvider(
     init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule]>,
   ): Promise<IApiProvider> {
@@ -94,6 +216,17 @@ export class ContextModuleConfigurator implements IContextModuleConfigurator {
     return parentServiceModule;
   }
 
+  /**
+   * 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.
+   */
   public async createConfig(
     init: ModuleInitializerArgs<IContextModuleConfigurator, [ServicesModule, NavigationModule]>,
   ): Promise<ContextModuleConfig> {

package/src/index.ts

@@ -1,3 +1,16 @@
+/**
+ * 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,

package/src/module.ts

@@ -10,8 +10,19 @@ import { type IContextModuleConfigurator, ContextModuleConfigurator } from './co
 import { type IContextProvider, ContextProvider } from './ContextProvider';
 import type { ContextItem } from './types';
 
+/**
+ * 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 const moduleKey: ContextModuleKey = 'context';
 
 /**

package/src/types.ts

@@ -44,12 +44,34 @@ export type ContextItem<TType extends Record<string, unknown> = Record<string, u
       };
 };
 
+/**
+ * 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/src/utils/index.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/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '7.0.3';
+export const version = '8.0.0';