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 <[email protected]> --------- Co-authored-by: Hamish Willee <[email protected]>
mdn · Jun 10, 2024 · 3c386c3 · 3c386c3
1 parent f7856d2
commit 3c386c3
Show file tree

Hide file tree

Showing 7 changed files with 177 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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()")}}