diff --git a/browser_tests/tests/agent/agentOnboarding.spec.ts b/browser_tests/tests/agent/agentOnboarding.spec.ts index bc6b9f6b0ff..d43bf33fbe0 100644 --- a/browser_tests/tests/agent/agentOnboarding.spec.ts +++ b/browser_tests/tests/agent/agentOnboarding.spec.ts @@ -52,6 +52,52 @@ test.describe('Agent onboarding tour', { tag: ['@cloud', '@ui'] }, () => { .toBe('false') }) + test('points the first card at the highlighted panel and answers clicks on it', async ({ + page, + agentFlagEnabled + }) => { + await bootAgentApp(page, agentFlagEnabled, { + onboardingCompleted: false + }) + await new AgentPanel(page).open() + + const firstCard = page.getByRole('dialog', { + name: enMessages.agent.coachTitle + }) + await expect(firstCard).toBeVisible() + const arrow = page.getByTestId('agent-coach-arrow') + const spotlight = page.getByTestId('agent-coach-spotlight') + await expect(arrow).toHaveCSS('visibility', 'visible') + await expect + .poll(async () => { + const [arrowBox, spotlightBox] = await Promise.all([ + arrow.boundingBox(), + spotlight.boundingBox() + ]) + if (!arrowBox || !spotlightBox) return null + return { + leftOfSpotlight: arrowBox.x < spotlightBox.x, + centersAligned: + Math.abs( + arrowBox.y + + arrowBox.height / 2 - + (spotlightBox.y + spotlightBox.height / 2) + ) < 4 + } + }) + .toEqual({ leftOfSpotlight: true, centersAligned: true }) + + const spotlightBox = await spotlight.boundingBox() + if (!spotlightBox) throw new Error('spotlight has no box') + await page.mouse.click( + spotlightBox.x + spotlightBox.width / 2, + spotlightBox.y + spotlightBox.height / 2 + ) + + await expect(firstCard).toBeFocused() + await expect(firstCard).toBeVisible() + }) + test('replays the tour from the header after it has been completed', async ({ page, agentFlagEnabled diff --git a/src/workbench/extensions/agent/README.md b/src/workbench/extensions/agent/README.md index 67b9f7427c8..bc75c9ca83f 100644 --- a/src/workbench/extensions/agent/README.md +++ b/src/workbench/extensions/agent/README.md @@ -140,6 +140,15 @@ panel, composer, graph and chat history. **Next** advances through the cards; **Done** on the last card, **Skip** on any card and Escape once a card is on screen all dismiss the tour and mark it complete. +A card placed beside its target carries an arrow pointing at it; cards placed +anywhere else never do. The arrow is also hidden when it would not actually +point at the target: when a narrow viewport has shifted the card onto its +target, or when the target's center lies outside the span the arrow can reach +along the card's edge. The rest of the +screen, the highlighted area included, does not respond while a card is up; a +click there briefly outlines the card and moves focus to it +so the user finds the controls instead of clicking the highlight. + Completion is device-local in `localStorage`, scoped to the authenticated user and active workspace; with either unresolved there is no scope to record, so no tour is shown at all. It does not sync through Global Settings. A different diff --git a/src/workbench/extensions/agent/components/agent/OnboardingCoach.test.ts b/src/workbench/extensions/agent/components/agent/OnboardingCoach.test.ts index ceaf45018c3..2be803fff44 100644 --- a/src/workbench/extensions/agent/components/agent/OnboardingCoach.test.ts +++ b/src/workbench/extensions/agent/components/agent/OnboardingCoach.test.ts @@ -51,6 +51,7 @@ const rectangles: Record = { history: new DOMRect(970, 104, 24, 24) } const tooltipRect = new DOMRect(998, 105, 84, 22) +const ARROW_SIZE = 12 function mount(steps = STEPS) { return render( @@ -79,6 +80,8 @@ beforeEach(() => { vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation( function (this: HTMLElement) { if (this.getAttribute('role') === 'tooltip') return tooltipRect + if (this.dataset.testid === 'agent-coach-arrow') + return new DOMRect(0, 0, ARROW_SIZE, ARROW_SIZE) return ( rectangles[this.id] ?? new DOMRect( @@ -230,6 +233,136 @@ describe('OnboardingCoach', () => { } }) + it.for(STEPS.filter((step) => step.placement !== 'graph-bottom'))( + 'points the $placement card arrow at the middle of its target', + async (step) => { + mount([step]) + const dialog = await screen.findByRole('dialog', { name: step.title }) + const arrow = screen.getByTestId('agent-coach-arrow') + const targetRect = rectangles[step.target.slice(1)] + + expect(dialog).toContainElement(arrow) + await waitFor(() => + expect( + parseFloat(dialog.style.top) + + parseFloat(arrow.style.top) + + ARROW_SIZE / 2 + ).toBeCloseTo(targetRect.top + targetRect.height / 2, 0) + ) + expect(arrow).not.toHaveStyle({ visibility: 'hidden' }) + } + ) + + it('draws no arrow on the canvas card, which sits on its target', async () => { + mount([STEPS[2]]) + await screen.findByRole('dialog', { name: STEPS[2].title }) + + expect(screen.queryByTestId('agent-coach-arrow')).toBeNull() + }) + + it('hides the arrow when the target center is outside the arrow reach', async () => { + const panel = rectangles.panel + rectangles.panel = new DOMRect(950, 0, 420, 24) + try { + mount([STEPS[0]]) + const dialog = await screen.findByRole('dialog', { + name: STEPS[0].title + }) + await waitFor(() => expect(dialog.style.opacity).toBe('1')) + expect( + parseFloat(dialog.style.left) + dialog.offsetWidth + ).toBeLessThanOrEqual(rectangles.panel.left) + expect(screen.getByTestId('agent-coach-arrow')).toHaveStyle({ + visibility: 'hidden' + }) + } finally { + rectangles.panel = panel + } + }) + + it('keeps the arrow when a small shift still leaves a gap beside the target', async () => { + const panel = rectangles.panel + rectangles.panel = new DOMRect(330, 60, 420, 700) + try { + mount([STEPS[0]]) + const dialog = await screen.findByRole('dialog', { + name: STEPS[0].title + }) + await waitFor(() => expect(dialog.style.opacity).toBe('1')) + expect(parseFloat(dialog.style.left)).toBe(8) + expect(screen.getByTestId('agent-coach-arrow')).not.toHaveStyle({ + visibility: 'hidden' + }) + } finally { + rectangles.panel = panel + } + }) + + it('draws attention to the card and focuses it when the user clicks the dimmed screen or the highlighted area', async () => { + const user = userEvent.setup() + mount() + const dialog = await screen.findByRole('dialog', { name: STEPS[0].title }) + expect(dialog).not.toHaveAttribute('data-nudged') + + await user.click(screen.getByTestId('agent-coach-scrim')) + + expect(dialog).toHaveAttribute('data-nudged') + expect(dialog).toHaveFocus() + expect(screen.getByRole('dialog', { name: STEPS[0].title })).toBe(dialog) + expect(localStorage.getItem(KEY)).toBe('false') + expect(telemetry().trackAgentOnboardingStep).not.toHaveBeenCalled() + }) + + it('stops drawing attention to the card when the user moves to the next card', async () => { + const user = userEvent.setup() + mount() + await screen.findByRole('dialog', { name: STEPS[0].title }) + await user.click(screen.getByTestId('agent-coach-scrim')) + await user.click(screen.getByRole('button', { name: 'Next' })) + + const second = await screen.findByRole('dialog', { name: STEPS[1].title }) + expect(second).not.toHaveAttribute('data-nudged') + }) + + it('hides the arrow when there is no room beside the target and the card overlaps it', async () => { + const panel = rectangles.panel + rectangles.panel = new DOMRect(100, 60, 1290, 700) + try { + mount([STEPS[0]]) + const dialog = await screen.findByRole('dialog', { + name: STEPS[0].title + }) + await waitFor(() => expect(dialog.style.opacity).toBe('1')) + expect( + parseFloat(dialog.style.left) + dialog.offsetWidth + ).toBeGreaterThan(rectangles.panel.left) + expect(screen.getByTestId('agent-coach-arrow')).toHaveStyle({ + visibility: 'hidden' + }) + } finally { + rectangles.panel = panel + } + }) + + it('stops drawing attention to the card shortly after the click', async () => { + vi.useFakeTimers() + try { + const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime }) + mount() + const dialog = await screen.findByRole('dialog', { + name: STEPS[0].title + }) + await user.click(screen.getByTestId('agent-coach-scrim')) + expect(dialog).toHaveAttribute('data-nudged') + + await vi.advanceTimersByTimeAsync(2_000) + + expect(dialog).not.toHaveAttribute('data-nudged') + } finally { + vi.useRealTimers() + } + }) + it('shows the target in its hover state with its tooltip inside the spotlight', async () => { const user = userEvent.setup() const steps = STEPS.map((step, index) => diff --git a/src/workbench/extensions/agent/components/agent/OnboardingCoach.vue b/src/workbench/extensions/agent/components/agent/OnboardingCoach.vue index 4f6df60152e..c07aaf53b07 100644 --- a/src/workbench/extensions/agent/components/agent/OnboardingCoach.vue +++ b/src/workbench/extensions/agent/components/agent/OnboardingCoach.vue @@ -1,6 +1,6 @@