@finsweet/webflow-apps-utils 1.0.4 → 1.0.6

package/dist/providers/GlobalProvider.mdx

@@ -1,322 +0,0 @@
-# GlobalProvider
-
-The `GlobalProvider` is a context management system built on Svelte 5 that manages multiple application contexts in a type-safe and reactive way.
-
-## Features
-
-- **Multiple Contexts**: Manage different types of state (form, app, data, etc.) in separate contexts
-- **Type Safety**: Full TypeScript support with branded types and generics
-- **Reactive**: Built on Svelte 5 runes for optimal reactivity
-- **Event System**: Subscribe to context changes and global events (batched for performance)
-
-## Basic Usage
-
-### Wrap Your App
-
-```svelte
-<script lang="ts">
-	import { GlobalProvider } from '$lib/providers';
-
-	const initialContexts = {
-		app: {
-			editMode: false,
-			repairMode: false,
-			title: 'My App'
-		},
-		form: {
-			formKey: null,
-			formUpdateKey: null
-		}
-	};
-</script>
-
-<GlobalProvider {initialContexts} debug={true}>
-	<App />
-</GlobalProvider>
-```
-
-### Default Contexts
-
-The `GlobalProvider` automatically creates these default contexts:
-
-- **`app`**: Application state (editMode, repairMode, title, configurator)
-- **`form`**: Form state (formKey, formUpdateKey)
-- **`data`**: General data state
-
-### Use Contexts in Components
-
-```svelte
-<script lang="ts">
-	import { useAppContext, useFormContext, useDataContext } from '$lib/providers';
-
-	const appContext = useAppContext();
-	const formContext = useFormContext();
-	const dataContext = useDataContext();
-
-	let appData = $derived(appContext.get());
-	let formData = $derived(formContext.get());
-
-	function toggleEditMode() {
-		appContext.update((current) => ({
-			...current,
-			editMode: !current?.editMode
-		}));
-	}
-</script>
-
-<div>
-	<p>Edit Mode: {appData?.editMode}</p>
-	<p>Form Key: {formData?.formKey}</p>
-	<button onclick={toggleEditMode}>Toggle Edit Mode</button>
-</div>
-```
-
-## API Reference
-
-### Context Operations
-
-#### `get(): T | null`
-
-Returns the current context data. Returns `undefined` if the context has been reset (completely removed).
-
-#### `set(data: Partial<T>): void`
-
-Sets context data (merges with existing data).
-
-#### `update(updater: (current: T | null) => T): void`
-
-Updates context data using an updater function.
-
-#### `clear(): void`
-
-Clears context data (sets to null). The context remains active but with null data.
-
-#### `reset(): void`
-
-Completely removes the context. After reset, `hasContext()` returns false and `get()` returns `undefined`.
-
-#### `subscribe(callback: (data: T | null) => void): () => void`
-
-Subscribes to context changes. Returns unsubscribe function. **Note**: Events are batched and emitted asynchronously for performance.
-
-### Global Operations
-
-- `getContext<T>(key: string): ContextOperations<T>` - Get context operations for a key
-- `hasContext(key: string): boolean` - Check if context exists
-- `removeContext(key: string): void` - Remove a specific context
-- `clearAll(): void` - Clear all context data (set to null)
-- `resetAll(): void` - Reset all contexts (completely remove them)
-- `resetByKey(key: string): void` - Reset a specific context by key
-- `getActiveContexts(): string[]` - Get list of active context keys
-- `getAllContexts(): Record<string, unknown>` - Get all context data
-- `getContextMetadata(key: string)` - Get metadata (version, updatedAt, isActive) for a context
-- `subscribe(callback): () => void` - Subscribe to global context events
-
-## Examples
-
-### App State Management
-
-```svelte
-<script lang="ts">
-	import { useAppContext } from '$lib/providers';
-
-	const appContext = useAppContext();
-	let appData = $derived(appContext.get());
-
-	function handleSubmit() {
-		appContext.set({ editMode: true });
-	}
-</script>
-
-<form onsubmit={handleSubmit}>
-	<p>Edit Mode: {appData?.editMode}</p>
-	<button type="submit">Submit</button>
-</form>
-```
-
-### Custom Context
-
-```svelte
-<script lang="ts">
-	import { useContext } from '$lib/providers';
-
-	type UserContext = {
-		id: string;
-		name: string;
-		preferences: { theme: 'light' | 'dark' };
-	};
-
-	const userContext = useContext<UserContext>('user');
-	let userData = $derived(userContext.get());
-
-	function updateTheme(theme: 'light' | 'dark') {
-		userContext.update((current) => ({
-			...current!,
-			preferences: { ...current!.preferences, theme }
-		}));
-	}
-</script>
-```
-
-### Typed Data Context
-
-```svelte
-<script lang="ts">
-	import { useDataContext } from '$lib/providers';
-
-	type AppDataType = {
-		users: Array<{ id: string; name: string; email: string }>;
-		products: Array<{ id: string; title: string; price: number }>;
-		currentPage: number;
-		totalPages: number;
-	};
-
-	const dataContext = useDataContext<AppDataType>();
-	let appData = $derived(dataContext.get());
-
-	function loadUsers(users: AppDataType['users']) {
-		dataContext.set({
-			state: {
-				...appData?.state,
-				users,
-				currentPage: 1
-			}
-		});
-	}
-
-	function nextPage() {
-		if (appData?.state && appData.state.currentPage < appData.state.totalPages) {
-			dataContext.update((current) => ({
-				state: {
-					...current!.state!,
-					currentPage: current!.state!.currentPage + 1
-				}
-			}));
-		}
-	}
-</script>
-
-<div>
-	<p>Users: {appData?.state?.users?.length || 0}</p>
-	<p>Page: {appData?.state?.currentPage || 1} of {appData?.state?.totalPages || 1}</p>
-	<button onclick={nextPage}>Next Page</button>
-</div>
-```
-
-## Configurator Support
-
-The `GlobalProvider` includes built-in support for configurator state management with automatic change detection.
-
-### Using the Configurator Context
-
-```svelte
-<script lang="ts">
-	import { useConfiguratorContext, useAppContext } from '$lib/providers';
-
-	// Define your configurator type
-	type MyConfiguratorType = {
-		theme: 'light' | 'dark';
-		layout: 'grid' | 'list';
-		itemsPerPage: number;
-	};
-
-	// Use typed configurator context
-	const configurator = useConfiguratorContext<MyConfiguratorType>();
-
-	// Or use typed app context
-	const appContext = useAppContext<MyConfiguratorType>();
-
-	// Set configurator data with watch options (fully typed)
-	configurator.setConfigurator(
-		{ theme: 'dark', layout: 'grid', itemsPerPage: 10 },
-		{ watchKeys: ['theme'], debounceMs: 100 }
-	);
-
-	// Check if configurator has changed
-	let hasChanged = $derived(configurator.hasChanged);
-	let currentConfig = $derived(configurator.configurator); // Type: MyConfiguratorType | null
-	let cachedConfig = $derived(configurator.configuratorCache); // Type: MyConfiguratorType | null
-
-	// Save current state to cache
-	function saveToCache() {
-		configurator.saveToCache();
-	}
-</script>
-
-<div>
-	<p>Has Changed: {hasChanged}</p>
-	<p>Current Theme: {currentConfig?.theme}</p>
-	<p>Cached Theme: {cachedConfig?.theme}</p>
-	<button onclick={saveToCache}>Save to Cache</button>
-</div>
-```
-
-### Configurator API
-
-- `configurator` - Current configurator data
-- `configuratorCache` - Cached configurator data
-- `hasChanged` - Boolean indicating if configurator differs from cache
-- `watchOptions` - Current watch configuration
-- `setConfigurator(data, watchOptions?)` - Set configurator data
-- `setConfiguratorCache(data)` - Set cache data
-- `saveToCache()` - Save current configurator to cache
-- `updateWatchOptions(options)` - Update watch configuration
-
-### Watch Options
-
-```typescript
-interface ConfiguratorWatchOptions {
-	watchAll?: boolean; // Watch all keys (default: true)
-	watchKeys?: string[]; // Specific keys to watch
-	debounceMs?: number; // Debounce delay (default: 50ms)
-}
-```
-
-## TypeScript Support
-
-### Generic Context Usage
-
-```typescript
-import type { ContextOperations, AppContextData, DataContextData } from '$lib/providers';
-
-// For custom contexts
-const userContext: ContextOperations<UserType> = useContext<UserType>('user');
-
-// For typed app context with configurator
-type MyConfiguratorType = {
-	theme: 'light' | 'dark';
-	layout: 'grid' | 'list';
-};
-
-const appContext = useAppContext<MyConfiguratorType>();
-const configurator = useConfiguratorContext<MyConfiguratorType>();
-
-// For typed data context
-type MyDataType = {
-	users: User[];
-	products: Product[];
-	currentPage: number;
-};
-
-const dataContext = useDataContext<MyDataType>();
-
-// The configurator and configuratorCache will both be typed as MyConfiguratorType | null
-// The data context state will be typed as MyDataType | null
-```
-
-### Type Definitions
-
-```typescript
-// Your configurator type
-type MyConfiguratorType = {
-	theme: 'light' | 'dark';
-	layout: 'grid' | 'list';
-	itemsPerPage: number;
-};
-
-// App context will be typed as AppContextData<MyConfiguratorType>
-type MyAppContextType = AppContextData<MyConfiguratorType>;
-
-// Data context will be typed as DataContextData<MyDataType>
-type MyDataContextType = DataContextData<MyDataType>;
-```