Use shadow dom to render the toolbar

[federicobond]

Description

Following the discussion on #2007, I started experimenting with shadow DOM and it turns out it's pretty easy to make it work with the debug toolbar.

Most of the changes are related to getting the correct root for querying elements in JS, and those could be extracted to a separate pull request to make it easy to review the changes specific to shadow DOM.

The only change required for custom panels is that they should access the root debug element via the getDebugElement function in utils.js instead of directly querying #djDebug, and they should perform all element queries from that root.

This change effectively isolates the Debug Toolbar styles from the rest of the page, which would make it easier to implement all sorts of utility classes for more advanced panel styling.

Checklist:

• I have added the relevant tests for this change.
• I have added an item to the Pending section of docs/changes.rst.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
debug_toolbar
toolbar.py
Project Total

This report was generated by python-coverage-comment-action

[tim-schilling]

Oh dang, this was a much simpler implementation than I expected. Thank you @federicobond!

I think we may want to make a mention of how to fetch JS elements in the JavaScript documentation somewhere. I'm going to assume, this will also impact any third-party panels that have some JS that looks for elements in the DOM? That may make things a bit tricky to support backwards compatibility for a version or two 🤔 What do you think?

[federicobond]

@tim-schilling I think we could take this approach:

Phase 1: Update the built-in JS in this version to support both approaches and add a note for custom panel developers to query elements from the root using the new getDebugElement function from utils.js. While we are here, we could add an option for early adopters to opt-in to shadow DOM.

Phase 2: Make Shadow DOM the default but allow users to opt-out if they experience broken custom panels.

This would give panel developers plenty of time to make their panels compatible with a shadow DOM toolbar and allow us to get feedback from early adopters.

[tim-schilling]

I like it. That sounds like it'll work well. I think the last area of concern is CSP. We'll need to do some investigation into that too.

[federicobond]

Cool! I went ahead and wrote some more changes to support opt-in shadow DOM via the USE_SHADOW_DOM setting.

As for CSP, I tested a CSP config with "default-src": [CSP.SELF, CSP.NONCE] which worked correctly with shadow DOM. The way the scripts and styles are loaded does not change whether we are using shadow DOM or not so it makes sense, but I'm not an expert on CSP.

Btw, we might want to get that CSP config into the example app to ease compliance but not sure how we would like to handle older Django versions in CI.

[matthiask]

LGTM. I wonder if we shouldn't flip the default and allow people to opt out? Bugs would probably be the only reason why anyone would want to not use shadow DOM when we support it?

[tim-schilling]

That's a good point @matthiask. I'm good with that.

[federicobond]

It will break any custom panels that use JS, probably, but it's not hard to fix. Should I go ahead and make it the default?

[federicobond]

Rebased and made shadow DOM opt-out instead of opt-in. Should be ready to merge now.

[matthiask]

I think this is good to go except for the note in the changelog and the merge conflicts we now have.

@tim-schilling You submitted a "changes requested" review for an earlier version of this, do you have the time to look at it again?

[tim-schilling]

This doesn't work because the #djDebug selector takes priority. Regardless though, we should call this out in the release notes. The original :root selector won't work after this change.

[tim-schilling]

Right now I'd like to see a few more changes, but I'm happy for someone to push back and say I'm nitpicking. I'll see if I can dismiss the requested changes without approving.

In general, I'm trying to be better about maintaining the changelog for changes. I added a more concrete suggestion for the shadow DOM feature. I think we also want to mention how themeing support will change. It's fine to just say, "Hey if you're using themes, it likely will break. Go read Theme Support to see how to do it now", but phrased better 😁

[codingjoe]

@tim-schilling no let's take the extra minute.

I'd love to deprecate the old solution. Maintaining both will be a nightmare long-term and complexity we don't need. If we can't switch switch confidence, deprecation is the next best thing.

A simple deprecation warnings when the setting is false should do the trick, right?

[federicobond]

Agree we likely don't want to support both long-term. The decision would be between deprecating non-shadow DOM support with the next release or after the dust has settled.

Edit: I can get on board with deprecating it this release.

[tim-schilling]

The decision would be between deprecating non-shadow DOM support with the next release or after the dust has settled.

I'd lean towards not deprecating this release (let's get this out the door), but it's a slight preference. If someone wants to spend the time doing the work to deprecate it now, that's fine.

I think we should use a major version number change for this PR though because we're breaking theme support and making a significant change to the tool.

[codingjoe]

IMHO, if we know now that we want to remove it. Telling the community early seems preferable to me. We can still decide to deprecate targeting the next-next major release but still announce it now, right?

[tim-schilling]

Thank you for your work on this @federicobond!