🙌 OpenHands: AI-Driven Development
fix(onboarding): keep the setup tour off other dialogs and start the MCP tour at the library (#18261)
Hiep Le00318e730138
diff --git a/__tests__/components/features/setup-guide/setup-guide-tour.test.ts b/__tests__/components/features/setup-guide/setup-guide-tour.test.tsindex 73e39524e1..1ef897c384 100644--- a/__tests__/components/features/setup-guide/setup-guide-tour.test.ts+++ b/__tests__/components/features/setup-guide/setup-guide-tour.test.ts@@ -54,7 +54,7 @@ describe("setup guide tours", () => {},);- it("hides the footer only on the stop that waits for a template card", async () => {+ it("hides the footer only on the stops that wait for a card in a list", async () => {await startSetupGuideTour("first-automation", NAV, t);await startSetupGuideTour("add-integration", NAV, t);@@ -63,7 +63,7 @@ describe("setup guide tours", () => {.mock.calls.flatMap(([tour]) => tour.stops);expect(stops.filter((stop) => stop.hideFooter).map((stop) => stop.id),- ).toEqual(["choose-template"]);+ ).toEqual(["choose-template", "pick-server"]);});it("starts nothing for a step done in the enterprise app", async () => {diff --git a/__tests__/components/features/setup-guide/tour-engine.test.ts b/__tests__/components/features/setup-guide/tour-engine.test.tsindex a58dd6f1a1..275fb4f55e 100644--- a/__tests__/components/features/setup-guide/tour-engine.test.ts+++ b/__tests__/components/features/setup-guide/tour-engine.test.ts@@ -73,9 +73,16 @@ describe("startGuidedTour", () => {afterEach(() => {stopGuidedTour();+ vi.useRealTimers();document.body.innerHTML = "";});+ const pickThenDialog = () =>+ tour(+ stop({ id: "pick", advanceOnClick: "#card" }),+ stop({ id: "dialog", anchor: "#dialog" }),+ );+it("ends the tour when the step its last stop waits for succeeds", async () => {// Arrangeawait startGuidedTour(@@ -136,6 +143,91 @@ describe("startGuidedTour", () => {await waitFor(() => expect(drivers[0].moveTo).toHaveBeenCalledWith(1));});+ it("hides while a click opens something else first, then shows the next stop once its element appears", async () => {+ // Arrange+ await startGuidedTour(pickThenDialog(), NAV, LABELS);+ await wait(60);++ // Act: the click opens a choice first, so the next stop's dialog is late.+ document.getElementById("card")!.click();+ await wait(1_400);++ // Assert: the tour is hidden and not marked active, so the setup guide+ // can show; nothing has moved yet.+ expect(document.body).toHaveClass("oh-setup-tour-waiting");+ expect(isGuidedTourActive()).toBe(false);+ expect(drivers[0].moveTo).not.toHaveBeenCalled();++ // Act+ document.body.insertAdjacentHTML("beforeend", '<div id="dialog"></div>');++ // Assert+ await waitFor(() => expect(drivers[0].moveTo).toHaveBeenCalledWith(1));+ expect(document.body).not.toHaveClass("oh-setup-tour-waiting");+ expect(isGuidedTourActive()).toBe(true);+ });++ it("ends the tour when the next stop's element never appears", async () => {+ // Arrange+ vi.useFakeTimers();+ await startGuidedTour(pickThenDialog(), NAV, LABELS);+ await vi.advanceTimersByTimeAsync(60);++ // Act: the admin went another way, so the dialog never opens.+ document.getElementById("card")!.click();+ await vi.advanceTimersByTimeAsync(61_000);++ // Assert: never shown away from its element.+ expect(drivers[0].moveTo).not.toHaveBeenCalled();+ expect(drivers[0].destroy).toHaveBeenCalledTimes(1);+ expect(document.body).not.toHaveClass("oh-setup-tour-waiting");+ expect(isGuidedTourActive()).toBe(false);+ });++ it("lets Tab move through the page, not the hidden tour, while it waits", async () => {+ // Arrange: driver.js keeps Tab in its stop with a listener on window.+ const tourTabListener = vi.fn();+ window.addEventListener("keydown", tourTabListener);+ const pressTab = () =>+ document.body.dispatchEvent(+ new KeyboardEvent("keydown", { key: "Tab", bubbles: true }),+ );+ await startGuidedTour(pickThenDialog(), NAV, LABELS);+ await wait(60);++ try {+ // Act+ document.getElementById("card")!.click();+ await wait(350);+ pressTab();+ stopGuidedTour();+ pressTab();++ // Assert+ expect(tourTabListener).toHaveBeenCalledTimes(1);+ } finally {+ window.removeEventListener("keydown", tourTabListener);+ }+ });++ it("does not start when the first stop's element is missing", async () => {+ // Arrange+ vi.useFakeTimers();++ // Act+ const started = startGuidedTour(+ tour(stop({ anchor: "#missing" })),+ NAV,+ LABELS,+ );+ await vi.advanceTimersByTimeAsync(6_000);+ await started;++ // Assert: driver.js would float the popover over the page.+ expect(drivers).toHaveLength(0);+ expect(isGuidedTourActive()).toBe(false);+ });+it("hides the popover footer only on a stop that asks for it", async () => {// Arrangeconst renderPopover = () => {diff --git a/src/components/features/setup-guide/tour/setup-guide-tour.ts b/src/components/features/setup-guide/tour/setup-guide-tour.tsindex b0197fe511..eafc244ff2 100644--- a/src/components/features/setup-guide/tour/setup-guide-tour.ts+++ b/src/components/features/setup-guide/tour/setup-guide-tour.ts@@ -41,16 +41,18 @@ const SETUP_GUIDE_TOUR_STOPS: Partial<],"add-integration": [{- id: "add-custom-server",- anchor: '[data-testid="mcp-add-custom-server"]',- nextClicksAnchor: true,+ id: "pick-server",+ anchor: '[data-testid="mcp-marketplace-section"]',+ // A card and its add button both open the server's install dialog.+ advanceOnClick: '[data-testid^="mcp-marketplace-card-"]',+ hideFooter: true,title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_TITLE,body: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_BODY,- side: "bottom",+ side: "top",},{id: "connect-server",- anchor: '[data-testid="mcp-custom-editor"]',+ anchor: '[data-testid="mcp-install-modal"]',waitForComplete: "add-integration",interactive: true,title: I18nKey.ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_TITLE,diff --git a/src/components/features/setup-guide/tour/tour-engine.ts b/src/components/features/setup-guide/tour/tour-engine.tsindex fed92bb40b..302c0a7813 100644--- a/src/components/features/setup-guide/tour/tour-engine.ts+++ b/src/components/features/setup-guide/tour/tour-engine.ts@@ -17,6 +17,16 @@ import "./tour-theme.css";/** On `<body>` while the current stop keeps the whole page usable. */const INTERACTIVE_STOP_CLASS = "oh-setup-tour-interactive";+/** On `<body>` while the tour is hidden, looking for the next stop's element. */+const WAITING_CLASS = "oh-setup-tour-waiting";++/**+ * How long a stop reached by a click may take to appear. The click can open+ * something else first, such as a choice of setup or an install dialog, and+ * the admin may take a while there.+ */+const NEXT_STOP_TIMEOUT_MS = 60_000;+export interface GuidedTourNavigation {navigate: (to: string) => void;/** The current route, relative to the app's base path. */@@ -65,6 +75,24 @@ function setInteractive(stop: GuidedTourStop | undefined): void {);}+// driver.js keeps Tab inside the stop it last showed, with a listener on+// `window`. While the tour is hidden, Tab should move through what the click+// opened instead, so it is stopped on `document` first.+function keepTabOutOfHiddenTour(event: KeyboardEvent): void {+ if (event.key === "Tab") {+ event.stopPropagation();+ }+}++function setWaiting(waiting: boolean): void {+ document.body.classList.toggle(WAITING_CLASS, waiting);+ if (waiting) {+ document.addEventListener("keydown", keepTabOutOfHiddenTour);+ } else {+ document.removeEventListener("keydown", keepTabOutOfHiddenTour);+ }+}+function queryFirst(selector: string): Element | null {const parts = selector.split(",").map((part) => part.trim());for (const part of parts) {@@ -76,9 +104,12 @@ function queryFirst(selector: string): Element | null {return null;}-async function resolveAnchor(selector: string): Promise<Element | null> {+async function resolveAnchor(+ selector: string,+ timeoutMs: number,+): Promise<Element | null> {// A stop reached by a click (a new route, a dialog) can take a moment.- for (let attempt = 0; attempt < 50; attempt += 1) {+ for (let attempt = 0; attempt * 100 < timeoutMs; attempt += 1) {const el = queryFirst(selector);if (el) {el.scrollIntoView({ block: "nearest", inline: "nearest" });@@ -111,13 +142,14 @@ function sideFor(el: Element, requested?: GuidedTourSide): GuidedTourSide {async function prepareStop(stop: GuidedTourStop,nav: GuidedTourNavigation,+ timeoutMs = 5_000,): Promise<Element | null> {if (stop.route && nav.getPath() !== stop.route) {nav.navigate(stop.route);// The route's page needs a beat before its anchors exist.await wait(400);}- const el = await resolveAnchor(stop.anchor);+ const el = await resolveAnchor(stop.anchor, timeoutMs);if (el) {resolvedAnchors.set(stop.id, el);} else {@@ -137,6 +169,7 @@ export function stopGuidedTour(): void {tourGeneration += 1;clearSetupStepListener();setInteractive(undefined);+ setWaiting(false);activeDriver?.destroy();activeDriver = null;resolvedAnchors.clear();@@ -156,8 +189,10 @@ export async function startGuidedTour(if (stops.length === 0) {return;}- await prepareStop(stops[0], nav);- if (!isCurrent()) {+ // A stop is only ever shown on its element: without one, driver.js would+ // float the popover over whatever is on the page.+ const firstAnchor = await prepareStop(stops[0], nav);+ if (!isCurrent() || !firstAnchor) {return;}@@ -192,10 +227,26 @@ export async function startGuidedTour(}clearSetupStepListener();tourCtl.clearAnchorClickHandler();- await prepareStop(nextStop, nav);+ // Hide the tour while the next stop's element is looked for, so it+ // covers nothing the click opened first and the page stays usable. A+ // longer wait also lets the setup guide show again meanwhile.+ setWaiting(true);+ const markIdle = window.setTimeout(() => {+ if (isCurrent()) setTourActive(false);+ }, 1_000);+ const anchor = await prepareStop(nextStop, nav, NEXT_STOP_TIMEOUT_MS);+ window.clearTimeout(markIdle);if (!isCurrent()) {return;}+ setWaiting(false);+ if (!anchor) {+ // The flow went elsewhere, e.g. the admin chose the built-in+ // integration or a template that starts a conversation.+ instanceApi.destroy();+ return;+ }+ setTourActive(true);index = nextIndex;setInteractive(nextStop);instanceApi.moveTo(nextIndex);@@ -232,7 +283,7 @@ export async function startGuidedTour(tourCtl.bindWaitForComplete(instanceApi);const current = stops[index];const anchor = current && resolvedAnchors.get(current.id);- if (!anchor || (!current.nextClicksAnchor && !current.advanceOnClick)) {+ if (!anchor || !current.advanceOnClick) {return;}anchorClickHandler = (event: Event) => {@@ -304,13 +355,6 @@ export async function startGuidedTour(return;}tourCtl.clearAnchorClickHandler();- if (current?.nextClicksAnchor) {- const anchor = resolvedAnchors.get(current.id);- if (anchor instanceof HTMLElement) {- anchor.click();- await wait(280);- }- }await tourCtl.advanceFrom(instanceApi, index + 1);},onPrevClick: async (_el, _step, { driver: instanceApi }) => {@@ -320,10 +364,14 @@ export async function startGuidedTour(}clearSetupStepListener();tourCtl.clearAnchorClickHandler();- await prepareStop(prevStop, nav);+ const anchor = await prepareStop(prevStop, nav);if (!isCurrent()) {return;}+ if (!anchor) {+ instanceApi.destroy();+ return;+ }index -= 1;setInteractive(prevStop);instanceApi.movePrevious();@@ -345,6 +393,7 @@ export async function startGuidedTour(}clearSetupStepListener();setInteractive(undefined);+ setWaiting(false);activeDriver = null;resolvedAnchors.clear();setTourActive(false);diff --git a/src/components/features/setup-guide/tour/tour-theme.css b/src/components/features/setup-guide/tour/tour-theme.cssindex c56e8b5ff8..5b728908b1 100644--- a/src/components/features/setup-guide/tour/tour-theme.css+++ b/src/components/features/setup-guide/tour/tour-theme.css@@ -179,3 +179,20 @@[data-agent-server-ui].oh-setup-tour-interactive.driver-active * {pointer-events: auto;}++/*+ * While the tour looks for the next stop's element (a click opened a choice+ * or a dialog first), it shows nothing and the whole page stays usable.+ */+[data-agent-server-ui].oh-setup-tour-waiting .driver-overlay {+ display: none;+}++/* driver.js shows the popover with an inline `display: block`. */+[data-agent-server-ui].oh-setup-tour-waiting .driver-popover {+ display: none !important;+}++[data-agent-server-ui].oh-setup-tour-waiting.driver-active * {+ pointer-events: auto;+}diff --git a/src/components/features/setup-guide/tour/tour-types.ts b/src/components/features/setup-guide/tour/tour-types.tsindex bffdc104de..dd104b3db2 100644--- a/src/components/features/setup-guide/tour/tour-types.ts+++ b/src/components/features/setup-guide/tour/tour-types.ts@@ -14,8 +14,6 @@ export interface GuidedTourStop {title: string;body: string;side?: GuidedTourSide;- /** Next clicks the anchor first, e.g. to open a form from its button. */- nextClicksAnchor?: boolean;/*** Hide Next; move on when the admin clicks an element matching this* selector inside the anchor, such as one template card in a list.diff --git a/src/i18n/translation.json b/src/i18n/translation.jsonindex fa694508f4..5a48c51acf 100644--- a/src/i18n/translation.json+++ b/src/i18n/translation.json@@ -43401,21 +43401,21 @@"uk": "Додайте MCP-сервер"},"ONBOARDING$SETUP_GUIDE_TOUR_MCP_ADD_BODY": {- "en": "Add a custom server here. To install one from the list instead, close this tour.",- "ja": "ここでカスタムサーバーを追加します。一覧からインストールする場合は、このツアーを閉じてください。",- "zh-CN": "在这里添加自定义服务器。如果想从列表中安装,请关闭此导览。",- "zh-TW": "在這裡新增自訂伺服器。若想從清單中安裝,請關閉此導覽。",- "ko-KR": "여기에서 사용자 지정 서버를 추가하세요. 목록에서 설치하려면 이 투어를 닫으세요.",- "no": "Legg til en egendefinert server her. Lukk denne omvisningen for å installere en fra listen i stedet.",- "ar": "أضف خادمًا مخصصًا من هنا. لتثبيت خادم من القائمة بدلًا من ذلك، أغلق هذه الجولة.",- "de": "Fügen Sie hier einen eigenen Server hinzu. Um stattdessen einen aus der Liste zu installieren, schließen Sie diese Tour.",- "fr": "Ajoutez ici un serveur personnalisé. Pour en installer un depuis la liste, fermez cette visite.",- "it": "Aggiungi qui un server personalizzato. Per installarne uno dall'elenco, chiudi questo tour.",- "pt": "Adicione aqui um servidor personalizado. Para instalar um da lista, feche este tour.",- "es": "Añade aquí un servidor personalizado. Para instalar uno de la lista, cierra este recorrido.",- "ca": "Afegeix aquí un servidor personalitzat. Per instal·lar-ne un de la llista, tanca aquest recorregut.",- "tr": "Buradan özel bir sunucu ekleyin. Bunun yerine listeden yüklemek için bu turu kapatın.",- "uk": "Додайте тут власний сервер. Щоб натомість установити сервер зі списку, закрийте цей тур."+ "en": "Pick a server from the library to set it up.",+ "ja": "ライブラリからサーバーを選んで設定します。",+ "zh-CN": "从库中选择一个服务器进行设置。",+ "zh-TW": "從資料庫中選擇一個伺服器進行設定。",+ "ko-KR": "라이브러리에서 서버를 선택해 설정하세요.",+ "no": "Velg en server fra biblioteket for å sette den opp.",+ "ar": "اختر خادمًا من المكتبة لإعداده.",+ "de": "Wählen Sie einen Server aus der Bibliothek aus, um ihn einzurichten.",+ "fr": "Choisissez un serveur dans la bibliothèque pour le configurer.",+ "it": "Scegli un server dalla libreria per configurarlo.",+ "pt": "Escolha um servidor da biblioteca para configurá-lo.",+ "es": "Elige un servidor de la biblioteca para configurarlo.",+ "ca": "Tria un servidor de la biblioteca per configurar-lo.",+ "tr": "Kurmak için kütüphaneden bir sunucu seçin.",+ "uk": "Виберіть сервер у бібліотеці, щоб налаштувати його."},"ONBOARDING$SETUP_GUIDE_TOUR_MCP_FORM_TITLE": {"en": "Connect the server",