@useatlas/create 0.0.5 → 0.0.7

package/templates/docker/src/ui/components/tour/nav-bar.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import {
+  MessageSquare,
+  BookOpen,
+  Settings,
+  Database,
+  CircleHelp,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+import { useTourContext } from "./guided-tour";
+
+interface NavBarProps {
+  /** Whether the current user has admin role. */
+  isAdmin: boolean;
+}
+
+const navItems = [
+  { href: "/", label: "Chat", icon: MessageSquare, tourId: "chat" },
+  { href: "/notebook", label: "Notebook", icon: BookOpen, tourId: "notebook" },
+] as const;
+
+const adminItems = [
+  { href: "/admin", label: "Admin", icon: Settings, tourId: "admin" },
+  { href: "/admin/semantic", label: "Semantic", icon: Database, tourId: "semantic" },
+] as const;
+
+/**
+ * Top navigation bar with data-tour attributes for the guided tour.
+ *
+ * Renders navigation links for Chat, Notebook, Admin (admin only),
+ * and Semantic Layer. Includes a help menu with a "Replay tour" option.
+ */
+export function NavBar({ isAdmin }: NavBarProps) {
+  const pathname = usePathname();
+  const tourContext = useTourContext();
+
+  const allItems = isAdmin
+    ? [...navItems, ...adminItems]
+    : [...navItems, { href: "/admin/semantic" as const, label: "Semantic" as const, icon: Database, tourId: "semantic" as const }];
+
+  return (
+    <nav className="flex h-10 shrink-0 items-center justify-between border-b border-zinc-200 bg-zinc-50 px-4 dark:border-zinc-800 dark:bg-zinc-950">
+      <div className="flex items-center gap-1">
+        {allItems.map((item) => {
+          const isActive = item.href === "/"
+            ? pathname === "/"
+            : pathname.startsWith(item.href);
+          const Icon = item.icon;
+          return (
+            <Link
+              key={item.href}
+              href={item.href}
+              data-tour={item.tourId}
+              className={cn(
+                "inline-flex items-center gap-1.5 rounded-md px-2.5 py-1.5 text-xs font-medium transition-colors",
+                isActive
+                  ? "bg-zinc-200 text-zinc-900 dark:bg-zinc-800 dark:text-zinc-100"
+                  : "text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 dark:text-zinc-400 dark:hover:bg-zinc-800 dark:hover:text-zinc-300",
+              )}
+            >
+              <Icon className="size-3.5" />
+              <span className="hidden sm:inline">{item.label}</span>
+            </Link>
+          );
+        })}
+      </div>
+
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            className="text-zinc-400 hover:text-zinc-600 dark:text-zinc-500 dark:hover:text-zinc-300"
+            aria-label="Help menu"
+          >
+            <CircleHelp className="size-4" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem
+            onClick={() => tourContext?.startTour()}
+            disabled={!tourContext}
+          >
+            Replay guided tour
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </nav>
+  );
+}

package/templates/docker/src/ui/components/tour/tour-overlay.tsx

@@ -0,0 +1,298 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { X, ChevronLeft, ChevronRight } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+import type { TourStep } from "./types";
+
+interface TourOverlayProps {
+  /** Whether the tour is currently visible. */
+  active: boolean;
+  /** The current step to display. */
+  step: TourStep;
+  /** Current step index (0-based). */
+  stepIndex: number;
+  /** Total number of steps. */
+  totalSteps: number;
+  /** Called when the user clicks "Next" or "Done". */
+  onNext: () => void;
+  /** Called when the user clicks "Back". */
+  onPrev: () => void;
+  /** Called when the user clicks "Skip" or the X button. */
+  onSkip: () => void;
+}
+
+interface TargetRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Full-screen backdrop overlay with a highlighted cutout around the target
+ * element and a floating tooltip card.
+ */
+export function TourOverlay({
+  active,
+  step,
+  stepIndex,
+  totalSteps,
+  onNext,
+  onPrev,
+  onSkip,
+}: TourOverlayProps) {
+  const [targetRect, setTargetRect] = useState<TargetRect | null>(null);
+  const [mounted, setMounted] = useState(false);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+
+  // Mount portal after hydration
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Find and track the target element
+  useEffect(() => {
+    if (!active || !step.targetSelector) {
+      setTargetRect(null);
+      return;
+    }
+
+    function updateRect() {
+      const el = document.querySelector(step.targetSelector!);
+      if (el) {
+        const rect = el.getBoundingClientRect();
+        setTargetRect({
+          top: rect.top,
+          left: rect.left,
+          width: rect.width,
+          height: rect.height,
+        });
+      } else {
+        setTargetRect(null);
+      }
+    }
+
+    updateRect();
+
+    // Re-measure on scroll/resize
+    window.addEventListener("resize", updateRect);
+    window.addEventListener("scroll", updateRect, true);
+
+    return () => {
+      window.removeEventListener("resize", updateRect);
+      window.removeEventListener("scroll", updateRect, true);
+    };
+  }, [active, step.targetSelector]);
+
+  // Handle Escape key
+  useEffect(() => {
+    if (!active) return;
+    function handleKeyDown(e: KeyboardEvent) {
+      if (e.key === "Escape") onSkip();
+      if (e.key === "ArrowRight") onNext();
+      if (e.key === "ArrowLeft") onPrev();
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [active, onSkip, onNext, onPrev]);
+
+  if (!active || !mounted) return null;
+
+  const isFirst = stepIndex === 0;
+  const isLast = stepIndex === totalSteps - 1;
+
+  // Calculate tooltip position
+  const tooltipStyle = calculateTooltipPosition(targetRect, step.side);
+
+  const overlay = (
+    <div
+      className="fixed inset-0 z-[9999]"
+      role="dialog"
+      aria-modal="true"
+      aria-label={`Guided tour: step ${stepIndex + 1} of ${totalSteps}`}
+    >
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0 bg-black/50 transition-opacity duration-200"
+        onClick={onSkip}
+        aria-hidden="true"
+      />
+
+      {/* Highlight cutout — renders a transparent box over the target */}
+      {targetRect && (
+        <div
+          className="absolute rounded-lg ring-4 ring-primary/50 transition-all duration-300 ease-in-out"
+          style={{
+            top: targetRect.top - 4,
+            left: targetRect.left - 4,
+            width: targetRect.width + 8,
+            height: targetRect.height + 8,
+            boxShadow: "0 0 0 9999px rgba(0, 0, 0, 0.5)",
+            backgroundColor: "transparent",
+            zIndex: 1,
+            pointerEvents: "none",
+          }}
+          aria-hidden="true"
+        />
+      )}
+
+      {/* Tooltip card */}
+      <div
+        ref={tooltipRef}
+        className={cn(
+          "absolute z-10 w-[calc(100vw-2rem)] max-w-sm rounded-lg border border-zinc-200 bg-white p-4 shadow-xl transition-all duration-300 ease-in-out dark:border-zinc-700 dark:bg-zinc-900",
+          // On mobile, center the card
+          !targetRect && "left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2",
+        )}
+        style={targetRect ? tooltipStyle : undefined}
+        role="tooltip"
+      >
+        {/* Close button */}
+        <button
+          onClick={onSkip}
+          className="absolute right-2 top-2 rounded-md p-1 text-zinc-400 hover:text-zinc-600 dark:text-zinc-500 dark:hover:text-zinc-300"
+          aria-label="Close tour"
+        >
+          <X className="size-4" />
+        </button>
+
+        {/* Step content */}
+        <div className="pr-6">
+          <h3 className="text-sm font-semibold text-zinc-900 dark:text-zinc-100">
+            {step.title}
+          </h3>
+          <p className="mt-1 text-sm text-zinc-500 dark:text-zinc-400">
+            {step.description}
+          </p>
+        </div>
+
+        {/* Footer: step indicator + navigation */}
+        <div className="mt-4 flex items-center justify-between">
+          <span className="text-xs text-zinc-400 dark:text-zinc-500">
+            {stepIndex + 1} of {totalSteps}
+          </span>
+          <div className="flex items-center gap-2">
+            {stepIndex > 0 && (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={onPrev}
+                className="text-xs"
+              >
+                <ChevronLeft className="size-3" />
+                Back
+              </Button>
+            )}
+            {!isFirst && !isLast && (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={onSkip}
+                className="text-xs text-zinc-400 dark:text-zinc-500"
+              >
+                Skip
+              </Button>
+            )}
+            {isFirst && (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={onSkip}
+                className="text-xs text-zinc-400 dark:text-zinc-500"
+              >
+                Skip tour
+              </Button>
+            )}
+            <Button size="sm" onClick={onNext} className="text-xs">
+              {isLast ? "Done" : "Next"}
+              {!isLast && <ChevronRight className="size-3" />}
+            </Button>
+          </div>
+        </div>
+
+        {/* Step dots */}
+        <div className="mt-3 flex justify-center gap-1.5">
+          {Array.from({ length: totalSteps }).map((_, i) => (
+            <div
+              key={i}
+              className={cn(
+                "size-1.5 rounded-full transition-colors",
+                i === stepIndex
+                  ? "bg-primary"
+                  : "bg-zinc-300 dark:bg-zinc-600",
+              )}
+              aria-hidden="true"
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  return createPortal(overlay, document.body);
+}
+
+/**
+ * Calculate tooltip position based on the target element rect and preferred side.
+ * Falls back to centered positioning when the target is too close to an edge.
+ */
+function calculateTooltipPosition(
+  rect: TargetRect | null,
+  side: TourStep["side"],
+): React.CSSProperties {
+  if (!rect) {
+    return {
+      left: "50%",
+      top: "50%",
+      transform: "translate(-50%, -50%)",
+    };
+  }
+
+  const GAP = 12;
+  const TOOLTIP_WIDTH = 384; // max-w-sm
+  const viewportWidth = typeof window !== "undefined" ? window.innerWidth : 1024;
+  const viewportHeight = typeof window !== "undefined" ? window.innerHeight : 768;
+
+  // Center horizontally relative to target by default
+  let left = rect.left + rect.width / 2 - TOOLTIP_WIDTH / 2;
+  let top: number;
+
+  switch (side) {
+    case "bottom":
+      top = rect.top + rect.height + GAP;
+      break;
+    case "top":
+      top = rect.top - GAP;
+      // Will be adjusted with transform
+      break;
+    case "left":
+      left = rect.left - TOOLTIP_WIDTH - GAP;
+      top = rect.top + rect.height / 2;
+      break;
+    case "right":
+      left = rect.left + rect.width + GAP;
+      top = rect.top + rect.height / 2;
+      break;
+    default:
+      top = rect.top + rect.height + GAP;
+  }
+
+  // Clamp to viewport bounds with padding
+  const PADDING = 16;
+  left = Math.max(PADDING, Math.min(left, viewportWidth - TOOLTIP_WIDTH - PADDING));
+  top = Math.max(PADDING, Math.min(top, viewportHeight - 200));
+
+  const style: React.CSSProperties = { left, top };
+
+  if (side === "top") {
+    style.transform = "translateY(-100%)";
+  }
+  if (side === "left" || side === "right") {
+    style.transform = "translateY(-50%)";
+  }
+
+  return style;
+}

package/templates/docker/src/ui/components/tour/tour-steps.ts

@@ -0,0 +1,43 @@
+import type { TourStep } from "./types";
+
+/**
+ * Default tour steps for the guided onboarding walkthrough.
+ *
+ * Targets are identified by `data-tour` attributes placed on key UI elements.
+ * Steps with `adminOnly: true` are filtered out for non-admin users.
+ */
+export const TOUR_STEPS: TourStep[] = [
+  {
+    id: "chat",
+    title: "Chat with your data",
+    description:
+      "Ask questions about your data in natural language. Atlas translates your questions into SQL and returns results instantly.",
+    targetSelector: "[data-tour='chat']",
+    side: "bottom",
+  },
+  {
+    id: "notebook",
+    title: "Notebook",
+    description:
+      "Build multi-step analyses with cells you can re-run, reorder, and export. Great for deeper exploration.",
+    targetSelector: "[data-tour='notebook']",
+    side: "bottom",
+  },
+  {
+    id: "admin",
+    title: "Admin console",
+    description:
+      "Manage connections, users, roles, and monitor usage. Configure your workspace settings here.",
+    targetSelector: "[data-tour='admin']",
+    side: "bottom",
+    adminOnly: true,
+  },
+  {
+    id: "semantic",
+    title: "Semantic layer",
+    description:
+      "Your data model lives here \u2014 entities, metrics, and glossary terms. It helps Atlas understand your data accurately.",
+    targetSelector: "[data-tour='semantic']",
+    side: "bottom",
+  },
+];

package/templates/docker/src/ui/components/tour/types.ts

@@ -0,0 +1,21 @@
+/** Tour step definition for the guided onboarding tour. */
+export interface TourStep {
+  /** Unique identifier for this step. */
+  id: string;
+  /** Step title shown in the tooltip. */
+  title: string;
+  /** Step description shown in the tooltip. */
+  description: string;
+  /** CSS selector for the element to highlight. Null for centered modal steps. */
+  targetSelector: string | null;
+  /** Preferred side for the popover tooltip. */
+  side: "top" | "bottom" | "left" | "right";
+  /** Whether this step requires admin role to be shown. */
+  adminOnly?: boolean;
+}
+
+/** Tour completion status from the API. */
+export interface TourStatus {
+  tourCompleted: boolean;
+  tourCompletedAt: string | null;
+}

package/templates/docker/src/ui/components/tour/use-tour.ts

@@ -0,0 +1,193 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import type { TourStep, TourStatus } from "./types";
+import { TOUR_STEPS } from "./tour-steps";
+
+/** Local storage key used as fallback when the API is unavailable. */
+const TOUR_STORAGE_KEY = "atlas-tour-completed";
+
+interface UseTourOptions {
+  /** Atlas API base URL. */
+  apiUrl: string;
+  /** Whether the API is cross-origin (determines credentials mode). */
+  isCrossOrigin: boolean;
+  /** Whether the current user has admin role. */
+  isAdmin: boolean;
+  /** Whether we should attempt server-side tour tracking. */
+  serverTrackingEnabled: boolean;
+}
+
+interface UseTourResult {
+  /** Whether the tour is currently active/visible. */
+  isActive: boolean;
+  /** The current step index (0-based). */
+  currentStep: number;
+  /** Filtered steps for the current user. */
+  steps: TourStep[];
+  /** Total number of steps. */
+  totalSteps: number;
+  /** Whether we're still loading tour status. */
+  loading: boolean;
+  /** Move to the next step or finish the tour. */
+  next: () => void;
+  /** Go back to the previous step. */
+  prev: () => void;
+  /** Skip/dismiss the entire tour. */
+  skip: () => void;
+  /** Start or restart the tour. */
+  start: () => void;
+}
+
+export function useTour({
+  apiUrl,
+  isCrossOrigin,
+  isAdmin,
+  serverTrackingEnabled,
+}: UseTourOptions): UseTourResult {
+  const [isActive, setIsActive] = useState(false);
+  const [currentStep, setCurrentStep] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [statusChecked, setStatusChecked] = useState(false);
+
+  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
+
+  // Filter steps based on user role
+  const steps = isAdmin ? TOUR_STEPS : TOUR_STEPS.filter((s) => !s.adminOnly);
+
+  // Check tour completion status on mount
+  useEffect(() => {
+    if (statusChecked) return;
+
+    async function checkStatus() {
+      // Check local storage first for fast path
+      try {
+        if (localStorage.getItem(TOUR_STORAGE_KEY) === "true") {
+          setLoading(false);
+          setStatusChecked(true);
+          return;
+        }
+      } catch {
+        // intentionally ignored: localStorage unavailable — continue to API check
+      }
+
+      if (serverTrackingEnabled) {
+        try {
+          const res = await fetch(`${apiUrl}/api/v1/onboarding/tour-status`, {
+            credentials,
+          });
+          if (res.ok) {
+            const data: TourStatus = await res.json();
+            if (data.tourCompleted) {
+              // Sync to local storage
+              try {
+                localStorage.setItem(TOUR_STORAGE_KEY, "true");
+              } catch {
+                /// intentionally ignored: localStorage may be unavailable in some environments
+              }
+              setLoading(false);
+              setStatusChecked(true);
+              return;
+            }
+          }
+        } catch (err) {
+          console.warn(
+            "Failed to check tour status:",
+            err instanceof Error ? err.message : String(err),
+          );
+        }
+      }
+
+      // Tour not completed — auto-start
+      setIsActive(true);
+      setCurrentStep(0);
+      setLoading(false);
+      setStatusChecked(true);
+    }
+
+    checkStatus();
+  }, [apiUrl, credentials, serverTrackingEnabled, statusChecked]);
+
+  async function markComplete() {
+    // Save to local storage immediately
+    try {
+      localStorage.setItem(TOUR_STORAGE_KEY, "true");
+    } catch {
+      /// intentionally ignored: localStorage may be unavailable in some environments
+    }
+
+    // Save to server
+    if (serverTrackingEnabled) {
+      try {
+        await fetch(`${apiUrl}/api/v1/onboarding/tour-complete`, {
+          method: "POST",
+          credentials,
+        });
+      } catch (err) {
+        console.warn(
+          "Failed to save tour completion to server:",
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+  }
+
+  function next() {
+    if (currentStep < steps.length - 1) {
+      setCurrentStep((s) => s + 1);
+    } else {
+      // Last step — complete tour
+      setIsActive(false);
+      markComplete();
+    }
+  }
+
+  function prev() {
+    if (currentStep > 0) {
+      setCurrentStep((s) => s - 1);
+    }
+  }
+
+  function skip() {
+    setIsActive(false);
+    markComplete();
+  }
+
+  function start() {
+    // Reset local storage for replay
+    try {
+      localStorage.removeItem(TOUR_STORAGE_KEY);
+    } catch {
+      /// intentionally ignored: localStorage may be unavailable in some environments
+    }
+
+    // Reset server-side status
+    if (serverTrackingEnabled) {
+      fetch(`${apiUrl}/api/v1/onboarding/tour-reset`, {
+        method: "POST",
+        credentials,
+      }).catch((err) => {
+        console.warn(
+          "Failed to reset tour on server:",
+          err instanceof Error ? err.message : String(err),
+        );
+      });
+    }
+
+    setCurrentStep(0);
+    setStatusChecked(true);
+    setIsActive(true);
+  }
+
+  return {
+    isActive,
+    currentStep,
+    steps,
+    totalSteps: steps.length,
+    loading,
+    next,
+    prev,
+    skip,
+    start,
+  };
+}

package/templates/docker/src/ui/context-reexport.ts

@@ -0,0 +1,3 @@
+/** Re-export from @useatlas/react for backwards compatibility. */
+export { AtlasUIProvider, useAtlasConfig } from "@useatlas/react";
+export type { AtlasUIConfig, AtlasAuthClient } from "@useatlas/react";

package/templates/docker/src/ui/hooks/theme-init-script.ts

@@ -0,0 +1,17 @@
+/**
+ * Blocking inline script for layout.tsx — prevents dark-mode flash on load.
+ *
+ * This file intentionally has NO "use client" directive so it can be imported
+ * by server components (layout.tsx). The storage key must stay in sync with
+ * use-dark-mode.ts.
+ */
+
+export const THEME_STORAGE_KEY = "atlas-theme";
+
+/**
+ * Returns the inline script string for the blocking `<script>` in layout.tsx.
+ * Reads atlas-theme from localStorage and sets the `dark` class before first paint.
+ */
+export function buildThemeInitScript(): string {
+  return `try{var t=localStorage.getItem("${THEME_STORAGE_KEY}");var d=t==="dark"||(t!=="light"&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(d)document.documentElement.classList.add("dark")}catch(e){}`;
+}