` or any other element. ```html ``` @@ -83,16 +77,10 @@ shadowRoot.innerHTML = '

Hello Shadow DOM

'; // Could also use appendChil // header.shadowRoot === shadowRoot // shadowRoot.host === header ``` - -Version 0 of the shadow DOM specification provided a slightly different method for creating shadow DOM: -```js -var root = host.createShadowRoot(); -``` -See this article on [shadow DOM v0](https://www.html5rocks.com/en/tutorials/webcomponents/shadowdom/) for more information. See also [Hayato Ito's comparison of v0 and v1 of the shadow DOM specification](http://hayato.io/2016/shadowdomv1/). - # Libraries for building web components -Many libraries already exist that make it easier to build web components. To dive in and create your own components, here are some you can try out: - * [Bosonic](https://bosonic.github.io/) is a collection of components designed to meet the everyday needs of web developers. +Many libraries already exist that make it easier to build web components. [The libraries section](https://www.webcomponents.org/libraries) of the site has additional details but here are some you can try out: + * [Hybrids](https://github.com/hybridsjs/hybrids) is a UI library for creating Web Components with simple and functional API. + * [lit-element](https://github.com/lit/lit/tree/main/packages/lit-element) uses [lit-html](https://github.com/lit/lit/tree/main/packages/lit-html) to render into the element's Shadow DOM and adds API to help manage element properties and attributes. * [Polymer](https://www.polymer-project.org) provides a set of features for creating custom elements. - * [SkateJS](https://github.com/skatejs/skatejs) is a JavaScript library for writing web components with a small footprint. - * [X-Tag](https://x-tag.github.io/) is an open source JavaScript library that provides an interface for component development. \ No newline at end of file + * [Slim.js](http://slimjs.com) is an opensource lightweight web component library that provides data-binding and extended capabilities for components, using es6 native class inheritance. + * [Stencil](https://stenciljs.com/) is an opensource compiler that generates standards-compliant web components. diff --git a/static/libraries.md b/static/libraries.md index e2e3ee2..6f7fe21 100644 --- a/static/libraries.md +++ b/static/libraries.md @@ -9,13 +9,22 @@ However, if you’re writing lots and lots of custom elements, using a library c # What should you look for in a web component library? -When choosing a web component library, make sure it has a large enough featureset to cover all of your use cases. Interoperability is also important - does the library leak implementation details? A good web component library should produce a web component that “just works” like any other HTML element. You should also be aware of browser compatibility, and any polyfills that will be needed to support features you use or the library uses. Good libraries also have a high value-to-payload ratio - that is, they provide a lot of value for their download size. +When choosing a web component library, make sure it has a large enough featureset to cover all of your use cases. Interoperability is also important - does the library leak implementation details? A good web component library should produce a web component that “just works” like any other HTML element. Good libraries also have a high value-to-payload ratio - that is, they provide a lot of value for their download size. Libraries which support ES modules, Custom Element, Shadow DOM and Template are listed below. +# Some web component libraries -# Existing web component libraries +This list has been compiled by the community and can be modified [via pull request under the community repository](https://github.com/webcomponents/community/edit/master/static/libraries.md) for this website. Projects are listed alphabetically and are known to support all four aspects of the web components specification. - * [Polymer](https://www.polymer-project.org/) is a web component library built by Google, with a simple element creation API. Polymer offers one- and two-way data binding into element templates, and provides shims for better cross-browser performance. +* [FAST](https://fast.design) is a web component library built by Microsoft, which offers several packages to leverage depending on your project needs. [Fast Element](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-element) is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. [Fast Foundation](https://github.com/microsoft/fast/tree/master/packages/web-components/fast-foundation) is a library of Web Component classes, templates, and other utilities built on fast-element intended to be composed into registered Web Components. + + * [Hybrids](https://github.com/hybridsjs/hybrids) is a UI library for creating web components with simple and functional API. The library uses plain objects and pure functions for defining custom elements, which allow very flexible composition. It provides built-in cache mechanism, template engine based on tagged template literals, and integration with developer tools. - * [Skate.js](http://skate.js.org/) is a library built on top of the W3C web component specs that enables you to write functional and performant web components with a very small footprint. Skate is Inherently cross-framework compatible. For example, it works seamlessly with - and complements - React and other frameworks. + * [LitElement](https://github.com/Polymer/lit-element) uses [lit-html](https://github.com/Polymer/lit-html) to render into the element's Shadow DOM and adds API to help manage element properties and attributes. LitElement reacts to changes in properties and renders declaratively using lit-html. + + * [Polymer](https://www.polymer-project.org/) is a web component library built by Google, with a simple element creation API. Polymer offers one- and two-way data binding into element templates, and provides shims for better cross-browser performance. - * [X-Tag](http://x-tag.github.io/) is a Microsoft supported, open source, JavaScript library that wraps the W3C standard Web Components family of APIs to provide a compact, feature-rich interface for rapid component development. While X-Tag offers feature hooks for all Web Component APIs (Custom Elements, Shadow DOM, Templates, and HTML Imports), it only requires Custom Element support to operate. In the absence of native Custom Element support, X-Tag uses a set of polyfills shared with Google's Polymer framework. + * [Skate.js](https://skatejs.gitbooks.io/skatejs/content/) is a library built on top of the W3C web component specs that enables you to write functional and performant web components with a very small footprint. Skate is inherently cross-framework compatible. For example, it works seamlessly with - and complements - React and other frameworks. + + * [Slim.js](http://slimjs.com) Slim.js is a lightweight web component library that provides extended capabilities for components, such as data binding, using es6 native class inheritance. This library is focused for providing the developer the ability to write robust and native web components without the hassle of dependencies and an overhead of a framework. + + * [Stencil](https://stenciljs.com/) is an opensource compiler that generates standards-compliant web components. diff --git a/static/polyfills.md b/static/polyfills.md index cdae0b7..8a00760 100644 --- a/static/polyfills.md +++ b/static/polyfills.md @@ -6,32 +6,18 @@ The polyfills are available on GitHub: https://github.com/WebComponents/webcompo To install the polyfills, run this command: ``` -bower install --save webcomponents/webcomponentsjs +npm install @webcomponents/webcomponentsjs ``` +There are severeal different ways of applying the polyfill [which you can read about here](https://github.com/WebComponents/webcomponentsjs#how-to-use). The easiest way to utilize webcomponents across platform is the following: +```html + + -To feature detect: -```js -(function() { - if ('registerElement' in document - && 'import' in document.createElement('link') - && 'content' in document.createElement('template')) { - // platform is good! - } else { - // polyfill the platform! - var e = document.createElement('script'); - e.src = '/bower_components/webcomponentsjs/webcomponents-lite.min.js'; - document.body.appendChild(e); - } -})(); -``` - -# Shadow DOM polyfill -The shadow DOM polyfill provides shadow DOM v0 functionality in browsers that don't support it natively. See the Compatibility table for more information. - -The shadow DOM polyfill, though very powerful, is also fairly intrusive and can add significant performance overhead. For this reason, many Web Components-based libraries like Polymer work around having to use this polyfill, and provide a lighter-weight alternative. These libraries don’t require loading the full Web Components polyfill, but instead use a “lite” version of the polyfill with shadow DOM removed: + + -``` -webcomponents/webcomponents-lite.min.js + + ``` ## Wrappers @@ -79,7 +65,7 @@ If you plan to work with elements that need to be wrapped over and over, try pas ## Event Retargeting An important aspect of the shadow DOM is that events are retargeted to never expose the shadow DOM to the light DOM. For example: -``` +```js var div = document.createElement('div'); div.innerHTML = 'Click me'; var shadow = div.createShadowRoot(); @@ -98,7 +84,7 @@ To support this kind of behavior the event dispatching in the browser has to be * No live `NodeLists`. All node lists are snapshotted upon read. * `document`, window`, document.body`, document.head` and others are non configurable and cannot be overridden. We are trying to make these work as seamlessly as possible but there will doubtlessly be cases where there will be problems; for those cases you can use wrapand unwrap to get unblocked. * Cross window/frame access is not implemented. - * CSS `:host()` rules can only have (at most) one level of nested parentheses in their argument selectors. For example, `:host(.zot)` and `:host(.zot:not(.bar)` both work, but `:host(.zot:not(.bar:nth-child(2)))` does not. + * CSS `:host()` rules can only have (at most) one level of nested parentheses in their argument selectors. For example, `:host(.zot)` and `:host(.zot:not(.bar))` both work, but `:host(.zot:not(.bar:nth-child(2)))` does not. # Custom Elements polyfill The Custom Elements polyfill provides support for v0 of the Custom Elements spec. A polyfill for v1 is in progress at https://github.com/webcomponents/custom-elements. @@ -126,35 +112,3 @@ The Custom Elements specification is still under discussion. The polyfill implem * `attributeChangedCallback(attributeName)` is called when a custom element's attribute value has changed `createdCallback` is invoked synchronously with element instantiation, the other callbacks are called asynchronously. The asynchronous callbacks generally use the `MutationObserver` timing model, which means they are called before layouts, paints, or other triggered events, so the developer need not worry about flashing content or other bad things happening before the callback has a chance to react to changes. - -# HTML Imports Polyfill - -In imported documents, `href` and `src` attributes in HTML, and `urlproperties` in CSS files, are relative to the location of the imported document, not the main document. - -The HTML Imports polyfill begins processing link tags when the `DOMContentLoaded` event fires. To know when loading is complete, listen for the `HTMLImportsLoaded` event on document or window. For example: - -```html - -``` - -The polyfill loads linked stylesheets, external scripts, and nested HTML imports, but does not parse any data in the loaded resources. For parsing imports, combine HTML Imports with Custom Elements. As long as the HTML Imports is loaded first, the Custom Elements polyfill will detect it, and process all imports when `HTMLImportsLoaded` event fires. - -## The WebComponentsReady event - -Under native imports, ` -``` - -In native HTML Imports, `document.currentScript.ownerDocument` references the import document itself. In the polyfill, use `document._currentScript.ownerDocument` (note the underscore). diff --git a/static/resources.md b/static/resources.md index 758d7fe..5cdd8ea 100644 --- a/static/resources.md +++ b/static/resources.md @@ -4,30 +4,32 @@ The WebComponents.org Resources section is a place to showcase useful tools and Web Components is a set of specs that introduce powerful new capabilities to the web platform. Before getting started with your first custom element, it will be helpful to understand the scope of these new features. The [Introduction](/introduction) section contains an overview of these APIs. The [Community](/community) section is also a great way to catch up on the latest goings-on in the Web Components world. We’d also recommend starting out by reading the Getting Started sections of: * [Polymer's documentation;](https://www.polymer-project.org/) - * [SkateJS's documentation.](http://skate.js.org/) - * [X-Tag's documentation.](http://x-tag.github.io/docs) + * [Slim.js's documentation.](http://slim.js.org/) + * [Skate.js's documentation.](https://skatejs.netlify.com/) -These will give you an idea on how these libraries for building web components work and what might be best for you. +These will give you an idea on how these libraries for building web components work and what might be best for you. Another incredible resource is the [web-components-todo repo](https://github.com/shprink/web-components-todo) which has the same to-do list app created in an ever growing list of web component and component compatible library methodologies. It's a great way to learn from the differences in techniques across libraries and see which one is right for your needs. # 2. Create Once you’ve learned about Web Components, it's time to create your own element! There are a number of different jumping-off points for getting started using a Web Component library, or just using the vanilla Web Component APIs directly: * [Polymer Boilerplate](https://github.com/webcomponents/polymer-boilerplate) - * [X-Tag Boilerplate](https://github.com/webcomponents/xtag-boilerplate); * [VanillaJS Boilerplate.](https://github.com/webcomponents/element-boilerplate) -In these boilerplates, we solve the same problem using different libraries (Polymer/X-Tag) or no library at all (VanillaJS), with the same tools and directory structure. +In these boilerplates, we solve the same problem using different libraries (Polymer / SkateJS / LitElement / SlimJS) or no library at all (VanillaJS), with the same tools and directory structure. -We encourage a series of best practices like setting up a live demo, documenting your API, maintaining a changelog for release purposes, and sharing your component on Bower. The boilerplates form small, opinionated starter-kits with all you need included, from polyfills to automated tasks. +We encourage a series of best practices like setting up a live demo, documenting your API, maintaining a changelog for release purposes, and sharing your component on NPM. The boilerplates form small, opinionated starter-kits with all you need included, from polyfills to automated tasks. You’ll still need to make some manual changes after forking each boilerplate, like changing an element's name in different files. In order to automate this process, we created a [Yeoman](http://yeoman.io/) Generator and a [Slush](http://slushjs.github.io/#/) Generator that can scaffold a web component using the command-line: - * [Element Generator for Yeoman.](https://github.com/webcomponents/generator-element) - * [Element Generator for Slush.](https://github.com/webcomponents/slush-element) + * [Element Generator for Yeoman](https://github.com/webcomponents/generator-element) + * [Element Generator for Slush](https://github.com/webcomponents/slush-element) + * [RHElement Generator](https://github.com/rhelements/generator-rhelement) -The generators help ensure an even more seamless start, helping with tasks like validating your element's name according to W3C's spec rules and checking if there's a similarly-named project on Bower. +The generators help ensure an even more seamless start, helping with tasks like validating your element's name according to W3C's spec rules and checking if there's a similarly-named project on NPM. -The Polymer Project also has a command-line tool to help automate the scaffolding of Polymer-based web components and applications: - * [Polymer CLI](https://www.polymer-project.org/1.0/docs/tools/polymer-cli) +Some projects also have command-line tools to help automate the scaffolding of web components and applications: + * [Polymer CLI](https://www.polymer-project.org/3.0/docs/tools/polymer-cli) - CLI + build Polymer 3 & scaffold full applications + * [StencilJS](https://www.stenciljs.com/) - CLI & Compiler to generate VanillaJS elements + * [Web Component Factory](https://github.com/elmsln/wcfactory) - CLI to produce boilerplate VanillaJS, SlimJS, StencilJS, Polmer 3, LitElement # 3. Share @@ -35,5 +37,4 @@ Now that you’ve finished your element it's time to share it with the world! Th The best way to share a component is by making it available for use with one of the current JavaScript package managers. Currently most web component libraries have great support for [Bower](https://bower.io/), and are working on improving support for [npm](https://www.npmjs.com/). -And make sure to publish your element to webcomponents.org! Check out the [Publish page](https://beta.webcomponents.org/publish) to learn how to publish your element. - +And make sure to publish your element to webcomponents.org! Check out the [Publish page](https://webcomponents.org/publish) to learn how to publish your element. diff --git a/static/specs.md b/static/specs.md index 05beb96..e381123 100644 --- a/static/specs.md +++ b/static/specs.md @@ -1,11 +1,13 @@ -Web components are based on four main specifications: +Web components is a meta-specification made possible by four other specifications: * The Custom Elements specification * The shadow DOM specification - * The HTML imports specification * The HTML Template specification + * The ES Module specification + +These four specifications can be used on their own but combined allow developers to define their own tags (custom element), whose styles are encapsulated and isolated (shadow dom), that can be restamped many times (template), and have a consistent way of being integrated into applications (es module). # The Custom Elements specification -The previous version of the Custom Elements specification, v0, was only shipped in Chromium-based browsers. It is being phased out in favour of v1. This section mostly applies to the new, cross-browser version of the Custom Elements specification (v1). See Eric Bidelman’s articles on [Custom Elements v1](https://developers.google.com/web/fundamentals/getting-started/primers/customelements#historysupport) or [Custom Elements v0](https://www.html5rocks.com/en/tutorials/webcomponents/customelements/) for full details. +This section applies to the cross-browser version of the Custom Elements specification (v1). See Eric Bidelman’s articles on [Custom Elements v1](https://developers.google.com/web/fundamentals/getting-started/primers/customelements#historysupport). The [Custom Elements specification](https://w3c.github.io/webcomponents/spec/custom/) lays the foundation for designing and using new types of DOM elements that are fully-featured and conforming. Following the Custom Elements spec, authors can define behaviors and styles for new HTML elements. @@ -13,7 +15,7 @@ The [Custom Elements specification](https://w3c.github.io/webcomponents/spec/cus * Customized built-ins extend existing HTML elements with custom functionality. They inherit semantics from the elements they extend. The specification for customized built-ins is still a work in progress, and at present is only supported by Chrome. ## Create a custom button as an autonomous custom element -To create an autonomous custom element, extend HTMLElement. The Custom Elements v1 syntax is: +To create an autonomous custom element, extend HTMLElement. The Custom Elements syntax is: ```html class AutonomousButton extends HTMLElement { ... @@ -21,12 +23,6 @@ class AutonomousButton extends HTMLElement { customElements.define("autonomous-button", AutonomousButton); ``` -The (deprecated) Custom Elements v0 syntax is: -```js -var AutonomousButton = document.registerElement('autonomous-button', {prototype: Object.create(HTMLElement.prototype) }); -document.body.appendChild(new AutonomousButton()); -``` - To use the element: ```html Click Me :) @@ -37,7 +33,7 @@ When the browser sees the `` tag, it constructs and renders a ## Create a custom button as a customized built-in You can extend an existing native HTML element to create a customized built-in*. -The Custom Elements v1 syntax is: +The Custom Elements syntax is: ```html class CustomizedButton extends HTMLButtonElement { ... @@ -45,14 +41,6 @@ class CustomizedButton extends HTMLButtonElement { customElements.define("customized-button", CustomizedButton, { extends: "button" }); ``` -The Custom Elements v0 syntax is: -```js -var CustomizedButton = document.registerElement('customized-button', { - prototype: Object.create(HTMLButtonElement.prototype), - extends: 'button' -}); -``` - To use the element: ```html Click Me :) @@ -64,7 +52,7 @@ By extending HTMLButtonElement instead of HTMLElement, CustomizedButton inherits # The shadow DOM specification -This section is a summary of the new, cross-browser version (v1) of the shadow DOM specification. See [Eric Bidelman’s article on shadow DOM v1](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom), [Dominic Cooney’s article on shadow DOM v0](https://www.html5rocks.com/en/tutorials/webcomponents/shadowdom/), and [Hayato Ito’s summary of the differences](https://hayato.io/2016/shadowdomv1/) for full details. +This section is a summary of the shadow DOM specification. See [Eric Bidelman’s article on shadow DOM](https://developers.google.com/web/fundamentals/getting-started/primers/shadowdom). The DOM (Document Object Model) is a representation of the structure of an html document. The DOM models a document as a tree, with elements in parent-child relationships. @@ -73,21 +61,15 @@ On its own, the DOM API contains no support for encapsulation. This makes it har The shadow DOM API overcomes this limitation by letting you attach DOM subtrees to elements in a web document. These subtrees are encapsulated; style information inside them cannot apply to outside elements, and vice versa. ## Creating shadow DOM for a custom element -In Shadow DOM v1, use the attachShadow() method to create shadow DOM: +In Shadow DOM, use the attachShadow() method to create shadow DOM: ```js const header = document.createElement('header'); const shadowRoot = header.attachShadow({mode: 'open'}); shadowRoot.innerHTML = '

Hello Shadow DOM

'; ``` -In Shadow DOM v0, use the createShadowRoot() method to create shadow DOM: -```js -let e = document.createElement('div'); -let shadowRoot = e.createShadowRoot(); -``` - ## Composition and slots -By default, if an element has shadow DOM, the shadow tree is rendered instead of the element's children. To allow children to render, you need to add placeholders for them in your shadow tree. To do this in shadow DOM v1: +By default, if an element has shadow DOM, the shadow tree is rendered instead of the element's children. To allow children to render, you need to add placeholders for them in your shadow tree. To do this in shadow DOM: Consider the following shadow tree for ``: @@ -113,23 +95,6 @@ The header renders as if the `` element was replaced by the children: ``` -To do this in shadow DOM v0, use `` as a placeholder. See [Hayato Ito's cheat sheet](https://hayato.io/2016/shadowdomv1/#insertion-points-v0-vs-slots-v1) for the source of this code, and for more explanation. -```html - - - - - - - - -

- - - -

-``` - ## Styling Styles inside a shadow tree are scoped to the shadow tree, and don't affect elements outside the shadow tree. @@ -154,24 +119,29 @@ To style elements with a shadow root, you can use custom properties if the eleme In this example, the `

` has a blue background, even though the div selector is less specific than the .test selector in the main document. That's because the main document selector doesn't match the `

` in the shadow DOM at all. On the other hand, the white text color set on the document body inherits down to `` and into its shadow root. -# The HTML imports specification -The [HTML imports specification](https://w3c.github.io/webcomponents/spec/imports/) defines the inclusion and reuse of HTML documents in other HTML documents. There are no corresponding changes to HTML imports for cross-browser specifications. +# The ES Module specification +The [ES Module specification](https://html.spec.whatwg.org/multipage/webappapis.html#integration-with-the-javascript-module-system) defines the inclusion and reuse of JS documents in other JS documents. -HTML imports enable web components to be developed in a modular way. You can define the interface of your custom element in an HTML file which is then included with an import. Imported HTML files are merged into one file at build time. +ES Modules enable web components to be developed in a modular way that is in alignment with other industry accepted implementations for JavaScript application development. You can define the interface of your custom element in a JS file which is then included with an `type="module"` attribute. ES Module files are merged into one file client side or can be rolled up into single packages ahead of time. -Supposing an element is defined in cool-thing.html, you would import it using the following link: +Supposing an element is defined in awesome-explosion.js, you would import it using one of the following script: ```html - + +... + ``` -Now you can use the cool-thing element in your own pages: +Now you can use the awesome-explosion element in your own pages: ```html - + ... - + ``` - # The HTML Template specification The [HTML template element specification](https://html.spec.whatwg.org/multipage/scripting.html#the-template-element/) defines how to declare fragments of markup that go unused at page load, but can be instantiated later on at runtime. There are no corresponding changes to HTML templates for cross-browser specifications. @@ -203,4 +173,4 @@ t.content.querySelector('img').src = 'logo.png'; var clone = document.importNode(t.content, true); document.body.appendChild(clone); -``` \ No newline at end of file +``` diff --git a/test/test.js b/test/test.js index c5f0ca7..abf1587 100644 --- a/test/test.js +++ b/test/test.js @@ -143,4 +143,17 @@ describe('api/resources', function() { done(); }); }); + + it('should return filtered list by author', function(done) { + chai.request(server) + .get('/resources/author/aaron_frost') + .end(function(err, response) { + const header = response.header; + header.should.have.property('access-control-allow-origin', '*'); + response.should.have.status(200); + response.should.be.json; + JSON.parse(response.text).should.have.property('count', 1); + done(); + }); + }); });