Skip to content

Add <template contentmethod> for declarative out-of-order streaming #11818

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Add <template contentmethod> for declarative out-of-order streaming #11818

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6ec5ba3
Add declarative out-of-order streaming
foolip Oct 22, 2025
50a4491
Think out loud with TODOs and questions
foolip Oct 22, 2025
97d3cfd
Flesh things out more
foolip Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 159 additions & 4 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13894,6 +13894,7 @@ https://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%
<li><code data-x="attr-autocorrect">autocorrect</code></li>
<li><code data-x="attr-fe-autofocus">autofocus</code></li>
<li><code data-x="attr-contenteditable">contenteditable</code></li>
<li><code data-x="attr-contentname">contentname</code></li>
<li><code data-x="attr-dir">dir</code></li>
<li><code data-x="attr-draggable">draggable</code></li>
<li><code data-x="attr-enterkeyhint">enterkeyhint</code></li>
Expand Down Expand Up @@ -67863,6 +67864,7 @@ not-slash = %x0000-002E / %x0030-10FFFF
<dd><span data-x="concept-content-nothing">Nothing</span> (for clarification, <a href="#template-example">see example</a>).</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-template-contentmethod">contentmethod</code></dd>
<dd><code data-x="attr-template-shadowrootmode">shadowrootmode</code></dd>
<dd><code data-x="attr-template-shadowrootdelegatesfocus">shadowrootdelegatesfocus</code></dd>
<dd><code data-x="attr-template-shadowrootclonable">shadowrootclonable</code></dd>
Expand All @@ -67879,6 +67881,7 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();

readonly attribute <span>DocumentFragment</span> <span data-x="dom-template-content">content</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-template-contentmethod">contentMethod</span>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-template-shadowrootmode">shadowRootMode</span>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowrootdelegatesfocus">shadowRootDelegatesFocus</dfn>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLTemplateElement" data-x="dom-template-shadowrootclonable">shadowRootClonable</dfn>;
Expand All @@ -67894,6 +67897,51 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {

<p>In a rendering, the <code>template</code> element <span>represents</span> nothing.</p>

<p>The <dfn element-attr for="template"><code
data-x="attr-template-contentmethod">contentmethod</code></dfn> content attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>

<table>
<thead>
<tr>
<th>Keyword
<th>State
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="template/contentmethod"><code data-x="attr-contentmethod-replace">replace</code></dfn>
<td><dfn data-x="attr-contentmethod-replace-state">Replace</dfn>
<td>Replace the target element itself.
<tr>
<td><dfn attr-value for="template/contentmethod"><code data-x="attr-contentmethod-replace-children">replace-children</code></dfn>
<td><dfn data-x="attr-contentmethod-replace-children-state">Replace Children</dfn>
<td>Replace the children of the target element.
<tr>
<td><dfn attr-value for="template/contentmethod"><code data-x="attr-contentmethod-append">append</code></dfn>
<td><dfn data-x="attr-contentmethod-append-state">Append</dfn>
<td>Append after the target element.
<tr>
<td><dfn attr-value for="template/contentmethod"><code data-x="attr-contentmethod-prepend">prepend</code></dfn>
<td><dfn data-x="attr-contentmethod-prepend-state">Prepend</dfn>
<td>Prepend before the target element.
</table>

<p>The <code data-x="attr-template-contentmethod">contentmethod</code> attribute's <i
data-x="invalid value default">invalid value default</i> and <i data-x="missing value
default">missing value default</i> are both the <dfn
data-x="attr-contentmethod-none-state">None</dfn> state.</p>

<p>The <dfn element-attr for="htmlsvg-global"><code data-x="attr-contentname">contentname</code></dfn>
content points to the target for template contentmethod, like an ID attribute.</p>
<!-- TODO better words, and should this be in another section since it's not for <template>? -->

<p class="XXX">Should contentname work on only HTML elements, HTML+SVG+MathML, or any element?</p>

<p>If specified, the <code data-x="attr-contentname">contentname</code> attribute value must equal
the <code data-x="attr-contentname">contentname</code> of another element in the same
<span>tree</span>.</p>
<!-- TODO: make this non-symmetrical and matching the processing model -->

<p>The <dfn element-attr for="template"><code
data-x="attr-template-shadowrootmode">shadowrootmode</code></dfn> content attribute is an
<span>enumerated attribute</span> with the following keywords and states:</p>
Expand Down Expand Up @@ -68075,6 +68123,13 @@ interface <dfn interface>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
not a <code>ShadowRoot</code> node; otherwise null.</p>
</div>

<div algorithm>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-contentmethod">contentMethod</code></dfn> IDL attribute must
<span>reflect</span> the <code data-x="attr-template-contentmethod">contentmethod</code> content
attribute, <span>limited to only known values</span>.</p>
</div>

<div algorithm>
<p>The <dfn attribute for="HTMLTemplateElement"><code
data-x="dom-template-shadowrootmode">shadowRootMode</code></dfn> IDL attribute must
Expand Down Expand Up @@ -139251,6 +139306,13 @@ dictionary <dfn dictionary>StorageEventInit</dfn> : <span>EventInit</span> {
parser.</p>
</dd>

<dt>If <var>target</var> is a <code>template</code> element whose "contentmethod target" is non-null:</dt>

<dd>
<p>Let <var>adjusted insertion location</var> be inside <var>target</var>'s "contentmethod target",
after its last child (if any).</p>
</dd>

<dt>Otherwise</dt>

<dd>
Expand All @@ -139262,8 +139324,31 @@ dictionary <dfn dictionary>StorageEventInit</dfn> : <span>EventInit</span> {

<li>
<p>If the <var>adjusted insertion location</var> is inside a <code>template</code>
element, let it instead be inside the <code>template</code> element's <span>template
contents</span>, after its last child (if any).</p>
element:</p>

<ol>
<li><p>If <var>target</var> is a <code>template</code> element whose "contentmethod target" is
non-null, let <var>adjusted insertion location</var> be inside <var>target</var>'s
"contentmethod target", after its last child (if any).</p></li>

<li><p>Otherwise, let <var>adjusted insertion location</var> be inside the
<code>template</code> element's <span>template contents</span>, after its last child (if
any).</p></li>
</ol>

<p class="XXX">We shouldn't handle contentmethod in both places above. But which is correct?
If we use the first place, should the above "Otherwise" be able to further update the
adjusted insertion location? The test case for this would be something like:</p>

<pre><code class="html">
&lt;template contentname="regular-template">
&lt;template contentmethod="append">
&lt;template contentname="regular-template">
&lt;div class="where-does-this-end-up">&lt;/div>
&lt;/template>
&lt;/template></code></pre>

<p class="XXX">Also, does "inside" above mean any descendent, or only children?</p>
</li>

<li>
Expand Down Expand Up @@ -139413,6 +139498,45 @@ dictionary <dfn dictionary>StorageEventInit</dfn> : <span>EventInit</span> {
algorithm</span>, then push a new <span>element queue</span> onto <var>element</var>'s
<span>relevant agent</span>'s <span>custom element reactions stack</span>.</p></li>

<li>
<p>If <var>element</var>'s has a <code data-x="attr-contentname">contentname</code> attribute
specified and <var>adjusted insertion location</var> is inside a <code>template</code> element whose
<code data-x="attr-template-contentmethod">contentmethod</code> attribute is not in the <span
data-x="attr-contentmethod-none-state">None</span> state:</p>

<ol>
<li><p>Let <var>scope</var> be the <code>template</code> element's parent.</p></li>

<li><p>If <var>scope</var> is a <code>body</code> element, set <var>scope</var> to its
parent.</p></li>

<li><p>Let <var>target</var> be the first element in tree-order within <var>scope</var> with
a <code data-x="attr-contentname">contentname</code> attribute exactly matching that of
<var>element</var>.</p></li>

<li><p>If <var>target</var> is null, TODO and return.</p></li>

<li><p>If <var>target</var> doesn't have the same namespace and localName as <var>element</var>,
TODO and return.</p></li>

<li>
<p>Set the <code>template</code> element's "contentmethod target" to <var>target</var>.</p>

<p class="note">The "contentmethod target" will be used later when nodes are to be inserted
into the child of the template element that has a contentname attribute.</p>
</li>

<li>
<p>Depending on the <code data-x="attr-template-contentmethod">contentmethod</code> attribute
state, potentially remove <var>target</var> or its children and adjust the
<code>template</code> element's "contentmethod target" and additionally keep track of the
element we should insert before for the "prepend" and "replace" modes.</p>

<p class="XXX">Should we still insert the element in the following steps? Does it matter?</p>
</li>
</ol>
</li>

<li><p>Insert <var>element</var> at the <var>adjusted insertion location</var>.</p></li>

<li><p>If the parser was not created as part of the <span>HTML fragment parsing
Expand Down Expand Up @@ -140196,6 +140320,10 @@ document.body.appendChild(text);
<p>If any of the following are false:</p>

<ul>
<li><var>templateStartTag</var>'s <code
data-x="attr-template-contentmethod">contentmethod</code> is not in the <span
data-x="attr-contentmethod-none-state">None</span> state;</li>

<li><var>templateStartTag</var>'s <code
data-x="attr-template-shadowrootmode">shadowrootmode</code> is not in the <span
data-x="attr-shadowrootmode-none-state">None</span> state;</li>
Expand All @@ -140208,11 +140336,25 @@ document.body.appendChild(text);
open elements</span>,</li>
</ul>

<p>then <span>insert an HTML element</span> for the token.</p>
<p>then <span>insert an HTML element</span> for the token and return.</p>
</li>

<li>
<p>Otherwise:</p>
<p>If <var>templateStartTag</var>'s <code
data-x="attr-template-contentmethod">contentmethod</code> is not in the <span
data-x="attr-contentmethod-none-state">None</span> state:</p>

<ol>
<li><p>TODO: what to we need to do so that elements are inserted into the template element
and redirected by our pre-insertion steps?</p></li>
</ol>
</li>

<li>
<!-- TODO: is it OK if both of these branches run? If not, which one wins? -->
<p>If <var>templateStartTag</var>'s <code
data-x="attr-template-shadowrootmode">shadowrootmode</code> is not in the <span
data-x="attr-shadowrootmode-none-state">None</span> state:</p>

<ol>
<li><p>Let <var>declarativeShadowHostElement</var> be <span>adjusted current
Expand Down Expand Up @@ -152714,6 +152856,19 @@ interface <dfn interface>External</dfn> {
<td> Whether the element is editable
<td> "<code data-x="">true</code>"; "<code data-x="">plaintext-only</code>";
"<code data-x="">false</code>"
<tr>
<th> <code data-x="">contentmethod</code>
<td> <code data-x="attr-template-contentmethod">template</code>
<td> Enables out-of-order streaming <!-- TODO better words -->
<td> "<code data-x="attr-contentmethod-replace">replace</code>";
"<code data-x="attr-contentmethod-replace-children">replace-children</code>";
"<code data-x="attr-contentmethod-append">append</code>";
"<code data-x="attr-contentmethod-prepend">prepend</code>"
<tr>
<th> <code data-x="">contentname</code>
<td> <span data-x="attr-contentname">HTML elements</span>
<td> Unique string to target what contentmethod affects <!-- TODO better words -->
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">controls</code>
<td> <code data-x="attr-media-controls">audio</code>;
Expand Down