From 3c386c36f6f1d177ae2ed400668f21ea2ada5db3 Mon Sep 17 00:00:00 2001
From: Luke Warlow <luke@warlow.dev>
Date: Mon, 10 Jun 2024 04:05:54 +0200
Subject: [PATCH] Add initial content for setHTMLUnsafe and parseHTMLUnsafe
 (#33492)

* Add initial content for setHTMLUnsafe and parseHTMLUnsafe

* Remove erroneous secure context banner

* Apply suggestions from (my own) code review

* Updates to parseHTMLUnsafe(), parent topic, cross link

* Apply suggestions from code review

* Element.setHTMLUnsafe

* ShadowRoot.setHTMLUnsafe()

* Apply suggestions from code review - remove untrusted

Co-authored-by: Luke Warlow <luke@warlow.dev>

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
---
 files/en-us/web/api/document/index.md         |  8 +++
 .../document/parsehtmlunsafe_static/index.md  | 47 ++++++++++++++
 .../api/domparser/parsefromstring/index.md    |  2 +
 files/en-us/web/api/element/index.md          |  4 +-
 .../web/api/element/sethtmlunsafe/index.md    | 64 +++++++++++++++++++
 files/en-us/web/api/shadowroot/index.md       |  2 +
 .../web/api/shadowroot/sethtmlunsafe/index.md | 51 +++++++++++++++
 7 files changed, 177 insertions(+), 1 deletion(-)
 create mode 100644 files/en-us/web/api/document/parsehtmlunsafe_static/index.md
 create mode 100644 files/en-us/web/api/element/sethtmlunsafe/index.md
 create mode 100644 files/en-us/web/api/shadowroot/sethtmlunsafe/index.md

diff --git a/files/en-us/web/api/document/index.md b/files/en-us/web/api/document/index.md
index 1a334d06ac8b03e..6592b38d8db382c 100644
--- a/files/en-us/web/api/document/index.md
+++ b/files/en-us/web/api/document/index.md
@@ -305,6 +305,14 @@ The `Document` interface for HTML documents inherit from the {{DOMxRef("HTMLDocu
 - {{DOMxRef("Document.writeln()")}}
   - : Writes a line of text in a document.
 
+## Static methods
+
+_This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventTarget")}} interfaces._
+
+- {{domxref("Document/parseHTMLUnsafe_static", "Document.parseHTMLUnsafe()")}}
+  - : Creates a new `Document` object from a string of HTML without performing sanitization.
+    The string may contain declarative shadow roots.
+
 ## Events
 
 Listen to these events using `addEventListener()` or by assigning an event listener to the `oneventname` property of this interface. In addition to the events listed below, many events can bubble from {{domxref("Node", "nodes", "", "nocode")}} contained in the document tree.
diff --git a/files/en-us/web/api/document/parsehtmlunsafe_static/index.md b/files/en-us/web/api/document/parsehtmlunsafe_static/index.md
new file mode 100644
index 000000000000000..d5ef29ba0b04591
--- /dev/null
+++ b/files/en-us/web/api/document/parsehtmlunsafe_static/index.md
@@ -0,0 +1,47 @@
+---
+title: "Document: parseHTMLUnsafe() static method"
+short-title: parseHTMLUnsafe()
+slug: Web/API/Document/parseHTMLUnsafe_static
+page-type: web-api-static-method
+browser-compat: api.Document.parseHTMLUnsafe_static
+---
+
+{{APIRef("DOM")}}
+
+The **`parseHTMLUnsafe()`** static method of the {{domxref("Document")}} object is used to parse a string of HTML, which may contain [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom), in order to create a new {{domxref("Document")}} instance.
+
+The suffix "Unsafe" in the method name indicates that, while `<script>` elements are not evaluated during parsing, the method does not sanitize other potentially unsafe XSS-relevant input.
+
+The resulting `Document` will have a [content type](/en-US/docs/Web/API/Document/contentType) of "text/html", a [character set](/en-US/docs/Web/API/Document/characterSet) of UTF-8, and a URL of "about:blank"
+
+## Syntax
+
+```js-nolint
+Document.parseHTMLUnsafe(input)
+```
+
+### Parameters
+
+- `html`
+  - : A string of HTML to be parsed.
+
+### Return value
+
+A {{domxref("Document")}}.
+
+### Exceptions
+
+None.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMParser.parseFromString()")}} for parsing HTML or XML into a DOM tree
+- {{domxref("Element.setHTMLUnsafe")}}
diff --git a/files/en-us/web/api/domparser/parsefromstring/index.md b/files/en-us/web/api/domparser/parsefromstring/index.md
index e7a88c027ca5eae..a16ecfa4987568a 100644
--- a/files/en-us/web/api/domparser/parsefromstring/index.md
+++ b/files/en-us/web/api/domparser/parsefromstring/index.md
@@ -10,6 +10,8 @@ browser-compat: api.DOMParser.parseFromString
 
 The **`parseFromString()`** method of the {{domxref("DOMParser")}} interface parses a string containing either HTML or XML, returning an {{domxref("HTMLDocument")}} or an {{domxref("XMLDocument")}}.
 
+> **Note:** The [`Document.parseHTMLUnsafe()`](/en-US/docs/Web/API/Document/parseHTMLUnsafe_static) static method provides an ergonomic alternative for parsing HTML strings into a {{domxref("Document")}}.
+
 ## Syntax
 
 ```js-nolint
diff --git a/files/en-us/web/api/element/index.md b/files/en-us/web/api/element/index.md
index e72f7d6f0bbacef..ab06b3379dfedbf 100644
--- a/files/en-us/web/api/element/index.md
+++ b/files/en-us/web/api/element/index.md
@@ -282,7 +282,9 @@ _`Element` inherits methods from its parents {{DOMxRef("Node")}}, and its own pa
 - {{DOMxRef("Element.setCapture()")}} {{Non-standard_Inline}} {{Deprecated_Inline}}
   - : Sets up mouse event capture, redirecting all mouse events to this element.
 - {{DOMxRef("Element.setHTML()")}} {{SecureContext_Inline}} {{deprecated_inline}}
-  - : Parses and [sanitizes](/en-US/docs/Web/API/HTML_Sanitizer_API) a string of HTML and inserts into the DOM as a subtree of the element.
+  - : Parses and [sanitizes](/en-US/docs/Web/API/HTML_Sanitizer_API) a string of HTML into a document fragment, which then replaces the element's original subtree in the DOM.
+- {{DOMxRef("Element.setHTMLUnsafe()")}}
+  - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the element's original subtree in the DOM. The HTML string may include declarative shadow roots, which would be parsed as template elements if the HTML was set using [`Element.innerHTML`](#element.innerhtml).
 - {{DOMxRef("Element.setPointerCapture()")}}
   - : Designates a specific element as the capture target of future [pointer events](/en-US/docs/Web/API/Pointer_events).
 - {{DOMxRef("Element.toggleAttribute()")}}
diff --git a/files/en-us/web/api/element/sethtmlunsafe/index.md b/files/en-us/web/api/element/sethtmlunsafe/index.md
new file mode 100644
index 000000000000000..0b45d9962840df4
--- /dev/null
+++ b/files/en-us/web/api/element/sethtmlunsafe/index.md
@@ -0,0 +1,64 @@
+---
+title: "Element: setHTMLUnsafe() method"
+short-title: setHTMLUnsafe()
+slug: Web/API/Element/setHTMLUnsafe
+page-type: web-api-instance-method
+browser-compat: api.Element.setHTMLUnsafe
+---
+
+{{APIRef("DOM")}}
+
+The **`setHTMLUnsafe()`** method of the {{domxref("Element")}} interface is used to parse a string of HTML into a {{domxref("DocumentFragment")}}, which then replaces the element's subtree in the DOM.
+The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom).
+
+The suffix "Unsafe" in the method name indicates that the method does not sanitize or remove potentially unsafe XSS-relevant input, such as `<script>` elements, and script or event handler content attributes.
+
+If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root.
+
+> **Note:** This method should be used instead of {{domxref("Element.innerHTML")}} when a string of HTML may contain declarative shadow roots.
+
+## Syntax
+
+```js-nolint
+setHTMLUnsafe(html)
+```
+
+### Parameters
+
+- `html`
+  - : A string defining HTML to be parsed.
+
+### Return value
+
+None (`undefined`).
+
+### Exceptions
+
+None.
+
+## Examples
+
+The code below demonstrates how to parse a string of HTML and insert it into the `Element` with an id of `target`.
+
+```js
+const value = "<p>This is a string of text</p>"; // string of HTML
+
+// Get the Element with id "target" and set it with the string.
+document.getElementById("target").setHTMLUnsafe(value);
+
+// Result (as a string): "<p>This is a string of text</p>"
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("ShadowRoot.setHTMLUnsafe()")}}
+- {{domxref("Element.innerHTML")}}
+- {{domxref("Document.parseHTMLUnsafe_static", "Document.parseHTMLUnsafe()")}}
diff --git a/files/en-us/web/api/shadowroot/index.md b/files/en-us/web/api/shadowroot/index.md
index d247975c4232d32..4a3bcfebf038a52 100644
--- a/files/en-us/web/api/shadowroot/index.md
+++ b/files/en-us/web/api/shadowroot/index.md
@@ -57,6 +57,8 @@ You can retrieve a reference to an element's shadow root using its {{domxref("El
   - : Returns the topmost element at the specified coordinates.
 - {{domxref("ShadowRoot.elementsFromPoint()")}} {{Non-standard_Inline}}
   - : Returns an array of all elements at the specified coordinates.
+- {{DOMxRef("ShadowRoot.setHTMLUnsafe()")}}
+  - : Parses a string of HTML into a document fragment, without sanitization, which then replaces the shadowroot's original subtree. The HTML string may include declarative shadow roots, which would be parsed as template elements the HTML was set using [`ShadowRoot.innerHTML`](#shadowroot.innerhtml).
 
 ## Events
 
diff --git a/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md b/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md
new file mode 100644
index 000000000000000..85b9b8f49146169
--- /dev/null
+++ b/files/en-us/web/api/shadowroot/sethtmlunsafe/index.md
@@ -0,0 +1,51 @@
+---
+title: "ShadowRoot: setHTMLUnsafe() method"
+short-title: setHTMLUnsafe()
+slug: Web/API/ShadowRoot/setHTMLUnsafe
+page-type: web-api-instance-method
+browser-compat: api.ShadowRoot.setHTMLUnsafe
+---
+
+{{APIRef("Shadow DOM")}}
+
+The **`setHTMLUnsafe()`** method of the {{domxref("ShadowRoot")}} interface is used to parse a string of HTML into a {{domxref("DocumentFragment")}}, which then replaces the element's subtree in the DOM.
+The input HTML may include [declarative shadow roots](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom).
+
+The suffix "Unsafe" in the method name indicates that the method does not sanitize or remove potentially unsafe XSS-relevant input, such as `<script>` elements, and script or event handler content attributes.
+
+If the string of HTML defines more than one [declarative shadow root](/en-US/docs/Web/HTML/Element/template#declarative_shadow_dom) in a particular shadow host then only the first {{domxref("ShadowRoot")}} is created — subsequent declarations are parsed as `<template>` elements within that shadow root.
+
+> **Note:** This method should be used instead of {{domxref("ShadowRoot.innerHTML")}} when a string of HTML may contain declarative shadow roots.
+
+## Syntax
+
+```js-nolint
+setHTMLUnsafe(html)
+```
+
+### Parameters
+
+- `html`
+  - : A string defining HTML to be parsed.
+
+### Return value
+
+None (`undefined`).
+
+### Exceptions
+
+None.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Element.setHTMLUnsafe()")}}
+- {{domxref("ShadowRoot.innerHTML")}}
+- {{domxref("Document.parseHTMLUnsafe_static", "Document.parseHTMLUnsafe()")}}