@useatlas/create 0.0.5 → 0.0.7

package/templates/docker/src/ui/components/schema-explorer/schema-explorer.tsx

@@ -0,0 +1,522 @@
+"use client";
+
+import { useEffect, useState, useRef } from "react";
+import { useAtlasConfig } from "../../context";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet";
+import { Input } from "@/components/ui/input";
+import { Badge } from "@/components/ui/badge";
+import { ScrollArea } from "@/components/ui/scroll-area";
+import { Separator } from "@/components/ui/separator";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
+import {
+  Search,
+  ArrowLeft,
+  ArrowRight,
+  Loader2,
+  TableProperties,
+  Eye,
+  Columns3,
+  Link2,
+  Sparkles,
+} from "lucide-react";
+import type {
+  SemanticEntitySummary,
+  SemanticEntityDetail,
+  Dimension,
+  Join,
+  Measure,
+  QueryPattern,
+} from "../../lib/types";
+import { normalizeList } from "../../lib/helpers";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type TypeFilter = "all" | "table" | "view";
+
+/** Parse a server error response, extracting the message field if present. */
+async function parseErrorResponse(r: Response): Promise<string> {
+  try {
+    const body = await r.json();
+    if (typeof body?.message === "string") return body.message;
+  } catch { /* intentionally ignored: response may not be JSON */ }
+  return `HTTP ${r.status}`;
+}
+
+// ---------------------------------------------------------------------------
+// Entity list
+// ---------------------------------------------------------------------------
+
+function EntityList({
+  entities,
+  search,
+  onSearchChange,
+  typeFilter,
+  onTypeFilterChange,
+  onSelect,
+}: {
+  entities: SemanticEntitySummary[];
+  search: string;
+  onSearchChange: (v: string) => void;
+  typeFilter: TypeFilter;
+  onTypeFilterChange: (v: TypeFilter) => void;
+  onSelect: (name: string) => void;
+}) {
+  const filtered = entities.filter((e) => {
+    const matchesSearch =
+      !search ||
+      e.table.toLowerCase().includes(search.toLowerCase()) ||
+      e.description.toLowerCase().includes(search.toLowerCase());
+    const matchesType =
+      typeFilter === "all" ||
+      (typeFilter === "view" ? e.type === "view" : e.type !== "view");
+    return matchesSearch && matchesType;
+  });
+
+  const tableCount = entities.filter((e) => e.type !== "view").length;
+  const viewCount = entities.filter((e) => e.type === "view").length;
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="space-y-3 px-4 pb-3">
+        <div className="relative">
+          <Search className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-zinc-400" />
+          <Input
+            value={search}
+            onChange={(e) => onSearchChange(e.target.value)}
+            placeholder="Search tables..."
+            className="h-8 pl-8 text-sm"
+          />
+        </div>
+        {viewCount > 0 && (
+          <ToggleGroup
+            type="single"
+            size="sm"
+            value={typeFilter}
+            onValueChange={(v) => { if (v) onTypeFilterChange(v as TypeFilter); }}
+            className="justify-start"
+          >
+            <ToggleGroupItem value="all" className="h-6 px-2 text-xs">
+              All ({entities.length})
+            </ToggleGroupItem>
+            <ToggleGroupItem value="table" className="h-6 px-2 text-xs">
+              Tables ({tableCount})
+            </ToggleGroupItem>
+            <ToggleGroupItem value="view" className="h-6 px-2 text-xs">
+              Views ({viewCount})
+            </ToggleGroupItem>
+          </ToggleGroup>
+        )}
+      </div>
+
+      <Separator />
+
+      <div className="flex-1 overflow-y-auto overflow-x-hidden p-2">
+          {filtered.length === 0 ? (
+            <p className="px-2 py-8 text-center text-xs text-zinc-400 dark:text-zinc-500">
+              {search ? "No matching entities" : "No entities found"}
+            </p>
+          ) : (
+            filtered.map((entity) => (
+              <button
+                key={entity.table}
+                onClick={() => onSelect(entity.table)}
+                className="flex w-full min-w-0 items-start gap-2 overflow-hidden rounded-md px-2 py-2 text-left transition-colors hover:bg-zinc-100 dark:hover:bg-zinc-800"
+              >
+                {entity.type === "view" ? (
+                  <Eye className="mt-0.5 size-3.5 shrink-0 text-zinc-400" />
+                ) : (
+                  <TableProperties className="mt-0.5 size-3.5 shrink-0 text-zinc-400" />
+                )}
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-1.5">
+                    <span className="truncate text-sm font-medium text-zinc-800 dark:text-zinc-200">
+                      {entity.table}
+                    </span>
+                    {entity.type === "view" && (
+                      <Badge variant="outline" className="shrink-0 text-[10px] px-1 py-0">
+                        view
+                      </Badge>
+                    )}
+                  </div>
+                  {entity.description && (
+                    <p className="mt-0.5 truncate text-xs text-zinc-500 dark:text-zinc-400">
+                      {entity.description}
+                    </p>
+                  )}
+                  <div className="mt-1 flex gap-2 text-[10px] text-zinc-400 dark:text-zinc-500">
+                    <span>{entity.columnCount} cols</span>
+                    {entity.joinCount > 0 && <span>{entity.joinCount} joins</span>}
+                  </div>
+                </div>
+                <ArrowRight className="mt-1 size-3 shrink-0 text-zinc-300 dark:text-zinc-600" />
+              </button>
+            ))
+          )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Entity detail
+// ---------------------------------------------------------------------------
+
+function EntityDetailView({
+  entity,
+  onBack,
+  onNavigateEntity,
+  onInsertQuery,
+}: {
+  entity: SemanticEntityDetail;
+  onBack: () => void;
+  onNavigateEntity: (name: string) => void;
+  onInsertQuery: (description: string) => void;
+}) {
+  const dimensions = normalizeList(entity.dimensions, "name") as Dimension[];
+  const joins = normalizeList(entity.joins, "to") as Join[];
+  const measures = normalizeList(entity.measures, "name") as Measure[];
+  const patterns = normalizeList(entity.query_patterns, "name") as QueryPattern[];
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex items-center gap-2 px-4 pb-3">
+        <Button variant="ghost" size="icon" className="size-7" onClick={onBack}>
+          <ArrowLeft className="size-3.5" />
+        </Button>
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-1.5">
+            <h3 className="truncate text-sm font-semibold">{entity.table}</h3>
+            {entity.type === "view" && (
+              <Badge variant="outline" className="text-[10px]">view</Badge>
+            )}
+          </div>
+        </div>
+      </div>
+
+      <Separator />
+
+      <ScrollArea className="flex-1">
+        <div className="space-y-5 p-4">
+          {entity.description && (
+            <p className="text-xs text-zinc-500 dark:text-zinc-400">{entity.description}</p>
+          )}
+
+          {/* Columns */}
+          <section>
+            <h4 className="mb-2 flex items-center gap-1.5 text-xs font-semibold text-zinc-700 dark:text-zinc-300">
+              <Columns3 className="size-3" />
+              Columns ({dimensions.length})
+            </h4>
+            <div className="rounded-md border">
+              <Table className="table-fixed">
+                <TableHeader>
+                  <TableRow>
+                    <TableHead className="h-7 w-[30%] text-[10px]">Name</TableHead>
+                    <TableHead className="h-7 w-[15%] text-[10px]">Type</TableHead>
+                    <TableHead className="h-7 w-[35%] text-[10px] hidden sm:table-cell">Description</TableHead>
+                    <TableHead className="h-7 w-[20%] text-[10px] hidden sm:table-cell">Samples</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {dimensions.map((dim) => (
+                    <TableRow key={dim.name}>
+                      <TableCell className="py-1.5 font-mono text-[11px]">
+                        <span className="flex items-center gap-1">
+                          <span className="truncate">{dim.name}</span>
+                          {dim.primary_key && (
+                            <Badge className="shrink-0 bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400 text-[9px] px-1 py-0">
+                              PK
+                            </Badge>
+                          )}
+                          {dim.foreign_key && (
+                            <Badge className="shrink-0 bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400 text-[9px] px-1 py-0">
+                              FK
+                            </Badge>
+                          )}
+                        </span>
+                      </TableCell>
+                      <TableCell className="py-1.5">
+                        <Badge variant="secondary" className="font-mono text-[9px]">
+                          {dim.type}
+                        </Badge>
+                      </TableCell>
+                      <TableCell className="hidden py-1.5 text-[11px] text-zinc-500 sm:table-cell">
+                        <span className="line-clamp-2">{dim.description || "—"}</span>
+                      </TableCell>
+                      <TableCell className="hidden py-1.5 text-[11px] text-zinc-400 sm:table-cell">
+                        <span className="line-clamp-1">
+                          {dim.sample_values?.length
+                            ? dim.sample_values.slice(0, 3).join(", ")
+                            : "—"}
+                        </span>
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </div>
+          </section>
+
+          {/* Joins */}
+          {joins.length > 0 && (
+            <section>
+              <h4 className="mb-2 flex items-center gap-1.5 text-xs font-semibold text-zinc-700 dark:text-zinc-300">
+                <Link2 className="size-3" />
+                Relationships ({joins.length})
+              </h4>
+              <div className="space-y-1.5">
+                {joins.map((join, i) => (
+                  <Card key={i} className="shadow-none">
+                    <CardContent className="px-3 py-2">
+                      <div className="flex items-center gap-2">
+                        <Badge variant="outline" className="shrink-0 text-[9px]">
+                          {join.relationship || "many_to_one"}
+                        </Badge>
+                        <button
+                          onClick={() => onNavigateEntity(join.to)}
+                          className="text-xs font-medium text-blue-600 hover:underline dark:text-blue-400"
+                        >
+                          {join.to}
+                        </button>
+                      </div>
+                      {join.description && (
+                        <p className="mt-1 text-[11px] text-zinc-500">{join.description}</p>
+                      )}
+                    </CardContent>
+                  </Card>
+                ))}
+              </div>
+            </section>
+          )}
+
+          {/* Measures */}
+          {measures.length > 0 && (
+            <section>
+              <h4 className="mb-2 text-xs font-semibold text-zinc-700 dark:text-zinc-300">
+                Measures ({measures.length})
+              </h4>
+              <div className="space-y-1">
+                {measures.map((m) => (
+                  <div key={m.name} className="flex items-center gap-2 rounded px-2 py-1 text-xs">
+                    <span className="font-medium text-zinc-700 dark:text-zinc-300">{m.name}</span>
+                    <code className="rounded bg-zinc-100 px-1.5 py-0.5 text-[10px] text-zinc-500 dark:bg-zinc-800">
+                      {m.sql}
+                    </code>
+                  </div>
+                ))}
+              </div>
+            </section>
+          )}
+
+          {/* Query patterns */}
+          {patterns.length > 0 && (
+            <section>
+              <h4 className="mb-2 flex items-center gap-1.5 text-xs font-semibold text-zinc-700 dark:text-zinc-300">
+                <Sparkles className="size-3" />
+                Query Patterns
+              </h4>
+              <div className="space-y-1.5">
+                {patterns.map((p, i) => (
+                  <button
+                    key={`${p.name}-${i}`}
+                    onClick={() => onInsertQuery(p.description)}
+                    className="w-full rounded-md border border-zinc-200 bg-zinc-50 px-3 py-2 text-left transition-colors hover:border-zinc-400 hover:bg-zinc-100 dark:border-zinc-700 dark:bg-zinc-900 dark:hover:border-zinc-500 dark:hover:bg-zinc-800"
+                  >
+                    <p className="text-xs font-medium text-zinc-700 dark:text-zinc-300">{p.name}</p>
+                    <p className="mt-0.5 text-[11px] text-zinc-500 dark:text-zinc-400">{p.description}</p>
+                  </button>
+                ))}
+              </div>
+            </section>
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main schema explorer panel
+// ---------------------------------------------------------------------------
+
+export function SchemaExplorer({
+  open,
+  onOpenChange,
+  onInsertQuery,
+  getHeaders,
+  getCredentials,
+}: {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onInsertQuery: (text: string) => void;
+  getHeaders: () => Record<string, string>;
+  getCredentials: () => RequestCredentials;
+}) {
+  const { apiUrl } = useAtlasConfig();
+  const [entities, setEntities] = useState<SemanticEntitySummary[]>([]);
+  const [selectedEntity, setSelectedEntity] = useState<SemanticEntityDetail | null>(null);
+  const [selectedName, setSelectedName] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [detailError, setDetailError] = useState<string | null>(null);
+  const [search, setSearch] = useState("");
+  const [typeFilter, setTypeFilter] = useState<TypeFilter>("all");
+  const abortRef = useRef<AbortController | null>(null);
+
+  // Fetch entity list when the sheet opens (or when API config changes)
+  useEffect(() => {
+    if (!open) return;
+
+    // Reset to list view on every open — prevents stale detail view on reopen
+    setSelectedName(null);
+    setSelectedEntity(null);
+    setDetailError(null);
+    abortRef.current?.abort();
+
+    setLoading(true);
+    setError(null);
+
+    const controller = new AbortController();
+    fetch(`${apiUrl}/api/v1/semantic/entities`, {
+      headers: getHeaders(),
+      credentials: getCredentials(),
+      signal: controller.signal,
+    })
+      .then(async (r) => {
+        if (!r.ok) throw new Error(await parseErrorResponse(r));
+        return r.json();
+      })
+      .then((data) => {
+        const list = Array.isArray(data?.entities) ? data.entities : [];
+        setEntities(list);
+      })
+      .catch((err) => {
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        console.warn("Schema explorer: failed to fetch entities:", err);
+        setError(err instanceof Error ? err.message : "Failed to load schema");
+      })
+      .finally(() => setLoading(false));
+
+    return () => controller.abort();
+  }, [open, apiUrl, getHeaders, getCredentials]);
+
+  function handleSelectEntity(name: string) {
+    // Cancel any in-flight detail request
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setSelectedName(name);
+    setSelectedEntity(null);
+    setDetailError(null);
+
+    fetch(`${apiUrl}/api/v1/semantic/entities/${encodeURIComponent(name)}`, {
+      headers: getHeaders(),
+      credentials: getCredentials(),
+      signal: controller.signal,
+    })
+      .then(async (r) => {
+        if (!r.ok) throw new Error(await parseErrorResponse(r));
+        return r.json();
+      })
+      .then((data) => {
+        setSelectedEntity(data?.entity ?? data);
+      })
+      .catch((err) => {
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        console.warn("Schema explorer: failed to load entity:", err);
+        setDetailError(err instanceof Error ? err.message : "Failed to load entity");
+      });
+  }
+
+  function handleBack() {
+    abortRef.current?.abort();
+    setSelectedName(null);
+    setSelectedEntity(null);
+    setDetailError(null);
+  }
+
+  function handleInsertQuery(description: string) {
+    onInsertQuery(description);
+    onOpenChange(false);
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent side="right" className="flex w-full flex-col p-0 sm:max-w-xl">
+        <SheetHeader className="px-4 pt-4">
+          <SheetTitle className="flex items-center gap-2 text-base">
+            <TableProperties className="size-4" />
+            Schema Explorer
+          </SheetTitle>
+          <SheetDescription className="sr-only">
+            Browse tables, columns, joins, and query patterns from the semantic layer
+          </SheetDescription>
+        </SheetHeader>
+
+        <Separator className="mt-3" />
+
+        <div className="flex-1 overflow-hidden pt-3">
+          {loading ? (
+            <div className="flex h-full items-center justify-center gap-2">
+              <Loader2 className="size-4 animate-spin text-zinc-400" />
+              <p className="text-xs text-zinc-400">Loading schema...</p>
+            </div>
+          ) : error ? (
+            <div className="flex h-full items-center justify-center px-4">
+              <p className="text-center text-xs text-red-500">{error}</p>
+            </div>
+          ) : selectedName ? (
+            detailError ? (
+              <div className="flex h-full flex-col items-center justify-center gap-2 px-4">
+                <p className="text-center text-xs text-red-500">{detailError}</p>
+                <Button variant="ghost" size="sm" onClick={handleBack} className="text-xs">
+                  <ArrowLeft className="mr-1 size-3" /> Back to list
+                </Button>
+              </div>
+            ) : selectedEntity ? (
+              <EntityDetailView
+                entity={selectedEntity}
+                onBack={handleBack}
+                onNavigateEntity={handleSelectEntity}
+                onInsertQuery={handleInsertQuery}
+              />
+            ) : (
+              <div className="flex h-full items-center justify-center gap-2">
+                <Loader2 className="size-4 animate-spin text-zinc-400" />
+                <p className="text-xs text-zinc-400">Loading {selectedName}...</p>
+              </div>
+            )
+          ) : (
+            <EntityList
+              entities={entities}
+              search={search}
+              onSearchChange={setSearch}
+              typeFilter={typeFilter}
+              onTypeFilterChange={setTypeFilter}
+              onSelect={handleSelectEntity}
+            />
+          )}
+        </div>
+      </SheetContent>
+    </Sheet>
+  );
+}

package/templates/docker/src/ui/components/social-icons.tsx

@@ -0,0 +1,26 @@
+export function GoogleIcon() {
+  return (
+    <svg className="mr-2 size-4" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 01-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z" />
+      <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" />
+      <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" />
+      <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" />
+    </svg>
+  );
+}
+
+export function GitHubIcon() {
+  return (
+    <svg className="mr-2 size-4" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0024 12c0-6.63-5.37-12-12-12z" />
+    </svg>
+  );
+}
+
+export function MicrosoftIcon() {
+  return (
+    <svg className="mr-2 size-4" viewBox="0 0 24 24" fill="currentColor">
+      <path d="M0 0h11.377v11.372H0zm12.623 0H24v11.372H12.623zM0 12.623h11.377V24H0zm12.623 0H24V24H12.623z" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,81 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import { TourOverlay } from "./tour-overlay";
+import { useTour } from "./use-tour";
+
+interface TourContextValue {
+  /** Start or restart the guided tour. */
+  startTour: () => void;
+  /** Whether the tour is currently active. */
+  isActive: boolean;
+}
+
+const TourContext = createContext<TourContextValue | null>(null);
+
+/**
+ * Access the tour context to trigger a tour replay from any component
+ * (e.g. a help menu item).
+ */
+export function useTourContext(): TourContextValue | null {
+  return useContext(TourContext);
+}
+
+interface GuidedTourProps {
+  /** Atlas API base URL. */
+  apiUrl: string;
+  /** Whether the API is cross-origin. */
+  isCrossOrigin: boolean;
+  /** Whether the current user has admin role. */
+  isAdmin: boolean;
+  /** Whether server-side tracking is available (managed auth + internal DB). */
+  serverTrackingEnabled: boolean;
+  /** Child components that can trigger tour via context. */
+  children: ReactNode;
+}
+
+/**
+ * Guided tour provider + overlay.
+ *
+ * Wraps children with a TourContext so any descendant can call `startTour()`
+ * to replay the walkthrough (e.g. from a help menu).
+ *
+ * The tour auto-starts on first visit when the user hasn't completed it.
+ * Loaded via `next/dynamic` to avoid bundle impact on the critical path.
+ */
+export function GuidedTour({
+  apiUrl,
+  isCrossOrigin,
+  isAdmin,
+  serverTrackingEnabled,
+  children,
+}: GuidedTourProps) {
+  const tour = useTour({
+    apiUrl,
+    isCrossOrigin,
+    isAdmin,
+    serverTrackingEnabled,
+  });
+
+  const contextValue: TourContextValue = {
+    startTour: tour.start,
+    isActive: tour.isActive,
+  };
+
+  return (
+    <TourContext.Provider value={contextValue}>
+      {children}
+      {tour.isActive && tour.steps[tour.currentStep] && (
+        <TourOverlay
+          active={tour.isActive}
+          step={tour.steps[tour.currentStep]}
+          stepIndex={tour.currentStep}
+          totalSteps={tour.totalSteps}
+          onNext={tour.next}
+          onPrev={tour.prev}
+          onSkip={tour.skip}
+        />
+      )}
+    </TourContext.Provider>
+  );
+}

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

@@ -0,0 +1,5 @@
+export { GuidedTour, useTourContext } from "./guided-tour";
+export { TourOverlay } from "./tour-overlay";
+export { useTour } from "./use-tour";
+export { TOUR_STEPS } from "./tour-steps";
+export type { TourStep, TourStatus } from "./types";