UNPKG

6.31 kBMarkdownView Raw
1# Custom Elements v1
2
3## Status
4
5The polyfill should be mostly feature complete now. It supports defining
6custom elements, the custom element reactions, and upgrading existing elements. It integrates with native Shadow DOM v1, and native and polyfilled HTML Imports.
7
8The implementation could use more tests, especially around ordering of
9reactions. The source references old versions of the spec.
10
11### To do
12
13 1. Implement Node#isConnected
14 2. Implement built-in element extension (is=)
15 3. Add reaction callback ordering tests
16 4. Reorganize tests to be closer to spec structure
17 5. Performance tests
18
19## Building & Running Tests
20
21 1. Install web-component-tester
22
23 ```bash
24 $ npm i -g web-component-tester
25 ```
26
27 2. Checkout the webcomponentsjs v1 branch
28
29 ```bash
30 $ git clone https://github.com/webcomponents/webcomponentsjs.git
31 $ cd webcomponentsjs
32 $ npm i
33 $ gulp build
34 ```
35
36 3. Run tests
37
38 ```bash
39 $ wct tests/CustomElements/v1/index.html -l chrome
40 ```
41
42 4. Bower link to use in another project
43
44 ```bash
45 $ bower link
46 $ cd {your project directory}
47 $ bower link webcomponentsjs
48 ```
49
50## Implementation approach and browser support
51
52The polyfill leans heavily on MutationObservers to drive custom element creation and reactions. This means that the polyfill requires native or polyfilled MutationObservers. The polyfill also uses Map and Set, though those would be easy to polyfill or remove.
53
54The implementation should work without additional polyfills in IE 11, Edge, Safari >6, Firefox, Chrome, Android Browser >4.4, and Opera (not Mini).
55
56IE 10 should be supported with the Mutation Observer polyfill.
57
58This branch does not pass the CI tests yet, but it passes locally in Chrome 52, Safari 9.1, Safari Technical Preview, and Firefox 47.
59
60Because MutationObservers are used to create custom element instances and react to document structure and attribute changes, all reactions are asynchronous while in the specs, some are synchronous. This is by design, since some of the synchronous reactions are impossible to polyfill. We consider it more important that reactions have the same relative timing to each other as the spec, for example attributeChangedCallback happens after connectedCallback.
61
62### Implementing the "Constructor-call Trick"
63
64The HTMLElement constructor is now specified to return a different object than `this`, so that the parser and upgrades can call the constructor on elements that have already been allocated. JavaScript allows this, but some compilers, such as TypeScript and Closure currently don't.
65
66The HTMLElement constructor is also specified to look up the tag name associated with a constructor by using `new.target`. `new.target` isn't available in ES5, is not polyfillable, but `this.constructor` behaves similarly for most ES5 class patterns, including the output of Babel, TypeScript and Closure, so the polyfill uses that to look up tag names.
67
68`new.target` isn't even feature detectable, since it's a syntax error in ES5. Because of this, the polyfill can't check `new.target` first and fallback to `this.constructor`. This also means that ES5-style constructors can't conditionally make a "super" call to the HTMLElement constructor (with `Reflect.construct`) in non-ES6 environments to be compatible with native Custom Elements.
69
70To allow for elements that work in both ES5 and ES6 environments, we provide a shim to be used in browsers that have native Custom Elements v1 support, that overrides the HTMLElement constructor and calls `Reflect.construct` with either the value of `new.target` or `this.constructor`. This shim can only be executed in ES6 environments that support `new.target`, and so should be conditionally loaded. The shim and the polyfill should not be loaded at the same time.
71
72## Building
73
74The Custom Elements V1 polyfill does not use the same module or build system as
75the other webcomponentsjs polyfills, and its build is not integrated into the default build tasks yet.
76
77To build run:
78
79 gulp
80
81This creates a `custom-elements.min.js` file in the main directory.
82
83## Custom Elements in the DOM Spec
84
85### 4.2.3 Mutation Algorithms
86
87https://dom.spec.whatwg.org/#mutation-algorithms
88
89 * insert 6.5.2.1: call connectedCallback
90 * insert 6.5.2.2: upgrade
91 * remove 14: call disconnectedCallback
92 * remove 15.2: call disconnectedCallback
93
94### 4.4 Node
95
96https://dom.spec.whatwg.org/#concept-node-clone
97
98 * clone 2.1: performs create-element
99 * clone 2.2: append attributes
100
101isConnected looks like it's Custom Elements related, but it's actually part of Shadow DOM. We might want to implement it for on non-native Shadow DOM environments, since we already watch for all connections and disconnections.
102
103### 4.5 Document
104
105https://dom.spec.whatwg.org/#interface-document
106
107 * createElement and createElementNS take ElementCreationOptions
108
109https://dom.spec.whatwg.org/#dom-document-createelement
110
111 * createElement 3, 4, 5, 7
112 * createElementNS 2, 3, 4, 5
113
114### 4.9 Element
115
116https://dom.spec.whatwg.org/#concept-element-custom-element-state
117
118https://dom.spec.whatwg.org/#concept-create-element
119
120 * create an element 2, 3, 4, 5, 6
121
122https://dom.spec.whatwg.org/#concept-element-attributes-change
123
124 * change an attribute 2
125
126https://dom.spec.whatwg.org/#concept-element-attributes-append
127
128 * append an attribute 2
129
130https://dom.spec.whatwg.org/#concept-element-attributes-remove
131
132 * remove an attribute 2
133
134https://dom.spec.whatwg.org/#concept-element-attributes-replace
135
136 * replace an attribute 2
137
138https://dom.spec.whatwg.org/#dom-element-attachshadow
139
140 * attachShadow 2 (nothing to implement)
141
142## Custom Elements in the HTML Spec
143
144
145### 3.2.3 HTML element constructors
146
147https://html.spec.whatwg.org/multipage/dom.html#html-element-constructors
148
149 * HTML element constructors 1-9
150
151### 4.13 Custom Elements
152
153https://html.spec.whatwg.org/multipage/scripting.html#custom-elements
154
155https://html.spec.whatwg.org/multipage/scripting.html#valid-custom-element-name
156
157https://html.spec.whatwg.org/multipage/scripting.html#customelementsregistry
158
159### 7.3 Window
160
161https://html.spec.whatwg.org/multipage/browsers.html#window
162
163 * Window#customElements
164
165https://html.spec.whatwg.org/multipage/syntax.html#create-an-element-for-the-token
166
167 * create an element for a token 3, 4, 5, 6, 7, 8, 9