Use better words about the bundles and the loader#693
Conversation
| - **Custom Elements**: allows authors to define their own custom tags ([spec](https://w3c.github.io/webcomponents/spec/custom/)). | ||
| - **HTML Imports**: a way to include and reuse HTML documents via other HTML documents ([spec](https://w3c.github.io/webcomponents/spec/imports/)). | ||
| - **Shadow DOM**: provides encapsulation by hiding DOM subtrees under shadow roots ([spec](https://w3c.github.io/webcomponents/spec/shadow/)). | ||
|
|
There was a problem hiding this comment.
List the other minor polyfills this provides under an "Other minor polyfills" bullet?
HTMLTemplateElementPromiseunresolvedattribute shim for::unresolvedEvent,CustomEvent,MouseEventconstructorsObject.assign,Array.from
| - `webcomponents-lite` -- all of the polyfills: HTML Imports, Custom Elements, Shady DOM/CSS and generic platform polyfills (such as Template, ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11) | ||
|
|
||
| If you are only targetting a specific browser, you can just use the bundle that's | ||
| needed by it; alternatively, if you're using server-side rendering, you can |
There was a problem hiding this comment.
Suggest changing
if you're using server-side rendering, you can...
to
if your server is capable of serving different assets based on user agent, you can...
The term "server-side rendering" has a different meaning.
| window.addEventListener('WebComponentsReady', function() { | ||
| var s = document.createElement('script'); | ||
| s.src = 'lazy-element.js'; | ||
| document.head.appendChild(s); |
There was a problem hiding this comment.
Hmmm... not sure the example is showing a particularly idiomatic use case (dynamically appending script after WCR?), thus might be hard to understand why WCR is important. How about:
<!-- Load polyfills; note that "loader" will load these async -->
<script src="bower_components/webcomponentsjs/webcomponents-loader.js"></script>
<!-- Load a custom element definition via HTMLImports -->
<link rel="import" href="my-element.html">
<!-- Use the custom element -->
<my-element></my-element>
<!-- Interact with the upgraded element -->
<script>
window.addEventListener('WebComponentsReady', function() {
// At this point we are guaranteed that all required polyfills have loaded,
// all HTML imports have loaded, and all defined custom elements have upgraded
let MyElement = customElements.get('my-element');
let element = document.querySelector('my-element');
console.assert(element instanceof MyElement); // 👍
element.someAPI(); // 👍
});
</script>There was a problem hiding this comment.
Oh yeah that's waaaay better. Thanks!
| - `webcomponents-hi-ce` -- HTML Imports and Custom Elements (needed by Safari 10) | ||
| - `webcomponents-hi-sd-ce` -- HTML Imports, Custom Elements and Shady DOM/CSS (needed by Safari 9, Firefox, Edge) | ||
| - `webcomponents-sd-ce` -- Custom Elements and Shady DOM/CSS (no HTML Imports) | ||
| - `webcomponents-lite` -- all of the polyfills: HTML Imports, Custom Elements, Shady DOM/CSS and generic platform polyfills (such as Template, ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11) |
There was a problem hiding this comment.
Add .js extensions so it's clear these are filenames?
| ## `webcomponents-loader.js` | ||
|
|
||
| Alternatively, this repo also comes with `webcomponents-loader.js`, a client-side | ||
| loader that dynamically loads the correct polyfill bundle, using feature detection. |
There was a problem hiding this comment.
s/correct polyfill bundle/minimum polyfill bundle
| - `webcomponents-hi-ce` -- HTML Imports and Custom Elements (needed by Safari 10) | ||
| - `webcomponents-hi-sd-ce` -- HTML Imports, Custom Elements and Shady DOM/CSS (needed by Safari 9, Firefox, Edge) | ||
| - `webcomponents-sd-ce` -- Custom Elements and Shady DOM/CSS (no HTML Imports) | ||
| - `webcomponents-lite` -- all of the polyfills: HTML Imports, Custom Elements, Shady DOM/CSS and generic platform polyfills (such as Template, ES6 Promise, Constructable events, etc.) (needed by Internet Explorer 11) |
There was a problem hiding this comment.
Yikes, just realized that we might need to tweak loader so that webcomponents-lite is loaded for Edge too -- let's double-check tomorrow. Technically Edge has Template but their impl is pretty busted (we fix it up in the Template polyfill). Since most testing is using webcomponents-lite this hasn't come up in tests. 😩
There was a problem hiding this comment.
Yeah... I think we need to add this check, and if it returns false need to load template polyfill (pf bundle):
(document.createDocumentFragment().cloneNode() instanceof DocumentFragment)
There was a problem hiding this comment.
|
@kevinpschaaf copy pasted all your changes, basically :) |
|
Thanks! |
2 participants
I cleaned up the "Releases" section into a (maybe clearer) "How to use section", since we have a lot a build artifacts now and they're a bit intimidating.
👀 @kevinpschaaf