Shadow DOM Design Constraints In Examples

Simple Component

Calendar

In HTML:

<basic-calendar-month></basic-calendar-month>

In JS:

var calendar = document.createElement("basic-calendar-month");

place.appendChild(calendar);

console.log(calendar.firstChild); // null

// suppose that #monthTable is an element inside of calendar
console.log(document.querySelector('#monthTable')); // null

document.body.addEventListener('click', function(evt) {
  console.log(evt.target.id); // should never return monthTable
});

document.body.addEventListener('mouseenter', function(evt) {
  console.log(evt.relatedTarget.id); // should never return monthTable
});

Constraints:

• Implementation details are not accessible using standard DOM traversal/query APIs: Node, ParentNode, Element, etc.)
• When traversing implementation details, you can't easily walk out.
• Event target values do not leak implementation details.
• Active element values do not leak implementation details.
• You can style implementation details with scoped <style> element (Early tabs control example that illustrates the need for style scoping )
• Style selectors in the document do not match inside of the implementation details
• Style selectors in the implementation details do not match in the document.

Inherited Components

Example:

Constraints:

Component With One Insertion Point

Basic Carousel

In HTML:

<basic-carousel>
 <img id="image1" src="../basic-sequence/images/image1.jpg">
 <img src="../basic-sequence/images/image2.jpg">
 <img src="../basic-sequence/images/image3.jpg">
 <img src="../basic-sequence/images/image4.jpg">
 <img src="../basic-sequence/images/image5.jpg">
</basic-carousel>

In JS:

var carousel = document.querySelector('basic-carousel');

console.log(carousel.firstChild.id == 'image1'); // returns true

console.log(carousel.childElementCount);; // returns 5

carousel.appendChild(anotherImage); // does not break carousel

carousel.removeChild(anotherImage); // does not break carousel

Constraints:

• Enable rendering the children of an element at an arbitrary place in the DOM sub-tree that represents the internal implementation details.
• Element's children are are always its direct children according to standard DOM traversal/query APIs: Node, ParentNode, Element, etc.)
• Similarly, no additional children from implementation details are detectable by these DOM APIs.
• Mutating the list of children does not require any knowledge of the implementation details.

Component With Several Insertion Points

Example: (tab strip)

Constraints:

• Need a way to select which children go into which insertion point.
• Let internal implementation details style children, distributed into the insertion point.
• Let internal implementation known which child is distributed into which insertion point.
• Distribution needs to happen before child style is computed

Nested Components

Example: my-editing-bar + my-zebra

Constraints:

• The outside of implementation details is not always main document. Sometimes it's the implementation details of another component.
• Another component's insertion point may end up being a child of the component.

Component Use In Real World

Examples:

Constraints:

• A way to occasionally pierce style-scoping boundaries
• A way to introspect shadow trees