@equinor/fusion-framework-react-app 14.1.0 → 14.1.2

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';

package/src/state/useAppState.ts

@@ -1,299 +0,0 @@
-import {
-  useCallback,
-  useLayoutEffect,
-  useRef,
-  useState,
-  useSyncExternalStore,
-  type SetStateAction,
-} from 'react';
-
-import { BehaviorSubject, from } from 'rxjs';
-import { map, skip } from 'rxjs/operators';
-
-import type { AllowedValue, StateModule } from '@equinor/fusion-framework-module-state';
-
-import useAppModule from '../useAppModule';
-
-/**
- * Configuration options for the `useAppState` hook.
- */
-interface UseAppStateOptions<T extends AllowedValue> {
-  /**
-   * Default value to return when the state item doesn't exist or is undefined.
-   * This value will be returned immediately on first render if no stored value exists.
-   */
-  defaultValue?: T;
-}
-
-/**
- * A React hook for managing persistent application state through the Fusion Framework.
- *
- * This hook provides a simple way to store and retrieve values that persist across
- * app sessions and are shared between different parts of your application. It works
- * similarly to `useState` but with automatic persistence and cross-component synchronization.
- *
- * **Key Features:**
- * - Automatic persistence across app sessions
- * - Real-time synchronization between components
- * - Optimistic updates for responsive UX
- * - Deep equality checking to prevent unnecessary re-renders
- * - TypeScript support with type safety
- * - Default value support
- *
- * **Important Notes:**
- * - Setting a value to `undefined` will completely remove it from storage
- * - Values must be serializable (JSON-compatible)
- * - Use unique keys to avoid conflicts between different state items
- * - **The key parameter must remain constant across re-renders** - changing the key after the hook
- *   is initialized will be ignored and a warning will be logged in development mode
- *
- * @template T The type of value to store. Must be serializable (string, number, boolean, object, array, etc.)
- * @param key Unique identifier for this state item. Use descriptive names like 'user.preferences' or 'dashboard.filters'. **Must remain constant across re-renders.**
- * @param options Configuration options including default value
- * @returns A tuple containing [currentValue, setValue] similar to useState
- *
- * @example
- * **Basic Usage:**
- * ```tsx
- * function UserProfile() {
- *   // Simple string state with default value
- *   const [userName, setUserName] = useAppState('user.name', {
- *     defaultValue: 'Anonymous'
- *   });
- *
- *   return (
- *     <input
- *       value={userName || ''}
- *       onChange={(e) => setUserName(e.target.value)}
- *     />
- *   );
- * }
- * ```
- *
- * @example
- * **Object State:**
- * ```tsx
- * interface UserSettings {
- *   theme: 'light' | 'dark';
- *   language: string;
- *   notifications: boolean;
- * }
- *
- * function SettingsPanel() {
- *   const [settings, setSettings] = useAppState<UserSettings>('user.settings', {
- *     defaultValue: { theme: 'light', language: 'en', notifications: true }
- *   });
- *
- *   const toggleTheme = () => {
- *     setSettings(prev => ({
- *       ...prev!,
- *       theme: prev!.theme === 'light' ? 'dark' : 'light'
- *     }));
- *   };
- *
- *   return <button onClick={toggleTheme}>Theme: {settings?.theme}</button>;
- * }
- * ```
- *
- * @example
- * **Array State:**
- * ```tsx
- * function TaskList() {
- *   const [tasks, setTasks] = useAppState<string[]>('tasks', { defaultValue: [] });
- *
- *   const addTask = (text: string) => {
- *     setTasks(prev => [...(prev || []), text]);
- *   };
- *
- *   const removeTask = (index: number) => {
- *     setTasks(prev => prev?.filter((_, i) => i !== index));
- *   };
- *
- *   return (
- *     <ul>
- *       {tasks?.map((task, index) => (
- *         <li key={index} onClick={() => removeTask(index)}>
- *           {task}
- *         </li>
- *       ))}
- *     </ul>
- *   );
- * }
- * ```
- *
- * @example
- * **Clearing State:**
- * ```tsx
- * function DataManager() {
- *   const [data, setData] = useAppState<unknown[]>('cache.data');
- *
- *   const clearCache = () => {
- *     // Setting to undefined removes the item from storage completely
- *     setData(undefined);
- *   };
- *
- *   return <button onClick={clearCache}>Clear Cache</button>;
- * }
- * ```
- *
- * @example
- * **Cross-Component Synchronization:**
- * ```tsx
- * // Component A
- * function ComponentA() {
- *   const [counter, setCounter] = useAppState('shared.counter', { defaultValue: 0 });
- *   return <button onClick={() => setCounter(c => (c || 0) + 1)}>Count: {counter}</button>;
- * }
- *
- * // Component B (automatically stays in sync)
- * function ComponentB() {
- *   const [counter] = useAppState('shared.counter', { defaultValue: 0 });
- *   return <div>Current count: {counter}</div>;
- * }
- * ```
- *
- * @example
- * **Key Stability - DO and DON'T:**
- * ```tsx
- * function MyComponent({ userId }: { userId: string }) {
- *   // ❌ DON'T: Key changes with prop, will cause warnings and use initial key
- *   const [userPrefs] = useAppState(`user.${userId}.preferences`);
- *
- *   // ✅ DO: Use a constant key
- *   const [globalSettings] = useAppState('app.global.settings');
- *
- *   return <div>...</div>;
- * }
- * ```
- *
- * @since 6.3.0
- */
-export const useAppState = <T extends AllowedValue = AllowedValue>(
-  key: string,
-  options?: UseAppStateOptions<T>,
-): [T | undefined, (action: SetStateAction<T | undefined>) => void] => {
-  // Restrict development-only key validation to avoid production overhead.
-  if (process.env.NODE_ENV === 'development') {
-    // Warn early when callers provide a key that cannot identify persisted state.
-    if (!key || typeof key !== 'string') {
-      console.warn('useAppState: key must be a non-empty string');
-    }
-  }
-
-  // Capture the initial key value and ensure it never changes
-  const initialKey = useRef(key);
-
-  // Warn about key changes only in development because the hook intentionally keeps its initial key.
-  if (process.env.NODE_ENV === 'development') {
-    // Surface an unstable key while preserving the original storage identity.
-    if (initialKey.current !== key) {
-      console.warn(
-        `useAppState: key changed from "${initialKey.current}" to "${key}". The key should remain constant across re-renders. Using initial key: "${initialKey.current}"`,
-      );
-    }
-  }
-
-  // Access the state module from the Fusion Framework's dependency injection system
-  const stateProvider = useAppModule<StateModule>('state');
-
-  // BehaviorSubject bridges async state provider with React's sync rendering.
-  // Provides immediate access via value$.value and replay semantics for new subscribers.
-  // Initialize with defaultValue for consistent SSR/client hydration.
-  const [value$] = useState(() => {
-    return new BehaviorSubject<T | undefined>(options?.defaultValue);
-  });
-
-  // useLayoutEffect runs synchronously after DOM mutations but before paint,
-  // preventing visual inconsistencies during hydration and ensuring state sync before updates.
-  useLayoutEffect(() => {
-    const subscription = from(
-      stateProvider.observeItem<T>(initialKey.current, { initialValue: value$.value }),
-    ).subscribe({
-      next: (item) => {
-        // Convert state provider's null to undefined for React conventions
-        value$.next(item === null ? undefined : item.value);
-      },
-      error: (err) => {
-        // Log errors for debugging but don't crash the component
-        console.error(`State observation error for key "${initialKey.current}":`, err);
-      },
-      complete: () => {
-        // Complete the local stream when the source completes
-        value$.complete();
-      },
-    });
-
-    // Critical: Always cleanup subscriptions to prevent memory leaks
-    return () => {
-      subscription.unsubscribe();
-    };
-  }, [stateProvider, value$]);
-
-  // Helper function to get the current value, falling back to the default if necessary
-  const getValue = useCallback(
-    (rawValue: T | undefined) => (rawValue === undefined ? options?.defaultValue : rawValue),
-    [options?.defaultValue],
-  );
-
-  // useSyncExternalStore integrates with React 18's concurrent features,
-  // ensuring consistent state during concurrent rendering and preventing tearing.
-  const value = useSyncExternalStore(
-    (callback) => {
-      const subscription = value$
-        // Transform state emissions into the snapshot updates expected by React.
-        .pipe(
-          // skip the initial value, since we don't want to emit anything before the app state provider has initialized
-          skip(1),
-          // Apply default value logic consistently with snapshot function
-          map((value) => (value === undefined ? options?.defaultValue : value)),
-        )
-        .subscribe(callback);
-
-      return () => {
-        subscription.unsubscribe();
-      };
-    },
-
-    // Snapshot function: returns current value synchronously for React rendering
-    () => getValue(value$.value),
-
-    // Server snapshot: ensures consistent hydration between server and client
-    () => options?.defaultValue,
-  );
-
-  // Implements optimistic updates: update local state immediately, then persist.
-  // If persistence fails, the state provider will emit the old value, reverting the update.
-  const setValue = useCallback(
-    (action: SetStateAction<T | undefined>) => {
-      // Handle both direct values and updater functions (like React's useState).
-      // Apply the same defaulting as the snapshot so updaters never see a bare `undefined`
-      // when a `defaultValue` was provided.
-      const value = typeof action === 'function' ? action(getValue(value$.value)) : action;
-
-      // Remove undefined values from storage while updating subscribers immediately.
-      if (value === undefined) {
-        // undefined means "delete from storage" - update local state first for immediate UI feedback
-        value$.next(undefined);
-        stateProvider.removeItem(initialKey.current).catch((error) => {
-          console.error(`Failed to remove item "${initialKey.current}":`, error);
-        });
-      } else {
-        // Optimistic update: local state first, then persist to storage
-        value$.next(value);
-        stateProvider
-          .storeItem({
-            key: initialKey.current,
-            value,
-          })
-          .catch((error) => {
-            console.error(`Failed to store item "${initialKey.current}":`, error);
-          });
-      }
-    },
-    [stateProvider, value$, getValue],
-  );
-
-  return [value, setValue];
-};
-
-export default useAppState;

package/src/state/useStateSyncEvents.ts

@@ -1,59 +0,0 @@
-import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
-import { BehaviorSubject } from 'rxjs';
-import { filter } from 'rxjs/operators';
-
-import type { EventModule } from '@equinor/fusion-framework-module-event';
-import { StateSyncEvent, type StateSyncEventType } from '@equinor/fusion-framework-module-state';
-
-import useAppModule from '../useAppModule';
-
-/**
- * Subscribes to the app's `state` module sync events (`onStateSync.status`,
- * `onStateSync.change`, `onStateSync.complete`, `onStateSync.error`) and returns the most
- * recent `limit` events, oldest first.
- *
- * Events are only dispatched while the state module's storage is configured for replication
- * (see `PouchDbSyncStorage`) - with the state module's default, local-only storage, this hook
- * returns an empty array.
- *
- * @param limit - Maximum number of most-recent sync events to retain.
- * @returns The most recent sync events, oldest first.
- *
- * @example
- * ```tsx
- * const events = useStateSyncEvents(20);
- * const lastEvent = events.at(-1);
- * ```
- *
- * @since 12.1.0
- */
-export const useStateSyncEvents = (limit: number): StateSyncEventType[] => {
-  const eventProvider = useAppModule<EventModule>('event');
-  const [event$] = useState(() => new BehaviorSubject<StateSyncEventType[]>([]));
-
-  // Read through a ref so changing `limit` trims the log without resubscribing.
-  const limitRef = useRef(limit);
-  limitRef.current = limit;
-
-  useLayoutEffect(() => {
-    // Narrow the shared event stream down to the sync-related events this hook exposes.
-    const subscription = eventProvider.event$.pipe(filter(StateSyncEvent.is)).subscribe((event) => {
-      const next = [...event$.getValue(), event];
-      // Clamp to 0 so `slice(-0)` (a no-op, unlike `slice(-1)`) can't retain the whole log.
-      const limit = Math.max(0, limitRef.current);
-      event$.next(limit === 0 ? [] : next.length > limit ? next.slice(-limit) : next);
-    });
-    return () => subscription.unsubscribe();
-  }, [eventProvider, event$]);
-
-  return useSyncExternalStore(
-    (onChange) => {
-      const subscription = event$.subscribe(onChange);
-      return () => subscription.unsubscribe();
-    },
-    () => event$.getValue(),
-    () => event$.getValue(),
-  );
-};
-
-export default useStateSyncEvents;

package/src/useAppEnvironmentVariables.ts

@@ -1,59 +0,0 @@
-import { useMemo } from 'react';
-import { map } from 'rxjs/operators';
-import type { ConfigEnvironment } from '@equinor/fusion-framework-module-app';
-import { useCurrentApp } from '@equinor/fusion-framework-react/app';
-import {
-  type ObservableStateReturnType,
-  useObservableState,
-} from '@equinor/fusion-observable/react';
-
-/**
- * A React hook that provides access to the application's environment variables.
- *
- * This hook returns an observable state object that represents the current environment configuration.
- * The environment configuration is retrieved from the app module provided by the framework.
- *
- * @remarks This hook is only available when the app module is loaded (should be always for applications).
- * This hook in theory should always have a value if config was provided for the application, but is async by nature, hence the `complete` and `error` properties.
- *
- * @example
- * ```typescript
- * const MyComponent = () => {
- *   const env = useAppEnvironmentVariables();
- *   if(!env.complete) {
- *     return <div>Loading environment variables...</div>;
- *   }
- *   if(env.error) {
- *    return <div>Error loading environment variables</div>;
- *   }
- *   return <div>My environment variables: {JSON.stringify(env.value)}</div>;
- * }
- *
- * @template TEnvironmentVariables - The type of the environment variables. Defaults to `unknown`.
- * @returns An observable state object containing the current environment configuration.
- */
-export const useAppEnvironmentVariables = <
-  TEnvironmentVariables extends ConfigEnvironment = ConfigEnvironment,
->(): ObservableStateReturnType<TEnvironmentVariables> => {
-  // Get the current app module instance from the framework
-  const app = useCurrentApp<[], TEnvironmentVariables>().currentApp;
-
-  // Ensure the app module is available before proceeding
-  if (!app) {
-    throw Error('Framework is missing app module');
-  }
-
-  const env$ = useMemo(() => {
-    // Extract just the environment slice of the app's config for consumers
-    return app.getConfig().pipe(
-      map((config) => {
-        return config.environment as TEnvironmentVariables;
-      }),
-    );
-  }, [app]);
-
-  // Return the observable state of the environment configuration
-  return useObservableState(env$, {
-    initial: app.config?.environment || ({} as TEnvironmentVariables),
-  });
-};

package/src/useAppModule.ts

@@ -1,45 +0,0 @@
-import type { AppModules, AppModulesInstance } from '@equinor/fusion-framework-app';
-import type {
-  AnyModule,
-  ModuleKey,
-  ModuleType,
-  ModuleTypes,
-} from '@equinor/fusion-framework-module';
-
-import { useAppModules } from './useAppModules';
-
-/**
- * React hook that retrieves a single module instance from the application scope.
- *
- * @template TType - The concrete module type (e.g. `ContextModule`). Pass
- *   `unknown` to infer the type from the key.
- * @template TKey - The string key used to look up the module.
- * @param module - The key identifying the module to retrieve.
- * @returns The resolved module instance.
- * @throws If the requested module is not registered in the application scope.
- *
- * @example
- * ```tsx
- * const auth = useAppModule('auth');
- * auth.acquireAccessToken().then(console.log);
- * ```
- */
-export function useAppModule<
-  TType extends AnyModule | unknown = unknown,
-  TKey extends string = ModuleKey<ModuleTypes<AppModules<[TType]>>>,
->(
-  module: TKey,
-): TType extends AnyModule
-  ? ModuleType<TType>
-  : AppModulesInstance[Extract<keyof AppModulesInstance, TKey>] {
-  const appModule = useAppModules()[module as keyof AppModulesInstance];
-  // Fail fast when the requested module was not registered on the app scope
-  if (!appModule) {
-    throw Error(`the requested module [${module}] is not included in the app scope`);
-  }
-  return appModule as TType extends AnyModule
-    ? ModuleType<TType>
-    : AppModulesInstance[Extract<keyof AppModulesInstance, TKey>];
-}
-
-export default useAppModule;

package/src/useAppModules.ts

@@ -1,21 +0,0 @@
-import type { AppModules, AppModulesInstance } from '@equinor/fusion-framework-app';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-import { useModules } from '@equinor/fusion-framework-react-module';
-
-/**
- * React hook that returns the full set of initialised application-scoped modules.
- *
- * @template T - Optional array of additional module types beyond the defaults.
- * @returns The {@link AppModulesInstance} containing all registered modules.
- *
- * @example
- * ```tsx
- * const modules = useAppModules();
- * console.log(Object.keys(modules));
- * ```
- */
-export const useAppModules = <
-  T extends Array<AnyModule> | unknown = unknown,
->(): AppModulesInstance<T> => useModules<AppModules<T>>() as AppModulesInstance<T>;
-
-export default useAppModules;

package/src/version.ts

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