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

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

package/tsconfig.json

@@ -1,48 +0,0 @@
-{
-  "extends": "../tsconfig.react.json",
-  "compilerOptions": {
-    "outDir": "dist/esm",
-    "rootDir": "src",
-    "declarationDir": "./dist/types"
-  },
-  "references": [
-    {
-      "path": "../../utils/observable"
-    },
-    {
-      "path": "../../app"
-    },
-    {
-      "path": "../framework"
-    },
-    {
-      "path": "../router"
-    },
-    {
-      "path": "../../modules/analytics"
-    },
-    {
-      "path": "../../modules/navigation"
-    },
-    {
-      "path": "../../modules/state"
-    },
-    {
-      "path": "../../modules/ag-grid"
-    },
-    {
-      "path": "../modules/module"
-    },
-    {
-      "path": "../modules/http"
-    },
-    {
-      "path": "../modules/context"
-    },
-    {
-      "path": "../modules/bookmark"
-    }
-  ],
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib", "src/__tests__/**/*"]
-}

package/vitest.config.ts

@@ -1,15 +0,0 @@
-import { defineProject } from 'vitest/config';
-
-import { name, version } from './package.json';
-
-export default defineProject({
-  resolve: {
-    // @ts-expect-error -- tsconfigPaths is a Vite 8 option; vitest 4.x ships Vite 7 types
-    tsconfigPaths: true,
-  },
-  test: {
-    include: ['src/__tests__/**'],
-    name: `${name}@${version}`,
-    environment: 'happy-dom',
-  },
-});