Skip to content
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

Custom elements: Add element.attachInternals() and ElementInternals interface #4324

Merged
merged 6 commits into from
May 16, 2019
Merged

Custom elements: Add element.attachInternals() and ElementInternals interface #4324

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2ece848
Custom elements: Add element.attachInternals() and ElementInternals i…
tkent-google Jan 28, 2019
98950c8
Handle domenic's comments
tkent-google Feb 5, 2019
5c962da
Minor tweaks
domenic Feb 14, 2019
b18e671
- Support disabledFeatures=['shadow']
tkent-google May 13, 2019
a823525
indentation nit
annevk May 13, 2019
4eea46c
NotSupportedError everywhere
domenic May 15, 2019
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
102 changes: 97 additions & 5 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3146,6 +3146,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-documenttype"><code>DocumentType</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-childnode"><code>ChildNode</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-element"><code>Element</code></dfn> interface</li>
<li><dfn data-x="dom-element-attachshadow" data-x-href="https://dom.spec.whatwg.org/#dom-element-attachshadow"><code>attachShadow()</code></dfn> method.</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-node"><code>Node</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-nodelist"><code>NodeList</code></dfn> interface</li>
<li><dfn data-x-href="https://dom.spec.whatwg.org/#interface-processinginstruction"><code>ProcessingInstruction</code></dfn> interface</li>
Expand Down Expand Up @@ -10195,6 +10196,8 @@ interface <dfn>HTMLElement</dfn> : <span>Element</span> {
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-autocapitalize">autocapitalize</span>;

[<span>CEReactions</span>] attribute [TreatNullAs=EmptyString] DOMString <span data-x="dom-innerText">innerText</span>;

<span>ElementInternals</span> <span data-x="dom-attachInternals">attachInternals</span>();
};

<span>HTMLElement</span> includes <span>GlobalEventHandlers</span>;
Expand Down Expand Up @@ -66612,6 +66615,14 @@ document.body.append(parent);
href="#html-element-constructors">HTML element constructors</a>. Each entry in the list will be
either an element or an <dfn data-x="concept-already-constructed-marker"><i>already
constructed</i> marker</dfn>.</dd>

domenic marked this conversation as resolved.
Show resolved Hide resolved
<dt>A <dfn data-x="concept-custom-element-definition-disable-internals">disable
internals</dfn> boolean</dt>
domenic marked this conversation as resolved.
Show resolved Hide resolved
<dd>Controls <code data-x="dom-attachInternals">attachInternals()</code>.

<dt>A <dfn data-x="concept-custom-element-definition-disable-shadow" data-export=""
data-dfn-for="custom element definition">disable shadow</dfn> boolean</dt>
<dd>Controls <code data-x="dom-element-attachshadow">attachShadow()</code>.
</dl>

<p>To <dfn data-export="">look up a custom element definition</dfn>, given a <var>document</var>,
Expand Down Expand Up @@ -66785,6 +66796,13 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
<li><p>Set this <code>CustomElementRegistry</code>'s <span>element definition is running</span>
flag.</p></li>

<li><p>Let <var>disableInternals</var> be false.

<li><p>Let <var>disableShadow</var> be false.

<li><p>Let <var>observedAttributes</var> be an empty <code
data-x="">sequence&lt;DOMString></code>.</p></li>

<li>
<p>Run the following substeps while catching any exceptions:</p>

Expand Down Expand Up @@ -66816,9 +66834,6 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
</ol>
</li>

<li><p>Let <var>observedAttributes</var> be an empty <code
data-x="">sequence&lt;DOMString></code>.</p></li>

<li>
<p>If the value of the entry in <var>lifecycleCallbacks</var> with key "<code
data-x="">attributeChangedCallback</code>" is not null, then:</p>
Expand All @@ -66834,6 +66849,24 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
<code data-x="">sequence&lt;DOMString></code>. Rethrow any exceptions from the
conversion.</p></li>
</ol>

<li><p>Let <var>disabledFeatures</var> be an empty <code
data-x="">sequence&lt;DOMString></code>.</p></li>

<li><p>Let <var>disabledFeaturesIterable</var> be <span
data-x="js-Get">Get</span>(<var>constructor</var>, "disabledFeatures"). Rethrow any
exceptions.</p></li>
domenic marked this conversation as resolved.
Show resolved Hide resolved

<li><p>If <var>disabledFeaturesIterable</var> is not undefined, then set
<var>disabledFeatures</var> to the result of <span
data-x="concept-idl-convert">converting</span> <var>disabledFeaturesIterable</var> to a <code
data-x="">sequence&lt;DOMString></code>. Rethrow any exceptions from the conversion.</p></li>

<li><p>Set <var>disableInternals</var> to true if <var>disabledFeaturesSequence</var>
<span data-x="list contains">contains</span> "<code data-x="">internals</code>".</p></li>

<li><p>Set <var>disableShadow</var> to true if <var>disabledFeaturesSequence</var>
<span data-x="list contains">contains</span> "<code data-x="">shadow</code>".</p></li>
</ol>

<p>Then, perform the following substep, regardless of whether the above steps threw an exception
Expand All @@ -66854,9 +66887,13 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
<span data-x="concept-custom-element-definition-constructor">constructor</span>
<var>constructor</var>, <span
data-x="concept-custom-element-definition-observed-attributes">observed attributes</span>
<var>observedAttributes</var>, and <span
<var>observedAttributes</var>, <span
data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span>
<var>lifecycleCallbacks</var>.</p></li>
<var>lifecycleCallbacks</var>, <span
data-x="concept-custom-element-definition-disable-internals">disable internals</span>
<var>disableInternals</var>, and <span
data-x="concept-custom-element-definition-disable-shadow">disable shadow</span>
<var>disableShadow</var>.</p></li>

<li><p>Add <var>definition</var> to this <code>CustomElementRegistry</code>.</p></li>

Expand Down Expand Up @@ -67429,6 +67466,61 @@ customElements.define("x-foo", class extends HTMLElement {

</div>

<h4>The <code>ElementInternals</code> interface</h4>

<dl class="domintro">
<dt><var>element</var> . <code subdfn data-x="dom-attachInternals">attachInternals()</code></dt>

<dd><p>Returns an <code>ElementInternals</code> object targeting the <span>custom element</span>
<var>element</var>. Throws an exception if <var>element</var> is not a <span>custom
element</span>, if the "<code data-x="">internals</code>" feature was disabled as part of the
domenic marked this conversation as resolved.
Show resolved Hide resolved
element definition, or if it is called twice on the same element.</p></dd>
</dl>

<pre><code class="idl" data-x="">[Exposed=Window]
interface <dfn>ElementInternals</dfn> {
<!-- We'll add some stuff here -->
};</code></pre>

<!-- We should have a domintro block for ElementInternals -->

<p>Each <code>ElementInternals</code> has a <dfn data-x="internals-target">target element</dfn>,
which is a <span>custom element</span>. <code>ElementInternals</code> provides various operations
and attributes to allow control over internal features which the user agent provides to all
elements.</p>

<p>Each <code>HTMLElement</code> has an <dfn>attached internals</dfn> boolean, initially
false.</p>

<p>The <dfn><code data-x="dom-attachInternals">attachInternals()</code></dfn> method on
domenic marked this conversation as resolved.
Show resolved Hide resolved
an <code>HTMLElement</code> <var>element</var>, when invoked, must run the following steps:</p>

<ol>
<!-- We could lift this restriction in the future. -->
<li><p>If <var>element</var>'s <span data-x="concept-element-is-value"><code
data-x="">is</code> value</span> is not null, then throw a
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>Let <var>definition</var> be the result of <span
data-x="look up a custom element definition">looking up a custom element definition</span> given
<var>element</var>'s <span>node document</span>, its namespace, its local name, and null as
<span data-x="concept-element-is-value"><code data-x="">is</code> value</span>.</p></li>

<li><p>If <var>definition</var> is null, then throw an
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>If <var>definition</var>'s <span
data-x="concept-custom-element-definition-disable-internals">disable internals</span> is true,
then throw a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As with attachShadow(), I don't think we should expose whether it's disabled or previously used. The same exception should be used for both.


<li><p>If <var>element</var>'s <span>attached internals</span> is true, then throw an
<span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>

<li><p>Set <var>element</var>'s <span>attached internals</span> to true.</p></li>

<li><p>Create a new <code>ElementInternals</code> instance
<span data-x="internals-target">targeting</span> <var>element</var>, and return it.</p></li>
</ol>

<h3 split-filename="semantics-other" id="common-idioms">Common idioms without dedicated elements</h3>

Expand Down