@equinor/fusion-framework-app 10.4.9 → 11.0.0

package/dist/types/AppConfigurator.d.ts

@@ -3,41 +3,92 @@ import { type AnyModule, type IModulesConfigurator, ModulesConfigurator } from '
 import { configureHttpClient, configureHttp, type HttpClientOptions } from '@equinor/fusion-framework-module-http';
 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.
      */
     useFrameworkServiceClient(serviceName: string, options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>): 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 declare class AppConfigurator<TModules extends Array<AnyModule> | unknown = unknown, TRef extends FusionModulesInstance = FusionModulesInstance, TEnv extends AppEnv = AppEnv> extends ModulesConfigurator<AppModules<TModules>, TRef> implements IAppConfigurator<TModules, TRef> {
     readonly env: TEnv;
     /**
@@ -45,26 +96,49 @@ export declare class AppConfigurator<TModules extends Array<AnyModule> | unknown
      * the name is preserved through compilation and minification.
      */
     static readonly className: string;
+    /**
+     * 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(env: TEnv);
     /**
-     * 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(): void;
+    /** {@inheritDoc IAppConfigurator.configureHttp} */
     configureHttp(...args: Parameters<typeof configureHttp>): void;
+    /** {@inheritDoc IAppConfigurator.configureHttpClient} */
     configureHttpClient(...args: Parameters<typeof configureHttpClient>): void;
     /**
-     * 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');
+     * ```
      */
     useFrameworkServiceClient(serviceName: string, options?: Omit<HttpClientOptions<any>, 'baseUri' | 'defaultScopes'>): void;
 }

package/dist/types/configure-modules.d.ts

@@ -2,23 +2,37 @@ import type { Fusion } from '@equinor/fusion-framework';
 import type { AnyModule } from '@equinor/fusion-framework-module';
 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 declare const configureModules: <TModules extends Array<AnyModule> | never, TRef extends Fusion = Fusion, TEnv extends AppEnv = AppEnv>(cb?: AppModuleInitiator<TModules, TRef, TEnv>) => ((args: {
     fusion: TRef;

package/dist/types/enable-bookmark.d.ts

@@ -1,12 +1,32 @@
 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);
+ * });
+ * ```
  */
 export declare const enableBookmark: (config: IAppConfigurator) => void;

package/dist/types/index.d.ts

@@ -1,4 +1,24 @@
+/**
+ * @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';
+/**
+ * @deprecated Use {@link configureModules} instead. This alias will be removed in a future major version.
+ */
 export { configureModules as initAppModules } from './configure-modules';

package/dist/types/types.d.ts

@@ -3,58 +3,110 @@ import type { AnyModule } from '@equinor/fusion-framework-module';
 import type { AppConfig, AppManifest, AppModulesInstance, ComponentRenderArgs } from '@equinor/fusion-framework-module-app';
 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, AppConfig, AppModulesInstance, } 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, TRef extends Fusion = Fusion, TEnv = AppEnv> = (configurator: IAppConfigurator<TModules, TRef['modules']>, args: {
     fusion: TRef;
     env: TEnv;
 }) => 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 = [], TRef extends Fusion = Fusion, TEnv = AppEnv> = (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, args: ComponentRenderArgs<TFusion, TEnv>) => VoidFunction | void;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "10.4.9";
+export declare const version = "11.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-app",
-  "version": "10.4.9",
+  "version": "11.0.0",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -46,20 +46,20 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework": "7.4.13",
-    "@equinor/fusion-framework-module-app": "7.4.1",
-    "@equinor/fusion-framework-module-event": "5.0.1",
-    "@equinor/fusion-framework-module": "5.0.6",
-    "@equinor/fusion-framework-module-http": "7.0.8",
-    "@equinor/fusion-framework-module-msal": "7.3.1",
-    "@equinor/fusion-framework-module-telemetry": "4.6.4"
+    "@equinor/fusion-framework": "8.0.0",
+    "@equinor/fusion-framework-module-app": "8.0.0",
+    "@equinor/fusion-framework-module-event": "6.0.0",
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-module-http": "8.0.0",
+    "@equinor/fusion-framework-module-msal": "8.0.0",
+    "@equinor/fusion-framework-module-telemetry": "5.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-bookmark": "^3.0.6"
+    "typescript": "^5.9.3",
+    "@equinor/fusion-framework-module-bookmark": "^4.0.0"
   },
   "peerDependencies": {
-    "@equinor/fusion-framework-module-bookmark": "^3.0.6"
+    "@equinor/fusion-framework-module-bookmark": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-module-bookmark": {