feat(app_state): implement state management with useAppState hook and enhance documentation

Author: odinr

.changeset/implement-react-app-state-management.md

@@ -0,0 +1,67 @@
+---
+"@equinor/fusion-framework-react-app": major
+---
+
+🎉 **Introducing State Management for React Applications!**
+
+We're excited to bring you a complete state management solution that makes sharing data between components effortless. Say goodbye to prop drilling and hello to persistent, synchronized state that survives page refreshes!
+
+**What's new?** The powerful `useAppState` hook works just like React's `useState` but with superpowers:
+
+🔄 **Persistent by default** - Your state survives page refreshes using browser storage
+🔗 **Automatically synchronized** - Share state between any components in real-time  
+⚡ **Optimistically updated** - Lightning-fast UI with automatic error recovery
+🛡️ **Fully type-safe** - Complete TypeScript support with type inference
+🎯 **Dead simple API** - If you know `useState`, you already know `useAppState`
+
+**Getting started is easy:**
+```typescript
+import { enableAppState } from '@equinor/fusion-framework-react-app/state';
+
+export const configure = (configurator) => {
+  enableAppState(configurator);
+};
+```
+
+**Then use it anywhere:**
+```typescript
+import { useAppState } from '@equinor/fusion-framework-react-app/state';
+
+const [count, setCount] = useAppState('counter', { defaultValue: 0 });
+```
+
+**Perfect for:**
+- User preferences and UI settings
+- Form data that enhances user experience
+- Filters, sorting, and view states
+- Any data that needs to be shared across components
+- Caching expensive operations
+
+**Important:** Uses browser storage (localStorage/IndexedDB via PouchDB) - perfect for enhancing user experience but not suitable for critical data that must be guaranteed to persist. Always have fallback strategies for essential information.
+
+**Examples that show the magic:**
+
+```typescript
+// Simple counter that persists across refreshes
+const Counter = () => {
+  const [count, setCount] = useAppState('counter', { defaultValue: 0 });
+  return <button onClick={() => setCount(c => (c || 0) + 1)}>Count: {count}</button>;
+};
+
+// Components automatically sync - change in one updates all others!
+const Settings = () => {
+  const [theme, setTheme] = useAppState('theme', { defaultValue: 'light' });
+  return <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+    Switch to {theme === 'light' ? 'dark' : 'light'} mode
+  </button>;
+};
+
+const Header = () => {
+  const [theme] = useAppState('theme', { defaultValue: 'light' });
+  return <header className={`header-${theme}`}>My App</header>;
+};
+```
+
+This feature includes comprehensive documentation with practical examples, best practices, and TypeScript patterns. Applications need to install `@equinor/fusion-framework-module-state` to unlock these capabilities.
+
+Ready to eliminate prop drilling and embrace persistent state? Check out the updated README for complete setup instructions and advanced usage patterns!

packages/app/package.json

@@ -62,6 +62,7 @@
     "@equinor/fusion-framework-module-event": "workspace:^",
     "@equinor/fusion-framework-module-http": "workspace:^",
     "@equinor/fusion-framework-module-msal": "workspace:^",
+    "fast-deep-equal": "^3.1.3",
     "lodash.clonedeep": "^4.5.0"
   },
   "devDependencies": {

packages/modules/state/src/index.ts

@@ -6,6 +6,8 @@ export { StateModuleConfigurator } from './StateModuleConfigurator.js';
 
 export { enableStateModule } from './enable-state-module.js';
 
+export { StateModule, module, module as default } from './StateModule.js';
+
 export type {
   AllowedValue,
   StateItem,

packages/react/app/README.md

@@ -91,6 +91,140 @@ const App = () => {
 }
 ```
 
+## State Management
+
+[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fstate%2Fpackage.json&label=@equinor/fusion-framework-module-state&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/state)
+
+The Fusion Framework provides a powerful state management solution that enables persistent, cross-component state sharing with automatic synchronization. Unlike traditional React state that's lost on page refresh, this state persists across app sessions and stays synchronized between different components in real-time.
+
+**Key Benefits:**
+- 🔄 **Persistent State**: Survives page refreshes and app restarts
+- 🔗 **Cross-Component Sync**: Share state between any components instantly
+- ⚡ **Optimistic Updates**: Responsive UI with automatic rollback on errors
+- 🛡️ **Type Safe**: Full TypeScript support with type inference
+- 🎯 **Simple API**: Works like `useState` but with persistence
+
+**Use Cases:**
+- User preferences and settings
+- Form data that should persist
+- UI state like filters, sorting, or view modes
+- Data that needs to be shared across multiple components
+- Cache management for expensive operations
+
+### Installation
+
+First, install the state module package:
+
+```sh
+pnpm install @equinor/fusion-framework-module-state
+```
+
+### Setup
+
+Enable the state module in your app configuration. This initializes the persistent storage and makes `useAppState` available throughout your application:
+
+```typescript
+import { enableAppState } from '@equinor/fusion-framework-react-app/state';
+export const configure: ModuleInitiator = (appConfigurator) => {
+  enableAppState(appConfigurator);
+};
+```
+
+### Basic Usage
+
+Use `useAppState` just like React's `useState`, but with automatic persistence. The first parameter is a unique key, and the second is an options object with the default value:
+
+```typescript
+import { useAppState } from '@equinor/fusion-framework-react-app/state';
+
+const Counter = () => {
+  const [count, setCount] = useAppState('counter', { defaultValue: 0 });
+  return (
+    <div>
+      <span>Count: {count}</span>
+      <button onClick={() => setCount((prev) => (prev ?? 0) + 1)}>Increment</button>
+    </div>
+  );
+};
+```
+
+### Cross-Component Synchronization
+
+Multiple components can share the same state by using the same key. Changes in one component automatically update all others:
+
+```typescript
+import { useAppState } from '@equinor/fusion-framework-react-app/state';
+
+const Incrementer = () => {
+  const [count, setCount] = useAppState('counter', { defaultValue: 0 });
+  return (
+    <button onClick={() => setCount((prev) => (prev || 0) + 1)}>
+      Increment
+    </button>
+  );
+};
+
+const Display = () => {
+  const [count] = useAppState('counter', { defaultValue: 0 });
+  return <span>Current count: {count}</span>;
+};
+
+// Usage in your app
+const App = () => (
+  <div>
+    <Incrementer />
+    <Display />
+  </div>
+);
+```
+
+### Best Practices
+
+> [!WARNING]
+> **Avoid Stale Closures**: When updating state based on the current value, always use the updater function to prevent stale closure issues in concurrent updates.
+> 
+> ```typescript
+> const [count, setCount] = useAppState('counter', { defaultValue: 0 });
+> 
+> // ❌ Bad: Can use stale value in rapid updates
+> const increment = () => setCount(count + 1);
+> 
+> // ✅ Good: Always gets the latest value
+> const increment = () => setCount(prev => (prev || 0) + 1);
+> ```
+
+### Advanced Usage
+
+**Complex Objects with TypeScript:**
+```typescript
+interface UserPreferences {
+  theme: 'light' | 'dark';
+  language: string;
+  notifications: boolean;
+}
+
+const SettingsPanel = () => {
+  const [settings, setSettings] = useAppState<UserPreferences>('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>;
+};
+```
+
+**Clearing State:**
+```typescript
+// Remove from storage completely
+const clearSettings = () => setSettings(undefined);
+```
+
 ## Feature Flag
 
 > [!IMPORTANT]

packages/react/app/package.json

@@ -123,8 +123,7 @@
     "@equinor/fusion-framework-module-navigation": "workspace:^",
     "@equinor/fusion-framework-react": "workspace:^",
     "@equinor/fusion-framework-react-module": "workspace:^",
-    "@equinor/fusion-framework-react-module-http": "workspace:^",
-    "fast-deep-equal": "^3.1.3"
+    "@equinor/fusion-framework-react-module-http": "workspace:^"
   },
   "devDependencies": {
     "@equinor/fusion-framework-module-ag-grid": "workspace:^",

packages/react/app/src/state/index.ts

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