@finsweet/webflow-apps-utils 1.0.3 → 1.0.5

package/dist/utils/diff-mapper/DiffMapper.stories.js

@@ -0,0 +1,185 @@
+import DiffMapperDemo from './DiffMapperDemo.svelte';
+const meta = {
+    title: 'Utils/DiffMapper',
+    component: DiffMapperDemo,
+    parameters: {
+        layout: 'centered',
+        backgrounds: {
+            default: 'dark',
+            values: [
+                { name: 'dark', value: '#292929' },
+                { name: 'light', value: '#ffffff' }
+            ]
+        },
+        docs: {
+            description: {
+                component: `
+# DiffMapper Utilities
+
+The DiffMapper utility provides intelligent object comparison with type coercion, whitespace handling, and advanced diff detection. Built specifically for configurator state management and general object comparison needs.
+
+## Features
+
+- **Smart Type Coercion**: Handles string/number/boolean conversions intelligently
+- **Whitespace Handling**: Automatically trims and compares string values
+- **Deep Comparison**: Recursively compares nested objects and arrays
+- **Performance Optimized**: Includes caching and circular reference detection
+- **Detailed Diff Output**: Provides granular change information
+- **Type Safety**: Full TypeScript support with proper type definitions
+
+## API Reference
+
+### Core Functions
+
+#### \`hasChangesViaDiff<T>(current: T, updated: T): boolean\`
+
+Determines if there are any meaningful changes between two objects.
+
+\`\`\`typescript
+const config1 = { theme: 'dark', notifications: true };
+const config2 = { theme: 'light', notifications: true };
+
+const hasChanges = hasChangesViaDiff(config1, config2); // true
+\`\`\`
+
+**Features:**
+- Automatic caching for performance
+- Type coercion handling
+- Whitespace normalization
+- Deep nested comparison
+
+#### \`getDetailedDiff<T>(current: T, updated: T): DiffResult | DiffMap\`
+
+Returns a detailed diff map showing exactly what changed.
+
+\`\`\`typescript
+const user1 = {
+  profile: { name: 'John', age: 30 },
+  settings: { theme: 'dark' }
+};
+
+const user2 = {
+  profile: { name: 'John', age: 31 },
+  settings: { theme: 'light', notifications: true }
+};
+
+const diff = getDetailedDiff(user1, user2);
+// Returns detailed diff structure showing exactly what changed
+\`\`\`
+
+### Diff Types
+
+\`\`\`typescript
+enum DiffType {
+	UNCHANGED = 'UNCHANGED', // Value is identical
+	UPDATED = 'UPDATED', // Value was modified
+	CREATED = 'CREATED', // Property was added
+	DELETED = 'DELETED' // Property was removed
+}
+\`\`\`
+
+## Type Coercion Examples
+
+The diff mapper intelligently handles type coercion:
+
+### String/Number Coercion
+\`\`\`typescript
+// These are considered UNCHANGED
+hasChangesViaDiff({ value: '42' }, { value: 42 }); // false
+hasChangesViaDiff({ value: '0' }, { value: 0 }); // false
+hasChangesViaDiff({ value: '' }, { value: 0 }); // false
+\`\`\`
+
+### String/Boolean Coercion
+\`\`\`typescript
+// These are considered UNCHANGED
+hasChangesViaDiff({ active: 'true' }, { active: true }); // false
+hasChangesViaDiff({ active: 'false' }, { active: false }); // false
+hasChangesViaDiff({ active: '' }, { active: false }); // false
+\`\`\`
+
+### Whitespace Handling
+\`\`\`typescript
+// These are considered UNCHANGED
+hasChangesViaDiff({ name: 'John' }, { name: '  John  ' }); // false
+hasChangesViaDiff({ value: '42' }, { value: ' 42 ' }); // false
+
+// But these are UPDATED (whitespace-only strings ≠ numbers)
+hasChangesViaDiff({ value: '  ' }, { value: 0 }); // true
+hasChangesViaDiff({ value: ' ' }, { value: false }); // true
+\`\`\`
+
+## Performance Features
+
+### Caching Strategy
+Results are cached for 1 second to avoid expensive re-computation:
+
+\`\`\`typescript
+const cacheKey = JSON.stringify([current, updated]);
+const cached = diffCache.get(cacheKey);
+
+if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
+  return cached.result;
+}
+\`\`\`
+
+### Memory Management
+Automatic cache cleanup when size exceeds 100 entries or TTL expires.
+
+## GlobalProvider Integration
+
+The diff mapper is seamlessly integrated with the GlobalProvider system:
+
+\`\`\`typescript
+import { useConfiguratorContext } from '../../providers';
+
+const configurator = useConfiguratorContext<MyConfigType>();
+
+// Automatic change detection using diff mapper
+const hasChanged = configurator.hasChanged; // Uses hasChangesViaDiff internally
+
+// Manual comparison
+const currentConfig = configurator.configurator;
+const cachedConfig = configurator.configuratorCache;
+const changes = getDetailedDiff(currentConfig, cachedConfig);
+\`\`\`
+
+## Usage with GlobalProvider
+
+For manual configurator state management:
+
+\`\`\`typescript
+import {
+	createDefaultConfiguratorState,
+	hasConfiguratorChanged,
+	validateWatchOptions,
+	extractKeys,
+	createDebouncedUpdate
+} from '../../providers';
+
+// 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);
+\`\`\`
+
+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: 'Click the buttons to run diff examples and see results. All functionality is combined in a single interactive demo.'
+            }
+        }
+    }
+};

package/dist/utils/diff-mapper/DiffMapperDemo.svelte

@@ -0,0 +1,351 @@
+<script lang="ts">
+	import { getDetailedDiff, hasChangesViaDiff } from '../../providers/configuratorUtils';
+
+	let output = '';
+	let coercionExamples = '';
+	let performanceResults = '';
+	let deepOutput = '';
+
+	function runDiffExamples() {
+		// Example 1: Basic object comparison
+		const obj1 = { name: 'John', age: 30, active: 'true' };
+		const obj2 = { name: 'John', age: 31, active: true };
+
+		// @ts-expect-error - intentional type mismatch for demo
+		const hasChanges = hasChangesViaDiff(obj1, obj2);
+		// @ts-expect-error - intentional type mismatch for demo
+		const detailedDiff = getDetailedDiff(obj1, obj2);
+
+		// Example 2: Nested object comparison
+		const nested1 = {
+			user: { profile: { name: 'John', settings: { theme: 'dark' } } },
+			items: [{ id: 1, name: 'Item 1' }]
+		};
+
+		const nested2 = {
+			user: { profile: { name: 'John', settings: { theme: 'light' } } },
+			items: [
+				{ id: 1, name: 'Item 1' },
+				{ id: 2, name: 'Item 2' }
+			]
+		};
+
+		const nestedChanges = hasChangesViaDiff(nested1, nested2);
+		const nestedDiff = getDetailedDiff(nested1, nested2);
+
+		// Example 3: Type coercion examples
+		const coercion1 = { count: '5', enabled: '', value: '0' };
+		const coercion2 = { count: 5, enabled: false, value: 0 };
+		// @ts-expect-error - intentional type mismatch for demo
+		const coercionChanges = hasChangesViaDiff(coercion1, coercion2);
+
+		output = `
+📊 DIFF MAPPER RESULTS
+
+1. Basic Object Comparison:
+   Object 1: ${JSON.stringify(obj1)}
+   Object 2: ${JSON.stringify(obj2)}
+   Has Changes: ${hasChanges}
+   Age changed from 30 to 31, but 'true' === true (type coercion)
+
+2. Nested Object Comparison:
+   Has Changes: ${nestedChanges}
+   Theme changed from 'dark' to 'light'
+   New item added to array
+
+3. Type Coercion Examples:
+   Object 1: ${JSON.stringify(coercion1)}
+   Object 2: ${JSON.stringify(coercion2)}
+   Has Changes: ${coercionChanges}
+   All values are equivalent due to intelligent type coercion!
+
+📝 Check the browser console for detailed diff objects.
+		`;
+
+		// Log detailed results to console
+		console.group('🔍 DiffMapper Detailed Results');
+		console.log('Basic diff:', detailedDiff);
+		console.log('Nested diff:', nestedDiff);
+		console.groupEnd();
+	}
+
+	function generateCoercionExamples() {
+		const examples = [
+			[{ value: '42' }, { value: 42 }, 'String "42" equals number 42'],
+			[{ active: 'true' }, { active: true }, 'String "true" equals boolean true'],
+			[{ empty: '' }, { empty: 0 }, 'Empty string equals number 0'],
+			[{ name: 'John' }, { name: '  John  ' }, 'Whitespace is trimmed'],
+			[{ enabled: 'false' }, { enabled: false }, 'String "false" equals boolean false']
+		];
+
+		let html = '<div style="display: grid; gap: 10px;">';
+
+		examples.forEach(([obj1, obj2, description]) => {
+			const hasChanges = hasChangesViaDiff(obj1, obj2);
+			const status = hasChanges ? '❌ DIFFERENT' : '✅ SAME';
+			const color = hasChanges ? 'var(--redText)' : 'var(--greenText)';
+
+			html += `
+				<div class="coercion-example">
+					<div style="color: ${color}; font-weight: var(--font-weight-medium); margin-bottom: var(--spacing-4);">${status}</div>
+					<div style="color: var(--text1);"><strong>A:</strong> ${JSON.stringify(obj1)}</div>
+					<div style="color: var(--text1);"><strong>B:</strong> ${JSON.stringify(obj2)}</div>
+					<div style="color: var(--text3); font-style: italic; margin-top: var(--spacing-4);">${description}</div>
+				</div>
+			`;
+		});
+
+		html += '</div>';
+		coercionExamples = html;
+	}
+
+	function runPerformanceTest() {
+		// Create large objects for testing
+		const createLargeObject = (size: number) => {
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			const obj: Record<string, any> = {};
+			for (let i = 0; i < size; i++) {
+				obj[`key${i}`] = {
+					id: i,
+					name: `Item ${i}`,
+					nested: {
+						value: Math.random(),
+						timestamp: Date.now()
+					}
+				};
+			}
+			return obj;
+		};
+
+		const obj1 = createLargeObject(100);
+		const obj2 = { ...obj1 };
+		obj2.key50.nested.value = 999; // Change one value
+
+		// Measure performance
+		const start = performance.now();
+		const hasChanges = hasChangesViaDiff(obj1, obj2);
+		const end = performance.now();
+
+		// Test caching - second call should be faster
+		const start2 = performance.now();
+		hasChangesViaDiff(obj1, obj2);
+		const end2 = performance.now();
+
+		performanceResults = `
+			<div class="performance-result">
+				<h4>Performance Test Results</h4>
+				<div><strong>Object Size:</strong> 100 nested objects</div>
+				<div><strong>Change Detected:</strong> ${hasChanges ? 'Yes' : 'No'}</div>
+				<div><strong>First Call:</strong> ${(end - start).toFixed(2)}ms</div>
+				<div><strong>Cached Call:</strong> ${(end2 - start2).toFixed(2)}ms</div>
+				<div style="color: var(--greenText); margin-top: var(--spacing-12); font-weight: var(--font-weight-medium);">
+					⚡ ${((end - start) / (end2 - start2)).toFixed(1)}x faster with caching!
+				</div>
+			</div>
+		`;
+
+		console.log('Performance test completed:', {
+			hasChanges,
+			firstCall: end - start,
+			cachedCall: end2 - start2,
+			speedup: (end - start) / (end2 - start2)
+		});
+	}
+
+	function runDeepTest() {
+		const deepObj1 = {
+			level1: {
+				level2: {
+					level3: {
+						level4: {
+							data: 'original',
+							count: 42,
+							items: [1, 2, 3]
+						}
+					}
+				}
+			}
+		};
+
+		const deepObj2 = {
+			level1: {
+				level2: {
+					level3: {
+						level4: {
+							data: 'modified',
+							count: 42,
+							items: [1, 2, 3, 4]
+						}
+					}
+				}
+			}
+		};
+
+		const hasChanges = hasChangesViaDiff(deepObj1, deepObj2);
+		const diff = getDetailedDiff(deepObj1, deepObj2);
+
+		deepOutput = `
+Deep Object Comparison Results:
+
+Has Changes: ${hasChanges}
+
+Changes detected:
+- level1.level2.level3.level4.data: "original" → "modified"
+- level1.level2.level3.level4.items: Array length changed (3 → 4)
+
+The diff mapper successfully navigated 4 levels deep to detect specific changes!
+
+See console for the complete diff structure.
+		`;
+
+		console.log('Deep nesting diff:', diff);
+	}
+</script>
+
+<div class="demo-container">
+	<h3>DiffMapper Utilities Demo</h3>
+	<p>Open the browser console to see diff results.</p>
+	<button class="btn btn--primary" onclick={runDiffExamples}>Run Diff Examples</button>
+	<pre class="output-block">{output}</pre>
+
+	<hr class="divider" />
+
+	<h3>Type Coercion Examples</h3>
+	<button class="btn btn--primary" onclick={generateCoercionExamples}>Show Type Coercion</button>
+	<div class="examples-container">
+		{@html coercionExamples}
+	</div>
+
+	<hr class="divider" />
+
+	<h3>Performance Features</h3>
+	<button class="btn btn--primary" onclick={runPerformanceTest}>Run Performance Test</button>
+	<div class="results-container">
+		{@html performanceResults}
+	</div>
+
+	<hr class="divider" />
+
+	<h3>Deep Nesting Comparison</h3>
+	<button class="btn btn--primary" onclick={runDeepTest}>Test Deep Objects</button>
+	<pre class="output-block small">{deepOutput}</pre>
+</div>
+
+<style>
+	.demo-container {
+		padding: var(--spacing-24);
+		font-family: var(--font-stack);
+		background: var(--background1);
+		color: var(--text1);
+		max-width: 800px;
+		margin: 0 auto;
+	}
+
+	h3 {
+		color: var(--text1);
+		font-size: var(--font-size-large);
+		font-weight: var(--font-weight-medium);
+		margin: var(--spacing-16) 0 var(--spacing-8) 0;
+	}
+
+	p {
+		color: var(--text2);
+		font-size: var(--font-size-small);
+		margin: var(--spacing-8) 0;
+	}
+
+	.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;
+		margin: var(--spacing-8) 0;
+	}
+
+	.btn--primary {
+		background: var(--actionPrimaryBackground);
+		color: var(--actionPrimaryText);
+		box-shadow: var(--boxShadows-action-colored);
+	}
+
+	.btn--primary:hover {
+		background: var(--actionPrimaryBackgroundHover);
+		color: var(--actionPrimaryTextHover);
+	}
+
+	.output-block {
+		background: var(--background2);
+		border: 1px solid var(--border2);
+		padding: var(--spacing-12);
+		margin-top: var(--spacing-12);
+		white-space: pre-wrap;
+		border-radius: var(--border-radius);
+		font-family: monospace;
+		color: var(--text2);
+		font-size: var(--font-size-small);
+	}
+
+	.output-block.small {
+		font-size: var(--font-size-small);
+	}
+
+	.divider {
+		border: none;
+		border-top: 1px solid var(--border2);
+		margin: var(--spacing-32) 0;
+	}
+
+	.examples-container,
+	.results-container {
+		margin-top: var(--spacing-16);
+	}
+
+	/* Dynamic HTML content styling */
+	:global(.examples-container > div) {
+		display: grid;
+		gap: var(--spacing-12);
+	}
+
+	:global(.coercion-example) {
+		padding: var(--spacing-12);
+		border: 1px solid var(--border2);
+		border-radius: var(--border-radius);
+		background: var(--background2);
+	}
+
+	:global(.performance-result) {
+		background: var(--background2);
+		border: 1px solid var(--border2);
+		padding: var(--spacing-16);
+		border-radius: var(--border-radius);
+	}
+
+	:global(.results-container > div) {
+		background: var(--background2);
+		border: 1px solid var(--border2);
+		padding: var(--spacing-16);
+		border-radius: var(--border-radius);
+	}
+
+	:global(.results-container h4) {
+		color: var(--text1);
+		font-size: var(--font-size-large);
+		font-weight: var(--font-weight-medium);
+		margin: 0 0 var(--spacing-8) 0;
+	}
+
+	:global(.results-container div) {
+		color: var(--text2);
+		font-size: var(--font-size-small);
+		margin: var(--spacing-4) 0;
+	}
+
+	:global(.results-container strong) {
+		color: var(--text1);
+		font-weight: var(--font-weight-medium);
+	}
+</style>

package/dist/utils/diff-mapper/DiffMapperDemo.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const DiffMapperDemo: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type DiffMapperDemo = InstanceType<typeof DiffMapperDemo>;
+export default DiffMapperDemo;

package/dist/utils/diff-mapper/deepDiffMapper.d.ts

@@ -0,0 +1,31 @@
+export declare enum DiffType {
+    CREATED = "created",
+    UPDATED = "updated",
+    DELETED = "deleted",
+    UNCHANGED = "unchanged"
+}
+export interface DiffResult {
+    type: DiffType;
+    data: any;
+}
+export type DiffMap = {
+    [key: string]: DiffResult | DiffMap;
+};
+export type ComparableValue = any;
+declare class DeepDiffMapper {
+    private visitedPairs;
+    private isFunction;
+    private isArray;
+    private isDate;
+    private isObject;
+    private isValue;
+    private compareValues;
+    private areEquivalentPrimitives;
+    private hasCircularReference;
+    private _map;
+    map(obj1: ComparableValue, obj2: ComparableValue): DiffResult | DiffMap;
+    compare(obj1: ComparableValue, obj2: ComparableValue): DiffResult | DiffMap;
+}
+export declare const deepDiffMapper: DeepDiffMapper;
+export { DeepDiffMapper };
+export declare function compareObjects(obj1: ComparableValue, obj2: ComparableValue): DiffResult | DiffMap;