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",
@@ -70,6 +71,7 @@ export const REACT_COMPILER_ENABLED_DIRS = [
   "src/components/ui/typography.tsx",
 
   "src/providers/DialogProvider",
+  "src/providers/OnboardingProvider",
   "src/providers/TourProvider/tourCompletion.ts",
   "src/routes/EditorV2",
 

src/components/Learn/DocsQuickLinks.tsx

@@ -2,6 +2,7 @@ import { Icon, type IconName } from "@/components/ui/icon";
 import { BlockStack, InlineStack } from "@/components/ui/layout";
 import { Link } from "@/components/ui/link";
 import { Text } from "@/components/ui/typography";
+import { useOnboarding } from "@/providers/OnboardingProvider/OnboardingProvider";
 import { DOCUMENTATION_URL } from "@/utils/constants";
 import { tracking } from "@/utils/tracking";
 
@@ -51,12 +52,19 @@ const QUICK_LINKS: QuickLink[] = [
   },
 ];
 
-function QuickLinkPill({ link }: { link: QuickLink }) {
+function QuickLinkPill({
+  link,
+  onClick,
+}: {
+  link: QuickLink;
+  onClick: () => void;
+}) {
   return (
     <a
       href={link.href}
       target="_blank"
       rel="noopener noreferrer"
+      onClick={onClick}
       className="inline-flex items-center gap-1.5 px-3 py-1 rounded-full border border-border hover:border-primary/40 hover:bg-muted/40 transition-all no-underline"
       {...tracking("learning_hub.documentation.quick_link", {
         link_id: link.id,
@@ -76,21 +84,24 @@ function QuickLinkPill({ link }: { link: QuickLink }) {
 }
 
 export function DocsQuickLinks() {
+  const { markDocsRead } = useOnboarding();
+
   return (
     <BlockStack gap="1">
       <Text size="sm" weight="semibold" className="text-muted-foreground">
         Quick links
       </Text>
       <InlineStack gap="2">
         {QUICK_LINKS.map((link) => (
-          <QuickLinkPill key={link.id} link={link} />
+          <QuickLinkPill key={link.id} link={link} onClick={markDocsRead} />
         ))}
         <Link
           href={DOCUMENTATION_URL}
           external
           variant="primary"
           size="sm"
           className="ml-1"
+          onClick={markDocsRead}
           {...tracking("learning_hub.documentation.full_docs")}
         >
           Full docs

src/components/Learn/OnboardingHero.tsx

@@ -1,116 +1,83 @@
-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 { cn } from "@/lib/utils";
-import { tracking } from "@/utils/tracking";
+import { Heading, Paragraph } from "@/components/ui/typography";
+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() {
-  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);
+  const { isComplete, dismissed, dismiss, reopen } = useOnboarding();
 
-  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>
+  if (dismissed) {
+    return (
+      <InlineStack align="end" className="text-muted-foreground opacity-50">
+        <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" />
           )}
-        </InlineStack>
+        </Button>
+      </InlineStack>
+    );
+  }
 
-        <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>
-          </InlineStack>
+  return (
+    <div className="relative rounded-xl border border-border bg-linear-to-br from-primary/5 to-transparent p-6">
+      <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>
 
-          <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>
+      <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>
+          <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,117 @@
+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,
+  onReadDocs,
+}: {
+  step: OnboardingStep;
+  onReadDocs: () => void;
+}) {
+  if (step.id === "read_docs") {
+    return (
+      <ExternalLink
+        href={DOCUMENTATION_URL}
+        external
+        variant="primary"
+        size="sm"
+        onClick={onReadDocs}
+        {...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,
+  onReadDocs,
+}: {
+  step: OnboardingStep;
+  onReadDocs: () => void;
+}) {
+  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} onReadDocs={onReadDocs} />}
+    </InlineStack>
+  );
+}
+
+export function OnboardingChecklist() {
+  const { steps, completedCount, total, markDocsRead } = 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} onReadDocs={markDocsRead} />
+        ))}
+      </BlockStack>
+    </BlockStack>
+  );
+}