Keep the inbox tour on screen and in step with the user #298

Merged

robbertbos merged 1 commit from tour-waits-for-async-banners into main 2026-08-13 09:23:22 +00:00

Conversation 0 Commits 1 Files changed 8 +370 -18

robbertbos commented 2026-08-12 19:54:45 +00:00

Owner

Copy link

Closes #289, plus three defects found while testing that fix.

A coach-mark is a top-layer bubble anchored to a live element, which is where all four problems come from.

It started too early. The banners App.vue renders above the router view hang off /api/auth/me and /api/accounts; arriving late, they dragged an open bubble down the page (#289). The tour now waits for both. The retention banner needed nothing - it lands with the settings query tour.active already waits for.

A click beside a callout ended it for good. NLDD reports that as reason ignored, and Waggle mapped it to ending the tour: hint marked seen, demo card gone with it, nothing left on screen to explain what happened. It now puts the same step back and leaves the counter alone. Advancing on it is wrong the other way round - every stray click walks the tour forward, and step 4 opens a card modal over whatever the user was doing.

One click counted as many steps. A card list mounts a coach-mark per row (25 cards = 50 of them, all inactive but the tour's own) and NLDD fires nldd-close on those too. The tour counted each one, raced to the end and dismissed itself. Hint now stays quiet unless it is the active coach-mark - the right rule for every consumer. Steps 1-3 live in the list and 4-7 in the card, so the tour also follows the user across that line instead of leaving the screen blank with the skip button still up.

The in-card steps were painted under the modal. Both live in the top layer, where the last promotion wins, so a step lit before showModal() sat under the dialog - present, visible to every locator, invisible to the user until a Tab re-promoted it. Modal already emits open after showModal(), so that is when they light up.

Testing

• Inbox.test.ts, Hint.test.ts: the tour is held while me/accounts are pending; a click beside the callout keeps its step; a close outside a running tour does nothing; the tour follows the user in and out of a card; an inactive hint stays quiet.
• onboarding-tour-start.spec.ts: delays /api/accounts and asserts the banner is already up when the tour starts; asserts a click beside the callout neither ends nor advances it; asserts the in-card callout is the topmost element via elementFromPoint - toBeVisible() passes either way and would not catch it.
• Each was confirmed red against the behaviour it replaces.
• attachments-lightbox.spec.ts stubbed GET /api/settings without hints_seen, so the tour ran through that whole file and competed for the focus those tests assert on; it only passed because the old code destroyed the tour on the first stray click. The stub now carries hints_seen.

Verified in the browser as well as in CI. Local gates: 1095 vitest, e2e 98 passed / 3 skipped, typecheck, eslint, pre-commit.

Closes #289, plus three defects found while testing that fix. A coach-mark is a top-layer bubble anchored to a live element, which is where all four problems come from. **It started too early.** The banners `App.vue` renders above the router view hang off `/api/auth/me` and `/api/accounts`; arriving late, they dragged an open bubble down the page (#289). The tour now waits for both. The retention banner needed nothing - it lands with the settings query `tour.active` already waits for. **A click beside a callout ended it for good.** NLDD reports that as reason `ignored`, and Waggle mapped it to ending the tour: hint marked seen, demo card gone with it, nothing left on screen to explain what happened. It now puts the same step back and leaves the counter alone. Advancing on it is wrong the other way round - every stray click walks the tour forward, and step 4 opens a card modal over whatever the user was doing. **One click counted as many steps.** A card list mounts a coach-mark per row (25 cards = 50 of them, all inactive but the tour's own) and NLDD fires `nldd-close` on those too. The tour counted each one, raced to the end and dismissed itself. `Hint` now stays quiet unless it is the active coach-mark - the right rule for every consumer. Steps 1-3 live in the list and 4-7 in the card, so the tour also follows the user across that line instead of leaving the screen blank with the skip button still up. **The in-card steps were painted under the modal.** Both live in the top layer, where the last promotion wins, so a step lit before `showModal()` sat under the dialog - present, visible to every locator, invisible to the user until a Tab re-promoted it. `Modal` already emits `open` after `showModal()`, so that is when they light up. ### Testing - `Inbox.test.ts`, `Hint.test.ts`: the tour is held while `me`/`accounts` are pending; a click beside the callout keeps its step; a close outside a running tour does nothing; the tour follows the user in and out of a card; an inactive hint stays quiet. - `onboarding-tour-start.spec.ts`: delays `/api/accounts` and asserts the banner is already up when the tour starts; asserts a click beside the callout neither ends nor advances it; asserts the in-card callout is the topmost element via `elementFromPoint` - `toBeVisible()` passes either way and would not catch it. - Each was confirmed red against the behaviour it replaces. - `attachments-lightbox.spec.ts` stubbed `GET /api/settings` without `hints_seen`, so the tour ran through that whole file and competed for the focus those tests assert on; it only passed because the old code destroyed the tour on the first stray click. The stub now carries `hints_seen`. Verified in the browser as well as in CI. Local gates: 1095 vitest, e2e 98 passed / 3 skipped, typecheck, eslint, pre-commit.

robbertbos force-pushed tour-waits-for-async-banners from 65d073147b to a88fbd23b5 2026-08-12 21:07:57 +00:00 Compare

robbertbos force-pushed tour-waits-for-async-banners from a88fbd23b5 to 4dd85de8be 2026-08-12 21:17:41 +00:00 Compare

robbertbos force-pushed tour-waits-for-async-banners from 4dd85de8be to d0fb45944d 2026-08-12 21:21:54 +00:00 Compare

robbertbos force-pushed tour-waits-for-async-banners from d0fb45944d to 6265a4cb82 2026-08-12 21:22:33 +00:00 Compare

robbertbos force-pushed tour-waits-for-async-banners from 6265a4cb82 to eb8f2a6a27 2026-08-12 21:33:00 +00:00 Compare

robbertbos force-pushed tour-waits-for-async-banners from 247b575ccf to 259656060f 2026-08-13 08:08:21 +00:00 Compare

robbertbos changed title from Start the inbox tour only once the banners above it have settled to Keep the inbox tour on screen and in step with the user 2026-08-13 08:08:51 +00:00

robbertbos force-pushed tour-waits-for-async-banners from 259656060f to 73d44de58d 2026-08-13 09:11:46 +00:00 Compare

robbertbos merged commit d0743861a7 into main 2026-08-13 09:23:22 +00:00

robbertbos deleted branch tour-waits-for-async-banners 2026-08-13 09:23:23 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

help wanted

Need some help

  

invalid

Something is wrong

  

nldd ds

  

question

More information is needed

  

wontfix

This won't be fixed

No labels

bug

duplicate

enhancement

help wanted

invalid

nldd ds

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

robbertbos/waggle!298

No description provided.