feat: Onboarding Checklist by camielvs · Pull Request #2421 · TangleML/tangle-ui

camielvs · 2026-06-17T20:54:55Z

Description

First PR in a stacked series that builds an onboarding experience for new users (see #622). This one lays the foundation and surfaces the first piece of UI — an onboarding checklist on the Learning Hub.

Foundation (OnboardingProvider)

Tracks four steps: read the docs, complete a guided tour, create a pipeline, and execute a run.
Steps are detected automatically rather than self-reported:
- complete a tour — derived from TourProvider completions.
- execute a run — queried from the backend (runs created by the current user).
- create a pipeline — driven by a small event bus (userPipelineWriteEvents) emitted from the pipeline-write chokepoints (componentStore and PipelineFile), so v1 edits, v2 edits, imports, and the new-pipeline button all count.
- read the docs — marked when the user opens the docs link.
Progress is persisted to the backend (/api/users/me/settings), not localStorage. Writes use keepalive so a fire-and-forget save survives navigation/reload.
Supports dismiss / restore.

UI

OnboardingChecklist — a reusable progress + step-list component (extracted up front so the next PR doesn't have to refactor it).
OnboardingHero on the Learning Hub renders the checklist with progress, per-step CTAs, and a dismiss control.

Provider and Onboarding components are enabled in the React Compiler.

Stacked PR — base of the series. Followed by the Onboarding Pill (#2440) and the Onboarding Welcome Page (#2435).

Related Issue and Pull requests

Progresses https://github.com/Shopify/oasis-frontend/issues/622

Stacked: #2440 → #2435

Type of Change

New feature

Checklist

I have tested this does not break current pipelines / runs functionality
I have tested the changes on staging

Screenshots (if applicable)

Test Instructions

As a fresh user (or after resetting onboarding settings), open the Learning Hub — the checklist should show 0/4 complete.
Complete a guided tour, create a pipeline, and execute a run — each should tick off without a reload (creation is event-driven).
Click the docs CTA — read the docs should tick.
Reload — progress should persist (backed by user settings, not localStorage).
Dismiss the card, reload, and restore it — dismissal state should persist too.

Additional Comments

The provider exposes isReady (queries settled, for routing) vs isResolved (backend resolved + state loaded, for gating visible UI). The downstream pill/welcome PRs rely on this distinction to avoid flicker.

camielvs · 2026-06-17T20:55:27Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

feat: Onboarding Welcome Page #2435
feat: Onboarding Pill #2440
feat: Onboarding Checklist #2421 👈 (View in Graphite)
feat: Learning Hub - Milestone 2 #2416
feat: Guided Tours Cleanup #2417
feat: Guided Tours E2E Tests #2415
feat: Guided Tours Completion Metrics #2412
feat: Guided Tour - Secrets #2406
feat: Guided Tours Framework (Secrets) #2405
feat: Guided Tour - Subgraphs #2366
feat: Guided Tours Framework (Subgraphs) #2365
feat: Guided Tour - First Pipeline #2312
feat: Guided Tours Framework (First Pipeline) #2347
feat: Guided Tour - Navigating the Editor #2306 : 1 other dependent PR (#2307 )
feat: Guided Tours Framework (Navigating the Editor) #2299
feat: Guided Tours End Screen #2339
feat: Guided Tours Ephemeral Pipelines #2334
feat: Guided Tours Custom Navigation #2340
feat: Guided Tours Foundation #2348
feat: Learning Hub Guided Tours #2297
feat: Learning Hub - Milestone 1 #2341
feat: Learning Hub Tip of the Day #2292
feat: Learning Hub Tip Browser #2291
feat: Learning Hub Example Pipelines #2283
feat: Learning Hub Documentation & FAQ #2282
feat: Learning Hub Dashboard #2281
master

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-06-17T20:57:01Z

🎩 Preview

A preview build has been created at: 06-17-feat_onboarding_checklist/a9f00df

camielvs

Reviewed the foundation PR. Solid structure — backend-backed progress, derived vs. self-reported steps, and good test coverage (parseProgress, hooks offline/online, docs-visit tracking). A few non-blocking observations left inline.

maxy-shpfy · 2026-06-26T06:17:23Z

+  const filterQuery = filtersToFilterQuery(parseFilterParam("created_by:me"));
+
+  const { data } = useQuery({
+    queryKey: ["onboarding", "myRunCount", backendUrl],


🤖 This is an AI-generated code review comment.

The new run-completion query uses its own key (["onboarding", "myRunCount", backendUrl]) with a 5-minute stale window and refetchOnWindowFocus: false. Existing pipeline submission invalidates queryKey: ["pipelineRuns"], so a brand-new user who starts with zero runs can submit a run and return to Learn while this query remains cached at 0. That leaves the new execute_run checklist item incomplete until the cache eventually refetches, which breaks the core onboarding flow introduced by thi…

Suggestion: Wire this query into the same invalidation path as run creation: either use/share the existing pipeline-runs query key, invalidate ["onboarding", "myRunCount"] from the submit success path, or emit a run-created event and refetch this query immediately. Add a test that starts with no runs, simulates run creation/invalidation, and verifies `execut…

Rule: Tangle UI review / General quality: TanStack Query server state must stay fresh through the relevant mutation invalidation path; review only changed code.

maxy-shpfy · 2026-06-26T06:17:24Z

+    queryFn: async () => {
+      const url = new URL(PIPELINE_RUNS_QUERY_URL, backendUrl);
+      if (filterQuery) url.searchParams.set("filter_query", filterQuery);
+      const payload = (await fetchWithErrorHandling(


🤖 This is an AI-generated code review comment.

The onboarding provider casts the raw fetchWithErrorHandling result to ListPipelineJobsResponse and then reads pipeline_runs. Project TypeScript standards avoid as Type assertions for external data because they bypass runtime validation and can hide malformed API responses.

Suggestion: Use a small parser/type guard for the response, or type the query function around a validated shape before reading pipeline_runs. For example, check that the payload is a record and pipeline_runs is an array before returning its length.

Rule: .claude/skills/typescript-standards: avoid unsafe type casting; prefer type guards/runtime validation.

maxy-shpfy · 2026-06-26T06:17:25Z

+  return (data ?? 0) > 0;
+}
+
+export function OnboardingProvider({ children }: { children: ReactNode }) {


🤖 This is an AI-generated code review comment.

FTA reports 53.6 with cyclomatic complexity 13 for this new provider. The file is still under the large-file threshold, but it already combines settings persistence, docs click tracking, pipeline-write events, tour-derived state, run-derived state, analytics, and context shaping. That makes future onboarding-step changes more likely to regress.

Suggestion: Split the derived step sources and actions into focused hooks/helpers, especially the run-completion query and persisted-step actions. The run-completion refetch fix above is a natural place to extract a useHasMyRun hook with an exported query key.

Rule: .tangent/skills/static-analysis: FTA 50-60 and cyclo 11-20 are medium flags that should map to an extraction/readability suggestion.

- Render OnboardingHero once, drive placement via CSS order toggle - Document why derived onboarding steps don't emit step.completed - Reconcile onboarding progress cache on PATCH failure via onError Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

camielvs mentioned this pull request Jun 17, 2026

feat: Guided Tours Cleanup #2417

Open

8 tasks

camielvs added the #gsd:50583 Learning Hub label Jun 17, 2026 — with Graphite App

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from c455af7 to fddfd22 Compare June 17, 2026 20:56

camielvs added the #gsd:50583 Learning Hub label Jun 17, 2026

camielvs force-pushed the 06-17-feat_onboarding_checklist branch 5 times, most recently from 247aa01 to a27cdb0 Compare June 18, 2026 22:35

This was referenced Jun 18, 2026

feat: Onboarding Welcome Page #2435

Open

feat: Onboarding Pill #2440

Open

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from a27cdb0 to 72eadf3 Compare June 19, 2026 02:09

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from 65047a8 to 1823626 Compare June 19, 2026 02:25

camielvs force-pushed the 06-17-feat_onboarding_checklist branch 4 times, most recently from ebc0b79 to 3b09b65 Compare June 19, 2026 17:40

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from 1823626 to f6fe1e5 Compare June 19, 2026 18:49

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from 3b09b65 to 30b5b30 Compare June 19, 2026 18:49

camielvs force-pushed the 06-17-feat_onboarding_checklist branch 2 times, most recently from 5d180fd to 4e68a1c Compare June 19, 2026 21:08

camielvs marked this pull request as ready for review June 19, 2026 21:24

camielvs requested a review from a team as a code owner June 19, 2026 21:24

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from f6fe1e5 to ab71553 Compare June 19, 2026 21:48

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from 4e68a1c to c818dc8 Compare June 19, 2026 21:48

camielvs commented Jun 19, 2026

View reviewed changes

Comment thread src/routes/Dashboard/Learn/LearnHomeView.tsx Outdated

Comment thread src/providers/OnboardingProvider/OnboardingProvider.tsx

Comment thread src/providers/OnboardingProvider/onboardingProgress.ts

camielvs force-pushed the 06-17-feat_onboarding_checklist branch 2 times, most recently from 8bdff0e to 2741cce Compare June 19, 2026 23:17

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from ab71553 to c1e70ec Compare June 26, 2026 00:20

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from 2741cce to 7e5fb3b Compare June 26, 2026 00:20

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from c1e70ec to f8a3078 Compare June 26, 2026 00:37

camielvs force-pushed the 06-17-feat_onboarding_checklist branch 2 times, most recently from 3691b8e to 12d1304 Compare June 26, 2026 00:53

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from f8a3078 to 01cfb6d Compare June 26, 2026 00:53

maxy-shpfy reviewed Jun 26, 2026

View reviewed changes

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from 12d1304 to db9a9fd Compare June 26, 2026 17:20

camielvs and others added 2 commits June 26, 2026 10:22

feat: Onboarding Checklist

792964f

camielvs force-pushed the 06-12-feat_learning_hub_-_milestone_2 branch from 0667d58 to b5fde41 Compare June 26, 2026 17:22

camielvs force-pushed the 06-17-feat_onboarding_checklist branch from db9a9fd to a9f00df Compare June 26, 2026 17:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Onboarding Checklist#2421

feat: Onboarding Checklist#2421
camielvs wants to merge 2 commits into
06-12-feat_learning_hub_-_milestone_2from
06-17-feat_onboarding_checklist

camielvs commented Jun 17, 2026 •

edited

Loading

Uh oh!

camielvs commented Jun 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 17, 2026 •

edited

Loading

Uh oh!

camielvs left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maxy-shpfy Jun 26, 2026

Uh oh!

maxy-shpfy Jun 26, 2026

Uh oh!

maxy-shpfy Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

camielvs commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue and Pull requests

Type of Change

Checklist

Screenshots (if applicable)

Test Instructions

Additional Comments

Uh oh!

camielvs commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎩 Preview

Uh oh!

camielvs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maxy-shpfy Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

maxy-shpfy Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

maxy-shpfy Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

camielvs commented Jun 17, 2026 •

edited

Loading

camielvs commented Jun 17, 2026 •

edited

Loading

github-actions Bot commented Jun 17, 2026 •

edited

Loading