@finsweet/webflow-apps-utils 1.0.3 → 1.0.4

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.