feat: Onboarding Welcome Page

Author: camielvs

src/components/Onboarding/IndexRedirect.test.tsx

@@ -0,0 +1,43 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { IndexRedirect } from "./IndexRedirect";
+
+vi.mock("@tanstack/react-router", () => ({
+  Navigate: ({ to }: { to: string }) => <div data-testid="navigate">{to}</div>,
+}));
+
+let onboarding = { isReady: true, isComplete: false, dismissed: false };
+vi.mock("@/providers/OnboardingProvider/OnboardingProvider", () => ({
+  useOnboarding: () => onboarding,
+}));
+
+afterEach(cleanup);
+
+const target = () => screen.queryByTestId("navigate");
+
+describe("IndexRedirect", () => {
+  it("waits (no redirect) until onboarding state is ready", () => {
+    onboarding = { isReady: false, isComplete: false, dismissed: false };
+    render(<IndexRedirect />);
+    expect(target()).toBeNull();
+  });
+
+  it("redirects to /welcome while onboarding is active", () => {
+    onboarding = { isReady: true, isComplete: false, dismissed: false };
+    render(<IndexRedirect />);
+    expect(target()).toHaveTextContent("/welcome");
+  });
+
+  it("redirects to /dashboard once complete", () => {
+    onboarding = { isReady: true, isComplete: true, dismissed: false };
+    render(<IndexRedirect />);
+    expect(target()).toHaveTextContent("/dashboard");
+  });
+
+  it("redirects to /dashboard once dismissed", () => {
+    onboarding = { isReady: true, isComplete: false, dismissed: true };
+    render(<IndexRedirect />);
+    expect(target()).toHaveTextContent("/dashboard");
+  });
+});

src/components/Onboarding/IndexRedirect.tsx

@@ -0,0 +1,26 @@
+import { Navigate } from "@tanstack/react-router";
+
+import { BlockStack } from "@/components/ui/layout";
+import { Spinner } from "@/components/ui/spinner";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
+import { APP_ROUTES } from "@/routes/appRoutes";
+
+export function IndexRedirect() {
+  const { isReady, isComplete, dismissed } = useOnboarding();
+
+  if (!isReady) {
+    return (
+      <BlockStack align="center" inlineAlign="center" className="h-full">
+        <Spinner />
+      </BlockStack>
+    );
+  }
+
+  const showOnboarding = !isComplete && !dismissed;
+  return (
+    <Navigate
+      replace
+      to={showOnboarding ? APP_ROUTES.WELCOME : APP_ROUTES.DASHBOARD}
+    />
+  );
+}

src/components/Onboarding/OnboardingWelcome.tsx

@@ -0,0 +1,35 @@
+import { Link, Navigate } from "@tanstack/react-router";
+
+import { OnboardingHero } from "@/components/Learn/OnboardingHero";
+import { BlockStack } from "@/components/ui/layout";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
+import { APP_ROUTES } from "@/routes/router";
+import { tracking } from "@/utils/tracking";
+
+export function OnboardingWelcome() {
+  const { isReady, isComplete, dismissed } = useOnboarding();
+
+  if (isReady && (isComplete || dismissed)) {
+    return <Navigate to={APP_ROUTES.DASHBOARD} replace />;
+  }
+
+  return (
+    <BlockStack
+      gap="4"
+      align="center"
+      inlineAlign="center"
+      className="h-full w-full"
+    >
+      <div className="w-full max-w-2xl">
+        <OnboardingHero />
+      </div>
+      <Link
+        to={APP_ROUTES.LEARN}
+        className="text-sm text-muted-foreground hover:text-foreground"
+        {...tracking("homepage.onboarding.learning_hub")}
+      >
+        Explore the Learning Hub →
+      </Link>
+    </BlockStack>
+  );
+}

src/routes/Dashboard/DashboardLayout.tsx

@@ -9,6 +9,7 @@ import { BlockStack, InlineStack } from "@/components/ui/layout";
 import { Link as UILink } from "@/components/ui/link";
 import { Text } from "@/components/ui/typography";
 import { cn } from "@/lib/utils";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
 import { APP_ROUTES } from "@/routes/appRoutes";
 import {
   ABOUT_URL,
@@ -28,7 +29,12 @@ interface SidebarItem {
 }
 
 const BASE_SIDEBAR_ITEMS: SidebarItem[] = [
-  { to: "/", label: "My Dashboard", icon: "LayoutDashboard", exact: true },
+  {
+    to: APP_ROUTES.DASHBOARD,
+    label: "My Dashboard",
+    icon: "LayoutDashboard",
+    exact: true,
+  },
   { to: "/pipelines", label: "My Pipelines", icon: "GitBranch" },
   { to: "/runs", label: "All Runs", icon: "Play" },
   { to: "/components", label: "Components", icon: "Package" },
@@ -53,14 +59,29 @@ export function DashboardLayout() {
   const requiresAuthorization = isAuthorizationRequired();
   const isComponentSearchEnabled = useFlagValue("component-search-v2");
 
-  const sidebarItems = isComponentSearchEnabled
+  const { isComplete, dismissed, isResolved } = useOnboarding();
+  const showOnboarding = isResolved && !isComplete && !dismissed;
+
+  const baseItems = isComponentSearchEnabled
     ? BASE_SIDEBAR_ITEMS.map((item) =>
         item.to === APP_ROUTES.DASHBOARD_COMPONENTS
           ? COMPONENT_SEARCH_ITEM
           : item,
       )
     : BASE_SIDEBAR_ITEMS;
 
+  const sidebarItems: SidebarItem[] = showOnboarding
+    ? [
+        {
+          to: APP_ROUTES.WELCOME,
+          label: "Get started",
+          icon: "Rocket",
+          exact: true,
+        },
+        ...baseItems,
+      ]
+    : baseItems;
+
   return (
     <div
       className="flex w-full overflow-hidden"

src/routes/appRoutes.ts

@@ -9,7 +9,8 @@ const TOUR_BASE_PATH = "/tour";
 
 export const APP_ROUTES = {
   HOME: "/",
-  DASHBOARD: "/",
+  DASHBOARD: "/dashboard",
+  WELCOME: "/welcome",
   DASHBOARD_RUNS: "/runs",
   DASHBOARD_PIPELINES: "/pipelines",
   DASHBOARD_COMPONENTS: "/components",

src/routes/router.ts

@@ -7,6 +7,8 @@ import {
   redirect,
 } from "@tanstack/react-router";
 
+import { IndexRedirect } from "@/components/Onboarding/IndexRedirect";
+import { OnboardingWelcome } from "@/components/Onboarding/OnboardingWelcome";
 import { ErrorPage } from "@/components/shared/ErrorPage";
 import { AuthorizationResultScreen as GitHubAuthorizationResultScreen } from "@/components/shared/GitHubAuth/AuthorizationResultScreen";
 import { AuthorizationResultScreen as HuggingFaceAuthorizationResultScreen } from "@/components/shared/HuggingFaceAuth/AuthorizationResultScreen";
@@ -79,9 +81,21 @@ const dashboardRoute = createRoute({
 const dashboardIndexRoute = createRoute({
   getParentRoute: () => dashboardRoute,
   path: "/",
+  component: IndexRedirect,
+});
+
+const dashboardHomeRoute = createRoute({
+  getParentRoute: () => dashboardRoute,
+  path: APP_ROUTES.DASHBOARD,
   component: DashboardHomeView,
 });
 
+const welcomeRoute = createRoute({
+  getParentRoute: () => dashboardRoute,
+  path: APP_ROUTES.WELCOME,
+  component: OnboardingWelcome,
+});
+
 const dashboardRunsRoute = createRoute({
   getParentRoute: () => dashboardRoute,
   path: "/runs",
@@ -329,6 +343,8 @@ const artifactPreviewRoute = createRoute({
 
 const dashboardRouteTree = dashboardRoute.addChildren([
   dashboardIndexRoute,
+  dashboardHomeRoute,
+  welcomeRoute,
   dashboardRunsRoute,
   dashboardPipelinesRoute,
   dashboardComponentsRoute,

tests/e2e/navigation-tracking.spec.ts

@@ -5,12 +5,10 @@ test.describe("Navigation tracking", () => {
     page,
   }) => {
     await page.addInitScript(() => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       (window as any).__analyticsEvents = [];
       window.addEventListener("tangle.analytics.track", (e) => {
         const detail = (e as CustomEvent).detail;
         if (detail.actionType === "page_view") {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
           (window as any).__analyticsEvents.push(detail);
         }
       });
@@ -24,39 +22,39 @@ test.describe("Navigation tracking", () => {
     await page.getByRole("link", { name: "Settings" }).click();
     await expect(page).toHaveURL(/\/settings/);
 
-    const events = await page.evaluate(
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      () => (window as any).__analyticsEvents,
-    );
+    const events = await page.evaluate(() => (window as any).__analyticsEvents);
 
     expect(events.length).toBeGreaterThanOrEqual(2);
 
-    const [initial, navigation] = events;
-
-    // First page_view from landing on /
-    expect(initial.actionType).toBe("page_view");
-    expect(initial.metadata).toMatchObject({
-      to: "/",
+    const landing = events.find(
+      (e: { metadata?: { to?: string } }) =>
+        e.metadata?.to === "/welcome" || e.metadata?.to === "/dashboard",
+    );
+    expect(landing).toBeTruthy();
+    expect(landing.metadata).toMatchObject({
+      to: expect.stringMatching(/^\/(welcome|dashboard)$/),
       route_pattern: expect.any(String),
     });
 
-    // Second page_view from navigating to settings
-    expect(navigation.actionType).toBe("page_view");
+    // Navigating to settings emits a page_view.
+    const navigation = events.find(
+      (e: { metadata?: { to?: string } }) =>
+        typeof e.metadata?.to === "string" &&
+        e.metadata.to.includes("/settings"),
+    );
+    expect(navigation).toBeTruthy();
     expect(navigation.metadata).toMatchObject({
-      from: "/",
       to: expect.stringContaining("/settings"),
       route_pattern: expect.any(String),
     });
   });
 
   test("captures search params in page_view metadata", async ({ page }) => {
     await page.addInitScript(() => {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       (window as any).__analyticsEvents = [];
       window.addEventListener("tangle.analytics.track", (e) => {
         const detail = (e as CustomEvent).detail;
         if (detail.actionType === "page_view") {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
           (window as any).__analyticsEvents.push(detail);
         }
       });
@@ -67,10 +65,7 @@ test.describe("Navigation tracking", () => {
       page.locator("[data-testid='app-menu-actions']"),
     ).toBeVisible();
 
-    const events = await page.evaluate(
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      () => (window as any).__analyticsEvents,
-    );
+    const events = await page.evaluate(() => (window as any).__analyticsEvents);
 
     expect(events.length).toBeGreaterThanOrEqual(1);