Skip to content

Commit

Permalink
Add imperative slot assignment API
Browse files Browse the repository at this point in the history 
Closes #3534. Closes #5483 by superseding it.

Explainer: https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Imperative-Shadow-DOM-Distribution-API.md

Corresponding DOM Standard pull request: whatwg/dom#966

Co-authored-by: Yu Han <yuzhehan@yuzhehan-macbookpro.roam.corp.google.com>
  • Loading branch information
@mfreed7
mfreed7 and Yu Han authored Apr 14, 2021
1 parent b31e145 commit 24a6d00
Showing 1 changed file with 70 additions and 19 deletions.
89 changes: 70 additions & 19 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2209,7 +2209,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x-href="https://infra.spec.whatwg.org/#list">list</dfn> data structure and the associated definitions for
<dfn data-x="list append" data-x-href="https://infra.spec.whatwg.org/#list-append">append</dfn>,
<dfn data-x="list extend" data-x-href="https://infra.spec.whatwg.org/#list-extend">extend</dfn>,
<dfn data-x="list replace" data-x-href="https://infra.spec.whatwg.org/#list-remove">replace</dfn>,
<dfn data-x="list replace" data-x-href="https://infra.spec.whatwg.org/#list-replace">replace</dfn>,
<dfn data-x="list remove" data-x-href="https://infra.spec.whatwg.org/#list-remove">remove</dfn>,
<dfn data-x="list empty" data-x-href="https://infra.spec.whatwg.org/#list-empty">empty</dfn>,
<dfn data-x="list contains" data-x-href="https://infra.spec.whatwg.org/#list-contain">contains</dfn>,
Expand Down Expand Up @@ -2964,10 +2964,16 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#document-element">document element</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document">in a document</dfn> (legacy), and <dfn data-x-href="https://dom.spec.whatwg.org/#connected">connected</dfn> concepts</li>
<li>The <dfn data-x="concept-slot" data-x-href="https://dom.spec.whatwg.org/#concept-slot">slot</dfn> concept, and its <dfn data-x="slot-name" data-x-href="https://dom.spec.whatwg.org/#slot-name">name</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#slot-assigned-nodes">assigned nodes</dfn></li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slotable-assigned-slot">assigned slot</dfn> concept.
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slotable-assigned-slot">assigned slot</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#dom-shadowroot-slot-assignment">slot assignment</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-slotable">slottable</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#assign-slotables-for-a-tree">assign slottables for a tree</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-descendant">inclusive descendants</dfn> concept</li>
<li>The <dfn data-x="finding flattened slottables" data-x-href="https://dom.spec.whatwg.org/#find-flattened-slotables">find flattened slottables</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#slottable-manual-slot-assignment">manual slot assignment</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#assign-a-slot">assign a slot</dfn> algorithm</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-node-pre-insert">pre-insert</dfn>, <dfn data-x="concept-node-insert" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert">insert</dfn>, <dfn data-x="concept-node-append" data-x-href="https://dom.spec.whatwg.org/#concept-node-append">append</dfn>, <dfn data-x="concept-node-replace" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace">replace</dfn>, <dfn data-x="concept-node-replace-all" data-x-href="https://dom.spec.whatwg.org/#concept-node-replace-all">replace all</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#string-replace-all">string replace all</dfn>, <dfn data-x="concept-node-remove" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove">remove</dfn>, and <dfn data-x="concept-node-adopt" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt">adopt</dfn> algorithms for nodes</li>
<li>The <dfn data-x="concept-tree-descendant" data-x-href="https://dom.spec.whatwg.org/#concept-tree-descendant">descendant</dfn> concept</li>
<li>The <dfn data-x="concept-node-insert-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-insert-ext">insertion steps</dfn>,
<dfn data-x="concept-node-remove-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-remove-ext">removing steps</dfn>,
<dfn data-x="concept-node-adopt-ext" data-x-href="https://dom.spec.whatwg.org/#concept-node-adopt-ext">adopting steps</dfn>, and
Expand Down Expand Up @@ -59542,16 +59548,17 @@ interface <dfn>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd w-nodev>
<pre><code class="idl">[Exposed=Window]
interface <dfn>HTMLSlotElement</dfn> : <span>HTMLElement</span> {
interface <dfn interface>HTMLSlotElement</dfn> : <span>HTMLElement</span> {
[<span>HTMLConstructor</span>] constructor();

[<span>CEReactions</span>] attribute DOMString <span data-x="dom-slot-name">name</span>;
sequence&lt;Node> <span data-x="dom-slot-assignedNodes">assignedNodes</span>(optional <span>AssignedNodesOptions</span> options = {});
sequence&lt;Element> <span data-x="dom-slot-assignedElements">assignedElements</span>(optional <span>AssignedNodesOptions</span> options = {});
undefined <span data-x="dom-slot-assign">assign</span>((<span>Element</span> or <span>Text</span>)... nodes);
};

dictionary <dfn>AssignedNodesOptions</dfn> {
boolean flatten = false;
dictionary <dfn dictionary>AssignedNodesOptions</dfn> {
boolean <dfn dict-member for="AssignedNodeOptions" data-x="dom-AssignedNodesOptions-flatten">flatten</dfn> = false;
};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLSlotElement</code>.</dd>
Expand Down Expand Up @@ -59593,33 +59600,76 @@ dictionary <dfn>AssignedNodesOptions</dfn> {
<dt><var>slot</var> . <code data-x="dom-slot-assignedElements">assignedElements</code>({ flatten: true })</dt>
<dd>Returns the same as <code data-x="dom-slot-assignedNodes">assignedNodes({ flatten: true
})</code>, limited to elements.</dd>

<dt><var>slot</var> . <code data-x="dom-slot-assign">assign</code>(...<var>nodes</var>)</dt>
<dd>
<p>Set <var>slot</var>'s <span>manually assigned nodes</span> to the given <var>nodes</var>.</p>
</dd>
</dl>

<p>The <dfn data-x="dom-slot-name"><code>name</code></dfn> IDL attribute must <span>reflect</span>
the content attribute of the same name.</p>
<p>The <dfn attribute for="HTMLSlotElement" data-x="dom-slot-name"><code>name</code></dfn> IDL
attribute must <span>reflect</span> the content attribute of the same name.</p>

<p>The <dfn data-x="dom-slot-assignedNodes"><code>assignedNodes(<var>options</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<p>The <code>slot</code> element has <dfn export for="HTMLSlotElement">manually assigned
nodes</dfn>, which is an <span data-x="set">ordered set</span> of <span
data-x="slottable">slottables</span> set by <code data-x="dom-slot-assign">assign()</code>.
This set is initially empty.</p>

<p class="note">The <span>manually assigned nodes</span> set can be implemented using weak
references to the <span data-x="slottable">slottables</span>, because this set is not
directly accessible from script.</p>

<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assignedNodes"><code>assignedNodes(<var>options</var>)</code></dfn> method steps
are:</p>

<ol>
<li><p>If the value of <var>options</var>'s <code data-x="">flatten</code> member is false, then
return this element's <span>assigned nodes</span>.</p></li>
<li><p>If <var>options</var>["<code data-x="dom-AssignedNodesOptions-flatten">flatten</code>"] is
false, then return <span>this</span>'s <span>assigned nodes</span>.</p></li>

<li><p>Return the result of <span>finding flattened slottables</span> with this element.</p></li>
<li><p>Return the result of <span>finding flattened slottables</span> with
<span>this</span>.</p></li>
</ol>

<p>The <dfn data-x="dom-slot-assignedElements"><code>assignedElements(<var>options</var>)</code></dfn>
method, when invoked, must run these steps:</p>
<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assignedElements"><code>assignedElements(<var>options</var>)</code></dfn> method
steps are:</p>

<ol>
<li><p>If the value of <var>options</var>'s <code data-x="">flatten</code> member is false, then
return this element's <span>assigned nodes</span>, filtered to contain only <code>Element</code>
nodes.</p></li>
<li><p>If <var>options</var>["<code data-x="dom-AssignedNodesOptions-flatten">flatten</code>"] is
false, then return <span>this</span>'s <span>assigned nodes</span>, filtered to contain only
<code>Element</code> nodes.</p></li>

<li><p>Return the result of <span>finding flattened slottables</span> with this element, filtered
to contain only <code>Element</code> nodes.</p></li>
<li><p>Return the result of <span>finding flattened slottables</span> with <span>this</span>,
filtered to contain only <code>Element</code> nodes.</p></li>
</ol>

<p>The <dfn method for="HTMLSlotElement"
data-x="dom-slot-assign"><code>assign(...<var>nodes</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>Let <var>nodesSet</var> be a new <span data-x="set">ordered set</span>.</p></li>

<li>
<p><span data-x="list iterate">For each</span> <var>node</var> of <var>nodes</var>:</p>

<ol>
<li><p>If <var>node</var>'s <span>manual slot assignment</span> refers to a <span>slot</span>,
then remove <var>node</var> from that <span>slot</span>'s
<span>manually assigned nodes</span>.</p></li>

<li><p>Set <var>node</var>'s <span>manual slot assignment</span> to <span>this</span>.</p></li>

<li><p><span data-x="set append">Append</span> <var>node</var> to <var>nodesSet</var>.</p></li>
</ol>
</li>

<li><p>Set <span>this</span>'s <span>manually assigned nodes</span> to
<var>nodesSet</var>.</p></li>

<li><p>Run <span>assign slottables for a tree</span> for <span>this</span>'s
<span>root</span>.</p></li>
</ol>


<h4 split-filename="canvas">The <dfn id="canvas"><code>canvas</code></dfn> element</h4>
Expand Down Expand Up @@ -124398,6 +124448,7 @@ INSERT INTERFACES HERE
Simon Fraser,
Simon Montagu,
Simon Sapin,
Yu Han, <!-- yuzhe-han on GitHub -->
Simon Spiegel,
skeww, <!-- on reddit -->
Smylers,
Expand Down

0 comments on commit 24a6d00

Please sign in to comment.