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

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,
-  };
-};

package/src/bookmark/index.ts

@@ -1,20 +0,0 @@
-/**
- * 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';
-export { useBookmark } from './useBookmark';
-
-export type {
-  Bookmark,
-  Bookmarks,
-  BookmarkData,
-  BookmarkPayloadGenerator,
-  BookmarkProvider,
-} from '@equinor/fusion-framework-react-module-bookmark';

package/src/bookmark/useBookmark.ts

@@ -1,25 +0,0 @@
-import {
-  useBookmark as _useBookmark,
-  type useBookmarkResult,
-} from '@equinor/fusion-framework-react-module-bookmark';
-
-/**
- * @deprecated Use useBookmark from @equinor/fusion-framework-react-module-bookmark
- *  For application development the useCurrentBookmark should be sufficient enough
- *
- *  Functionality provided here is:
- *  - addBookmarkCreator
- *  - getAllBookmarks
- *  - createBookmark
- *  - updateBookmark
- *  - deleteBookmarkById
- *  - setCurrentBookmark
- *  - currentBookmark
- *  - bookmarks,
- *
- * @template TData - Current applications  bookmark type
- * @return {*}  {Bookmarks<TData>} the full api fro handling bookmarks
- */
-export const useBookmark = <_TData>(): useBookmarkResult => _useBookmark();
-
-export default useBookmark;

package/src/bookmark/useCurrentBookmark.ts

@@ -1,54 +0,0 @@
-import {
-  type BookmarkData,
-  type BookmarkPayloadGenerator,
-  type useCurrentBookmarkReturn,
-  useCurrentBookmark as _useCurrentBookmark,
-  type BookmarkModule,
-  bookmarkWithDataSchema,
-} from '@equinor/fusion-framework-react-module-bookmark';
-
-import { useFrameworkModule } from '@equinor/fusion-framework-react';
-import useAppModules from '../useAppModules';
-import { useCurrentApp } from '@equinor/fusion-framework-react/app';
-
-/**
- * By providing a CreateBookMarkFn bookmarks is enabled for the current application.
- *
- * @template TData - Type of data stored in bookmark
- * @param {CreateBookMarkFn<TData>} [createBookmarkState] - Function for creating bookmark payload, this function should be wrapped in useCallback
- *
- * ```TS
- * // Example
- * const { currentBookmark } = useCurrentBookmark(useCallback(()=> someState, [someState]))
- * ```
- * @return {*}  {CurrentBookmark<TData>}
- */
-export const useCurrentBookmark = <TData extends BookmarkData>(
-  payloadGenerator?: BookmarkPayloadGenerator<TData>,
-): useCurrentBookmarkReturn<TData> => {
-  const { currentApp } = useCurrentApp();
-  const appBookmarkProvider = useAppModules<[BookmarkModule]>().bookmark;
-  const frameworkBookmarkProvider = useFrameworkModule<BookmarkModule>('bookmark');
-  // Warn about the deprecated fallback to the framework-scoped bookmark provider
-  if (!appBookmarkProvider) {
-    console.warn(
-      '@deprecation',
-      'application has not enabled bookmarks, this will not work in the future',
-    );
-  }
-  const { currentBookmark, setCurrentBookmark } = _useCurrentBookmark<TData>({
-    provider: appBookmarkProvider ?? frameworkBookmarkProvider,
-    payloadGenerator,
-  });
-
-  const currentBookmarkAppKey = bookmarkWithDataSchema().safeParse(currentBookmark).success
-    ? bookmarkWithDataSchema().parse(currentBookmark).appKey
-    : null;
-
-  return {
-    currentBookmark: currentBookmarkAppKey === currentApp?.appKey ? currentBookmark : null,
-    setCurrentBookmark,
-  };
-};
-
-export default useCurrentBookmark;

package/src/context/index.ts

@@ -1,14 +0,0 @@
-/**
- * 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';
-export { useCurrentContext } from './useCurrentContext';
-
-export { useFrameworkCurrentContext } from '../framework/useFrameworkCurrentContext';

package/src/context/useContextProvider.ts

@@ -1,12 +0,0 @@
-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,20 +0,0 @@
-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;