@equinor/fusion-framework-react-app 12.0.5 → 14.0.0

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

@@ -0,0 +1,4 @@
+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/dist/types/state/useAppState.d.ts

@@ -0,0 +1,157 @@
+import { type SetStateAction } from 'react';
+import type { AllowedValue } from '@equinor/fusion-framework-module-state';
+/**
+ * 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 declare const useAppState: <T extends AllowedValue = AllowedValue>(key: string, options?: UseAppStateOptions<T>) => [T | undefined, (action: SetStateAction<T | undefined>) => void];
+export default useAppState;

package/dist/types/state/useStateSyncEvents.d.ts

@@ -0,0 +1,23 @@
+import { type StateSyncEventType } from '@equinor/fusion-framework-module-state';
+/**
+ * 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 declare const useStateSyncEvents: (limit: number) => StateSyncEventType[];
+export default useStateSyncEvents;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "12.0.5";
+export declare const version = "14.0.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "12.0.5",
+  "version": "14.0.0",
   "description": "",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
@@ -29,6 +29,10 @@
       "types": "./dist/types/feature-flag/index.d.ts",
       "import": "./dist/esm/feature-flag/index.js"
     },
+    "./state": {
+      "types": "./dist/types/state/index.d.ts",
+      "import": "./dist/esm/state/index.js"
+    },
     "./framework": {
       "types": "./dist/types/framework/index.d.ts",
       "import": "./dist/esm/framework/index.js"
@@ -86,6 +90,9 @@
       "feature-flag": [
         "dist/types/feature-flag/index.d.ts"
       ],
+      "state": [
+        "dist/types/state/index.d.ts"
+      ],
       "framework": [
         "dist/types/framework/index.d.ts"
       ],
@@ -124,16 +131,17 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-module": "6.1.1",
+    "@equinor/fusion-framework-app": "13.0.0",
+    "@equinor/fusion-framework-module": "6.1.2",
     "@equinor/fusion-framework-module-app": "8.0.4",
-    "@equinor/fusion-framework-app": "11.0.12",
     "@equinor/fusion-framework-module-http": "8.0.5",
+    "@equinor/fusion-framework-module-navigation": "7.0.7",
     "@equinor/fusion-framework-react": "8.0.1",
-    "@equinor/fusion-framework-module-navigation": "7.0.6",
-    "@equinor/fusion-framework-react-module": "4.0.2",
-    "@equinor/fusion-framework-react-module-http": "11.0.1"
+    "@equinor/fusion-framework-react-module-http": "11.0.1",
+    "@equinor/fusion-framework-react-module": "4.0.2"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.0.0",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "happy-dom": "^20.8.4",
@@ -143,13 +151,14 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.0",
     "@equinor/fusion-framework-module-ag-grid": "37.0.1",
+    "@equinor/fusion-framework-module-analytics": "3.0.5",
     "@equinor/fusion-framework-module-event": "6.0.1",
-    "@equinor/fusion-framework-module-analytics": "3.0.4",
-    "@equinor/fusion-framework-module-feature-flag": "2.0.3",
     "@equinor/fusion-framework-module-msal": "10.0.2",
+    "@equinor/fusion-framework-module-state": "^2.0.0",
     "@equinor/fusion-framework-react-module-bookmark": "6.0.1",
-    "@equinor/fusion-framework-react-module-context": "7.0.2",
+    "@equinor/fusion-framework-module-feature-flag": "2.0.3",
     "@equinor/fusion-framework-react-router": "2.4.0",
+    "@equinor/fusion-framework-react-module-context": "7.0.2",
     "@equinor/fusion-observable": "9.1.1"
   },
   "peerDependencies": {
@@ -158,6 +167,7 @@
     "react-dom": "^18.0.0 || ^19.0.0",
     "rxjs": "^7.0.0",
     "@equinor/fusion-framework-module-msal": "^10.0.2",
+    "@equinor/fusion-framework-module-state": "^2.0.0",
     "@equinor/fusion-framework-react-router": "^2.4.0"
   },
   "peerDependenciesMeta": {
@@ -176,6 +186,9 @@
     "@equinor/fusion-framework-module-feature-flag": {
       "optional": true
     },
+    "@equinor/fusion-framework-module-state": {
+      "optional": true
+    },
     "@equinor/fusion-observable": {
       "optional": true
     },

package/src/__tests__/useStateSyncEvents.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Subject } from 'rxjs';
+
+import { act, renderHook } from '@testing-library/react';
+
+import { StateSyncEvent, type StateSyncEventType } from '@equinor/fusion-framework-module-state';
+
+const event$ = new Subject<StateSyncEventType>();
+
+vi.mock('../useAppModule', () => ({
+  default: () => ({ event$ }),
+}));
+
+import { useStateSyncEvents } from '../state/useStateSyncEvents';
+
+describe('useStateSyncEvents', () => {
+  it('collects dispatched onStateSync.* events, oldest first', () => {
+    const { result } = renderHook(() => useStateSyncEvents(10));
+
+    expect(result.current).toEqual([]);
+
+    act(() => {
+      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
+      event$.next(new StateSyncEvent.Status({ detail: { status: 'paused' } }));
+    });
+
+    expect(result.current).toHaveLength(2);
+    expect(result.current[0].detail.status).toBe('active');
+    expect(result.current[1].detail.status).toBe('paused');
+  });
+
+  it('ignores events unrelated to state sync and trims the log to the given limit', () => {
+    const { result } = renderHook(() => useStateSyncEvents(1));
+
+    act(() => {
+      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
+      event$.next(
+        new StateSyncEvent.Error({ detail: { error: new Error('boom'), type: 'error' } }),
+      );
+    });
+
+    expect(result.current).toHaveLength(1);
+    expect(result.current[0]).toBeInstanceOf(StateSyncEvent.Error);
+  });
+
+  it('unsubscribes from the event stream on unmount', () => {
+    const { result, unmount } = renderHook(() => useStateSyncEvents(10));
+
+    unmount();
+
+    act(() => {
+      event$.next(new StateSyncEvent.Status({ detail: { status: 'active' } }));
+    });
+
+    expect(result.current).toEqual([]);
+  });
+});

package/src/state/index.ts

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

@@ -0,0 +1,299 @@
+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;