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

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

[camielvs]

🤖 This is an AI-generated code review comment.

const observer = new MutationObserver(update);
observer.observe(document.body, { childList: true, subtree: true });

update() runs document.querySelectorAll(sel) for every ring selector on every childList mutation anywhere in the document. In the v2 editor, ReactFlow adds/removes node DOM as the user pans/zooms/edits — i.e. during exactly the interactions a ring step accompanies — so this re-queries the whole tree in bursts.

Suggestion: coalesce into a single requestAnimationFrame (the same rAF-guard pattern followWindowPosition already uses in this file) so a burst of mutations triggers at most one update() per frame, and optionally narrow the observed root from document.body to the editor container.

[camielvs]

🤖 This is an AI-generated code review comment.

return spec.tasks.some((task) =>
  task.arguments.some(
    (arg) => arg.name === targetArgumentName && ... ,
  ),
);

This scans all tasks, so if two tasks expose an argument with the same name, setting it on the wrong task still satisfies the step. This is the same class of issue raised on #2299 for select-task — which you fixed here by checking data-task-name; set-argument still lacks a task qualifier, and TourStep already carries targetTaskName.

If set-argument steps target a specific task, restrict the .some to the task whose name matches step.targetTaskName (when present). If matching any task is intentional, a one-line comment would keep it from reading as an oversight.

[camielvs]

🤖 This is an AI-generated code review comment.

Each new event handler casts event.target as Element | null and then calls .closest(...) / .matches(...) on it (here and at lines 372 and 442). Per typescript-standards, prefer a narrowing guard over as:

if (event.target instanceof Element && event.target.closest(selector)) { ... }

Since the pattern now repeats across four+ handlers in this file, a small shared helper — e.g. closestFromEvent(event, selector) returning Element | null — would remove the cast everywhere and read cleaner. Low priority.