Re: [webcomponents] Imperative API for Insertion Points

On Sat, Feb 15, 2014 at 4:57 PM, Ryosuke Niwa <rniwa@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.


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

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.

Regards