@finsweet/webflow-apps-utils 1.0.3 → 1.0.5

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>;
-```

package/dist/router/README.md

@@ -1,397 +0,0 @@
-# Custom Svelte 5 Router
-
-A lightweight, type-safe client-side router built specifically for Svelte 5 using runes. Designed to replace svelte-routing with modern reactivity patterns and support for persistent app version hashes.
-
-## Features
-
-- 🚀 **Svelte 5 Native**: Built with runes for optimal reactivity
-- 🎯 **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 📦 **Lightweight**: Minimal bundle size with no external dependencies
-- 🔄 **Reactive**: All router state is reactive using Svelte 5 runes
-- 🛣️ **Parameter Support**: URL parameters like `/users/:id`
-- 🔍 **Query Params**: Built-in query parameter handling
-- 🏠 **App Version Support**: Persistent app version hashes across navigation
-- 📱 **Hash Mode**: Optional hash-based routing
-- 🎣 **Rich Hooks**: Comprehensive set of utility hooks
-- ♿ **Accessible**: Built-in accessibility features for navigation
-
-## Installation
-
-The router is included in your project. Import from:
-
-```typescript
-import { Router, RouterComponent, Route, Link } from './router';
-```
-
-## Quick Start
-
-### 1. Create and Configure Router
-
-```typescript
-// router.ts
-import { createRouter } from './lib/router';
-
-export const appRouter = createRouter({
-	autoInit: true
-});
-
-// Export the router instance for use throughout the app
-export default appRouter;
-```
-
-### 2. Initialize with App Version
-
-```typescript
-// In your app initialization
-const awaitRouter = async () => {
-	const current = new URL(window.location.href);
-	const appVersionID = current.pathname.split('/')[1] || 'dev-mode';
-
-	// Initialize app version - this persists across all navigation
-	appRouter.initAppVersion(`/${appVersionID}`);
-
-	// Define routes without app version prefix
-	appRouter.addRoutes([
-		{ path: '/', component: MyComponentsLinks },
-		{ path: '/finsweetbuilder', component: BuilderLinks },
-		{ path: '/finsweetlibrary', component: LibraryLinks },
-		{ path: '/finsweetlibrary-admin', component: LibraryAdminLinks }
-	]);
-
-	// Update your existing router store
-	routerStore.set({
-		hash: appVersionID,
-		url: current
-	});
-};
-```
-
-### 3. Setup Router in Your App
-
-```svelte
-<!-- App.svelte -->
-<script lang="ts">
-	import { RouterComponent, Route } from './lib/router';
-	import appRouter from './router.ts';
-	import { routerStore } from '@finsweet/components-utils';
-
-	const awaitRouter = async () => {
-		const current = new URL(window.location.href);
-		const appVersionID = current.pathname.split('/')[1] || 'dev-mode';
-
-		// Initialize app version - this persists across all navigation
-		appRouter.initAppVersion(`/${appVersionID}`);
-
-		// Update your existing router store
-		routerStore.set({
-			hash: appVersionID,
-			url: current
-		});
-
-		// Update configurator if needed
-		configurator.update((state) => ({
-			...state,
-			pathname: current.pathname,
-			appVersionID: appVersionID
-		}));
-
-		await delay(50);
-	};
-
-	// ... rest of your init logic
-</script>
-
-<!-- Replace your existing Router with RouterComponent -->
-<RouterComponent router={appRouter}>
-	<!-- Define routes without app version prefix -->
-	<Route path="/" component={MyComponentsLinks} />
-	<Route path="/finsweetbuilder" component={BuilderLinks} />
-	<Route path="/finsweetlibrary" component={LibraryLinks} />
-	<Route path="/finsweetlibrary-admin" component={LibraryAdminLinks} />
-
-	<!-- Dynamic component routes -->
-	{#each $finsweetComponentsList as { solution, live, key }}
-		{#if live}
-			<Route path="/finsweetbuilder/{key}" component={solution} />
-		{/if}
-	{/each}
-</RouterComponent>
-```
-
-### 4. Navigate with Links
-
-```svelte
-<!-- LeftNavBarLinks.svelte -->
-<script lang="ts">
-	import { Link, useAppVersion, useLocation } from '../lib/router';
-
-	const appVersionPath = useAppVersion();
-	const location = useLocation();
-
-	// Routes are now clean without app version prefix
-	const navLinks = [
-		{ path: '/', label: 'My Components', icon: ComponentsIcon },
-		{ path: '/finsweetbuilder', label: 'Builder', icon: BuilderIcon },
-		{ path: '/finsweetlibrary', label: 'Library', icon: FinsweetLibraryIcon }
-	];
-</script>
-
-<div class="nav-container">
-	{#each navLinks as link}
-		<Link to={link.path} activeClass="active" class="nav-links parent-link">
-			<svelte:component this={link.icon} />
-			<Text label={link.label} fontSize="normal" />
-		</Link>
-	{/each}
-</div>
-
-<style>
-	.active {
-		font-weight: bold;
-		color: blue;
-	}
-</style>
-```
-
-### 5. Use Router Hooks for Navigation
-
-```svelte
-<!-- BackNavLink.svelte -->
-<script lang="ts">
-	import { useNavigate, useAppVersion } from '../lib/router';
-
-	export let fsComponent: string;
-
-	const navigate = useNavigate();
-	const appVersionPath = useAppVersion();
-
-	const goBack = () => {
-		// Navigate to builder page - app version is automatically included
-		navigate('/finsweetbuilder');
-
-		// Update your existing store if needed
-		const appVersionID = appVersionPath.slice(1); // Remove leading slash
-		routerStore.set({
-			hash: appVersionID,
-			url: new URL(`${appVersionPath}/finsweetbuilder`, window.location.origin)
-		});
-	};
-</script>
-
-<div class="nav-links-wrapper">
-	<Section clickable onclick={goBack}>
-		<!-- ... rest of your template -->
-	</Section>
-</div>
-```
-
-## Core Concepts
-
-### App Version Hash Support
-
-The router's key feature is maintaining app version hashes across all navigation:
-
-```typescript
-// Once initialized, all routes automatically include the app version
-appRouter.initAppVersion('/test-app-hash');
-
-// These routes work automatically with app version:
-navigate('/'); // Goes to /test-app-hash/
-navigate('/finsweetbuilder'); // Goes to /test-app-hash/finsweetbuilder
-```
-
-### Links with App Version
-
-Links automatically include the app version prefix:
-
-```svelte
-<!-- These automatically include the app version prefix -->
-<Link to="/">Home</Link>
-<!-- Renders as href="/test-app-hash/" -->
-
-<Link to="/finsweetbuilder">Builder</Link>
-<!-- Renders as href="/test-app-hash/finsweetbuilder" -->
-```
-
-### App Version Utility Hooks
-
-```svelte
-<script lang="ts">
-	import { useAppVersion, useFullPathname, useLocation } from './router';
-
-	const appVersionPath = useAppVersion(); // Returns '/test-app-hash'
-	const fullPathname = useFullPathname(); // Returns '/test-app-hash/users/123'
-	const location = useLocation(); // location.pathname is clean: '/users/123'
-</script>
-
-<p>App Version: {appVersionPath}</p>
-<p>Full Path: {fullPathname}</p>
-<p>Clean Path: {location.pathname}</p>
-```
-
-### Working with Route Parameters
-
-```svelte
-<!-- UserDetail.svelte -->
-<script lang="ts">
-	import { useParams, useNavigate, useLocation } from './router';
-
-	const params = useParams();
-	const navigate = useNavigate();
-	const location = useLocation();
-
-	// Reactive access to route parameters
-	$: userId = params.id;
-
-	function goBack() {
-		navigate('/users');
-	}
-</script>
-
-<h1>User {userId}</h1>
-<button onclick={goBack}>Back to Users</button>
-<p>Current path: {location.pathname}</p>
-```
-
-### Component Modal Updates
-
-```svelte
-<!-- NewComponent.svelte -->
-<script lang="ts">
-	import { useNavigate } from '../lib/router';
-
-	const navigate = useNavigate();
-
-	const handleBuilderClick = () => {
-		// Navigate to builder - app version automatically included
-		navigate('/finsweetbuilder');
-	};
-
-	const handleLibraryClick = () => {
-		// Navigate to library - app version automatically included
-		navigate('/finsweetlibrary');
-	};
-</script>
-
-<!-- Navigation calls with new navigate function -->
-<WebflowTooltip>
-	<div slot="tooltip">
-		<Section clickable on:click={handleBuilderClick}>
-			<!-- Builder option -->
-		</Section>
-		<Section clickable on:click={handleLibraryClick}>
-			<!-- Library option -->
-		</Section>
-	</div>
-</WebflowTooltip>
-```
-
-## API Reference
-
-### Router Class
-
-```typescript
-const router = createRouter({
-	basePath: '/app', // Optional base path
-	hashMode: false, // Use hash-based routing
-	fallbackRoute: '/404', // Fallback for unmatched routes
-	autoInit: true // Auto-initialize in browser
-});
-
-// Methods
-router.navigate('/path', { replace: false, state: {} });
-router.addRoute({ path: '/users/:id', component: UserComponent });
-router.addRoutes([...routes]);
-router.initAppVersion('/app-version'); // Set persistent app version
-router.isActive('/path', (exact = false));
-router.getParams();
-router.getQuery();
-router.back();
-router.forward();
-```
-
-### Hooks
-
-```typescript
-// Get router instance
-const router = useRouter();
-
-// Reactive location information
-const location = useLocation();
-
-// Current route information
-const route = useRoute();
-
-// Route parameters
-const params = useParams();
-
-// Query parameters
-const query = useQuery();
-
-// Navigation function
-const navigate = useNavigate();
-
-// Check if path is active
-const isActive = useIsActiveRoute();
-
-// App version utilities
-const appVersionPath = useAppVersion();
-const fullPathname = useFullPathname();
-
-// Navigation state
-const isNavigating = useNavigating();
-
-// History tracking
-const history = useHistory();
-
-// Search params helper
-const search = useSearchParams();
-search.set('page', '2');
-search.get('page');
-search.delete('page');
-```
-
-### Components
-
-#### RouterComponent
-
-```svelte
-<RouterComponent {router} autoInit={true}>
-	<!-- Route components go here -->
-</RouterComponent>
-```
-
-#### Route
-
-```svelte
-<Route path="/users/:id" component={UserComponent} exact={true} meta={{ requiresAuth: true }} />
-
-<!-- Or with slot content -->
-<Route path="/about">
-	<AboutPage />
-</Route>
-```
-
-#### Link
-
-```svelte
-<Link
-	to="/users/123"
-	activeClass="active"
-	exact={false}
-	replace={false}
-	disabled={false}
-	element="a">View User</Link
->
-```
-
-## Key Benefits
-
-1. **Persistent App Version**: Once `initAppVersion` is called, the app version hash persists across all navigation
-2. **Clean Route Definitions**: Define routes without app version prefixes (`/finsweetbuilder` instead of `/{appVersionID}/finsweetbuilder`)
-3. **Automatic URL Generation**: Links and navigation automatically include the app version prefix
-4. **Backward Compatibility**: Works with your existing `routerStore` and other components
-5. **Type Safety**: Full TypeScript support with proper typing
-6. **Modern Reactivity**: Built on Svelte 5 runes for optimal performance
-
-The router handles all the app version complexity automatically while maintaining compatibility with your existing application structure and providing a modern, type-safe routing solution for Svelte 5.