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 added 1 commit 2026-08-12 19:54:45 +00:00

Start the inbox tour only once the banners above it have settled ... 65d073147b

The coach-marks are anchored to live elements, so a banner that mounts above
them afterwards drags the open bubble down the page. The banners App.vue
renders above the router view hang off /api/auth/me and /api/accounts, so hold
the tour until both queries have settled; the retention banner already lands
with the settings query that the tour hint itself waits for.

Closes #289

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 added 1 commit 2026-08-12 22:12:47 +00:00

Keep a click beside a coach-mark from ending the inbox tour ... cd7a5285ce

NLDD closes a callout with reason 'ignored' when the click lands next to it.
Waggle mapped that to ending the tour, which marks the hint seen: one stray
click and the tour was gone for good, taking the demo card with it, so nothing
on screen explained what had happened.

Put the same step back instead, and leave the counter alone. Stepping the tour
along on 'ignored' is wrong the other way round: every stray click walks it
forward, and step 4 opens the card modal over whatever the user was doing -
measured, and it is what the attachments-lightbox spec tripped over.

That spec stubs GET /api/settings without hints_seen, so every hint read as
unseen and the tour ran through the whole file; it only passed because the
first stray click destroyed the tour. The stub now carries hints_seen.

robbertbos added 1 commit 2026-08-13 06:46:54 +00:00

Let the inbox tour follow the user into a card, and stop counting stray closes ... 63b87ce0fd

A card list mounts a coach-mark per row - a card list of 25 carries 50 of them,
all inactive but the tour's own. NLDD fires nldd-close on those too, so a single
click produced a burst of them and the tour counted every one: it raced through
its steps, opened the demo card on the way and dismissed itself at the end. Hint
now stays quiet unless it is the active coach-mark, which is the right rule for
every consumer, not only the tour.

Steps 1-3 live in the list and 4-7 inside the card, so the tour also has to
follow the user across that line. Opening a card of your own on step 2 left the
tour with nothing on screen while the skip button still said it was running;
now the tour moves to the in-card steps, and closing the card puts it back on
the step that invites you in.

robbertbos added 1 commit 2026-08-13 07:56:13 +00:00

Light the in-card tour steps after the dialog, not before it ... 247b575ccf

A coach-mark and the card modal both live in the top layer, where the element
promoted last paints on top. The tour lit its in-card step in the same tick as
it opened the card, so the callout was promoted first and the dialog covered it:
present, visible to every locator, and invisible to the user until something
re-promoted it - one Tab did, which is how this was spotted.

Modal already emits `open` after nldd-window's showModal(), so gate the in-card
steps on that. The e2e asserts it with elementFromPoint at the callout's centre;
toBeVisible() passes either way and would not have caught this.

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.