Shadow: define .attachShadow() and .shadowRoot

dom.bs

@@ -3568,7 +3568,7 @@ dom-Range-extractContents, dom-Range-cloneContents -->
 invoked, must run these steps:
 
 <ol>
- <li><p>If <a>context object</a> is a <a>shadow root</a>, <a>throw</a> a {{NotSupportedError}}
+ <li><p>If <a>context object</a> is a <a for=/>shadow root</a>, <a>throw</a> a {{NotSupportedError}}
  exception.
 
  <li><p>Return a <a lt="clone a node">clone</a> of the <a>context object</a>, with the
@@ -4537,7 +4537,7 @@ method, when invoked, must run these steps:
   <var>deep</var> is true, the copy also includes the
   <var>node</var>'s <a>descendants</a>.
 
-  If <var>node</var> is a <a>document</a> or a <a>shadow root</a>, throws a
+  If <var>node</var> is a <a>document</a> or a <a for=/>shadow root</a>, throws a
   {{NotSupportedError}} exception.
 
  <dt><var>node</var> = <var>document</var> . {{adoptNode(node)}}
@@ -4547,14 +4547,14 @@ method, when invoked, must run these steps:
   <a>document</a> and returns it.
 
   If <var>node</var> is a <a>document</a>, throws a {{NotSupportedError}} or, if
-  <var>node</var> is a <a>shadow root</a>, throws a {{HierarchyRequestError}} exception.
+  <var>node</var> is a <a for=/>shadow root</a>, throws a {{HierarchyRequestError}} exception.
 </dl>
 
 The <dfn method for=Document><code>importNode(<var>node</var>, <var>deep</var>)</code></dfn> method,
 when invoked, must run these steps:
 
 <ol>
- <li>If <var>node</var> is a <a>document</a> or <a>shadow root</a>, <a>throw</a> a
+ <li>If <var>node</var> is a <a>document</a> or <a for=/>shadow root</a>, <a>throw</a> a
  {{NotSupportedError}} exception.
 
  <li>Return a <a lt="clone a node">clone</a> of
@@ -4598,7 +4598,7 @@ must run these steps:
  <li>If <var>node</var> is a <a>document</a>, <a>throw</a> a {{NotSupportedError}}
  exception.
 
- <li>If <var>node</var> is a <a>shadow root</a>, <a>throw</a> a {{HierarchyRequestError}}
+ <li>If <var>node</var> is a <a for=/>shadow root</a>, <a>throw</a> a {{HierarchyRequestError}}
  exception.
 
  <li><a>Adopt</a> <var>node</var>
@@ -4962,7 +4962,7 @@ or if <var>B</var>'s <a for=tree>root</a> has an associated <a for=DocumentFragm
 <a for=DocumentFragment>host</a>.
 
 <p class="note no-backref">The {{DocumentFragment}} <a>node</a>'s <a for=DocumentFragment>host</a>
-concept is useful for HTML's <{template}> element and for <a>shadow roots</a>, and impacts the
+concept is useful for HTML's <{template}> element and for <a for=/>shadow roots</a>, and impacts the
 <a>pre-insert</a> and <a>replace</a> algorithms.
 
 <dl class=domintro>
@@ -4985,7 +4985,10 @@ interface ShadowRoot : DocumentFragment {
 </pre>
 
 <p>{{ShadowRoot}} <a>nodes</a> are simply known as
-<dfn export id=concept-shadow-root>shadow roots</dfn>.
+<dfn export id=concept-shadow-root lt="shadow root">shadow roots</dfn>.
+
+<p><a for=/>Shadow roots</a> have an associated <dfn for=ShadowRoot>encapsulation mode</dfn>
+("<code>open</code>" or "<code>closed</code>").</p>
 
 <p>The <dfn attribute for=ShadowRoot><code>host</code></dfn> attribute's getter must return the
 <a>context object</a>'s <a for=DocumentFragment>host</a>.
@@ -5027,6 +5030,9 @@ interface Element : Node {
   Attr? setAttributeNodeNS(Attr attr);
   Attr removeAttributeNode(Attr attr);
 
+  ShadowRoot attachShadow(ShadowRootInit init);
+  readonly attribute ShadowRoot? shadowRoot;
+
   Element? closest(DOMString selectors);
   boolean matches(DOMString selectors);
   boolean webkitMatchesSelector(DOMString selectors); // historical alias of .matches
@@ -5037,22 +5043,29 @@ interface Element : Node {
 
   Element? insertAdjacentElement(DOMString where, Element element); // historical
   void insertAdjacentText(DOMString where, DOMString data); // historical
-};</pre>
+};
 
+dictionary ShadowRootInit {
+  required ShadowRootMode mode;
+};
 
-{{Element}} <a>nodes</a> are simply
-known as <dfn export id=concept-element lt="element">elements</dfn>.
+enum ShadowRootMode { "open", "closed" };
+</pre>
+
+<p>{{Element}} <a>nodes</a> are simply known as
+<dfn export id=concept-element lt=element>elements</dfn>.
 
-<a for="/">Elements</a> have an associated
+<p><a for=/>Elements</a> have an associated
 <dfn export id=concept-element-namespace for=Element>namespace</dfn>,
 <dfn export id=concept-element-namespace-prefix for=Element>namespace prefix</dfn>, and
 <dfn export id=concept-element-local-name for=Element>local name</dfn>. When an
-<a for="/">element</a> is created, its
-<a for=Element>local name</a> is always given.
-Unless explicitly given when an <a for="/">element</a>
-is created, its <a for=Element>namespace</a> and
-<a for=Element>namespace prefix</a> are
-null.
+<a for="/">element</a> is created, its <a for=Element>local name</a> is always given. Unless
+explicitly given when an <a for="/">element</a> is created, its <a for=Element>namespace</a> and
+<a for=Element>namespace prefix</a> are null.
+
+<p><a for=/>Elements</a> also have an associated
+<dfn export id=concept-element-shadow-root for=Element>shadow root</dfn> (null or a
+<a for=/>shadow root</a>). Null unless otherwise stated.
 
 <p>An <a for=/>element</a>'s <dfn id=concept-element-qualified-name for=Element>qualified name</dfn>
 is its <a for=Element>local name</a> if its <a for=Element>namespace prefix</a> is null, and its
@@ -5572,6 +5585,68 @@ method, when invoked, must run these steps:
 
 <hr>
 
+<dl class=domintro>
+ <dt><code>var shadow = <var>element</var> . {{attachShadow(init)}}</code>
+ <dd><p>Creates a <a for=/>shadow root</a> for <var>element</var> and returns it.
+
+ <dt><code>var shadow = <var>element</var> . {{shadowRoot}}</code>
+ <dd><p>Returns <var>element</var>'s <a for=Element>shadow root</a>, if any, and if
+ <a for=/>shadow root</a>'s <a for=ShadowRoot>encapsulation mode</a> is "<code>open</code>", and
+ null otherwise.
+</dl>
+
+<p>The <dfn method for=Element><code>attachShadow(<var>init</var>)</code></dfn> method, when
+invoked, must run these steps:
+
+<ol>
+ <li><p>If <a>context object</a> is not a <span class=XXX>custom element</span>, and is not an
+ <a for=/>element</a> whose <a for=Element>namespace</a> is the <a>HTML namespace</a> and
+ <a for=Element>local name</a> is
+ "<code>article</code>",
+ "<code>aside</code>",
+ "<code>blockquote</code>",
+ "<code>body</code>",
+ "<code>div</code>",
+ "<code>footer</code>",
+ "<code>h1</code>",
+ "<code>h2</code>",
+ "<code>h3</code>",
+ "<code>h4</code>",
+ "<code>h5</code>",
+ "<code>h6</code>",
+ "<code>header</code>",
+ "<code>nav</code>",
+ "<code>p</code>",
+ "<code>section</code>", or
+ "<code>span</code>", then throw a {{NotSupportedError}} exception.
+
+ <li><p>If <a>context object</a>'s <a for=Element>shadow root</a> is non-null, then throw a
+ {{InvalidStateError}} exception.
+
+ <li><p>Let <var>shadow</var> be a new <a for=/>shadow root</a> whose <a>node document</a> is
+ <a>context object</a>'s <a>node document</a>, <a for=DocumentFragment>host</a> is
+ <a>context object</a>, and <a for=ShadowRoot>encapsulation mode</a> is <var>init</var>'s
+ {{ShadowRootInit/mode}}.
+
+ <li><p>Set <a>context object</a>'s <a for=Element>shadow root</a> to <var>shadow</var>.
+
+ <li><p>Return <var>shadow</var>.
+</ol>
+
+<p>The <dfn attribute for=Element><code>shadowRoot</code></dfn> attribute's getter must run these
+steps:
+
+<ol>
+ <li><p>Let <var>shadow</var> be <a>context object</a>'s <a for=Element>shadow root</a>.
+
+ <li><p>If <var>shadow</var> is null or its <a for=ShadowRoot>encapsulation mode</a> is
+ "<code>closed</code>", then return null.
+
+ <li><p>Return <var>shadow</var>.
+</ol>
+
+<hr>
+
 <dl class=domintro>
  <dt><code><var>element</var> . {{closest(selectors)}}</code>
  <dd>Returns the first (starting at <var>element</var>)