@hub-kit/core 0.3.0 → 0.3.2

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

@@ -1,4 +1,4 @@
-export type { TourContentBlock, TourDefinition, TourMap, TourPlacement, TourStep, } from "./types";
+export type { TourContentBlock, TourDefinition, TourMap, TourOutcome, TourPlacement, TourSeenStore, TourStep, } from "./types";
 export { TourProvider } from "./tour-provider";
 export type { TourProviderProps } from "./tour-provider";
 export type { TourState } from "./tour-context";
@@ -11,4 +11,4 @@ export { TourCard } from "./tour-card";
 export type { TourCardProps } from "./tour-card";
 export { englishTourLabels } from "./labels";
 export type { TourLabels } from "./labels";
-export { hasSeenTour, markTourSeen, resetSeenTours } from "./seen-store";
+export { hasSeenTour, localTourSeenStore, markTourSeen, resetSeenTours, } from "./seen-store";

package/dist/components/tour/index.js

@@ -5,4 +5,4 @@ export { TourButton } from "./tour-button.js";
 export { TourOverlay } from "./tour-overlay.js";
 export { TourCard } from "./tour-card.js";
 export { englishTourLabels } from "./labels.js";
-export { hasSeenTour, markTourSeen, resetSeenTours } from "./seen-store.js";
+export { hasSeenTour, localTourSeenStore, markTourSeen, resetSeenTours, } from "./seen-store.js";

package/dist/components/tour/seen-store.d.ts

@@ -1,3 +1,5 @@
-export declare function hasSeenTour(tourId: string): boolean;
-export declare function markTourSeen(tourId: string): void;
+import type { TourSeenStore } from "./types";
+export declare function hasSeenTour(tourId: string, version?: number): boolean;
+export declare function markTourSeen(tourId: string, version?: number): void;
+export declare const localTourSeenStore: TourSeenStore;
 export declare function resetSeenTours(): void;

package/dist/components/tour/seen-store.js

@@ -1,29 +1,45 @@
 const STORAGE_KEY = "hub-kit.tour.seen";
-function readSeenIds() {
+function readEntries() {
     try {
         const raw = localStorage.getItem(STORAGE_KEY);
         const parsed = raw ? JSON.parse(raw) : null;
-        return Array.isArray(parsed) ? parsed.filter((id) => typeof id === "string") : [];
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.flatMap((entry) => {
+            if (typeof entry === "string") {
+                return [{ id: entry, version: 1 }];
+            }
+            if (entry && typeof entry === "object" && "id" in entry) {
+                const record = entry;
+                if (typeof record.id === "string") {
+                    return [{ id: record.id, version: Number(record.version) || 1 }];
+                }
+            }
+            return [];
+        });
     }
     catch {
         return [];
     }
 }
-export function hasSeenTour(tourId) {
-    return readSeenIds().includes(tourId);
+export function hasSeenTour(tourId, version = 1) {
+    return readEntries().some((entry) => entry.id === tourId && entry.version >= version);
 }
-export function markTourSeen(tourId) {
-    const ids = readSeenIds();
-    if (ids.includes(tourId)) {
-        return;
-    }
+export function markTourSeen(tourId, version = 1) {
+    const entries = readEntries().filter((entry) => entry.id !== tourId);
     try {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify([...ids, tourId]));
+        localStorage.setItem(STORAGE_KEY, JSON.stringify([...entries, { id: tourId, version }]));
     }
     catch {
         return;
     }
 }
+export const localTourSeenStore = {
+    isReady: true,
+    hasSeen: hasSeenTour,
+    markSeen: (tourId, version) => markTourSeen(tourId, version),
+};
 export function resetSeenTours() {
     try {
         localStorage.removeItem(STORAGE_KEY);

package/dist/components/tour/tour-overlay.js

@@ -80,6 +80,23 @@ export function TourOverlay() {
             wrapper.style.transition = `transform ${MOVE_DURATION} ease`;
         }
     }, [target]);
+    useEffect(() => {
+        if (!tour?.isOpen) {
+            return;
+        }
+        const body = document.body;
+        const previousOverflow = body.style.overflow;
+        const previousPadding = body.style.paddingRight;
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        body.style.overflow = "hidden";
+        if (scrollbarWidth > 0) {
+            body.style.paddingRight = `${scrollbarWidth}px`;
+        }
+        return () => {
+            body.style.overflow = previousOverflow;
+            body.style.paddingRight = previousPadding;
+        };
+    }, [tour?.isOpen]);
     useEffect(() => {
         if (!tour?.isOpen) {
             return;
@@ -101,7 +118,7 @@ export function TourOverlay() {
     if (!tour || !tour.isOpen || !step || !rect) {
         return null;
     }
-    return (_jsxs("div", { className: "fixed inset-0 z-50", role: "presentation", children: [_jsx("div", { className: "absolute inset-0", style: { background: "var(--tour-backdrop, rgb(0 0 0 / 0.5))" } }), _jsx("div", { className: "absolute", style: {
+    return (_jsxs("div", { className: "fixed inset-0 z-50", role: "presentation", onClick: tour.skip, children: [_jsx("div", { className: "absolute inset-0", style: { background: "var(--tour-backdrop, rgb(0 0 0 / 0.5))" } }), _jsx("div", { className: "absolute", style: {
                     top: rect.top - SPOTLIGHT_PADDING,
                     left: rect.left - SPOTLIGHT_PADDING,
                     width: rect.width + SPOTLIGHT_PADDING * 2,

package/dist/components/tour/tour-provider.d.ts

@@ -1,9 +1,10 @@
 import { type ReactNode } from "react";
 import { type TourLabels } from "./labels";
-import type { TourMap } from "./types";
+import type { TourMap, TourSeenStore } from "./types";
 export interface TourProviderProps {
     tours: TourMap;
     labels?: TourLabels;
+    seenStore?: TourSeenStore;
     children: ReactNode;
 }
-export declare function TourProvider({ tours, labels, children }: TourProviderProps): import("react").JSX.Element;
+export declare function TourProvider({ tours, labels, seenStore, children, }: TourProviderProps): import("react").JSX.Element;

package/dist/components/tour/tour-provider.js

@@ -3,10 +3,12 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { useRouterState } from "@tanstack/react-router";
 import { englishTourLabels } from "./labels.js";
 import { findTourTarget } from "./find-target.js";
-import { hasSeenTour, markTourSeen } from "./seen-store.js";
+import { localTourSeenStore } from "./seen-store.js";
 import { TourContext } from "./tour-context.js";
 import { TourOverlay } from "./tour-overlay.js";
-export function TourProvider({ tours, labels = englishTourLabels, children }) {
+const STABLE_FRAMES = 10;
+const MAX_WAIT_FRAMES = 600;
+export function TourProvider({ tours, labels = englishTourLabels, seenStore = localTourSeenStore, children, }) {
     const pathname = useRouterState({ select: (state) => state.location.pathname });
     const tour = tours[pathname] ?? null;
     const [openTourId, setOpenTourId] = useState(null);
@@ -20,20 +22,45 @@ export function TourProvider({ tours, labels = englishTourLabels, children }) {
         close();
     }, [pathname, close]);
     const tourId = tour?.id ?? null;
+    const tourVersion = tour?.version ?? 1;
     const autoStartAllowed = tour?.autoStart !== false;
     const firstTarget = tour?.steps[0]?.target ?? null;
+    const storeIsReady = seenStore.isReady;
+    const alreadySeen = tourId !== null && storeIsReady && seenStore.hasSeen(tourId, tourVersion);
     useEffect(() => {
-        if (!tourId || !firstTarget || !autoStartAllowed || hasSeenTour(tourId)) {
+        if (!tourId || !firstTarget || !autoStartAllowed || !storeIsReady || alreadySeen) {
             return;
         }
-        const frame = requestAnimationFrame(() => {
-            if (findTourTarget(firstTarget)) {
-                setStepIndex(0);
-                setOpenTourId(tourId);
+        let frame = 0;
+        let attempts = 0;
+        let lastHeight = -1;
+        let stableFrames = 0;
+        const waitForSettledPage = () => {
+            attempts += 1;
+            if (attempts > MAX_WAIT_FRAMES) {
+                return;
             }
-        });
+            const element = findTourTarget(firstTarget);
+            if (element) {
+                const height = element.getBoundingClientRect().height;
+                if (height > 0 && height === lastHeight) {
+                    stableFrames += 1;
+                    if (stableFrames >= STABLE_FRAMES) {
+                        setStepIndex(0);
+                        setOpenTourId(tourId);
+                        return;
+                    }
+                }
+                else {
+                    stableFrames = 0;
+                }
+                lastHeight = height;
+            }
+            frame = requestAnimationFrame(waitForSettledPage);
+        };
+        frame = requestAnimationFrame(waitForSettledPage);
         return () => cancelAnimationFrame(frame);
-    }, [tourId, firstTarget, autoStartAllowed]);
+    }, [tourId, firstTarget, autoStartAllowed, storeIsReady, alreadySeen]);
     const start = useCallback(() => {
         if (!tour || tour.steps.length === 0) {
             return;
@@ -41,22 +68,23 @@ export function TourProvider({ tours, labels = englishTourLabels, children }) {
         setStepIndex(0);
         setOpenTourId(tour.id);
     }, [tour]);
-    const finish = useCallback(() => {
+    const finish = useCallback((status) => {
         if (tour) {
-            markTourSeen(tour.id);
+            seenStore.markSeen(tour.id, tour.version ?? 1, { status, lastStep: stepIndex });
         }
         close();
-    }, [tour, close]);
+    }, [tour, seenStore, stepIndex, close]);
     const next = useCallback(() => {
         if (!tour) {
             return;
         }
         if (stepIndex + 1 >= tour.steps.length) {
-            finish();
+            finish("completed");
             return;
         }
         setStepIndex(stepIndex + 1);
     }, [tour, stepIndex, finish]);
+    const skip = useCallback(() => finish("skipped"), [finish]);
     const back = useCallback(() => {
         setStepIndex((index) => (index > 0 ? index - 1 : index));
     }, []);
@@ -73,8 +101,8 @@ export function TourProvider({ tours, labels = englishTourLabels, children }) {
             start,
             next,
             back,
-            skip: finish,
+            skip: skip,
         };
-    }, [tour, stepIndex, isOpen, labels, start, next, back, finish]);
+    }, [tour, stepIndex, isOpen, labels, start, next, back, skip]);
     return (_jsxs(TourContext.Provider, { value: value, children: [children, _jsx(TourOverlay, {})] }));
 }

package/dist/components/tour/types.d.ts

@@ -40,5 +40,15 @@ export interface TourDefinition {
     id: string;
     steps: TourStep[];
     autoStart?: boolean;
+    version?: number;
+}
+export type TourOutcome = "skipped" | "completed";
+export interface TourSeenStore {
+    isReady: boolean;
+    hasSeen: (tourId: string, version: number) => boolean;
+    markSeen: (tourId: string, version: number, outcome: {
+        status: TourOutcome;
+        lastStep: number;
+    }) => void;
 }
 export type TourMap = Record<string, TourDefinition>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hub-kit/core",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shared pages, components and theme system for all Hub projects.",
   "type": "module",
   "files": [