Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Ryosuke Niwa
On Feb 15, 2014, at 11:30 PM, Alex Russell slightly...@google.com wrote:

 On Sat, Feb 15, 2014 at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:
 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.
 
 Throwing exceptions is hostile to usability.

If people are so inclined, we don’t have to throw an exception and silently 
fail.
 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.
 This doesn't seem like progress. I'd hope an imperative API would, instead, 
 be used to explain how the existing system works and then propose layering 
 that both accommodates the existing system and opens new areas for 
 programmatic use.
 
 We can imagine such a system for programmatic Shadow DOM with some sort of 
 distribute(Element) callback that can be over-ridden and use add/remove 
 methods to do final distribution.

The problem here is that such a callback must be called on every node upon any 
state change because UAs have no way of knowing what causes redistribution for 
a given component.  As as a matter of fact, some use cases may involve changing 
the node distributions based on some JS objects state.  And having authors 
codify such conditions for UAs is much more cumbersome than letting them 
re-distribute nodes at their will.

In terms of add/remove explaining “select” content attribute, we could describe 
node distribution as something that happens at the end of micro task via 
mutation observers.  In fact, we should probably spec as such.

 I'm deeply skeptical of appeals to defeat/elide layering on the basis of 
 performance arguments. Real-world systems often have fast-paths for common 
 operations and we should note that a self-hosted DOM would feel no particular 
 pain about calling back to JS. If your mental model is that the world is 
 C++ and JS is bolt-on, you're bound to get this continuously wrong.

Points 1 and 2 are mostly API advantages, not of performance.

- R. Niwa



Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Ryosuke Niwa
On Feb 16, 2014, at 12:42 AM, Ryosuke Niwa rn...@apple.com wrote:

 On Feb 15, 2014, at 11:30 PM, Alex Russell slightly...@google.com wrote:
 
 On Sat, Feb 15, 2014 at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:
 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.
 
 Throwing exceptions is hostile to usability.
 
 If people are so inclined, we don’t have to throw an exception and silently 
 fail.
 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.
 This doesn't seem like progress. I'd hope an imperative API would, instead, 
 be used to explain how the existing system works and then propose layering 
 that both accommodates the existing system and opens new areas for 
 programmatic use.
 
 We can imagine such a system for programmatic Shadow DOM with some sort of 
 distribute(Element) callback that can be over-ridden and use add/remove 
 methods to do final distribution.
 
 The problem here is that such a callback must be called on every node upon 
 any state change because UAs have no way of knowing what causes 
 redistribution for a given component.  As as a matter of fact, some use cases 
 may involve changing the node distributions based on some JS objects state.  
 And having authors codify such conditions for UAs is much more cumbersome 
 than letting them re-distribute nodes at their will.

To give you more concrete example, in the case of my random image element, how 
can UA notice that user clicking on the element should trigger reconstruction 
of the composed tree?  Should the script call some method like redistribute() 
on the host upon click?  But then, since the element needs to pick a child 
uniformly random, it probably needs to keep track of the number of children to 
be distributed and return true exactly when that node was passed into the 
callback.  That’s an extremely cumbersome API at least for my use case.

- R. Niwa



Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Alex Russell
On Sun, Feb 16, 2014 at 12:52 AM, Ryosuke Niwa rn...@apple.com wrote:

 On Feb 16, 2014, at 12:42 AM, Ryosuke Niwa rn...@apple.com wrote:

 On Feb 15, 2014, at 11:30 PM, Alex Russell slightly...@google.com wrote:

 On Sat, Feb 15, 2014 at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:

 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:

1. If the content element's shadow host's node tree doesn't contain _
*element*_, throw HierarchyRequestError.
2. If element is already in some other content element's _*explicitly
inserted nodes*_
then call remove with _*element*_ on that content element.
3. Append _*element*_ to the end of _*explicitly inserted nodes*_.


 remove(Element element) must act according to the following algorithm:

1. If the content element's _*explicitly inserted nodes*_ does not
contain _*element*_, throw NotFoundError.


 Throwing exceptions is hostile to usability.


 If people are so inclined, we don’t have to throw an exception and
 silently fail.


1. 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:

1. It doesn't require UA calling back to JS constantly to match
elements
2. Point 1 implies we don't expose when distribution happens for
select content attribute.

 This doesn't seem like progress. I'd hope an imperative API would,
 instead, be used to explain how the existing system works and then propose
 layering that both accommodates the existing system and opens new areas for
 programmatic use.

 We can imagine such a system for programmatic Shadow DOM with some sort of
 distribute(Element) callback that can be over-ridden and use add/remove
 methods to do final distribution.


 The problem here is that such a callback must be called on every node upon
 any state change because UAs have no way of knowing what causes
 redistribution for a given component.  As as a matter of fact, some use
 cases may involve changing the node distributions based on some JS objects
 state.  And having authors codify such conditions for UAs is much more
 cumbersome than letting them re-distribute nodes at their will.


 To give you more concrete example, in the case of my random image element,
 how can UA notice that user clicking on the element should trigger
 reconstruction of the composed tree?


Isn't the stated design of the custom element that it re-constructs the
composed tree with a random image every time it's clicked? It's not
actually clear what you wanted here because there isn't any example code to
go on.


  Should the script call some method like redistribute() on the host upon
 click?  But then, since the element needs to pick a child uniformly random,
 it probably needs to keep track of the number of children to be distributed
 and return true exactly when that node was passed into the callback.
  That’s an extremely cumbersome API at least for my use case.


I have the sense that if you produced example code you'd be able to make a
better guess about what's onerous and what isn't. As it is, we're debating
hypotheticals.

Here's a version of your component 

Re: [manifest] Utility of bookmarking to home screen, was V1 ready for wider review

2014-02-16 Thread Marcos Caceres
On Sunday, February 16, 2014, Alex Russell slightly...@google.com wrote:

 On Sat, Feb 15, 2014 at 5:56 AM, Marcos Caceres 
 w...@marcosc.comjavascript:_e(%7B%7D,'cvml','w...@marcosc.com');
  wrote:

 tl;dr: I strongly agree (and data below shows) that installable web apps
 without offline capabilities are essentially useless.

 Things currently specified in the manifest are supposed to help make
 these apps less useless (as I said in the original email, they by no means
 give us the dream of installable web apps, just one little step closer) -
 even if we had SW tomorrow, we would still need orientation, display mode,
 start URL, etc.

 So yes, SW and manifest will converge... questions for us to decide on is
 when? And if appcache can see us through this transitional period to having
 SW support in browsers? I believe we can initially standardize a limited
 set of functionality, while we continue to wait for SW to come into
 fruition which could take another year or two.


 SW will becoming to chrome ASAP. We're actively implementing. Jonas or
 Nikhil can probably provide more Mozilla context.


I'm also interested in the WebKit and Microsoft context. I just don't know
who to ask there. Have their been any public signals of their level of
interest in SW?


My personal view is that isn't not a good user experience to offer the
 affordance if the resulting system can't be trusted. That is to say, if we
 plow on with V1 without a (required) offline story, I'm not sure what we've
 really won. Happy for this to go to LC, but wouldn't recommend that Chrome
 For Android implement.


I think this is good feedback. I'm happy to add (or for you to add;)) SW
support to the manifest format. At least from Moz perspective it's fine as
we are doing SW already.

Anyone object to adding SW support to V1 of the manifest spec? Anything
else that should be prioritized for V1?





 On Saturday, February 15, 2014 at 1:37 AM, Alex Russell wrote:

  I further think that the marginal utility in bookmarking something to
 the homescreen (sorry, yes, I'm focusing on mobile first) is low if it
 doesn't have a Service Worker / Appcache associated.

 Although I've not published this research yet, this is strongly backed by
 evidence. Nearly all applications in the top 78,000 websites that opt. into
 being standalone applications via apple-mobile-web-app-capable do not, in
 fact, work as standalone applications. If anyone is interested to try this
 for themselves, here is the raw dataset listing all the sites [1] - you
 will need an iPhone to test them. The data set is from Oct. 2013, but
 should still be relevant. Just pick some at random and add to homescreen;
 it makes for depressing viewing.

 There are a few exceptions (listed below) - but those are the exceptions,
 not the rule.
  It's strictly second-class-citizen territory to have web bookmarks
 that routinely don't do anything meaningful when offline.

 Yes, but there are a number of factors that contribute to this: not just
 offline (e.g., flexbox support is still fairly limited, dev tools still
 suck, cross-browser is a nightmare, even how navigation works differs
 across UAs!, limited orientation-locking support, etc.).

 However, to your point the data we have shows that about 50 sites in the
 top 78K declare an appcache [2], while there are 1163 sites that declare
 apple-mobile-web-app-capable. So yeah, appcache, as we all know, is a bit
 of a failure. Some of the sites that declare it actually have it commented
 out... like they tried it and just gave up.

 Interestingly, only 10 sites in the dataset are both capable of running
 standalone AND declare offline:

 1. forecast.io
 2. timer-tab.com
 3. capitalone.com
 4. rachaelrayshow.com
 5. delicious.com
 6. forbesmiddleeast.com
 7. shopfato.com.br
 8. ptable.com
 9 authenticjobs.com

 10. swedenabroad.com

 So, yeah... 10 / 1163 = 0.0085... or, :_(.

 Anyway... do you think it's ok for us to just standardize the limited
 things in the manifest? We could have those at LC like in 2 weeks and then
 spin up V2 to have convergence with SW. Better still, the SW spec can just
 specify how it wants to work with manifests.

 [1] https://gist.github.com/marcoscaceres/7419589
 [2] https://gist.github.com/marcoscaceres/9018819
 --
 Marcos Caceres







[Bug 24628] spec has (almost) no style (or scripts)

2014-02-16 Thread bugzilla
https://www.w3.org/Bugs/Public/show_bug.cgi?id=24628

Ms2ger ms2...@gmail.com changed:

   What|Removed |Added

 Status|NEW |RESOLVED
 Resolution|--- |FIXED
   Assignee|a...@aryeh.name  |ms2...@gmail.com

--- Comment #2 from Ms2ger ms2...@gmail.com ---
Forgot this was filed as a bug too. I fixed this earlier:

https://dvcs.w3.org/hg/editing/rev/28f516366550

-- 
You are receiving this mail because:
You are on the CC list for the bug.



Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Ryosuke Niwa

 On Feb 15, 2014, at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:
 
 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.
I'm sorry I don't know what was reading. The strawman proposal on the bug is 
basically what I'm proposing.  add/remove are simply on distributedChildren 
instead.

In fact, the stated design is probably better than what I have here now that we 
have getDistributedNodes() on content element.

I think we just need to turn that into a Static/Live NodeList with add/remove.  
I would prefer the name distributedNodes.

One important implication of adding this API surface is that the node 
distribution from declarative syntax also needs to happen at the end of each 
micro task as opposed to happen implicitly after each DOM mutation if we wanted 
to formulate the mutation observer as a way of implementing select content 
attribute.

Since this is visible to the scripts, it's important to take it into the 
account in the level 1 specification.

- R. Niwa

Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Maciej Stachowiak
On Feb 15, 2014, at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:Hi all,I’d like to propose one solution for[Shadow]: Specify imperative API for node distributionhttps://www.w3.org/Bugs/Public/show_bug.cgi?id=18429because 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="" img src="" img src=""/random-image-elementrandom-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 elementsbut I would rather use shadow DOM to encapsulate the implementation.I wanted to mention that this handles other use cases besides selecting a random child which are impossible (or at least very awkward) with contentselect="" as presently defined:(1) A container component that can hold an arbitrary number of children, and wraps each of its light DOM children in a piece of markup inside the ShadowDOM. Consider a buttonbar component that placed each child into a button, and styled them all specially:buttonbar  i _onclick_="execCommand('italic')"I/i  b _onclick_="execCommand('bold')B/b  u _onclick_="execCommand('underline')U/ubuttonImagine it would render like this (explaining why separate individual button elements won't cut it).(2) A component that expects alternate labels and corresponding items, wants to parent them into different boxes, but wants to make sure they remaincorresponding.tabview  tabtitlePuppies/tabtitle  tabpane lots of pictures of puppies /tabpane  tabtitleKittens/tabtitle  tabpane lots of pictures of kittens /tabpane  tabtitleSadness/tabtitle  !-- no tab pane provided for this title yet --  tabtitleBunnies/tabtitle  tabpane lots of pictures of bunnies .../tabpane/tabviewThe component author would like this to render as a tabview with 4 tab labels at the top ("Puppies", "Kittens", "Sadness", "Bunnies") and 3 actual tab paneswith one placeholder inserted: (the puppy pane, the kitten pane, a blank placeholder, the bunny pane).But if my shadow DOM looks like this:div class=tab-label-barcontent select="tabtitle"/divdiv class=tab-holdercontent select="tabpane"/divThen the pictures of bunnies would line up with the "Sadness" label, and I don't have an easy way to add the placeholder anywhere but at the beginning or theend of the tab panes.(3) An element that selects some of its children conditionally. Let's say you have an element that will select different children depending on what features thebrowser supports:cond  case condition="Modernizr.webgl"Spiffy WebGL view goes here!/case  case condition="Modernizr.canvas"Passable 2-D canvas view goes here/case  case defaultOh noes! You need more browser features to use this site!/case/condThe idea is to select in only exactly one of the cases - the first that matches. The others don't go into the shadow DOM. There isn't a great way to select only one of the "case" elements here (after having run the JS to evaluate which applies).The SVG "switch" element does something similar, as does Modernizr's normal class-based mode of operation.I hope these examples give more motivation for why programmatically binding an insertion point may be useful.Regards,Maciej

Re: [webcomponents] Imperative API for Insertion Points

2014-02-16 Thread Ryosuke Niwa

 On Feb 16, 2014, at 1:21 AM, Alex Russell slightly...@google.com wrote:
 
 On Sun, Feb 16, 2014 at 12:52 AM, Ryosuke Niwa rn...@apple.com wrote:
 On Feb 16, 2014, at 12:42 AM, Ryosuke Niwa rn...@apple.com wrote:
 
 On Feb 15, 2014, at 11:30 PM, Alex Russell slightly...@google.com wrote:
 
 On Sat, Feb 15, 2014 at 4:57 PM, Ryosuke Niwa rn...@apple.com wrote:
 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.
 
 Throwing exceptions is hostile to usability.
 
 If people are so inclined, we don’t have to throw an exception and silently 
 fail.
 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.
 This doesn't seem like progress. I'd hope an imperative API would, 
 instead, be used to explain how the existing system works and then propose 
 layering that both accommodates the existing system and opens new areas 
 for programmatic use.
 
 We can imagine such a system for programmatic Shadow DOM with some sort of 
 distribute(Element) callback that can be over-ridden and use add/remove 
 methods to do final distribution.
 
 The problem here is that such a callback must be called on every node upon 
 any state change because UAs have no way of knowing what causes 
 redistribution for a given component.  As as a matter of fact, some use 
 cases may involve changing the node distributions based on some JS objects 
 state.  And having authors codify such conditions for UAs is much more 
 cumbersome than letting them re-distribute nodes at their will.
 
 To give you more concrete example, in the case of my random image element, 
 how can UA notice that user clicking on the element should trigger 
 reconstruction of the composed tree?
 
 Isn't the stated design of the custom element that it re-constructs the 
 composed tree with a random image every time it's clicked? It's not actually 
 clear what you wanted here because there isn't any example code to go on.
  
  Should the script call some method like redistribute() on the host upon 
 click?  But then, since the element needs to pick a child uniformly random, 
 it probably needs to keep track of the number of children to be distributed 
 and return true exactly when that node was passed into the callback.  That’s 
 an extremely cumbersome API at least for my use case.
 
 I have the sense that if you produced example code you'd be able to make a 
 better guess about what's onerous and what isn't. As it is, we're debating