@finsweet/webflow-apps-utils 1.0.3 → 1.0.4

package/dist/router/Router.mdx

@@ -0,0 +1,958 @@
+# Router API Documentation
+
+A comprehensive client-side router for Svelte 5 applications with support for reactive state management, dynamic routing, and app version persistence.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Core Classes](#core-classes)
+  - [Router](#router)
+  - [createRouter()](#createrouter)
+- [Components](#components)
+  - [RouterProvider](#routerprovider)
+  - [Route](#route)
+  - [Link](#link)
+- [Hooks](#hooks)
+- [Interfaces](#interfaces)
+- [Examples](#examples)
+
+## Installation
+
+```typescript
+import {
+	createRouter,
+	RouterProvider,
+	Route,
+	Link,
+	useRouter,
+	useLocation,
+	useNavigate
+} from '@finsweet/webflow-apps-utils';
+```
+
+## Core Classes
+
+### Router
+
+The main router class that handles navigation, route matching, and state management.
+
+#### Constructor
+
+```typescript
+new Router(config?: RouterConfig)
+```
+
+#### Configuration Options
+
+```typescript
+interface RouterConfig {
+	basePath?: string; // Base path for all routes (default: '')
+	hashMode?: boolean; // Use hash-based routing (default: false)
+	fallbackRoute?: string; // Fallback route when no match (default: '/')
+	autoInit?: boolean; // Auto-initialize on creation (default: true)
+}
+```
+
+#### Methods
+
+##### Navigation Methods
+
+```typescript
+// Navigate to a path
+navigate(pathname: string, options?: { replace?: boolean; state?: any }): void
+
+// Navigate back in history
+back(): void
+
+// Navigate forward in history
+forward(): void
+
+// Navigate to root path
+gotoRootPath(): void
+```
+
+##### Route Management
+
+```typescript
+// Add a single route
+addRoute(route: RouteConfig): void
+
+// Add multiple routes
+addRoutes(routes: RouteConfig[]): void
+```
+
+##### State Access Methods
+
+```typescript
+// Get reactive location information
+useLocation(): LocationInfo
+
+// Get reactive current route
+useRoute(): RouteConfig | null
+
+// Get reactive navigation state
+useNavigating(): boolean
+
+// Get reactive navigation history
+useHistory(): HistoryEntry[]
+
+// Check if path is active
+isActive(path: string, exact?: boolean): boolean
+
+// Get current route parameters
+getParams(): RouteParams
+
+// Get current query parameters
+getQuery(): URLSearchParams
+```
+
+##### App Version Methods
+
+```typescript
+// Initialize app version path persistence
+initAppVersion(appVersionPath: string): void
+
+// Get current app version path
+getAppVersionPath(): string
+
+// Get full pathname including app version
+getFullPathname(): string
+
+// Get active path with app version
+getActivePath(): string
+```
+
+##### Lifecycle Methods
+
+```typescript
+// Initialize the router
+init(): void
+
+// Clean up and destroy router
+destroy(): void
+```
+
+#### Example Usage
+
+```typescript
+import { createRouter } from '@finsweet/webflow-apps-utils';
+
+// Create router with configuration
+const router = createRouter({
+	basePath: '/app',
+	hashMode: false,
+	fallbackRoute: '/home',
+	autoInit: true
+});
+
+// Add routes
+router.addRoutes([
+	{ path: '/', component: HomePage, meta: { title: 'Home' } },
+	{ path: '/users/:id', component: UserPage, meta: { title: 'User Profile' } },
+	{ path: '/about', component: AboutPage, meta: { title: 'About' } }
+]);
+
+// Initialize app version for persistence
+router.initAppVersion('/v1');
+
+// Navigate programmatically
+router.navigate('/users/123');
+router.navigate('/about', { replace: true, state: { from: 'home' } });
+```
+
+### createRouter()
+
+Factory function to create a new router instance.
+
+```typescript
+function createRouter(config?: RouterConfig): Router;
+```
+
+#### Example
+
+```typescript
+const router = createRouter({
+	basePath: '/my-app',
+	fallbackRoute: '/dashboard'
+});
+```
+
+## Components
+
+### RouterProvider
+
+Root component that provides router context to child components and manages router lifecycle.
+
+#### Props
+
+```typescript
+interface RouterProviderProps {
+	router: Router; // Router instance
+	autoInit?: boolean; // Auto-initialize router (default: true)
+	loading?: boolean; // Show loading screen
+	loadingMessage?: string; // Loading message text
+	children?: Snippet<[RouterContext]>; // Children with router context
+}
+
+interface RouterContext {
+	router: Router;
+	currentRoute: RouteConfig | null;
+	currentLocation: LocationInfo;
+	isNavigating: boolean;
+}
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { createRouter, RouterProvider } from '@finsweet/webflow-apps-utils';
+
+  const router = createRouter();
+</script>
+
+<RouterProvider {router} loading={false}>
+  {#snippet children({ router, currentRoute, currentLocation, isNavigating })}
+    <nav>
+      <!-- Navigation content -->
+    </nav>
+
+    <main class:navigating={isNavigating}>
+      <!-- Route content -->
+    </main>
+  {/snippet}
+</RouterProvider>
+```
+
+### Route
+
+Component for defining and rendering routes based on path patterns.
+
+#### Props
+
+```typescript
+interface RouteProps {
+	path: string; // Path pattern (supports :params)
+	component?: any; // Component to render when active
+	meta?: Record<string, any>; // Route metadata
+	exact?: boolean; // Exact path matching (default: true)
+	children?: Snippet<[RouteContext]>; // Children with route context
+}
+
+interface RouteContext {
+	params: Record<string, string>; // Route parameters
+	location: LocationInfo; // Current location
+	router: Router; // Router instance
+	isActive: boolean; // Whether route is active
+}
+```
+
+#### Example
+
+```typescript
+<!-- Using component prop -->
+<Route path="/users/:id" component={UserProfile} />
+
+<!-- Using children snippet -->
+<Route path="/dashboard">
+  {#snippet children({ params, location, router, isActive })}
+    {#if isActive}
+      <Dashboard userId={params.id} />
+    {/if}
+  {/snippet}
+</Route>
+
+<!-- Wildcard route for 404 -->
+<Route path="*" exact={false}>
+  {#snippet children({ isActive })}
+    {#if isActive}
+      <NotFoundPage />
+    {/if}
+  {/snippet}
+</Route>
+```
+
+### Link
+
+Navigation component that generates proper links with active state management.
+
+#### Props
+
+```typescript
+interface LinkProps {
+	to: string; // Target path
+	replace?: boolean; // Replace history entry (default: false)
+	activeClass?: string; // CSS class when active
+	exact?: boolean; // Exact matching for active state
+	disabled?: boolean; // Disable the link
+	class?: string; // Additional CSS classes
+	state?: any; // State to pass with navigation
+	element?: 'a' | 'button'; // HTML element type (default: 'a')
+	children?: Snippet; // Link content
+	onclick?: (event: MouseEvent) => void; // Click handler
+}
+```
+
+#### Example
+
+```typescript
+<!-- Basic link -->
+<Link to="/about">About Us</Link>
+
+<!-- Link with active styling -->
+<Link to="/dashboard" activeClass="nav-active" exact>
+  Dashboard
+</Link>
+
+<!-- Button-style link -->
+<Link to="/settings" element="button" class="btn btn-primary">
+  Settings
+</Link>
+
+<!-- Link with custom click handler -->
+<Link
+  to="/profile"
+  onclick={(e) => console.log('Navigating to profile')}
+>
+  My Profile
+</Link>
+
+<!-- Disabled link -->
+<Link to="/admin" disabled>
+  Admin Panel
+</Link>
+```
+
+## Hooks
+
+### useRouter()
+
+Get the router instance from context.
+
+```typescript
+function useRouter(): Router;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useRouter } from '@finsweet/webflow-apps-utils';
+
+  const router = useRouter();
+
+  function handleLogout() {
+    router.navigate('/login', { replace: true });
+  }
+</script>
+```
+
+### useLocation()
+
+Get reactive location information.
+
+```typescript
+function useLocation(): LocationInfo;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useLocation } from '@finsweet/webflow-apps-utils';
+
+  const location = useLocation();
+</script>
+
+<div>
+  Current path: {location.pathname}
+  Query params: {location.search}
+  Route params: {JSON.stringify(location.params)}
+</div>
+```
+
+### useRoute()
+
+Get reactive current route information.
+
+```typescript
+function useRoute(): RouteConfig | null;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useRoute } from '@finsweet/webflow-apps-utils';
+
+  const route = useRoute();
+</script>
+
+{#if route}
+  <title>{route.meta?.title || 'My App'}</title>
+{/if}
+```
+
+### useParams()
+
+Get reactive route parameters.
+
+```typescript
+function useParams(): RouteParams;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useParams } from '@finsweet/webflow-apps-utils';
+
+  const params = useParams();
+
+  $: userId = params.id;
+</script>
+
+<h1>User Profile: {userId}</h1>
+```
+
+### useQuery()
+
+Get reactive query parameters.
+
+```typescript
+function useQuery(): URLSearchParams;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useQuery } from '@finsweet/webflow-apps-utils';
+
+  const query = useQuery();
+
+  $: page = query.get('page') || '1';
+  $: sort = query.get('sort') || 'name';
+</script>
+```
+
+### useNavigate()
+
+Get a navigation function.
+
+```typescript
+function useNavigate(): (pathname: string, options?: NavigateOptions) => void;
+
+interface NavigateOptions {
+	replace?: boolean;
+	state?: any;
+}
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useNavigate } from '@finsweet/webflow-apps-utils';
+
+  const navigate = useNavigate();
+
+  function goToProfile() {
+    navigate('/profile');
+  }
+
+  function goToSettings() {
+    navigate('/settings', { replace: true });
+  }
+</script>
+```
+
+### useNavigating()
+
+Get reactive navigation state.
+
+```typescript
+function useNavigating(): boolean;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useNavigating } from '@finsweet/webflow-apps-utils';
+
+  const isNavigating = useNavigating();
+</script>
+
+{#if isNavigating}
+  <div class="loading-spinner">Navigating...</div>
+{/if}
+```
+
+### useHistory()
+
+Get reactive navigation history.
+
+```typescript
+function useHistory(): HistoryEntry[];
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useHistory } from '@finsweet/webflow-apps-utils';
+
+  const history = useHistory();
+</script>
+
+<div>
+  <h3>Navigation History:</h3>
+  {#each history.slice(-5) as entry}
+    <div>{entry.pathname} - {new Date(entry.timestamp).toLocaleTimeString()}</div>
+  {/each}
+</div>
+```
+
+### useIsActiveRoute()
+
+Get a function to check if routes are active.
+
+```typescript
+function useIsActiveRoute(): (path: string, exact?: boolean) => boolean;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useIsActiveRoute } from '@finsweet/webflow-apps-utils';
+
+  const isActive = useIsActiveRoute();
+</script>
+
+<nav>
+  <a href="/home" class:active={isActive('/home')}>Home</a>
+  <a href="/about" class:active={isActive('/about')}>About</a>
+</nav>
+```
+
+### useRouteWatcher()
+
+Watch for route changes and execute callbacks.
+
+```typescript
+function useRouteWatcher(
+	callback: (location: LocationInfo, route: RouteConfig | null) => void,
+	immediate?: boolean
+): void;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useRouteWatcher } from '@finsweet/webflow-apps-utils';
+
+  useRouteWatcher((location, route) => {
+    console.log('Route changed:', location.pathname);
+
+    // Update page title
+    if (route?.meta?.title) {
+      document.title = route.meta.title;
+    }
+
+    // Analytics tracking
+    analytics.track('page_view', { path: location.pathname });
+  });
+</script>
+```
+
+### useSearchParams()
+
+Get search params helper with reactive updates.
+
+```typescript
+function useSearchParams(): SearchParamsHelper;
+
+interface SearchParamsHelper {
+	get(key: string): string | null;
+	set(key: string, value: string): void;
+	delete(key: string): void;
+	has(key: string): boolean;
+	toString(): string;
+	getAll(): Record<string, string>;
+}
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useSearchParams } from '@finsweet/webflow-apps-utils';
+
+  const searchParams = useSearchParams();
+
+  function updatePage(page: number) {
+    searchParams.set('page', page.toString());
+  }
+
+  function clearFilters() {
+    searchParams.delete('filter');
+    searchParams.delete('sort');
+  }
+</script>
+
+<div>
+  Current page: {searchParams.get('page') || '1'}
+  <button onclick={() => updatePage(2)}>Go to Page 2</button>
+  <button onclick={clearFilters}>Clear Filters</button>
+</div>
+```
+
+### useAppVersion()
+
+Get the current app version path.
+
+```typescript
+function useAppVersion(): string;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useAppVersion } from '@finsweet/webflow-apps-utils';
+
+  const appVersion = useAppVersion();
+</script>
+
+<div>App Version: {appVersion}</div>
+```
+
+### useFullPathname()
+
+Get the full pathname including app version.
+
+```typescript
+function useFullPathname(): string;
+```
+
+#### Example
+
+```typescript
+<script lang="ts">
+  import { useFullPathname } from '@finsweet/webflow-apps-utils';
+
+  const fullPathname = useFullPathname();
+</script>
+
+<div>Full URL Path: {fullPathname}</div>
+```
+
+## Interfaces
+
+### RouteConfig
+
+```typescript
+interface RouteConfig {
+	path: string; // Path pattern ('/users/:id')
+	component?: any; // Svelte component
+	meta?: Record<string, any>; // Route metadata
+}
+```
+
+### LocationInfo
+
+```typescript
+interface LocationInfo {
+	pathname: string; // Current pathname
+	search: string; // Query string
+	hash: string; // URL hash
+	url: URL; // Complete URL object
+	params: RouteParams; // Route parameters
+	query: URLSearchParams; // Query parameters object
+}
+```
+
+### RouteParams
+
+```typescript
+interface RouteParams {
+	[key: string]: string; // Parameter name to value mapping
+}
+```
+
+### HistoryEntry
+
+```typescript
+interface HistoryEntry {
+	pathname: string; // Path of history entry
+	timestamp: number; // Entry creation time
+	state?: any; // Optional state data
+}
+```
+
+## Examples
+
+### Complete Application Setup
+
+```typescript
+<!-- App.svelte -->
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { createRouter, RouterProvider, Route, Link } from '@finsweet/webflow-apps-utils';
+
+  // Import page components
+  import HomePage from './pages/HomePage.svelte';
+  import AboutPage from './pages/AboutPage.svelte';
+  import UserPage from './pages/UserPage.svelte';
+  import NotFoundPage from './pages/NotFoundPage.svelte';
+
+  // Create router with configuration
+  const router = createRouter({
+    basePath: '',
+    fallbackRoute: '/'
+  });
+
+  // Define routes
+  router.addRoutes([
+    { path: '/', component: HomePage, meta: { title: 'Home' } },
+    { path: '/about', component: AboutPage, meta: { title: 'About' } },
+    { path: '/users/:id', component: UserPage, meta: { title: 'User Profile' } },
+    { path: '*', component: NotFoundPage, meta: { title: 'Not Found' } }
+  ]);
+
+  onMount(() => {
+    // Initialize app version if needed
+    router.initAppVersion('/v1');
+  });
+</script>
+
+<RouterProvider {router}>
+  {#snippet children({ router, currentRoute, isNavigating })}
+    <div class="app">
+      <!-- Navigation -->
+      <nav class="navbar">
+        <div class="nav-brand">
+          <Link to="/">My App</Link>
+        </div>
+        <ul class="nav-links">
+          <li><Link to="/" exact activeClass="active">Home</Link></li>
+          <li><Link to="/about" activeClass="active">About</Link></li>
+          <li><Link to="/users/123" activeClass="active">Profile</Link></li>
+        </ul>
+      </nav>
+
+      <!-- Loading indicator -->
+      {#if isNavigating}
+        <div class="loading-bar"></div>
+      {/if}
+
+      <!-- Page title -->
+      <title>{currentRoute?.meta?.title || 'My App'}</title>
+
+      <!-- Main content -->
+      <main class="main-content">
+        <!-- Home Route -->
+        <Route path="/">
+          {#snippet children({ isActive })}
+            {#if isActive}
+              <HomePage />
+            {/if}
+          {/snippet}
+        </Route>
+
+        <!-- About Route -->
+        <Route path="/about" component={AboutPage} />
+
+        <!-- User Profile Route -->
+        <Route path="/users/:id">
+          {#snippet children({ params, isActive })}
+            {#if isActive}
+              <UserPage userId={params.id} />
+            {/if}
+          {/snippet}
+        </Route>
+
+        <!-- 404 Route -->
+        <Route path="*" exact={false} component={NotFoundPage} />
+      </main>
+    </div>
+  {/snippet}
+</RouterProvider>
+
+<style>
+  .app {
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .navbar {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 1rem 2rem;
+    background: #f8f9fa;
+    border-bottom: 1px solid #dee2e6;
+  }
+
+  .nav-links {
+    display: flex;
+    list-style: none;
+    gap: 1rem;
+    margin: 0;
+    padding: 0;
+  }
+
+  .nav-links :global(a) {
+    padding: 0.5rem 1rem;
+    text-decoration: none;
+    color: #495057;
+    border-radius: 4px;
+    transition: all 0.2s;
+  }
+
+  .nav-links :global(a:hover) {
+    background: #e9ecef;
+  }
+
+  .nav-links :global(a.active) {
+    background: #007bff;
+    color: white;
+  }
+
+  .loading-bar {
+    height: 3px;
+    background: linear-gradient(90deg, #007bff, #6610f2);
+    animation: slide 1s ease-in-out infinite;
+  }
+
+  @keyframes slide {
+    0% { transform: translateX(-100%); }
+    100% { transform: translateX(100vw); }
+  }
+
+  .main-content {
+    flex: 1;
+    padding: 2rem;
+  }
+</style>
+```
+
+### Using Hooks in Components
+
+```typescript
+<!-- UserProfile.svelte -->
+<script lang="ts">
+  import { useParams, useNavigate, useSearchParams } from '@finsweet/webflow-apps-utils';
+
+  const params = useParams();
+  const navigate = useNavigate();
+  const searchParams = useSearchParams();
+
+  // Reactive values
+  $: userId = params.id;
+  $: tab = searchParams.get('tab') || 'profile';
+
+  function switchTab(newTab: string) {
+    searchParams.set('tab', newTab);
+  }
+
+  function goBack() {
+    navigate('/users');
+  }
+</script>
+
+<div class="user-profile">
+  <header>
+    <button onclick={goBack}>← Back to Users</button>
+    <h1>User Profile: {userId}</h1>
+  </header>
+
+  <nav class="tabs">
+    <button
+      class:active={tab === 'profile'}
+      onclick={() => switchTab('profile')}
+    >
+      Profile
+    </button>
+    <button
+      class:active={tab === 'settings'}
+      onclick={() => switchTab('settings')}
+    >
+      Settings
+    </button>
+  </nav>
+
+  <main>
+    {#if tab === 'profile'}
+      <div>Profile content for user {userId}</div>
+    {:else if tab === 'settings'}
+      <div>Settings for user {userId}</div>
+    {/if}
+  </main>
+</div>
+```
+
+### Programmatic Navigation
+
+```typescript
+<!-- NavigationExample.svelte -->
+<script lang="ts">
+  import { useRouter, useNavigate, useLocation } from '@finsweet/webflow-apps-utils';
+
+  const router = useRouter();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  async function handleLogin(userData: any) {
+    // Simulate login
+    await loginUser(userData);
+
+    // Navigate to dashboard after login
+    navigate('/dashboard', {
+      replace: true,
+      state: { loginTime: Date.now() }
+    });
+  }
+
+  function handleLogout() {
+    // Clear user data
+    clearUserSession();
+
+    // Navigate to home and replace history
+    router.navigate('/', { replace: true });
+  }
+
+  function goToUserProfile(userId: string) {
+    navigate(`/users/${userId}?tab=profile`);
+  }
+
+  function navigateWithState() {
+    navigate('/results', {
+      state: {
+        searchQuery: 'example',
+        timestamp: Date.now()
+      }
+    });
+  }
+</script>
+
+<div>
+  <p>Current path: {location.pathname}</p>
+
+  <button onclick={() => goToUserProfile('123')}>
+    View User 123
+  </button>
+
+  <button onclick={navigateWithState}>
+    Search with State
+  </button>
+
+  <button onclick={handleLogout}>
+    Logout
+  </button>
+</div>
+```