@equinor/fusion-framework-react-app 12.0.4 → 13.0.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Change Log
 
+## 13.0.0
+
+### Minor Changes
+
+- b92698d: Add state management support to `@equinor/fusion-framework-react-app/state`:
+
+  - `enableAppState` - configures the app to use `@equinor/fusion-framework-module-state`, with
+    app-scoped storage key prefixing to prevent state collisions between apps.
+  - `useAppState` - a persistent, cross-component-synchronized alternative to `useState`, backed by
+    the state module's storage.
+  - `useStateSyncEvents` - subscribes to the app's `onStateSync.status`/`.change`/`.complete`/`.error`
+    events (dispatched when storage is configured for replication, e.g. `PouchDbSyncStorage`) and
+    returns the most recent events, oldest first, bounded to a given `limit`. Also re-exports
+    `StateSyncEvent` and `StateSyncEventType` from `@equinor/fusion-framework-module-state` for
+    convenience.
+
+  ```typescript
+  import { enableAppState } from "@equinor/fusion-framework-react-app/state";
+
+  export const configure = (configurator) => {
+    enableAppState(configurator);
+  };
+  ```
+
+  ```typescript
+  import {
+    useAppState,
+    useStateSyncEvents,
+  } from "@equinor/fusion-framework-react-app/state";
+
+  const [count, setCount] = useAppState("counter", { defaultValue: 0 });
+  const events = useStateSyncEvents(20);
+  ```
+
+  Requires the optional peer dependency `@equinor/fusion-framework-module-state`.
+
+### Patch Changes
+
+- Updated dependencies [b92698d]
+- Updated dependencies [1b9d026]
+- Updated dependencies [1b9d026]
+- Updated dependencies [0d6ef3a]
+- Updated dependencies [020d9e5]
+- Updated dependencies [0d9d876]
+- Updated dependencies [05586e7]
+- Updated dependencies [b92698d]
+- Updated dependencies [b92698d]
+  - @equinor/fusion-framework-app@12.0.0
+  - @equinor/fusion-framework-module-navigation@7.0.7
+  - @equinor/fusion-framework-module-state@1.0.0
+  - @equinor/fusion-framework-module@6.1.2
+
+## 12.0.5
+
+### Patch Changes
+
+- Updated dependencies [de2b4fb]
+  - @equinor/fusion-framework-module-app@8.0.4
+  - @equinor/fusion-framework-module-http@8.0.5
+  - @equinor/fusion-framework-app@11.0.12
+
 ## 12.0.4
 
 ### Patch Changes

package/README.md

@@ -106,6 +106,214 @@ 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);
+};
+```
+
+> [!CAUTION]
+> The state management module is a powerful tool, but it's important to know the potential pitfalls and limitations when using it in your application. The state management is global and can lead to unexpected behavior if not used carefully.
+>
+> __example 1:__ If you have multiple components that rely on the same state, updating the state in one component can cause re-renders in all components that use that state, potentially leading to performance issues.
+>
+> __example 2:__ The user has open multiple tabs of the application, and each tab is modifying the same state. This can lead to unexpected behavior, as changes made in one tab will be reflected to all tabs. _(like storing user preferences for selected columns)_
+
+### 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>
+);
+```
+
+### 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);
+```
+
+### Best Practices
+
+#### Avoid Stale Closures
+> [!WARNING]
+> 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);
+ ```
+
+#### State Key Organization
+
+Use hierarchical naming for better organization:
+
+```typescript
+// ✅ Good - hierarchical, descriptive
+'user.profile.personal'
+'user.preferences.theme'
+'app.settings.notifications'
+'feature.dashboard.filters'
+
+// ❌ Avoid - flat, unclear
+'userdata'
+'settings'
+'stuff'
+```
+
+#### Use strong typing
+
+```typescript
+// ✅ Good - strong typing
+interface UserProfile {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const [user, setUser] = useAppState<UserProfile>('user.profile');
+
+// ❌ Avoid - weak typing
+const [user, setUser] = useAppState('user.profile');
+```
+
+> [!TIP] Validate Complex Schemas
+> Use a library like `zod` or `yup` to validate complex state schemas before using them.
+> ```typescript
+> const userSchema = z.object({
+>   id: z.string().uuid(),
+>   name: z.string().min(2).max(100),
+>   email: z.string().email(),
+> });
+>
+> type UserProfile = z.infer<typeof userSchema>;
+>
+> // ✅ Good - strong typing with validation
+> const useMyUser = () => {
+>   const [value, setValue] = useAppState<UserProfile>('user.profile');
+>   const setUser = useCallback((user: UserProfile) => {
+>     if (userSchema.safeParse(user).success) {
+>       setValue(user);
+>       return true;
+>     } else {
+>       console.warn('Provided user is invalid');
+>       return false;
+>     }
+>   }, [setValue]);
+>   if(!userSchema.safeParse(value).success) {
+>     console.warn('Current user state is invalid');
+>     return null;
+>   }
+>   return value;
+> };
+> ```
+
+## Feature Flag
+
 ### Feature flags
 
 > **Note:** Requires `@equinor/fusion-framework-module-feature-flag`.

package/dist/esm/state/index.js

@@ -0,0 +1,5 @@
+export { StateSyncEvent, } 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';
+//# sourceMappingURL=index.js.map

package/dist/esm/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,GAEf,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,WAAW,IAAI,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAE3F,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/esm/state/useAppState.js

@@ -0,0 +1,247 @@
+import { useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, } from 'react';
+import { BehaviorSubject, from } from 'rxjs';
+import { map, skip } from 'rxjs/operators';
+import useAppModule from '../useAppModule';
+/**
+ * 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 = (key, options) => {
+    // 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('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(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(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) => (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) => {
+        // 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;
+//# sourceMappingURL=useAppState.js.map

package/dist/esm/state/useAppState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppState.js","sourceRoot":"","sources":["../../../src/state/useAppState.ts"],"names":[],"mappings":"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"}

package/dist/esm/state/useStateSyncEvents.js

@@ -0,0 +1,48 @@
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { BehaviorSubject } from 'rxjs';
+import { filter } from 'rxjs/operators';
+import { StateSyncEvent } 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) => {
+    const eventProvider = useAppModule('event');
+    const [event$] = useState(() => new BehaviorSubject([]));
+    // 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;
+//# sourceMappingURL=useStateSyncEvents.js.map

package/dist/esm/state/useStateSyncEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateSyncEvents.js","sourceRoot":"","sources":["../../../src/state/useStateSyncEvents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGxC,OAAO,EAAE,cAAc,EAA2B,MAAM,wCAAwC,CAAC;AAEjG,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAa,EAAwB,EAAE;IACxE,MAAM,aAAa,GAAG,YAAY,CAAc,OAAO,CAAC,CAAC;IACzD,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,eAAe,CAAuB,EAAE,CAAC,CAAC,CAAC;IAE/E,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC;IAEzB,eAAe,CAAC,GAAG,EAAE;QACnB,oFAAoF;QACpF,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5F,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;YAC3C,sFAAsF;YACtF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClF,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5B,OAAO,oBAAoB,CACzB,CAAC,QAAQ,EAAE,EAAE;QACX,MAAM,YAAY,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAChD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EACD,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EACvB,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,CACxB,CAAC;AACJ,CAAC,CAAC;AAEF,eAAe,kBAAkB,CAAC"}

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export const version = '12.0.4';
+export const version = '13.0.0';
 //# sourceMappingURL=version.js.map