HTML enhanced setter and streaming methods

[tunetheweb]

Specification

https://github.com/WICG/declarative-partial-updates/blob/main/dynamic-markup-revamped-explainer.md#resulting-api

Various discussions in HTML spec:
whatwg/html#11669
whatwg/html#2142
whatwg/html#12495
whatwg/html#12753
whatwg/html#12756
whatwg/html#12758

Description

Chrome is launching a new set of static and streaming HTML APIs as described here:
https://developer.chrome.com/blog/declarative-partial-updates#a_new_set_of_static_and_streaming_apis

This includes enhancements to setHTML (covered in sanitizer.yml), setHTMLUnsafe (covered in parse-html-unsafe.yml), and various new positional methods (replace, before, prepend, append, after) as well as streaming versions of these.

As these are likely to be implemented together if they roll out to other browsers, but the static and streaming versions are somewhat separate and could even be implemented at different times. So we in the Chrome team are suggesting two new features for this:

• HTML setter methods
• HTML stream methods

For now, since there is existing browser support we'll keep setHTML and setHTMLUnsafe separate, but longer term I could see those merging into "HTML setter methods" if all browsers converge on these (as we hope they will).

Documentation

https://developer.chrome.com/blog/declarative-partial-updates#a_new_set_of_static_and_streaming_apis
https://github.com/WICG/declarative-partial-updates/blob/main/dynamic-markup-revamped-explainer.md#resulting-api
https://github.com/WICG/declarative-partial-updates/tree/main/examples

Browser support

Available behind a flag from Chrome 148. Shipping in Chrome 154:
https://chromestatus.com/feature/5054329641893888

Firefox: Positive - mozilla/standards-positions#1370
WebKit: No signal yet - WebKit/standards-positions#629

[ddbeck]

Thanks for filing this, @tunetheweb. I'm taking some notes here to help me write some YAML files. You don't have to review this, but I'd very much welcome it.

Names and IDs

I'm going to propose four feature IDs and names:

• dom-html-setters-safe - HTML setter methods
• dom-html-setters-unsafe - Unsanitized HTML setter methods
• dom-html-streaming-setters-safe - HTML streaming setter methods
• dom-html-streaming-setters-unsafe - Unsanitized HTML streaming setter methods

This most closely follows after parse-html-unsafe (source, dist) presentation of this kind of API.

This is, admittedly, a bit verbose. And also a little bit opinionated on my part. But I think this approach has two major benefits:

• The IDs are long, which preserves the option of a future dom-html-setters feature, to consolidate the whole API (and other, lesser consolidations), if desired. And it's easier to make small things bigger than big things smaller.
• It separates the safe-by-default from the unsafe-by-default, which makes it somewhat easier to describe the features in clearer terms to developers that might encourage them to prefer the safer API (e.g., we can describe the unsafe API as such without confusing the issue for the safe API). See the next section for more on this.

As for the hierarchical positioning here as subordinate to dom, I'm supposing that the the existing treatment of APIs like innerHTML as more or less foundational to the DOM (and thus in dom) means that the "parent" feature of these new HTML setters is the DOM generally. There are alternatives but this is the one I think best. If it feels bad or inexplicable, please say so, and I can discuss why this route and what alternatives exist at unfortunate length.

Descriptions

In our style, I'm proposing the following, riffing on parse-html-unsafe:

dom-html-setters-safe:

The setHTML(), replaceWithHTML(), beforeHTML(), prependHTML(), appendHTML() and afterHTML() methods of Element and ShadowRoot objects insert HTML into an existing tree.

dom-html-setters-unsafe:

The setHTMLUnsafe(), replaceWithHTMLUnsafe(), beforeHTMLUnsafe(), prependHTMLUnsafe(), appendHTMLUnsafe() and afterHTMLUnsafe() DOM methods insert HTML into an existing tree. By default, they're dangerous: they don't sanitize inputs and may execute <script> code.

dom-html-streaming-setters-safe:

The streamHTML(), streamReplaceWithHTML(), streamBeforeHTML(), streamPrependHTML(), streamAppendHTML() and streamAfterHTML() methods of Element and ShadowRoot objects return writeable streams that incrementally insert HTML into an existing tree.

dom-html-streaming-setters-unsafe:

This last one has an irritating length limitation, so we have to go a bit indirect here:

The unsafe streaming HTML setter methods of the DOM API, such as streamHTMLUnsafe() and streamReplaceWithHTMLUnsafe(), return writable streams that incrementally insert HTML into an existing tree. By default, they're dangerous: they don't sanitize inputs and may execute <script> code.

Compat data

It's an early feature, with no shipping implementations, so there are not yet compat keys for this. Chrome Status seems to indicate this in line for Chrome 154, so I expect these keys will appear in September, as it moves through the beta channel.

That said, I will note one little cheat I've done with the descriptions, which implicates the data:

I included setHTML() in the description of dom-html-setters-safe. I've done this for the consistency and coherence of the whole set of features. At the time that I'm writing this, we can't actually include the compat data for the setHTML() method because it's part of sanitizer (source, dist).

I expect to be able to formally include the key in both features, when #4034 merges. I think there's a strong case to be made here to allow setHTML() to be overlapped, as it's the earliest concrete entry point for the sanitizer API, while it's also part of the raison d'etre for the constellation of methods captured by this issue.

Questions

A couple of miscellaneous questions:

• Is there to be an equivalent of Document.parseHTML() static method, in the streaming API? (e.g., should I expect there to be some future Document.streamHTML() and Document.streamHTMLUnsafe())
• If this succeeds to all the major engines, is there any possibility that y'all might push WHATG to include some author discouragement text on the old school innerHTML, outerHTML, and insertAdjacentHTML() API? It'd be really, really nice to have a legitimated discouragement pointer from those properties to the -safe APIs and trusted-types. 🤞

[tunetheweb]

Adding in @noamr for his opinions too.

I'm going to propose four feature IDs and names:
...
This is, admittedly, a bit verbose.

Yeah, I do think this is a bit verbose personally. I thought the point of web features was to try to group things up as much as possible to avoid the verbosity of MDN BCD? I don't think anyone will implement the unsafe (but not safe) variants of this (or vice versa) — though it is possible I suppose given Safari does not yet support the basic version of setHTML() (aka the safe version), but I'd presume they'd implement that at the same time as the safe versions here.

I guess another question is if parse-html-unsafe should be retired into this? Or maybe one to consider for the future once browser support becomes more widespread.

Anyway, I'm not that opposed to 4 features instead of 2 if that's your preference.

As for the hierarchical positioning here as subordinate to dom, I'm supposing that the the existing treatment of APIs like innerHTML as more or less foundational to the DOM (and thus in dom) means that the "parent" feature of these new HTML setters is the DOM generally. There are alternatives but this is the one I think best. If it feels bad or inexplicable, please say so, and I can discuss why this route and what alternatives exist at unfortunate length.

It's true their part of the DOM, but not sure we need to be that explicit. We aren't with parse-html-unsafe, nor sanitizer. I guess it makes it more obvious that they should eventually be collapsed into dom.yml but I think we're some way off that, and I'm not even sure it's desirable to keep growing that forever! So personally I'd drop the dom- prefix and just have html-setters-safe, html-setters-unsafe...etc. But again don't feel strongly about this if you prefer to keep it.

It's an early feature, with no shipping implementations, so there are not yet compat keys for this. Chrome Status seems to indicate this in line for Chrome 154, so I expect these keys will appear in September, as it moves through the beta channel.

Going to start working on that this, week, though the spec PRs are still going through review so won't have spec links so think I have to marked it as standardsTrack: false for now.

I included setHTML() in the description of dom-html-setters-safe. I've done this for the consistency and coherence of the whole set of features. At the time that I'm writing this, we can't actually include the compat data for the setHTML() method because it's part of sanitizer (source, dist).

I expect to be able to formally include the key in both features, when #4034 merges. I think there's a strong case to be made here to allow setHTML() to be overlapped, as it's the earliest concrete entry point for the sanitizer API, while it's also part of the raison d'etre for the constellation of methods captured by this issue.

Yeah I'm not sure how to handler setHTML() either. #4034 looks interesting for solving this! Technically all the "safe" versions build upon the Sanitizer API, and there is an actual API for that, so I think I see the argument for moving setHTML() out of sanitizer.yml but maybe it's a little early for that?

• Is there to be an equivalent of Document.parseHTML() static method, in the streaming API?

No there isn't. It doesn't really make sense as parseHTML says to take some text, parse it into HTML without adding it to the document, while streaming only makes sense when it's streamed into a document so the reader can benefit from seeing it as it streams in. There would be no point in parsing streaming HTML without adding it to the document. If that's what you want, then just wait until it's finished and parse it all at once. In fact, you'd also need to reparse streaming.

(e.g., should I expect there to be some future Document.streamHTML() and Document.streamHTMLUnsafe())

Not sure I understand the question or how safe/unsafe relates to parseHTML? streamHTML() already takes a option parameter which is used to make it safe or unsafe (we decided against having explicit unsafe versions of these methods and instead to make this via an options parameter to avoid exploding the number of methods anymore!).

• If this succeeds to all the major engines, is there any possibility that y'all might push WHATG to include some author discouragement text on the old school innerHTML, outerHTML, and insertAdjacentHTML() API? It'd be really, really nice to have a legitimated discouragement pointer from those properties to the -safe APIs and trusted-types. 🤞

@noamr thoughts here? I suspect these are too prevalent to deprecate (even with just discouragement text), but internally will basically become wrapper functions to setHTML(), replaceWithHTML(), and beforeHTML/prependHTML/appendHTML/afterHTML respectively. There are legitimate use cases for "unsafe" setting of HTML (otherwise we wouldn't introduce these!), but it all depends on how trusted the inputs are.

[noamr]

Adding in @noamr for his opinions too.

I'm going to propose four feature IDs and names:
...
This is, admittedly, a bit verbose.

Yeah, I do think this is a bit verbose personally. I thought the point of web features was to try to group things up as much as possible to avoid the verbosity of MDN BCD? I don't think anyone will implement the safe (but not unsafe) variants of this — though it is possible I suppose given Safari does not yet support the basic version of setHTML(), but I'd presume they'd implement that at the same time as the unsafe versions here.

I guess another question is if parse-html-unsafe should be retired into this? Or maybe one to consider for the future once browser support becomes more widespread.

Anyway, I'm not that opposed to 4 features instead of 2 if that's your preference.

Maybe "HTML streaming" and "positional HTML insertion"? Then the latter shouldn't include setHTMLUnsafe and parseHTMLUnsafe.
I don't see the use in separating the safe/unsafe versions. If the sanitizer feature is supported, the safe variants should be supported.
Not a hill I'd die on either way.

• If this succeeds to all the major engines, is there any possibility that y'all might push WHATG to include some author discouragement text on the old school innerHTML, outerHTML, and insertAdjacentHTML() API? It'd be really, really nice to have a legitimated discouragement pointer from those properties to the -safe APIs and trusted-types. 🤞

@noamr thoughts here? I suspect these are too prevalent to deprecate (even with just discouragement text), but internally will basically become wrapper functions to setHTML(), replaceWithHTML(), and beforeHTML/prependHTML/appendHTML/afterHTML respectively. There are legitimate use cases for "unsafe" setting of HTML (otherwise we wouldn't introduce these!), but it all depends on how trusted the inputs are.

They're considered legacy rather than deprecated. We can consider some wording about this, I'll raise it at WHATWG and see what folks think (once this is merged).

[tunetheweb]

I've opened the MDN BCD PR here: mdn/browser-compat-data#30328

[ddbeck]

Thank you both for your thoughtful follow up comments here.

Having slept on it, I think I'm open to collapsing this into two features, though if that's going to be the approach then I'm kinda inclined to not mention the Unsafe variants in the descriptions (the methods would be included for status calculation purposes, naturally) and leave awareness about that to documentation.

I'm also fine with not having the dom- prefix.

On the subject of discouragement, the WHATWG specs are relatively reluctant toward advising authors away from things, as compared to CSSWG and TC39. For example, the latter use "legacy" terminology somewhat freely to call out an upgrade path to new things, despite the understanding that there's no intention to ever retire the old the things (e.g., legacy name alias, Legacy subclauses). This makes it much easier to advise that upgrade path in documentation, etc., knowing it's formally blessed. Mostly, I'm just trying to plant the idea in heads, whenever I have the audience for it.

Lastly, please forgive my questions about other possible methods. I was mostly trying to get a handle on how "complete" these proposals are and, as a tech writer, I'm in the habit of asking "not even wrong" questions to verify my understanding. 😅

I've got a little bit of a backlog of feature requests for things that have now shipped, so I'll be a little delayed in writing a PR for these. But if you wish to try at creating a PR yourself, I'll be happy to reviewer sooner. Thank you!

[tunetheweb]

All questions are appreciated!

When mdn/browser-compat-data#30328 lands then I might throw together a PR here. No rush to do that before then anyway.