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

package/docs/framework.md

@@ -0,0 +1,93 @@
+# Framework
+
+Access framework-level (portal/host) context and services from within your app.
+
+**Import:**
+
+```ts
+import { useFramework, useCurrentUser, useFrameworkHttpClient } from '@equinor/fusion-framework-react-app/framework';
+// useFrameworkCurrentContext is exported from the /context sub-path:
+import { useFrameworkCurrentContext } from '@equinor/fusion-framework-react-app/context';
+```
+
+## When to Use
+
+Most apps should use the **app-scoped** hooks from the `/context` sub-path (`@equinor/fusion-framework-react-app/context`). The framework sub-path is for specific cases where you need data from the portal/host level, regardless of your app's own module configuration.
+
+> [!NOTE]
+> **Prefer `/context` unless you specifically need framework-level context.**
+>
+> `useCurrentContext` (from `/context`) reads from your app's own context module.
+> `useFrameworkCurrentContext` (also from `/context`) reads from the portal's context, bypassing your app's context module entirely.
+
+## useFrameworkCurrentContext
+
+Returns the currently selected context from the **framework-level** context module — the portal or host application's context, not your app's.
+
+Use this when your app hasn't configured its own context module but still needs to read what context the portal has selected.
+
+**Signature:**
+
+```ts
+function useFrameworkCurrentContext(): {
+  currentContext: ContextItem | undefined;
+  setCurrentContext: (entry?: ContextItem | string | null) => void;
+};
+```
+
+**Returns:** An object with `currentContext` (the portal's active context, or `undefined` if none is selected) and `setCurrentContext` to change it.
+
+**Example:**
+
+```tsx
+import { useFrameworkCurrentContext } from '@equinor/fusion-framework-react-app/context';
+
+const PortalContextInfo = () => {
+  const { currentContext } = useFrameworkCurrentContext();
+
+  if (!currentContext) return <p>No portal context selected</p>;
+
+  return <p>Portal context: {currentContext.title}</p>;
+};
+```
+
+## useFramework
+
+Returns the Fusion framework instance directly, giving access to all framework-level modules.
+
+**Signature:**
+
+```ts
+function useFramework(): Fusion;
+```
+
+## useCurrentUser
+
+Returns the currently authenticated user from the framework.
+
+**Signature:**
+
+```ts
+function useCurrentUser(): AccountInfo | undefined;
+```
+
+## useFrameworkHttpClient
+
+Returns an HTTP client from the framework-level HTTP module (not your app's configured clients). Useful for accessing portal-provided API clients.
+
+**Signature:**
+
+```ts
+function useFrameworkHttpClient(name: 'portal' | 'people'): IHttpClient;
+```
+
+**Throws** if no client is configured for the given key.
+
+## App-Scoped vs Framework-Scoped
+
+| Need                                          | Use                          | Sub-path      |
+| --------------------------------------------- | ---------------------------- | ------------- |
+| Context your app configured                   | `useCurrentContext`          | `/context`    |
+| Portal-level context (no app context module)  | `useFrameworkCurrentContext` | `/context`    |
+| App-specific HTTP client                      | `useHttpClient`              | `/http`       |
+| Portal-level HTTP client                      | `useFrameworkHttpClient`     | `/framework`  |

package/docs/help-center.md

@@ -0,0 +1,88 @@
+# Help Center
+
+Open the Fusion portal help sidesheet programmatically from your app using the `useHelpCenter` hook.
+
+**Import:**
+
+```ts
+import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';
+```
+
+> [!NOTE]
+> This hook dispatches a framework event to the portal shell. The help module must be enabled by the host — your app does not configure it directly.
+
+## useHelpCenter
+
+Returns an object with methods for opening specific pages of the portal help sidesheet.
+
+**Signature:**
+
+```ts
+useHelpCenter(): HelpCenter;
+```
+
+**Returned methods:**
+
+| Method                          | Description                                         |
+| ------------------------------- | --------------------------------------------------- |
+| `openHelp()`                    | Opens the help sidesheet on the home page           |
+| `openArticle(articleId: string)` | Opens a specific help article by its slug or ID    |
+| `openFaqs()`                    | Opens the FAQs page                                 |
+| `openSearch(search: string)`    | Opens the search page with a pre-filled query       |
+| `openGovernance()`              | Opens the governance tab                            |
+| `openReleaseNotes()`            | Opens the release notes page                        |
+
+## Examples
+
+### Open a Specific Article from a Button
+
+```tsx
+import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';
+
+const HelpButton = () => {
+  const { openArticle } = useHelpCenter();
+
+  return (
+    <button onClick={() => openArticle('getting-started')}>
+      How to get started
+    </button>
+  );
+};
+```
+
+### Open Help Home
+
+```tsx
+import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';
+
+const HelpLink = () => {
+  const { openHelp } = useHelpCenter();
+  return <button onClick={openHelp}>Help</button>;
+};
+```
+
+### Search Help Content
+
+```tsx
+import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';
+
+const SearchHelp = ({ query }: { query: string }) => {
+  const { openSearch } = useHelpCenter();
+  return <button onClick={() => openSearch(query)}>Search help</button>;
+};
+```
+
+## How It Works
+
+Each method dispatches a `@Portal::FusionHelp::open` framework event with a `page` discriminator. The portal shell listens for this event and opens the corresponding help sidesheet page. The event module must be available in the app's module scope — this is the default when running inside a Fusion portal.
+
+The known `page` values and their additional fields are:
+
+| `page` value      | Extra fields                  | Opened by          |
+| ----------------- | ----------------------------- | ------------------ |
+| `home`            | —                             | `openHelp()`       |
+| `article`         | `articleId: string`           | `openArticle(id)`  |
+| `faqs`            | —                             | `openFaqs()`       |
+| `search`          | `search: string`              | `openSearch(q)`    |
+| `governance`      | —                             | `openGovernance()` |
+| `release-notes`   | —                             | `openReleaseNotes()` |

package/docs/http.md

@@ -0,0 +1,118 @@
+# HTTP
+
+Make authenticated HTTP calls from your Fusion app using the framework-managed HTTP client.
+
+**Import:**
+
+```ts
+import { useHttpClient } from '@equinor/fusion-framework-react-app/http';
+```
+
+**Selectors sub-path:**
+
+```ts
+import { jsonSelector, blobSelector } from '@equinor/fusion-framework-react-app/http/selectors';
+```
+
+## Overview
+
+The `useHttpClient` hook provides access to named HTTP clients that are pre-configured with authentication, base URLs, and interceptors. Clients must be registered in the app configurator before use — the hook creates a memoised client instance by name.
+
+The `selectors` sub-path re-exports response selectors (`jsonSelector`, `blobSelector`, `createSseSelector`) from the HTTP module, providing typed helpers for parsing fetch responses.
+
+## Configure an HTTP Client
+
+Register a named client in your app's configuration callback:
+
+```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'],
+  });
+};
+```
+
+## useHttpClient
+
+Returns a configured `IHttpClient` instance by name. Throws if no client is registered for the given key.
+
+**Signature:**
+
+```ts
+function useHttpClient(name: string): IHttpClient;
+```
+
+| Parameter | Type     | Description                          |
+| --------- | -------- | ------------------------------------ |
+| `name`    | `string` | Named client key from configuration  |
+
+**Returns:** An `IHttpClient` instance with `fetch`, `json`, `blob`, and other request methods.
+
+### Fetch JSON Data
+
+```tsx
+import { useEffect, useState } from 'react';
+import { useHttpClient } from '@equinor/fusion-framework-react-app/http';
+
+type Item = { id: string; name: string };
+
+const ItemList = () => {
+  const client = useHttpClient('my-api');
+  const [items, setItems] = useState<Item[]>([]);
+
+  useEffect(() => {
+    client.json<Item[]>('/items')
+      .then(setItems);
+  }, [client]);
+
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### POST Data
+
+```tsx
+import { useCallback } from 'react';
+import { useHttpClient } from '@equinor/fusion-framework-react-app/http';
+
+const CreateItem = () => {
+  const client = useHttpClient('my-api');
+
+  const handleSubmit = useCallback(async (name: string) => {
+    await client.fetch('/items', {
+      method: 'POST',
+      body: JSON.stringify({ name }),
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }, [client]);
+
+  return <button onClick={() => handleSubmit('New item')}>Create</button>;
+};
+```
+
+## Response Selectors
+
+The `selectors` sub-path provides typed helpers for parsing HTTP responses:
+
+| Selector             | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `jsonSelector`       | Parses response as JSON; use a typed call (e.g. `client.json<T>(...)`) to get a typed result |
+| `blobSelector`       | Returns response as a `Blob`                   |
+| `createSseSelector`  | Creates a selector for Server-Sent Events streams |
+
+These are re-exported from `@equinor/fusion-framework-module-http/selectors`.
+
+## Prerequisites
+
+- HTTP clients must be configured in your app's configurator before calling `useHttpClient`
+- Authentication scopes are attached automatically based on the client configuration
+- For detailed HTTP module configuration, see the [`@equinor/fusion-framework-module-http` documentation](../../../modules/http/README.md)

package/docs/routing.md

@@ -0,0 +1,86 @@
+# Routing
+
+The `@equinor/fusion-framework-react-app/routing` entry point re-exports the full public API of
+`@equinor/fusion-framework-react-router` — including the `<Router>` component, the route builder
+DSL, all React Router hooks, and types — so you can import everything from a single package without
+adding `@equinor/fusion-framework-react-router` as a direct dependency.
+
+## Installation
+
+`@equinor/fusion-framework-react-router` is an **optional peer dependency**. Install it alongside the app package:
+
+```bash
+pnpm add @equinor/fusion-framework-react-router
+```
+
+## Usage
+
+```ts
+import { Router } from '@equinor/fusion-framework-react-app/routing';
+import { layout, index, route, prefix } from '@equinor/fusion-framework-react-app/routing';
+```
+
+Everything exported from `@equinor/fusion-framework-react-router` and its `/routes` DSL is
+available from this single entry point.
+
+## Enable navigation in your configurator
+
+The `<Router>` component reads `history` and `basename` from the Fusion navigation module.
+Enable it in your configurator before mounting:
+
+```ts
+import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
+import type { IAppConfigurator, AppEnv, Fusion } from '@equinor/fusion-framework-react-app';
+
+export const configure = (
+  configurator: IAppConfigurator,
+  args: { fusion: Fusion; env: AppEnv },
+) => {
+  enableNavigation(configurator, {
+    configure: (config) => {
+      config.setBasename(args.env.basename);
+    },
+  });
+};
+```
+
+## Define routes
+
+```ts
+// src/routes.ts
+import { layout, index, route, prefix } from '@equinor/fusion-framework-react-app/routing';
+
+export default layout('./Layout.tsx', [
+  index('./pages/HomePage.tsx'),
+  prefix('products', [
+    index('./pages/ProductsPage.tsx'),
+    route(':id', './pages/ProductPage.tsx'),
+  ]),
+]);
+```
+
+## Mount the Router
+
+```tsx
+// src/Router.tsx
+import { Router } from '@equinor/fusion-framework-react-app/routing';
+import routes from './routes';
+
+export default function AppRouter() {
+  return <Router routes={routes} />;
+}
+```
+
+## Use routing hooks
+
+All React Router hooks are re-exported from the same entry point:
+
+```tsx
+import { useNavigate, useParams, useLocation, Link } from '@equinor/fusion-framework-react-app/routing';
+```
+
+## See also
+
+- [Getting started](/modules/react/router/getting-started) — full setup walkthrough for the standalone router package
+- [Interop entry point](/modules/react/router/interop) — `MemoryRouter` and other react-router bridges for testing and mid-migration
+- [Migration guide](/modules/react/router/migration) — moving from a plain react-router setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "10.0.8",
+  "version": "12.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -60,6 +60,10 @@
     "./widget": {
       "types": "./dist/types/widget/index.d.ts",
       "import": "./dist/esm/widget/index.js"
+    },
+    "./routing": {
+      "types": "./dist/types/routing/index.d.ts",
+      "import": "./dist/esm/routing/index.js"
     }
   },
   "typesVersions": {
@@ -102,6 +106,9 @@
       ],
       "widget": [
         "dist/types/widget/index.d.ts"
+      ],
+      "routing": [
+        "dist/types/routing/index.d.ts"
       ]
     }
   },
@@ -117,14 +124,14 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-module": "6.0.0",
+    "@equinor/fusion-framework-app": "11.0.9",
     "@equinor/fusion-framework-module-app": "8.0.2",
-    "@equinor/fusion-framework-app": "11.0.6",
-    "@equinor/fusion-framework-module-http": "8.0.1",
+    "@equinor/fusion-framework-module": "6.1.0",
+    "@equinor/fusion-framework-module-http": "8.0.3",
     "@equinor/fusion-framework-react": "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.3"
+    "@equinor/fusion-framework-module-navigation": "7.0.4",
+    "@equinor/fusion-framework-react-module": "4.0.1",
+    "@equinor/fusion-framework-react-module-http": "11.0.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",
@@ -136,20 +143,22 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.0",
     "@equinor/fusion-framework-module-ag-grid": "36.0.1",
+    "@equinor/fusion-framework-module-analytics": "3.0.0",
     "@equinor/fusion-framework-module-event": "6.0.0",
-    "@equinor/fusion-framework-module-analytics": "2.0.5",
     "@equinor/fusion-framework-module-feature-flag": "2.0.1",
-    "@equinor/fusion-framework-module-msal": "8.0.5",
-    "@equinor/fusion-framework-react-module-bookmark": "6.0.0",
-    "@equinor/fusion-observable": "9.0.1",
-    "@equinor/fusion-framework-react-module-context": "7.0.0"
+    "@equinor/fusion-framework-module-msal": "10.0.0",
+    "@equinor/fusion-framework-react-router": "2.2.0",
+    "@equinor/fusion-framework-react-module-context": "7.0.1",
+    "@equinor/fusion-observable": "9.1.0",
+    "@equinor/fusion-framework-react-module-bookmark": "6.0.0"
   },
   "peerDependencies": {
     "@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.5"
+    "@equinor/fusion-framework-module-msal": "^10.0.0",
+    "@equinor/fusion-framework-react-router": "^2.2.0"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-react-module-ag-grid": {
@@ -178,6 +187,9 @@
     },
     "rxjs": {
       "optional": true
+    },
+    "@equinor/fusion-framework-react-router": {
+      "optional": true
     }
   },
   "scripts": {

package/src/apploader/README.md

@@ -1,5 +1,8 @@
 # `@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]

package/src/routing/index.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+// Explicit re-exports from /routes so the DSL `Route` class takes precedence
+// over the deprecated react-router `Route` component from the main entry.
+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/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '10.0.8';
+export const version = '12.0.0';

package/tsconfig.json

@@ -15,6 +15,9 @@
     {
       "path": "../framework"
     },
+    {
+      "path": "../router"
+    },
     {
       "path": "../../modules/analytics"
     },