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

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.7",
+  "version": "11.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-app": "11.0.5",
+    "@equinor/fusion-framework-app": "11.0.7",
+    "@equinor/fusion-framework-module": "6.1.0",
     "@equinor/fusion-framework-module-app": "8.0.2",
-    "@equinor/fusion-framework-module": "6.0.0",
-    "@equinor/fusion-framework-module-http": "8.0.1",
+    "@equinor/fusion-framework-module-navigation": "7.0.4",
+    "@equinor/fusion-framework-module-http": "8.0.2",
     "@equinor/fusion-framework-react": "8.0.0",
     "@equinor/fusion-framework-react-module-http": "11.0.0",
-    "@equinor/fusion-framework-react-module": "4.0.0",
-    "@equinor/fusion-framework-module-navigation": "7.0.3"
+    "@equinor/fusion-framework-react-module": "4.0.1"
   },
   "devDependencies": {
     "@types/react": "^19.2.7",
@@ -135,21 +142,23 @@
     "rxjs": "^7.8.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.0",
-    "@equinor/fusion-framework-module-analytics": "2.0.4",
+    "@equinor/fusion-framework-module-analytics": "2.0.6",
+    "@equinor/fusion-framework-module-ag-grid": "36.0.1",
     "@equinor/fusion-framework-module-event": "6.0.0",
-    "@equinor/fusion-framework-module-ag-grid": "36.0.0",
-    "@equinor/fusion-framework-module-msal": "8.0.4",
-    "@equinor/fusion-framework-react-module-context": "7.0.0",
     "@equinor/fusion-framework-module-feature-flag": "2.0.1",
     "@equinor/fusion-framework-react-module-bookmark": "6.0.0",
-    "@equinor/fusion-observable": "9.0.1"
+    "@equinor/fusion-framework-react-module-context": "7.0.1",
+    "@equinor/fusion-framework-module-msal": "9.0.0",
+    "@equinor/fusion-framework-react-router": "2.2.0",
+    "@equinor/fusion-observable": "9.0.2"
   },
   "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.4"
+    "@equinor/fusion-framework-module-msal": "^9.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.7';
+export const version = '11.0.0';