feat: Onboarding Checklist

react-compiler.config.js

@@ -6,6 +6,7 @@ export const REACT_COMPILER_ENABLED_DIRS = [
   "src/components/Home",
   "src/components/Editor",
   "src/components/Learn",
+  "src/components/Onboarding",
 
   // 0 useCallback/useMemo - ready to enable
   "src/components/layout",
@@ -72,6 +73,7 @@ export const REACT_COMPILER_ENABLED_DIRS = [
 
   "src/providers/DialogProvider",
   "src/providers/TourProvider",
+  "src/providers/OnboardingProvider",
   "src/routes/EditorV2",
 
   // 11-20 useCallback/useMemo

src/components/Learn/LearnSearchBar.tsx

@@ -4,16 +4,19 @@ import { Icon } from "@/components/ui/icon";
 import { Input, InputGroup } from "@/components/ui/input";
 import { Text } from "@/components/ui/typography";
 import { useAnalytics } from "@/providers/AnalyticsProvider";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
 import { TANGLE_WEBSITE_URL } from "@/utils/constants";
 
 export function LearnSearchBar() {
   const [value, setValue] = useState("");
   const { track } = useAnalytics();
+  const { markDocsRead } = useOnboarding();
 
   const handleSubmit = () => {
     const query = value.trim();
     if (!query) return;
     track("learning_hub.search.submitted");
+    markDocsRead();
     const url = `${TANGLE_WEBSITE_URL}search/?q=${encodeURIComponent(query)}`;
     window.open(url, "_blank", "noopener,noreferrer");
   };

src/components/Learn/OnboardingHero.tsx

@@ -1,116 +1,92 @@
-import { Link } from "@tanstack/react-router";
-
+import { OnboardingChecklist } from "@/components/Onboarding/OnboardingChecklist";
 import { Button } from "@/components/ui/button";
 import { Icon } from "@/components/ui/icon";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
-import { Heading, Paragraph, Text } from "@/components/ui/typography";
+import { Heading, Paragraph } from "@/components/ui/typography";
 import { cn } from "@/lib/utils";
-import { tracking } from "@/utils/tracking";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
 
-interface OnboardingStep {
-  id: string;
-  label: string;
-  completed: boolean;
+function scrollNearestScrollableToTop(el: HTMLElement | null) {
+  let node = el?.parentElement ?? null;
+  while (node) {
+    const { overflowY } = getComputedStyle(node);
+    if (
+      (overflowY === "auto" || overflowY === "scroll") &&
+      node.scrollHeight > node.clientHeight
+    ) {
+      node.scrollTo({ top: 0, behavior: "smooth" });
+      return;
+    }
+    node = node.parentElement;
+  }
+  window.scrollTo({ top: 0, behavior: "smooth" });
 }
 
-const STUB_STEPS: OnboardingStep[] = [
-  { id: "configure-backend", label: "Connect a backend", completed: true },
-  { id: "import-sample", label: "Import a sample pipeline", completed: true },
-  { id: "run-pipeline", label: "Run your first pipeline", completed: false },
-  { id: "edit-component", label: "Edit a component", completed: false },
-  {
-    id: "create-pipeline",
-    label: "Build a pipeline from scratch",
-    completed: false,
-  },
-];
+export function OnboardingHero({ className }: { className?: string }) {
+  const { isComplete, dismissed, dismiss, reopen } = useOnboarding();
 
-export function OnboardingHero() {
-  const completed = STUB_STEPS.filter((s) => s.completed).length;
-  const total = STUB_STEPS.length;
-  const isComplete = completed === total;
-  const nextStep = STUB_STEPS.find((s) => !s.completed);
+  if (dismissed) {
+    return (
+      <InlineStack
+        align="end"
+        className={cn("text-muted-foreground opacity-50", className)}
+      >
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={(e) => {
+            reopen();
+            scrollNearestScrollableToTop(e.currentTarget);
+          }}
+        >
+          <Icon name="Rocket" size="sm" aria-hidden="true" />
+          {isComplete ? "Onboarding (complete)" : "Resume onboarding"}
+          {isComplete && (
+            <Icon name="ArrowRight" size="sm" aria-hidden="true" />
+          )}
+        </Button>
+      </InlineStack>
+    );
+  }
 
   return (
-    <div className="rounded-xl border border-border bg-linear-to-br from-primary/5 to-transparent p-6">
-      <BlockStack gap="4">
-        <InlineStack gap="4" align="space-between" blockAlign="start">
-          <BlockStack gap="2">
-            <InlineStack gap="2" blockAlign="center">
-              <Icon
-                name="Rocket"
-                size="lg"
-                className="text-primary"
-                aria-hidden="true"
-              />
-              <Heading level={2}>
-                {isComplete ? "You're all set up!" : "Welcome to Tangle"}
-              </Heading>
-            </InlineStack>
-            <Paragraph tone="subdued" size="sm">
-              {isComplete
-                ? "Onboarding complete — explore tours and tips below to keep going."
-                : "Follow a few quick steps to get from zero to your first pipeline run."}
-            </Paragraph>
-          </BlockStack>
-          {!isComplete && nextStep && (
-            <Button
-              asChild
-              size="sm"
-              {...tracking("learning_hub.onboarding.resume")}
-            >
-              <Link to="/learn">
-                Resume
-                <Icon name="ArrowRight" size="sm" aria-hidden="true" />
-              </Link>
-            </Button>
-          )}
-        </InlineStack>
+    <div
+      className={cn(
+        "relative rounded-xl border border-border bg-linear-to-br from-primary/5 to-transparent p-6",
+        className,
+      )}
+    >
+      <Button
+        variant="ghost"
+        size="icon"
+        onClick={dismiss}
+        aria-label="Dismiss onboarding"
+        className="absolute right-3 top-3 hover:bg-transparent hover:text-muted-foreground"
+      >
+        <Icon name="X" size="sm" aria-hidden="true" />
+      </Button>
 
-        <BlockStack gap="2">
-          <InlineStack gap="3" blockAlign="center">
-            <Text size="xs" tone="subdued" weight="semibold">
-              {completed} of {total} steps
-            </Text>
-            <div
-              className="flex-1 h-2 rounded-full bg-muted overflow-hidden"
-              role="progressbar"
-              aria-valuenow={completed}
-              aria-valuemin={0}
-              aria-valuemax={total}
-              aria-label="Onboarding progress"
-            >
-              <div
-                className="h-full bg-primary transition-all duration-300"
-                style={{ width: `${(completed / total) * 100}%` }}
-              />
-            </div>
+      <BlockStack gap="4">
+        <BlockStack gap="2" className="min-w-0 pr-8">
+          <InlineStack gap="2" blockAlign="center">
+            <Icon
+              name="Rocket"
+              size="lg"
+              className="text-primary"
+              aria-hidden="true"
+            />
+            <Heading level={2}>
+              {isComplete ? "You're all set up!" : "Welcome to Tangle"}
+            </Heading>
           </InlineStack>
-
-          <ul className="flex flex-wrap gap-x-4 gap-y-1.5 list-none p-0 m-0">
-            {STUB_STEPS.map((step) => (
-              <li key={step.id} className="flex items-center gap-1.5 text-xs">
-                <Icon
-                  name={step.completed ? "CircleCheck" : "Circle"}
-                  size="sm"
-                  className={cn(
-                    step.completed
-                      ? "text-primary"
-                      : "text-muted-foreground/60",
-                  )}
-                  aria-hidden="true"
-                />
-                <Text
-                  size="xs"
-                  tone={step.completed ? "subdued" : "inherit"}
-                  className={cn(step.completed && "line-through")}
-                >
-                  {step.label}
-                </Text>
-              </li>
-            ))}
-          </ul>
+          <Paragraph tone="subdued" size="sm">
+            {isComplete
+              ? "Onboarding complete - explore tours and tips below to keep going."
+              : "Follow a few quick steps to get from zero to your first pipeline run."}
+          </Paragraph>
         </BlockStack>
+
+        <OnboardingChecklist />
       </BlockStack>
     </div>
   );

src/components/Onboarding/OnboardingChecklist.tsx

@@ -0,0 +1,104 @@
+import { Link } from "@tanstack/react-router";
+
+import { Button } from "@/components/ui/button";
+import { Icon } from "@/components/ui/icon";
+import { BlockStack, InlineStack } from "@/components/ui/layout";
+import { Link as ExternalLink } from "@/components/ui/link";
+import { Text } from "@/components/ui/typography";
+import { cn } from "@/lib/utils";
+import {
+  type OnboardingStep,
+  useOnboarding,
+} from "@/providers/OnboardingProvider/OnboardingProvider";
+import { DOCUMENTATION_URL } from "@/utils/constants";
+import { tracking } from "@/utils/tracking";
+
+function StepCta({ step }: { step: OnboardingStep }) {
+  if (step.id === "read_docs") {
+    return (
+      <ExternalLink
+        href={DOCUMENTATION_URL}
+        external
+        variant="primary"
+        size="sm"
+        {...tracking("learning_hub.onboarding.step", { step_id: step.id })}
+      >
+        {step.cta.label}
+      </ExternalLink>
+    );
+  }
+
+  return (
+    <Button
+      asChild
+      size="sm"
+      variant="outline"
+      {...tracking("learning_hub.onboarding.step", { step_id: step.id })}
+    >
+      <Link to={step.cta.to}>{step.cta.label}</Link>
+    </Button>
+  );
+}
+
+function StepRow({ step }: { step: OnboardingStep }) {
+  return (
+    <InlineStack as="li" gap="3" blockAlign="start" wrap="nowrap">
+      <Icon
+        name={step.completed ? "CircleCheck" : step.icon}
+        size="md"
+        className={cn(
+          "mt-0.5 shrink-0",
+          step.completed ? "text-primary" : "text-muted-foreground",
+        )}
+        aria-hidden="true"
+      />
+      <BlockStack className="min-w-0 flex-1">
+        <Text
+          size="sm"
+          weight="semibold"
+          tone={step.completed ? "subdued" : "inherit"}
+          className={cn(step.completed && "line-through")}
+        >
+          {step.label}
+        </Text>
+        <Text size="xs" tone="subdued">
+          {step.description}
+        </Text>
+      </BlockStack>
+      {!step.completed && <StepCta step={step} />}
+    </InlineStack>
+  );
+}
+
+export function OnboardingChecklist() {
+  const { steps, completedCount, total } = useOnboarding();
+
+  return (
+    <BlockStack gap="4">
+      <InlineStack gap="3" blockAlign="center">
+        <Text size="xs" tone="subdued" weight="semibold">
+          {completedCount} of {total} steps
+        </Text>
+        <div
+          className="flex-1 h-2 rounded-full bg-muted overflow-hidden"
+          role="progressbar"
+          aria-valuenow={completedCount}
+          aria-valuemin={0}
+          aria-valuemax={total}
+          aria-label="Onboarding progress"
+        >
+          <div
+            className="h-full bg-primary transition-all duration-300"
+            style={{ width: `${(completedCount / total) * 100}%` }}
+          />
+        </div>
+      </InlineStack>
+
+      <BlockStack as="ul" gap="3" align="stretch" className="list-none p-0 m-0">
+        {steps.map((step) => (
+          <StepRow key={step.id} step={step} />
+        ))}
+      </BlockStack>
+    </BlockStack>
+  );
+}

src/components/layout/RootLayout.tsx

@@ -10,6 +10,7 @@ import { useSessionPipelineStats } from "@/hooks/useSessionPipelineStats";
 import { AnalyticsProvider } from "@/providers/AnalyticsProvider";
 import { BackendProvider } from "@/providers/BackendProvider";
 import { ComponentSpecProvider } from "@/providers/ComponentSpecProvider";
+import { OnboardingProvider } from "@/providers/OnboardingProvider/OnboardingProvider";
 import { TourProvider } from "@/providers/TourProvider/TourProvider";
 import { PipelineStorageProvider } from "@/services/pipelineStorage/PipelineStorageProvider";
 
@@ -29,21 +30,23 @@ function RootLayoutContent() {
       <ComponentSpecProvider>
         <PipelineStorageProvider>
           <TourProvider>
-            <SessionPipelineStatsTracker />
-            <ToastContainer />
-            <ConfirmDialogBridge />
+            <OnboardingProvider>
+              <SessionPipelineStatsTracker />
+              <ToastContainer />
+              <ConfirmDialogBridge />
 
-            <div className="App flex flex-col min-h-screen w-full">
-              <AppMenu />
+              <div className="App flex flex-col min-h-screen w-full">
+                <AppMenu />
 
-              <main className="flex-1 grid">
-                <Outlet />
-              </main>
+                <main className="flex-1 grid">
+                  <Outlet />
+                </main>
 
-              {import.meta.env.VITE_ENABLE_ROUTER_DEVTOOLS === "true" && (
-                <TanStackRouterDevtools />
-              )}
-            </div>
+                {import.meta.env.VITE_ENABLE_ROUTER_DEVTOOLS === "true" && (
+                  <TanStackRouterDevtools />
+                )}
+              </div>
+            </OnboardingProvider>
           </TourProvider>
         </PipelineStorageProvider>
       </ComponentSpecProvider>