@finsweet/webflow-apps-utils 1.0.2 → 1.0.3

package/README.md

@@ -4,6 +4,8 @@
 
 Shared UI components and utilities for Finsweet's Webflow applications.
 
+🔗 **[Live Storybook Documentation](https://webflow-apps-utils.pages.dev)**
+
 ## Installation
 
 ```bash
@@ -15,7 +17,165 @@ pnpm add @finsweet/webflow-apps-utils
 ```typescript
 import '@finsweet/webflow-apps-utils/index.css';
 
-import { Button, Modal, Input, breakpointStore } from '@finsweet/webflow-apps-utils';
+import { Button, Modal, Input, siteInfo } from '@finsweet/webflow-apps-utils';
+```
+
+## Project Structure
+
+```
+src/
+├── lib/
+│   ├── router/          # Client-side routing utilities
+│   ├── stores/          # Stores for state management
+│   ├── types/           # TypeScript type definitions
+│   ├── ui/              # UI components and styling
+│   │   ├── components/  # Reusable UI components
+│   │   └── icons/       # SVG icon components
+│   └── utils/           # Helper functions and utilities
+```
+
+## Coding Standards
+
+### Naming Conventions
+
+#### File and Folder Names
+
+- **Folders**: Use `kebab-case` for all directory names
+
+  ```
+  ✅ custom-code/
+  ✅ webflow-canvas/
+  ✅ browser-storage/
+  ❌ customCode/
+  ❌ WebflowCanvas/
+  ```
+
+- **Files**: Use `camelCase` and `PascalCase` for all file names
+
+  ```
+  ✅ localStorage.ts
+  ✅ handlePaste.ts
+  ✅ getAllAssets.ts
+  ✅ Button.svelte
+  ✅ Form.svelte
+  ❌ local-storage.ts
+  ❌ handle_paste.ts
+  ❌ form.svelte
+
+  ```
+
+#### Code Naming
+
+- **Components**: Use `PascalCase` for component names
+- **Functions**: Use `camelCase` for function names
+- **Variables**: Use `camelCase` for variable names
+- **Constants**: Use `UPPERCASE` for constants
+- **Types/Interfaces**: Use `PascalCase` for type definitions
+
+### Documentation Standards
+
+- Keep function documentation concise
+
+## Testing UI Components
+
+### Testing Strategy
+
+All UI components should include comprehensive tests covering:
+
+- **Basic Rendering**: Default props, custom props, and various configurations
+- **Component Variants**: All available variants (primary, secondary, danger, etc.)
+- **Interactive States**: Disabled, loading, invalid, and other state combinations
+- **User Interactions**: Click events, keyboard navigation, and form submissions
+- **Accessibility**: ARIA attributes, focus management, and screen reader support
+- **Visual Features**: Icons, tooltips, custom styling, and layout variations
+
+### Test Structure
+
+Use Vitest and Testing Library for component testing:
+
+```typescript
+import { fireEvent, render, screen, waitFor } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import Component from './Component.svelte';
+
+describe('Component Name', () => {
+	describe('Basic Rendering', () => {
+		it('renders with default props', () => {
+			render(Component);
+			const element = screen.getByRole('...');
+			expect(element).toBeInTheDocument();
+		});
+	});
+
+	describe('Variants', () => {
+		// Test all component variants
+	});
+
+	describe('States', () => {
+		// Test disabled, loading, invalid states
+	});
+
+	describe('Events', () => {
+		// Test user interactions
+	});
+
+	describe('Accessibility', () => {
+		// Test ARIA attributes and keyboard navigation
+	});
+});
+```
+
+### Testing Best Practices
+
+- **Comprehensive Coverage**: Test all props, variants, and states
+- **User-Centric Tests**: Focus on user interactions rather than implementation details
+- **Accessibility Testing**: Verify ARIA attributes, keyboard navigation, and screen reader support
+- **Async Behavior**: Use `waitFor` for testing tooltips, modals, and dynamic content
+- **Event Mocking**: Mock external dependencies and event handlers properly
+- **State Verification**: Check both visual state and underlying attributes
+
+### Example: Button Component Testing
+
+```typescript
+// Testing component variants
+const variants: ButtonVariant[] = ['primary', 'secondary', 'danger', 'cms'];
+variants.forEach((variant) => {
+	it(`renders ${variant} variant correctly`, () => {
+		render(Button, { variant });
+		const button = screen.getByRole('button');
+		expect(button).toHaveClass(`button--${variant}`);
+	});
+});
+
+// Testing interactive states
+it('renders loading state', () => {
+	render(Button, { loading: true });
+	const button = screen.getByRole('button');
+	expect(button).toBeDisabled();
+	expect(button).toHaveAttribute('aria-busy', 'true');
+	expect(button).toHaveClass('button--loading');
+});
+
+// Testing accessibility
+it('has proper ARIA attributes', () => {
+	render(Button, { ariaLabel: 'Custom label', loading: true });
+	const button = screen.getByRole('button');
+	expect(button).toHaveAttribute('aria-label', 'Custom label');
+	expect(button).toHaveAttribute('aria-busy', 'true');
+});
+
+// Testing async interactions (tooltips)
+it('shows tooltip on hover', async () => {
+	render(Button, {
+		tooltip: { message: 'Help text', listener: 'hover', listenerout: 'hover' }
+	});
+
+	const button = screen.getByRole('button');
+	const tooltipTarget = button.closest('.target');
+	await fireEvent.mouseEnter(tooltipTarget || button);
+
+	expect(screen.getByText('Help text')).toBeInTheDocument();
+});
 ```
 
 ## Development
@@ -32,6 +192,7 @@ pnpm storybook        # Component development
 pnpm build            # Build library
 pnpm test             # Run tests
 pnpm lint             # Check code quality
+pnpm check            # Check code quality
 ```
 
 ## Publishing

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './ui';
 export * from './router/index.svelte';
 export * from './stores';
+export * from './providers';
 export * from './utils';
 export * from './types';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './ui';
 export * from './router/index.svelte';
 export * from './stores';
+export * from './providers';
 export * from './utils';
 export * from './types';

package/dist/providers/GlobalProvider.mdx

@@ -0,0 +1,322 @@
+# 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>;
+```

package/dist/providers/GlobalProvider.svelte

@@ -0,0 +1,58 @@
+<script lang="ts">
+	import { getFinsweetComponentsEnvironment } from '../utils/index.js';
+
+	import { createGlobalContext, setGlobalContext } from './globalContext.svelte';
+	import type { GlobalProviderProps } from './types';
+
+	let { initialContexts = {}, debug = false, children }: GlobalProviderProps = $props();
+
+	// Default contexts with configurator support
+	const defaultContexts = {
+		app: {
+			editMode: false,
+			repairMode: false,
+			title: null,
+			configurator: {
+				configurator: null,
+				configuratorCache: null,
+				hasChanged: false,
+				watchOptions: {
+					watchAll: true,
+					watchKeys: [],
+					debounceMs: 100
+				}
+			}
+		},
+		form: {
+			formKey: null,
+			formUpdateKey: null
+		},
+		data: {
+			state: null
+		}
+	};
+
+	// Merge provided contexts with defaults
+	const mergedContexts = {
+		...defaultContexts,
+		...initialContexts
+	};
+
+	// Create and set the global context
+	const globalContext = createGlobalContext(mergedContexts, debug);
+	setGlobalContext(globalContext);
+	const { development } = getFinsweetComponentsEnvironment();
+
+	// Development mode debugging
+	if (development && typeof window !== 'undefined') {
+		globalContext.subscribe((event) => {
+			console.log('🌍 Global Context Event:', event);
+		});
+	}
+</script>
+
+{#if children}{@render children()}{/if}
+
+<style>
+	/* Global provider styles - currently using display: contents */
+</style>

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

@@ -0,0 +1,4 @@
+import type { GlobalProviderProps } from './types';
+declare const GlobalProvider: import("svelte").Component<GlobalProviderProps, {}, "">;
+type GlobalProvider = ReturnType<typeof GlobalProvider>;
+export default GlobalProvider;

package/dist/providers/configuratorUtils.d.ts

@@ -0,0 +1,37 @@
+import type { ConfiguratorState, ConfiguratorWatchOptions } from './types';
+/**
+ * Create default configurator state
+ */
+export declare function createDefaultConfiguratorState<T = Record<string, any>>(): ConfiguratorState<T>;
+/**
+ * Deep compare two objects with performance optimizations
+ */
+export declare function deepCompare<T>(obj1: T, obj2: T): boolean;
+/**
+ * Compare specific keys of two objects with optimization
+ */
+export declare function compareKeys<T extends Record<string, any>>(obj1: T | null, obj2: T | null, keys: string[]): boolean;
+/**
+ * Determine if configurator has changed with performance optimization
+ */
+export declare function hasConfiguratorChanged<T extends Record<string, any>>(configurator: T | null, configuratorCache: T | null, watchOptions: ConfiguratorWatchOptions): boolean;
+/**
+ * Create a debounced function for configurator updates
+ */
+export declare function createDebouncedUpdate<T extends (...args: any[]) => void>(fn: T, delay: number): T;
+/**
+ * Extract specific keys from an object
+ */
+export declare function extractKeys<T extends Record<string, any>>(obj: T | null, keys: string[]): Partial<T> | null;
+/**
+ * Get all keys from an object (for watchAll mode)
+ */
+export declare function getAllKeys<T extends Record<string, any>>(obj: T | null): string[];
+/**
+ * Validate watch options
+ */
+export declare function validateWatchOptions(options: ConfiguratorWatchOptions): ConfiguratorWatchOptions;
+/**
+ * Create a snapshot of configurator state for comparison
+ */
+export declare function createConfiguratorSnapshot<T extends Record<string, any>>(configurator: T | null, watchOptions: ConfiguratorWatchOptions): T | Partial<T> | null;