[css-shadow-parts-1] Add algorithm description. Fixes w3c#2650

Author: fergald

css-shadow-parts-1/Overview.bs

@@ -24,10 +24,7 @@ Introduction {#intro}
 =====================
 
 Issue: This spec is intentionally a rough sketch at the moment.
-It should contain all the details necessary to evaluate the proposal,
-but is intentionally avoiding precise algorithms at the moment,
-to aid in easy comprehension
-and to, hopefully, discourage implementation from this sketch.
+It should contain all the details necessary to evaluate the proposal.
 
 Shadow DOM allows authors to separate their page into "components",
 subtrees of markup whose details are only relevant to the component itself,
@@ -121,34 +118,64 @@ as authors can use ''::part()'' without fear of accidental over-styling.
 
 Exposing a Shadow Element: {#exposing}
 =============================================================
-Each <a>shadow root</a> has a <dfn export for="shadow root">shadow part map</dfn>
+Elements in a <a>shadow tree</a> may be exposed for styling by stylesheets outside the tree
+using the part and partmap attributes.
+
+Each element has a <dfn export for="element">part name list</dfn>
+which is an [=ordered sets=] of tokens.
+
+Each element has a <dfn export for="element">part name map</dfn>
 which is an <a>ordered map</a>,
+with keys that are tokens
+and values that are [=ordered sets=] of tokens.
+
+Each <a>shadow root</a> can be thought of as having a <dfn export for="shadow root">part element map</dfn>
 with keys that are [=strings=]
 and values that are [=ordered sets=] of elements.
 
-The <a>shadow part map</a> contains all the entries named or forwarded by the elements in its <a>shadow tree</a>,
-as described below.
+The part element map is described
+only as part of the algorithm for calculating style in this spec.
+It is not exposed via the DOM,
+as calculating it may be expensive
+and exposing it could allow access to elements inside closed shadow roots.
+
+Part element maps are affected by the addition and removal of elements
+and changes to the part name lists and part name maps of elements in the DOM.
+
+To calculate the part element map of a shadow root, |r|:
+
+<ol>
+	<li>For each element, |el| within |r|
+	  <ol>
+		  <li>For each |name| in |el|'s part name list,
+        add |el| to |r|'s part element map
+        under the key |name|.
+      <li>If |el| is a shadow host itself, let |er| be its shadow root:
+        <ol>
+          <li>Calculate |er|'s part element map.
+          <li>For each key, |outerName|, in |r|'s part name map
+            and for each token |innerName| under that key
+            look up |innerName| in |er|'s shadow part element map
+            to get a (possibly empty) set of elements
+            and add these elements to |r|'s part element map under |outerName|
+        </ol>
+		</ol>
+</ol>
+
+
+Issue: Include wild-card forwarding in algortihm.
 
-Issue: Factor this out into an algorithm.
+Issue: When doing prefixed-wildcard forwarding, should probably automatically exclude sub-parts that are manually forwarded.  With that, would be good to have a syntax to block forwarding of a sub-part (currently would require `foo => nonsense-name`).
 
-Issue: The value in the map is a set of elements, not individual elements; need to properly append.
+Issue: There is no need for the part element map values to be ordered, can we drop that?
 
 Naming a Shadow Element: the <{html-global/part}> attribute {#part-attr}
 ------------------------------------------------------------------------
 
 Any element in a shadow tree can have a <dfn element-attr for=html-global>part</dfn> attribute.
 This is used to expose the element outside of the <a>shadow tree</a>.
 
-The part attribute is parsed as a space-separated list of part names.
-Each part name is:
-
-<dl class=switch>
-    : <code>ident</code>
-    :: Adds «[ ident → el ]» to the <a>shadow part map</a> of the <a>shadow root</a> containing the element.
-
-    : anything else
-    :: Ignored for error-recovery / future compat.
-</dl>
+The part attribute is parsed as a space-separated list of tokens representing the part names of this element.
 
 Note: It's okay to give a part multiple names.
 The "part name" should be considered similar to a class,
@@ -158,33 +185,32 @@ Forwarding a Shadow Element: the <{html-global/partmap}> attribute {#partmap-att
 ----------------------------------------------------------------------------------
 Any element in a shadow tree can have a <dfn element-attr for=html-global>partmap</dfn> attribute.
 If the element is a shadow host,
-this is used to expose elements from inside this host's <a>shadow tree</a> to outside this host's containing <a>shadow tree</a>.
+this is used to allow styling of parts from hosts inside the <a>shadow tree</a>
+by rules outside this the <a>shadow tree</a>
+(as if they were elements in the same tree as the host,
+named by a part attribute).
 
 The partmap attribute is parsed as a comma-separated list of part mappings.
 Each part mapping is one of:
 
 <dl class=switch>
-    : <code>ident1 => ident2</code>
-    :: If el is a <a>shadow host</a>,
-        and it's <a>shadow root's</a> <a>shadow part map</a> |partMap| [=map/contains=] ident1,
-        then this adds «[ ident2 → |partMap|[ident1] ]» to the <a>shadow part map</a> of the <a>shadow root</a> containing el.
+    : <code>outerIdent => innerIdent</code>
+    :: this adds «[ outerIdent → innerIdent ]» to el's <a>part name map</a>.
 
     : <code>ident</code>
     :: Is equivalent to <code>ident => ident</code>.
 
-    : <code>* => prefix*</code>
-    :: If el is a <a>shadow host</a>,
-        then [=map/for each=] |ident| → |subEl| in el's <a>shadow root's</a> <a>shadow part map</a>,
-        «[ prefix + |ident| → |subEl| ]» is added to the <a>shadow part map</a> of the <a>shadow root</a> containing el.
-
     : anything else
     :: Ignored for error-recovery / future compat.
 </dl>
 
-Issue: When doing prefixed-wildcard forwarding, should probably automatically exclude sub-parts that are manually forwarded.  With that, would be good to have a syntax to block forwarding of a sub-part (currently would require `foo => nonsense-name`).
-
 Note: It's okay to map a sub-part to several names.
 
+Issue: Decide whether we use "outer => inner" or vice-versa.
+
+Issue: Decide whether to allow "ident1 => ident2 ident3 ..."
+as shorthand for "ident1 => ident2, ident1 => ident3, ...".
+
 Exposing More Widely: the <{html-global/theme}> attribute {#theme-attr}
 -----------------------------------------------------------------------
 
@@ -221,7 +247,7 @@ The syntaxes of them are:
 
 The ''::part()'' pseudo-element only matches anything
 when the <a>originating element</a> is a <a>shadow host</a>.
-If the <a>originating element's</a> <a>shadow root's</a> <a>shadow part map</a>
+If the <a>originating element's</a> <a>shadow root's</a> <a>part element map</a>
 [=map/contains=] the specified <<ident>>,
 ''::part()'' matches the element or elements keyed to that <<ident>>.
 Otherwise, it matches nothing.
@@ -272,7 +298,7 @@ but never match additional <a>shadow-part pseudo-elements</a>.
 
     If the <code>&lt;x-panel></code>'s internal confirm button had used something like
     <code>part="confirm-button, * => confirm-*"</code>
-    to forward the button's internal parts up into the panel's own <a>shadow part map</a>,
+    to forward the button's internal parts up into the panel's own <a>part element map</a>,
     then a selector like
     ''x-panel::part(confirm-label)''
     would select just the one button's label,