[webcomponents] Imperative API for Insertion Points

Hi all,

I’d like to propose one solution for

[Shadow]: Specify imperative API for node distribution
https://www.w3.org/Bugs/Public/show_bug.cgi?id=18429

because select content attribute doesn’t satisfy the needs of framework/library authors to support conditionals in their templates,
and doesn’t satisfy my random image element use case below.


== Use Case ==
Random image element is a custom element that shows one of child img elements chosen uniformally random.

e.g. the markup of a document that uses random-image-element may look like this:
<random-image-element>
  <img src="kitten.jpg">
  <img src="cat.jpg">
  <img src="webkitten.jpg">
</random-image-element>

random-image-element displays one out of the three img child elements when a user clicks on it.

As an author of this element, I could modify the DOM and add style content attribute directly on those elements
but I would rather use shadow DOM to encapsulate the implementation.


== API Proposal ==

Add two methods void add(Element) and void remove(Element) to content element.
(We can give them more descriptive names. I matched select element for now).

Each content element has an ordered list of *explicitly inserted nodes*.

add(Element element) must act according to the following algorithm:
If the content element's shadow host's node tree doesn't contain _element_, throw HierarchyRequestError.
If element is already in some other content element's _explicitly inserted nodes_
then call remove with _element_ on that content element.
Append _element_ to the end of _explicitly inserted nodes_.

remove(Element element) must act according to the following algorithm:
If the content element's _explicitly inserted nodes_ does not contain _element_, throw NotFoundError.
Remove _element_ from _explicitly inserted nodes_.

The idea here is that _explicitly inserted nodes_ of an insertion point A would be the list of distributed nodes of A but
I haven't figured out exactly how _explicitly inserted nodes_ should interact with select content attribute.

I think the simplest model would be _explicitly inserted nodes_ simply overriding whatever select content attribute was
trying to do but I don't have a strong opinion about how they should interact yet.

I don't think it makes sense to support redistributions, etc... at least in the initial API.


This proposal has an advantage over the existing proposal on https://www.w3.org/Bugs/Public/show_bug.cgi?id=18429:
It doesn't require UA calling back to JS constantly to match elements
Point 1 implies we don't expose when distribution happens for select content attribute.

- R. Niwa