feat: Guided Tours Framework (Subgraphs)

[camielvs]

Description

The subgraph-specific interaction mechanics for the guided-tour framework, layered on the framework stack (#2348 / #2299 / #2347 / #2340). Foundation for the Subgraphs tour (#2366) — this PR adds the interaction types and the bridge logic that detects them; the tour content lands in #2366.

Five new tour interactions cover navigating and authoring subgraphs, plus a canvas re-measurement fix so spotlights track the viewport when navigation changes the view.

What changed

Interaction vocabulary (src/components/Learn/tours/registry.ts)

Five new TourStep.interaction values, plus a targetMinCount field:

• navigate-into-subgraph — descends a level (optionally gated to a specific targetTaskName)
• navigate-to-root — returns to the top level
• unpack-subgraph — the active spec's subgraph-task count drops (a subgraph was flattened)
• multi-select-tasks — ≥ targetMinCount (default 2) task nodes are selected
• create-subgraph — the subgraph-task count rises (a subgraph was created)

Bridge handlers (src/routes/v2/pages/Editor/components/EditorTourBridge.tsx)

Each interaction is detected by observing the existing MobX stores — navigation.navigationDepth / navigationPath for level changes, navigation.activeSpec.tasks (counting subgraphSpec) for unpack/create, and editor.multiSelection for multi-select. Following the model from #2299, a detected interaction marks the step complete in the shared tour-progress state (it does not advance the tour itself); already-satisfied-on-entry states are marked complete immediately. Gated "Next" / auto-advance (#2340) handle progression.

Contextual checklist labels

Adds the checklist copy for these interactions (using the contextual bold-target support from #2340):

• navigate-into-subgraph → "Open the {targetTaskName} subgraph"
• multi-select-tasks → "Select {targetMinCount} tasks"
• navigate-to-root → "Return to the top level"
• unpack-subgraph → "Unpack the subgraph"
• create-subgraph → "Create a subgraph from the selected tasks"

Spotlight re-measurement while navigating

• Dispatches a resize event (via requestAnimationFrame) whenever the xyflow viewport pans/zooms during an open tour, so reactour re-positions the highlight/popover after navigating into a subgraph shifts the canvas.
• ensureWindowRestored now waits for the target DOM to actually appear — the step's own selector, else the dock window — polling up to 1.5s before forcing a re-measure, instead of measuring against a not-yet-rendered target.

Related Issue and Pull requests

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

Builds on the framework stack (#2348 / #2299 / #2347 / #2340); consumed by the Subgraphs tour in #2366.

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

The registry is otherwise inert in this PR — the interactions are exercised end-to-end by the Subgraphs tour in #2366. To verify in isolation:

• No regressions in the existing tours ("Find your way around the editor", "Build your first pipeline"): interaction completion, ensureWindowRestored steps, and the dock/window highlight steps still work.
• Re-measurement — in any canvas-anchored tour step, pan/zoom the viewport; the spotlight/popover should re-position to follow rather than freeze.

Additional Comments

Selector/anchor additions and the seed pipeline for the subgraph tour live in #2366, following the convention that tour-specific DOM anchors ship alongside the tour that needs them.

[github-actions]

🎩 Preview

A preview build has been created at: 06-03-feat_guided_tours_framework_subgraphs_/4ba9aae

[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: 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 👈 (View in Graphite)
• 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.

[camielvs]

🤖 This is an AI-generated code review comment.

This countSubgraphTasks is defined identically here and in the create-subgraph branch (line ~722) — both count spec.tasks.filter((t) => t.subgraphSpec !== undefined).length. The two branches differ only in direction (current < baseline for unpack, current > baseline for create).

This is the same count-delta logic the file already centralizes in countForInteraction / isCountInteraction at the top. Per project-conventions (extract duplicated logic, especially against helpers established in the same file), hoist a module-level function countSubgraphTasks(spec: ComponentSpec | null): number next to countForInteraction and have both branches call it — each branch then only owns its direction check.

[camielvs]

🤖 This is an AI-generated code review comment.

This waitForDom loop is structurally identical to the tryRefresh loop in the resetLibrarySearch effect (around line 292): same Date.now() 1500ms budget, same 50ms setTimeout recursion, same cancelled guard, and the same setSteps?.((prev) => [...prev]) trick to force reactour to re-query the step selector.

Two copies of a non-obvious mechanism (the setSteps clone especially) will drift. Since this PR introduces the second copy, it's the right place to extract — e.g. a shared pollForSelectorThenRefreshSteps({ wantSelector, fallbackSelector, setSteps }) that returns a cancel function, called from both effects.

[camielvs]

🤖 This is an AI-generated code review comment.

useViewport is called unconditionally, so EditorTourBridge (mounted whenever the editor is) re-renders on every viewport change — pan and zoom, every frame — regardless of isOpen.

The render itself is cheap (returns null, and the heavy interaction effect's deps don't change), and the resize-dispatch effect below is correctly isOpen-gated and rAF-guarded, so this is Low — just flagging that the subscription cost is paid outside tour mode too. If it ever shows up in profiling, scoping the viewport-follow into a child that mounts only when isOpen would isolate the subscription; otherwise not worth the added indirection.

[camielvs]

🤖 This is an AI-generated code review comment.

Minor: displayName is a required string on NavigationEntry, so the second optional chain is redundant — last?.displayName.toLowerCase() suffices (the last?. already short-circuits when the path entry is undefined).