@finsweet/webflow-apps-utils 1.0.4 → 1.0.6

package/dist/router/Router.mdx

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