@equinor/fusion-framework-react-app 5.3.1 → 5.4.0

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

@@ -0,0 +1,3 @@
+export { useAppSetting } from './useAppSetting';
+export { useAppSettings } from './useAppSettings';
+export type { AppSettings } from '@equinor/fusion-framework-module-app';

package/dist/types/settings/useAppSetting.d.ts

@@ -0,0 +1,42 @@
+import { type AppSettingsStatusHooks } from './useAppSettingsStatus';
+import type { AppSettings } from '@equinor/fusion-framework-module-app';
+type UpdateSettingFunction<T, O = T> = (currentSetting: T | undefined) => O;
+/**
+ * Custom hook to manage application settings.
+ *
+ * @template TSettings - The type of the settings object. Defaults to `AppSettings`.
+ * @template TProp - The type of the property key in the settings object. Defaults to `keyof TSettings`.
+ *
+ * @param {TProp} prop - The property key in the settings object to manage.
+ * @param {TSettings[TProp]} [defaultValue] - The default value for the setting.
+ * @param hooks - Optional hooks to handle the status changes and errors.
+ *
+ * @returns {Array} An array containing:
+ * - `setting`: The current setting value or undefined.
+ * - `setSetting`: A function to update the setting.
+ *
+ * @example
+ * const { setting, setSetting } = useAppSetting('theme');
+ *
+ * @example
+ * // with default value
+ * const { setting, setSetting } = useAppSetting('theme', 'dark');
+ *
+ * @example
+ * // with hooks
+ * const [isLoading, setIsLoading] = useState(false);
+ * const [isUpdating, setIsUpdating] = useState(false);
+ * const [error, setError] = useState<Error | null>(null);
+ *
+ * const { setting, setSetting } = useAppSetting('theme', 'dark', {
+ *    onLoading: setIsLoading,
+ *    onUpdating: setIsUpdating,
+ *    onError: setError,
+ *    onUpdated: useCallback(() => console.log('Settings updated'), [])
+ * });
+ */
+export declare const useAppSetting: <TSettings extends Record<string, unknown> = AppSettings, TProp extends keyof TSettings = keyof TSettings>(prop: TProp, defaultValue?: TSettings[TProp], hooks?: AppSettingsStatusHooks & {
+    onError?: (error: Error | null) => void;
+    onUpdated?: () => void;
+}) => [TSettings[TProp] | undefined, (update: TSettings[TProp] | UpdateSettingFunction<TSettings[TProp]>) => void];
+export default useAppSetting;

package/dist/types/settings/useAppSettings.d.ts

@@ -0,0 +1,44 @@
+import { type AppSettings } from '@equinor/fusion-framework-module-app';
+import { type AppSettingsStatusHooks } from './useAppSettingsStatus';
+type UpdateSettingsFunction<T, O = T> = (currentSettings: T | undefined) => O;
+/**
+ * Custom hook to manage application settings.
+ *
+ * @template TSettings - The type of the settings object, extending Record<string, any>. Defaults to AppSettings.
+ *
+ * @param {TSettings} [defaultValue] - The default value for the settings.
+ * @param hooks - Optional hooks to handle the status changes and errors.
+ *
+ * @note
+ * `defaultValue` will only be used on the first render.
+ * `hooks`must be memoized to avoid unnecessary re-renders.
+ *
+ * @returns {Array} An array containing:
+ * - `settings`: The current settings object.
+ * - `setSettings`: A function to update the settings.
+ *
+ * @example
+ * const [settings, setSettings] = useAppSettings();
+ *
+ * @example
+ * const [settings, setSettings] = useAppSettings({ theme: 'dark' });
+ *
+ * @example
+ * const [isLoading, setIsLoading] = useState(false);
+ * const [isUpdating, setIsUpdating] = useState(false);
+ * const [error, setError] = useState<Error | null>(null);
+ *
+ * const onUpdated = useCallback(() => console.log('Settings updated'), []);
+ *
+ * const [settings, setSettings] = useAppSettings({ theme: 'dark' }, {
+ *  onLoading: setIsLoading,
+ *  onUpdating: setIsUpdating,
+ *  onError: setError,
+ *  onUpdated,
+ * });
+ */
+export declare const useAppSettings: <TSettings extends Record<string, unknown> = AppSettings>(defaultValue?: TSettings, hooks?: AppSettingsStatusHooks & {
+    onError?: (error: Error | null) => void;
+    onUpdated?: () => void;
+}) => [TSettings, (settings: TSettings | UpdateSettingsFunction<TSettings>) => void];
+export default useAppSettings;

package/dist/types/settings/useAppSettingsStatus.d.ts

@@ -0,0 +1,23 @@
+import type { IApp } from '@equinor/fusion-framework-module-app';
+export type AppSettingsStatusHooks = {
+    onLoading?: (isLoading: boolean) => void;
+    onUpdating?: (isUpdating: boolean) => void;
+};
+/**
+ * Custom hook to handle app settings status updates.
+ *
+ * @param {IApp | null} app - The app instance to monitor settings status.
+ * @param {AppSettingsStatusHooks} [hooks] - Optional hooks to handle loading and updating status.
+ * @param {function} [hooks.onLoading] - Callback function to handle loading status.
+ * @param {function} [hooks.onUpdating] - Callback function to handle updating status.
+ *
+ * @returns {void}
+ *
+ * @example
+ * const hooks = useMemo(() => ({
+ *   onLoading: (isLoading) => console.log('Loading:', isLoading),
+ *   onUpdating: (isUpdating) => console.log('Updating:', isUpdating),
+ * }, []);
+ * useAppSettingsStatus(app, hooks);
+ */
+export declare const useAppSettingsStatus: (app: IApp | null, hooks?: AppSettingsStatusHooks) => void;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.3.1";
+export declare const version = "5.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -37,6 +37,10 @@
       "types": "./dist/types/navigation/index.d.ts",
       "import": "./dist/esm/navigation/index.js"
     },
+    "./settings": {
+      "types": "./dist/types/settings/index.d.ts",
+      "import": "./dist/esm/settings/index.js"
+    },
     "./widget": {
       "types": "./dist/types/widget/index.d.ts",
       "import": "./dist/esm/widget/index.js"
@@ -65,6 +69,9 @@
       "navigation": [
         "dist/types/navigation/index.d.ts"
       ],
+      "settings": [
+        "dist/types/settings/index.d.ts"
+      ],
       "widget": [
         "dist/types/widget/index.d.ts"
       ]
@@ -82,13 +89,13 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-app": "^9.1.14",
-    "@equinor/fusion-framework-module-navigation": "^4.0.7",
+    "@equinor/fusion-framework-app": "^9.1.15",
     "@equinor/fusion-framework-module": "^4.3.5",
+    "@equinor/fusion-framework-module-app": "^6.1.0",
+    "@equinor/fusion-framework-module-navigation": "^4.0.7",
     "@equinor/fusion-framework-react": "^7.3.3",
-    "@equinor/fusion-framework-react-module": "^3.1.6",
-    "@equinor/fusion-framework-module-app": "^6.0.3",
-    "@equinor/fusion-framework-react-module-http": "^8.0.0"
+    "@equinor/fusion-framework-react-module-http": "^8.0.0",
+    "@equinor/fusion-framework-react-module": "^3.1.6"
   },
   "devDependencies": {
     "@types/react": "^18.2.50",
@@ -97,13 +104,13 @@
     "react-dom": "^18.2.0",
     "rxjs": "^7.8.1",
     "typescript": "^5.5.4",
-    "@equinor/fusion-framework-module-event": "^4.2.4",
     "@equinor/fusion-framework-module-feature-flag": "^1.1.11",
+    "@equinor/fusion-framework-module-event": "^4.2.4",
     "@equinor/fusion-framework-module-msal": "^3.1.5",
     "@equinor/fusion-framework-react-module-bookmark": "^2.2.2",
-    "@equinor/fusion-framework-react-module-context": "^6.2.15",
     "@equinor/fusion-framework-react-widget": "^1.1.21",
-    "@equinor/fusion-observable": "^8.4.3"
+    "@equinor/fusion-observable": "^8.4.3",
+    "@equinor/fusion-framework-react-module-context": "^6.2.15"
   },
   "peerDependencies": {
     "@types/react": "^17.0.0 || ^18.0.0",

package/src/settings/README.md

@@ -0,0 +1,123 @@
+## Portal Settings
+
+> TBD
+
+## App Settings
+
+App settings are a way to store and retrieve settings that are shared across the app. The settings are stored in the configured service of the app module.
+
+```ts
+declare module '@equinor/fusion-framework-react-app/settings' {
+  interface AppSettings {
+    theme: 'default' | 'light' | 'dark';
+    mode: 'simple' | 'advanced';
+  }
+}
+useAppSetting('theme', 'default');
+
+// Explicit type the setting
+useAppSetting<{notDefined: string}>('notDefined', 'not registered');
+```
+
+### Example
+
+```tsx
+const MyApp = () => {
+  const [ theme, setTheme ] = useAppSetting('theme', 'default');
+  const [ mode, setMode ] = useAppSetting('mode', 'simple');
+
+  // using the setter as a callback
+  const toggleMode = useCallback(() => {
+    setMode(mode => mode === 'simple' ? 'advanced' : 'simple')
+  }, [setMode]);
+
+  return (
+    <MyThemeProvider theme={theme} onChange={setTheme}>
+      <Button onClick={toggleMode}>Toggle mode</Button>
+      {mode === 'simple' ? <SimpleView /> : <AdvancedView />}
+    </MyThemeProvider>
+  );
+}
+```
+
+### Using all settings
+
+> [!WARNING]
+> **Using the `setSettings` must include all settings, not just the ones you want to change.**
+> prefer using `setSettings` with a callback function.
+
+> [!IMPORTANT]
+> This is not recommended for large apps, as it will cause re-renders on every setting change.
+
+```tsx
+const MyApp = () => {
+  const [ settings, setSettings ] = useAppSettings();
+
+  const updateTheme = useCallback(
+    (theme: AppSettings['theme']) => setSettings(settings => ({...settings, theme})),
+    [updateSettings]
+  );
+      
+  return (
+    <MyThemeProvider theme={settings.theme} onChange={updateTheme}>
+      {settings.mode === 'simple' ? <SimpleView /> : <AdvancedView />}
+    </MyThemeProvider>
+  );
+}
+```
+
+### Using hook callbacks
+
+The `useAppSettings` and `useAppSetting` hooks can take callbacks for loading, updating, updated and error handling.
+
+> [!NOTE]
+> These callbacks are optional and can be used to show loading spinners, error dialogs or other UI elements.
+>
+> We have chosen to use callbacks as parameters to the hooks, instead of returning them, to avoid unnecessary re-renders.
+
+> [!NOTE]
+> `onUpdating` and `onLoading` refers to the global state of the settings, not the individual settings. This means that if you have multiple settings that are being updated, the `onUpdating` and `onLoading` will be true until all settings are updated.
+> 
+> Good practice is to disable UI elements that can trigger settings updates when `onUpdating` or `onLoading` is true.
+
+
+> [!IMPORTANT]
+> Hooks must be memoized to avoid re-renders on every render. Provided callbacks are not internally memoized, to allow consumers to control implementation of these callbacks.
+
+```tsx
+
+// state and callback for loading settings
+const [ loading, setLoading ] = useState(false);
+
+// state and callback for updating settings
+const [ updating, setUpdating ] = useState(false);
+
+// state and callback for error handling
+const [ error, setError ] = useState<Error | null>(null);
+
+// callback for when settings are updated
+const onUpdated = useCallback(() => {
+  showSnackbar('Settings updated');
+}, [showSnackbar]);
+
+const [ settings, setSettings ] = useAppSettings(defaultSettings, {
+  onLoading: setLoading,
+  onUpdating: setUpdating,
+  onError: setError,
+});
+
+const updateSettings = useCallback(() => {
+  setSettings(/* new settings */);
+}, [setSettings, onUpdated]);
+
+return (
+  <MyThemeProvider theme={settings.theme}>
+    {loading && <Loading />}
+    {updating && <Updating />}
+    {error && <ErrorDialog error={error} />}
+    <Button onClick={updateSettings} disabled={loading||updating}>
+      Update settings
+    </Button>
+  </MyThemeProvider>
+);
+```

package/src/settings/index.ts

@@ -0,0 +1,4 @@
+export { useAppSetting } from './useAppSetting';
+export { useAppSettings } from './useAppSettings';
+
+export type { AppSettings } from '@equinor/fusion-framework-module-app';

package/src/settings/useAppSetting.ts

@@ -0,0 +1,112 @@
+import { useCallback, useLayoutEffect, useMemo, useState } from 'react';
+import { BehaviorSubject, map } from 'rxjs';
+
+import { useCurrentApp } from '@equinor/fusion-framework-react/app';
+
+import { useAppSettingsStatus, type AppSettingsStatusHooks } from './useAppSettingsStatus';
+
+import type { AppSettings } from '@equinor/fusion-framework-module-app';
+import { useObservableState } from '@equinor/fusion-observable/react';
+
+type UpdateSettingFunction<T, O = T> = (currentSetting: T | undefined) => O;
+
+/**
+ * Custom hook to manage application settings.
+ *
+ * @template TSettings - The type of the settings object. Defaults to `AppSettings`.
+ * @template TProp - The type of the property key in the settings object. Defaults to `keyof TSettings`.
+ *
+ * @param {TProp} prop - The property key in the settings object to manage.
+ * @param {TSettings[TProp]} [defaultValue] - The default value for the setting.
+ * @param hooks - Optional hooks to handle the status changes and errors.
+ *
+ * @returns {Array} An array containing:
+ * - `setting`: The current setting value or undefined.
+ * - `setSetting`: A function to update the setting.
+ *
+ * @example
+ * const { setting, setSetting } = useAppSetting('theme');
+ *
+ * @example
+ * // with default value
+ * const { setting, setSetting } = useAppSetting('theme', 'dark');
+ *
+ * @example
+ * // with hooks
+ * const [isLoading, setIsLoading] = useState(false);
+ * const [isUpdating, setIsUpdating] = useState(false);
+ * const [error, setError] = useState<Error | null>(null);
+ *
+ * const { setting, setSetting } = useAppSetting('theme', 'dark', {
+ *    onLoading: setIsLoading,
+ *    onUpdating: setIsUpdating,
+ *    onError: setError,
+ *    onUpdated: useCallback(() => console.log('Settings updated'), [])
+ * });
+ */
+export const useAppSetting = <
+    TSettings extends Record<string, unknown> = AppSettings,
+    TProp extends keyof TSettings = keyof TSettings,
+>(
+    prop: TProp,
+    defaultValue?: TSettings[TProp],
+    hooks?: AppSettingsStatusHooks & {
+        onError?: (error: Error | null) => void;
+        onUpdated?: () => void;
+    },
+): [
+    TSettings[TProp] | undefined,
+    (update: TSettings[TProp] | UpdateSettingFunction<TSettings[TProp]>) => void,
+] => {
+    const [{ onError, onUpdated, onLoading, onUpdating }] = useState(() => hooks ?? {});
+
+    const { currentApp = null } = useCurrentApp();
+
+    // create a subject to manage the setting value
+    const subject = useMemo(() => {
+        return new BehaviorSubject<TSettings[TProp] | undefined>(defaultValue);
+        // Only create a new subject when the current app changes
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentApp]);
+
+    useLayoutEffect(() => {
+        const sub = currentApp?.settings$
+            .pipe(map((settings) => (settings as TSettings)[prop]))
+            .subscribe(subject);
+        return () => sub?.unsubscribe();
+    }, [currentApp, subject, prop]);
+
+    // subscribe to the setting value
+    const { value: setting } = useObservableState(subject);
+
+    // update function
+    const setSetting = useCallback(
+        (update: TSettings[TProp] | UpdateSettingFunction<TSettings[TProp]>) => {
+            if (!currentApp) {
+                return onError?.(new Error('App is not available'));
+            }
+
+            // resolve setting value with the provided value or function
+            const value =
+                typeof update === 'function'
+                    ? (update as UpdateSettingFunction<TSettings[TProp]>)(subject.value)
+                    : update;
+
+            currentApp.updateSetting<TSettings, TProp>(prop, value).subscribe({
+                error: onError,
+                complete: onUpdated,
+            });
+        },
+        [currentApp, subject, prop, onError, onUpdated],
+    );
+
+    // status hooks
+    useAppSettingsStatus(currentApp, {
+        onLoading,
+        onUpdating,
+    });
+
+    return [setting, setSetting];
+};
+
+export default useAppSetting;

package/src/settings/useAppSettings.ts

@@ -0,0 +1,99 @@
+import { useCallback, useLayoutEffect, useMemo } from 'react';
+import { BehaviorSubject, Observable } from 'rxjs';
+
+import { type AppSettings } from '@equinor/fusion-framework-module-app';
+
+import { useCurrentApp } from '@equinor/fusion-framework-react/app';
+import { useObservableState } from '@equinor/fusion-observable/react';
+
+import { useAppSettingsStatus, type AppSettingsStatusHooks } from './useAppSettingsStatus';
+
+type UpdateSettingsFunction<T, O = T> = (currentSettings: T | undefined) => O;
+
+/**
+ * Custom hook to manage application settings.
+ *
+ * @template TSettings - The type of the settings object, extending Record<string, any>. Defaults to AppSettings.
+ *
+ * @param {TSettings} [defaultValue] - The default value for the settings.
+ * @param hooks - Optional hooks to handle the status changes and errors.
+ *
+ * @note
+ * `defaultValue` will only be used on the first render.
+ * `hooks`must be memoized to avoid unnecessary re-renders.
+ *
+ * @returns {Array} An array containing:
+ * - `settings`: The current settings object.
+ * - `setSettings`: A function to update the settings.
+ *
+ * @example
+ * const [settings, setSettings] = useAppSettings();
+ *
+ * @example
+ * const [settings, setSettings] = useAppSettings({ theme: 'dark' });
+ *
+ * @example
+ * const [isLoading, setIsLoading] = useState(false);
+ * const [isUpdating, setIsUpdating] = useState(false);
+ * const [error, setError] = useState<Error | null>(null);
+ *
+ * const onUpdated = useCallback(() => console.log('Settings updated'), []);
+ *
+ * const [settings, setSettings] = useAppSettings({ theme: 'dark' }, {
+ *  onLoading: setIsLoading,
+ *  onUpdating: setIsUpdating,
+ *  onError: setError,
+ *  onUpdated,
+ * });
+ */
+export const useAppSettings = <TSettings extends Record<string, unknown> = AppSettings>(
+    defaultValue?: TSettings,
+    hooks?: AppSettingsStatusHooks & {
+        onError?: (error: Error | null) => void;
+        onUpdated?: () => void;
+    },
+): [TSettings, (settings: TSettings | UpdateSettingsFunction<TSettings>) => void] => {
+    const { onError, onUpdated, onLoading, onUpdating } = hooks ?? {};
+    const { currentApp = null } = useCurrentApp();
+
+    const subject = useMemo(() => {
+        return new BehaviorSubject<TSettings>(defaultValue ?? ({} as TSettings));
+        // Only create a new subject when the current app changes
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentApp]);
+
+    // connect the subject to the current app settings stream
+    useLayoutEffect(() => {
+        const sub = (currentApp?.settings$ as Observable<TSettings>).subscribe(subject);
+        return () => sub?.unsubscribe();
+    }, [currentApp, subject]);
+
+    // subscribe to the subject to get the latest settings
+    const { value: settings } = useObservableState(subject, { initial: defaultValue });
+
+    const setSettings = useCallback(
+        (update: TSettings | UpdateSettingsFunction<TSettings>) => {
+            if (!currentApp) {
+                return onError?.(new Error('App is not available'));
+            }
+
+            // resolve settings with the provided value or function
+            const settings = typeof update === 'function' ? update(subject.value) : update;
+
+            currentApp.updateSettings(settings).subscribe({
+                next: () => {
+                    onUpdated?.();
+                    onError?.(null);
+                },
+                error: onError,
+            });
+        },
+        [currentApp, subject, onError, onUpdated],
+    );
+
+    useAppSettingsStatus(currentApp, { onLoading, onUpdating });
+
+    return [settings, setSettings];
+};
+
+export default useAppSettings;

package/src/settings/useAppSettingsStatus.ts

@@ -0,0 +1,48 @@
+import { useLayoutEffect } from 'react';
+import { map } from 'rxjs';
+
+import type { IApp } from '@equinor/fusion-framework-module-app';
+
+export type AppSettingsStatusHooks = {
+    onLoading?: (isLoading: boolean) => void;
+    onUpdating?: (isUpdating: boolean) => void;
+};
+
+/**
+ * Custom hook to handle app settings status updates.
+ *
+ * @param {IApp | null} app - The app instance to monitor settings status.
+ * @param {AppSettingsStatusHooks} [hooks] - Optional hooks to handle loading and updating status.
+ * @param {function} [hooks.onLoading] - Callback function to handle loading status.
+ * @param {function} [hooks.onUpdating] - Callback function to handle updating status.
+ *
+ * @returns {void}
+ *
+ * @example
+ * const hooks = useMemo(() => ({
+ *   onLoading: (isLoading) => console.log('Loading:', isLoading),
+ *   onUpdating: (isUpdating) => console.log('Updating:', isUpdating),
+ * }, []);
+ * useAppSettingsStatus(app, hooks);
+ */
+export const useAppSettingsStatus = (app: IApp | null, hooks?: AppSettingsStatusHooks) => {
+    const { onLoading, onUpdating } = hooks ?? {};
+
+    useLayoutEffect(() => {
+        if (app && onLoading) {
+            const subscription = app.status$
+                .pipe(map((status) => status.has('fetch_settings')))
+                .subscribe(onLoading);
+            return () => subscription.unsubscribe();
+        }
+    }, [app, onLoading]);
+
+    useLayoutEffect(() => {
+        if (app && onUpdating) {
+            const subscription = app.status$
+                .pipe(map((status) => status.has('update_settings')))
+                .subscribe(onUpdating);
+            return () => subscription.unsubscribe();
+        }
+    }, [app, onUpdating]);
+};

package/src/version.ts

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