@equinor/fusion-framework-module-widget 16.0.6 → 16.0.8

package/src/WidgetModuleProvider.ts

@@ -1,233 +0,0 @@
-import { catchError, type Observable, Subscription } from 'rxjs';
-
-import type { ModuleType } from '@equinor/fusion-framework-module';
-import { HttpResponseError } from '@equinor/fusion-framework-module-http';
-import type { EventModule } from '@equinor/fusion-framework-module-event';
-
-import { Query } from '@equinor/fusion-query';
-
-import type { GetWidgetParameters, WidgetConfig, WidgetManifest } from './types';
-
-import type { WidgetModuleConfig } from './WidgetModuleConfigurator';
-import { WidgetManifestLoadError, WidgetConfigLoadError } from './WidgetManifestLoadError';
-import { Widget } from './Widget';
-
-/**
- * Public interface for the widget module provider.
- *
- * Consumers depend on this interface rather than the concrete
- * {@link WidgetModuleProvider} class, enabling testability and
- * alternative implementations.
- */
-export interface IWidgetModuleProvider {
-  /**
-   * Creates a {@link Widget} instance for the given widget key.
-   *
-   * @param widgetKey - Unique identifier (name) of the widget.
-   * @param args - Optional version or tag selector.
-   * @returns A new `Widget` ready for initialization.
-   */
-  getWidget(
-    widgetKey: GetWidgetParameters['widgetKey'],
-    args?: GetWidgetParameters['args'],
-  ): Widget;
-
-  /**
-   * Fetches the manifest for a widget as an observable stream.
-   *
-   * @param widgetKey - Unique identifier (name) of the widget.
-   * @param args - Optional version or tag selector.
-   * @returns Observable that emits the {@link WidgetManifest}.
-   */
-  getWidgetManifest(
-    widgetKey: GetWidgetParameters['widgetKey'],
-    args?: GetWidgetParameters['args'],
-  ): Observable<WidgetManifest>;
-
-  /**
-   * Fetches the configuration for a widget as an observable stream.
-   *
-   * @param widgetKey - Unique identifier (name) of the widget.
-   * @param args - Optional version or tag selector.
-   * @returns Observable that emits the {@link WidgetConfig}.
-   */
-  getWidgetConfig(
-    widgetKey: GetWidgetParameters['widgetKey'],
-    args?: GetWidgetParameters['args'],
-  ): Observable<WidgetConfig>;
-}
-
-/**
- * Concrete provider that manages widget instances and performs API queries
- * for widget manifests and configurations.
- *
- * Created automatically during module initialization; see {@link module} and
- * {@link enableWidgetModule}.
- *
- * @example
- * ```typescript
- * const widget = provider.getWidget('my-widget');
- * widget.initialize().subscribe(result => { ... });
- * ```
- */
-export class WidgetModuleProvider implements IWidgetModuleProvider {
-  // Private fields
-  #subscription = new Subscription();
-  #config: WidgetModuleConfig;
-  #event?: ModuleType<EventModule>;
-
-  /**
-   * Creates a new `WidgetModuleProvider`.
-   *
-   * @param args - Provider dependencies.
-   * @param args.config - Resolved {@link WidgetModuleConfig} with HTTP client.
-   * @param args.event - Optional event module for dispatching lifecycle events.
-   */
-  constructor(args: { config: WidgetModuleConfig; event?: ModuleType<EventModule> }) {
-    const { config, event } = args;
-    this.#event = event;
-    this.#config = config;
-  }
-
-  /**
-   * Creates a new {@link Widget} instance for the given name.
-   *
-   * The returned widget has not been initialized yet — call
-   * {@link Widget.initialize} to start the lifecycle.
-   *
-   * @param name - Unique widget name (used as lookup key).
-   * @param widgetPrams - Optional version or tag selector.
-   * @returns A new `Widget` instance.
-   */
-  public getWidget(name: string, widgetPrams?: GetWidgetParameters['args']): Widget {
-    return new Widget(
-      { name },
-      { provider: this, event: this.#event, widgetPrams, config: this.#config },
-    );
-  }
-
-  /**
-   * Fetches the manifest for a widget via the configured HTTP client.
-   *
-   * @param name - Unique widget name.
-   * @param widgetPrams - Optional version or tag selector.
-   * @returns Observable that emits the {@link WidgetManifest} and completes.
-   * @throws {WidgetManifestLoadError} When the manifest request fails.
-   */
-  public getWidgetManifest(
-    name: string,
-    widgetPrams?: GetWidgetParameters['args'],
-  ): Observable<WidgetManifest> {
-    return this._getWidget(name, widgetPrams);
-  }
-
-  /**
-   * Fetches the configuration for a widget via the configured HTTP client.
-   *
-   * @param name - Unique widget name.
-   * @param widgetPrams - Optional version or tag selector.
-   * @returns Observable that emits the {@link WidgetConfig} and completes.
-   * @throws {WidgetConfigLoadError} When the config request fails.
-   */
-  public getWidgetConfig(
-    name: string,
-    widgetPrams?: GetWidgetParameters['args'],
-  ): Observable<WidgetConfig> {
-    return this._getWidgetConfig(name, widgetPrams);
-  }
-
-  /**
-   * Internal: queries widget config from the API and maps HTTP errors to
-   * typed {@link WidgetConfigLoadError} instances.
-   *
-   * @param widgetKey - Widget identifier.
-   * @param args - Optional version or tag selector.
-   * @returns Observable emitting the {@link WidgetConfig}.
-   * @throws {WidgetManifestLoadError} When the underlying query fails.
-   */
-  protected _getWidgetConfig(
-    widgetKey: GetWidgetParameters['widgetKey'],
-    args?: GetWidgetParameters['args'],
-  ): Observable<WidgetConfig> {
-    const client = new Query(this.#config.client.getWidgetConfig);
-    this.#subscription.add(() => client.complete());
-    // Execute the query and handle errors
-    return Query.extractQueryValue(
-      // Map any query failure to a typed `WidgetManifestLoadError`
-      client.query({ widgetKey, args }).pipe(
-        catchError((err) => {
-          // Extract the cause since the error will be a `QueryError`
-          const { cause } = err;
-
-          // Handle specific errors and throw a `GetWidgetManifestError` if applicable
-          if (cause instanceof WidgetManifestLoadError) {
-            throw cause;
-          }
-          // Map HTTP failures to a `WidgetManifestLoadError` carrying the response
-          if (cause instanceof HttpResponseError) {
-            throw WidgetManifestLoadError.fromHttpResponse(cause.response, {
-              cause,
-            });
-          }
-          // Throw a generic `GetWidgetManifestError` for unknown errors
-          throw new WidgetManifestLoadError('unknown', 'failed to load config', {
-            cause,
-          });
-        }),
-      ),
-    );
-  }
-
-  /**
-   * Internal: queries widget manifest from the API and maps HTTP errors to
-   * typed {@link WidgetManifestLoadError} instances.
-   *
-   * @param widgetKey - Widget identifier.
-   * @param args - Optional version or tag selector.
-   * @returns Observable emitting the {@link WidgetManifest}.
-   * @throws {WidgetConfigLoadError} When the underlying query fails.
-   */
-  protected _getWidget(
-    widgetKey: GetWidgetParameters['widgetKey'],
-    args?: GetWidgetParameters['args'],
-  ): Observable<WidgetManifest> {
-    // Create a new query using the configured client
-    const client = new Query(this.#config.client.getWidgetManifest);
-    this.#subscription.add(() => client.complete());
-
-    // Execute the query and handle errors
-    return Query.extractQueryValue(
-      // Map any query failure to a typed `WidgetConfigLoadError`
-      client.query({ widgetKey, args }).pipe(
-        catchError((err) => {
-          // Extract the cause since the error will be a `QueryError`
-          const { cause } = err;
-
-          // Handle specific errors and throw a `GetWidgetConfigError` if applicable
-          if (cause instanceof WidgetConfigLoadError) {
-            throw cause;
-          }
-          // Map HTTP failures to a `WidgetConfigLoadError` carrying the response
-          if (cause instanceof HttpResponseError) {
-            throw WidgetConfigLoadError.fromHttpResponse(cause.response, { cause });
-          }
-          // Throw a generic `GetWidgetManifestError` for unknown errors
-          throw new WidgetConfigLoadError('unknown', 'failed to load config', {
-            cause,
-          });
-        }),
-      ),
-    );
-  }
-
-  /**
-   * Disposes all internal query subscriptions.
-   *
-   * After disposal the provider should not be reused.
-   */
-  public dispose() {
-    this.#subscription.unsubscribe();
-  }
-}
-
-export default WidgetModuleProvider;

package/src/enable-widget-module.ts

@@ -1,35 +0,0 @@
-import type { IModulesConfigurator } from '@equinor/fusion-framework-module';
-
-import { module } from './module';
-import type { WidgetModuleConfigBuilderCallback } from './WidgetModuleConfigurator';
-
-/**
- * Registers the widget module on a Fusion Framework configurator.
- *
- * Call this during framework setup to enable widget loading, manifest
- * resolution, and script import capabilities.
- *
- * @param configurator - The framework modules configurator to register the
- *   widget module on.
- * @param builder - Optional callback to customize the
- *   {@link WidgetModuleConfigurator} (e.g., set a custom HTTP client).
- *
- * @example
- * ```typescript
- * import { enableWidgetModule } from '@equinor/fusion-framework-module-widget';
- *
- * enableWidgetModule(configurator);
- * ```
- */
-export const enableWidgetModule = (
-  // biome-ignore lint/suspicious/noExplicitAny: `IModulesConfigurator<any, any>` widens to accept a configurator for any concrete module set — `unknown` would break assignability of a real configurator instance to this parameter
-  configurator: IModulesConfigurator<any, any>,
-  builder?: WidgetModuleConfigBuilderCallback,
-): void => {
-  configurator.addConfig({
-    module,
-    configure: (widgetConfigurator) => {
-      builder?.(widgetConfigurator);
-    },
-  });
-};

package/src/errors/WidgetConfigLoadError.ts

@@ -1,51 +0,0 @@
-import type { WidgetErrorType } from '../WidgetManifestLoadError.js';
-
-/**
- * Error thrown when a widget configuration cannot be loaded from the backend API.
- *
- * Use the static {@link fromHttpResponse} factory to create instances from
- * HTTP responses with appropriate type mapping.
- */
-export class WidgetConfigLoadError extends Error {
-  /**
-   * Creates a `WidgetConfigLoadError` from an HTTP `Response`.
-   *
-   * Maps HTTP 401 to `'unauthorized'`, 404 to `'not_found'`, and all other
-   * status codes to `'unknown'`.
-   *
-   * @param response - The failing HTTP response.
-   * @param options - Standard `ErrorOptions` (e.g., `cause`).
-   * @returns A typed `WidgetConfigLoadError`.
-   */
-  static fromHttpResponse(response: Response, options?: ErrorOptions) {
-    // Map known status codes to a specific error type, otherwise fall through to 'unknown'
-    switch (response.status) {
-      case 401:
-        return new WidgetConfigLoadError(
-          'unauthorized',
-          'failed to load widget config, request not authorized',
-          options,
-        );
-      case 404:
-        return new WidgetConfigLoadError('not_found', 'widget config not found', options);
-    }
-    return new WidgetConfigLoadError(
-      'unknown',
-      `failed to load widget config, status code ${response.status}`,
-      options,
-    );
-  }
-  /**
-   * @param type - Error category discriminator.
-   * @param message - Human-readable error description.
-   * @param options - Standard `ErrorOptions` (e.g., `cause`).
-   */
-  constructor(
-    public readonly type: WidgetErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-    this.name = 'GetWidgetLoadConfigError';
-  }
-}

package/src/errors/WidgetScriptModuleError.ts

@@ -1,20 +0,0 @@
-import type { WidgetErrorType } from '../WidgetManifestLoadError.js';
-
-/**
- * Error thrown when a widget script module cannot be dynamically imported.
- */
-export class WidgetScriptModuleError extends Error {
-  /**
-   * @param type - Error category discriminator.
-   * @param message - Human-readable error description.
-   * @param options - Standard `ErrorOptions` (e.g., `cause`).
-   */
-  constructor(
-    public readonly type: WidgetErrorType,
-    message?: string,
-    options?: ErrorOptions,
-  ) {
-    super(message, options);
-    this.name = 'WidgetScriptModuleError';
-  }
-}

package/src/events.ts

@@ -1,94 +0,0 @@
-import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framework-module-event';
-
-import type { Widget } from './Widget';
-
-import type {
-  WidgetConfig,
-  WidgetManifest,
-  WidgetModulesInstance,
-  WidgetScriptModule,
-} from './types';
-
-/**
- * Base event-init shape for all widget lifecycle events.
- *
- * Extends `FrameworkEventInit` with a mandatory `name` field identifying
- * the widget, and sets the event `source` to the originating {@link Widget}
- * instance.
- *
- * @template TDetail - Additional detail properties merged with `{ name: string }`.
- */
-export type WidgetEventInit<TDetail extends Record<string, unknown> | unknown = unknown> =
-  FrameworkEventInit<TDetail & { name: string }, Widget>;
-
-/**
- * Concrete framework-event type for widget lifecycle events.
- *
- * @template TDetail - Additional detail properties.
- */
-export type WidgetEvent<TDetail extends Record<string, unknown> | unknown = unknown> =
-  FrameworkEvent<WidgetEventInit<TDetail>>;
-
-/**
- * Framework-event type for widget lifecycle failure events.
- *
- * Carries an `error` property in the event detail for error inspection.
- */
-export type WidgetEventFailure = FrameworkEvent<
-  WidgetEventInit<{
-    error: WidgetConfig;
-  }>
->;
-
-declare module '@equinor/fusion-framework-module-event' {
-  interface FrameworkEventMap {
-    /** Fired when a widget has finished initializing its framework modules. */
-    onWidgetModulesLoaded: WidgetEvent<{
-      /** The initialized module instances. */
-      modules: WidgetModulesInstance;
-    }>;
-
-    /** Fired when a widget manifest fetch starts. */
-    onWidgetManifestLoad: WidgetEvent;
-    /** Fired when a widget manifest has been successfully loaded. */
-    onWidgetManifestLoaded: WidgetEvent<{
-      manifest: WidgetManifest;
-    }>;
-    /** Fired when a widget manifest fetch fails. */
-    onWidgetManifestFailure: WidgetEventFailure;
-
-    /** Fired when a widget config fetch starts. */
-    onWidgetConfigLoad: WidgetEvent;
-    /** Fired when a widget config has been successfully loaded. */
-    onWidgetConfigLoaded: WidgetEvent<{
-      config: WidgetConfig;
-    }>;
-    /** Fired when a widget config fetch fails. */
-    onWidgetConfigFailure: WidgetEventFailure;
-
-    /** Fired when a widget script import starts. */
-    onAWidgetScriptLoad: WidgetEvent;
-    /** Fired when a widget script has been successfully imported. */
-    onWidgetScriptLoaded: WidgetEvent<{
-      script: WidgetScriptModule;
-    }>;
-    /** Fired when a widget script import fails. */
-    onWidgetScriptFailure: WidgetEventFailure;
-
-    /** Fired before the widget begins loading manifest, config, and script. */
-    onWidgetInitialize: WidgetEvent;
-
-    /**
-     * Fired after the widget has loaded manifest, config, and script.
-     *
-     * Not emitted until all loaders have settled (last emission).
-     */
-    onWidgetInitialized: WidgetEvent;
-
-    /** Fired when the widget fails to load manifest, config, or script. */
-    onWidgetInitializeFailure: WidgetEventFailure;
-
-    /** Fired when the widget is disposed (unmounted from the DOM). */
-    onWidgetDispose: FrameworkEvent<WidgetEventInit>;
-  }
-}

package/src/index.ts

@@ -1,21 +0,0 @@
-/**
- * Fusion Framework Widget Module
- *
- * Provides runtime loading, configuration, and lifecycle management for
- * remote widget micro-frontends. Widgets are dynamically fetched, imported,
- * and mounted into a host application.
- *
- * @packageDocumentation
- */
-
-export { WidgetModuleConfigurator, type WidgetModuleConfig } from './WidgetModuleConfigurator';
-
-export { WidgetModuleProvider } from './WidgetModuleProvider';
-
-export type { IWidgetModuleProvider } from './WidgetModuleProvider';
-
-export * from './types';
-
-export { enableWidgetModule } from './enable-widget-module';
-
-export { default, type WidgetModule, module, moduleKey } from './module';

package/src/module.ts

@@ -1,61 +0,0 @@
-import type { Module } from '@equinor/fusion-framework-module';
-import type { ModuleDeps } from './types';
-
-import { WidgetModuleConfigurator } from './WidgetModuleConfigurator';
-import { type IWidgetModuleProvider, WidgetModuleProvider } from './WidgetModuleProvider';
-
-/** Module registration key used in the Fusion Framework module map. */
-export const moduleKey = 'widget';
-
-/**
- * Module type definition binding the `'widget'` key to the
- * {@link IWidgetModuleProvider} instance, {@link WidgetModuleConfigurator}
- * configuration builder, and required {@link ModuleDeps}.
- */
-export type WidgetModule = Module<
-  typeof moduleKey,
-  IWidgetModuleProvider,
-  WidgetModuleConfigurator,
-  ModuleDeps
->;
-
-/**
- * Widget module descriptor.
- *
- * Defines how the widget module is configured, initialized, and disposed
- * within the Fusion Framework module system.
- *
- * - `configure` — creates a fresh {@link WidgetModuleConfigurator}
- * - `initialize` — resolves the config, optionally acquires the event module,
- *   and returns a {@link WidgetModuleProvider}
- * - `dispose` — cleans up provider subscriptions
- */
-export const module: WidgetModule = {
-  name: moduleKey,
-  configure() {
-    const config = new WidgetModuleConfigurator();
-    return config;
-  },
-  initialize: async (args) => {
-    const config = await args.config.createConfigAsync(args);
-    const event = await args.requireInstance('event').catch(() => undefined);
-    return new WidgetModuleProvider({ config, event });
-  },
-  dispose: (args) => {
-    // `args.instance` is typed as the generic module instance, but the module descriptor
-    // guarantees it was created as a `WidgetModuleProvider` — safe to cast for disposal.
-    (args.instance as unknown as WidgetModuleProvider).dispose();
-  },
-};
-
-export default module;
-
-/**
- * Augments the global Fusion Framework `Modules` interface so that
- * `modules.widget` is typed as {@link WidgetModule}.
- */
-declare module '@equinor/fusion-framework-module' {
-  interface Modules {
-    [moduleKey]: WidgetModule;
-  }
-}

package/src/state/actions.ts

@@ -1,88 +0,0 @@
-import {
-  type ActionInstanceMap,
-  type ActionTypes,
-  createAction,
-  createAsyncAction,
-} from '@equinor/fusion-observable';
-import type {
-  GetWidgetParameters,
-  WidgetConfig,
-  WidgetManifest,
-  WidgetModulesInstance,
-  WidgetScriptModule,
-} from '../types';
-
-/**
- * Factory that creates all widget state-machine actions.
- *
- * Each action (or async action triplet) drives a specific step in the
- * widget lifecycle: manifest loading, config loading, script import,
- * and initialization.
- *
- * @returns Action creators for the widget state machine.
- */
-const createActions = () => ({
-  /** Sets the manifest in state (optionally merging with existing). */
-  setManifest: createAction('set_manifest', (manifest: WidgetManifest, update?: boolean) => ({
-    payload: manifest,
-    meta: {
-      created: Date.now(),
-      update,
-    },
-  })),
-  /** Async action triplet for fetching the widget manifest from the API. */
-  fetchManifest: createAsyncAction(
-    'fetch_manifest',
-    (payload: { key: string; args?: GetWidgetParameters['args'] }, update?: boolean) => ({
-      payload,
-      meta: { update },
-    }),
-    (manifest: WidgetManifest) => ({ payload: manifest }),
-    (error: unknown) => ({ payload: error }),
-  ),
-  /** Sets the widget config in state. */
-  setConfig: createAction('set_config', (config: WidgetConfig) => ({ payload: config })),
-  /** Async action triplet for fetching the widget config from the API. */
-  fetchConfig: createAsyncAction(
-    'fetch_config',
-    (payload: { key: string; args?: GetWidgetParameters['args'] }, update?: boolean) => ({
-      payload,
-      meta: { update },
-    }),
-    (config: WidgetConfig) => ({ payload: config }),
-    (error: unknown) => ({ payload: error }),
-  ),
-  /** Sets the dynamically imported widget script module in state. */
-  // biome-ignore lint/suspicious/noExplicitAny: module payload widens to accept any script module shape when set
-  setModule: createAction('set_module', (module: any) => ({ payload: module })),
-  /** Async action triplet for dynamically importing the widget script. */
-  importWidget: createAsyncAction(
-    'import_widget',
-    (entrypoint: string) => ({ payload: entrypoint }),
-    (module: WidgetScriptModule) => ({ payload: module }),
-    (error: unknown) => ({ payload: error }),
-  ),
-  /** Sets the resolved widget framework-module instances in state. */
-  setInstance: createAction('set_instance', (instance: WidgetModulesInstance) => ({
-    payload: instance,
-  })),
-  /** Async action triplet for the overall widget initialization lifecycle. */
-  initialize: createAsyncAction(
-    'initialize_widget',
-    () => ({ payload: null }),
-    () => ({ payload: null }),
-    (error: unknown) => ({ payload: error }),
-  ),
-});
-
-/** Singleton action creators used by the widget state machine. */
-export const actions = createActions();
-
-/** Map of action-creator names to their instance types. */
-export type ActionBuilder = ReturnType<typeof createActions>;
-
-/** Map of action types produced by the action builders. */
-export type ActionMap = ActionInstanceMap<ActionBuilder>;
-
-/** Union of all action types dispatched in the widget state machine. */
-export type Actions = ActionTypes<typeof actions>;

package/src/state/create-reducer.ts

@@ -1,57 +0,0 @@
-import {
-  getBaseType,
-  createReducer as makeReducer,
-  isCompleteAction,
-  isRequestAction,
-} from '@equinor/fusion-observable';
-
-import { enableMapSet } from 'immer';
-
-enableMapSet();
-
-import { type Actions, actions } from './actions';
-import type { WidgetStateInitial, WidgetState } from '../types';
-
-/**
- * Creates an Immer-powered reducer for the widget state machine.
- *
- * Handles direct state setters (`setManifest`, `setConfig`, `setModule`,
- * `setInstance`) and tracks in-flight async operations via the `status` set.
- *
- * @param value - Initial widget state (without `status`, which is added
- *   automatically as an empty `Set`).
- * @returns A reducer function compatible with `FlowSubject`.
- */
-export const createReducer = (value: WidgetStateInitial) =>
-  // Seed the reducer's initial state with an empty in-progress status set.
-  makeReducer<WidgetState, Actions>({ ...value, status: new Set() } as WidgetState, (builder) =>
-    builder
-      .addCase(actions.setManifest, (state, action) => {
-        // Merge with existing state when caller requested an update, otherwise replace
-        if (action.meta.update) {
-          // Shallow-merge the new payload over the existing manifest fields.
-          state.manifest = { ...state.manifest, ...action.payload };
-        } else {
-          state.manifest = action.payload;
-        }
-      })
-      .addCase(actions.setConfig, (state, action) => {
-        state.config = action.payload;
-      })
-      .addCase(actions.setModule, (state, action) => {
-        state.modules = action.payload;
-      })
-      .addCase(actions.setInstance, (state, action) => {
-        state.instance = action.payload;
-      })
-      /** mark status as loading {{type}} */
-      .addMatcher(isRequestAction, (state, action) => {
-        state.status.add(getBaseType(action.type));
-      })
-      /** clear status {{type}} */
-      .addMatcher(isCompleteAction, (state, action) => {
-        state.status.delete(getBaseType(action.type));
-      }),
-  );
-
-export default createReducer;