feat: add state management module with sync capabilities and React hooks

- Add @equinor/fusion-framework-module-state with PouchDB sync storage
- Add state management support to @equinor/fusion-framework-app
- Add useAppState hook to @equinor/fusion-framework-react-app
- Add state management cookbooks for examples and replication demos
- Reorganize event system with comprehensive state event types
- Update dependencies and fix formatting issues

Author: odinr

.changeset/add-state-module-support.md .changeset/app_state-support.md.changeset/add-state-module-support.md renamed to .changeset/app_state-support.md

@@ -6,15 +6,15 @@ Add state management module support to @equinor/fusion-framework-app
 
 This change introduces comprehensive state management capabilities to the app package, allowing developers to easily enable persistent state storage in their Fusion applications.
 
-### New Features
+**Features**
 
 - **State Module Enabler**: Added `enableState` function that configures the state module with PouchDB storage
 - **Package Exports**: Added new export path `./enable-state` for the state enabler function
 - **Type Definitions**: Added typesVersions support for the new state enabler
 - **Peer Dependencies**: Added `@equinor/fusion-framework-module-state` as an optional peer dependency
 - **Storage Configuration**: Automatic app-scoped storage with key prefixing to prevent state collisions
 
-### Usage
+**Usage**
 
 Applications can now enable state management by:
 

…ngeset/new-cookbook-state-replication.md …app-react-state-replication_sync-demo.md.changeset/new-cookbook-state-replication.md renamed to .changeset/cookbook-app-react-state-replication_sync-demo.md .changeset/new-cookbook-state-replication.md renamed to .changeset/cookbook-app-react-state-replication_sync-demo.md

@@ -2,8 +2,6 @@
 "@equinor/fusion-framework-cookbook-app-react-state": major
 ---
 
-**@equinor/fusion-framework-cookbook-app-react-state:**
-
 🎉 Added new cookbook demonstrating state management with useAppState hook in React applications!
 
 This comprehensive cookbook 📚 provides developers with practical examples and best practices for using the Fusion Framework state module in React applications.
@@ -12,7 +10,7 @@ The cookbook includes complete state management examples demonstrating simple st
 
 Key features include:
 - 📖 Educational documentation with learning objectives, setup instructions, and key concepts
-- 🔷 Full TypeScript implementation with proper type definitions  
+- 🔷 Full TypeScript implementation with proper type definitions
 - ⚡ Complete development setup with dev server and build configuration
 
 Developers will learn how to configure the state module using `enableAppState`, use the `useAppState` hook for persistent state management, share state between components with unique state keys, manage complex object state with proper update patterns, and follow best practices for organizing state in Fusion applications.

…hangeset/add-app-react-state-cookbook.md …set/cookbook-app-react-state_examples.md.changeset/add-app-react-state-cookbook.md renamed to .changeset/cookbook-app-react-state_examples.md .changeset/add-app-react-state-cookbook.md renamed to .changeset/cookbook-app-react-state_examples.md

@@ -0,0 +1,38 @@
+---
+"@equinor/fusion-framework-module-state": major
+---
+
+**🚀 Introducing the Fusion Framework State Module**
+
+**@equinor/fusion-framework-module-state** is a new reactive state management module with built-in synchronization capabilities and comprehensive event system for enterprise-grade applications.
+
+**🗄️ Synchronization Features**
+- **PouchDbSyncStorage**: Bidirectional synchronization with remote databases
+- **Real-time sync events**: Monitor sync progress, errors, and status changes
+- **Conflict resolution**: Automatic handling of concurrent data modifications
+- **Live sync options**: Configurable heartbeat, retry, and timeout settings
+
+**📡 Event System**
+Comprehensive event architecture for type-safe state management:
+
+**Event Classes:**
+- `StateEntryCreatedEvent` - Item creation tracking
+- `StateEntryUpdatedEvent` - Item modification events
+- `StateEntryDeletedEvent` - Item removal notifications
+- `StateSyncChangeEvent` - Sync data changes
+- `StateSyncCompleteEvent` - Sync operation completion
+- `StateSyncErrorEvent` - Sync failure handling
+- `StateSyncStatusEvent` - Sync status monitoring
+- `StateOperationSuccessEvent` - Successful operations
+- `StateOperationFailureEvent` - Operation failure tracking
+
+**Event Organization:**
+- `StateChangeEvent` - CRUD operation events
+- `StateSyncEvent` - Synchronization events
+- `StateOperationEvent` - Operation result events
+
+**🏗️ Core Architecture**
+- **StateProvider**: Reactive state management with observable patterns
+- **Storage Interface**: Extensible storage backends with sync capabilities
+- **Type Safety**: Comprehensive TypeScript definitions
+- **Memory Management**: Proper cleanup and disposal patterns

.changeset/improve-app-configurator-architecture.md

@@ -9,7 +9,7 @@ We're excited to bring you a complete state management solution that makes shari
 **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  
+🔗 **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`

.changeset/module-state_sync-events.md

@@ -23,7 +23,7 @@
     "@equinor/fusion-framework-cli": "workspace:^",
     "@equinor/fusion-framework-module": "workspace:^",
     "@equinor/fusion-framework-module-event": "workspace:^",
-    "@equinor/fusion-framework-module-navigation": "^5.0.3",
+    "@equinor/fusion-framework-module-navigation": "workspace:^",
     "@equinor/fusion-framework-module-state": "workspace:^",
     "@equinor/fusion-framework-react-app": "workspace:^",
     "@equinor/fusion-observable": "workspace:^",

…/implement-react-app-state-management.md .changeset/react-app_useAppState.md.changeset/implement-react-app-state-management.md renamed to .changeset/react-app_useAppState.md .changeset/implement-react-app-state-management.md renamed to .changeset/react-app_useAppState.md

@@ -4,7 +4,7 @@
     "outDir": "./dist",
     "rootDir": "./src",
     "jsx": "react-jsx",
-    "baseUrl": "./src",
+    "baseUrl": "./src"
   },
   "references": [{ "path": "../../packages/modules/state" }],
   "include": ["src/**/*"],

cookbooks/app-react-state-replication/package.json

@@ -29,9 +29,16 @@ const modules = await configurator.initialize();
 
 // Use the state provider
 const stateProvider = modules.state;
+
+// Store and retrieve data
 await stateProvider.storeItem({ key: 'example', value: 'Hello, World!' });
 const item = await stateProvider.getItem('example');
 console.log(item?.value); // "Hello, World!"
+
+// Observe changes reactively
+stateProvider.observeItem('example').subscribe(item => {
+  console.log('Item updated:', item?.value);
+});
 ```
 
 ## Module Setup
@@ -304,16 +311,16 @@ import { PouchDbStorage } from '@equinor/fusion-framework-module-state/storage';
 
 enableStateModule(configurator, async (builder) => {
   // Create local PouchDB storage
-  const localStorage = PouchDbStorage.CreateDb('my-app-state');
-  const remoteStorage = PouchDbStorage.CreateDb('http://localhost:5984/my-app-state');
+  const localDb = PouchDbStorage.CreateDb('my-app-state');
+  const remoteDb = PouchDbStorage.CreateDb('http://localhost:5984/my-app-state');
 
   // Set up two-way sync with remote CouchDB
-  localStorage.sync(remoteStorage, {
+  localDb.sync(remoteDb, {
     live: true,
     retry: true
   });
 
-  builder.setStorage(new PouchDbStorage(localStorage));
+  builder.setStorage(new PouchDbStorage(localDb));
 });
 ```
 
@@ -322,6 +329,25 @@ enableStateModule(configurator, async (builder) => {
 - **`retry: true`**: Automatically retries replication on connection failures
 - **`filter`**: Apply custom filters to replicate only specific documents
 - **`since`**: Start replication from a specific sequence number
+
+### Monitoring Sync Progress
+
+The state module provides comprehensive sync event monitoring through RxJS observables:
+
+```typescript
+import { enableStateModule } from '@equinor/fusion-framework-module-state';
+import { StateSyncEvent } from '@equinor/fusion-framework-module-state/events';
+
+enableStateModule(configurator, async (builder) => {
+  const localDb = PouchDbStorage.CreateDb('my-app-state');
+  const remoteDb = PouchDbStorage.CreateDb('http://localhost:5984/my-app-state');
+
+  // Start sync
+  const sync = localDb.sync(remoteDb, { live: true, retry: true });
+
+  builder.setStorage(new PouchDbStorage(localDb));
+});
+
 ### Custom Storage Implementation
 
 If you need to use a different storage backend, you can create your own by implementing the `IStorage` interface. This allows you to integrate with any storage system (e.g., custom APIs, browser storage, or other databases).
@@ -535,6 +561,123 @@ Response object for bulk item retrieval operations.
 - **`offset?: number`**
   - Current offset in the result set.
 
+## Testing
+
+The state module includes comprehensive test utilities and examples:
+
+```typescript
+import { StateProvider } from '@equinor/fusion-framework-module-state';
+import { createMockStorage } from '@equinor/fusion-framework-module-state/__tests__/storage.mock';
+
+// Create a mock storage for testing
+const mockStorage = createMockStorage();
+const stateProvider = new StateProvider({ storage: mockStorage });
+
+// Test your state operations
+describe('State Management', () => {
+  it('should store and retrieve items', async () => {
+    await stateProvider.storeItem({ key: 'test', value: 'data' });
+    const item = await stateProvider.getItem('test');
+    expect(item?.value).toBe('data');
+  });
+});
+```
+
+## Migration Guide
+
+### Upgrading from v1.x to v2.x
+
+**Breaking Changes:**
+- Event system has been refactored - see [events documentation](#monitoring-sync-progress)
+- Storage interface methods are now async by default
+- `observeItems` now returns `StateItem<T>[]` instead of `StateItem[]`
+
+**Migration Steps:**
+1. Update event subscriptions to use new event types
+2. Add `await` to storage operations if using custom storage
+3. Update type annotations for `observeItems` return values
+
+### From Other State Libraries
+
+**Redux Migration:**
+```typescript
+// Before (Redux)
+const store = createStore(reducer);
+store.dispatch({ type: 'SET_DATA', payload: data });
+
+// After (Fusion State)
+await stateProvider.storeItem({ key: 'data', value: data });
+```
+
+**Zustand Migration:**
+```typescript
+// Before (Zustand)
+const useStore = create((set) => ({ data, setData }));
+useStore.getState().setData(newData);
+
+// After (Fusion State)
+await stateProvider.storeItem({ key: 'data', value: newData });
+```
+
+## Performance Considerations
+
+### Optimization Tips
+
+1. **Use prefix filtering** for large datasets:
+   ```typescript
+   // Good: Filter by prefix for better performance
+   const userPrefs = await stateProvider.getAllItems({ prefix: 'user.' });
+
+   // Avoid: Loading all items when you only need a subset
+   const allItems = await stateProvider.getAllItems();
+   const userPrefs = allItems.items.filter(item => item.key.startsWith('user.'));
+   ```
+
+2. **Batch operations** for multiple changes:
+   ```typescript
+   // Good: Single bulk operation
+   await stateProvider.storeItems([
+     { key: 'user.name', value: 'John' },
+     { key: 'user.email', value: 'john@example.com' }
+   ]);
+
+   // Avoid: Multiple individual operations
+   await stateProvider.storeItem({ key: 'user.name', value: 'John' });
+   await stateProvider.storeItem({ key: 'user.email', value: 'john@example.com' });
+   ```
+
+3. **Unsubscribe from observables** when components unmount:
+   ```typescript
+   // Good: Proper cleanup
+   useEffect(() => {
+     const subscription = stateProvider.observeItem('data').subscribe(setData);
+     return () => subscription.unsubscribe();
+   }, []);
+
+   // Avoid: Memory leaks
+   stateProvider.observeItem('data').subscribe(setData); // Never unsubscribed
+   ```
+
+### Memory Management
+
+- **PouchDB Storage**: Uses IndexedDB in browsers, which has storage limits
+- **Memory Storage**: All data kept in memory - lost on page refresh
+- **Custom Storage**: Depends on your implementation
+
+### Sync Performance
+
+- **Live sync**: Provides real-time updates but increases network usage
+- **Batch sync**: Reduces network calls but may show stale data
+- **Filtered sync**: Only sync relevant data to improve performance
+
 ## Development
 
 This package is part of the [Fusion Framework monorepo](https://github.com/equinor/fusion-framework).
+
+### Contributing
+
+We welcome contributions! Please see our [contributing guidelines](../../CONTRIBUTING.md) for details on:
+- Code style and formatting
+- Testing requirements
+- Pull request process
+- Release process

cookbooks/app-react-state-replication/tsconfig.json

@@ -10,6 +10,10 @@
       "import": "./dist/esm/index.js",
       "types": "./dist/types/index.d.ts"
     },
+    "./events": {
+      "import": "./dist/esm/events/index.js",
+      "types": "./dist/types/storeventsage/index.d.ts"
+    },
     "./storage": {
       "import": "./dist/esm/storage/index.js",
       "types": "./dist/types/storage/index.d.ts"