@finsweet/webflow-apps-utils 1.0.1

package/dist/router/Route.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	import { getContext, onMount, type Snippet } from 'svelte';
+
+	import type { RouteConfig, Router } from './index.svelte.js';
+
+	interface Props {
+		/** The path pattern for this route (supports parameters like :id) */
+		path: string;
+		/** Optional component to render when route matches */
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		component?: any;
+		/** Additional metadata for this route */
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		meta?: Record<string, any>;
+		/** Whether this route should match exactly (default: true) */
+		exact?: boolean;
+		/** Children snippet */
+
+		children?: Snippet<
+			[
+				{
+					params: Record<string, string>;
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					location: any;
+					router: Router;
+					isActive: boolean;
+				}
+			]
+		>;
+	}
+
+	let { path, component, meta = {}, exact = true, children }: Props = $props();
+
+	// Get router from context
+	const router = getContext<Router>('router');
+
+	if (!router) {
+		throw new Error('Route component must be used within a Router component');
+	}
+
+	// Reactive state
+	let isActive = $state(false);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	let currentLocation = $state<any>(null);
+	let routeParams = $state<Record<string, string>>({});
+
+	// Route configuration
+	const routeConfig: RouteConfig = {
+		path,
+		component,
+		meta: { ...meta, exact }
+	};
+
+	// Register route with router
+	onMount(() => {
+		router.addRoute(routeConfig);
+	});
+
+	// Update reactive state when router changes
+	$effect(() => {
+		currentLocation = router.useLocation();
+		routeParams = router.getParams();
+		isActive = router.isActive(path, exact);
+	});
+</script>
+
+<!-- Render content only if route is active -->
+{#if isActive}
+	{#if component}
+		<!-- Render provided component with route props -->
+		{@const Component = component}
+		<Component params={routeParams} location={currentLocation} {router} />
+	{:else if children}
+		<!-- Render children snippet with route data -->
+		{@render children({
+			params: routeParams,
+			location: currentLocation,
+			router,
+			isActive
+		})}
+	{/if}
+{/if}

package/dist/router/Route.svelte.d.ts

@@ -0,0 +1,24 @@
+import { type Snippet } from 'svelte';
+import type { Router } from './index.svelte.js';
+interface Props {
+    /** The path pattern for this route (supports parameters like :id) */
+    path: string;
+    /** Optional component to render when route matches */
+    component?: any;
+    /** Additional metadata for this route */
+    meta?: Record<string, any>;
+    /** Whether this route should match exactly (default: true) */
+    exact?: boolean;
+    /** Children snippet */
+    children?: Snippet<[
+        {
+            params: Record<string, string>;
+            location: any;
+            router: Router;
+            isActive: boolean;
+        }
+    ]>;
+}
+declare const Route: import("svelte").Component<Props, {}, "">;
+type Route = ReturnType<typeof Route>;
+export default Route;

package/dist/router/Router.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+	import { onDestroy, onMount, setContext, type Snippet } from 'svelte';
+
+	import type { RouteConfig, Router } from './index.svelte';
+
+	interface Props {
+		/** Router instance to use for routing */
+		router: Router;
+		/** Whether to automatically initialize the router */
+		autoInit?: boolean;
+		/** Children snippet */
+		children?: Snippet<
+			[
+				{
+					router: Router;
+					currentRoute: RouteConfig | null;
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					currentLocation: any;
+					isNavigating: boolean;
+				}
+			]
+		>;
+	}
+
+	let { router, autoInit = true, children }: Props = $props();
+
+	// Reactive state from router
+	let currentRoute = $state<RouteConfig | null>(null);
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	let currentLocation = $state<any>(null);
+	let isNavigating = $state(false);
+
+	// Provide router context for child components
+	setContext('router', router);
+
+	// Update reactive state when router changes
+	$effect(() => {
+		currentRoute = router.useRoute();
+		currentLocation = router.useLocation();
+		isNavigating = router.useNavigating();
+	});
+
+	onMount(() => {
+		if (autoInit) {
+			router.init();
+		}
+	});
+
+	onDestroy(() => {
+		router.destroy();
+	});
+</script>
+
+<div class="router-container" class:navigating={isNavigating}>
+	{#if children}
+		{@render children({ router, currentRoute, currentLocation, isNavigating })}
+	{/if}
+</div>
+
+<style>
+	.router-container {
+		width: 100%;
+		height: 100%;
+	}
+
+	.router-container.navigating {
+		/* Optional loading styles during navigation */
+		opacity: 0.9;
+		transition: opacity 0.1s ease;
+	}
+</style>

package/dist/router/Router.svelte.d.ts

@@ -0,0 +1,20 @@
+import { type Snippet } from 'svelte';
+import type { RouteConfig, Router } from './index.svelte';
+interface Props {
+    /** Router instance to use for routing */
+    router: Router;
+    /** Whether to automatically initialize the router */
+    autoInit?: boolean;
+    /** Children snippet */
+    children?: Snippet<[
+        {
+            router: Router;
+            currentRoute: RouteConfig | null;
+            currentLocation: any;
+            isNavigating: boolean;
+        }
+    ]>;
+}
+declare const Router: import("svelte").Component<Props, {}, "">;
+type Router = ReturnType<typeof Router>;
+export default Router;

package/dist/router/hooks.svelte.d.ts

@@ -0,0 +1,77 @@
+import type { LocationInfo, RouteConfig, RouteParams, Router } from './index.svelte';
+/**
+ * Get the router instance from context
+ */
+export declare function useRouter(): Router;
+/**
+ * Get reactive location information
+ */
+export declare function useLocation(): LocationInfo;
+/**
+ * Get reactive current route information
+ */
+export declare function useRoute(): RouteConfig | null;
+/**
+ * Get reactive route parameters
+ */
+export declare function useParams(): RouteParams;
+/**
+ * Get reactive query parameters
+ */
+export declare function useQuery(): URLSearchParams;
+/**
+ * Get reactive navigation state
+ */
+export declare function useNavigating(): boolean;
+/**
+ * Get reactive navigation history
+ */
+export declare function useHistory(): import("./index.svelte").HistoryEntry[];
+/**
+ * Get a navigation function
+ */
+export declare function useNavigate(): (pathname: string, options?: {
+    replace?: boolean;
+    state?: any;
+}) => void;
+/**
+ * Check if a path is currently active
+ */
+export declare function useIsActiveRoute(): (path: string, exact?: boolean) => boolean;
+/**
+ * Get a function to go back in history
+ */
+export declare function useGoBack(): () => void;
+/**
+ * Get a function to go forward in history
+ */
+export declare function useGoForward(): () => void;
+/**
+ * Watch for route changes and execute a callback
+ */
+export declare function useRouteWatcher(callback: (location: LocationInfo, route: RouteConfig | null) => void, immediate?: boolean): void;
+/**
+ * Get current route metadata
+ */
+export declare function useRouteMeta(): Record<string, any> | undefined;
+/**
+ * Create a search params helper with reactive updates
+ */
+export declare function useSearchParams(): {
+    get: (key: string) => string | null;
+    set: (key: string, value: string) => void;
+    delete: (key: string) => void;
+    has: (key: string) => boolean;
+    toString: () => string;
+    getAll: () => {
+        [k: string]: string;
+    };
+};
+/**
+ * Hook to get the current app version path
+ */
+export declare function useAppVersion(): string;
+/**
+ * Hook to get the full pathname including app version
+ */
+export declare function useFullPathname(): string;

package/dist/router/hooks.svelte.js

@@ -0,0 +1,148 @@
+import { getContext } from 'svelte';
+/**
+ * Get the router instance from context
+ */
+export function useRouter() {
+    const router = getContext('router');
+    if (!router) {
+        throw new Error('useRouter must be used within a Router component');
+    }
+    return router;
+}
+/**
+ * Get reactive location information
+ */
+export function useLocation() {
+    const router = useRouter();
+    return router.useLocation();
+}
+/**
+ * Get reactive current route information
+ */
+export function useRoute() {
+    const router = useRouter();
+    return router.useRoute();
+}
+/**
+ * Get reactive route parameters
+ */
+export function useParams() {
+    const router = useRouter();
+    return router.getParams();
+}
+/**
+ * Get reactive query parameters
+ */
+export function useQuery() {
+    const router = useRouter();
+    return router.getQuery();
+}
+/**
+ * Get reactive navigation state
+ */
+export function useNavigating() {
+    const router = useRouter();
+    return router.useNavigating();
+}
+/**
+ * Get reactive navigation history
+ */
+export function useHistory() {
+    const router = useRouter();
+    return router.useHistory();
+}
+/**
+ * Get a navigation function
+ */
+export function useNavigate() {
+    const router = useRouter();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (pathname, options) => {
+        router.navigate(pathname, { ...options, replace: true });
+    };
+}
+/**
+ * Check if a path is currently active
+ */
+export function useIsActiveRoute() {
+    const router = useRouter();
+    return (path, exact = false) => router.isActive(path, exact);
+}
+/**
+ * Get a function to go back in history
+ */
+export function useGoBack() {
+    const router = useRouter();
+    return () => router.back();
+}
+/**
+ * Get a function to go forward in history
+ */
+export function useGoForward() {
+    const router = useRouter();
+    return () => router.forward();
+}
+/**
+ * Watch for route changes and execute a callback
+ */
+export function useRouteWatcher(callback, immediate = false) {
+    const router = useRouter();
+    let previousPathname = null;
+    $effect(() => {
+        const location = router.useLocation();
+        const route = router.useRoute();
+        // Only call if pathname actually changed (or immediate is true)
+        if (immediate || location.pathname !== previousPathname) {
+            callback(location, route);
+            previousPathname = location.pathname;
+        }
+    });
+}
+/**
+ * Get current route metadata
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useRouteMeta() {
+    const route = useRoute();
+    return route?.meta;
+}
+/**
+ * Create a search params helper with reactive updates
+ */
+export function useSearchParams() {
+    const navigate = useNavigate();
+    const location = useLocation();
+    return {
+        get: (key) => location.query.get(key),
+        set: (key, value) => {
+            const newQuery = new URLSearchParams(location.search);
+            newQuery.set(key, value);
+            const newPath = location.pathname + '?' + newQuery.toString();
+            navigate(newPath, { replace: true });
+        },
+        delete: (key) => {
+            const newQuery = new URLSearchParams(location.search);
+            newQuery.delete(key);
+            const search = newQuery.toString();
+            const newPath = location.pathname + (search ? '?' + search : '');
+            navigate(newPath, { replace: true });
+        },
+        has: (key) => location.query.has(key),
+        toString: () => location.query.toString(),
+        getAll: () => Object.fromEntries(location.query.entries())
+    };
+}
+/**
+ * Hook to get the current app version path
+ */
+export function useAppVersion() {
+    const router = useRouter();
+    return router.getAppVersionPath();
+}
+/**
+ * Hook to get the full pathname including app version
+ */
+export function useFullPathname() {
+    const router = useRouter();
+    return router.getFullPathname();
+}

package/dist/router/index.svelte.d.ts

@@ -0,0 +1,107 @@
+/** Route configuration object */
+export interface RouteConfig {
+    /** The path pattern to match (supports parameters like /users/:id) */
+    path: string;
+    /** Optional component to render when route matches */
+    component?: any;
+    /** Additional metadata for the route */
+    meta?: Record<string, any>;
+}
+/** Parsed route parameters from URL */
+export interface RouteParams {
+    [key: string]: string;
+}
+/** Current location information */
+export interface LocationInfo {
+    /** Current pathname (e.g., '/users/123') */
+    pathname: string;
+    /** Current search string (e.g., '?page=1') */
+    search: string;
+    /** Current hash (e.g., '#section') */
+    hash: string;
+    /** Complete URL object */
+    url: URL;
+    /** Parsed route parameters */
+    params: RouteParams;
+    /** Current query parameters */
+    query: URLSearchParams;
+}
+/** History entry for navigation tracking */
+export interface HistoryEntry {
+    /** The pathname of the history entry */
+    pathname: string;
+    /** Timestamp when entry was created */
+    timestamp: number;
+    /** Optional state data */
+    state?: any;
+}
+/** Router configuration options */
+export interface RouterConfig {
+    /** Base path for all routes (default: '') */
+    basePath?: string;
+    /** Whether to use hash-based routing (default: false) */
+    hashMode?: boolean;
+    /** Initial route to navigate to if no route matches */
+    fallbackRoute?: string;
+    /** Whether to automatically initialize on browser load */
+    autoInit?: boolean;
+}
+/** Custom Router Class for Svelte 5 */
+export declare class Router {
+    #private;
+    /** Creates a new Router instance */
+    constructor(config?: RouterConfig);
+    /** Initialize the router and start listening to navigation events */
+    init(): void;
+    /** Navigate to the root path */
+    gotoRootPath(): void;
+    /** Initialize the app version path that will be persisted across all routes */
+    initAppVersion(appVersionPath: string): void;
+    /** Clean up event listeners and stop the router */
+    destroy(): void;
+    /** Register a route with the router */
+    addRoute(route: RouteConfig): void;
+    /** Register multiple routes at once */
+    addRoutes(routes: RouteConfig[]): void;
+    /** Navigate to a specified pathname */
+    navigate(pathname: string, options?: {
+        replace?: boolean;
+        state?: any;
+    }): void;
+    /** Navigate back in history */
+    back(): void;
+    /** Navigate forward in history */
+    forward(): void;
+    /** Get reactive location information */
+    useLocation(): LocationInfo;
+    /** Get reactive current route information */
+    useRoute(): RouteConfig | null;
+    /** Get reactive navigation history */
+    useHistory(): HistoryEntry[];
+    /** Get reactive navigation state */
+    useNavigating(): boolean;
+    /** Check if a path matches the current location */
+    isActive(path: string, exact?: boolean): boolean;
+    /** Get the current app version path */
+    getAppVersionPath(): string;
+    /** Get the full pathname including app version path */
+    getFullPathname(): string;
+    /** Get the current active path */
+    getActivePath(): string;
+    /** Get the current route parameters */
+    getParams(): RouteParams;
+    /** Get current query parameters */
+    getQuery(): URLSearchParams;
+}
+/**
+ * Create a router instance with the given configuration
+ */
+export declare function createRouter(config?: RouterConfig): Router;
+/**
+ * Default router instance for convenience
+ */
+export declare const router: Router;
+export { default as Link } from './Link.svelte';
+export { default as Route } from './Route.svelte';
+export { default as RouterComponent } from './Router.svelte';
+export * from './hooks.svelte.js';