From 6958f3a3bf8ad49dfcd43006ce65ca77553aa106 Mon Sep 17 00:00:00 2001 From: Joel Denning Date: Thu, 11 Oct 2018 12:59:41 -0600 Subject: [PATCH 1/5] Improving documentation for how to use this project. --- packages/custom-elements/README.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/packages/custom-elements/README.md b/packages/custom-elements/README.md index 415504f7a..db99fe243 100644 --- a/packages/custom-elements/README.md +++ b/packages/custom-elements/README.md @@ -4,13 +4,32 @@ A polyfill for the [custom elements](https://html.spec.whatwg.org/multipage/scri v1 spec. ## Using +#### Standalone script tag +Include a script tag at the beginning of your page, *before* any code that +manipulates the DOM. The custom-elements.min.js can be loaded from a CDN: +```html + +``` -Include `custom-elements.min.js` at the beginning of your page, *before* any code that -manipulates the DOM: +Or you can build it yourself and then load it: ```html ``` +#### Via npm: +If you're using npm, webpack, or similar tools, this package can be installed and imported: +```bash +npm install @webcomponents/custom-elements +``` + +```js +// Do this import before any code that manipulates the DOM. +import '@webcomponents/custom-elements' +``` + +#### Via the webcomponents polyfill +Alternatively, you can use this polyfill via the [webcomponentjs polyfills](https://github.com/WebComponents/webcomponentsjs). + ## Developing 1. Install and build From 863a0e7c18c1c39fcd418d6b8d12bf6b2fc79c24 Mon Sep 17 00:00:00 2001 From: Steven Orvell Date: Tue, 4 Jun 2019 08:36:17 -0700 Subject: [PATCH 2/5] Address review feedback. --- packages/custom-elements/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/packages/custom-elements/README.md b/packages/custom-elements/README.md index db99fe243..ba349791a 100644 --- a/packages/custom-elements/README.md +++ b/packages/custom-elements/README.md @@ -228,3 +228,23 @@ customElements.define('c-e', class extends HTMLElement {}); // 'added first' // The document is walked to attempt upgrades. ``` + +## Settings + +The polyfill provides a few settings to improve performance by tweaking behavior. +These settings typically have correctness trade offs (noted below) and should be +used with caution. + +* `customElements.noDocumentConstructionObserver`: Set this flag to true to +prevent the polyfill from mutation observing and upgrading DOM as it is added. +This provides a small performance improvement during document parsing. +With this setting on, the polyfill will not upgrade parser generated elements +defined after an element definition. This setting should be used in +conjunction with a `polyfillWrapFlushCallback` that defers element upgrades +until the parser is complete. + +* `customElements.shadyDomFastWalk`: Set this flag to true when using the +ShadyDOM polyfill to optimize how elements are found in the DOM. There are a +couple of limitations: (1) Elements that are children of Shadow DOM hosts and +are not distributed to slots may not upgrade; (2) This setting is not compatible +with using native HTML Imports. \ No newline at end of file From dade607303567ac406413b9b7bfbac02ac6dca9b Mon Sep 17 00:00:00 2001 From: Steven Orvell Date: Tue, 4 Jun 2019 08:40:40 -0700 Subject: [PATCH 3/5] Fix typo --- packages/custom-elements/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/custom-elements/README.md b/packages/custom-elements/README.md index ba349791a..a4e17d964 100644 --- a/packages/custom-elements/README.md +++ b/packages/custom-elements/README.md @@ -229,7 +229,7 @@ customElements.define('c-e', class extends HTMLElement {}); // The document is walked to attempt upgrades. ``` -## Settings +### Settings The polyfill provides a few settings to improve performance by tweaking behavior. These settings typically have correctness trade offs (noted below) and should be From b1f256064a2634d1e288d0b123f45f338d24270e Mon Sep 17 00:00:00 2001 From: Steven Orvell Date: Tue, 4 Jun 2019 14:56:41 -0700 Subject: [PATCH 4/5] Address review feedback --- packages/custom-elements/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/custom-elements/README.md b/packages/custom-elements/README.md index a4e17d964..88ddc14d9 100644 --- a/packages/custom-elements/README.md +++ b/packages/custom-elements/README.md @@ -236,12 +236,12 @@ These settings typically have correctness trade offs (noted below) and should be used with caution. * `customElements.noDocumentConstructionObserver`: Set this flag to true to -prevent the polyfill from mutation observing and upgrading DOM as it is added. -This provides a small performance improvement during document parsing. -With this setting on, the polyfill will not upgrade parser generated elements -defined after an element definition. This setting should be used in -conjunction with a `polyfillWrapFlushCallback` that defers element upgrades -until the parser is complete. +prevent the polyfill from mutation observing and upgrading DOM as it is added +to the main document. This provides a small performance improvement during +document parsing. With this setting on, the polyfill will not upgrade elements +created when parsing the main document's HTML. This setting should be +used in conjunction with a `polyfillWrapFlushCallback` that defers element +upgrades until the parser is complete. * `customElements.shadyDomFastWalk`: Set this flag to true when using the ShadyDOM polyfill to optimize how elements are found in the DOM. There are a From 454247d77b522759df4aeade27bf624dbb89f364 Mon Sep 17 00:00:00 2001 From: Russell Bicknell Date: Thu, 22 Aug 2019 15:05:32 -0700 Subject: [PATCH 5/5] URL: `WebComponents` -> `webcomponents` --- packages/custom-elements/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/custom-elements/README.md b/packages/custom-elements/README.md index c6889f981..0011fdc4c 100644 --- a/packages/custom-elements/README.md +++ b/packages/custom-elements/README.md @@ -28,7 +28,7 @@ import '@webcomponents/custom-elements' ``` #### Via the webcomponents polyfill -Alternatively, you can use this polyfill via the [webcomponentjs polyfills](https://github.com/WebComponents/webcomponentsjs). +Alternatively, you can use this polyfill via the [webcomponentjs polyfills](https://github.com/webcomponents/webcomponentsjs). ## Developing