feat: Guided Tours Framework (First Pipeline)

[camielvs]

Description

The interaction primitives, popover positioning, and CSS utilities needed to power the second guided tour (#2312 — Build Your First Pipeline). No visible behavior on its own; all testing happens in #2312.

Builds directly on #2299 (the first three interactions). This PR introduces the remaining interactions a build-from-scratch tour needs, plus a handful of cross-cutting tour-step features.

What's new

New interaction types (EditorTourBridge.tsx)

Each is declared on a tour step via interaction: "<name>". Following the model established in #2299, a detected interaction marks the step complete in the shared tour-progress state — it does not advance the tour itself; the gated "Next" / auto-advance in #2340 handle progression.

• expand-folder — completes when the named folder in the component library is expanded (matches [data-folder-name=...] [aria-expanded="true"]).
• library-search — completes when the search box value contains a target substring; debounced so the user finishes typing first.
• add-task — completes when a task whose name matches a target substring is added to the canvas. Baseline counted at step start so pre-existing tasks don't false-trigger.
• add-input / add-output — count-based: complete when spec.inputs.length / spec.outputs.length increases.
• connect-edge — completes when a specific edge is drawn, matched by (sourceTaskName, sourcePortName, targetTaskName, targetPortName). The target task/port pair is optional.
• set-argument — completes when a specific argument on any task is set to a non-empty string.

Existing select-task (from #2299) gets a targetTaskName narrowing — only the named task counts, not any task.

Contextual checklist labels

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

• add-task → "Add {targetTaskName} to the canvas"
• expand-folder → "Open the {targetFolderName} folder"
• library-search → "Search the library for {targetSearchTerm}"
• set-argument → "Set the {targetArgumentName} value"
• add-input / add-output / connect-edge → generic phrasings

Each falls back to a generic label when its target field isn't set.

Cross-cutting step features

• ringSelectors — paint per-element rings via the new .tour-ring CSS class (reactour merges highlightedSelectors into one bounding box; per-handle rings need a separate mechanism).
• requiresTaskSelected — auto-rewind to a previous select-task step if the required task is no longer selected.
• ensureWindowRestored — auto-restore a minimized/hidden dock window at step start.
• resetLibrarySearch — clear the component-library search box before the step's selector is queried.
• libraryDragAllow — block drags of library items that don't match the step's target.

Popover positioning

• computeDefaultPopoverPosition gets a symmetric left-anchored tall-strip branch (mirrors the right-anchored branch from feat: Guided Tours Foundation #2348) for steps that highlight the component library.
• POPOVER_STYLES.clickArea set to pointer-events: none so the spotlight click-area doesn't intercept drags onto the canvas.

Misc

• TourStep registry types extended with the new interaction fields (targetFolderName, targetSearchTerm, targetTaskName, targetComponentName, targetEdge, targetArgumentName, plus the cross-cutting flags above).
• .tour-ring CSS utility in editor.css, with a React Flow handle override (position: absolute).
• defaultPipelineYamlWithName now JSON.stringifys the name (pipelines named with YAML-special characters were breaking the YAML).

Related Issue and Pull requests

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

Builds on #2299. Consumed by #2312 (First Pipeline tour content).

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

No visible behavior on its own — every new utility is unused until #2312 lands. Regression-only checks in isolation:

• Navigating the Editor tour (feat: Guided Tour - Navigating the Editor #2306) still works end-to-end; none of the new interactions or cross-cutting features affect tours that don't use them.
• select-task without targetTaskName still completes on click of any task (the narrowing is opt-in).
• Editor opens normally, no console errors from the new CSS utility or popover-style additions.

Additional Comments

Originally bundled into #2312 alongside the tour content; split out so reviewers can read the mechanics and the tour JSON separately.

[github-actions]

🎩 Preview

A preview build has been created at: 06-02-feat_guided_tours_framework_2/fb72c17

[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: Onboarding Welcome Page #2435
• feat: Onboarding Pill #2440
• feat: Onboarding Checklist #2421
• 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 👈 (View in Graphite)
• 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.

[maxy-shpfy]

🤖 This is an AI-generated code review comment.

This PR grows EditorTourBridge from FTA 53.9/cyclo 32/155 lines to FTA 76.3/cyclo 118/526 lines. The added interaction branches, DOM observers, timers, MobX reactions, selection repair, drag gating, and count tracking all live in one component/effect, which is above the static-analysis strong-flag thresholds and makes the first-pipeline tour behavior difficult to reason about or safely extend.

Suggestion: Split the new behavior into co-located helpers/hooks keyed by interaction, e.g. a small interaction handler map plus focused hooks for library search reset, ring selectors, required selection, and spec-count progression. Keep EditorTourBridge as the orchestrator and add targeted tests around each extracted handler.

Rule: static-analysis skill: FTA > 60 and cyclomatic complexity > 20 are strong flags; tangle-ui review checklist: flag readability/component-size regressions and split large mode-switch