@equinor/fusion-framework-react-app 10.0.8 → 11.0.0

package/dist/types/create-legacy-app.d.ts

@@ -14,4 +14,4 @@ import type { AppModuleInitiator } from '@equinor/fusion-framework-app';
  * @param configure - Optional callback to configure application modules.
  * @returns A React function component that initialises modules and renders the app.
  */
-export declare const createLegacyApp: <TModules extends Array<AnyModule>>(Component: ElementType, configure?: AppModuleInitiator<TModules>) => () => import("react/jsx-runtime").JSX.Element;
+export declare const createLegacyApp: <TModules extends Array<AnyModule>>(Component: ElementType, configure?: AppModuleInitiator<TModules>) => () => import("react").JSX.Element;

package/dist/types/routing/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Routing sub-path entry-point for `@equinor/fusion-framework-react-app`.
+ *
+ * Re-exports the full public API of `@equinor/fusion-framework-react-router`
+ * and its route builder DSL so consumers can import all routing primitives
+ * from a single entry point without adding a separate direct dependency.
+ *
+ * Requires `@equinor/fusion-framework-react-router` to be installed.
+ * It is declared as an optional peer dependency — install it only when
+ * you need routing in your app, portal, or widget.
+ *
+ * @example
+ * ```ts
+ * import { Router } from '@equinor/fusion-framework-react-app/routing';
+ * import { layout, index, route } from '@equinor/fusion-framework-react-app/routing';
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * from '@equinor/fusion-framework-react-router';
+export { index, IndexRoute, route, Route, layout, LayoutRoute, prefix, PrefixRoute, } from '@equinor/fusion-framework-react-router/routes';
+export type { RouteSchemaEntry } from '@equinor/fusion-framework-react-router/routes';

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "10.0.8";
+export declare const version = "11.0.0";

package/docs/analytics.md

@@ -0,0 +1,122 @@
+# Analytics
+
+React hooks for tracking application feature usage through the Fusion analytics module.
+
+**Import:**
+
+```ts
+import { useTrackFeature } 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 runtime setup**.
+
+> [!IMPORTANT]
+> `useTrackFeature` accepts an `AnyValueMap` type parameter from `@equinor/fusion-framework-module-analytics`. This package is a `devDependency` of `@equinor/fusion-framework-react-app`, so **no runtime installation is needed** when running inside a Fusion portal. However, if your app imports `AnyValueMap` directly for typing, you may need to add `@equinor/fusion-framework-module-analytics` as a `devDependency` in your own project for TypeScript to resolve the type.
+
+## When to Track
+
+Use `useTrackFeature` when you want to record a discrete user action or application milestone. Focus on actions that answer a question about user behavior or feature value — you do not need to track every click.
+
+> [!NOTE]
+> The `name` argument you pass to the tracking callback becomes `value.feature` in the analytics event. The emitted analytics event always has `name: 'app-feature'` — the `name` you supply is the **feature name**, not the analytics event name.
+
+| Use case                | What to track                            | Example feature name        |
+| ----------------------- | ---------------------------------------- | ---------------------------- |
+| Button or action clicks | User triggers a specific workflow        | `'export-clicked'`           |
+| Page or component views | A section of the app is displayed        | `'dashboard-loaded'`         |
+| 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'`         |
+| Error recovery actions  | A user retries or dismisses an error     | `'retry-clicked'`            |
+
+## 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:**
+
+```ts
+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 included 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>;
+};
+```
+
+## Prerequisites
+
+The analytics module must be enabled for the hook to work. **In most cases, no app-level configuration is needed** — the hosting Fusion portal already enables and configures analytics. 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, enable the analytics module yourself:
+
+```ts
+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/docs/app.md

@@ -0,0 +1,148 @@
+# App (Root Entry Point)
+
+Core bootstrapping and module access hooks for Fusion React applications.
+
+**Import:**
+
+```ts
+import { renderApp, useAppModule, useAppModules, useAppEnvironmentVariables } from '@equinor/fusion-framework-react-app';
+```
+
+## renderApp
+
+The standard bootstrap function for Fusion React apps. Wraps your root component and an optional configuration callback into a render function that the Fusion portal calls to mount your app.
+
+**Signature:**
+
+```ts
+function renderApp(
+  Component: React.ElementType,
+  configure?: AppModuleInitiator,
+): (el: HTMLElement, args: ComponentRenderArgs) => RenderTeardown;
+```
+
+`AppModuleInitiator` receives `(configurator, { fusion, env })` and may return `Promise<void>` for async setup.
+
+**Returns:** A mount function the portal calls with a DOM element and render args. The returned `RenderTeardown` callback unmounts the app.
+
+### How to Use
+
+Export `renderApp` as your app's `render` entrypoint:
+
+```ts
+// main.ts
+import { renderApp } from '@equinor/fusion-framework-react-app';
+import { App } from './App';
+import { configure } from './config';
+
+export const render = renderApp(App, configure);
+export default render;
+```
+
+The `configure` callback is an `AppModuleInitiator` — it receives `(configurator, { fusion, env })` and may be async:
+
+```ts
+// config.ts
+import type { AppModuleInitiator } from '@equinor/fusion-framework-react-app';
+
+export const configure: AppModuleInitiator = (configurator) => {
+  configurator.configureHttpClient('my-api', {
+    baseUri: 'https://api.example.com',
+    defaultScopes: ['api://my-api/.default'],
+  });
+};
+```
+
+## useAppModule
+
+Retrieves a single typed module instance from the application scope. Throws if the module is not registered.
+
+**Signature:**
+
+```ts
+// Key-based inference (no explicit generic needed for known modules):
+function useAppModule(module: 'auth' | 'context' | ...): InferredModuleType;
+
+// Explicit generic for custom/unknown module keys:
+function useAppModule<TType extends AnyModule>(module: string): ModuleType<TType>;
+```
+
+When called with a known string literal key (e.g. `'auth'`), the return type is inferred automatically. Pass an explicit generic only when using a custom or unrecognised key.
+
+**Example:**
+
+```tsx
+import { useAppModule } from '@equinor/fusion-framework-react-app';
+
+const MyComponent = () => {
+  const auth = useAppModule('auth');
+  // auth is typed based on the registered module
+  return <button onClick={() => auth.acquireAccessToken()}>Get token</button>;
+};
+```
+
+## useAppModules
+
+Returns the full set of initialised application-scoped modules. Use this when you need to inspect or access multiple modules at once — prefer `useAppModule` for single-module access.
+
+**Signature:**
+
+```ts
+function useAppModules<T>(): AppModulesInstance<T>;
+```
+
+**Example:**
+
+```tsx
+import { useAppModules } from '@equinor/fusion-framework-react-app';
+
+const DebugPanel = () => {
+  const modules = useAppModules();
+  return <pre>{Object.keys(modules).join(', ')}</pre>;
+};
+```
+
+## useAppEnvironmentVariables
+
+Returns the app's environment variables as an observable state. The value is loaded asynchronously from the app configuration, so you should handle `complete` and `error` states.
+
+**Signature:**
+
+```ts
+function useAppEnvironmentVariables<TEnvironmentVariables>(): ObservableStateReturnType<TEnvironmentVariables>;
+```
+
+**Returns:**
+
+| Property   | Type                         | Description                                          |
+| ---------- | ---------------------------- | ---------------------------------------------------- |
+| `value`    | `TEnvironmentVariables \| undefined` | The resolved environment variables, or `undefined` before the observable emits |
+| `complete` | `boolean`                           | `true` when loading is finished                                                |
+| `error`    | `unknown \| null`                   | Error if loading failed, `null` otherwise                                      |
+
+**Example:**
+
+```tsx
+import { useAppEnvironmentVariables } from '@equinor/fusion-framework-react-app';
+
+type MyEnv = {
+  apiUrl: string;
+  featureFlags: Record<string, boolean>;
+};
+
+const MyComponent = () => {
+  const env = useAppEnvironmentVariables<MyEnv>();
+
+  if (!env.complete) return <p>Loading environment…</p>;
+  if (env.error) return <p>Failed to load environment</p>;
+
+  return <p>API URL: {env.value.apiUrl}</p>;
+};
+```
+
+## Deprecated APIs
+
+> [!CAUTION]
+> `createComponent` is **deprecated**. Use `renderApp` instead.
+
+These older bootstrapping functions are still exported for backward compatibility but should not be used in new apps.

package/docs/apploader.md

@@ -0,0 +1,110 @@
+# Apploader
+
+Embed a Fusion child application inside a parent Fusion application using the `Apploader` component or `useApploader` hook.
+
+> [!WARNING]
+> **Experimental / Proof of Concept**
+>
+> The embedded application will likely have issues with routing, context, and other framework features.
+> Use this only for embedding simple applications such as **PowerBI** or **PowerApps** viewers.
+
+**Import:**
+
+```ts
+import { Apploader, useApploader } from '@equinor/fusion-framework-react-app/apploader';
+```
+
+## When to Use
+
+Use apploader when your Fusion app needs to render another Fusion app inline — for example, embedding a PowerBI report viewer inside a dashboard app. For complex child apps that need their own routing or context module, this approach is not suitable.
+
+## Apploader Component
+
+The `Apploader` component is the simplest way to embed a child app. It handles loading and error states automatically and mounts the child app's DOM element into a container `div`.
+
+**Signature:**
+
+```tsx
+function Apploader(props: ApploaderProps): ReactElement;
+
+type ApploaderProps = {
+  /** The app key identifying the Fusion app to load and mount */
+  appKey: string;
+};
+```
+
+**Example:**
+
+```tsx
+import { Apploader } from '@equinor/fusion-framework-react-app/apploader';
+
+const Dashboard = () => {
+  return (
+    <section>
+      <h2>Embedded Report</h2>
+      <Apploader appKey="my-powerbi-app" />
+    </section>
+  );
+};
+```
+
+The component renders:
+
+- `"Loading {appKey}"` while the child app is being fetched and initialized
+- `"Error loading {appKey}. Error: {message}"` if initialization fails
+- The child app's DOM tree once loaded
+
+## useApploader Hook
+
+Use the `useApploader` hook when you need custom loading or error UI, or when you want more control over how the child app's DOM element is mounted.
+
+**Signature:**
+
+```ts
+function useApploader(params: { appKey: string }): {
+  loading: boolean;
+  error: Error | undefined;
+  appRef: React.RefObject<HTMLDivElement | null>;
+};
+```
+
+**Parameters:**
+
+- `appKey` — the key of the Fusion app to load and mount
+
+**Returns:**
+
+| Property  | Type                                    | Description                                      |
+| --------- | --------------------------------------- | ------------------------------------------------ |
+| `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 |
+
+**Example:**
+
+```tsx
+import { useApploader } from '@equinor/fusion-framework-react-app/apploader';
+import { useEffect, useRef } from 'react';
+
+const CustomAppEmbed = ({ appKey }: { appKey: string }) => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const { loading, error, appRef } = useApploader({ appKey });
+
+  useEffect(() => {
+    if (containerRef.current && appRef.current) {
+      containerRef.current.appendChild(appRef.current);
+    }
+  }, [appRef.current]);
+
+  if (loading) return <p>Loading application…</p>;
+  if (error) return <p>Failed to load: {error.message}</p>;
+
+  return <div ref={containerRef} />;
+};
+```
+
+## Limitations
+
+- **Routing:** The child app shares the parent's URL space. Deep-linking and navigation inside the embedded app may conflict with the parent's router.
+- **Context:** The child app receives the parent's framework instance but does not get its own isolated context module.
+- **Scope:** Best suited for simple, self-contained apps (e.g., PowerBI, PowerApps). Complex apps with their own routing or context configuration are not supported.

package/docs/bookmark.md

@@ -0,0 +1,101 @@
+# Bookmark
+
+Save and restore application state snapshots using the Fusion bookmark module.
+
+**Import:**
+
+```ts
+import { useCurrentBookmark, enableBookmark } from '@equinor/fusion-framework-react-app/bookmark';
+```
+
+## Overview
+
+Bookmarks let users save the current state of your app (filters, selections, active views) and restore it later. The `useCurrentBookmark` hook is the primary API for app developers — it reads the active bookmark and lets you provide a callback that captures your app's current state when a bookmark is created.
+
+## Enable Bookmarks
+
+Register the bookmark module in your app's configuration:
+
+```ts
+import { enableBookmark } from '@equinor/fusion-framework-react-app/bookmark';
+
+export const configure = (configurator) => {
+  enableBookmark(configurator);
+};
+```
+
+## useCurrentBookmark
+
+The recommended hook for working with bookmarks in your app. Returns the current bookmark (if any) and a setter, filtered to only show bookmarks belonging to your app.
+
+**Signature:**
+
+```ts
+function useCurrentBookmark<TData extends BookmarkData>(
+  payloadGenerator?: BookmarkPayloadGenerator<TData>,
+): {
+  currentBookmark: Bookmark<TData> | null;
+  setCurrentBookmark: (bookmark_or_id: Bookmark | string | null) => VoidFunction;
+};
+```
+
+| Parameter          | Type                                | Description                                                    |
+| ------------------ | ----------------------------------- | -------------------------------------------------------------- |
+| `payloadGenerator` | `BookmarkPayloadGenerator<TData>` _(optional)_ | Callback that returns the current app state to store in the bookmark. **Must be wrapped in `useCallback`.** |
+
+### Basic Usage
+
+Provide a `payloadGenerator` wrapped in `useCallback` to capture your app state when a bookmark is created:
+
+```tsx
+import { useCallback, useState } from 'react';
+import { useCurrentBookmark } from '@equinor/fusion-framework-react-app/bookmark';
+
+type MyBookmarkData = {
+  selectedFilter: string;
+  activeTab: number;
+};
+
+const MyApp = () => {
+  const [filter, setFilter] = useState('all');
+  const [tab, setTab] = useState(0);
+
+  const { currentBookmark } = useCurrentBookmark<MyBookmarkData>(
+    useCallback(() => ({
+      selectedFilter: filter,
+      activeTab: tab,
+    }), [filter, tab])
+  );
+
+  // Restore state from bookmark when it changes
+  // currentBookmark is null when no bookmark is active or the bookmark belongs to a different app
+
+  return (
+    <div>
+      <p>Active bookmark: {currentBookmark?.name ?? 'None'}</p>
+    </div>
+  );
+};
+```
+
+## useBookmark (Deprecated)
+
+> [!CAUTION]
+> `useBookmark` is **deprecated**. Use `useCurrentBookmark` instead.
+
+`useBookmark` provides the full bookmark CRUD API (create, update, delete, list). For app development, `useCurrentBookmark` is sufficient — it handles app-scoping automatically and has a simpler interface.
+
+```ts
+// ❌ Deprecated
+import { useBookmark } from '@equinor/fusion-framework-react-app/bookmark';
+
+// ✅ Use instead
+import { useCurrentBookmark } from '@equinor/fusion-framework-react-app/bookmark';
+```
+
+If you need the full CRUD API, import directly from `@equinor/fusion-framework-react-module-bookmark`.
+
+## Prerequisites
+
+- The bookmark module must be enabled via `enableBookmark` in the app configurator
+- `@equinor/fusion-framework-react-module-bookmark` must be installed explicitly in your app

package/docs/context.md

@@ -0,0 +1,86 @@
+# Context
+
+Read the currently selected Fusion context (project, facility, etc.) from your app using the app-scoped context hooks.
+
+**Import:**
+
+```ts
+import { useCurrentContext, useContextProvider } from '@equinor/fusion-framework-react-app/context';
+```
+
+## Overview
+
+Fusion apps operate within a **context** — typically a project or facility selected by the user in the portal. The `useCurrentContext` hook returns the active context from your app's own context module. If no context is selected, it returns `undefined`.
+
+> [!IMPORTANT]
+> **App-scoped vs Framework-scoped context**
+>
+> - `useCurrentContext` (this sub-path) reads from the **app's own context module**. Your app must have the context module enabled.
+> - `useFrameworkCurrentContext` (from `/framework`) reads from the **portal/host-level context**, regardless of whether your app has its own context module.
+>
+> **Prefer `useCurrentContext`** unless you specifically need portal-level context.
+
+## useCurrentContext
+
+Returns the currently selected context from the application-scoped context module.
+
+**Signature:**
+
+```ts
+function useCurrentContext(): {
+  currentContext: ContextItem | null | undefined;
+  setCurrentContext: (context?: ContextItem | string | null) => void;
+};
+```
+
+**Returns:** An object with the current context (`ContextItem | null | undefined`) and a setter to change it.
+
+### Example
+
+```tsx
+import { useCurrentContext } from '@equinor/fusion-framework-react-app/context';
+
+const ProjectHeader = () => {
+  const { currentContext } = useCurrentContext();
+
+  if (!currentContext) {
+    return <p>No context selected</p>;
+  }
+
+  return (
+    <header>
+      <h1>{currentContext.title}</h1>
+      <span>Type: {currentContext.type.id}</span>
+    </header>
+  );
+};
+```
+
+## useContextProvider
+
+Returns the app-scoped context module provider instance directly. Use this when you need to interact with the context module beyond just reading the current value — for example, querying available contexts or subscribing to context changes.
+
+**Signature:**
+
+```ts
+function useContextProvider(): IContextProvider;
+```
+
+**Throws** if the context module is not registered in the application scope.
+
+### Example
+
+```tsx
+import { useContextProvider } from '@equinor/fusion-framework-react-app/context';
+
+const ContextDebug = () => {
+  const contextProvider = useContextProvider();
+  // Access the full provider API
+  return <pre>{JSON.stringify(contextProvider.currentContext, null, 2)}</pre>;
+};
+```
+
+## Prerequisites
+
+- The context module must be enabled in your app's configurator
+- The `useFrameworkCurrentContext` hook is also re-exported from this sub-path for convenience — see the [framework docs](./framework.md) for details