@hub-kit/core 0.3.0

package/dist/components/shell/shell.js

@@ -0,0 +1,110 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { Link, useRouterState } from "@tanstack/react-router";
+import { ChevronDown, X } from "lucide-react";
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, } from "../../ui/breadcrumb.js";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../../ui/collapsible.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuTrigger, } from "../../ui/dropdown-menu.js";
+import { Separator } from "../../ui/separator.js";
+import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarTrigger, useSidebar, } from "../../ui/sidebar.js";
+import { Toaster } from "../../ui/sonner.js";
+import { TooltipProvider } from "../../ui/tooltip.js";
+import { cn } from "../../lib/class-names.js";
+import { buildCrumbs } from "./breadcrumbs.js";
+import { isShellGroup, } from "./types.js";
+const ShellLeafLabelContext = createContext(() => { });
+export function useShellLeafLabel(label) {
+    const set = useContext(ShellLeafLabelContext);
+    useEffect(() => {
+        set(label);
+        return () => set(null);
+    }, [set, label]);
+}
+export function ShellFooterGroup({ label, icon: Icon, items, active, }) {
+    const pathname = useRouterState({ select: (state) => state.location.pathname });
+    const { state, isMobile, setOpenMobile } = useSidebar();
+    const [open, setOpen] = useState(false);
+    const groupRef = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onPointerDown = (event) => {
+            if (!groupRef.current?.contains(event.target))
+                setOpen(false);
+        };
+        const onKeyDown = (event) => {
+            if (event.key === "Escape")
+                setOpen(false);
+        };
+        document.addEventListener("pointerdown", onPointerDown);
+        document.addEventListener("keydown", onKeyDown);
+        return () => {
+            document.removeEventListener("pointerdown", onPointerDown);
+            document.removeEventListener("keydown", onKeyDown);
+        };
+    }, [open]);
+    if (state === "collapsed" && !isMobile) {
+        return (_jsx(SidebarMenuItem, { children: _jsx(ShellRailMenu, { label: label, icon: Icon, items: items, active: active, align: "end" }) }));
+    }
+    return (_jsx(Collapsible, { open: open, onOpenChange: setOpen, className: "group/collapsible", children: _jsxs(SidebarMenuItem, { ref: groupRef, className: "flex flex-col", children: [_jsx(CollapsibleContent, { className: "overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down", children: _jsx(SidebarMenuSub, { className: "mx-1 mb-1 gap-0.5 rounded-md border border-l-4 border-border border-l-primary bg-popover p-1 shadow-xl", children: items.map((child) => {
+                            const childActive = child.to === "/" ? pathname === "/" : pathname.startsWith(child.to);
+                            return (_jsx(SidebarMenuSubItem, { children: _jsx(SidebarMenuSubButton, { asChild: true, isActive: childActive, children: _jsxs(Link, { to: child.to, "aria-current": childActive ? "page" : undefined, onClick: () => isMobile && setOpenMobile(false), children: [_jsx(child.icon, { className: "size-4" }), _jsx("span", { children: child.label })] }) }) }, child.key));
+                        }) }) }), _jsx(CollapsibleTrigger, { asChild: true, children: _jsxs(SidebarMenuButton, { children: [_jsx(Icon, {}), _jsx("span", { children: label }), _jsx(ChevronDown, { className: "ml-auto size-4 shrink-0 opacity-60 transition-transform group-data-[state=open]/collapsible:rotate-180" })] }) })] }) }));
+}
+export function ShellRailMenu({ label, icon: Icon, items, active, align = "start", }) {
+    const pathname = useRouterState({ select: (state) => state.location.pathname });
+    const { isMobile, setOpenMobile } = useSidebar();
+    return (_jsxs(DropdownMenu, { modal: false, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(SidebarMenuButton, { isActive: active, children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }), _jsxs(DropdownMenuContent, { side: isMobile ? "top" : "right", align: isMobile ? "start" : align, sideOffset: isMobile ? 8 : 10, collisionPadding: 12, className: cn("min-w-52 max-w-[calc(100vw-2rem)] overflow-visible border-l-4 border-l-primary shadow-xl", "relative before:absolute before:h-0 before:w-0 before:content-['']", "data-[side=right]:before:-left-2 data-[side=right]:before:border-y-8 data-[side=right]:before:border-r-8 data-[side=right]:before:border-y-transparent data-[side=right]:before:border-r-primary", "data-[side=right]:data-[align=start]:before:top-4 data-[side=right]:data-[align=end]:before:bottom-4", "data-[side=top]:before:-bottom-2 data-[side=top]:before:left-5 data-[side=top]:before:border-x-8 data-[side=top]:before:border-t-8 data-[side=top]:before:border-x-transparent data-[side=top]:before:border-t-primary"), children: [_jsx(DropdownMenuLabel, { children: label }), items.map((child) => {
+                        const childActive = child.to === "/" ? pathname === "/" : pathname.startsWith(child.to);
+                        return (_jsx(DropdownMenuItem, { asChild: true, children: _jsxs(Link, { to: child.to, "aria-current": childActive ? "page" : undefined, onClick: () => isMobile && setOpenMobile(false), className: cn("cursor-pointer", childActive && "font-medium text-brand"), children: [_jsx(child.icon, { className: "size-4" }), child.label] }) }, child.key));
+                    })] })] }));
+}
+export function Shell({ nav, logo, footer, headerActions, badges, homeLabel, staticLeafLabels, breadcrumbAriaLabel, closeLabel, children, }) {
+    const pathname = useRouterState({ select: (s) => s.location.pathname });
+    const [leafLabel, setLeafLabel] = useState(null);
+    const crumbs = useMemo(() => {
+        const built = buildCrumbs({ nav, pathname, homeLabel, staticLeafLabels });
+        if (leafLabel && built.length > 1) {
+            built[built.length - 1] = { ...built[built.length - 1], label: leafLabel };
+        }
+        return built;
+    }, [nav, pathname, homeLabel, staticLeafLabels, leafLabel]);
+    return (_jsx(TooltipProvider, { delayDuration: 200, children: _jsx(ShellLeafLabelContext.Provider, { value: setLeafLabel, children: _jsxs(SidebarProvider, { children: [_jsx(ShellSidebar, { nav: nav, logo: logo, footer: footer, badges: badges, closeLabel: closeLabel }), _jsxs(SidebarInset, { className: "min-w-0 bg-brand-wash", children: [_jsxs("header", { className: "sticky top-0 z-30 flex h-14 shrink-0 items-center gap-2 border-b border-sidebar-border bg-header/90 px-4 backdrop-blur-sm", children: [_jsx(SidebarTrigger, { className: "-ml-1 shrink-0" }), _jsx(Separator, { orientation: "vertical", className: "mr-1 h-4 shrink-0" }), _jsxs(Breadcrumb, { "aria-label": breadcrumbAriaLabel, className: "min-w-0", children: [_jsx(BreadcrumbList, { className: "flex-nowrap sm:hidden", children: _jsx(BreadcrumbItem, { className: "min-w-0", children: _jsx(BreadcrumbPage, { className: "truncate", children: crumbs[crumbs.length - 1]?.label }) }) }), _jsx(BreadcrumbList, { className: "hidden flex-nowrap sm:flex", children: crumbs.map((crumb, i) => {
+                                                    const last = i === crumbs.length - 1;
+                                                    return (_jsxs(BreadcrumbItem, { className: "min-w-0", children: [last ? (_jsx(BreadcrumbPage, { className: "truncate", children: crumb.label })) : crumb.to ? (_jsx(BreadcrumbLink, { asChild: true, children: _jsx(Link, { to: crumb.to, className: "truncate", children: crumb.label }) })) : (_jsx("span", { className: "truncate text-muted-foreground", children: crumb.label })), !last && _jsx(BreadcrumbSeparator, { className: "shrink-0" })] }, `${crumb.label}-${i}`));
+                                                }) })] }), headerActions && (_jsx("div", { className: "ml-auto flex shrink-0 items-center gap-2 pl-2", children: headerActions }))] }), _jsx("main", { className: "w-full min-w-0 px-4 py-4 sm:px-6", children: children }), _jsx(Toaster, { position: "bottom-right" })] })] }) }) }));
+}
+function ShellSidebar({ nav, logo, footer, badges, closeLabel, }) {
+    const pathname = useRouterState({ select: (s) => s.location.pathname });
+    const { state, isMobile, setOpenMobile } = useSidebar();
+    const closeOnMobile = () => {
+        if (isMobile)
+            setOpenMobile(false);
+    };
+    const railCollapsed = state === "collapsed" && !isMobile;
+    const isActive = (to) => (to === "/" ? pathname === "/" : pathname.startsWith(to));
+    return (_jsxs(Sidebar, { collapsible: "icon", children: [_jsxs(SidebarHeader, { className: "h-14 flex-row items-center justify-between px-3", children: [logo, isMobile && (_jsx("button", { type: "button", onClick: () => setOpenMobile(false), "aria-label": closeLabel, className: "-mr-1 shrink-0 cursor-pointer rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-sidebar-accent hover:text-foreground", children: _jsx(X, { className: "size-5" }) }))] }), _jsx(SidebarContent, { children: _jsx(SidebarGroup, { children: _jsx(SidebarMenu, { children: nav.map((item) => {
+                            const badge = badges?.[item.key];
+                            const showBadge = !!badge && badge.count > 0;
+                            if (!isShellGroup(item)) {
+                                const active = isActive(item.to);
+                                return (_jsxs(SidebarMenuItem, { children: [_jsx(SidebarMenuButton, { asChild: true, isActive: active, children: _jsxs(Link, { to: item.to, "aria-current": active ? "page" : undefined, onClick: closeOnMobile, children: [_jsx(item.icon, {}), _jsx("span", { children: item.label })] }) }), showBadge && _jsx(ShellBadgePill, { badge: badge })] }, item.key));
+                            }
+                            const groupActive = item.items.some((c) => isActive(c.to));
+                            if (railCollapsed) {
+                                return (_jsxs(SidebarMenuItem, { children: [_jsx(ShellRailMenu, { label: item.label, icon: item.icon, items: item.items, active: groupActive }), showBadge && _jsx(ShellBadgePill, { badge: badge })] }, item.key));
+                            }
+                            return (_jsx(ShellNavGroupItem, { item: item, groupActive: groupActive, isActive: isActive, closeOnMobile: closeOnMobile, badge: showBadge ? badge : undefined }, item.key));
+                        }) }) }) }), footer && _jsx(SidebarFooter, { className: "gap-2", children: footer }), _jsx(SidebarRail, {})] }));
+}
+function ShellNavGroupItem({ item, groupActive, isActive, closeOnMobile, badge, }) {
+    const [open, setOpen] = useState(groupActive);
+    useEffect(() => {
+        if (groupActive)
+            setOpen(true);
+    }, [groupActive]);
+    return (_jsx(Collapsible, { open: open, onOpenChange: setOpen, className: "group/collapsible", children: _jsxs(SidebarMenuItem, { children: [_jsx(CollapsibleTrigger, { asChild: true, children: _jsxs(SidebarMenuButton, { children: [_jsx(item.icon, {}), _jsx("span", { children: item.label }), _jsx(ChevronDown, { className: "ml-auto size-4 shrink-0 opacity-60 transition-transform group-data-[state=open]/collapsible:rotate-180" })] }) }), badge && _jsx(ShellBadgePill, { badge: badge, className: "right-8" }), _jsx(CollapsibleContent, { className: "overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down", children: _jsx(SidebarMenuSub, { children: item.items.map((child) => (_jsx(SidebarMenuSubItem, { children: _jsx(SidebarMenuSubButton, { asChild: true, isActive: isActive(child.to), children: _jsxs(Link, { to: child.to, "aria-current": isActive(child.to) ? "page" : undefined, onClick: closeOnMobile, children: [_jsx(child.icon, { className: "size-4" }), _jsx("span", { children: child.label })] }) }) }, child.key))) }) })] }) }));
+}
+function ShellBadgePill({ badge, className }) {
+    return (_jsx(SidebarMenuBadge, { title: badge.title, className: cn("pointer-events-none bg-amber-500 text-white", className), children: badge.count }));
+}

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

@@ -0,0 +1,23 @@
+import type { LucideIcon } from "lucide-react";
+export type ShellNavLink = {
+    key: string;
+    label: string;
+    to: string;
+    icon: LucideIcon;
+};
+export type ShellNavGroup = {
+    key: string;
+    label: string;
+    icon: LucideIcon;
+    items: ShellNavLink[];
+};
+export type ShellNavEntry = ShellNavLink | ShellNavGroup;
+export declare function isShellGroup(entry: ShellNavEntry): entry is ShellNavGroup;
+export type ShellBadge = {
+    count: number;
+    title?: string;
+};
+export type Crumb = {
+    label: string;
+    to?: string;
+};

package/dist/components/shell/types.js

@@ -0,0 +1,3 @@
+export function isShellGroup(entry) {
+    return "items" in entry;
+}

package/dist/components/tour/find-target.d.ts

@@ -0,0 +1 @@
+export declare function findTourTarget(target: string): HTMLElement | null;

package/dist/components/tour/find-target.js

@@ -0,0 +1,3 @@
+export function findTourTarget(target) {
+    return document.querySelector(`[data-tour="${target}"]`);
+}

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

@@ -0,0 +1,14 @@
+export type { TourContentBlock, TourDefinition, TourMap, TourPlacement, TourStep, } from "./types";
+export { TourProvider } from "./tour-provider";
+export type { TourProviderProps } from "./tour-provider";
+export type { TourState } from "./tour-context";
+export { findTourTarget } from "./find-target";
+export { useTour, useTourPlaceholderData } from "./use-tour";
+export { TourButton } from "./tour-button";
+export type { TourButtonProps } from "./tour-button";
+export { TourOverlay } from "./tour-overlay";
+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";

package/dist/components/tour/index.js

@@ -0,0 +1,8 @@
+export { TourProvider } from "./tour-provider.js";
+export { findTourTarget } from "./find-target.js";
+export { useTour, useTourPlaceholderData } from "./use-tour.js";
+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";

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

@@ -0,0 +1,10 @@
+export interface TourLabels {
+    openTour: string;
+    stepCounter: (current: number, total: number) => string;
+    next: string;
+    skip: string;
+    finish: string;
+    sampleData: string;
+    cardTitle: string;
+}
+export declare const englishTourLabels: TourLabels;

package/dist/components/tour/labels.js

@@ -0,0 +1,9 @@
+export const englishTourLabels = {
+    openTour: "Tour",
+    stepCounter: (current, total) => `${current} of ${total}`,
+    next: "Next",
+    skip: "Skip tour",
+    finish: "Done",
+    sampleData: "Sample data",
+    cardTitle: "Guided tour",
+};

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

@@ -0,0 +1,3 @@
+export declare function hasSeenTour(tourId: string): boolean;
+export declare function markTourSeen(tourId: string): void;
+export declare function resetSeenTours(): void;

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

@@ -0,0 +1,34 @@
+const STORAGE_KEY = "hub-kit.tour.seen";
+function readSeenIds() {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        const parsed = raw ? JSON.parse(raw) : null;
+        return Array.isArray(parsed) ? parsed.filter((id) => typeof id === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function hasSeenTour(tourId) {
+    return readSeenIds().includes(tourId);
+}
+export function markTourSeen(tourId) {
+    const ids = readSeenIds();
+    if (ids.includes(tourId)) {
+        return;
+    }
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify([...ids, tourId]));
+    }
+    catch {
+        return;
+    }
+}
+export function resetSeenTours() {
+    try {
+        localStorage.removeItem(STORAGE_KEY);
+    }
+    catch {
+        return;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { TourContentBlock } from "./types";
+export declare function TourBlock({ block }: {
+    block: TourContentBlock;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Info, TriangleAlert } from "lucide-react";
+export function TourBlock({ block }) {
+    switch (block.kind) {
+        case "paragraph":
+            return _jsx("p", { className: "text-[13px] leading-relaxed text-muted-foreground sm:text-[15px]", children: block.text });
+        case "list":
+            return (_jsx("ul", { className: "list-disc space-y-1 pl-5 text-[13px] text-muted-foreground sm:text-sm", children: block.items.map((item) => (_jsx("li", { children: item }, item))) }));
+        case "image":
+            return (_jsx("img", { src: block.src, alt: block.alt, className: "max-h-40 w-full rounded-md border object-cover" }));
+        case "video":
+            return (_jsxs("figure", { className: "space-y-1", children: [_jsx("video", { src: block.src, controls: true, className: "w-full rounded-md border" }), block.caption && (_jsx("figcaption", { className: "text-xs text-muted-foreground", children: block.caption }))] }));
+        case "link":
+            return (_jsx("a", { href: block.href, target: block.newTab ? "_blank" : undefined, rel: block.newTab ? "noreferrer" : undefined, className: "text-[13px] font-medium text-primary underline-offset-4 hover:underline sm:text-sm", children: block.label }));
+        case "keyValueList":
+            return (_jsx("dl", { className: "space-y-1 text-[13px] sm:text-sm", children: block.pairs.map((pair) => (_jsxs("div", { className: "flex justify-between gap-3", children: [_jsx("dt", { className: "text-muted-foreground", children: pair.label }), _jsx("dd", { className: "font-medium", children: pair.value })] }, pair.label))) }));
+        case "callout":
+            return _jsx(TourCallout, { tone: block.tone, text: block.text });
+    }
+}
+function TourCallout({ tone, text }) {
+    const isWarning = tone === "warning";
+    const Icon = isWarning ? TriangleAlert : Info;
+    return (_jsxs("div", { className: isWarning
+            ? "flex gap-2 rounded-md bg-[var(--warning-soft)] p-2 text-[13px] text-[var(--warning)] sm:text-sm"
+            : "flex gap-2 rounded-md bg-accent p-2 text-[13px] text-accent-foreground sm:text-sm", children: [_jsx(Icon, { className: "mt-0.5 size-4 shrink-0", "aria-hidden": "true" }), _jsx("span", { children: text })] }));
+}

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

@@ -0,0 +1,4 @@
+export interface TourButtonProps {
+    className?: string;
+}
+export declare function TourButton({ className }: TourButtonProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { HelpCircle } from "lucide-react";
+import { Button } from "../../ui/button.js";
+import { cn } from "../../lib/class-names.js";
+import { useTour } from "./use-tour.js";
+export function TourButton({ className }) {
+    const tour = useTour();
+    if (!tour || !tour.tour || tour.stepCount === 0) {
+        return null;
+    }
+    return (_jsxs(Button, { type: "button", variant: "ghost", size: "sm", className: cn("gap-1.5", className), onClick: tour.start, children: [_jsx(HelpCircle, { "aria-hidden": "true" }), tour.labels.openTour] }));
+}

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

@@ -0,0 +1,11 @@
+import type { TourLabels } from "./labels";
+import type { TourStep } from "./types";
+export interface TourCardProps {
+    step: TourStep;
+    stepIndex: number;
+    stepCount: number;
+    labels: TourLabels;
+    onNext: () => void;
+    onSkip: () => void;
+}
+export declare function TourCard({ step, stepIndex, stepCount, labels, onNext, onSkip }: TourCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from "../../ui/button.js";
+import { TourBlock } from "./tour-blocks.js";
+export function TourCard({ step, stepIndex, stepCount, labels, onNext, onSkip }) {
+    const isLastStep = stepIndex + 1 >= stepCount;
+    return (_jsxs("div", { children: [_jsx("span", { className: "inline-flex rounded-full bg-[var(--tour-accent,var(--primary))] px-2 py-0.5 text-[11px] font-semibold text-primary-foreground sm:text-xs", children: labels.stepCounter(stepIndex + 1, stepCount) }), _jsx("h2", { className: "mt-2 text-[15px] font-semibold leading-snug text-popover-foreground sm:text-[17px]", children: step.title }), _jsx("div", { className: "mt-2 max-h-[min(70vh,calc(var(--radix-popover-content-available-height,70vh)-6rem))] space-y-2 overflow-y-auto pr-3 pb-1", children: step.content.map((block, index) => (_jsx(TourBlock, { block: block }, index))) }), _jsxs("div", { className: "mt-2 flex items-center justify-between gap-2", children: [_jsx("button", { type: "button", onClick: onSkip, className: "cursor-pointer text-[12px] text-muted-foreground transition-colors hover:text-foreground sm:text-sm", children: labels.skip }), _jsx(Button, { type: "button", onClick: onNext, className: "h-7 rounded-lg bg-[var(--tour-accent,var(--primary))] px-3.5 text-[12px] sm:h-8 sm:px-5 sm:text-sm", children: isLastStep ? labels.finish : labels.next })] })] }));
+}

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

@@ -0,0 +1,16 @@
+import type { TourLabels } from "./labels";
+import type { TourDefinition, TourStep } from "./types";
+export interface TourState {
+    tour: TourDefinition | null;
+    step: TourStep | null;
+    stepIndex: number;
+    stepCount: number;
+    isOpen: boolean;
+    showsPlaceholderData: boolean;
+    labels: TourLabels;
+    start: () => void;
+    next: () => void;
+    back: () => void;
+    skip: () => void;
+}
+export declare const TourContext: import("react").Context<TourState | null>;

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

@@ -0,0 +1,2 @@
+import { createContext } from "react";
+export const TourContext = createContext(null);

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

@@ -0,0 +1 @@
+export declare function TourOverlay(): import("react").JSX.Element | null;

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

@@ -0,0 +1,165 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Popover, PopoverAnchor, PopoverArrow, PopoverContent } from "../../ui/popover.js";
+import { findTourTarget } from "./find-target.js";
+import { TourCard } from "./tour-card.js";
+import { useTour } from "./use-tour.js";
+const SPOTLIGHT_PADDING = 6;
+const MOVE_DURATION = "220ms";
+const TALL_TARGET_GAP = 0.45;
+const MAX_CARD_WIDTH = 352;
+const SCREEN_MARGIN = 32;
+const ESTIMATED_CARD_HEIGHT = 240;
+const CARD_GAP = 12;
+export function TourOverlay() {
+    const tour = useTour();
+    const step = tour?.step ?? null;
+    const target = step?.target ?? null;
+    const [rect, setRect] = useState(null);
+    const [viewport, setViewport] = useState({ width: 0, height: 0 });
+    useEffect(() => {
+        const readViewport = () => setViewport({ width: window.innerWidth, height: window.innerHeight });
+        readViewport();
+        window.addEventListener("resize", readViewport);
+        return () => window.removeEventListener("resize", readViewport);
+    }, []);
+    const cardRef = useRef(null);
+    const skipMissingStep = useRef(() => { });
+    skipMissingStep.current = tour ? tour.next : () => { };
+    useEffect(() => {
+        if (!target) {
+            setRect(null);
+            return;
+        }
+        let stopMeasuring;
+        const watch = (element) => {
+            if (element.getBoundingClientRect().height > window.innerHeight * 0.6) {
+                revealTallTarget(element);
+            }
+            else {
+                element.scrollIntoView({ block: "center", behavior: "smooth" });
+            }
+            let frame = 0;
+            const measure = () => {
+                const box = element.getBoundingClientRect();
+                setRect((current) => current &&
+                    current.top === box.top &&
+                    current.left === box.left &&
+                    current.width === box.width &&
+                    current.height === box.height
+                    ? current
+                    : { top: box.top, left: box.left, width: box.width, height: box.height });
+                frame = requestAnimationFrame(measure);
+            };
+            measure();
+            stopMeasuring = () => cancelAnimationFrame(frame);
+        };
+        const element = findTourTarget(target);
+        if (element) {
+            watch(element);
+            return () => stopMeasuring?.();
+        }
+        setRect(null);
+        const frame = requestAnimationFrame(() => {
+            const lateElement = findTourTarget(target);
+            if (lateElement) {
+                watch(lateElement);
+            }
+            else {
+                skipMissingStep.current();
+            }
+        });
+        return () => {
+            cancelAnimationFrame(frame);
+            stopMeasuring?.();
+        };
+    }, [target]);
+    useEffect(() => {
+        const wrapper = cardRef.current?.closest("[data-radix-popper-content-wrapper]");
+        if (wrapper) {
+            wrapper.style.transition = `transform ${MOVE_DURATION} ease`;
+        }
+    }, [target]);
+    useEffect(() => {
+        if (!tour?.isOpen) {
+            return;
+        }
+        const onKeyDown = (event) => {
+            if (event.key === "Escape") {
+                tour.skip();
+            }
+            else if (event.key === "ArrowRight") {
+                tour.next();
+            }
+            else if (event.key === "ArrowLeft") {
+                tour.back();
+            }
+        };
+        document.addEventListener("keydown", onKeyDown);
+        return () => document.removeEventListener("keydown", onKeyDown);
+    }, [tour]);
+    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: {
+                    top: rect.top - SPOTLIGHT_PADDING,
+                    left: rect.left - SPOTLIGHT_PADDING,
+                    width: rect.width + SPOTLIGHT_PADDING * 2,
+                    height: rect.height + SPOTLIGHT_PADDING * 2,
+                    borderRadius: "var(--tour-spotlight-radius, calc(var(--radius) + 4px))",
+                    transition: `top ${MOVE_DURATION} ease, left ${MOVE_DURATION} ease, width ${MOVE_DURATION} ease, height ${MOVE_DURATION} ease`,
+                    boxShadow: [
+                        "0 0 0 3px var(--tour-ring-gap, var(--background))",
+                        "0 0 0 5px var(--tour-accent, var(--primary))",
+                    ].join(", "),
+                } }), _jsxs(Popover, { open: true, children: [_jsx(PopoverAnchor, { asChild: true, children: _jsx("div", { className: "absolute", style: { top: rect.top, left: rect.left, width: rect.width, height: rect.height } }) }), _jsxs(PopoverContent, { ref: cardRef, side: sideForScreen(step.placement, rect, viewport), align: "center", sideOffset: 12, arrowPadding: 16, collisionPadding: 16, className: "w-[min(var(--tour-card-width,22rem),calc(100vw-2rem))] rounded-2xl border-0 px-4 pt-4 pb-2.5 shadow-xl sm:px-5 sm:pt-5 sm:pb-3.5", onOpenAutoFocus: (event) => event.preventDefault(), onEscapeKeyDown: (event) => event.preventDefault(), onPointerDownOutside: (event) => event.preventDefault(), onInteractOutside: (event) => event.preventDefault(), "aria-label": tour.labels.cardTitle, children: [_jsx(TourCard, { step: step, stepIndex: tour.stepIndex, stepCount: tour.stepCount, labels: tour.labels, onNext: tour.next, onSkip: tour.skip }), _jsx(PopoverArrow, { width: 18, height: 9, style: { fill: "var(--popover)" } })] })] })] }));
+}
+function sideForScreen(placement, rect, viewport) {
+    if (viewport.width === 0) {
+        return placement ?? "bottom";
+    }
+    const cardWidth = Math.min(MAX_CARD_WIDTH, viewport.width - SCREEN_MARGIN);
+    const space = {
+        top: rect.top,
+        bottom: viewport.height - (rect.top + rect.height),
+        left: rect.left,
+        right: viewport.width - (rect.left + rect.width),
+    };
+    const fits = {
+        top: space.top >= ESTIMATED_CARD_HEIGHT + CARD_GAP,
+        bottom: space.bottom >= ESTIMATED_CARD_HEIGHT + CARD_GAP,
+        left: space.left >= cardWidth + CARD_GAP,
+        right: space.right >= cardWidth + CARD_GAP,
+    };
+    if (placement && fits[placement]) {
+        return placement;
+    }
+    if (fits.bottom)
+        return "bottom";
+    if (fits.top)
+        return "top";
+    if (fits.right)
+        return "right";
+    if (fits.left)
+        return "left";
+    return space.bottom >= space.top ? "bottom" : "top";
+}
+function scrollingAncestor(element) {
+    let node = element.parentElement;
+    while (node) {
+        const overflowY = getComputedStyle(node).overflowY;
+        if ((overflowY === "auto" || overflowY === "scroll") && node.scrollHeight > node.clientHeight) {
+            return node;
+        }
+        node = node.parentElement;
+    }
+    return document.scrollingElement ?? document.documentElement;
+}
+function revealTallTarget(element) {
+    const container = scrollingAncestor(element);
+    const isPageScroll = container === document.scrollingElement || container === document.documentElement;
+    const containerTop = isPageScroll ? 0 : container.getBoundingClientRect().top;
+    const gapAbove = window.innerHeight * TALL_TARGET_GAP;
+    const delta = element.getBoundingClientRect().top - containerTop - gapAbove;
+    container.scrollBy({ top: delta, behavior: "smooth" });
+}

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

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

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

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 { TourContext } from "./tour-context.js";
+import { TourOverlay } from "./tour-overlay.js";
+export function TourProvider({ tours, labels = englishTourLabels, children }) {
+    const pathname = useRouterState({ select: (state) => state.location.pathname });
+    const tour = tours[pathname] ?? null;
+    const [openTourId, setOpenTourId] = useState(null);
+    const [stepIndex, setStepIndex] = useState(0);
+    const isOpen = tour !== null && openTourId === tour.id;
+    const close = useCallback(() => {
+        setOpenTourId(null);
+        setStepIndex(0);
+    }, []);
+    useEffect(() => {
+        close();
+    }, [pathname, close]);
+    const tourId = tour?.id ?? null;
+    const autoStartAllowed = tour?.autoStart !== false;
+    const firstTarget = tour?.steps[0]?.target ?? null;
+    useEffect(() => {
+        if (!tourId || !firstTarget || !autoStartAllowed || hasSeenTour(tourId)) {
+            return;
+        }
+        const frame = requestAnimationFrame(() => {
+            if (findTourTarget(firstTarget)) {
+                setStepIndex(0);
+                setOpenTourId(tourId);
+            }
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [tourId, firstTarget, autoStartAllowed]);
+    const start = useCallback(() => {
+        if (!tour || tour.steps.length === 0) {
+            return;
+        }
+        setStepIndex(0);
+        setOpenTourId(tour.id);
+    }, [tour]);
+    const finish = useCallback(() => {
+        if (tour) {
+            markTourSeen(tour.id);
+        }
+        close();
+    }, [tour, close]);
+    const next = useCallback(() => {
+        if (!tour) {
+            return;
+        }
+        if (stepIndex + 1 >= tour.steps.length) {
+            finish();
+            return;
+        }
+        setStepIndex(stepIndex + 1);
+    }, [tour, stepIndex, finish]);
+    const back = useCallback(() => {
+        setStepIndex((index) => (index > 0 ? index - 1 : index));
+    }, []);
+    const value = useMemo(() => {
+        const step = isOpen && tour ? (tour.steps[stepIndex] ?? null) : null;
+        return {
+            tour,
+            step,
+            stepIndex,
+            stepCount: tour ? tour.steps.length : 0,
+            isOpen,
+            showsPlaceholderData: step?.showPlaceholderData === true,
+            labels,
+            start,
+            next,
+            back,
+            skip: finish,
+        };
+    }, [tour, stepIndex, isOpen, labels, start, next, back, finish]);
+    return (_jsxs(TourContext.Provider, { value: value, children: [children, _jsx(TourOverlay, {})] }));
+}

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

@@ -0,0 +1,44 @@
+export type TourContentBlock = {
+    kind: "paragraph";
+    text: string;
+} | {
+    kind: "list";
+    items: string[];
+} | {
+    kind: "image";
+    src: string;
+    alt: string;
+} | {
+    kind: "video";
+    src: string;
+    caption?: string;
+} | {
+    kind: "link";
+    href: string;
+    label: string;
+    newTab?: boolean;
+} | {
+    kind: "keyValueList";
+    pairs: {
+        label: string;
+        value: string;
+    }[];
+} | {
+    kind: "callout";
+    tone: "info" | "warning";
+    text: string;
+};
+export type TourPlacement = "top" | "bottom" | "left" | "right";
+export interface TourStep {
+    target: string;
+    title: string;
+    content: TourContentBlock[];
+    placement?: TourPlacement;
+    showPlaceholderData?: boolean;
+}
+export interface TourDefinition {
+    id: string;
+    steps: TourStep[];
+    autoStart?: boolean;
+}
+export type TourMap = Record<string, TourDefinition>;

package/dist/components/tour/types.js

@@ -0,0 +1 @@
+export {};