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

package/dist/types/version.d.ts

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

package/docs/ag-grid.md

@@ -0,0 +1,70 @@
+# AG Grid
+
+Apply the Fusion-managed AG Grid theme to your `<AgGridReact>` instance.
+
+**Import:**
+
+```ts
+import { useTheme } from '@equinor/fusion-framework-react-ag-grid';
+```
+
+## Overview
+
+The `useTheme` hook returns the current AG Grid theme configured by the Fusion AG Grid module. Pass the returned theme to `<AgGridReact>` to ensure your grid uses the correct Fusion/EDS styling.
+
+> [!IMPORTANT]
+> The AG Grid module must be enabled in the app configurator before `useTheme` is available. If the module is not registered, the hook throws an error.
+
+## useTheme
+
+Returns the active AG Grid `Theme` object from the application-scoped AG Grid module.
+
+**Signature:**
+
+```ts
+function useTheme(): Theme;
+```
+
+**Returns:** A `Theme` object compatible with AG Grid's `theme` prop.
+
+**Throws** if the AG Grid module is not registered in the application.
+
+## Usage
+
+### Setup
+
+Enable the AG Grid module in your app's configurator:
+
+```ts
+import { enableAgGrid } from '@equinor/fusion-framework-module-ag-grid';
+
+export const configure = (configurator) => {
+  enableAgGrid(configurator);
+};
+```
+
+### Apply Theme to AgGridReact
+
+```tsx
+import { useTheme } from '@equinor/fusion-framework-react-ag-grid';
+import { AgGridReact } from '@equinor/fusion-framework-react-ag-grid';
+
+const MyGrid = ({ rowData, columnDefs }) => {
+  const theme = useTheme();
+
+  return (
+    <div style={{ height: 500 }}>
+      <AgGridReact
+        theme={theme}
+        rowData={rowData}
+        columnDefs={columnDefs}
+      />
+    </div>
+  );
+};
+```
+
+## Notes
+
+- The theme is sourced from `@equinor/fusion-framework-module-ag-grid` — see the module documentation for detailed AG Grid configuration options
+- The Fusion AG Grid theme follows EDS design tokens for consistent styling across apps

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

@@ -0,0 +1,139 @@
+# Settings
+
+Persist and read app-specific user settings using the Fusion settings service.
+
+**Import:**
+
+```ts
+import { useAppSetting, useAppSettings } from '@equinor/fusion-framework-react-app/settings';
+```
+
+## Overview
+
+App settings let users customise their experience (theme, layout, filters) with values persisted per-user by the Fusion platform. The `useAppSetting` hook manages a single setting, while `useAppSettings` provides access to all settings at once.
+
+## Type Your Settings
+
+Use module augmentation to get type-safe setting keys and values:
+
+```ts
+declare module '@equinor/fusion-framework-react-app/settings' {
+  interface AppSettings {
+    theme: 'default' | 'light' | 'dark';
+    mode: 'simple' | 'advanced';
+  }
+}
+```
+
+## useAppSetting
+
+Manages a single setting by key. Returns the current value and a setter function, similar to `useState`.
+
+**Signature:**
+
+```ts
+function useAppSetting<TSettings, TProp extends keyof TSettings>(
+  prop: TProp,
+  defaultValue?: TSettings[TProp],
+  hooks?: AppSettingsStatusHooks & {
+    onError?: (error: Error | null) => void;
+    onUpdated?: () => void;
+  },
+): [TSettings[TProp] | undefined, (update: TSettings[TProp] | ((current: TSettings[TProp] | undefined) => TSettings[TProp])) => void];
+```
+
+### Example
+
+```tsx
+import { useCallback } from 'react';
+import { useAppSetting } from '@equinor/fusion-framework-react-app/settings';
+
+const ThemeSwitcher = () => {
+  const [theme, setTheme] = useAppSetting('theme', 'default');
+  const [mode, setMode] = useAppSetting('mode', 'simple');
+
+  const toggleMode = useCallback(() => {
+    setMode((current) => (current === 'simple' ? 'advanced' : 'simple'));
+  }, [setMode]);
+
+  return (
+    <div>
+      {/* cast: e.target.value is string, but setTheme expects the union type */}
+      <select value={theme ?? 'default'} onChange={(e) => setTheme(e.target.value as AppSettings['theme'])}>
+        <option value="default">Default</option>
+        <option value="light">Light</option>
+        <option value="dark">Dark</option>
+      </select>
+      <button onClick={toggleMode}>Toggle mode ({mode})</button>
+    </div>
+  );
+};
+```
+
+## useAppSettings
+
+Returns all settings as a single object with a bulk setter. Use `useAppSetting` for individual settings when possible — `useAppSettings` triggers a re-render on _any_ setting change.
+
+**Signature:**
+
+```ts
+function useAppSettings<TSettings>(
+  defaultValue?: TSettings,
+  hooks?: AppSettingsStatusHooks & {
+    onError?: (error: Error | null) => void;
+    onUpdated?: () => void;
+  },
+): [TSettings, (update: TSettings | ((current: TSettings | undefined) => TSettings)) => void];
+```
+
+> [!WARNING]
+> **`setSettings` must include all settings, not just the ones you want to change.** Use a callback to merge with the current state:
+>
+> ```ts
+> setSettings((current) => ({ ...current, theme: 'dark' }));
+> ```
+
+### Example
+
+```tsx
+import { useCallback } from 'react';
+import { useAppSettings } from '@equinor/fusion-framework-react-app/settings';
+
+const SettingsPanel = () => {
+  const [settings, setSettings] = useAppSettings();
+
+  const updateTheme = useCallback(
+    (theme: AppSettings['theme']) => setSettings((current) => ({ ...current, theme })),
+    [setSettings],
+  );
+
+  return <ThemeSelector value={settings?.theme} onChange={updateTheme} />;
+};
+```
+
+## Status Hooks
+
+Both hooks accept optional status callbacks for loading, updating, and error states:
+
+```tsx
+const [loading, setLoading] = useState(false);
+const [updating, setUpdating] = useState(false);
+const [error, setError] = useState<Error | null>(null);
+
+const [theme, setTheme] = useAppSetting('theme', 'default', {
+  onLoading: setLoading,
+  onUpdating: setUpdating,
+  onError: setError,
+  onUpdated: useCallback(() => console.log('Saved'), []),
+});
+```
+
+> [!NOTE]
+> `onUpdating` and `onLoading` reflect the _global_ settings state, not individual settings. Disable update buttons while either is `true`.
+
+## Notes
+
+- Settings are async — there is a loading phase when the component mounts and an updating phase when values are saved
+- `useAppSetting` captures the `hooks` object once on mount (via `useState`); **the callbacks must be stable before the first render** — changes after mount are ignored
+- `useAppSettings` reads `hooks` on every render; **memoise callbacks** (e.g. with `useCallback`) to avoid unnecessary re-renders
+- Settings are persisted per-user per-app by the Fusion platform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "10.0.6",
+  "version": "10.0.8",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -117,14 +117,14 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-app": "11.0.4",
-    "@equinor/fusion-framework-module-app": "8.0.1",
     "@equinor/fusion-framework-module": "6.0.0",
-    "@equinor/fusion-framework-module-http": "8.0.0",
-    "@equinor/fusion-framework-module-navigation": "7.0.2",
+    "@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-react": "8.0.0",
     "@equinor/fusion-framework-react-module": "4.0.0",
     "@equinor/fusion-framework-react-module-http": "11.0.0",
-    "@equinor/fusion-framework-react": "8.0.0"
+    "@equinor/fusion-framework-module-navigation": "7.0.3"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",
@@ -133,23 +133,23 @@
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "rxjs": "^7.8.1",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.0",
-    "@equinor/fusion-framework-module-ag-grid": "36.0.0",
-    "@equinor/fusion-framework-module-analytics": "2.0.3",
+    "@equinor/fusion-framework-module-ag-grid": "36.0.1",
     "@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.3",
+    "@equinor/fusion-framework-module-msal": "8.0.5",
     "@equinor/fusion-framework-react-module-bookmark": "6.0.0",
-    "@equinor/fusion-framework-react-module-context": "7.0.0",
-    "@equinor/fusion-observable": "9.0.1"
+    "@equinor/fusion-observable": "9.0.1",
+    "@equinor/fusion-framework-react-module-context": "7.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.3"
+    "@equinor/fusion-framework-module-msal": "^8.0.5"
   },
   "peerDependenciesMeta": {
     "@equinor/fusion-framework-react-module-ag-grid": {

package/src/version.ts

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