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/ed43073

[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.

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

This PR adds new exported React components/hooks under src/providers/TourProvider, but react-compiler.config.js is unchanged and src/providers/TourProvider is not covered by REACT_COMPILER_ENABLED_DIRS. The review standard treats missing compiler coverage for new components/hooks as High because it bypasses the project's incremental React Compiler adoption.

Suggestion: Add the new TourProvider files, or the cleaned-up TourProvider directory, to react-compiler.config.js after fixing compiler-incompatible patterns in this PR.

Rule: tangle-ui-review: React Compiler adoption; .claude/skills/react-patterns/SKILL.md: Adding Files to React Compiler

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

recordTourVisited(currentStep) mutates module-level state while TourNavigation renders. This is not React Compiler compatible and also makes visited navigation state global to the module instead of scoped to a TourProvider instance.

Suggestion: Keep visited progress in provider-scoped React state/context, and update it from an effect or navigation action rather than mutating module state during render.

Rule: .claude/skills/react-patterns/SKILL.md: React Compiler compatible code must not mutate values during render

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

FTA reports TourNavigation.tsx at 61.75 with cyclomatic complexity 40 across 280 lines, which is over the strong-flag thresholds. The new file combines navigation buttons, revisit tracking, checklist rendering, progress dots, and auto-advance timing.

Suggestion: Split this into smaller sibling components/hooks, e.g. TourNavButton, TourProgressDots, useVisitedTourSteps, and TourAutoAdvance, so each unit has one responsibility and lower complexity.

Rule: static-analysis skill: FTA > 60 and cyclomatic complexity > 20 are strong flags; tangle-ui-review: Readability & component size

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

The new checklist casts StepType to ChecklistStep instead of narrowing or typing the tour step metadata at the source. That bypasses the TypeScript standard's preference for type guards and proper source typing over as Type assertions.

Suggestion: Define a project tour-step type that extends Reactour's StepType with the supported interaction metadata, or add a small type guard that checks interaction before passing the step to tourActionLabel.

Rule: .claude/skills/typescript-standards/SKILL.md: avoid unsafe type casting; prefer proper typing/type guards

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

The new navigation UI passes Tailwind className values into Tangle UI primitives such as InlineStack, Icon, Text, BlockStack, and Badge. The UI primitive standard says to use semantic props, tone, variants, or a local raw-HTML primitive rather than styling primitives through className.

Suggestion: Move layout/background needs into supported primitive props or a small local wrapper/pattern component, and use semantic tone/variant props for text/icon/dot colors instead of hardcoded color classes.

Rule: tangle-ui-review: UI primitives; .claude/skills/ui-primitives/SKILL.md: prefer primitives and semantic props over raw class styling