@keenmate/svelte-spa-router 5.0.0-rc12 → 5.1.0

package/CHANGELOG.md

@@ -7,7 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [5.0.0-rc12] - 2025-02-12
+## [5.1.0] - TBD
+
+### Added
+- **Global Window API:** Added runtime debugging and introspection via `window.components['svelte-spa-router']`
+  - `version()` - Get library version at runtime
+  - `config` - Access package metadata (name, version, author, license, repository, homepage)
+  - `logging.enableLogging()` - Enable all debug logging from browser console
+  - `logging.disableLogging()` - Disable all logging from browser console
+  - `logging.setLogLevel(level)` - Set global log level from browser console
+  - `logging.setCategoryLevel(category, level)` - Control specific logging categories from browser console
+  - `logging.getCategories()` - List all available logging categories
+  - TypeScript support with full autocompletion for global API
+  - SSR-safe implementation (only initializes in browser)
+  - Namespace-safe pattern using `window.components` (shared across all component libraries)
+  - Enables debugging production issues without code changes or rebuilding
+  - Example: `window.components['svelte-spa-router'].logging.setCategoryLevel('ROUTER:NAVIGATION', 'debug')`
+
+## [5.0.0] - 2025-01-17 ✅ Published
+
+### Changed
+- **Code Quality:** Major ESLint cleanup - reduced linting issues from 161 to 11 (93% reduction)
+  - Removed unused imports across multiple modules (hierarchyLogger, location, untrack, hasRoute, etc.)
+  - Removed unused function parameters in test files
+  - Replaced unused catch error variables with bare catch blocks
+  - Added `src/lib/vendor/**` to eslint ignore list (third-party loglevel library)
+  - Remaining 11 warnings are false positives from ESLint not understanding Svelte 5 runes
+  - **Note:** If issues arise, this cleanup touched error-handler, hierarchy, navigation-guard, permissions, querystring-helpers, route-metadata, utils, and all test files
+- **Logger API:** Renamed `enableCategory()` to `setCategoryLevel()` for better clarity
+  - Old name was confusing: `enableCategory('ROUTER:SCROLL', 'silent')` reads as "enable to disable"
+  - New name is explicit: `setCategoryLevel('ROUTER:SCROLL', 'silent')` clearly sets the level
+  - Added `'silent'` to TypeScript type definitions for level parameter
+  - No backward compatibility - clean break for clearer API
+
+### Fixed
+- **Breaking:** Standardized Router callback prop naming to camelCase (JavaScript convention)
+  - `onrouteLoading` → `onRouteLoading`
+  - `onrouteLoaded` → `onRouteLoaded`
+  - `onconditionsFailed` → `onConditionsFailed`
+  - `onNotFound` remains unchanged (already correct)
+  - Updated all documentation, examples, tests, and showcase site
+  - **Migration:** Update your Router component props to use camelCase naming
+- **Permissions:** Completely redesigned unauthorized handling system
+  - Previously required manual `/unauthorized` route definition and `onUnauthorized` callback with hash-based navigation
+  - New system treats unauthorized state as special router state (like 404), not a regular route
+  - `/unauthorized` route no longer needs to be defined in routes object
+  - Respects configured routing mode (hash/history) instead of forcing hash navigation
+  - Two behavior modes available:
+    - `unauthorizedBehavior: 'component'` - Shows unauthorized component without changing URL (default)
+    - `unauthorizedBehavior: 'navigate'` - Navigates to configured unauthorized route
+  - Configure via `configurePermissions()` with new options: `unauthorizedBehavior`, `unauthorizedRoute`, `unauthorizedComponent`
+  - Router automatically detects permission failures by checking `routeContext.permissions`
+  - `createPermissionCondition()` only calls `onUnauthorized` handler if explicitly configured (backward compatibility)
+  - Added internal `hasExplicitHandler()` tracking to distinguish explicit callbacks from defaults
+  - **Migration:** Old `onUnauthorized` callback approach still works, new declarative config recommended
+- **Referrer Tracking:** Fixed referrer not being preserved on browser back/forward navigation
+  - Previously, pressing back button would show chronological previous route as referrer instead of original referrer
+  - Example: `/` → `/links` (referrer: `/`) → `/query` (referrer: `/links`) → [BACK] → `/links` showed referrer `/query` (wrong!) instead of `/` (correct)
+  - Root cause: navigationContext with referrer was calculated by router but never saved to history.state
+  - Solution: Router now saves calculated navigationContext (with referrer) back to history.state after route loads
+  - Added serialization handling for Proxy objects in params (uses JSON serialization fallback when structuredClone fails)
+  - Applied to both hash mode and history mode navigation
+  - Navigation sequence tracking now correctly increments on forward and decrements on back
+  - `goBack()` function simplified to use native browser back (`window.history.back()`) instead of manual push
+  - Referrer and scroll position now automatically restored from history.state on back/forward navigation
+- **Permissions:** Fixed `createProtectedRoute()` failing with synchronous component imports
+  - Error: "Cannot read properties of undefined (reading 'before')" when using sync imports like `component: AdminPanel`
+  - Root cause: `createProtectedRouteDefinition()` always treated components as async, causing Router to call component constructor as function returning `undefined`
+  - Solution: Detect sync vs async components - use `component` key for sync (let wrap() handle Promise wrapping) and `asyncComponent` key for async
+  - Now supports both patterns: `component: AdminPanel` (sync) and `component: () => import('./Admin.svelte')` (async)
+  - Async detection: `typeof component === 'function' && component.length === 0`
+
+## [5.0.0-rc12] - 2025-02-12 ✅ Published
 
 ### Fixed
 - **Critical:** Fixed missing TypeScript source files in published npm package
@@ -34,7 +105,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Uses vendored `loglevel` and `loglevel-plugin-prefix` libraries (ESM versions)
   - **Breaking API change**: `setDebugLoggingEnabled()` replaced with new API
     - Old: `import { setDebugLoggingEnabled } from '@keenmate/svelte-spa-router/utils'`
-    - New: `import { enableLogging, disableLogging, setLogLevel, enableCategory } from '@keenmate/svelte-spa-router/logger'`
+    - New: `import { enableLogging, disableLogging, setLogLevel, setCategoryLevel } from '@keenmate/svelte-spa-router/logger'`
   - **12 hierarchical categories** for granular control:
     - `ROUTER` - Core routing pipeline, route matching
     - `ROUTER:NAVIGATION` - push, pop, replace, goBack
@@ -53,8 +124,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Per-category control**: Enable specific categories at different log levels
     \`\`\`javascript
     disableLogging()  // Disable all
-    enableCategory('ROUTER:SCROLL', 'debug')  // Enable only scroll logs
-    enableCategory('ROUTER:NAVIGATION', 'info')  // Navigation at info level
+    setCategoryLevel('ROUTER:SCROLL', 'debug')  // Enable only scroll logs
+    setCategoryLevel('ROUTER:NAVIGATION', 'info')  // Navigation at info level
     \`\`\`
   - **Global level control**: \`setLogLevel('warn')\` to set all categories at once
   - Removed \`src/lib/internal/logging.js\` (custom implementation)

package/README.md

@@ -35,6 +35,135 @@ npm install @keenmate/svelte-spa-router
 
 > **⚠️ Important:** This package requires **Node.js 22 or higher** for production builds. Node.js 20 has compatibility issues with Svelte 5 that may cause runtime errors like "link is not defined" in production builds. Make sure your build environment (CI/CD, Docker, etc.) uses Node 22+.
 
+## Quick Start: Common Imports
+
+Here are the most frequently used imports and where to get them:
+
+### Basic Router Setup
+
+```javascript
+// Main Router component
+import Router from '@keenmate/svelte-spa-router'
+
+// Navigation functions - available from main module OR /utils
+import { push, replace, pop, goBack } from '@keenmate/svelte-spa-router'
+// Alternative:
+import { push, replace, pop, goBack } from '@keenmate/svelte-spa-router/utils'
+
+// Link action for <a> tags
+import { link } from '@keenmate/svelte-spa-router'
+```
+
+### Accessing Route Information
+
+```javascript
+// Get current route data (call as functions, not stores!)
+import { location, querystring, routeParams, navigationContext } from '@keenmate/svelte-spa-router'
+
+// Usage in components:
+const currentPath = $derived(location())        // e.g., "/user/123"
+const query = $derived(querystring())           // e.g., "?tab=profile"
+const params = $derived(routeParams())          // e.g., { id: "123" }
+const context = $derived(navigationContext())   // Navigation context data
+
+// Alternative: Access from /utils
+import { location, querystring, routeParams } from '@keenmate/svelte-spa-router'
+```
+
+**⚠️ Important:** In route components, prefer receiving `routeParams` as props instead of importing:
+
+```svelte
+<script>
+// Recommended in route components
+let { routeParams = {} } = $props()
+</script>
+
+<p>User ID: {routeParams.id}</p>
+```
+
+### Route Configuration
+
+```javascript
+// Wrap routes with loading/conditions
+import { wrap } from '@keenmate/svelte-spa-router/wrap'
+
+// Active link highlighting
+import active from '@keenmate/svelte-spa-router/active'
+
+// Named routes system
+import { registerRoutes, buildUrl } from '@keenmate/svelte-spa-router/routes'
+```
+
+### Advanced Features
+
+```javascript
+// Permission-based routing
+import {
+  configurePermissions,
+  createProtectedRoute,
+  hasPermission
+} from '@keenmate/svelte-spa-router/helpers/permissions'
+
+// Navigation guards
+import {
+  registerBeforeLeave,
+  unregisterBeforeLeave,
+  NavigationCancelledError
+} from '@keenmate/svelte-spa-router/helpers/navigation-guard'
+
+// Hierarchical route structure
+import { createHierarchy } from '@keenmate/svelte-spa-router/helpers/hierarchy'
+
+// Error handling
+import {
+  configureGlobalErrorHandler
+} from '@keenmate/svelte-spa-router/helpers/error-handler'
+import { GlobalErrorHandler } from '@keenmate/svelte-spa-router/helpers/GlobalErrorHandler'
+
+// URL utilities
+import { joinPaths } from '@keenmate/svelte-spa-router/helpers/url-helpers'
+
+// Query string helpers
+import {
+  parseQuerystring,
+  stringifyQuerystring,
+  updateQuerystring
+} from '@keenmate/svelte-spa-router/helpers/querystring'
+```
+
+### All Available Import Paths
+
+```javascript
+'@keenmate/svelte-spa-router'                        // Main module (Router, push, location, etc.)
+'@keenmate/svelte-spa-router/utils'                  // Alternative path for utils
+'@keenmate/svelte-spa-router/wrap'                   // Route wrapping
+'@keenmate/svelte-spa-router/active'                 // Active link action
+'@keenmate/svelte-spa-router/routes'                 // Named routes system
+'@keenmate/svelte-spa-router/constants'              // Constants and enums
+'@keenmate/svelte-spa-router/logger'                 // Debug logging
+'@keenmate/svelte-spa-router/helpers/permissions'    // Permission system
+'@keenmate/svelte-spa-router/helpers/navigation-guard'  // Navigation guards
+'@keenmate/svelte-spa-router/helpers/hierarchy'      // Hierarchical routes
+'@keenmate/svelte-spa-router/helpers/error-handler'  // Error handling
+'@keenmate/svelte-spa-router/helpers/GlobalErrorHandler'  // Error component
+'@keenmate/svelte-spa-router/helpers/url-helpers'    // URL utilities
+'@keenmate/svelte-spa-router/helpers/querystring'    // Query string helpers
+'@keenmate/svelte-spa-router/helpers/route-metadata' // Breadcrumbs/metadata
+'@keenmate/svelte-spa-router/helpers/filters'        // Filter parsing
+```
+
+**❌ Common Mistake:**
+
+```javascript
+// ❌ WRONG - /stores path doesn't exist (this was the old v3/v4 API)
+import { routeParams } from '@keenmate/svelte-spa-router/stores'
+
+// ✅ CORRECT - Import from main module or /utils
+import { routeParams } from '@keenmate/svelte-spa-router'
+```
+
+> **Note:** This is a Svelte 5 router using runes (`$state`, `$derived`), not Svelte stores. There is no `/stores` export path.
+
 ## Debug Logging
 
 The router includes a built-in debug logging system to help troubleshoot routing issues during development.
@@ -51,11 +180,11 @@ if (import.meta.env.DEV) {
 }
 
 // Or enable specific categories only
-import { disableLogging, enableCategory } from '@keenmate/svelte-spa-router/logger'
+import { disableLogging, setCategoryLevel } from '@keenmate/svelte-spa-router/logger'
 
 disableLogging()  // Disable all first
-enableCategory('ROUTER:SCROLL', 'debug')  // Enable only scroll logs
-enableCategory('ROUTER:NAVIGATION', 'info')  // Enable navigation at info level
+setCategoryLevel('ROUTER:SCROLL', 'debug')  // Enable only scroll logs
+setCategoryLevel('ROUTER:NAVIGATION', 'info')  // Enable navigation at info level
 ```
 
 ### What Gets Logged
@@ -88,15 +217,15 @@ The router provides **12 hierarchical logging categories** for granular control:
 ### Advanced Logging Control
 
 ```javascript
-import { setLogLevel, enableCategory } from '@keenmate/svelte-spa-router/logger'
+import { setLogLevel, setCategoryLevel } from '@keenmate/svelte-spa-router/logger'
 
 // Set global log level (affects all categories)
 setLogLevel('warn')  // Only show warnings and errors
 
 // Enable specific categories at different levels
 disableLogging()  // Start with all disabled
-enableCategory('ROUTER:SCROLL', 'debug')  // Debug scroll issues
-enableCategory('ROUTER:PERMISSIONS', 'info')  // Monitor permission checks
+setCategoryLevel('ROUTER:SCROLL', 'debug')  // Debug scroll issues
+setCategoryLevel('ROUTER:PERMISSIONS', 'info')  // Monitor permission checks
 ```
 
 **Log Levels:** `trace`, `debug`, `info`, `warn`, `error`, `silent`
@@ -233,7 +362,7 @@ Uses the History API with clean URLs like `http://example.com/path`.
 ```javascript
 // main.js
 import { mount } from 'svelte'
-import { setHashRoutingEnabled, setBasePath } from '@keenmate/svelte-spa-router/utils'
+import { setHashRoutingEnabled, setBasePath } from '@keenmate/svelte-spa-router'
 import App from './App.svelte'
 
 // Enable history mode
@@ -384,9 +513,12 @@ push({
   navigationContext: { source: 'toolbar', userId: 789 }
 })
 
-// Go back
+// Go back (browser back button)
 pop()
 
+// Go back to referrer (with scroll restoration) - requires referrer tracking
+goBack()
+
 // Replace current page (supports all formats above)
 replace('/book/3')
 replace(['bookDetail', { bookId: 456 }])
@@ -432,50 +564,115 @@ Navigation context:
 
 ### Referrer Tracking
 
-Automatically track and access information about the previous route:
+Automatically track and navigate back to the previous route with full context preservation.
+
+#### Enabling Referrer Tracking
+
+Configure in your main.js before mounting the app:
 
 ```javascript
-// main.js - Enable referrer tracking
-import { setIncludeReferrer } from '@keenmate/svelte-spa-router/utils'
+// main.js
+import { setIncludeReferrer } from '@keenmate/svelte-spa-router'
 
 setIncludeReferrer('always')  // Track referrer for all routes
-// Options: 'never' (default), 'notfound' (404 only), 'always'
 ```
 
+**Configuration Options:**
+- `'never'` (default) - Disable referrer tracking
+- `'notfound'` - Track referrer only for 404/catch-all routes
+- `'always'` - Track referrer for all navigation
+
+#### Using goBack() for "Go Back" Buttons
+
+The `goBack()` helper provides the best way to navigate back with automatic scroll restoration:
+
+```svelte
+<script>
+import { goBack, navigationContext } from '@keenmate/svelte-spa-router'
+
+const navContext = $derived(navigationContext())
+const referrer = $derived(navContext?.referrer)
+</script>
+
+{#if referrer}
+    <button onclick={goBack}>← Back to {referrer.location}</button>
+{/if}
+```
+
+**How it works:**
+- Navigates using browser's native back button (`window.history.back()`)
+- Automatically restores scroll position from when you first visited that page
+- Preserves the original referrer (not chronological previous route)
+- Falls back to `pop()` if no referrer exists
+
+> **⚠️ Important:** Use `goBack()` instead of manual `push(referrer.location)` to get automatic scroll restoration and proper back navigation behavior.
+
+#### What Gets Tracked
+
+The referrer object includes complete route context:
+
+```javascript
+{
+  location: '/documents/123',      // Previous route path
+  querystring: 'tab=settings',     // Query string
+  params: { id: '123' },           // Route parameters
+  routeName: 'documentDetail',     // Named route (if using named routes)
+  scrollX: 0,                      // Scroll position when leaving
+  scrollY: 245                     // Scroll position when leaving
+}
+```
+
+#### How It Works
+
+Referrers are automatically preserved in browser history:
+
+1. When you navigate forward, the router calculates the referrer and saves it to `history.state`
+2. When you press browser back/forward buttons, the referrer is restored from history
+3. Referrer tracking respects your routing mode (hash or history API)
+4. Scroll position is automatically saved and restored by `goBack()`
+
+The referrer is cleared when users manually type a URL or refresh the page.
+
+#### Advanced: Manual Navigation
+
+For cases requiring custom logic before navigation:
+
 ```svelte
-<!-- In any route component -->
 <script>
-import { push, navigationContext } from '@keenmate/svelte-spa-router/utils'
+import { push, navigationContext } from '@keenmate/svelte-spa-router'
 
 const navContext = $derived(navigationContext())
 const referrer = $derived(navContext?.referrer)
 
-function goBack() {
-    if (referrer?.location) {
+function customGoBack() {
+    if (!referrer?.location) {
+        // No referrer - fallback to home
+        push('/')
+        return
+    }
+
+    // Custom logic before navigation
+    if (await confirmUnsavedChanges()) {
         const url = referrer.querystring
             ? `${referrer.location}?${referrer.querystring}`
             : referrer.location
         push(url)
+        // Note: Manual push does NOT restore scroll position
     }
 }
 </script>
-
-{#if referrer}
-    <button onclick={goBack}>← Go Back to {referrer.location}</button>
-{/if}
 ```
 
-Referrer object contains:
-- `location` - Previous route path (e.g., '/documents/123')
-- `querystring` - Previous query string
-- `params` - Previous route parameters
-- `routeName` - Previous route name (if using named routes)
+> **Migration Note:** If you're currently using manual `push(referrer.location)` pattern, switch to `goBack()` for automatic scroll restoration and proper history navigation.
+
+#### Benefits over history.back()
 
-**Benefits over `history.back()`:**
-- Works correctly with `replace()` navigation
-- Allows conditional logic before navigating back
-- Access to full previous route context
-- Custom fallback destinations
+- **Automatic scroll restoration** - Returns to exact scroll position when you left
+- **Preserved in browser history** - Works with browser back/forward buttons
+- **Works with replace() navigation** - Referrer persists even when using `replace()`
+- **Conditional logic** - Check referrer before navigating back
+- **Full route context** - Access to params, querystring, route name
+- **Custom fallback** - Redirect to home or other route when no referrer exists
 
 ### Strict Parameter Replacement
 
@@ -483,7 +680,7 @@ Configure how missing route parameters are handled:
 
 ```javascript
 // main.js
-import { setParamReplacementPlaceholder } from '@keenmate/svelte-spa-router/utils'
+import { setParamReplacementPlaceholder } from '@keenmate/svelte-spa-router'
 
 // Set placeholder for missing parameters (default: 'N-A')
 setParamReplacementPlaceholder('N-A')
@@ -1522,7 +1719,7 @@ Define routes in a hierarchical tree structure as an alternative to flat definit
 **Enable hierarchical mode first:**
 ```javascript
 // main.js - before mounting app
-import { setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router/utils'
+import { setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router'
 
 setHierarchicalRoutesEnabled(true)
 ```
@@ -1600,7 +1797,7 @@ const routes = {
 import Router from '@keenmate/svelte-spa-router'
 
 // Navigation utilities
-import { routeParams, navigationContext } from '@keenmate/svelte-spa-router'
+import { push, replace, pop, goBack, location, querystring, routeParams, navigationContext } from '@keenmate/svelte-spa-router'
 
 // Named routes (for use with push/replace/link)
 import { registerRoutes, buildUrl } from '@keenmate/svelte-spa-router/routes'
@@ -1618,7 +1815,7 @@ import { createHierarchy } from '@keenmate/svelte-spa-router/helpers/hierarchy'
 import active from '@keenmate/svelte-spa-router/active'
 
 // Configuration
-import { setHashRoutingEnabled, setBasePath, setParamReplacementPlaceholder, setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router/utils'
+import { setHashRoutingEnabled, setBasePath, setParamReplacementPlaceholder, setHierarchicalRoutesEnabled } from '@keenmate/svelte-spa-router'
 
 // Querystring helpers (shared reactive state)
 import { configureQuerystring, query } from '@keenmate/svelte-spa-router/helpers/querystring'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/svelte-spa-router",
-  "version": "5.0.0-rc12",
+  "version": "5.1.0",
   "description": "Router for SPAs using Svelte 5 with runes, dual-mode routing, permissions, and error handling",
   "main": "./src/lib/index.js",
   "svelte": "./src/lib/Router.svelte",
@@ -21,7 +21,6 @@
   "exports": {
     ".": {
       "types": "./src/lib/index.d.ts",
-      "svelte": "./src/lib/Router.svelte",
       "import": "./src/lib/index.js"
     },
     "./active": {