feat: Guided Tours Custom Navigation

[camielvs]

Description

Replaces reactour's default Prev/Next with a custom tour navigation and the interactive-step UX layer that sits on top of it: progress dots, a completion-gated "Next", an action checklist in the popover, and auto-progress. Visible behavior becomes observable once the registry has tours (#2306 onwards).

What's in it

Custom navigation

• Progress dots between Prev and Next, one per step, colored by visit state (current / visited / unvisited). Non-clickable — bouncing between arbitrary steps would leave reactour inconsistent on tours with interaction gates.
• The furthest-reached step is tracked at module level so the indicator survives popover remounts and stays accurate on tours that swap step content via setSteps.
• Visit-aware Next: a "Next" text label on the furthest-reached step, a chevron-only button on revisits.

Step completion + gated "Next"

• TourProgressContext tracks per-step completion (a Set of completed step indices), reset whenever a tour opens.
• On an interactive step, "Next" is disabled until the step's interaction is reported complete (the editor bridge in feat: Guided Tours Framework (Navigating the Editor) #2299 reports completion). On non-interactive steps, and on already-complete/revisited steps, it's enabled.

Action checklist

• TourStepChecklist renders the step's required action in the popover and ticks it off — Circle → CircleCheck with a check animation and strike-through — when complete.
• Labels come from tourActionLabel and may embed bold targets (e.g. "Select the Greet task"), rendered via renderInline (exported from TourContent). Each interaction's label is authored in the PR that introduces that interaction (feat: Guided Tours Framework (Navigating the Editor) #2299 / feat: Guided Tours Framework (First Pipeline) #2347 / feat: Guided Tours Framework (Subgraphs) #2365).

Auto-progress

• TourAutoAdvance advances ~800ms after a fresh completion — long enough to see the tick register. Steps already complete on arrival (e.g. revisited via Back) stay on a manual click; clicking "Next" advances immediately and cancels the pending auto-advance.

File layout

• Navigation components live in TourNavigation.tsx (TourNavigation, NavButton, GatedNextButton/renderNextButton, TourStepChecklist, TourAutoAdvance, and the module-level visit-tracking helpers).
• TourPopover.tsx keeps popover styling/positioning, the viewport clamp bridge, and the completion actions.
• TourProgressContext.tsx holds the completion state + useTourProgress hook. Tests: TourNavigation.test.tsx and TourProgressContext.test.tsx.

Popover polish

• The navigation row fills the popover width, and the checklist is spaced from the step content above it.

Related Issue and Pull requests

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

Depends on #2348 (foundation). The interaction detection that drives completion lands in #2299; interaction-specific checklist labels are authored in #2299 / #2347 / #2365.

Type of Change

• New feature

Checklist

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

Test Instructions

With a tour registered (use this branch with #2306 on top):

Dots

• Step through the tour. Each dot fills in as you reach it — current is enlarged + saturated, visited is lighter blue, unvisited is zinc-gray. Clicking a dot does nothing (intentionally disabled).

Checklist + gated Next

• On an interactive step (e.g. step 7's "click the Greet task"), a checklist row shows the required action and "Next" is disabled.
• Complete the action — the row ticks (check animation + strike-through) and, after ~800ms, the tour auto-advances. Clicking "Next" while it's enabled advances immediately.
• A step whose action is already satisfied on arrival shows pre-checked with "Next" enabled.

Visit-aware Next + revisits

• On the furthest step reached, "Next" shows a text label; stepping back via Prev collapses it to a chevron. Revisited (already-complete) steps do not auto-advance — they wait for a manual click.

Reset between tours

• Finish a tour, return to /learn/tours, start a different one. Completion + visited-max reset for the new tour.

[github-actions]

🎩 Preview

A preview build has been created at: 05-29-feat_guided_tours_navigation_dots_track_progress/0090034

[camielvs]

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: Guided Tour - Navigating the Editor #2306 : 2 dependent PRs (#2307 , #2347 )
• 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 👈 (View in Graphite)
• 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.

[camielvs]

🤖 This is an AI-generated code review comment.

Duplicated step-target type shape (project-conventions — extract duplicated definitions)

This ChecklistStep enumerates the same target* fields as TourActionLabelInput in tourActionLabels.ts, and tourActionLabel(interactiveStep) is already called with a ChecklistStep. The two will drift as new interaction targets are added. Both files are new in this PR, so it's the right time to unify.

Fix: type ChecklistStep = StepType & TourActionLabelInput; (import TourActionLabelInput) — single source of truth for the target fields.

[camielvs]

🤖 This is an AI-generated code review comment.

Inline static style (project-conventions — inline style only for dynamic/computed values)

style={{ visibility: "hidden", pointerEvents: "none" }} is fully static → use Tailwind: className="invisible pointer-events-none". Carried over from the old renderNextButton, but this file is new/extracted here so it's fair to fix now.

[camielvs]

🤖 This is an AI-generated code review comment.

Hardcoded palette colors vs tone/tokens (ui-primitives)

bg-slate-50 here and text-zinc-400 / text-zinc-500 line-through / text-green-600 on the checklist Icon/Text use raw palette classes. Prefer the semantic equivalents: the checklist Text → tone="subdued", bg-slate-50 → bg-muted. (The text-blue-*/text-zinc-* on the dot Badge variant="dot" below are decorative state colors — leave those if no token fits.)

[camielvs]

🤖 This is an AI-generated code review comment.

Component defined inside render (react-patterns)

NavButton is declared in TourNavigation's render body, so it gets a new component identity every render and the nav buttons remount each time. Low impact here (stateless leaves, and reactour's render-prop API nudges this shape), but hoisting it to module scope and passing currentStep/disableAll/rtl as props would avoid the churn.

[camielvs]

🤖 This is an AI-generated code review comment.

as casts — informational, no change needed (typescript-standards)

props.Button as FC<...> (line 35) and step as ChecklistStep (line 105) are as casts, which typescript-standards generally discourages. Both work around genuine limitations in reactour's narrower third-party types, and the Button cast carries a clear WHY comment. Flagging only for completeness — these are acceptable as-is.

[camielvs]

type narrowing