@equinor/fusion-framework-react-app 14.0.3 → 14.1.1

package/src/settings/README.md

@@ -1,123 +0,0 @@
-## 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

@@ -1,12 +0,0 @@
-/**
- * Settings sub-path entry-point.
- *
- * Provides hooks for reading and updating per-application user settings
- * that are persisted by the Fusion platform.
- *
- * @packageDocumentation
- */
-export { useAppSetting } from './useAppSetting';
-export { useAppSettings } from './useAppSettings';
-
-export type { AppSettings } from '@equinor/fusion-framework-module-app';

package/src/settings/useAppSetting.ts

@@ -1,113 +0,0 @@
-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
-  // biome-ignore lint/correctness/useExhaustiveDependencies: new subject when app changes
-  const subject = useMemo(() => {
-    return new BehaviorSubject<TSettings[TProp] | undefined>(defaultValue);
-  }, [currentApp]);
-
-  useLayoutEffect(() => {
-    // Narrow the settings stream down to just this specific setting's value
-    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]>) => {
-      // Cannot persist a setting update without a current app to write it to
-      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

@@ -1,103 +0,0 @@
-import { useCallback, useLayoutEffect, useMemo } from 'react';
-import { BehaviorSubject, type 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.
- *
- * @remarks
- * `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();
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: create new subject when app changes
-  const subject = useMemo(() => {
-    return new BehaviorSubject<TSettings>(defaultValue ?? ({} as TSettings));
-  }, [currentApp]);
-
-  // connect the subject to the current app settings stream
-  useLayoutEffect(() => {
-    // Nothing to subscribe to until an app is resolved
-    if (!currentApp) {
-      return;
-    }
-    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>) => {
-      // Cannot persist settings updates without a current app to write them to
-      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

@@ -1,52 +0,0 @@
-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(() => {
-    // Only subscribe once both an app and an onLoading callback are available
-    if (app && onLoading) {
-      // Derive a boolean loading flag from whether 'fetch_settings' is an active status
-      const subscription = app.status$
-        .pipe(map((status) => status.has('fetch_settings')))
-        .subscribe(onLoading);
-      return () => subscription.unsubscribe();
-    }
-  }, [app, onLoading]);
-
-  useLayoutEffect(() => {
-    // Only subscribe once both an app and an onUpdating callback are available
-    if (app && onUpdating) {
-      // Derive a boolean updating flag from whether 'update_settings' is an active status
-      const subscription = app.status$
-        .pipe(map((status) => status.has('update_settings')))
-        .subscribe(onUpdating);
-      return () => subscription.unsubscribe();
-    }
-  }, [app, onUpdating]);
-};

package/src/state/index.ts

@@ -1,12 +0,0 @@
-export {
-  AllowedValue,
-  IStateProvider,
-  StateItem,
-  StateSyncEvent,
-  type StateSyncEventType,
-} from '@equinor/fusion-framework-module-state';
-
-export { enableState as enableAppState } from '@equinor/fusion-framework-app/enable-state';
-
-export { useAppState } from './useAppState';
-export { useStateSyncEvents } from './useStateSyncEvents';