@equinor/fusion-framework-app 10.4.9 → 11.0.0

package/src/AppConfigurator.ts

@@ -19,43 +19,72 @@ import auth from '@equinor/fusion-framework-module-msal';
 import type { AppEnv, AppModules } from './types';
 
 /**
- * Configurator for configuring application modules
+ * Contract for configuring Fusion application modules.
  *
- * @template TModules Addition modules
- * @template TRef usually undefined, optional references
+ * `IAppConfigurator` extends the base module configurator with application-specific
+ * methods for setting up HTTP clients and integrating with Fusion service discovery.
+ * Use this interface when typing configuration callbacks that receive the configurator.
+ *
+ * @template TModules - Additional application-specific modules to register beyond the defaults.
+ * @template TRef - The resolved Fusion modules instance used as a reference during initialization.
+ *
+ * @example
+ * ```ts
+ * import type { IAppConfigurator } from '@equinor/fusion-framework-app';
+ *
+ * const configure = (configurator: IAppConfigurator) => {
+ *   configurator.configureHttpClient('myApi', {
+ *     baseUri: 'https://api.example.com',
+ *     defaultScopes: ['api://client-id/.default'],
+ *   });
+ * };
+ * ```
  */
 export interface IAppConfigurator<
   TModules extends Array<AnyModule> | unknown = unknown,
   TRef extends FusionModulesInstance = FusionModulesInstance,
 > extends IModulesConfigurator<AppModules<TModules>, TRef> {
   /**
-   * [optional]
-   * enable/configure the http module
+   * Configure the HTTP module with custom settings.
+   *
+   * Delegates to the framework `configureHttp` helper. Use this when you need
+   * low-level control over the HTTP module configuration. For most applications,
+   * prefer {@link IAppConfigurator.configureHttpClient | configureHttpClient} instead.
+   *
+   * @param args - Arguments forwarded to the framework `configureHttp` function.
    */
   configureHttp(...args: Parameters<typeof configureHttp>): void;
 
   /**
-     * [optional]
-     * Configure a named http client.
-     * @example
-     * ```ts
-     configurator.configureHttpClient(
-        'myClient',
-        {
-            baseUri: 'https://foo.bar',
-            defaultScopes: ['client-id/.default']
-        }
-    );
-     * ```
-     */
+   * Register a named HTTP client with explicit base URI and authentication scopes.
+   *
+   * Use this method when the application needs to call a specific API endpoint
+   * that is not provided through Fusion service discovery.
+   *
+   * @param args - Arguments forwarded to the framework `configureHttpClient` function.
+   *
+   * @example
+   * ```ts
+   * configurator.configureHttpClient('myClient', {
+   *   baseUri: 'https://foo.bar',
+   *   defaultScopes: ['api://client-id/.default'],
+   * });
+   * ```
+   */
   configureHttpClient(...args: Parameters<typeof configureHttpClient>): void;
 
   /**
-   * [optional]
+   * Register a named HTTP client resolved through Fusion service discovery.
    *
-   * configure a http client which is resolved by service discovery
+   * The `serviceName` is looked up in the portal’s service-discovery registry at
+   * initialization time. Base URI and default scopes are resolved automatically.
+   * Use this instead of {@link IAppConfigurator.configureHttpClient | configureHttpClient}
+   * when the service is registered with the Fusion portal.
    *
-   * @param serviceName - name of the service to use
+   * @param serviceName - Registered name of the service in Fusion service discovery.
+   * @param options - Optional HTTP client overrides (headers, interceptors, etc.).
+   *                  `baseUri` and `defaultScopes` are excluded because they are
+   *                  resolved from service discovery.
    */
   // TODO - rename
   useFrameworkServiceClient(
@@ -65,6 +94,28 @@ export interface IAppConfigurator<
   ): void;
 }
 
+/**
+ * Configurator that bootstraps default Fusion application modules and provides
+ * helper methods for HTTP client and service-discovery setup.
+ *
+ * `AppConfigurator` is created internally by {@link configureModules}. It registers
+ * the `event`, `http`, and `msal` (auth) modules by default and reads any HTTP
+ * endpoints declared in the application’s environment config.
+ *
+ * @template TModules - Additional application-specific modules beyond the defaults.
+ * @template TRef - The resolved Fusion modules instance used as an initialization reference.
+ * @template TEnv - The application environment descriptor (manifest, config, basename).
+ *
+ * @example
+ * ```ts
+ * // Typically used indirectly via configureModules:
+ * import { configureModules } from '@equinor/fusion-framework-app';
+ *
+ * const initialize = configureModules((configurator) => {
+ *   configurator.useFrameworkServiceClient('my-service');
+ * });
+ * ```
+ */
 export class AppConfigurator<
     TModules extends Array<AnyModule> | unknown = unknown,
     TRef extends FusionModulesInstance = FusionModulesInstance,
@@ -79,7 +130,14 @@ export class AppConfigurator<
    */
   static readonly className: string = 'AppConfigurator';
 
-  // @todo - use zod to validate provided env config shape?
+  /**
+   * Create an application configurator with default modules and environment.
+   *
+   * Registers the `event`, `http`, and `msal` modules and pre-configures any
+   * HTTP clients declared in `env.config.endpoints`.
+   *
+   * @param env - The application environment containing manifest, config, and optional basename.
+   */
   constructor(public readonly env: TEnv) {
     super([event, http, auth]);
 
@@ -87,7 +145,11 @@ export class AppConfigurator<
   }
 
   /**
-   * Reads app config's endpoints and configure the endpoints as httpClients
+   * Read HTTP endpoint definitions from the application config and register each
+   * one as a named HTTP client.
+   *
+   * Iterates over `env.config.endpoints` and calls
+   * {@link IAppConfigurator.configureHttpClient | configureHttpClient} for each entry.
    */
   protected _configureHttpClientsFromAppConfig() {
     const { endpoints = {} } = this.env.config ?? {};
@@ -99,27 +161,38 @@ export class AppConfigurator<
     }
   }
 
-  public configureHttp(...args: Parameters<typeof configureHttp>) {
+  /** {@inheritDoc IAppConfigurator.configureHttp} */
+  public configureHttp(...args: Parameters<typeof configureHttp>): void {
     this.addConfig(configureHttp(...args));
   }
 
-  public configureHttpClient(...args: Parameters<typeof configureHttpClient>) {
+  /** {@inheritDoc IAppConfigurator.configureHttpClient} */
+  public configureHttpClient(...args: Parameters<typeof configureHttpClient>): void {
     this.addConfig(configureHttpClient(...args));
   }
 
   /**
-   * Configures a http client for the service `serviceName`.
-   * The serviceName is looked up in ServiceDiscovery.
-   * User can override url and scopes with session values.
-   * App can override url and scopes with app config.
+   * Register a named HTTP client whose base URI and scopes are resolved via
+   * Fusion service discovery.
+   *
+   * Resolution priority (highest wins):
+   * 1. Session overrides (user-specific URL / scopes)
+   * 2. Application config (`env.config.endpoints`)
+   * 3. Service-discovery registry
+   *
+   * If a client with the same `serviceName` is already registered (e.g. from
+   * app config) and the service has **not** been overridden at session level,
+   * a warning is logged and the existing configuration is kept.
    *
-   * Priority:
-   * 1. Session overrides
-   * 2. AppConfig
-   * 3. ServiceDiscovery
+   * @param serviceName - Registered name of the service in Fusion service discovery.
+   * @param options - Optional HTTP client overrides. `baseUri` and `defaultScopes`
+   *                  are excluded because they come from service discovery.
+   * @throws {Error} When the service cannot be resolved from service discovery.
    *
-   * @see modules/service-discovery/src/client.ts
-   * @see configureHttpClientsFromAppConfig()
+   * @example
+   * ```ts
+   * configurator.useFrameworkServiceClient('my-backend-service');
+   * ```
    */
   public useFrameworkServiceClient(
     serviceName: string,

package/src/configure-modules.ts

@@ -9,23 +9,37 @@ import { AppConfigurator } from './AppConfigurator';
 import type { AppModulesInstance, AppModuleInitiator, AppEnv } from './types';
 
 /**
+ * Create an application module initializer for a Fusion application.
  *
- * Creates a callback for initializing configuration of application modules
+ * `configureModules` is the primary entry point for setting up an application’s
+ * module pipeline. It returns an async function that, when called with the Fusion
+ * instance and the application environment, will:
+ *
+ * 1. Create an {@link AppConfigurator} with the provided environment.
+ * 2. Wire up telemetry scoped to the application.
+ * 3. Invoke the optional user-supplied configuration callback.
+ * 4. Initialize all registered modules and dispatch an `onAppModulesLoaded` event.
+ *
+ * @template TModules - Additional application-specific modules to register.
+ * @template TRef - The Fusion instance type, used as a configuration reference.
+ * @template TEnv - The application environment descriptor (manifest, config, basename).
+ *
+ * @param cb - Optional configuration callback invoked before modules are initialized.
+ *             Use this to register HTTP clients, enable bookmarks, or add custom modules.
+ * @returns An async initializer function that accepts `{ fusion, env }` and resolves
+ *          with the fully initialized application module instance.
  *
  * @example
- ```ts
-    const initialize =  configureModules((configurator, args) => {
-        configurator.configure(someModule);
-    });
-    await initialize({ fusion, { manifest, config }});
- ```
- * @template TModules Addition modules
- * @template TRef usually undefined, optional references
- * @template TEnv environment object for configuring modules
+ * ```ts
+ * import { configureModules } from '@equinor/fusion-framework-app';
  *
- * @param cb configuration callback
+ * const initialize = configureModules((configurator, { fusion, env }) => {
+ *   configurator.useFrameworkServiceClient('my-service');
+ * });
  *
- * @returns initialize function, executes configurator
+ * // Later, during app bootstrap:
+ * const modules = await initialize({ fusion, env });
+ * ```
  */
 export const configureModules =
   <
@@ -36,11 +50,12 @@ export const configureModules =
     cb?: AppModuleInitiator<TModules, TRef, TEnv>,
   ): ((args: { fusion: TRef; env: TEnv }) => Promise<AppModulesInstance<TModules>>) =>
   /**
+   * Async initializer that bootstraps application modules.
    *
-   * Callback for initializing application modules
-   *
-   * @param args - Fusion and application  environments (manifest, config ...)
-   * @returns initialized app modules
+   * @param args - Object containing the Fusion instance and the application environment.
+   * @param args.fusion - The active Fusion framework instance.
+   * @param args.env - The application environment with manifest, config, and basename.
+   * @returns The fully initialized application module instance.
    */
   async (args: { fusion: TRef; env: TEnv }): Promise<AppModulesInstance<TModules>> => {
     const { fusion } = args;

package/src/enable-bookmark.ts

@@ -5,14 +5,34 @@ import type {
 import type { IAppConfigurator } from './AppConfigurator';
 
 /**
- * When enabling bookmarks for applications, we will for now only provide the portals bookmark provider.
+ * Enable the bookmark module for a Fusion application.
  *
- * This function will add the portals bookmark provider to the applications modules.
- * When adding a payload generator to the bookmark provider, we will intercept the teardown function and add it to a cleanup set.
+ * Adds bookmark support by wiring the portal’s bookmark provider into the
+ * application’s module set. Payload generators registered by the application
+ * are automatically cleaned up when the module is disposed, preventing memory
+ * leaks across application load/unload cycles.
+ *
+ * Import this function from `@equinor/fusion-framework-app/enable-bookmark` or, for
+ * React apps, from `@equinor/fusion-framework-react-app/bookmark`.
  *
  * @remarks
- * The cleanup function will be called when the module is disposed.
- * There are no guarantees that the dispose function will be called, incase of weird behavior.
+ * - The portal must expose a bookmark provider on `ref.bookmark`; if it is
+ *   missing, an error is logged and the module initializes as a no-op.
+ * - The `@equinor/fusion-framework-module-bookmark` package must be installed,
+ *   but do **not** call its `enableBookmark` directly in app code — use this
+ *   app-level enabler instead.
+ *
+ * @param config - The application configurator to register the bookmark module on.
+ *
+ * @example
+ * ```ts
+ * import { configureModules } from '@equinor/fusion-framework-app';
+ * import { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';
+ *
+ * const initialize = configureModules((configurator) => {
+ *   enableBookmark(configurator);
+ * });
+ * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const enableBookmark = (config: IAppConfigurator): void => {

package/src/index.ts

@@ -1,8 +1,28 @@
+/**
+ * @packageDocumentation
+ *
+ * `@equinor/fusion-framework-app` provides the configuration and initialization
+ * layer for Fusion applications. Use this package to set up application modules,
+ * configure HTTP clients, enable bookmarks, and integrate with telemetry and
+ * service discovery.
+ *
+ * The main entry points are:
+ *
+ * - {@link configureModules} — factory that creates an application initializer
+ * - {@link AppConfigurator} / {@link IAppConfigurator} — configurator for registering modules and HTTP clients
+ * - Type aliases such as {@link AppModuleInitiator}, {@link AppEnv}, and {@link AppRenderFn}
+ *
+ * Bookmark support is available via the `@equinor/fusion-framework-app/enable-bookmark`
+ * sub-path export.
+ */
+
 export { AppConfigurator, IAppConfigurator } from './AppConfigurator';
 
 export * from './types';
 
 export { configureModules, default } from './configure-modules';
 
-// TODO remove
+/**
+ * @deprecated Use {@link configureModules} instead. This alias will be removed in a future major version.
+ */
 export { configureModules as initAppModules } from './configure-modules';

package/src/types.ts

@@ -12,6 +12,14 @@ import type {
 import type { IAppConfigurator } from './AppConfigurator';
 import type { ConfigEnvironment } from '@equinor/fusion-framework-module-app';
 
+/**
+ * Re-exported application module types from `@equinor/fusion-framework-module-app`.
+ *
+ * - `AppModules` — union of default application modules
+ * - `AppManifest` — application manifest metadata (app key, version, etc.)
+ * - `AppConfig` — environment-specific application configuration
+ * - `AppModulesInstance` — resolved module instances after initialization
+ */
 export type {
   AppModules,
   AppManifest,
@@ -20,26 +28,48 @@ export type {
 } from '@equinor/fusion-framework-module-app';
 
 /**
- * Application environment args
- * Arguments provided when initializing/configuring application modules
+ * Environment descriptor passed to the application during module initialization.
  *
- * @template TConfig config value type
- * @template TProps [__not in use__] properties for application component
+ * Contains the application manifest, optional config (with endpoint definitions),
+ * an optional base path for routing, and optional component props.
+ *
+ * @template TConfig - Shape of the environment-specific configuration object.
+ * @template TProps - Additional properties forwarded to the application component (currently unused).
  */
 export type AppEnv<TConfig extends ConfigEnvironment = ConfigEnvironment, TProps = unknown> = {
-  /** base routing path of the application */
+  /** Base routing path of the application (e.g. `/apps/my-app`). */
   basename?: string;
+  /** Application manifest describing the app key, version, and build metadata. */
   manifest: AppManifest;
+  /** Environment-specific configuration with optional endpoint definitions. */
   config?: AppConfig<TConfig>;
+  /** Optional properties forwarded to the application component. */
   props?: TProps;
 };
 
 /**
- * Blueprint for initializing application modules
+ * Configuration callback for setting up application modules.
+ *
+ * This is the function signature accepted by {@link configureModules}. Implement
+ * this callback to register HTTP clients, enable bookmarks, and add custom modules
+ * to the application’s module pipeline.
+ *
+ * @template TModules - Additional modules registered by the application.
+ * @template TRef - The Fusion instance type used as a configuration reference.
+ * @template TEnv - The application environment descriptor.
+ *
+ * @param configurator - The application configurator with HTTP and module helpers.
+ * @param args - Object containing the Fusion instance and the application environment.
+ * @returns `void` or a `Promise<void>` for async configuration steps.
+ *
+ * @example
+ * ```ts
+ * import type { AppModuleInitiator } from '@equinor/fusion-framework-app';
  *
- * @template TModules Addition modules
- * @template TRef usually undefined, optional references
- * @template TEnv environment object for configuring modules
+ * const configure: AppModuleInitiator = (configurator, { fusion, env }) => {
+ *   configurator.useFrameworkServiceClient('portal-api');
+ * };
+ * ```
  */
 export type AppModuleInitiator<
   TModules extends Array<AnyModule> | unknown = unknown,
@@ -51,11 +81,15 @@ export type AppModuleInitiator<
 ) => void | Promise<void>;
 
 /**
- * Blueprint for creating application initialization
+ * Factory type that wraps {@link AppModuleInitiator} into a complete initializer.
+ *
+ * Accepts a configuration callback and returns an async function that, given the
+ * Fusion instance and environment, produces the initialized module instance.
+ * This is the signature of the {@link configureModules} function itself.
  *
- * @template TModules Addition modules
- * @template TRef usually undefined, optional references
- * @template TEnv environment object for configuring modules
+ * @template TModules - Additional modules registered by the application.
+ * @template TRef - The Fusion instance type used as a configuration reference.
+ * @template TEnv - The application environment descriptor.
  */
 export type AppModuleInit<
   TModules extends Array<AnyModule> | unknown = [],
@@ -65,26 +99,44 @@ export type AppModuleInit<
   cb: AppModuleInitiator<TModules, TRef, TEnv>,
 ) => (args: AppModuleInitArgs<TRef, TEnv>) => Promise<AppModulesInstance<TModules>>;
 
+/**
+ * Arguments passed to the async initializer returned by {@link configureModules}.
+ *
+ * @template TRef - The Fusion instance type.
+ * @template TEnv - The application environment descriptor.
+ */
 export type AppModuleInitArgs<TRef extends Fusion = Fusion, TEnv = AppEnv> = {
   fusion: TRef;
   env: TEnv;
 };
 
 /**
- * Type definition for AppRenderFn.
- * This type is responsible for rendering the application within a given environment.
- * It takes a generic `TFusion` type parameter extending `Fusion` for the Fusion instance,
- * and an optional `TEnv` type parameter for the application environment, defaulting to `AppEnv`.
+ * Render function signature for mounting a Fusion application into the DOM.
+ *
+ * Called by the Fusion portal or dev-server to render the application. The
+ * function receives the root element and render arguments (Fusion instance,
+ * environment, and modules) and optionally returns a cleanup function that
+ * is invoked when the application is unmounted.
  *
- * @param el - The root document element where the application will be rendered.
- * @param args - An object containing arguments required for component rendering, including the Fusion instance and environment-specific configurations.
- * @returns A function that can be invoked to perform cleanup operations, or `void` if no cleanup is necessary.
+ * @template TFusion - The Fusion instance type providing framework modules.
+ * @template TEnv - The application environment descriptor.
+ *
+ * @param el - The root HTML element where the application will be rendered.
+ * @param args - Render arguments including the Fusion instance, environment,
+ *               and resolved modules.
+ * @returns A cleanup / teardown function, or `void` if no cleanup is needed.
  *
  * @example
- * const renderMyApp: AppRenderFn = (el, args) => {
- *   // Implementation for rendering the application
- *   // Optionally return a cleanup function
+ * ```ts
+ * import type { AppRenderFn } from '@equinor/fusion-framework-app';
+ * import { createRoot } from 'react-dom/client';
+ *
+ * export const renderApp: AppRenderFn = (el, args) => {
+ *   const root = createRoot(el);
+ *   root.render(<App />);
+ *   return () => root.unmount();
  * };
+ * ```
  */
 export type AppRenderFn<TFusion extends Fusion = Fusion, TEnv = AppEnv> = (
   el: HTMLHtmlElement,

package/src/version.ts

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