Intent to Deprecate and Remove: Deprecate the includeShadowRoots argument on DOMParser

[Mason Freed]

Contact emails

mas...@chromium.org

Explainer

None

Specification

https://github.com/whatwg/html/pull/10139

Summary

The includeShadowRoots argument was a never-standardized argument to the DOMParser.parseFromString() function, which was there to allow imperative parsing of HTML content that contains declarative shadow DOM. This was shipped in M90 [1] as part of the initial shipment of declarative shadow DOM. Since the standards discussion rematerialized in 2023, the shape of DSD APIs changed, including this feature for imperative parsing. (See [2] for more context on the standards situation and recent changes, and see [3] and [4] for other related deprecations.) Now that a standardized version of this API, in the form of setHTMLUnsafe() and parseHTMLUnsafe() will ship in M124 ([5]), the non-standard includeShadowRoots argument needs to be deprecated and removed. All usage should shift accordingly: Instead of: (new DOMParser()).parseFromString(html,'text/html',{includeShadowRoots: true}); this can be used instead: document.parseHTMLUnsafe(html); [1] https://chromestatus.com/feature/5191745052606464 [2] https://chromestatus.com/feature/5161240576393216 [3] https://chromestatus.com/feature/5081733588582400 [4] https://chromestatus.com/feature/6239658726391808 [5] https://chromestatus.com/feature/6560361081995264

Blink component

Blink>DOM>ShadowDOM

Motivation

Now that there is a standardized version of this API, it makes sense to remove the non-standard, Chrome-only version of the API.

Initial public proposal

None

TAG review

None

TAG review status

Not applicable

Risks

Interoperability and Compatibility

Because this is a removal of an API, there is some compat risk if sites use the API without feature detection. Additionally, feature detection is a bit difficult for this feature directly, and typical usage would instead feature-detect the old `shadowroot` attribute. In that case, there should be no breakage, since that attribute has since been removed. The use counter [1] for this feature has unfortunately had a recent spike in usage, peaking at just over 0.01% of page loads as of March, 2024. However, I analyzed 8 of the top sites, and 8 of 8 are due to the exact same code snippet, from AstroJS/Lit [2]. And that code amounts to feature detection, which as-written will properly detect the lack of `includeShadowRoots` and fall back to other behavior. This, plus the lack of support in other browsers, makes me less concerned about the compat risk here. [1] https://chromestatus.com/metrics/feature/timeline/popularity/4455 [2] https://github.com/withastro/astro/blob/main/packages/integrations/lit/client-shim.js

Gecko: No signal

WebKit: No signal

Web developers: No signals

Other signals:

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

None

Debuggability

None

Is this feature fully tested by web-platform-tests?

Yes

Tested via this WPT: https://wpt.fyi/results/shadow-dom/declarative/declarative-shadow-dom-opt-in.html which fails because `includeShadowRoots` is non-standard. This is the only test failing within the Interop2024 Declarative Shadow DOM section, due to this deprecation not being completed yet.

Flag name on chrome://flags

Finch feature name

None

Non-finch justification

None

Requires code in //chrome?

False

Estimated milestones

Shipping on desktop	129
DevTrial on desktop	125

Shipping on Android	129
DevTrial on Android	125

Shipping on WebView

129

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5116094370283520

This intent message was generated by Chrome Platform Status.

[Mike Taylor]

Hi Mason,

Would you mind requesting reviews for the various shipping gates (privacy, security, enterprise, etc.) in your chromestatus entry?

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAM%3DNeDhoX1h-FiR6p9tjuOCxhb1iXVciuQ%2BH4%3DHnzdb9M4rGKQ%40mail.gmail.com.

[Mason Freed]

On Tue, Mar 19, 2024 at 1:44 PM Mike Taylor <mike...@chromium.org> wrote:

Hi Mason,

Would you mind requesting reviews for the various shipping gates (privacy, security, enterprise, etc.) in your chromestatus entry?

Definitely! But I only need to do that before I ship this, right? I.e. not required yet, while I’m just deprecating but not yet removing the feature?

Thanks,

Mason

[Daniel Bratell]

I don't think we, in general, want open ended deprecations. Nowadays they are a bit more hidden in DevTools, but they used to be a source of console spam and cause warning fatigue. Many also don't react to deprecations unless there is some kind of timeline so I really prefer there to be a set point in the future where we plan to remove something.

I will also admit to being a bit mislead by the way chromestatus generates mail titles, thinking you had already planned for a removal.

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAM%3DNeDjAZX70dA6rRjASo%3D70sPstaGn4WJEyMrQud0PdFG8Gug%40mail.gmail.com.

[Philip Jägenstedt]

We indeed try to avoid open ended deprecation warnings with no planned milestone for removal.

Given that the usage is still low (~0.01%) and that you found 8/8 sites analyzed were doing feature detection, this seems fairly low risk. I presume it's OK to gate this removal behind a flag, so that we have a kill switch (revive switch?) in case we see breakage? In that case, I think we should skip deprecation and just attempt removal.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/66900d83-e291-4a49-a132-aa6fbbb5b04b%40gmail.com.

[Mike Taylor]

On 3/19/24 6:51 PM, Mason Freed wrote:

On Tue, Mar 19, 2024 at 1:44 PM Mike Taylor <mike...@chromium.org> wrote:

Hi Mason,

Would you mind requesting reviews for the various shipping gates (privacy, security, enterprise, etc.) in your chromestatus entry?

Definitely! But I only need to do that before I ship this, right? I.e. not required yet, while I’m just deprecating but not yet removing the feature?

We discussed this in our owners meeting today, and we think it's probably useful to go ahead and do that now - Enterprise in particular would probably be very interested in knowing about a deprecation. And for the rest if you think they're N/A, it's not much work to request that.

[Mason Freed]

Thanks for the comments, and sorry for the confusion. The chromestatus tool, I think, needs a bit of help with deprecations. There are two "Draft Intent to Foobar" links on chromestatus, which for typical launches correspond to "Intent to Prototype" and "Intent to Ship". For deprecations, those are relabeled to "Intent to Deprecate and Remove" and "Intent to Ship", respectively. I would have thought that the first should correspond to "deprecation" and the second to "removal". In this case, I clicked the first, and my intention was to announce that this property is being deprecated. My plan (listed on chromestatus and my original email here) is to deprecate in M125, and remove in 129, so definitely not an open-ended deprecation. In a past deprecation, I renamed the email to just "Intent to Deprecate" and that messed with the chromestatus tooling, so I've learned not to touch the email titles the tool gives me.

Help me understand what I did wrong here.

> Given that the usage is still low (~0.01%) and that you found 8/8 sites analyzed were doing feature detection, this seems fairly low risk. I presume it's OK to gate this removal behind a flag, so that we have a kill switch (revive switch?) in case we see breakage? In that case, I think we should skip deprecation and just attempt removal.

I'd like to give it a bit of time (just to M129), mostly because the replacement API (parseHTMLUnsafe()) only shipped in M124.

> We discussed this in our owners meeting today, and we think it's probably useful to go ahead and do that now - Enterprise in particular would probably be very interested in knowing about a deprecation. And for the rest if you think they're N/A, it's not much work to request that.

Ok, that's a very good point - I'll do that now.

Thanks,

Mason

[Philip Jägenstedt]

LGTM1 to remove without deprecation

I looked through all 24 sites listed in https://chromestatus.com/metrics/feature/timeline/popularity/4455. 23 of them are the code from client-shim.js minified in various ways, and one site no longer has includeShadowRoots.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/ed23f647-4779-4a1a-a7d9-5a6447ae099d%40chromium.org.

[Mason Freed]

On Wed, Mar 20, 2024 at 9:54 AM Philip Jägenstedt <foo...@chromium.org> wrote:

LGTM1 to remove without deprecation

Cool, ok! If I get two more of those, then I'll go ahead with the removal. I'd still like to take it slowly and carefully, so I think I'd roll it out via Finch over a milestone or two. But if that's what the API owners prefer, that's fine by me.

 

I looked through all 24 sites listed in https://chromestatus.com/metrics/feature/timeline/popularity/4455. 23 of them are the code from client-shim.js minified in various ways, and one site no longer has includeShadowRoots.

Wow, thanks for doing that work. I'm glad the subsequent 16 sites looked just like the top 8. As a side-note to that, I reached out to someone who is putting up a PR against client-shim.js to move to the new/correct feature detection. It sounded like in the next few days, maybe.

Thanks,

Mason

[Daniel Bratell]

(resending to list)

LGTM2 to go directly to removal (with a flag of course). Also, keep an eye on enterprise feedback since they are a blind area.

I took a look at code in github, and there was mostly just documentation, including the Portuguese chrome.com, and I also saw a page from someone named mfreednumber. Hmm.

/Daniel

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAARdPYeXL6xj0oUcAyCaGzgcW%2Btkg%3DGR2i7tMr%3Duxw%2Be6bMLqQ%40mail.gmail.com.

[Chris Harrelson]

LGTM3

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/a1dbd108-c4fc-4d61-b038-4e1b32ce99d2%40gmail.com.