Skip to content

🙌 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.ts
index 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.ts
index 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 () => {
// Arrange
await 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 () => {
// Arrange
const renderPopover = () => {
diff --git a/src/components/features/setup-guide/tour/setup-guide-tour.ts b/src/components/features/setup-guide/tour/setup-guide-tour.ts
index 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.ts
index 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.css
index 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.ts
index 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.json
index 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",