feat: add onboarding tour component and integrate into dashboard layout

- Introduced the OnboardingTour component to guide users through key features.
- Integrated the OnboardingTour into the DashboardClientLayout for improved user experience.
- Updated connector popup and sidebar navigation with data attributes for tour steps.

surfsense_web/app/dashboard/[search_space_id]/client-layout.tsx

@@ -17,6 +17,7 @@ import { activeSearchSpaceIdAtom } from "@/atoms/search-spaces/search-space-quer
 import { DocumentUploadDialogProvider } from "@/components/assistant-ui/document-upload-popup";
 import { DashboardBreadcrumb } from "@/components/dashboard-breadcrumb";
 import { LanguageSwitcher } from "@/components/LanguageSwitcher";
+import { OnboardingTour } from "@/components/onboarding-tour";
 import { AppSidebarProvider } from "@/components/sidebar/AppSidebarProvider";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";
@@ -242,6 +243,7 @@ export function DashboardClientLayout({
 
 	return (
 		<DocumentUploadDialogProvider>
+			<OnboardingTour />
 			<SidebarProvider className="h-full overflow-hidden" open={open} onOpenChange={setOpen}>
 				{/* Use AppSidebarProvider which fetches user, search space, and recent chats */}
 				<AppSidebarProvider

surfsense_web/components/assistant-ui/connector-popup.tsx

@@ -162,6 +162,7 @@ export const ConnectorIndicator: FC = () => {
 	return (
 		<Dialog open={isOpen} onOpenChange={handleOpenChange}>
 			<TooltipIconButton
+				data-joyride="connector-icon"
 				tooltip={hasConnectors ? `Manage ${activeConnectorsCount} connectors` : "Connect your data"}
 				side="bottom"
 				className={cn(

surfsense_web/components/onboarding-tour.tsx

@@ -0,0 +1,523 @@
+"use client";
+
+import { useTheme } from "next-themes";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+interface TourStep {
+	target: string;
+	title: string;
+	content: string;
+	placement: "top" | "bottom" | "left" | "right";
+}
+
+const TOUR_STEPS: TourStep[] = [
+	{
+		target: '[data-joyride="connector-icon"]',
+		title: "Connect your data sources",
+		content:
+			"Click this icon to connect and sync data from GitHub, Slack, Notion, Jira, Confluence, and more.",
+		placement: "bottom",
+	},
+	{
+		target: '[data-joyride="documents-sidebar"]',
+		title: "Manage your documents",
+		content: "Access and manage all your uploaded documents from the sidebar.",
+		placement: "right",
+	},
+];
+
+interface TooltipPosition {
+	top: number;
+	left: number;
+	pointerPosition: "top" | "bottom" | "left" | "right";
+}
+
+function calculatePosition(targetEl: Element, placement: TourStep["placement"]): TooltipPosition {
+	const rect = targetEl.getBoundingClientRect();
+	const scrollTop = window.scrollY;
+	const scrollLeft = window.scrollX;
+	const tooltipWidth = 280;
+	const tooltipHeight = 120;
+	const offset = 16;
+
+	let top = 0;
+	let left = 0;
+	let pointerPosition: TooltipPosition["pointerPosition"] = "left";
+
+	switch (placement) {
+		case "bottom":
+			top = rect.bottom + scrollTop + offset;
+			left = rect.left + scrollLeft + rect.width / 2 - tooltipWidth / 2;
+			pointerPosition = "top";
+			break;
+		case "top":
+			top = rect.top + scrollTop - tooltipHeight - offset;
+			left = rect.left + scrollLeft + rect.width / 2 - tooltipWidth / 2;
+			pointerPosition = "bottom";
+			break;
+		case "right":
+			top = rect.top + scrollTop + rect.height / 2 - tooltipHeight / 2;
+			left = rect.right + scrollLeft + offset;
+			pointerPosition = "left";
+			break;
+		case "left":
+			top = rect.top + scrollTop + rect.height / 2 - tooltipHeight / 2;
+			left = rect.left + scrollLeft - tooltipWidth - offset;
+			pointerPosition = "right";
+			break;
+	}
+
+	// Ensure tooltip stays within viewport
+	left = Math.max(10, Math.min(left, window.innerWidth - tooltipWidth - 10));
+	top = Math.max(10, top);
+
+	return { top, left, pointerPosition };
+}
+
+function Spotlight({
+	targetEl,
+	isDarkMode,
+	stepIndex,
+}: {
+	targetEl: Element;
+	isDarkMode: boolean;
+	stepIndex: number;
+}) {
+	const rect = targetEl.getBoundingClientRect();
+	const padding = 6;
+	const shadowColor = isDarkMode ? "#172554" : "#0c1a3a";
+
+	// Check if this is the connector icon step (stepIndex === 0)
+	const isConnectorStep = stepIndex === 0;
+
+	// For circle, use the larger dimension to ensure it's a perfect circle
+	const circleSize = isConnectorStep ? Math.max(rect.width, rect.height) : 0;
+	const circleTop = isConnectorStep ? rect.top + (rect.height - circleSize) / 2 : rect.top;
+	const circleLeft = isConnectorStep ? rect.left + (rect.width - circleSize) / 2 : rect.left;
+
+	return (
+		<>
+			{/* Dark overlay with cutout using box-shadow technique */}
+			<div
+				className="fixed pointer-events-none"
+				style={{
+					top: isConnectorStep ? circleTop - padding : rect.top - padding,
+					left: isConnectorStep ? circleLeft - padding : rect.left - padding,
+					width: isConnectorStep ? circleSize + padding * 2 : rect.width + padding * 2,
+					height: isConnectorStep ? circleSize + padding * 2 : rect.height + padding * 2,
+					borderRadius: isConnectorStep ? "50%" : 8,
+					boxShadow: `0 0 0 9999px rgba(0, 0, 0, 0.6)`,
+					backgroundColor: "transparent",
+					zIndex: 99996,
+				}}
+			/>
+			{/* Blue shadow behind the button - starts from button border */}
+			<div
+				className="fixed pointer-events-none"
+				style={{
+					top: isConnectorStep ? circleTop : rect.top,
+					left: isConnectorStep ? circleLeft : rect.left,
+					width: isConnectorStep ? circleSize : rect.width,
+					height: isConnectorStep ? circleSize : rect.height,
+					borderRadius: isConnectorStep ? "50%" : 8,
+					boxShadow: `0 0 10px 2px ${shadowColor}CC, 0 0 20px 6px ${shadowColor}99, 0 0 40px 12px ${shadowColor}66`,
+					backgroundColor: "transparent",
+					zIndex: 99997,
+				}}
+			/>
+		</>
+	);
+}
+
+function TourTooltip({
+	step,
+	stepIndex,
+	totalSteps,
+	position,
+	targetRect,
+	onNext,
+	onPrev,
+	onSkip,
+	isDarkMode,
+}: {
+	step: TourStep;
+	stepIndex: number;
+	totalSteps: number;
+	position: TooltipPosition;
+	targetRect: DOMRect;
+	onNext: () => void;
+	onPrev: () => void;
+	onSkip: () => void;
+	isDarkMode: boolean;
+}) {
+	const isLastStep = stepIndex === totalSteps - 1;
+	const isFirstStep = stepIndex === 0;
+
+	const bgColor = isDarkMode ? "#18181b" : "#18181b"; // Dark tooltip for both modes as shown in image
+	const textColor = "#ffffff";
+	const mutedTextColor = "#a1a1aa";
+
+	// Calculate pointer line position
+	const getPointerStyles = (): React.CSSProperties => {
+		const lineLength = 16;
+		const dotSize = 6;
+		// Check if this is the documents step (stepIndex === 1)
+		const isDocumentsStep = stepIndex === 1;
+
+		if (position.pointerPosition === "left") {
+			return {
+				position: "absolute",
+				left: -lineLength - dotSize,
+				top: isDocumentsStep ? "calc(50% - 8px)" : "50%",
+				transform: "translateY(-50%)",
+				display: "flex",
+				alignItems: "center",
+			};
+		}
+		if (position.pointerPosition === "top") {
+			return {
+				position: "absolute",
+				top: -lineLength - dotSize,
+				left: "50%",
+				transform: "translateX(-50%)",
+				display: "flex",
+				flexDirection: "column",
+				alignItems: "center",
+			};
+		}
+		return {};
+	};
+
+	const renderPointer = () => {
+		const lineColor = "#18181B";
+
+		if (position.pointerPosition === "left") {
+			return (
+				<div style={getPointerStyles()}>
+					<div
+						style={{
+							width: 6,
+							height: 6,
+							borderRadius: "50%",
+							backgroundColor: lineColor,
+						}}
+					/>
+					<div
+						style={{
+							width: 16,
+							height: 2,
+							backgroundColor: lineColor,
+						}}
+					/>
+				</div>
+			);
+		}
+		if (position.pointerPosition === "top") {
+			return (
+				<div style={getPointerStyles()}>
+					<div
+						style={{
+							width: 6,
+							height: 6,
+							borderRadius: "50%",
+							backgroundColor: lineColor,
+						}}
+					/>
+					<div
+						style={{
+							width: 2,
+							height: 16,
+							backgroundColor: lineColor,
+						}}
+					/>
+				</div>
+			);
+		}
+		return null;
+	};
+
+	// Render step dots
+	const renderStepDots = () => {
+		return (
+			<div className="flex items-center gap-1.5">
+				{Array.from({ length: totalSteps }).map((_, i) => (
+					<div
+						key={`step-dot-${i}`}
+						style={{
+							width: 6,
+							height: 6,
+							borderRadius: "50%",
+							backgroundColor: i === stepIndex ? "#ffffff" : "#52525b",
+							transition: "background-color 0.2s",
+						}}
+					/>
+				))}
+			</div>
+		);
+	};
+
+	return (
+		<div
+			role="dialog"
+			aria-modal="true"
+			aria-labelledby="tour-title"
+			className="fixed z-[99999]"
+			style={{
+				top: position.top,
+				left: position.left,
+				width: 280,
+			}}
+			onClick={(e) => e.stopPropagation()}
+			onKeyDown={(e) => e.stopPropagation()}
+		>
+			{/* Pointer line */}
+			{renderPointer()}
+
+			<div
+				className="relative rounded-lg p-4"
+				style={{
+					backgroundColor: bgColor,
+					color: textColor,
+					boxShadow: "0 25px 50px -12px rgba(0, 0, 0, 0.5)",
+				}}
+			>
+				{/* Content */}
+				<div>
+					<h3 id="tour-title" className="text-sm font-semibold mb-1.5" style={{ color: textColor }}>
+						{step.title}
+					</h3>
+					<p className="text-sm leading-relaxed" style={{ color: mutedTextColor }}>
+						{step.content}
+					</p>
+				</div>
+
+				{/* Footer */}
+				<div className="flex items-center justify-between mt-4">
+					{/* Step dots */}
+					{renderStepDots()}
+
+					{/* Navigation buttons */}
+					<div className="flex items-center gap-3">
+						{!isFirstStep && (
+							<button
+								type="button"
+								onClick={(e) => {
+									e.stopPropagation();
+									onPrev();
+								}}
+								className="text-sm font-medium transition-opacity hover:opacity-80"
+								style={{ color: mutedTextColor }}
+							>
+								Back
+							</button>
+						)}
+						{isFirstStep && (
+							<button
+								type="button"
+								onClick={(e) => {
+									e.stopPropagation();
+									onSkip();
+								}}
+								className="text-sm font-medium transition-opacity hover:opacity-80"
+								style={{ color: mutedTextColor }}
+							>
+								Skip
+							</button>
+						)}
+						<button
+							type="button"
+							onClick={(e) => {
+								e.stopPropagation();
+								onNext();
+							}}
+							className="text-sm font-medium transition-opacity hover:opacity-80"
+							style={{ color: textColor }}
+						>
+							{isLastStep ? "Done" : "Next"}
+						</button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+export function OnboardingTour() {
+	const [isActive, setIsActive] = useState(false);
+	const [stepIndex, setStepIndex] = useState(0);
+	const [targetEl, setTargetEl] = useState<Element | null>(null);
+	const [position, setPosition] = useState<TooltipPosition | null>(null);
+	const [targetRect, setTargetRect] = useState<DOMRect | null>(null);
+	const [mounted, setMounted] = useState(false);
+	const { resolvedTheme } = useTheme();
+	const retryCountRef = useRef(0);
+	const maxRetries = 10;
+
+	const isDarkMode = resolvedTheme === "dark";
+	const currentStep = TOUR_STEPS[stepIndex];
+
+	// Handle mounting for portal
+	useEffect(() => {
+		setMounted(true);
+	}, []);
+
+	// Find and track target element with retry logic
+	const updateTarget = useCallback(() => {
+		if (!currentStep) return;
+
+		const el = document.querySelector(currentStep.target);
+		if (el) {
+			setTargetEl(el);
+			setTargetRect(el.getBoundingClientRect());
+			setPosition(calculatePosition(el, currentStep.placement));
+			retryCountRef.current = 0;
+		} else if (retryCountRef.current < maxRetries) {
+			retryCountRef.current++;
+			setTimeout(() => {
+				const retryEl = document.querySelector(currentStep.target);
+				if (retryEl) {
+					setTargetEl(retryEl);
+					setTargetRect(retryEl.getBoundingClientRect());
+					setPosition(calculatePosition(retryEl, currentStep.placement));
+					retryCountRef.current = 0;
+				}
+			}, 200);
+		}
+	}, [currentStep]);
+
+	// Start tour and find first target
+	useEffect(() => {
+		const timer = setTimeout(() => {
+			const el = document.querySelector(TOUR_STEPS[0].target);
+			if (el) {
+				setIsActive(true);
+				setTargetEl(el);
+				setTargetRect(el.getBoundingClientRect());
+				setPosition(calculatePosition(el, TOUR_STEPS[0].placement));
+			}
+		}, 1000);
+
+		return () => clearTimeout(timer);
+	}, []);
+
+	// Update position on resize/scroll
+	useEffect(() => {
+		if (!isActive || !targetEl) return;
+
+		const handleUpdate = () => {
+			const rect = targetEl.getBoundingClientRect();
+			if (rect.width > 0 && rect.height > 0) {
+				setTargetRect(rect);
+				setPosition(calculatePosition(targetEl, currentStep?.placement || "bottom"));
+			}
+		};
+
+		window.addEventListener("resize", handleUpdate);
+		window.addEventListener("scroll", handleUpdate, true);
+
+		return () => {
+			window.removeEventListener("resize", handleUpdate);
+			window.removeEventListener("scroll", handleUpdate, true);
+		};
+	}, [isActive, targetEl, currentStep?.placement]);
+
+	// Update target when step changes
+	useEffect(() => {
+		if (isActive && currentStep) {
+			const timer = setTimeout(() => {
+				updateTarget();
+			}, 100);
+			return () => clearTimeout(timer);
+		}
+	}, [isActive, updateTarget, currentStep]);
+
+	// Ensure target element is above overlay layers so content is fully visible
+	useEffect(() => {
+		if (!targetEl || !isActive) return;
+
+		const originalZIndex = (targetEl as HTMLElement).style.zIndex;
+		const originalPosition = (targetEl as HTMLElement).style.position;
+
+		// Ensure the element has a position that allows z-index
+		if (getComputedStyle(targetEl).position === "static") {
+			(targetEl as HTMLElement).style.position = "relative";
+		}
+		(targetEl as HTMLElement).style.zIndex = "99999";
+
+		return () => {
+			(targetEl as HTMLElement).style.zIndex = originalZIndex;
+			if (originalPosition) {
+				(targetEl as HTMLElement).style.position = originalPosition;
+			} else if (getComputedStyle(targetEl).position === "relative" && originalPosition === "") {
+				(targetEl as HTMLElement).style.position = "";
+			}
+		};
+	}, [targetEl, isActive]);
+
+	const handleNext = useCallback(() => {
+		if (stepIndex < TOUR_STEPS.length - 1) {
+			retryCountRef.current = 0;
+			setStepIndex(stepIndex + 1);
+		} else {
+			setIsActive(false);
+		}
+	}, [stepIndex]);
+
+	const handlePrev = useCallback(() => {
+		if (stepIndex > 0) {
+			retryCountRef.current = 0;
+			setStepIndex(stepIndex - 1);
+		}
+	}, [stepIndex]);
+
+	const handleSkip = useCallback(() => {
+		setIsActive(false);
+	}, []);
+
+	// Handle overlay click to close
+	const handleOverlayClick = useCallback(() => {
+		setIsActive(false);
+	}, []);
+
+	// Handle escape key
+	useEffect(() => {
+		const handleKeyDown = (e: KeyboardEvent) => {
+			if (e.key === "Escape" && isActive) {
+				setIsActive(false);
+			}
+		};
+		window.addEventListener("keydown", handleKeyDown);
+		return () => window.removeEventListener("keydown", handleKeyDown);
+	}, [isActive]);
+
+	// Don't render if not active or not mounted
+	if (!mounted || !isActive || !targetEl || !position || !currentStep || !targetRect) {
+		return null;
+	}
+
+	return createPortal(
+		<div className="fixed inset-0 z-[99995]">
+			{/* Clickable backdrop to close */}
+			<button
+				type="button"
+				className="fixed inset-0 w-full h-full bg-transparent border-0 cursor-default"
+				onClick={handleOverlayClick}
+				aria-label="Close tour"
+			/>
+			<Spotlight targetEl={targetEl} isDarkMode={isDarkMode} stepIndex={stepIndex} />
+			<TourTooltip
+				step={currentStep}
+				stepIndex={stepIndex}
+				totalSteps={TOUR_STEPS.length}
+				position={position}
+				targetRect={targetRect}
+				onNext={handleNext}
+				onPrev={handlePrev}
+				onSkip={handleSkip}
+				isDarkMode={isDarkMode}
+			/>
+		</div>,
+		document.body
+	);
+}

surfsense_web/components/sidebar/nav-main.tsx

@@ -131,7 +131,11 @@ export function NavMain({ items }: NavMainProps) {
 												isActive={isActive}
 												aria-label={`${translatedTitle} with submenu`}
 											>
-												<button type="button" className="flex items-center gap-2 w-full text-left">
+												<button
+													type="button"
+													className="flex items-center gap-2 w-full text-left"
+													{...(item.title === "Sources" ? { "data-joyride": "sources-menu" } : {})}
+												>
 													<item.icon />
 													<span>{translatedTitle}</span>
 												</button>
@@ -152,10 +156,18 @@ export function NavMain({ items }: NavMainProps) {
 											<SidebarMenuSub>
 												{item.items?.map((subItem, subIndex) => {
 													const translatedSubTitle = translateTitle(subItem.title);
+													const isDocumentsLink =
+														subItem.title === "Manage Documents" ||
+														translatedSubTitle.toLowerCase().includes("documents");
 													return (
 														<SidebarMenuSubItem key={`${subItem.title}-${subIndex}`}>
 															<SidebarMenuSubButton asChild aria-label={translatedSubTitle}>
-																<a href={subItem.url}>
+																<a
+																	href={subItem.url}
+																	{...(isDocumentsLink
+																		? { "data-joyride": "documents-sidebar" }
+																		: {})}
+																>
 																	<span>{translatedSubTitle}</span>
 																</a>
 															</SidebarMenuSubButton>
@@ -173,7 +185,13 @@ export function NavMain({ items }: NavMainProps) {
 										isActive={isActive}
 										aria-label={translatedTitle}
 									>
-										<a href={item.url}>
+										<a
+											href={item.url}
+											{...(item.title === "Documents" ||
+											translatedTitle.toLowerCase() === "documents"
+												? { "data-joyride": "documents-sidebar" }
+												: {})}
+										>
 											<item.icon />
 											<span>{translatedTitle}</span>
 										</a>