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

package/docs/feature-flag.md

@@ -0,0 +1,119 @@
+# Feature Flag
+
+Add, read, and toggle feature flags in your Fusion app.
+
+> [!NOTE]
+> Requires `@equinor/fusion-framework-module-feature-flag` to be installed as a dependency. The `enableFeatureFlag` helper and `useFeature` hook will not work without it.
+
+**Import:**
+
+```ts
+import { enableFeatureFlag, useFeature } from '@equinor/fusion-framework-react-app/feature-flag';
+```
+
+## Overview
+
+Feature flags let you ship code behind a toggle — enabling gradual rollouts, A/B testing, or developer-only features. The `enableFeatureFlag` helper registers flags in your app's configurator, and the `useFeature` hook reads and toggles them at runtime. Framework-level flags are also visible through this hook.
+
+## Configure Feature Flags
+
+Register flags in your app's configuration callback. Each flag has a `key`, a `title`, and optionally `allowUrl` to enable URL-driven overrides (e.g. `?my-flag=true`):
+
+```ts
+import { enableFeatureFlag } from '@equinor/fusion-framework-react-app/feature-flag';
+
+export const configure = (configurator) => {
+  enableFeatureFlag(configurator, [
+    {
+      key: 'dark-mode',
+      title: 'Dark Mode',
+      enabled: false,
+    },
+    {
+      key: 'beta-dashboard',
+      title: 'Beta Dashboard',
+      enabled: false,
+      allowUrl: true, // can be toggled via URL query parameter — requires the navigation module to be registered
+    },
+  ]);
+};
+```
+
+## useFeature
+
+Reads a single feature flag by key and provides a toggle callback. Merges feature flags from both the framework scope and the application scope, so framework-level flags are visible alongside app-specific ones.
+
+**Signature:**
+
+```ts
+function useFeature<T = unknown>(key: string): {
+  feature?: IFeatureFlag<T>;
+  toggleFeature: (enabled?: boolean) => void;
+  error?: unknown;
+};
+```
+
+**Returns:**
+
+| Property        | Type                        | Description                                           |
+| --------------- | --------------------------- | ----------------------------------------------------- |
+| `feature`       | `IFeatureFlag<T> \| undefined` | The resolved feature flag, or `undefined` if not found |
+| `toggleFeature` | `(enabled?: boolean) => void`  | Toggle the flag; pass `true`/`false` to set explicitly, or omit to invert |
+| `error`         | `unknown`                   | Any error from the feature-flag observable             |
+
+### End-to-End Example
+
+```tsx
+import { useFeature } from '@equinor/fusion-framework-react-app/feature-flag';
+
+const Dashboard = () => {
+  const { feature, toggleFeature } = useFeature('beta-dashboard');
+
+  return (
+    <div>
+      <button onClick={() => toggleFeature()}>
+        {feature?.enabled ? 'Disable' : 'Enable'} beta dashboard
+      </button>
+      {feature?.enabled && <BetaDashboard />}
+    </div>
+  );
+};
+```
+
+### Read-Only Flag Check
+
+```tsx
+import { useFeature } from '@equinor/fusion-framework-react-app/feature-flag';
+
+const FeatureGate = ({ flagKey, children }: { flagKey: string; children: React.ReactNode }) => {
+  const { feature } = useFeature(flagKey);
+  if (!feature?.enabled) return null;
+  return <>{children}</>;
+};
+```
+
+## Advanced Configuration
+
+For advanced scenarios, pass a builder callback instead of an array. The builder exposes `addPlugin` — use it to register feature sources such as the local-storage or URL plugin directly:
+
+```ts
+import { enableFeatureFlag } from '@equinor/fusion-framework-react-app/feature-flag';
+import {
+  createLocalStoragePlugin,
+  createUrlPlugin,
+} from '@equinor/fusion-framework-module-feature-flag/plugins';
+
+export const configure = (configurator) => {
+  enableFeatureFlag(configurator, (builder) => {
+    builder.addPlugin(createLocalStoragePlugin([{ key: 'dark-mode', title: 'Dark Mode', enabled: false }]));
+    // only add URL plugin if your app also registers the navigation module
+    builder.addPlugin(createUrlPlugin([{ key: 'beta-dashboard', title: 'Beta Dashboard', enabled: false }]));
+  });
+};
+```
+
+## Notes
+
+- Framework-level flags are merged with app-level flags — if both define the same key, the app-level flag takes precedence
+- **Array overload**: local-storage persistence and URL override support are wired automatically. Flags with `allowUrl: true` are passed to the URL plugin (requires the `navigation` module)
+- **Builder-callback overload**: no plugins are added automatically — add `createLocalStoragePlugin` and/or `createUrlPlugin` explicitly if you need persistence or URL overrides

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/navigation.md

@@ -0,0 +1,80 @@
+# Navigation
+
+Set up client-side routing in your Fusion app using the framework-managed navigation module.
+
+**Import:**
+
+```ts
+import { useRouter, useNavigationModule } from '@equinor/fusion-framework-react-app/navigation';
+```
+
+## Overview
+
+The navigation module wraps React Router with Fusion's base path handling, ensuring your app's routes work correctly under the portal's URL structure (e.g. `/apps/my-app/...`). Use `useRouter` to create a router instance and pass it to `<RouterProvider>`.
+
+> [!IMPORTANT]
+> Do not use `createBrowserRouter` from React Router directly — it bypasses the Fusion base path and will cause routing conflicts inside the portal.
+
+## Enable Navigation
+
+The navigation module must be enabled in your app's configurator. Always pass the basename so routes resolve correctly under the portal's URL prefix:
+
+```ts
+import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
+
+export const configure = (configurator) => {
+  // Pass the basename that matches where the portal mounts your app.
+  // In a Fusion portal this is typically the app's appKey path, e.g. '/apps/my-app'.
+  enableNavigation(configurator, '/apps/my-app');
+};
+```
+
+Without a basename, routes will not be prefixed and will conflict with the portal's URL structure.
+
+## useRouter
+
+Creates a router instance from route definitions. The returned router is compatible with `<Router>` from `@equinor/fusion-framework-react-router`.
+
+> [!WARNING]
+> `useRouter` calls `INavigationProvider.createRouter()`, which is **deprecated** in the navigation module and emits a telemetry warning at runtime. For new apps, prefer `<Router>` from `@equinor/fusion-framework-react-router` directly — it handles the basename and Fusion context automatically without requiring `useRouter`.
+
+> [!CAUTION]
+> **Routes must be stable or memoised.** If you pass a new array reference on every render, the router will be recreated each time, resetting navigation state. Define routes outside the component or use `useMemo`.
+
+### Minimal Routing Example
+
+```tsx
+import { useRouter } from '@equinor/fusion-framework-react-app/navigation';
+import { Router } from '@equinor/fusion-framework-react-router';
+
+const Home = () => <h1>Home</h1>;
+const Settings = () => <h1>Settings</h1>;
+
+// Define routes outside the component to keep them stable
+const routes = [
+  { path: '/', element: <Home /> },
+  { path: '/settings', element: <Settings /> },
+];
+
+const App = () => {
+  const router = useRouter(routes);
+  return <Router router={router} />;
+};
+```
+
+## useNavigationModule
+
+Returns the navigation module provider instance directly. Use this for advanced scenarios where you need access to the full provider API (e.g. programmatic navigation outside of React Router's hooks).
+
+**Signature:**
+
+```ts
+function useNavigationModule(): INavigationProvider;
+```
+
+**Throws** if the navigation module has not been enabled for the application.
+
+## Prerequisites
+
+- The navigation module must be enabled in your app's configurator via `enableNavigation`
+- Do not mix `useRouter` with direct `createBrowserRouter` calls — use one approach consistently

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