@equinor/fusion-framework-react-app 9.0.8 → 10.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "9.0.8",
+  "version": "10.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -41,6 +41,10 @@
       "types": "./dist/types/http/index.d.ts",
       "import": "./dist/esm/http/index.js"
     },
+    "./http/selectors": {
+      "types": "./dist/types/http/selectors.d.ts",
+      "import": "./dist/esm/http/selectors.js"
+    },
     "./msal": {
       "types": "./dist/types/msal/index.d.ts",
       "import": "./dist/esm/msal/index.js"
@@ -113,36 +117,39 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-app": "10.4.9",
-    "@equinor/fusion-framework-module": "5.0.6",
-    "@equinor/fusion-framework-module-app": "7.4.1",
-    "@equinor/fusion-framework-module-navigation": "6.0.1",
-    "@equinor/fusion-framework-react": "7.4.20",
-    "@equinor/fusion-framework-react-module": "3.1.14",
-    "@equinor/fusion-framework-react-module-http": "10.0.1"
+    "@equinor/fusion-framework-app": "11.0.0",
+    "@equinor/fusion-framework-module-app": "8.0.0",
+    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-react": "8.0.0",
+    "@equinor/fusion-framework-module-http": "8.0.0",
+    "@equinor/fusion-framework-react-module": "4.0.0",
+    "@equinor/fusion-framework-react-module-http": "11.0.0",
+    "@equinor/fusion-framework-module-navigation": "7.0.0"
   },
   "devDependencies": {
-    "@types/react": "^18.2.50",
-    "@types/react-dom": "^18.2.7",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "happy-dom": "^20.8.4",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
     "rxjs": "^7.8.1",
-    "typescript": "^5.8.2",
-    "@equinor/fusion-framework-module-ag-grid": "35.0.2",
-    "@equinor/fusion-framework-module-event": "5.0.1",
-    "@equinor/fusion-framework-module-analytics": "1.0.2",
-    "@equinor/fusion-framework-module-feature-flag": "1.1.28",
-    "@equinor/fusion-framework-react-module-bookmark": "5.0.2",
-    "@equinor/fusion-framework-module-msal": "7.3.1",
-    "@equinor/fusion-framework-react-module-context": "6.2.34",
-    "@equinor/fusion-observable": "8.5.8"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "@equinor/fusion-framework-module-ag-grid": "36.0.0",
+    "@equinor/fusion-framework-module-event": "6.0.0",
+    "@equinor/fusion-framework-module-analytics": "2.0.0",
+    "@equinor/fusion-framework-module-feature-flag": "2.0.0",
+    "@equinor/fusion-framework-module-msal": "8.0.0",
+    "@equinor/fusion-framework-react-module-context": "7.0.0",
+    "@equinor/fusion-observable": "9.0.0",
+    "@equinor/fusion-framework-react-module-bookmark": "6.0.0"
   },
   "peerDependencies": {
-    "@types/react": "^17.0.0 || ^18.0.0",
-    "react": "^17.0.0 || ^18.0.0",
-    "react-dom": "^17.0.0 || ^18.0.0",
-    "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module-msal": "^7.3.1"
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "rxjs": "^7.0.0",
+    "@equinor/fusion-framework-module-msal": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-react-module-ag-grid": {
@@ -174,6 +181,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b",
+    "test": "vitest --run"
   }
 }

package/src/__tests__/render-app.test.tsx

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ComponentRenderArgs } from '../create-component';
+import type { Fusion } from '@equinor/fusion-framework-react';
+import type { AppEnv } from '@equinor/fusion-framework-app';
+
+// Mock dependencies before importing
+vi.mock('../create-component', () => ({
+  createComponent: vi.fn(),
+}));
+
+vi.mock('../render-component', () => ({
+  renderComponent: vi.fn(),
+}));
+
+import { renderApp } from '../render-app';
+import { createComponent } from '../create-component';
+import { renderComponent } from '../render-component';
+
+describe('renderApp', () => {
+  let mockFusion: Fusion;
+  let mockEnv: AppEnv;
+  let mockElement: HTMLElement;
+  let mockTeardown: () => void;
+  let mockComponentRenderer: ReturnType<typeof createComponent>;
+  let mockRenderFunction: ReturnType<typeof renderComponent>;
+
+  beforeEach(() => {
+    // Setup mock data
+    mockFusion = {} as Fusion;
+    mockEnv = {} as AppEnv;
+    mockElement = document.createElement('div');
+    mockTeardown = vi.fn();
+
+    // Create a mock component renderer
+    // createComponent returns a ComponentRenderer function: (fusion, env) => React.LazyExoticComponent
+    mockComponentRenderer = vi.fn() as unknown as ReturnType<typeof createComponent>;
+
+    // Create a mock render function
+    mockRenderFunction = vi.fn(() => mockTeardown) as unknown as ReturnType<typeof renderComponent>;
+
+    // Mock renderComponent to return our mock render function
+    vi.mocked(renderComponent).mockReturnValue(mockRenderFunction);
+
+    // Mock createComponent to return our mock component renderer
+    vi.mocked(createComponent).mockReturnValue(mockComponentRenderer);
+  });
+
+  it('should create a render function that calls createComponent with provided arguments', () => {
+    const TestComponent = () => <div>Test</div>;
+    const mockConfigure = vi.fn();
+
+    renderApp(TestComponent, mockConfigure);
+
+    expect(createComponent).toHaveBeenCalledWith(TestComponent, mockConfigure);
+  });
+
+  it('should create a render function that uses renderComponent with the component renderer', () => {
+    const TestComponent = () => <div>Test</div>;
+    const appRender = renderApp(TestComponent);
+
+    // Call the render function
+    const teardown = appRender(mockElement, { fusion: mockFusion, env: mockEnv });
+
+    expect(renderComponent).toHaveBeenCalledWith(mockComponentRenderer);
+    expect(mockRenderFunction).toHaveBeenCalledWith(mockElement, {
+      fusion: mockFusion,
+      env: mockEnv,
+    });
+    expect(teardown).toBe(mockTeardown);
+  });
+
+  it('should return a teardown function that unmounts the component', () => {
+    const TestComponent = () => <div>Test</div>;
+    const appRender = renderApp(TestComponent);
+
+    const teardown = appRender(mockElement, { fusion: mockFusion, env: mockEnv });
+
+    expect(typeof teardown).toBe('function');
+    teardown();
+    expect(mockTeardown).toHaveBeenCalled();
+  });
+
+  it('should work without a configure callback', () => {
+    vi.clearAllMocks();
+    const TestComponent = () => <div>Test</div>;
+    const appRender = renderApp(TestComponent);
+
+    // When no configure callback is provided, it may be called with just the component
+    // or with undefined as the second parameter
+    expect(createComponent).toHaveBeenCalled();
+    const calls = vi.mocked(createComponent).mock.calls;
+    expect(calls[calls.length - 1][0]).toBe(TestComponent);
+    expect(calls[calls.length - 1][1]).toBeUndefined();
+
+    const teardown = appRender(mockElement, { fusion: mockFusion, env: mockEnv });
+
+    expect(teardown).toBe(mockTeardown);
+  });
+
+  it('should pass component renderer args correctly to renderComponent', () => {
+    const TestComponent = () => <div>Test</div>;
+    const appRender = renderApp(TestComponent);
+
+    const args: ComponentRenderArgs = {
+      fusion: mockFusion,
+      env: mockEnv,
+    };
+
+    appRender(mockElement, args);
+
+    expect(mockRenderFunction).toHaveBeenCalledWith(mockElement, args);
+  });
+});

package/src/ag-grid/useTheme.ts

@@ -2,6 +2,13 @@ import { useAppModule } from '../useAppModule';
 import type { AgGridModule } from '@equinor/fusion-framework-module-ag-grid';
 import type { Theme } from '@equinor/fusion-framework-module-ag-grid/themes';
 
+/**
+ * React hook that returns the current AG Grid theme from the application-scoped
+ * AG Grid module.
+ *
+ * @returns The active {@link Theme} object.
+ * @throws If the AG Grid module is not registered in the application.
+ */
 export const useTheme = (): Theme => {
   const agGrid = useAppModule<AgGridModule>('agGrid');
 

package/src/analytics/index.ts

@@ -1 +1,9 @@
+/**
+ * Analytics sub-path entry-point.
+ *
+ * Provides the {@link useTrackFeature} hook for tracking application-level
+ * analytics events through the Fusion analytics module.
+ *
+ * @packageDocumentation
+ */
 export { useTrackFeature } from './useTrackFeature';

package/src/analytics/useTrackFeature.ts

@@ -4,7 +4,23 @@ import type { AnalyticsModule, AnyValueMap } from '@equinor/fusion-framework-mod
 import { useCallback } from 'react';
 
 /**
- * Hook for using analytics module configured in the framework.
+ * React hook that returns a callback for tracking application feature usage
+ * via the Fusion analytics module.
+ *
+ * The tracked event includes the current app key and context (if available)
+ * as attributes, enabling downstream analytics dashboards to group events
+ * by application and context.
+ *
+ * @returns A `trackFeature` callback: `(name: string, data?: AnyValueMap) => void`.
+ *
+ * @example
+ * ```tsx
+ * const trackFeature = useTrackFeature();
+ *
+ * const handleClick = useCallback(() => {
+ *   trackFeature('button-click', { section: 'header' });
+ * }, [trackFeature]);
+ * ```
  */
 export const useTrackFeature = () => {
   const analyticsProvider = useFrameworkModule<AnalyticsModule>('analytics');

package/src/apploader/Apploader.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, type ReactElement } from 'react';
 import { useApploader } from './useApploader';
 
 export type ApploaderProps = {
@@ -13,12 +13,12 @@ export type ApploaderProps = {
  *
  * @param { ApploaderProps } props - The props for the component.
  * @param { string } props.appKey - The key of the Fusion app to load and mount.
- * @returns { JSX.Element } The rendered component, which displays loading, error, or the embedded app.
+ * @returns { ReactElement } The rendered component, which displays loading, error, or the embedded app.
  *
  * @example
  * <Apploader appKey="my-app" />
  */
-export const Apploader = ({ appKey }: ApploaderProps): JSX.Element => {
+export const Apploader = ({ appKey }: ApploaderProps): ReactElement => {
   const refWrapp = useRef<HTMLDivElement | null>(null);
   const { loading, error, appRef } = useApploader({ appKey });
 

package/src/apploader/index.ts

@@ -1,2 +1,10 @@
+/**
+ * Apploader sub-path entry-point.
+ *
+ * Provides the {@link Apploader} component and {@link useApploader} hook
+ * for embedding Fusion child applications inside a parent Fusion application.
+ *
+ * @packageDocumentation
+ */
 export { Apploader, type ApploaderProps } from './Apploader';
 export { useApploader } from './useApploader';

package/src/bookmark/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Bookmark sub-path entry-point.
+ *
+ * Provides helpers to enable and consume the Fusion bookmark module,
+ * allowing users to save and restore application state snapshots.
+ *
+ * @packageDocumentation
+ */
 export { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';
 
 export { useCurrentBookmark } from './useCurrentBookmark';

package/src/context/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Context sub-path entry-point.
+ *
+ * Provides hooks for reading and interacting with the Fusion context
+ * (project, facility, etc.) at both the application and framework level.
+ *
+ * @packageDocumentation
+ */
 export * from '@equinor/fusion-framework-react-module-context';
 
 export { useContextProvider } from './useContextProvider';

package/src/context/useContextProvider.ts

@@ -1,6 +1,12 @@
 import type { ContextModule } from '@equinor/fusion-framework-react-module-context';
 import { useAppModule } from '../useAppModule';
 
+/**
+ * React hook that resolves the application-scoped context module provider.
+ *
+ * @returns The context module provider instance.
+ * @throws If the context module is not registered in the application scope.
+ */
 export const useContextProvider = () => useAppModule<ContextModule>('context');
 
 export default useContextProvider;

package/src/context/useCurrentContext.ts

@@ -1,6 +1,20 @@
 import { useCurrentContext as _useCurrentContext } from '@equinor/fusion-framework-react-module-context';
 import useContextProvider from './useContextProvider';
 
+/**
+ * React hook that returns the currently selected Fusion context from the
+ * **application-scoped** context module.
+ *
+ * @returns The current context object, or `undefined` if no context is selected.
+ *
+ * @example
+ * ```tsx
+ * const context = useCurrentContext();
+ * if (context) {
+ *   console.log('Selected:', context.title);
+ * }
+ * ```
+ */
 export const useCurrentContext = () => _useCurrentContext(useContextProvider());
 
 export default useCurrentContext;

package/src/create-legacy-app.tsx

@@ -8,6 +8,19 @@ import type { AppEnv, AppModuleInitiator } from '@equinor/fusion-framework-app';
 import { createComponent } from './create-component';
 import type { AppModule } from '@equinor/fusion-framework-module-app';
 
+/**
+ * Creates a legacy wrapper component that bootstraps a Fusion React app within
+ * the older Fusion CLI hosting model.
+ *
+ * @deprecated Prefer {@link renderApp} for new applications. This helper exists
+ * only for backward-compatibility with apps that must run inside the legacy
+ * Fusion CLI.
+ *
+ * @template TModules - Array of additional module types to initialise.
+ * @param Component - The root React element to render.
+ * @param configure - Optional callback to configure application modules.
+ * @returns A React function component that initialises modules and renders the app.
+ */
 export const createLegacyApp = <TModules extends Array<AnyModule>>(
   Component: ElementType,
   configure?: AppModuleInitiator<TModules>,

package/src/feature-flag/index.ts

@@ -1,3 +1,11 @@
+/**
+ * Feature-flag sub-path entry-point.
+ *
+ * Provides the {@link enableFeatureFlag} configurator helper and the
+ * {@link useFeature} hook for reading and toggling feature flags at runtime.
+ *
+ * @packageDocumentation
+ */
 export {
   IFeatureFlag,
   IFeatureFlagProvider,

package/src/feature-flag/useFeature.ts

@@ -13,10 +13,26 @@ import { findFeature } from '@equinor/fusion-framework-module-feature-flag/selec
 import { useAppModule } from '../useAppModule';
 
 /**
- * Custom hook for accessing and manipulating feature flags.
- * @template T - The type of the feature flag value.
- * @param key - The key of the feature flag.
- * @returns An object containing the feature flag, toggle function, and error (if any).
+ * React hook for reading and toggling a single feature flag.
+ *
+ * Merges feature flags from both the framework and the application scope,
+ * so framework-level flags are visible alongside app-specific ones.
+ *
+ * @template T - The type of the feature flag's value payload.
+ * @param key - The unique key identifying the feature flag.
+ * @returns An object with:
+ *   - `feature` – the resolved {@link IFeatureFlag}, or `undefined` if not found.
+ *   - `toggleFeature` – callback to toggle the flag; pass `true`/`false` to
+ *     set explicitly, or omit to invert the current state.
+ *   - `error` – any error from the feature-flag observable.
+ *
+ * @example
+ * ```tsx
+ * const { feature, toggleFeature } = useFeature('dark-mode');
+ * return (
+ *   <Switch checked={feature?.enabled} onChange={() => toggleFeature()} />
+ * );
+ * ```
  */
 export const useFeature = <T = unknown>(
   key: string,

package/src/framework/index.ts

@@ -1,6 +1,13 @@
+/**
+ * Framework sub-path entry-point.
+ *
+ * Re-exports framework-level hooks (as opposed to application-scoped ones)
+ * for accessing the Fusion instance, current user, and HTTP clients.
+ *
+ * @packageDocumentation
+ */
 export { useFramework } from '@equinor/fusion-framework-react';
 
-// TODO
 export {
   useCurrentUser,
   useHttpClient as useFrameworkHttpClient,

package/src/framework/useFrameworkCurrentContext.ts

@@ -1,6 +1,15 @@
 import { useFramework } from '@equinor/fusion-framework-react';
 import { useCurrentContext } from '@equinor/fusion-framework-react-module-context';
 
+/**
+ * React hook that returns the currently selected context from the
+ * **framework-level** context module (as opposed to the application-scoped one).
+ *
+ * Use this when you need the portal/host context rather than the app's own
+ * context provider.
+ *
+ * @returns The current framework context, or `undefined` if none is selected.
+ */
 export const useFrameworkCurrentContext = () => useCurrentContext(useFramework().modules.context);
 
 export default useFrameworkCurrentContext;

package/src/help-center/useHelpCenter.ts

@@ -77,7 +77,18 @@ export interface HelpCenter {
 }
 
 /**
- * Hook for accessing help center.
+ * React hook that returns an API for opening the portal help-center sidesheet.
+ *
+ * Each method dispatches a framework event that the portal shell listens for
+ * and opens the corresponding help page.
+ *
+ * @returns A {@link HelpCenter} object with methods to open specific help pages.
+ *
+ * @example
+ * ```tsx
+ * const helpCenter = useHelpCenter();
+ * <Button onClick={() => helpCenter.openFaqs()}>FAQs</Button>
+ * ```
  */
 export const useHelpCenter = (): HelpCenter => {
   const eventModule = useAppModule('event');

package/src/http/index.ts

@@ -1 +1,10 @@
+/**
+ * HTTP sub-path entry-point.
+ *
+ * Re-exports hooks from `@equinor/fusion-framework-react-module-http`,
+ * including {@link useHttpClient} for making authenticated HTTP requests
+ * from within a Fusion application.
+ *
+ * @packageDocumentation
+ */
 export * from '@equinor/fusion-framework-react-module-http';

package/src/http/selectors.ts

@@ -0,0 +1,9 @@
+/**
+ * HTTP selector utilities.
+ *
+ * Re-exports response-selector helpers (e.g. JSON, blob, text selectors)
+ * from `@equinor/fusion-framework-module-http/selectors`.
+ *
+ * @packageDocumentation
+ */
+export * from '@equinor/fusion-framework-module-http/selectors';

package/src/index.ts

@@ -1,3 +1,19 @@
+/**
+ * @packageDocumentation
+ *
+ * React bindings for building Fusion Framework applications.
+ *
+ * Provides the main entry-point helpers (`renderApp`, `createComponent`, `makeComponent`)
+ * plus React hooks for accessing framework modules (HTTP, auth, context, navigation, etc.)
+ * from within a Fusion app.
+ *
+ * @remarks
+ * This is the primary package application developers depend on when building
+ * React-based Fusion apps. It re-exports core types from `@equinor/fusion-framework-app`
+ * and adds React-specific rendering, hooks, and sub-path entry-points for optional
+ * modules such as MSAL, feature flags, bookmarks, analytics, and settings.
+ */
+
 export type {
   AppConfig,
   AppEnv,
@@ -8,6 +24,8 @@ export type {
   IAppConfigurator,
 } from '@equinor/fusion-framework-app';
 
+export type { Fusion } from '@equinor/fusion-framework-react';
+
 export { AppManifest } from '@equinor/fusion-framework-module-app';
 
 export { useAppModule } from './useAppModule';
@@ -18,11 +36,11 @@ export { makeComponent, ComponentRenderArgs } from './make-component';
 
 export { createLegacyApp } from './create-legacy-app';
 
-// TODO deprecate
-export { renderApp } from './render-app';
 export { createComponent } from './create-component';
+export { renderApp } from './render-app';
 export { renderComponent } from './render-component';
 
 export type { ComponentRenderer } from './create-component';
+export type { RenderTeardown } from './render-component';
 
 export { default } from './render-app';

package/src/make-component.tsx

@@ -13,11 +13,26 @@ import type { FrameworkEvent, FrameworkEventInit } from '@equinor/fusion-framewo
 
 import { ModuleProvider as AppModuleProvider } from '@equinor/fusion-framework-react-module';
 
+/**
+ * Arguments supplied when rendering a Fusion app component.
+ *
+ * @template TFusion - The Fusion framework instance type.
+ * @template TEnv - The application environment type.
+ */
 export type ComponentRenderArgs<TFusion extends Fusion = Fusion, TEnv = AppEnv> = {
+  /** The Fusion framework instance. */
   fusion: TFusion;
+  /** The application environment (manifest, config, basename, etc.). */
   env: TEnv;
 };
 
+/**
+ * Factory function that receives a Fusion instance and environment and returns a
+ * lazy React component ready to be rendered.
+ *
+ * @template TFusion - The Fusion framework instance type.
+ * @template TEnv - The application environment type.
+ */
 export type ComponentRenderer<TFusion extends Fusion = Fusion, TEnv = AppEnv> = (
   fusion: TFusion,
   env: TEnv,
@@ -55,7 +70,7 @@ export const makeComponent = <
 ): React.LazyExoticComponent<React.ComponentType> =>
   lazy(async () => {
     const init = configureModules<TModules, TRef, TEnv>(configure);
-    const modules = (await init(args)) as unknown as AppModulesInstance;
+    const modules = await init(args);
 
     const { fusion } = args;
 

package/src/msal/index.ts

@@ -1,3 +1,16 @@
+/**
+ * MSAL authentication sub-path entry-point.
+ *
+ * Provides React hooks for accessing MSAL-based authentication state
+ * (current account, access tokens) from within a Fusion application.
+ *
+ * @remarks
+ * Requires `@equinor/fusion-framework-module-msal` to be installed and
+ * configured by the host/portal. Applications should **not** configure the
+ * MSAL module themselves.
+ *
+ * @packageDocumentation
+ */
 export { useCurrentAccount } from './useCurrentAccount';
 export { useAccessToken } from './useAccessToken';
 export { useToken } from './useToken';

package/src/msal/useAccessToken.ts

@@ -1,10 +1,22 @@
 import { useToken } from './useToken';
 
 /**
- * Custom hook that retrieves an access token for the specified authentication request.
+ * React hook that acquires an OAuth 2.0 access token string via MSAL.
  *
- * @param req - The authentication request.
- * @returns An object containing the access token, pending state, and error.
+ * This is a convenience wrapper around {@link useToken} that extracts the
+ * `accessToken` property from the full `AuthenticationResult`.
+ *
+ * @param req - The token request containing the `scopes` to acquire.
+ * @param req.scopes - Array of scope strings (e.g. `['User.Read']`).
+ * @returns An object with:
+ *   - `token` – the access token string, or `undefined` while pending.
+ *   - `pending` – `true` while the token is being acquired.
+ *   - `error` – any error encountered during acquisition.
+ *
+ * @example
+ * ```tsx
+ * const { token, pending, error } = useAccessToken({ scopes: ['api://my-api/.default'] });
+ * ```
  */
 export const useAccessToken = (req: {
   scopes: string[];

package/src/msal/useCurrentAccount.ts

@@ -2,8 +2,18 @@ import type { AccountInfo } from '@equinor/fusion-framework-module-msal';
 import useAppModule from '../useAppModule';
 
 /**
- * Retrieves the current account information from the MSAL provider.
- * @returns The current account information or undefined if no account is available.
+ * React hook that returns the currently signed-in user's MSAL account info.
+ *
+ * @returns The {@link AccountInfo} for the active account, or `undefined` if
+ *   no user is signed in.
+ *
+ * @example
+ * ```tsx
+ * const account = useCurrentAccount();
+ * if (account) {
+ *   console.log('Signed in as', account.name);
+ * }
+ * ```
  */
 export const useCurrentAccount = (): AccountInfo | undefined => {
   const msalProvider = useAppModule('auth');