Dimitri Glazkov dglazkov

#The Shadow DOM Diaries

Feature design is hard, and takes time. With time, it doesn't matter how public and consistent you are with communication during design process. In the end, it all will look like a jumbled mess of emails and bug comments. That seems bad. To make things less bad, I decided to start writing these little docs. Here they are. I may add more. Or not. Whatevs.

Sometimes You Need to Build a Larger Thing First looks back at the road we've traveled.

Shadow DOM Evolution outlines the path forward.

Why Do We Only Allow Children in Insertion Points provides a glimpse into the reasoning behind current insertion point design.

#Composition is the Goal

I see several discussions now that vacillate around on encapsulation qualities of Shadow DOM and the flavors thereof. It's all my fault. I stuck encapsulation into the problem statement of the spec. I even glued the somewhat irrelevant term functional encapsulation on top of it. What a dork.

It was a couple of years ago, when one of my colleagues read the spec and noted: "Dude, it's like your story and whatever, but the way you tell it, Shadow DOM is not about encapsulation. It's about composition". The world went blank around me. I was blinded by insight.

My hipster colleague was right, of course. Encapsulation is just a tool. Composition is the goal.

This is why the people who'd never used Shadow DOM in real life get really hung up on the details of encapsulation, while those who actually use Shadow DOM stare at them quizzically.

#Shadow DOM Imperative API Brainstorming

##Reduced test case:

<div>
  <template shadow> <!-- shadow root -->
    <details>
      <content></content>

Easy Way to Grok Insertion Points

Suppose you're writing a Polymer app. It's a grocery list app to rule all grocery list apps. In it, you have this <grocery-completion> component:

used as:
<grocery-completion data="{{groceries}}"></grocery-completion>

defined as:
<link rel="import" href="../elements/grocery-ingredient-chooser.html">

I am a Widget Building Man. I bulid widgets. All my widgets are custom elements. Each of my elements has a shadow tree that contains styles.

Situation 1: My widgets share the same set of styles, which makes them consistent and awesome. I keep this set of styles in awesome.css.

Situation 2: Some of my widgets have styles that are long and boring. I want to split them into a separate file, instead of using the style element.

In both situations:

What's the easy-peasy HTML syntax for doing this?
There's a distinct FOUC moment between instantiating the widget's shadow tree and the styles being available. How do I control that?

Definition of the Multiple-actor Problem

The Multiple-actor Problem (MAP) occurs in a web application that contains multiple bits of code, each assuming that they are the only actor in the document. The problem manifests when these assumptions conflict with each other.

Some examples:

A web app is written in framework A, then later an analytics script B is added. A makes assumptions about lifetime of elements and handling of events. B is not aware of these assumptions and subtly violates them, causing jank (example)
A web app is written using framework A. Attempting to introduce a widgets built using framework B results in weird errors, because B is violating A's assumptions about control of document state (examples 1, [2](http://stackoverflow.com/questions/254

	<element extends="table" name="x-table-chart" constructor="TableChart">
	<script>

	this.lifecycle({
	created: function(shadowRoot) {
	this._canvas = shadowRoot.firstChild;
	this.draw();
	},
	attributeChanged: function(name, oldValue, newValue) {
	if (!name.startsWith('x-chart-'))

	/* Scenario A:
	The most naive example of what a developer expects.
	*/
	div.innerHTML = '<foo-bar></foo-bar>';
	// <foo-bar>'s readyCallback must be called here.
	div.firstChild.methodOnFooBar();

	/* Scenario B:
	HTMLInputElement as Custom Element, Part 1.
	*/

	// stays as is
	class FontDescription;

	// stays as is
	class FontData;

	class FontContext : public RefCounted<FontContext> {
	PassRefPtr<FontData> getFontData(const FontDescription&);
	void addFontDataProvider(const AtomicString& familyName,
	PassRefPtr<FontDataProvider>);

	<link rel="import" href="../core-scaffold/core-scaffold.html">
	<link rel="import" href="../core-header-panel/core-header-panel.html">
	<link rel="import" href="../core-menu/core-menu.html">
	<link rel="import" href="../core-item/core-item.html">
	<link rel="import" href="../core-icon-button/core-icon-button.html">
	<link rel="import" href="../core-toolbar/core-toolbar.html">
	<link rel="import" href="../core-menu/core-submenu.html">
	<link rel="import" href="../core-icons/core-icons.html">
	<link rel="import" href="../paper-item/paper-item.html">
	<link rel="import" href="../core-animated-pages/core-animated-pages.html">