@urbicon-ui/blocks 6.7.0 → 6.8.0

package/dist/components/Guide/GuideProvider.svelte

@@ -3,14 +3,15 @@
   import type { GuideProviderProps } from './index';
   import { setGuideContext } from './guide.context';
 
-  let { storage, controller, children }: GuideProviderProps = $props();
+  let { storage, navigate, controller, children }: GuideProviderProps = $props();
 
   // Use a consumer-supplied controller (for programmatic access from outside the provider)
   // or create one. Built once from the initial props — a stable controller/adapter is
   // expected, so later prop changes are intentionally ignored. SSR-safe: the default
-  // adapter only touches localStorage inside load/save.
+  // adapter only touches localStorage inside load/save. `storage`/`navigate` are ignored
+  // when a `controller` is supplied (it already carries them).
   // svelte-ignore state_referenced_locally
-  const instance = controller ?? new GuideController({ storage });
+  const instance = controller ?? new GuideController({ storage, navigate });
   setGuideContext(instance);
 </script>
 

package/dist/components/Guide/index.d.ts

@@ -30,10 +30,17 @@ import type { GuideArticleSlots, GuideBeaconSlots, GuideBeaconVariants, GuideHin
 export interface GuideProviderProps {
     /** Persistence adapter for "seen" state (tours/hints). @default localStorage-backed adapter */
     storage?: GuideStorageAdapter;
+    /**
+     * Navigation hook for declarative cross-route tours, forwarded to the internally created
+     * controller. A SvelteKit consumer wires `(route) => goto(route)`; a step's `route` then
+     * navigates before its spotlight. Ignored when a `controller` is supplied (set it there).
+     * @default undefined
+     */
+    navigate?: (route: string) => void | Promise<void>;
     /**
      * Supply a pre-created `GuideController` for programmatic access from outside the provider
      * (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one
-     * internally and shares it via context. When supplied, `storage` is ignored.
+     * internally and shares it via context. When supplied, `storage` and `navigate` are ignored.
      */
     controller?: GuideController;
     /** App subtree wired to the Guide context. */

package/dist/utils/guide.svelte.d.ts

@@ -15,6 +15,18 @@ export interface GuideTopicMeta {
 export interface GuideStep {
     /** `data-guide` id of the element to anchor to. Omit for a centered, target-less step. */
     target?: string;
+    /**
+     * Optional route this step lives on — declarative cross-route touring. When set and different
+     * from the current location, the controller calls its injected `navigate` hook to go there
+     * **before** the spotlight, then re-anchors once the target appears on the new page (via the
+     * surface's existing `reapplyStepHighlight`). Such a tour-internal navigation keeps the tour
+     * running; a *foreign* navigation (the user leaving on their own) still stops it. Compared
+     * against `window.location.pathname` by default, so use a normalized path (no query/hash);
+     * inject a {@link GuideControllerOptions.navigationSource} for a custom router or base path.
+     * A `route` step with no `navigate` hook wired logs a DEV warning and stays put (no crash).
+     * @see GuideControllerOptions.navigate
+     */
+    route?: string;
     /** Step heading. */
     title?: string;
     /** Step body text. */
@@ -103,12 +115,45 @@ export interface GuideOverlayStackLike {
     /** Number of modal overlays currently open — drives the non-modal hide (§3.4). */
     readonly depth: number;
 }
+/**
+ * Source of the current route and navigation notifications the controller needs for cross-route
+ * tours (injectable for tests and custom routers). The default {@link createBrowserNavigationSource}
+ * reads `window.location.pathname` and subscribes via the Navigation API, falling back to `popstate`.
+ */
+export interface GuideNavigationSource {
+    /** The current path, compared against a step's `route` (e.g. `"/expenses"`). `''` on the server. */
+    current(): string;
+    /**
+     * Subscribe to navigations; `onNavigate` receives the new path. Returns an unsubscribe. The
+     * controller subscribes only while a tour with at least one `route` step is active, so a tour
+     * that never declares a route observes no navigation (preserving the manual-`goto` recipe).
+     */
+    subscribe(onNavigate: (path: string) => void): () => void;
+}
 /** Options for {@link GuideController}; every dependency is injectable for testing. */
 export interface GuideControllerOptions {
     /** Persistence adapter. @default localStorage-backed adapter */
     storage?: GuideStorageAdapter;
     /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
     overlayStack?: GuideOverlayStackLike;
+    /**
+     * Navigation hook for declarative cross-route tours. When a step's `route` differs from the
+     * current location, the controller calls this to navigate there before spotlighting the step.
+     * Framework-agnostic by injection — a SvelteKit consumer wires `(route) => goto(route)`. May be
+     * sync or async; a thrown/rejected navigation is swallowed (DEV-warned). A `route` step with no
+     * hook wired logs a DEV warning and stays on the current route (no crash). @default undefined
+     */
+    navigate?: (route: string) => void | Promise<void>;
+    /**
+     * Source for the current path + navigation events, used to decide whether a step's `route`
+     * needs navigating and to tell a tour-internal navigation from a foreign one (which stops the
+     * tour). @default a browser source reading `window.location.pathname` and listening via the
+     * Navigation API. Where that API is unavailable it falls back to `popstate` (back/forward only,
+     * not `pushState`), so a foreign *forward* navigation may go unobserved — inject a router-backed
+     * source (SvelteKit: `afterNavigate` + the `page` store; see docs/GUIDE.md §9) for reliable
+     * detection, or to handle a configured base path / custom router.
+     */
+    navigationSource?: GuideNavigationSource;
     /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
     dev?: boolean;
 }
@@ -117,6 +162,13 @@ export interface GuideControllerOptions {
  * resilient to private-mode / quota failures (mirrors `persistent-state`).
  */
 export declare function createLocalStorageAdapter(key?: string): GuideStorageAdapter;
+/**
+ * The default {@link GuideNavigationSource}: reads `window.location.pathname` and observes SPA
+ * navigations through the Navigation API when available — catching link clicks, programmatic
+ * navigation (`goto`), and back/forward — falling back to `popstate` (back/forward only) where it
+ * is not. SSR-safe: `current()` returns `''` and `subscribe()` is a no-op without a `window`.
+ */
+export declare function createBrowserNavigationSource(): GuideNavigationSource;
 /**
  * Headless engine for the Guide system — the UI-free state machine behind every
  * Guide surface (Panel, Marker, Mention, Hint, Tour).

package/dist/utils/guide.svelte.js

@@ -42,6 +42,57 @@ export function createLocalStorageAdapter(key = SEEN_STORAGE_KEY) {
         }
     };
 }
+/**
+ * The default {@link GuideNavigationSource}: reads `window.location.pathname` and observes SPA
+ * navigations through the Navigation API when available — catching link clicks, programmatic
+ * navigation (`goto`), and back/forward — falling back to `popstate` (back/forward only) where it
+ * is not. SSR-safe: `current()` returns `''` and `subscribe()` is a no-op without a `window`.
+ */
+export function createBrowserNavigationSource() {
+    let warnedFallback = false;
+    return {
+        current() {
+            return BROWSER ? window.location.pathname : '';
+        },
+        subscribe(onNavigate) {
+            if (!BROWSER)
+                return () => { };
+            const nav = window.navigation;
+            if (nav && typeof nav.addEventListener === 'function') {
+                const handler = (event) => {
+                    if (event.downloadRequest != null)
+                        return; // a download is not a route change
+                    const url = event.destination?.url;
+                    if (typeof url !== 'string')
+                        return;
+                    let path;
+                    try {
+                        path = new URL(url).pathname;
+                    }
+                    catch {
+                        return; // opaque/cross-origin destination — not a same-app route
+                    }
+                    onNavigate(path);
+                };
+                nav.addEventListener('navigate', handler);
+                return () => nav.removeEventListener('navigate', handler);
+            }
+            // `popstate` only catches back/forward, not `pushState` (a SvelteKit `goto` / intercepted
+            // link click), so a foreign *forward* navigation goes unobserved and the tour won't stop.
+            // Warn once so a degraded-detection browser is diagnosable; inject a router-backed
+            // navigationSource for reliable detection (docs/GUIDE.md §9).
+            if (import.meta.env?.DEV && !warnedFallback) {
+                warnedFallback = true;
+                console.warn('[Guide] the Navigation API is unavailable; cross-route foreign-navigation detection falls back to popstate and will miss pushState navigations (link clicks, goto). Inject a router-backed navigationSource for reliable detection — see docs/GUIDE.md §9.');
+            }
+            const onPop = () => onNavigate(window.location.pathname);
+            window.addEventListener('popstate', onPop);
+            return () => window.removeEventListener('popstate', onPop);
+        }
+    };
+}
+/** DEV-only: grace period for a navigated-to `route` step's target before warning it never showed. */
+const ROUTE_TARGET_TIMEOUT_MS = 4000;
 let tourIdCounter = 0;
 /** Opaque id for overlay-stack registration. Never SSR-rendered, so no hydration risk. */
 function nextOverlayId() {
@@ -101,6 +152,17 @@ export class GuideController {
     // independently of #activeTour (today they always change in lockstep).
     #tourOverlayId = $state(null);
     #tourUnregister = null;
+    // ── Cross-route touring ─────────────────────────────────
+    #navigate;
+    #navSource;
+    /** The path a tour-internal navigation is heading to; distinguishes our own nav from a foreign one. */
+    #expectedRoute = null;
+    /** Last path the tour is known to be on — set at start, updated on each handled navigation. */
+    #knownPath = '';
+    /** Unsubscribe from the navigation source; non-null only while a route-using tour runs. */
+    #navUnsub = null;
+    /** DEV-only timer that warns when a navigated-to step's target never appears. */
+    #routeTargetTimer = null;
     // ── Highlight (shared by tour steps + Mention→UI, Direction B) ──
     #highlightedId = $state(null);
     // ── Panel state (UI in Phase 3) ─────────────────────────
@@ -112,6 +174,8 @@ export class GuideController {
     constructor(options = {}) {
         this.#storage = options.storage ?? createLocalStorageAdapter();
         this.#overlayStack = options.overlayStack ?? overlayStack;
+        this.#navigate = options.navigate;
+        this.#navSource = options.navigationSource ?? createBrowserNavigationSource();
         // `import.meta.env?.DEV` is `boolean | undefined` (undefined outside Vite);
         // `?? false` keeps `#dev` a strict boolean and means non-Vite consumers
         // simply get no dev warnings (rather than a crash).
@@ -240,8 +304,14 @@ export class GuideController {
         this.#stepIndex = 0;
         this.#tourOverlayId = nextOverlayId();
         this.#tourUnregister = this.#overlayStack.register(this.#tourOverlayId, () => this.skip());
-        this.#applyStepHighlight();
-        this.#emitStep('start');
+        // Observe navigation only for tours that declare a step route. This keeps the manual-`goto`
+        // recipe (consumer navigates in `onStep`, no `step.route`) untouched, where a navigation is
+        // the consumer's own and must NOT be read as a foreign one that stops the tour.
+        this.#knownPath = this.#navSource.current();
+        if (tour.steps.some((s) => typeof s.route === 'string')) {
+            this.#navUnsub = this.#navSource.subscribe((path) => this.#onLocationChange(path));
+        }
+        this.#activateStep('start');
         return true;
     }
     /** Advance to the next step, or finish the tour if on the last step. */
@@ -253,16 +323,14 @@ export class GuideController {
             return;
         }
         this.#stepIndex += 1;
-        this.#applyStepHighlight();
-        this.#emitStep('next');
+        this.#activateStep('next');
     }
     /** Go back one step. No-op on the first step. */
     prev() {
         if (!this.#activeTour || this.isFirstStep)
             return;
         this.#stepIndex -= 1;
-        this.#applyStepHighlight();
-        this.#emitStep('prev');
+        this.#activateStep('prev');
     }
     /** Dismiss the tour without completing it — marks it seen, fires `onSkip`. */
     skip() {
@@ -304,6 +372,132 @@ export class GuideController {
         if (this.#activeTour)
             this.#applyStepHighlight();
     }
+    // ─── Cross-route touring ──────────────────────────────────────────────────
+    /**
+     * Make the now-current step active: trigger its cross-route navigation (if any), apply the
+     * highlight, then fire `onStep`. Shared by `startTour`/`next`/`prev`, so every entry point
+     * navigates symmetrically — including `prev()` stepping back across a route boundary.
+     */
+    #activateStep(via) {
+        this.#clearRouteTargetWarning();
+        this.#maybeNavigate();
+        this.#applyStepHighlight();
+        this.#emitStep(via);
+    }
+    /**
+     * If the active step lives on a different route, navigate there via the injected hook and record
+     * it as the `expectedRoute`, so the resulting navigation is recognized as the tour's own rather
+     * than a foreign one. Already on the route → nothing to do. No hook wired → DEV warning, stay put.
+     */
+    #maybeNavigate() {
+        // Each step starts with a clean slate — no navigation is pending until we trigger one below.
+        // (A step that doesn't navigate must not inherit the previous step's `expectedRoute`.)
+        this.#expectedRoute = null;
+        const route = this.currentStep?.route;
+        if (route == null)
+            return;
+        if (route === this.#navSource.current())
+            return;
+        if (!this.#navigate) {
+            if (this.#dev) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${this.#stepIndex}: step has route "${route}" but no navigate hook was provided to the GuideController — staying on the current route.`);
+            }
+            return;
+        }
+        this.#expectedRoute = route;
+        this.#scheduleRouteTargetWarning();
+        try {
+            const result = this.#navigate(route);
+            if (result && typeof result.then === 'function') {
+                result.catch((err) => {
+                    if (this.#dev)
+                        console.warn('[Guide] navigate hook rejected:', err);
+                    this.#abortPendingNavigation(route);
+                });
+            }
+        }
+        catch (err) {
+            if (this.#dev)
+                console.warn('[Guide] navigate hook threw:', err);
+            this.#abortPendingNavigation(route);
+        }
+    }
+    /**
+     * Roll back the bookkeeping for a navigation that failed (hook threw/rejected) — but only if it
+     * is still the pending one, so a newer step's navigation (the user clicked Next while this hook
+     * was in flight) is never clobbered by a late rejection. Clears the now-meaningless "target never
+     * appeared" timer too, so it can't later fire a misleading warning for a navigation that never ran.
+     */
+    #abortPendingNavigation(route) {
+        if (this.#expectedRoute !== route)
+            return;
+        this.#expectedRoute = null;
+        this.#clearRouteTargetWarning();
+    }
+    /**
+     * React to a navigation observed while a route-using tour runs. A navigation matching the pending
+     * `expectedRoute` is the tour's own → clear the flag and keep running (the ring lands via the
+     * surface's `reapplyStepHighlight`). Any other navigation is foreign — the user left, or a
+     * youngest-gesture-wins race — and tears the tour down, analytics-silent (`stopTour`).
+     */
+    #onLocationChange(path) {
+        if (!this.#activeTour)
+            return;
+        if (path === this.#knownPath)
+            return; // no pathname change (e.g. a hash/query update) — ignore
+        this.#knownPath = path;
+        if (this.#expectedRoute !== null && path === this.#expectedRoute) {
+            // The tour's own navigation landed — keep running. For a *targeted* step, keep `#expectedRoute`
+            // set until the target settles (`#applyStepHighlight`) so a redirecting / multi-hop source (the
+            // Navigation API emitting one event per hop) firing a *second* event for the redirect target is
+            // still recognized as a mismatch (and DEV-warned) instead of silently stopping. A *targetless*
+            // route step has no target to wait for — it is settled on landing, so clear now; otherwise a
+            // later foreign navigation would misfire the "navigated toward …" warning. (`#maybeNavigate`
+            // also resets it on the next step. Clearing here can't move into `#applyStepHighlight`, which
+            // runs synchronously in `#activateStep` before the nav lands — it would mis-read our own nav.)
+            if (this.currentStep?.target == null)
+                this.#expectedRoute = null;
+            return;
+        }
+        // Any other navigation stops the tour (analytics-silent). When one was pending, a landed path
+        // that doesn't match is most often a normalized `step.route` (trailing slash, base/locale
+        // prefix) rather than a genuine foreign nav — so surface it instead of a silent teardown on a
+        // one-character mismatch. (The strict stop is kept either way: better than running on a wrong page.)
+        if (this.#dev && this.#expectedRoute !== null) {
+            console.warn(`[Guide] tour "${this.#activeTour?.id}" navigated toward "${this.#expectedRoute}" but landed on "${path}" — stopping as a foreign navigation. If "${path}" is just a normalized form of the step's route (trailing slash, base/locale prefix), set step.route to the router's actual path.`);
+        }
+        this.#expectedRoute = null;
+        this.stopTour();
+    }
+    /**
+     * DEV-only: after navigating for a `route` step, warn if its target never appears so the spotlight
+     * can't land (the step still renders, centered over the scrim — it never hangs). Browser-gated, so
+     * no timer is ever scheduled under SSR or in node tests.
+     */
+    #scheduleRouteTargetWarning() {
+        if (!this.#dev || !BROWSER)
+            return;
+        const step = this.currentStep;
+        if (!step?.target)
+            return;
+        this.#clearRouteTargetWarning();
+        const index = this.#stepIndex;
+        const targetId = step.target;
+        const route = step.route;
+        this.#routeTargetTimer = setTimeout(() => {
+            this.#routeTargetTimer = null;
+            if (this.#stepIndex === index && !this.resolveTarget(targetId)) {
+                console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${index}: navigated to "${route}" but target "${targetId}" never appeared — showing the step without a spotlight ring.`);
+            }
+        }, ROUTE_TARGET_TIMEOUT_MS);
+    }
+    /** Cancel a pending route-target warning (target appeared, the step changed, or teardown). */
+    #clearRouteTargetWarning() {
+        if (this.#routeTargetTimer !== null) {
+            clearTimeout(this.#routeTargetTimer);
+            this.#routeTargetTimer = null;
+        }
+    }
     #endTour() {
         const tour = this.#activeTour;
         this.#teardownTour();
@@ -313,8 +507,12 @@ export class GuideController {
         if (tour && tour.once !== false)
             this.markSeen(tour.id);
     }
-    /** Reset all tour state and release the overlay-stack registration. No persistence. */
+    /** Reset all tour state and release the overlay-stack + navigation registrations. No persistence. */
     #teardownTour() {
+        this.#clearRouteTargetWarning();
+        this.#navUnsub?.();
+        this.#navUnsub = null;
+        this.#expectedRoute = null;
         this.clearHighlight();
         this.#tourUnregister?.();
         this.#tourUnregister = null;
@@ -364,10 +562,16 @@ export class GuideController {
             // Unlike Direction-B hover (which never scrolls), a tour drives the viewport —
             // the scroll is reduced-motion-aware inside `highlight`.
             this.highlight(step.target, { scroll: true });
+            this.#clearRouteTargetWarning(); // target landed → no "never appeared" warning needed
+            this.#expectedRoute = null; // the navigated-to target resolved → navigation fully settled
         }
         else {
             this.clearHighlight();
-            if (this.#dev) {
+            // A step bound to another route legitimately has no target on the current page — during the
+            // navigation gap, or when no navigate hook is wired — so don't warn "not found" there; the
+            // missing-hook and never-appeared paths own those diagnostics instead.
+            const offRoute = step.route != null && step.route !== this.#navSource.current();
+            if (this.#dev && !offRoute) {
                 console.warn(`[Guide] tour "${this.#activeTour?.id}" step ${this.#stepIndex}: target "${step.target}" not found in DOM.`);
             }
         }

package/dist/utils/index.d.ts

@@ -2,7 +2,7 @@ export * from './date.js';
 export * from './draggable.js';
 export * from './figma-token-export.js';
 export { arrow, autoUpdate, type ComputePositionReturn, computePosition, flip, type Middleware, offset, type Placement, type Strategy, shift, size } from './floating.js';
-export { createLocalStorageAdapter, GuideController, type GuideControllerOptions, type GuideDirection, type GuideEndEvent, type GuideOverlayStackLike, type GuideStep, type GuideStepEvent, type GuideStorageAdapter, type GuideTopicMeta, type GuideTour } from './guide.svelte.js';
+export { createBrowserNavigationSource, createLocalStorageAdapter, GuideController, type GuideControllerOptions, type GuideDirection, type GuideEndEvent, type GuideNavigationSource, type GuideOverlayStackLike, type GuideStep, type GuideStepEvent, type GuideStorageAdapter, type GuideTopicMeta, type GuideTour } from './guide.svelte.js';
 export * from './id.js';
 export { observeTargetResolution } from './observe-target.js';
 export { createOptionalContext } from './optional-context.js';

package/dist/utils/index.js

@@ -2,7 +2,7 @@ export * from './date.js';
 export * from './draggable.js';
 export * from './figma-token-export.js';
 export { arrow, autoUpdate, computePosition, flip, offset, shift, size } from './floating.js';
-export { createLocalStorageAdapter, GuideController } from './guide.svelte.js';
+export { createBrowserNavigationSource, createLocalStorageAdapter, GuideController } from './guide.svelte.js';
 export * from './id.js';
 export { observeTargetResolution } from './observe-target.js';
 export { createOptionalContext } from './optional-context.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -91,8 +91,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.7.0",
-    "@urbicon-ui/shared-types": "6.7.0",
+    "@urbicon-ui/i18n": "6.8.0",
+    "@urbicon-ui/shared-types": "6.8.0",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",