1 | # Custom Elements v1
|
2 |
|
3 | ## Status
|
4 |
|
5 | The polyfill should be mostly feature complete now. It supports defining
|
6 | custom elements, the custom element reactions, and upgrading existing elements. It integrates with native Shadow DOM v1, and native and polyfilled HTML Imports.
|
7 |
|
8 | The implementation could use more tests, especially around ordering of
|
9 | reactions. 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 |
|
52 | The 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 |
|
54 | The implementation should work without additional polyfills in IE 11, Edge, Safari >6, Firefox, Chrome, Android Browser >4.4, and Opera (not Mini).
|
55 |
|
56 | IE 10 should be supported with the Mutation Observer polyfill.
|
57 |
|
58 | This 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 |
|
60 | Because 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 |
|
64 | The 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 |
|
66 | The 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 |
|
70 | To 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 |
|
74 | The Custom Elements V1 polyfill does not use the same module or build system as
|
75 | the other webcomponentsjs polyfills, and its build is not integrated into the default build tasks yet.
|
76 |
|
77 | To build run:
|
78 |
|
79 | gulp
|
80 |
|
81 | This 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 |
|
87 | https://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 |
|
96 | https://dom.spec.whatwg.org/#concept-node-clone
|
97 |
|
98 | * clone 2.1: performs create-element
|
99 | * clone 2.2: append attributes
|
100 |
|
101 | isConnected 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 |
|
105 | https://dom.spec.whatwg.org/#interface-document
|
106 |
|
107 | * createElement and createElementNS take ElementCreationOptions
|
108 |
|
109 | https://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 |
|
116 | https://dom.spec.whatwg.org/#concept-element-custom-element-state
|
117 |
|
118 | https://dom.spec.whatwg.org/#concept-create-element
|
119 |
|
120 | * create an element 2, 3, 4, 5, 6
|
121 |
|
122 | https://dom.spec.whatwg.org/#concept-element-attributes-change
|
123 |
|
124 | * change an attribute 2
|
125 |
|
126 | https://dom.spec.whatwg.org/#concept-element-attributes-append
|
127 |
|
128 | * append an attribute 2
|
129 |
|
130 | https://dom.spec.whatwg.org/#concept-element-attributes-remove
|
131 |
|
132 | * remove an attribute 2
|
133 |
|
134 | https://dom.spec.whatwg.org/#concept-element-attributes-replace
|
135 |
|
136 | * replace an attribute 2
|
137 |
|
138 | https://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 |
|
147 | https://html.spec.whatwg.org/multipage/dom.html#html-element-constructors
|
148 |
|
149 | * HTML element constructors 1-9
|
150 |
|
151 | ### 4.13 Custom Elements
|
152 |
|
153 | https://html.spec.whatwg.org/multipage/scripting.html#custom-elements
|
154 |
|
155 | https://html.spec.whatwg.org/multipage/scripting.html#valid-custom-element-name
|
156 |
|
157 | https://html.spec.whatwg.org/multipage/scripting.html#customelementsregistry
|
158 |
|
159 | ### 7.3 Window
|
160 |
|
161 | https://html.spec.whatwg.org/multipage/browsers.html#window
|
162 |
|
163 | * Window#customElements
|
164 |
|
165 | https://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
|