Add information to DOMParser.parseFromString page about the includeShadowRoots option

[thescientist13]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString

What specific section or headline is this issue about?

Parameters

What information was incorrect, unhelpful, or incomplete?

Per the Chrome Developer docs, there is reference to a third parameter to parseFromString that handles parsing Declarative Shadow DOM

<script>
  const html = `
    <div>
      <template shadowrootmode="open"></template>
    </div>
  `;
  const div = document.createElement('div');
  div.innerHTML = html; // No shadow root here

  const fragment = new DOMParser().parseFromString(html, 'text/html', {
    includeShadowRoots: true
  }); // Shadow root here
</script>

What did you expect to see?

I would like to see the content expanded to include the third param and some details about the option and why it would be used. For example, the Chrome docs frame it as such:

To avoid some important security considerations, Declarative Shadow Roots also can't be created using fragment parsing APIs like innerHTML or insertAdjacentHTML(). The only way to parse HTML with Declarative Shadow Roots applied is to pass a new includeShadowRoots option to DOMParser:

Do you have any supporting links, references, or citations?

Here is a thread from WHATWG/dom GitHub discussion regarding its participation in the Declarative Shadow DOM spec
whatwg/dom#912 (comment)

Do you have anything more you want to share?

It seems like this might make a good companion to #29600 ?

---

Happy to help contribute to drafting this content if you would like. 👍

[pepelsbey]

Hey! Great idea :) We’re currently documenting shadowrootmode and clonable for the upcoming Firefox 122 release (behind the flag for now, but it will be enabled by default in 123). Feel free to go ahead and send a PR with the includeShadowRoots option as well.

Though I’m curious what’s the browser support for includeShadowRoots. I couldn’t find it in BCD, apart from the parseFromString method itself.

[thescientist13]

Thanks, I'll get started on that PR then!

Though I’m curious what’s the browser support for includeShadowRoots. I couldn’t find it in BCD, apart from the parseFromString method itself.

I can try and take a look into that. Is it just a matter of getting an official response from each vendor a confirmation of what version that feature was added in? (Apologies, haven't worked with BCD myself).

I found this blog post from Webkit about Declarative Shadow DOM which calls out DOMParser but not specifically includeShadowRoots. Not sure if that is helpful...

[thescientist13]

With some help from the WCCG, I was pointed to the WPT which shows that includeShadowRoots is under test
https://wpt.fyi/results/shadow-dom/declarative/declarative-shadow-dom-opt-in.html?label=experimental&label=master&aligned

And that is being shown in reports

It's called out as "(includingShadowRoots is historical)" and It's not mentioned in the spec.

Additionally this comment implies that the explanation for these then is that it's not going to be standardized.

---

So I wonder then if the goal here with this particular content around includeShadowRoots should be focused on capturing from a historical perspective and that it is not a standard, and should encourage readers to use / look to the alternative options instead?

• Add setHTMLUnsafe and parseHTMLUnsafe methods whatwg/html#9538
• https://wpt.fyi/results/html/webappapis/dynamic-markup-insertion/html-unsafe-methods?label=master&label=experimental&aligned&q=setHTMLUnsafe
• https://wpt.fyi/results/html/webappapis/dynamic-markup-insertion/html-unsafe-methods?label=master&label=experimental&aligned

There is a tracking item for this content as well - mdn/mdn#459

[pepelsbey]

It’s not mentioned in the spec
It’s not going to be standardized

I’m afraid this changes everything. Thank you so much for bringing this to our attention, filing the issue, and opening a draft PR. We really appreciate it! However, since the options param is not in the spec and hence why the WPT tests fail. It is also not a part of BCD. I’ll have to close it since we’re not documenting features that aren’t in the spec or the browsers, even for historical reasons. I’m sorry for confusing you earlier.

[thescientist13]

Alrighty.

Do you think there's any value on starting on mdn/mdn#459 at all, or is it too soon for that one? It's in WPT and the spec PR was merged but not sure around the sanitization efforts / parameters called out in that description.

Either way, happy to support on this now or in the future when MDN is ready for it. 👍

[pepelsbey]

@thescientist13 thank you! It seems like the setHTMLUnsafe and parseHTMLUnsafe methods were implemented behind the flag in Firefox 122 and will be shipped by default in 123. It means we have a stable spec and at least one implementation with other browsers ready to follow. That’s a perfect case for documenting this on MDN :)