@keenmate/svelte-spa-router 5.0.0 → 5.1.1

package/CHANGELOG.md

@@ -5,9 +5,75 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.1.1] - 2025-11-30
+
+### Fixed
+- **Breadcrumbs preserved on querystring changes** - Fixed breadcrumbs resetting to "Loading..." when only the querystring changes (e.g., tab navigation)
+  - Issue: Changing tabs via `replace('/items/1', {}, { tab: 'settings' })` would reset dynamically updated breadcrumbs back to their initial "Loading..." state
+  - Root cause: `updateRouteMetadata()` was resetting the entire route context on any navigation, including querystring-only changes
+  - Solution: Detect when only querystring changed (same location + params) and preserve current breadcrumbs instead of resetting
+  - Also applies cached breadcrumb updates when the route context is updated
+
+### Added
+- **TabsDemo example** - New example demonstrating correct pattern for tabs with querystring state
+  - Shows how to use `replace()` instead of `push()` for tab changes
+  - Demonstrates dynamic breadcrumbs that persist across tab switches
+  - Located at `example/src/routes/TabsDemo.svelte`
+
+### Documentation
+- **AI Documentation Index** - Added comprehensive `ai/INDEX.txt` file for quick keyword lookup
+  - Organized by topic sections: Getting Started, Imports, Navigation, Named Routes, etc.
+  - Includes file descriptions, reading order recommendations, and cross-references
+  - Quick problem solving guide mapping common errors to solutions
+  - Examples organized by use case (Simple SPA, Admin Dashboard, E-commerce, etc.)
+- **Breadcrumbs with Tabs** - Added "TABS WITH QUERY STRING" section to `ai/breadcrumbs.txt`
+  - Documents the pattern for tabs that use querystring for state
+  - Explains why `replace()` is necessary to preserve breadcrumbs
+  - Includes complete code example
+- **Named Routes in Basic Setup** - Added "ENABLING NAMED ROUTES" section to `ai/basic-setup.txt`
+  - Documents that `registerRoutes()` must be called for named route navigation to work
+  - Shows common pattern with page definitions array
+  - Explains the "Route X not found in registry" error and how to fix it
+
 ## [Unreleased]
 
-## [5.0.0] - 2025-01-17
+### Documentation
+- **AI Assistant Documentation** - Added 15 concise text files in `./ai` folder optimized for AI assistants
+  - Plain text format (no markdown) with bullet-style structure for efficient AI parsing
+  - Files organized by feature: basic-setup, navigation, named-routes, route-params, permissions, guards-conditions, hierarchical-routes, tree-structure, link-actions, error-handling, referrer-tracking, debug-logging, import-patterns, utilities, breadcrumbs
+  - Includes correct/incorrect usage patterns (✅/❌) for common mistakes
+  - Code examples designed for copy-paste usage
+  - Complements CLAUDE.md by providing quick-reference documentation
+  - Aimed at helping AI coding assistants (like Claude, Cursor, Copilot) quickly understand router functionality
+- **Breadcrumbs Documentation** - Added comprehensive `ai/breadcrumbs.txt` covering breadcrumb navigation system
+  - Basic breadcrumb definition and structure
+  - Accessing breadcrumbs in components via `routeBreadcrumbs()` helper
+  - Breadcrumb component examples with navigation and styling
+  - Dynamic breadcrumb updates using `updateBreadcrumb(id, updates)` after data loads
+  - Integration with route parameters for dynamic segments
+  - Hierarchical breadcrumb inheritance with automatic concatenation
+  - Tree structure support with `createHierarchy()`
+  - Best practices and common patterns
+  - Debugging with ROUTER:METADATA logging category
+
+## [5.1.0] - 2025-11-20 ✅ Published
+
+### 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/svelte-spa-router",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "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",

package/src/lib/Router.svelte

@@ -595,11 +595,6 @@ function commitToReactiveState(ctx) {
                     }
                 }
 
-                // Debug log AFTER navigationContext is set
-                const finalReferrer = ctx.updatedNavigationContext?.referrer?.location || 'none'
-                const finalSeq = typeof window !== 'undefined' && window.history.state?.__navigationSequence || 0
-                console.log(`🔍 NAV: route="${ctx.location}" referrer="${finalReferrer}" seq=${finalSeq}`)
-
                 // Update current route tracking (unless catch-all)
                 if (!ctx.isCatchAll) {
                     currentRoute = ctx.location

package/src/lib/helpers/route-metadata.svelte.js

@@ -42,8 +42,11 @@ let updatedBreadcrumbsCache = new Map()
  * @param {Object} params - route params
  */
 export function updateRouteMetadata(routeContext = {}, location = '', querystring = '', params = {}) {
-    // Create a unique key for this route (location + querystring + params)
-    const routeKey = `${location}|${querystring}|${JSON.stringify(params)}`
+    // Create a key for the route path (without querystring) to detect actual route changes
+    const locationKey = `${location}|${JSON.stringify(params)}`
+
+    // Create full key including querystring for logging
+    const fullRouteKey = `${location}|${querystring}|${JSON.stringify(params)}`
 
     // Extract base path (e.g., /documents/1 → /documents, /documents/1/logs → /documents/1)
     // This is a simple heuristic: get path up to the last segment
@@ -56,12 +59,45 @@ export function updateRouteMetadata(routeContext = {}, location = '', querystrin
         clearBreadcrumbCache()
     }
 
-    // Only update if route actually changed
-    if (currentRouteKey !== routeKey) {
-        currentRouterouteContext = routeContext
-        currentRouteKey = routeKey
-        currentBasePath = basePath
-        metadataLogger.debug('[updateRouteMetadata] Route changed to:', routeKey)
+    // Check if only querystring changed (same location and params)
+    const onlyQuerystringChanged = currentRouteKey && currentRouteKey.startsWith(locationKey.split('|')[0] + '|')
+        && currentRouteKey.includes('|' + JSON.stringify(params))
+        && currentRouteKey !== fullRouteKey
+
+    // Only update context if the actual route (location + params) changed, not just querystring
+    if (currentRouteKey !== fullRouteKey) {
+        if (onlyQuerystringChanged) {
+            // Querystring-only change: preserve breadcrumbs, just update the key
+            metadataLogger.debug('[updateRouteMetadata] Querystring changed, preserving breadcrumbs')
+            currentRouteKey = fullRouteKey
+        } else {
+            // Actual route change: update context but apply cached breadcrumb updates
+            let finalContext = { ...routeContext }
+
+            // Apply any cached breadcrumb updates to the new context
+            if (routeContext.breadcrumbs && updatedBreadcrumbsCache.size > 0) {
+                const breadcrumbs = [...routeContext.breadcrumbs]
+                let appliedUpdates = false
+
+                for (const [id, updates] of updatedBreadcrumbsCache) {
+                    const index = breadcrumbs.findIndex(crumb => crumb.id === id)
+                    if (index !== -1) {
+                        breadcrumbs[index] = { ...breadcrumbs[index], ...updates }
+                        appliedUpdates = true
+                        metadataLogger.debug('[updateRouteMetadata] Applied cached update for:', id)
+                    }
+                }
+
+                if (appliedUpdates) {
+                    finalContext = { ...finalContext, breadcrumbs }
+                }
+            }
+
+            currentRouterouteContext = finalContext
+            currentRouteKey = fullRouteKey
+            currentBasePath = basePath
+            metadataLogger.debug('[updateRouteMetadata] Route changed to:', fullRouteKey)
+        }
     } else {
         metadataLogger.debug('[updateRouteMetadata] Same route, ignoring update')
     }

package/src/lib/index.js

@@ -24,3 +24,73 @@ export * from './helpers/filters.svelte.js';
 
 // Navigation guard system
 export * from './helpers/navigation-guard.svelte.js';
+
+// Import logging utilities for global API
+import {
+    enableLogging,
+    disableLogging,
+    setLogLevel,
+    setCategoryLevel
+} from './logger';
+
+/**
+ * @typedef {Object} GlobalRouterAPI
+ * @property {() => string} version - Get library version
+ * @property {Object} config - Package metadata
+ * @property {string} config.name - Package name
+ * @property {string} config.version - Package version
+ * @property {string} config.author - Package author
+ * @property {string} config.license - Package license
+ * @property {string} config.repository - Repository URL
+ * @property {string} config.homepage - Homepage URL
+ * @property {Object} logging - Logging controls
+ * @property {() => void} logging.enableLogging - Enable all debug logging
+ * @property {() => void} logging.disableLogging - Disable all logging
+ * @property {(level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent') => void} logging.setLogLevel - Set global log level
+ * @property {(category: string, level?: string) => void} logging.setCategoryLevel - Set category-specific log level
+ * @property {() => string[]} logging.getCategories - List all logging categories
+ */
+
+// List of all logging categories
+const LOGGING_CATEGORIES = [
+    'ROUTER',
+    'ROUTER:NAVIGATION',
+    'ROUTER:SCROLL',
+    'ROUTER:GUARDS',
+    'ROUTER:CONDITIONS',
+    'ROUTER:HIERARCHY',
+    'ROUTER:PERMISSIONS',
+    'ROUTER:ROUTES',
+    'ROUTER:ZONES',
+    'ROUTER:METADATA',
+    'ROUTER:ERROR_HANDLER',
+    'ROUTER:FILTERS'
+];
+
+// Initialize global API (SSR-safe)
+if (typeof window !== 'undefined') {
+    // Create components namespace if it doesn't exist
+    window.components = window.components || {};
+
+    // Initialize svelte-spa-router API
+    // Note: __VERSION__, __PACKAGE_NAME__, etc. are injected by build tools (Vite, Rollup)
+    // via the `define` option. Fallback values are provided for source distribution.
+    window.components['svelte-spa-router'] = {
+        version: () => typeof __VERSION__ !== 'undefined' ? __VERSION__ : '5.1.0',
+        config: {
+            name: typeof __PACKAGE_NAME__ !== 'undefined' ? __PACKAGE_NAME__ : '@keenmate/svelte-spa-router',
+            version: typeof __VERSION__ !== 'undefined' ? __VERSION__ : '5.1.0',
+            author: typeof __AUTHOR__ !== 'undefined' ? __AUTHOR__ : 'KeenMate (https://keenmate.com)',
+            license: typeof __LICENSE__ !== 'undefined' ? __LICENSE__ : 'MIT',
+            repository: typeof __REPOSITORY__ !== 'undefined' ? __REPOSITORY__ : 'https://github.com/keenmate/svelte-spa-router',
+            homepage: typeof __HOMEPAGE__ !== 'undefined' ? __HOMEPAGE__ : 'https://github.com/keenmate/svelte-spa-router#readme'
+        },
+        logging: {
+            enableLogging,
+            disableLogging,
+            setLogLevel,
+            setCategoryLevel,
+            getCategories: () => [...LOGGING_CATEGORIES]
+        }
+    };
+}