@equinor/fusion-framework-react-app 14.0.3 → 14.1.1

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

@@ -1,113 +0,0 @@
-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/__tests__/useStateSyncEvents.test.ts

@@ -1,57 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { Subject } from 'rxjs';
-
-import { act, renderHook } from '@testing-library/react';
-
-import { StateSyncEvent, type StateSyncEventType } from '@equinor/fusion-framework-module-state';
-
-const event$ = new Subject<StateSyncEventType>();
-
-vi.mock('../useAppModule', () => ({
-  default: () => ({ event$ }),
-}));
-
-import { useStateSyncEvents } from '../state/useStateSyncEvents';
-
-describe('useStateSyncEvents', () => {
-  it('collects dispatched onStateSync.* events, oldest first', () => {
-    const { result } = renderHook(() => useStateSyncEvents(10));
-
-    expect(result.current).toEqual([]);
-
-    act(() => {
-      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
-      event$.next(new StateSyncEvent.Status({ detail: { status: 'paused' } }));
-    });
-
-    expect(result.current).toHaveLength(2);
-    expect(result.current[0].detail.status).toBe('active');
-    expect(result.current[1].detail.status).toBe('paused');
-  });
-
-  it('ignores events unrelated to state sync and trims the log to the given limit', () => {
-    const { result } = renderHook(() => useStateSyncEvents(1));
-
-    act(() => {
-      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
-      event$.next(
-        new StateSyncEvent.Error({ detail: { error: new Error('boom'), type: 'error' } }),
-      );
-    });
-
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]).toBeInstanceOf(StateSyncEvent.Error);
-  });
-
-  it('unsubscribes from the event stream on unmount', () => {
-    const { result, unmount } = renderHook(() => useStateSyncEvents(10));
-
-    unmount();
-
-    act(() => {
-      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
-    });
-
-    expect(result.current).toEqual([]);
-  });
-});

package/src/ag-grid/useTheme.ts

@@ -1,21 +0,0 @@
-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');
-
-  // Fail fast when the AG Grid module has not been registered on the app
-  if (!agGrid) {
-    throw new Error('agGrid module is not available');
-  }
-
-  return agGrid.theme as Theme;
-};

package/src/analytics/README.md

@@ -1,148 +0,0 @@
-## Analytics React Hooks
-
-React hooks for tracking application feature usage through the Fusion analytics module.
-
-These hooks are available from `@equinor/fusion-framework-react-app/analytics`. The analytics module is enabled and configured by the hosting portal, so **apps running inside a Fusion portal can use these hooks immediately without any setup**.
-
-### Why track feature usage?
-
-Understanding how users interact with your application helps you make informed decisions about what to build, improve, or remove. Without usage data, you are guessing which features matter.
-
-Common reasons to add feature tracking:
-
-- **Measure adoption** — find out whether a newly released feature is actually being used, and by how many users across different contexts.
-- **Identify unused features** — discover features that can be simplified or removed, reducing maintenance cost and complexity.
-- **Understand user workflows** — see which paths users take through your application, revealing unexpected patterns or friction points.
-- **Support data-driven prioritisation** — back up roadmap discussions with real usage numbers instead of assumptions.
-- **Debug user-reported issues** — correlate analytics events with error reports to understand what the user was doing when something went wrong.
-
-### When to use `useTrackFeature`
-
-Use `useTrackFeature` when you want to record a discrete user action or application milestone from a React component. Typical use cases include:
-
-| Use case | What to track | Example event name |
-|----------|---------------|-------------------|
-| Button or action clicks | User triggers a specific workflow | `'export-clicked'`, `'filter-applied'` |
-| Page or component views | A section of the app is displayed | `'dashboard-loaded'`, `'settings-opened'` |
-| Feature gate checks | A feature behind a flag is accessed | `'beta-feature-used'` |
-| Form submissions | A user completes a form or wizard step | `'report-submitted'`, `'wizard-step-3'` |
-| Error recovery actions | A user retries or dismisses an error | `'retry-clicked'`, `'error-dismissed'` |
-| Search and filtering | A user interacts with data exploration tools | `'search-executed'`, `'date-range-changed'` |
-
-> [!TIP]
-> You do not need to track every click. Focus on actions that answer a question about user behavior or feature value.
-
-### useTrackFeature
-
-Returns a stable callback for tracking feature usage events. Each event automatically includes the current app key and active context as attributes, so downstream dashboards can group events by application and context without extra work.
-
-**Signature:**
-
-```typescript
-function useTrackFeature(): (name: string, data?: AnyValueMap) => void;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `name` | `string` | Name of the feature being tracked |
-| `data` | `AnyValueMap` (optional) | Additional key-value pairs to include with the event |
-
-#### Track a button click
-
-```tsx
-import { useCallback } from 'react';
-import { useTrackFeature } from '@equinor/fusion-framework-react-app/analytics';
-
-const MyButton = () => {
-  const trackFeature = useTrackFeature();
-
-  const handleClick = useCallback(() => {
-    trackFeature('button-clicked');
-  }, [trackFeature]);
-
-  return <button onClick={handleClick}>Click me</button>;
-};
-```
-
-#### Track with additional data
-
-Pass a second argument to include custom attributes with the event:
-
-```tsx
-import { useCallback } from 'react';
-import { useTrackFeature } from '@equinor/fusion-framework-react-app/analytics';
-
-const SaveButton = ({ section }: { section: string }) => {
-  const trackFeature = useTrackFeature();
-
-  const handleSave = useCallback(() => {
-    trackFeature('save-clicked', { section, timestamp: Date.now() });
-  }, [trackFeature, section]);
-
-  return <button onClick={handleSave}>Save</button>;
-};
-```
-
-#### Track on component mount
-
-Use `useEffect` to track when a component or page loads:
-
-```tsx
-import { useEffect } from 'react';
-import { useTrackFeature } from '@equinor/fusion-framework-react-app/analytics';
-
-const Dashboard = () => {
-  const trackFeature = useTrackFeature();
-
-  useEffect(() => {
-    trackFeature('dashboard-loaded');
-  }, [trackFeature]);
-
-  return <div>Dashboard content</div>;
-};
-```
-
-#### Combine click and mount tracking
-
-```tsx
-import { useCallback, useEffect } from 'react';
-import { useTrackFeature } from '@equinor/fusion-framework-react-app/analytics';
-
-const SomeComponent = () => {
-  const trackFeature = useTrackFeature();
-
-  useEffect(() => {
-    trackFeature('SomeComponent loaded');
-    trackFeature('some feature happened', { extra: 'data', foo: 'bar' });
-  }, [trackFeature]);
-
-  const handleOnClick = useCallback(() => {
-    trackFeature('button-clicked');
-  }, [trackFeature]);
-
-  return <button onClick={handleOnClick}>Click me</button>;
-};
-```
-
-### Prerequisites
-
-The analytics module must be enabled for these hooks to work. **In most cases, no app-level configuration is needed** — the hosting Fusion portal already enables and configures analytics with the appropriate adapters and collectors. Your app inherits this automatically.
-
-If the module is not available (e.g. in a standalone or custom portal setup), `useTrackFeature` logs an exception via the telemetry provider instead of throwing, so your app will not crash.
-
-#### Custom or standalone setups
-
-If you are building a custom portal or running outside the standard Fusion portal, you need to enable the analytics module yourself:
-
-```typescript
-import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
-import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
-
-const configure = (configurator) => {
-  enableAnalytics(configurator, (builder) => {
-    builder.setAdapter('console', async () => new ConsoleAnalyticsAdapter());
-  });
-};
-```
-
-See the [analytics module documentation](https://equinor.github.io/fusion-framework/modules/analytics/) for adapter and collector setup.

package/src/analytics/index.ts

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-import { useFrameworkModule } from '@equinor/fusion-framework-react';
-import type { AppModule } from '@equinor/fusion-framework-module-app';
-import type { AnalyticsModule, AnyValueMap } from '@equinor/fusion-framework-module-analytics';
-import { useCallback } from 'react';
-
-/**
- * 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');
-  const appProvider = useFrameworkModule<AppModule>('app');
-  const contextProvider = useFrameworkModule('context');
-  const telemetryProvider = useFrameworkModule('telemetry');
-
-  /**
-   * Tracks a analytics event.
-   *
-   * Can be used both in useCallback or useEffects - see README.md for examples.
-   *
-   * @param name - The feature to track
-   * @param data - Optional map of additional key-value pairs to include with the analytics event
-   */
-  const trackFeature = useCallback(
-    (name: string, data?: AnyValueMap) => {
-      // Report to telemetry when analytics tracking is not available so the gap is visible
-      if (!analyticsProvider) {
-        telemetryProvider?.trackException({
-          name: 'AnalyticsProviderNotFound',
-          exception: new Error(`Analytics provider not found`),
-        });
-      }
-
-      analyticsProvider?.trackAnalytic({
-        name: 'app-feature',
-        value: {
-          feature: name,
-          data,
-        },
-        attributes: {
-          appKey: appProvider?.current?.appKey,
-          context: contextProvider?.currentContext
-            ? {
-                id: contextProvider.currentContext.id,
-                externalId: contextProvider.currentContext.externalId,
-                title: contextProvider.currentContext.title,
-                type: contextProvider.currentContext.type.id,
-                source: contextProvider.currentContext.source,
-              }
-            : undefined,
-        },
-      });
-    },
-    [analyticsProvider, appProvider, contextProvider, telemetryProvider],
-  );
-
-  return trackFeature;
-};

package/src/apploader/Apploader.tsx

@@ -1,50 +0,0 @@
-import { useEffect, useRef, type ReactElement } from 'react';
-import { useApploader } from './useApploader';
-
-export type ApploaderProps = {
-  appKey: string;
-};
-
-/**
- * Apploader component
- *
- * Embeds a Fusion child application inside a parent Fusion application.
- * Handles loading and error states, and mounts the child app's DOM element into a container div.
- *
- * @param { ApploaderProps } props - The props for the component.
- * @param { string } props.appKey - The key of the Fusion app to load and mount.
- * @returns { ReactElement } The rendered component, which displays loading, error, or the embedded app.
- *
- * @example
- * <Apploader appKey="my-app" />
- */
-export const Apploader = ({ appKey }: ApploaderProps): ReactElement => {
-  const refWrapp = useRef<HTMLDivElement | null>(null);
-  const { loading, error, appRef } = useApploader({ appKey });
-
-  useEffect(() => {
-    // Wait until both the wrapper element and the loaded app element are available
-    if (!refWrapp.current || !appRef.current) {
-      return;
-    }
-
-    refWrapp.current.appendChild(appRef.current);
-  }, [appRef.current]);
-
-  // Show a loading placeholder while the app is being fetched and initialized
-  if (loading) {
-    return <div>Loading {appKey}</div>;
-  }
-  // Surface the load error instead of rendering the app
-  if (error) {
-    return (
-      <div>
-        Error loading {appKey}. Error: {error.message}
-      </div>
-    );
-  }
-
-  return <div ref={refWrapp} />;
-};
-
-export default Apploader;

package/src/apploader/README.md

@@ -1,81 +0,0 @@
-# `@equinor/fusion-framework-react-app/apploader`
-
-> [!NOTE]
-> This file is kept for legacy tooling. The canonical documentation is in [`packages/react/app/docs/apploader.md`](../../docs/apploader.md) and published via VuePress.
-
-[Apploader](#apploader) component and [useApploader](#useapploader) is intended to be used to embed Fusion applications inside other Fusion application.
-
-> [!WARNING]
-> `Apploader` is an experimental poc.
->
-> The embedded application will likely have issues with routing, context and other framework functionality, so use with care.
->
-> Should only be used to embed 'simple' applications like **PowerBI** and **PowerApps**.
-
-## Apploader
-
-React component for embeding a Fusion child application inside a parent Fusion application.
-
-Handles loading and error states, and mounts the child app's DOM element into a container div.
-
-If you need to customise the error and loading messages, then use the hook ``useApploader`` and create your own component.
-
-### Example usage
-
-```typescript
-<Apploader appKey="my-app" />
-```
-
-## useApploader
-
-A React hook for dynamically loading and mounting a Fusion child app inside a parent Fusion app. Handles loading state, error reporting, and provides a reference to the mounted app’s DOM element.
-
-### Signature
-
-```typescript
-useApploader({ appKey }: { appKey: string }): {
-  loading: boolean;
-  error: Error | undefined;
-  appRef: React.RefObject<HTMLDivElement | null>;
-}
-```
-
-### Parameters
-
-`appKey (string)`: The key of the Fusion app to load and mount.
-
-### Returns
-
-- **loading** ``(boolean)``: true while the app is loading.
-- **error** ``(Error | undefined)``: Error object if loading fails, otherwise undefined.
-- **appRef** ``(React.RefObject<HTMLDivElement | null>)``: Ref to the DOM element where the child app is mounted.
-
-### Usage Example
-
-```typescript
-import React, { useEffect, useRef } from 'react';
-import { useApploader } from './useAppLoader';
-
-const MyAppLoader = ({ appKey }: { appKey: string }) => {
-  const wrapperRef = useRef<HTMLDivElement | null>(null);
-  const { loading, error, appRef } = useApploader({ appKey });
-
-  useEffect(() => {
-    if (wrapperRef.current && appRef.current) {
-      wrapperRef.current.appendChild(appRef.current);
-    }
-  }, [appRef.current]);
-
-  if (loading) return <div>Loading {appKey}...</div>;
-  if (error) return <div>Error loading {appKey}: {error.message}</div>;
-
-  return <div ref={wrapperRef} />;
-};
-```
-
-### Notes
-
-- The hook is designed to be used in a parent Fusion app context.
-- The returned appRef should be appended to a container element in your component.
-- Handles subscription and cleanup automatically.
-- Useful for micro-frontend scenarios where apps are loaded dynamically.

package/src/apploader/index.ts

@@ -1,10 +0,0 @@
-/**
- * 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/apploader/useApploader.ts

@@ -1,107 +0,0 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
-
-import { useFramework } from '@equinor/fusion-framework-react';
-import type { AppModule } from '@equinor/fusion-framework-module-app';
-
-import type { ApploaderProps } from './Apploader';
-import type { AppInitializeResult } from '@equinor/fusion-framework-module-app/app';
-
-/**
- * React hook for dynamically loading and mounting a Fusion child app inside a parent Fusion app.
- * Handles loading state, error reporting, and provides a reference to the mounted app’s DOM element.
- *
- * @param { Object } params
- * @param { string } params.appKey - The key of the Fusion app to load and mount.
- * @returns {{
- *   loading: boolean,
- *   error: Error | undefined,
- *   appRef: React.RefObject<HTMLDivElement | null>
- * }} An object containing loading state, error, and a ref to the mounted app element.
- *
- * @example
- * ```typescript
- * const { loading, error, appRef } = useApploader({ appKey: 'my-app' });
- *
- * useEffect(() => {
- *   if (containerRef.current && appRef.current) {
- *     containerRef.current.appendChild(appRef.current);
- *   }
- * }, [appRef.current]);
- *
- * if (loading) return <div>Loading...</div>;
- * if (error) return <div>Error: {error.message}</div>;
- * return <div ref={containerRef} />;
- * ```
- */
-export const useApploader = ({
-  appKey,
-}: ApploaderProps): {
-  loading: boolean;
-  error: Error | undefined;
-  appRef: React.RefObject<HTMLDivElement | null>;
-} => {
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | undefined>();
-  const appRef = useRef<HTMLDivElement | null>(null);
-  const fusion = useFramework<[AppModule]>();
-
-  /**
-   * The current fusion app.
-   * aka the parent app that is loading the child app.
-   */
-  const fusionApp = useMemo(() => fusion.modules.app.current, [fusion]);
-
-  /**
-   * The app to be mounted
-   * aka the child app that is being loaded.
-   */
-  const loadedApp = useMemo(() => fusion.modules.app.createApp({ appKey }), [fusion, appKey]);
-
-  useEffect(() => {
-    setLoading(true);
-    setError(undefined);
-    const subscription$ = loadedApp?.initialize().subscribe({
-      next: (instance: AppInitializeResult) => {
-        const { manifest, script, config } = instance;
-        /* Application Element for mounting */
-        appRef.current = document.createElement('div');
-        appRef.current.id = manifest.appKey;
-        appRef.current.style.display = 'contents';
-
-        /* Use basename of current fusionApp */
-        const basename = `/apps/${fusionApp?.appKey}`;
-
-        try {
-          const render = script.renderApp ?? script.default;
-          // Prefer the modern renderApp export, falling back to the default export
-          if (render) {
-            return render(appRef.current, {
-              fusion,
-              env: { basename, config, manifest, props: {} },
-            });
-          }
-          throw Error('Application is not supported, no render function provided');
-        } catch (error) {
-          console.error('App loading Error: ', error);
-          setError(error as Error);
-        }
-      },
-      complete: () => {
-        setLoading(false);
-      },
-      error: (error: Error) => {
-        setError(error);
-        setLoading(false);
-      },
-    });
-    return () => {
-      subscription$.unsubscribe();
-    };
-  }, [fusionApp, loadedApp, fusion]);
-
-  return {
-    loading,
-    error,
-    appRef,
-  };
-};