define slot element (#1403)

* define slot element Fix #1404 * define methods * link terms * bikeshed syntax... trying a fix. :( * link roles per review * update changes
w3c · Apr 24, 2018 · a1091e2 · a1091e2
1 parent 9462db4
commit a1091e2
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 1 deletion.
diff --git a/sections/changes.include b/sections/changes.include
@@ -13,8 +13,10 @@
 <h3 id="changes-wd3">Changes since the <a href="https://www.w3.org/TR/2017/WD-html53-20170206/">HTML 5.3 Second Public Working Draft</a></h3>
 
   <dl>
-  <dt><a href="https://github.com/w3c/html/pull/1329">Add the <code>:defined</code> psuedo-class selector definition</a></dt>
+  <dt><a href="https://github.com/w3c/html/pull/1403">Add the <code>slot</code> element</a></dt>
    <dd>Substantive change for custom elements.</dd>
+  <dt><a href="https://github.com/w3c/html/pull/1329">Add the <code>:defined</code> psuedo-class selector definition</a></dt>
+   <dd>Substantive change for custom elements. This is at risk with only one known implementation</dd>
     <dt><a href="https://github.com/w3c/html/pull/1343">Add autonomous custom elements</a></dd>
     <dd>Substantive change, implemented in Firefox, Blink, Webkit</dd>
     <dd>Includes the {{CustomElementRegistry}} object, the {{CEReactions}} and {{HTMLConstructor}}

diff --git a/sections/elements.include b/sections/elements.include
@@ -1204,6 +1204,18 @@
        <td>{{HTMLElement}}</td>
       </tr>
 
+      <tr>
+       <th><{slot}></th>
+       <td>Shadow root slot</td>
+       <td><a>flow</a>;
+           <a>phrasing</a></td>
+       <td><a>phrasing</a></td>
+       <td><a>transparent</a></td>
+       <td><a>globals</a>;
+       <{slot/name}></td>
+       <td>{{HTMLElement}}</td>
+      </tr>
+
       <tr>
        <th><{source}></th>
        <td>Media source for <{video}> or <{audio}> or as image source for <{picture}></td>

diff --git a/sections/semantics-scriptings.include b/sections/semantics-scriptings.include
@@ -2350,4 +2350,95 @@
 
   Some of these requirements are checked during [=create an element|element creation=],
   and failing to follow them will result in a custom element that cannot be instantiated by the parser or DOM APIs.</p>
+
+  <h4 id="sec-the-slot-element">The <code>slot</code> element</h4>
+
+  <dl class="element">
+    <dt><a>Categories</a>:</dt>
+    <dd><a>Flow content</a>.</dd>
+    <dd><a>Phrasing content</a>.</dd>
+    <dt><a>Contexts in which this element can be used</a>:</dt>
+    <dd>Where <a>phrasing content</a> is expected.</dd>
+    <dt><a>Content model</a>:</dt>
+    <dd><a>Transparent</a></dd>
+    <dt><a>Tag omission in text/html</a>:</dt>
+    <dd>Neither tag is omissible</dd>
+    <dt><a>Content attributes</a>:</dt>
+    <dd><a>Global attributes</a></dd>
+    <dd><{slot/name}> - the name of the slot created.</dd>
+    <dt>[=Allowed ARIA role attribute values=]:</dt>
+    <dd>
+      <a href="#allowed-aria-roles-states-and-properties">Any role value</a>.
+    </dd>
+    <dt>[=Allowed ARIA state and property attributes=]:</dt>
+    <dd>Any <code>aria-*</code> attributes
+    <a href="#allowed-aria-roles-states-and-properties">applicable to the default or allowed roles</a>.</dd>
+    <dt><a>DOM interface</a>:</dt>
+    <dd>
+      <pre class="idl" data-highlight="webidl">
+      [Exposed=Window, HTMLConstructor]
+        interface HTMLSlotElement : HTMLElement {
+          [CEReactions] attribute DOMString name;
+          sequence&lt;Node&gt; assignedNodes(optional AssignedNodesOptions options);
+          sequence&lt;Element&gt; assignedElements(optional AssignedNodesOptions options);
+        };
+
+        dictionary AssignedNodesOptions {
+          boolean flatten = false;
+        };
+      </pre>
+    </dd>
+    <dt>
+      DPub Roles:
+    </dt>
+    <dd>
+      Any
+    </dd>
+  </dl>
+
+  The <{slot}> element creates a named <a>slot</a> within a <a>shadow tree</a>.
+  If it has an <a>assigned node</a> it <a>represents</a> that, if not it <a>represents</a> its contents.
+
+  The <dfn element-attr for="slot">name</dfn> attribute's value is a string.
+  It <a>represents</a> the name of the <a>slot</a> created in a shadow tree.
+
+  The {{slot/name}} IDL attribute must <a>reflect</a> the <{slot/name}> content attribute.
+
+  <dl class="domintro">
+  <dt><var>slot</var> . <code>name</code></dt>
+  <dd>Get or set the slot's name.</dd>
+  <dt><var>slot</var> . <code>assignedNodes()</code></dt>
+  <dd>Returns the slot's <a>assigned nodes</a>.</dd>
+  <dt><var>slot</var> . <code>assignedNodes({ flatten: true})</code></dt>
+  <dd>Returns the slot's <a>assigned nodes</a>, including those of any <{slot}> elements that are descendants, calculated recursively. If there are not <a>assigned nodes</a> it returns the elements children.</dd>
+  <dt><var>slot</var> . <code>assignedElements()</code></dt>
+  <dd>Returns the slot's <a>assigned nodes</a> that are <a>Elements</a>.</dd>
+  <dt><var>slot</var> . <code>assignedElements({ flatten: true})</code></dt>
+  <dd>Returns only the <a>Elements</a> that would be returned by
+    <code>assignedNodes({ flatten: true})</code>.</dd>
+  </dl>
+
+  The <dfn method for="slot"><code>assignedNodes()</code></dfn>, when invoked on an element <var>element</var>,
+  and given <code>options</code> <var>options</var>, must run the following algorithm:
+
+  <ol>
+    <li>If the <code>flatten</code> member of <var>options</var> is <code>false</code>,
+      return the element's <a>assigned nodes</a>.</li>
+    <li>otherwise, return the result of
+    [=find flattened slotables|finding flattened slottables=] for <var>element</var>.</li>
+  </ol>
+
+  The <dfn method for="slot"><code>assignedElements()</code></dfn>, when invoked on an element <var>element</var>,
+  and given <code>options</code> <var>options</var>, must run the following algorithm:
+
+  <ol>
+    <li>Let <var>result</var> be empty.</li>
+    <li>If the <code>flatten</code> member of <var>options</var> is <code>false</code>,
+      set <var>result</var> to the element's <a>assigned nodes</a>.</li>
+    <li>otherwise, set <var>result</var> to the result of
+     [=find flattened slotables|finding flattened slottables=] for <var>element</var>.</li>
+    <li>Remove all <a>nodes</a> from <var>result</var> that are not <a>elements</a>.</li>
+    <li>Return <var>result</var>.</li>
+  </ol>
+
 </section>
diff --git a/single-page.bs b/single-page.bs
@@ -954,6 +954,7 @@ urlPrefix: https://www.w3.org/TR/WebIDL-1/#; spec: WEBIDL-1
             text: double
             text: Error
             text: long
+            text: sequence
             text: unrestricted double
             text: unsigned long
             text: enumeration
@@ -963,6 +964,8 @@ urlPrefix: https://www.w3.org/TR/WebIDL-1/#; spec: WEBIDL-1
         type: interface;
             text: DOMString[]; url: DOMString
             text: EmptyString; url: TreatNullAs
+    urlPrefix: slot-; type: dfn;
+        text: assigned nodes
 
 # ****************************** XML (and related) ******************************************