@finsweet/webflow-apps-utils 1.0.4 → 1.0.5

package/dist/providers/GlobalProvider.stories.d.ts

@@ -0,0 +1,5 @@
+import type { Meta, StoryObj } from '@storybook/sveltekit';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Interactive: Story;

package/dist/providers/GlobalProvider.stories.js

@@ -0,0 +1,419 @@
+import GlobalProviderDemo from './GlobalProviderDemo.svelte';
+const meta = {
+    title: 'Utils/GlobalProvider',
+    component: GlobalProviderDemo,
+    parameters: {
+        layout: 'centered',
+        backgrounds: {
+            default: 'dark',
+            values: [
+                { name: 'dark', value: '#292929' },
+                { name: 'light', value: '#ffffff' }
+            ]
+        },
+        docs: {
+            description: {
+                component: `
+# GlobalProvider
+
+The \`GlobalProvider\` is a comprehensive context management system built on Svelte 5 that manages multiple application contexts in a type-safe and reactive way. It includes advanced configurator state management with intelligent change detection using the DiffMapper utilities.
+
+## 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)
+- **Intelligent Change Detection**: Uses DiffMapper for smart configurator state comparison
+- **Performance Optimized**: Includes caching, debouncing, and memory management
+- **Advanced Configurator Support**: Built-in configurator state with watch options and change tracking
+
+## Basic Usage
+
+### Wrap Your App
+
+\`\`\`svelte
+<script lang="ts">
+	import { GlobalProvider } from './';
+
+	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 './';
+
+	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
+
+## Advanced Configurator Support
+
+The \`GlobalProvider\` includes sophisticated configurator state management with intelligent change detection powered by the DiffMapper utilities. The configurator system automatically detects changes using smart type coercion, whitespace handling, and performance optimization.
+
+### Core Configurator Features
+
+- **Automatic Change Detection**: Uses \`hasChangesViaDiff\` internally for intelligent comparison
+- **Type Coercion**: Handles string/number/boolean conversions automatically
+- **Watch Options**: Configure which keys to monitor for changes
+- **Debounced Updates**: Performance-optimized change detection with configurable debouncing
+- **Caching**: Automatic caching for expensive diff operations
+
+### Using the Configurator Context
+
+\`\`\`svelte
+<script lang="ts">
+	import { useConfiguratorContext, useAppContext } from './';
+
+	// 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, min: 16ms)
+}
+\`\`\`
+
+### Change Detection Examples
+
+The configurator uses intelligent change detection that handles various edge cases:
+
+\`\`\`typescript
+// Type coercion examples - these are considered UNCHANGED
+const config1 = { count: '5', active: 'true', value: '' };
+const config2 = { count: 5, active: true, value: 0 };
+
+configurator.setConfigurator(config1);
+configurator.setConfiguratorCache(config2);
+console.log(configurator.hasChanged); // false - intelligent type coercion
+
+// Whitespace handling - these are considered UNCHANGED
+const config3 = { name: 'John' };
+const config4 = { name: '  John  ' };
+
+// Nested object changes - detected intelligently
+const config5 = { user: { name: 'John', age: 30 }, settings: { theme: 'dark' } };
+const config6 = { user: { name: 'John', age: 31 }, settings: { theme: 'dark' } };
+// Only user.age is different, hasChanged will be true
+\`\`\`
+
+## TypeScript Support
+
+### Generic Context Usage
+
+\`\`\`typescript
+import type { ContextOperations, AppContextData, DataContextData } from './';
+
+// 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
+\`\`\`
+
+## Utility Helper Functions
+
+The GlobalProvider system includes several powerful utility functions for advanced use cases and manual comparisons.
+
+### DiffMapper Utilities
+
+For detailed object comparison and change analysis:
+
+\`\`\`typescript
+import { hasChangesViaDiff, getDetailedDiff, compareKeys } from './';
+
+// Quick change detection
+const hasChanges = hasChangesViaDiff(oldConfig, newConfig);
+
+// Detailed diff analysis
+const diff = getDetailedDiff(oldConfig, newConfig);
+console.log(diff);
+// Returns detailed DiffMap showing exactly what changed
+
+// Compare specific keys only
+const hasKeyChanges = !compareKeys(oldConfig, newConfig, ['theme', 'layout']);
+\`\`\`
+
+### Configurator Utilities
+
+For manual configurator state management:
+
+\`\`\`typescript
+import {
+	createDefaultConfiguratorState,
+	hasConfiguratorChanged,
+	validateWatchOptions,
+	extractKeys,
+	createDebouncedUpdate
+} from './';
+
+// Create default configurator state
+const defaultState = createDefaultConfiguratorState<MyConfigType>();
+
+// Manual change detection with watch options
+const watchOptions = { watchKeys: ['theme'], debounceMs: 100 };
+const hasChanged = hasConfiguratorChanged(current, cached, watchOptions);
+
+// Validate and normalize watch options
+const validatedOptions = validateWatchOptions(userOptions);
+
+// Extract specific keys from configuration
+const extractedConfig = extractKeys(fullConfig, ['theme', 'layout']);
+
+// Create debounced update function
+const debouncedSave = createDebouncedUpdate(saveConfig, 300);
+\`\`\`
+
+### Performance Optimization Helpers
+
+\`\`\`typescript
+import { createDebouncedUpdate } from './';
+
+// Create debounced functions for expensive operations
+const debouncedValidation = createDebouncedUpdate((config) => {
+	// Expensive validation logic
+	validateConfiguration(config);
+}, 500); // 500ms debounce
+
+// Use in components
+function handleConfigChange(newConfig) {
+	setConfig(newConfig);
+	debouncedValidation(newConfig);
+}
+\`\`\`
+
+### Memory Management
+
+The GlobalProvider includes automatic memory management for performance:
+
+\`\`\`typescript
+// Automatic cache cleanup in diff operations
+// Cache entries older than 1 second are automatically removed
+// Cache size is limited to 100 entries
+
+// Event listener cleanup
+const unsubscribe = globalContext.subscribe((event) => {
+	console.log('Context changed:', event);
+});
+
+// Always clean up subscriptions
+onDestroy(() => {
+	unsubscribe();
+});
+\`\`\`
+
+### Debugging and Development
+
+For development and debugging:
+
+\`\`\`typescript
+// Enable debug mode in GlobalProvider
+<GlobalProvider debug={true} initialContexts={...}>
+
+// Get context metadata
+const metadata = globalContext.getContextMetadata('app');
+console.log(metadata);
+// { updatedAt: 1234567890, version: 5, isActive: true }
+
+// Get all active contexts
+const activeContexts = globalContext.getActiveContexts();
+console.log(activeContexts); // ['app', 'form', 'data', 'userPreferences']
+
+// Get complete state snapshot
+const allData = globalContext.getAllContexts();
+console.log(allData); // Complete state object
+\`\`\`
+
+### Error Handling Best Practices
+
+\`\`\`typescript
+try {
+	const context = getGlobalContext();
+	const appData = context.getContext('app').get();
+	// Handle operations...
+} catch (error) {
+	if (error.message.includes('Global context not found')) {
+		console.error('GlobalProvider not found. Make sure to wrap your app properly.');
+	}
+}
+
+// Safe context access with fallbacks
+const safeGetContext = <T>(key: string): T | null => {
+	try {
+		const context = getGlobalContext();
+		return context.getContext<T>(key).get();
+	} catch {
+		return null;
+	}
+};
+\`\`\`
+
+## Related Documentation
+
+- **Performance Considerations**: All diff operations include automatic caching and optimization
+- **Type Safety**: Full TypeScript support with branded types and generics
+
+Click the buttons in the interactive demo below to see these features in action!
+				`
+            }
+        }
+    },
+    tags: ['autodocs']
+};
+export default meta;
+export const Interactive = {
+    name: 'Interactive Demo',
+    parameters: {
+        docs: {
+            description: {
+                story: 'Interactive demo showing GlobalProvider features including context management, configurator state, and change detection.'
+            }
+        }
+    }
+};

package/dist/providers/GlobalProviderDemo.svelte

@@ -0,0 +1,266 @@
+<script lang="ts">
+	import { onDestroy } from 'svelte';
+
+	import { GlobalProvider, useAppContext, useConfiguratorContext, useFormContext } from './index';
+
+	// Demo configurator type
+	type DemoConfigType = {
+		theme: 'light' | 'dark';
+		layout: 'grid' | 'list';
+		itemsPerPage: number;
+	};
+
+	const initialContexts = {
+		app: {
+			editMode: false,
+			repairMode: false,
+			title: 'GlobalProvider Demo',
+			configurator: {
+				configurator: { theme: 'light', layout: 'grid', itemsPerPage: 10 },
+				configuratorCache: { theme: 'light', layout: 'grid', itemsPerPage: 10 },
+				hasChanged: false,
+				watchOptions: { watchAll: true, watchKeys: [], debounceMs: 100 }
+			}
+		},
+		form: {
+			formKey: 'demo-form',
+			formUpdateKey: null
+		}
+	};
+
+	let demoStarted = $state(false);
+
+	function startDemo() {
+		demoStarted = true;
+	}
+
+	// Simple demo state management
+	let refreshTrigger = $state(0);
+
+	function forceRefresh() {
+		refreshTrigger++;
+	}
+</script>
+
+<div class="demo-container">
+	{#if !demoStarted}
+		<div class="start-demo">
+			<h3>GlobalProvider Interactive Demo</h3>
+			<p>Click below to start the demo and explore GlobalProvider features.</p>
+			<button onclick={startDemo} class="btn btn--primary">Start Demo</button>
+		</div>
+	{:else}
+		<GlobalProvider {initialContexts} debug={false}>
+			{@render DemoContent()}
+		</GlobalProvider>
+	{/if}
+</div>
+
+{#snippet DemoContent()}
+	<!-- Get contexts and data reactively -->
+	{@const appContext = useAppContext<DemoConfigType>()}
+	{@const formContext = useFormContext()}
+	{@const configuratorContext = useConfiguratorContext<DemoConfigType>()}
+
+	<!-- Force reactive updates with trigger -->
+	{#key refreshTrigger}
+		{@const appData = appContext.get()}
+		{@const formData = formContext.get()}
+		{@const configuratorData = configuratorContext.configurator}
+		{@const hasChanged = configuratorContext.hasChanged}
+
+		<div class="demo-content">
+			<h3>GlobalProvider Demo</h3>
+
+			<div class="context-section">
+				<h4>App Context</h4>
+				<p>Edit Mode: <strong>{appData?.editMode ? 'ON' : 'OFF'}</strong></p>
+				<p>Title: <strong>{appData?.title || 'N/A'}</strong></p>
+				<button
+					onclick={() => {
+						const current = appContext.get();
+						appContext.set({
+							...current,
+							editMode: !current?.editMode
+						});
+						forceRefresh();
+					}}
+					class="btn btn--secondary"
+				>
+					Toggle Edit Mode
+				</button>
+			</div>
+
+			<div class="context-section">
+				<h4>Form Context</h4>
+				<p>Form Key: <strong>{formData?.formKey || 'N/A'}</strong></p>
+				<button
+					onclick={() => {
+						const current = formContext.get();
+						formContext.set({
+							...current,
+							formKey: `form-${Date.now()}`
+						});
+						forceRefresh();
+					}}
+					class="btn btn--secondary"
+				>
+					Update Form Key
+				</button>
+			</div>
+
+			<div class="context-section">
+				<h4>Configurator Context</h4>
+				<p>Theme: <strong>{configuratorData?.theme || 'N/A'}</strong></p>
+				<p>Layout: <strong>{configuratorData?.layout || 'N/A'}</strong></p>
+				<p>Items Per Page: <strong>{configuratorData?.itemsPerPage || 'N/A'}</strong></p>
+				<p>
+					Has Changed: <strong class="status-{hasChanged}">{hasChanged ? 'YES' : 'NO'}</strong>
+				</p>
+
+				<div class="button-group">
+					<button
+						onclick={() => {
+							const current = configuratorContext.configurator;
+							if (current) {
+								configuratorContext.setConfigurator({
+									...current,
+									theme: current.theme === 'light' ? 'dark' : 'light'
+								});
+								forceRefresh();
+							}
+						}}
+						class="btn btn--secondary"
+					>
+						Toggle Theme
+					</button>
+					<button
+						onclick={() => {
+							configuratorContext.saveToCache();
+							forceRefresh();
+						}}
+						class="btn btn--primary"
+					>
+						Save to Cache
+					</button>
+				</div>
+			</div>
+
+			<div class="context-section">
+				<h4>Debug Info</h4>
+				<p>App Data: <code>{JSON.stringify(appData, null, 2)}</code></p>
+				<p>Form Data: <code>{JSON.stringify(formData, null, 2)}</code></p>
+				<p>Configurator Data: <code>{JSON.stringify(configuratorData, null, 2)}</code></p>
+			</div>
+		</div>
+	{/key}
+{/snippet}
+
+<style>
+	.demo-container {
+		padding: 1rem;
+		max-width: 600px;
+		margin: 0 auto;
+		background: var(--background1);
+		color: var(--text1);
+		font-family: var(--font-stack);
+	}
+
+	.start-demo {
+		text-align: center;
+		padding: 2rem;
+		border: 2px dashed var(--border2);
+		border-radius: var(--border-radius);
+		background: var(--background2);
+	}
+
+	.demo-content {
+		display: flex;
+		flex-direction: column;
+		gap: 1.5rem;
+	}
+
+	.context-section {
+		padding: 1rem;
+		border: 1px solid var(--border2);
+		border-radius: var(--border-radius);
+		background: var(--background2);
+	}
+
+	.context-section h4 {
+		margin: 0 0 0.5rem 0;
+		color: var(--text1);
+		font-size: var(--font-size-large);
+		font-weight: var(--font-weight-medium);
+	}
+
+	.context-section p {
+		margin: 0.25rem 0;
+		font-size: var(--font-size-small);
+		color: var(--text2);
+	}
+
+	.button-group {
+		display: flex;
+		gap: 0.5rem;
+		margin-top: 0.75rem;
+	}
+
+	.btn {
+		padding: var(--padding-small) var(--padding-regular);
+		border: none;
+		border-radius: var(--border-radius);
+		cursor: pointer;
+		font-size: var(--font-size-small);
+		font-weight: var(--font-weight-normal);
+		font-family: var(--font-stack);
+		transition: all 0.2s ease;
+	}
+
+	.btn--primary {
+		background: var(--actionPrimaryBackground);
+		color: var(--actionPrimaryText);
+		box-shadow: var(--boxShadows-action-colored);
+	}
+
+	.btn--primary:hover {
+		background: var(--actionPrimaryBackgroundHover);
+		color: var(--actionPrimaryTextHover);
+	}
+
+	.btn--secondary {
+		background: var(--actionSecondaryBackground);
+		color: var(--actionSecondaryText);
+		box-shadow: var(--boxShadows-action-secondary);
+	}
+
+	.btn--secondary:hover {
+		background: var(--actionSecondaryBackgroundHover);
+		color: var(--actionSecondaryTextHover);
+	}
+
+	.status-true {
+		color: var(--redText);
+		font-weight: var(--font-weight-medium);
+	}
+
+	.status-false {
+		color: var(--greenText);
+		font-weight: var(--font-weight-medium);
+	}
+
+	code {
+		background: var(--background3);
+		border: 1px solid var(--border2);
+		padding: var(--padding-tiny);
+		border-radius: var(--border-radius);
+		font-family: monospace;
+		font-size: var(--font-size-small);
+		color: var(--text2);
+		display: block;
+		margin-top: var(--spacing-4);
+		white-space: pre-wrap;
+		max-height: 150px;
+		overflow-y: auto;
+	}
+</style>

package/dist/providers/GlobalProviderDemo.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const GlobalProviderDemo: import("svelte").Component<Record<string, never>, {}, "">;
+type GlobalProviderDemo = ReturnType<typeof GlobalProviderDemo>;
+export default GlobalProviderDemo;