Skip to content

feat(tours): target elements inside open shadow roots - #222

Merged
floooat merged 1 commit into
masterfrom
shadow-dom-tours
Nov 17, 2026
Merged

floooat merged 1 commit into
masterfrom
shadow-dom-tours

Conversation

@floooat

@floooat floooat commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Why

Apps mounted inside a shadow root (Vue defineCustomElement, Lit, a manual attachShadow mount) could not be targeted by product tours. Selectors are resolved with document.querySelector, which stops at the shadow boundary, and the picker only ever saw the shadow host, so every element inside picked as one.

What

  • Selectors: host >>> inner continues inside the open shadow root of host, nested roots included. Handled in GleapSafeSelector, so tours, co-browse tours, the builder and tooltips resolve it. Plain selectors behave as before.
  • Picker: hit-testing looks through open shadow roots to the real element and stores a host >>> inner selector. A data-gleap-tour anchor inside a shadow root gets the host prefix too.
  • Interaction lockout: the lockout rules live in the document stylesheet and do not reach into a shadow root (the host's pointer-events: none is inherited instead). For an active element inside one, the same rule is applied inline and restored afterwards.
  • Click to continue: the click check uses the event's composed path, since event.target is retargeted to the host.
  • Builder highlight: the red ring for the selected step is applied inline for shadow elements.
  • Fix: the tour's document click listener was added with capture: true but removed without it, so it was never removed. A second tour in the same page load advanced two steps per click.

Verification

  • npx jest: 767 tests pass, 8 of them new (src/GleapShadowSelector.test.js).
  • Browser, on the new demo/shadow-dom.html: a three-step tour highlights each element, advances on a real click in a CLICK step, ignores clicks elsewhere in the widget, and cleans up classes and inline styles on close.
  • Not exercised end to end: the picker inside a tour builder session (only its hit-testing was checked in the browser).

Not covered

  • Closed shadow roots and iframes stay unreachable.
  • The tooltip manager's mutation observer does not watch inside shadow roots, so tooltips there are not guaranteed to attach.
  • The dashboard rejects >>> in its selector validation; that is a separate PR in the dashboard repo.

🤖 Generated with Claude Code

Tour and tooltip selectors can continue inside a shadow root with
`host >>> inner`. The picker looks through shadow roots and stores such a
selector, and the highlight, interaction lockout and click-to-continue
handling work for an element inside one.

Also removes the tour's document click listener with the capture flag it was
added with; it was never removed, so a second tour in the same page load
advanced two steps per click.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@floooat
floooat merged commit 0296b6b into master Nov 17, 2026
1 check passed
@floooat floooat mentioned this pull request Nov 18, 2026
@TobiasDuelli
TobiasDuelli deleted the shadow-dom-tours branch November 18, 2026 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants