@equinor/fusion-framework-module-app 7.4.1 → 8.0.0

package/src/app/create-reducer.ts

@@ -13,6 +13,15 @@ import { type Actions, actions } from './actions';
 
 import type { AppBundleState, AppBundleStateInitial } from './types';
 
+/**
+ * Creates the Immer-powered reducer for the {@link App} state machine.
+ *
+ * Handles synchronous state updates (set manifest, config, settings, module, instance)
+ * and tracks in-progress async operations via a `status` set.
+ *
+ * @param value - Initial state values (appKey, tag, and any pre-loaded data).
+ * @returns A reducer function compatible with {@link FlowSubject}.
+ */
 export const createReducer = (value: AppBundleStateInitial) =>
   makeReducer<AppBundleState, Actions>(
     { ...value, status: new Set() } as AppBundleState,

package/src/app/create-state.ts

@@ -14,6 +14,17 @@ import type { Actions } from './actions';
 import type { AppBundleState, AppBundleStateInitial } from './types';
 import type { AppModuleProvider } from '../AppModuleProvider';
 
+/**
+ * Creates and configures the reactive state machine ({@link FlowSubject}) for
+ * an {@link App} instance.
+ *
+ * Registers flows for fetching manifests, configs, settings, and importing
+ * the application script module.
+ *
+ * @param value - Initial state values (appKey, tag, and any pre-loaded data).
+ * @param provider - The {@link AppModuleProvider} used by flows to fetch data.
+ * @returns A configured `FlowSubject` ready for use by the App class.
+ */
 export const createState = (
   value: AppBundleStateInitial,
   provider: AppModuleProvider,

package/src/app/events.ts

@@ -10,7 +10,14 @@ import type {
   AppSettings,
 } from '../types';
 
-/** base event type for applications */
+/**
+ * Base event initialization type for application lifecycle events.
+ *
+ * Extends {@link FrameworkEventInit} with a mandatory `appKey` field and
+ * the {@link App} as the event source.
+ *
+ * @template TDetail - Additional detail properties carried by the event.
+ */
 export type AppEventEventInit<TDetail extends Record<string, unknown> | unknown = unknown> =
   FrameworkEventInit<
     /** additional event details and key of target event */
@@ -19,10 +26,19 @@ export type AppEventEventInit<TDetail extends Record<string, unknown> | unknown
     App
   >;
 
+/**
+ * Framework event carrying application-scoped detail and an {@link App} source.
+ *
+ * @template TDetail - Additional detail properties carried by the event.
+ */
 export type AppEvent<TDetail extends Record<string, unknown> | unknown = unknown> = FrameworkEvent<
   AppEventEventInit<TDetail>
 >;
 
+/**
+ * Framework event emitted when an application lifecycle operation fails.
+ * The `error` detail carries the underlying failure.
+ */
 export type AppEventFailure = FrameworkEvent<
   AppEventEventInit<{
     error: AppConfig;

package/src/app/flows.ts

@@ -173,9 +173,13 @@ export const handleImportApplication =
       filter(actions.importApp.match),
       // when request is received, abort any ongoing request and start new
       switchMap(({ payload }) => {
-        const endpoint = [provider.assetUri, payload].join('/').replace(/\/{2,}/g, '/');
         // dynamically import the application script
-        return from(import(/* @vite-ignore */ /* webpackIgnore: true */ endpoint)).pipe(
+        return from(
+          import(
+            /* @vite-ignore */ /* webpackIgnore: true */
+            [provider.assetUri, payload].join('/').replace(/\/{2,}/g, '/')
+          ),
+        ).pipe(
           // dispatch success action
           map(actions.importApp.success),
           // catch any error and dispatch failure action

package/src/app/index.ts

@@ -1,3 +1,10 @@
+/**
+ * Re-exports for the app sub-module.
+ *
+ * - {@link App} – Concrete application class managing reactive state.
+ * - {@link IApp} – Public interface for an application instance.
+ * - {@link AppInitializeResult} – Shape emitted by `App.initialize()`.
+ */
 export { App, IApp, type AppInitializeResult } from './App';
 
 export { default } from './App';

package/src/enable-app-module.ts

@@ -3,8 +3,25 @@ import { module } from './module';
 import type { AppConfigurator } from './AppConfigurator';
 
 /**
- * Method for enabling the Service module
- * @param configurator - configuration object
+ * Registers the app module with a framework configurator.
+ *
+ * Call this during framework setup to enable application loading, manifest fetching,
+ * configuration resolution, and per-user settings management.
+ *
+ * @param configurator - The framework modules configurator to register the app module with.
+ * @param callback - Optional callback to customize the {@link AppConfigurator} before initialization
+ *   (e.g., override the HTTP client or set a custom asset URI).
+ *
+ * @example
+ * ```ts
+ * import { enableAppModule } from '@equinor/fusion-framework-module-app';
+ *
+ * export const configure = async (configurator: FrameworkConfigurator) => {
+ *   enableAppModule(configurator, (builder) => {
+ *     builder.setAssetUri('/custom-proxy');
+ *   });
+ * };
+ * ```
  */
 export const enableAppModule = (
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/errors.ts

@@ -1,3 +1,11 @@
+/**
+ * Discriminant for application-related errors.
+ *
+ * - `'not_found'` – The requested resource does not exist (HTTP 404).
+ * - `'unauthorized'` – The request lacks valid credentials (HTTP 401).
+ * - `'deleted'` – The resource has been removed (HTTP 410).
+ * - `'unknown'` – An unexpected failure occurred.
+ */
 type AppErrorType = 'not_found' | 'unauthorized' | 'unknown' | 'deleted';
 
 /**

package/src/index.ts

@@ -1,3 +1,22 @@
+/**
+ * @packageDocumentation
+ *
+ * Framework module for loading, configuring, and managing Fusion applications at runtime.
+ *
+ * Use {@link enableAppModule} to register the module with a framework configurator.
+ * Once initialized, {@link AppModuleProvider} exposes methods for fetching app manifests,
+ * configurations, user settings, and for setting the current active application.
+ *
+ * @example
+ * ```ts
+ * import { enableAppModule } from '@equinor/fusion-framework-module-app';
+ *
+ * export const configure = async (configurator: FrameworkConfigurator) => {
+ *   enableAppModule(configurator);
+ * };
+ * ```
+ */
+
 export {
   AppModuleConfig,
   AppConfigurator,

package/src/module.ts

@@ -4,8 +4,14 @@ import type { ModuleDeps } from './types';
 import { AppConfigurator } from './AppConfigurator';
 import { AppModuleProvider } from './AppModuleProvider';
 
+/** Module key used to register and look up the app module in the framework. */
 export const moduleKey = 'app';
 
+/**
+ * Type alias for the app module definition, binding the module key,
+ * provider type ({@link AppModuleProvider}), configurator type
+ * ({@link AppConfigurator}), and required module dependencies.
+ */
 export type AppModule = Module<typeof moduleKey, AppModuleProvider, AppConfigurator, ModuleDeps>;
 
 /**

package/src/types.ts

@@ -6,13 +6,22 @@ import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-se
 import type { AppConfig } from './AppConfig';
 import type IApp from './app';
 
+/**
+ * Re-export of {@link ConfigEnvironment} from AppConfig.
+ */
 export type ConfigEnvironment = Record<string, unknown>;
 export type { AppConfig } from './AppConfig';
 
-// TODO
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// biome-ignore lint/suspicious/noExplicitAny: TODO - needs proper type definition
 type Fusion = any;
 
+/**
+ * Environment bindings passed to an application at render time,
+ * including its manifest, configuration, base path, and custom props.
+ *
+ * @template TEnv - Shape of the environment configuration record.
+ * @template TProps - Shape of custom properties passed to the app.
+ */
 export type AppEnv<TEnv extends ConfigEnvironment = ConfigEnvironment, TProps = unknown> = {
   basename?: string;
   manifest?: AppManifest;
@@ -21,21 +30,38 @@ export type AppEnv<TEnv extends ConfigEnvironment = ConfigEnvironment, TProps =
 };
 
 /**
- * Reference to an app, used to fetch app manifest from app service
+ * Reference to an application, used to fetch the app manifest from the app service.
+ * The `tag` defaults to `'latest'` when omitted.
  */
 export type AppReference = {
   appKey: string;
   tag?: string; // defaults to 'latest'
 };
 
-// TODO: change to module-services when new app service is created
+/**
+ * Required module dependencies for the app module.
+ *
+ * The app module depends on HTTP (for API calls), service discovery
+ * (for resolving the apps service URL), and events (for lifecycle notifications).
+ */
 export type ModuleDeps = [HttpModule, ServiceDiscoveryModule, EventModule];
 
+/**
+ * Per-user application settings, stored as an arbitrary key-value record.
+ * Read via `getAppSettings` and written via `updateAppSettings` on the provider.
+ */
 export interface AppSettings {
   [key: string]: unknown;
 }
 
-// TODO: remove `report` and `launcher` when legacy apps are removed
+/**
+ * Discriminant union of supported application types.
+ *
+ * - `'standalone'` – A full standalone application.
+ * - `'template'` / `'template-app'` – Template-based apps.
+ * - `'landing-page'` – Portal landing pages.
+ * - `'report'` / `'launcher'` – Legacy types (will be removed).
+ */
 export type AppType =
   | 'standalone'
   | 'report'
@@ -44,6 +70,13 @@ export type AppType =
   | 'template-app'
   | 'landing-page';
 
+/**
+ * The currently active application, or `null` when cleared, or `undefined`
+ * when no application has been set yet.
+ *
+ * @template TModules - Additional framework modules the app depends on.
+ * @template TEnv - Shape of the environment configuration record.
+ */
 export type CurrentApp<
   TModules extends Array<AnyModule> = [],
   TEnv extends ConfigEnvironment = ConfigEnvironment,
@@ -51,6 +84,9 @@ export type CurrentApp<
 
 type Nullable<T> = T | null | undefined;
 
+/**
+ * Represents a person associated with an application (admin or owner).
+ */
 type AppPerson = {
   id: string;
   azureUniqueId: string;
@@ -62,10 +98,29 @@ type AppPerson = {
   isExpired?: Nullable<boolean>;
 };
 
+/** An application administrator. */
 export type AppAdmin = AppPerson;
 
+/** An application owner. */
 export type AppOwner = AppPerson;
 
+/**
+ * Schema entry format for route documentation in app manifests.
+ * Each entry represents a route with its path, description, and optional parameter/search schemas.
+ */
+export type RouteSchemaEntry = [
+  path: string,
+  description: string,
+  options?: {
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  },
+];
+
+/**
+ * Build metadata returned by the app service for a specific application version.
+ * Contains the script entry point, asset path, tags, and optional CI metadata.
+ */
 export type AppBuildManifest = {
   version: string;
   entryPoint: string;
@@ -82,6 +137,10 @@ export type AppBuildManifest = {
   uploadedBy?: Nullable<AppOwner>;
 };
 
+/**
+ * Full manifest describing a registered Fusion application, including
+ * display metadata, category, admins/owners, build info, and optional route schemas.
+ */
 export interface AppManifest {
   /** @deprecated will be removed, use appKey */
   key?: string;
@@ -110,11 +169,15 @@ export interface AppManifest {
   admins?: Nullable<AppAdmin[]>;
   owners?: Nullable<AppOwner[]>;
   build?: Nullable<AppBuildManifest>;
+  /** Route schema entries for documentation and API schema generation */
+  routes?: Nullable<RouteSchemaEntry[]>;
 }
 
 /**
- * @template TEnvironment - name of hosted environment
- * @template TModule - ES module type (import return type)
+ * A loaded application bundle containing its manifest, config, and imported script module.
+ *
+ * @template TEnvironment - Shape of the environment config record.
+ * @template TModule - Type of the dynamically imported ES module.
  */
 export type AppBundle<
   TEnvironment extends ConfigEnvironment = ConfigEnvironment,
@@ -125,20 +188,44 @@ export type AppBundle<
   module: TModule;
 };
 
+/**
+ * Combined module type merging the app's own modules with base framework modules
+ * (Event, HTTP, MSAL).
+ *
+ * @template TModules - Additional modules contributed by the application.
+ */
 export type AppModules<TModules extends Array<AnyModule> | unknown = unknown> = CombinedModules<
   TModules,
   [EventModule, HttpModule, MsalModule]
 >;
 
+/**
+ * Arguments passed to an application's `renderApp` or default export function
+ * when mounting the application into a DOM element.
+ *
+ * @template TFusion - Type of the Fusion framework instance.
+ * @template TEnv - Type of the environment bindings.
+ */
 export type ComponentRenderArgs<TFusion extends Fusion = Fusion, TEnv = AppEnv> = {
   fusion: TFusion;
   env: TEnv;
 };
 
+/**
+ * Shape of the ES module exported by an application's script bundle.
+ *
+ * Must expose either a `default` export or a `renderApp` function (or both)
+ * that mounts the application into a host DOM element.
+ */
 export type AppScriptModule = {
   default: (el: HTMLElement, args: ComponentRenderArgs) => VoidFunction;
   renderApp: (el: HTMLElement, args: ComponentRenderArgs) => VoidFunction;
 };
 
+/**
+ * Instantiated module collection for a running application.
+ *
+ * @template TModules - Additional modules contributed by the application.
+ */
 export type AppModulesInstance<TModules extends Array<AnyModule> | unknown = unknown> =
   ModulesInstance<AppModules<TModules>>;

package/src/version.ts

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