[docs] Publish and Use an Element docs

docs/_data/guide.yml

@@ -8,17 +8,20 @@ toc:
     url: /guide/start
   templates: 
     title: Templates
-    desc: Create and render LitElement templates. Use JavaScript expressions to add properties and logic.      
     url: /guide/templates
   styles:
     title: Styles
     desc: Style your elements with CSS.
     url: /guide/styles
   properties: 
     title: Properties
-    desc: Declare and configure a component's properties and attributes.
     url: /guide/properties
   lifecycle: 
     title: Lifecycle
-    desc: Specify when an element should update. Respond to updates, or wait for an update to complete.
     url: /guide/lifecycle
+  publish: 
+    title: Publish a component
+    url: /guide/publish
+  use: 
+    title: Use a component
+    url: /guide/use

docs/_guide/publish.md

@@ -0,0 +1,104 @@
+---
+layout: guide
+title: Publish an element
+slug: publish
+---
+
+{::options toc_levels="1..3" /}
+* ToC
+{:toc}
+
+This page describes how to publish a LitElement component to npm.
+
+We recommend publishing JavaScript modules in standard ES2017. If you're writing your element in standard ES2017, you don't need to transpile for publication. If you're using decorators, class fields, or other ES2017+ features, you will need to transpile your element for publication.
+
+## Publish to npm
+
+To publish your component to npm, [see the instructions on contributing npm packages](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry).
+
+Your package.json configuration should have both the `main` and `module` fields:
+
+**package.json**
+
+```json
+{
+  "main": "my-element.js",
+  "module": "my-element.js"
+}
+```
+
+You should also create a README describing how to consume your component. A basic guide to consuming LitElement components is documented at [Use a component](use).
+
+## Transpiling with TypeScript
+
+When compiling your code from TypeScript to JavaScript, we recommend targeting ES2017 with Node.js module resolution. See the examples below for suggested options in tsconfig.json.
+
+### Targeting ES2017 (Recommended)
+
+The following JSON sample is a partial tsconfig.json that uses recommended options for targeting ES2017:
+
+```json
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "ES2017",
+    "moduleResolution": "node",
+    "lib": ["ES2017", "DOM"],
+    "experimentalDecorators": true,
+    "outDir": "path/to/your-output-dir"
+  }
+```
+
+See the 
+
+### ES5
+
+The following JSON sample is a partial tsconfig.json for those who need to target ES5:
+
+```json
+  "compilerOptions": {
+    "downLevelIteration": true,
+    "target": "ES5",
+    "module": "ES2015",
+    "moduleResolution": "node",
+    "lib": ["ES5", "DOM", "ScriptHost" ],
+    "experimentalDecorators": true,
+    "outDir": "path/to/your-output-dir"
+  }
+```
+
+<div class="alert alert-info">
+
+**You may need the compiler option `downlevelIteration` when targeting ES5**. The `downlevelIteration` option enables full support for [generators and the Iterator protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#Generator_functions) when compiling to ES5. You need this option if your own code iterates over, for example, a `Set` or `Map`. 
+
+The LitElement library is distributed as JavaScript and won't be passing through your TypeScript compiler.
+
+</div>
+
+## Transpiling with Babel
+
+To transpile a LitElement component that uses proposed JavaScript features, use Babel. 
+
+Install Babel and the Babel plugins you need. For example:
+
+```
+npm install --save-dev @babel/core
+npm install --save-dev @babel/plugin-proposal-class-properties
+npm install --save-dev @babel/proposal-decorators
+```
+
+Configure Babel. For example:
+
+**babel.config.js**
+
+```js
+const plugins = [
+  '@babel/plugin-proposal-class-properties',
+  ['@babel/proposal-decorators', { decoratorsBeforeExport: true } ],
+];
+
+module.exports = { plugins };
+```
+
+You can run Babel via a bundler plugin such as [rollup-plugin-babel](https://www.npmjs.com/package/rollup-plugin-babel), or from the command line. See the [Babel documentation](https://babeljs.io/docs/en/) for more information.
+
+See a [sample build configuration for LitElement with Babel and Rollup](https://github.com/PolymerLabs/lit-element-build-rollup/blob/master/src/index.html).

docs/_guide/use.md

@@ -0,0 +1,149 @@
+---
+layout: guide
+title: Use a component
+slug: use
+---
+
+{::options toc_levels="1..3" /}
+* ToC
+{:toc}
+
+This page describes how to [use a LitElement component in your application](#use). It also describes how to make sure your deployed code is browser-ready by [building it for production](#build) and [loading the Web Components polyfills](#polyfills).
+
+## Use a LitElement component {#use}
+
+This is a general guide to using third-party LitElement components. Refer to a component's README or other documentation for specific details.
+
+To use a LitElement component in your code:
+
+1.  Install the component from npm.
+
+    ```
+    npm install --save some-package-name
+    ```
+
+2.  Import the component.
+
+    In a JavaScript module: 
+
+    ```js
+    import 'some-package-name';
+    ```
+
+    In an HTML page:
+
+    ```html
+    <script type="module">
+    import './path-to/some-package-name/some-component.js';
+    </script>
+    ```
+
+    Or:
+
+    ```html
+    <script type="module" src="./path-to/some-package-name/some-component.js"></script>
+    ```
+
+3.  Add the component to the page via markup:
+
+    ```html
+    <some-component></some-component>
+    ```
+
+## Build for production {#build}
+
+Elements built with LitElement are published to npm as standard JavaScript modules so that they can be loaded with the native module loader available in all current major browsers.
+
+However, LitElement and elements built with it import their dependencies using bare module specifiers. In order to be loaded by a Web browser, a light transform is required to resolve the bare specifiers.
+
+This can be done with a bundler such as WebPack or Rollup.
+
+The following example configuration for [Rollup](https://rollupjs.org/guide/en) resolves modules and dependencies, and bundles the output.
+
+**rollup.config.js**
+
+```js
+import resolve from 'rollup-plugin-node-resolve';
+
+export default {
+  // If using any exports from a symlinked project, uncomment the following:
+  // preserveSymlinks: true,
+	input: ['src/index.js'],
+	output: {
+		file: 'build/index.js',
+    format: 'es',
+		sourcemap: true
+	},
+	plugins: [
+    resolve()
+  ]
+};
+```
+
+See a [sample build configuration for LitElement with Babel and Rollup](https://github.com/PolymerLabs/lit-element-build-rollup/blob/master/src/index.html).
+
+## Load the WebComponents polyfills {#polyfills}
+
+Elements built with LitElement use the Web Components set of standards, which are currently supported by all major browsers with the exception of Edge. 
+
+For compatibility with older browsers and Edge, load the Web Components polyfills.
+
+To load the WebComponents polyfills:
+
+1.  Install the `@webcomponents/webcomponentsjs` package:
+
+    ```
+    npm install --save-dev @webcomponents/webcomponentsjs
+    ```
+
+2.  Add the polyfills to your HTML entrypoint:
+
+    ```html
+    <head>
+      <!-- 
+        If you are loading es5 code you will need 
+        custom-elements-es5-loader to make the element work in 
+        es6-capable browsers. 
+
+        If you are not loading es5 code, you don't need 
+        custom-elements-es5-loader. 
+      --> 
+      <!-- 
+      <script src="./path-to/custom-elements-es5-loader.js"></script>
+      -->
+
+      <!-- Load polyfills -->
+      <script 
+        src="path-to/webcomponents-loader.js"
+        defer>
+      </script> 
+
+      <!-- Load component when polyfills are definitely ready -->
+      <script type="module">
+        // Take care of cases in which the browser runs this
+        // script before it has finished running 
+        // webcomponents-loader.js (e.g. Firefox script execution order)
+        window.WebComponents = window.WebComponents || { 
+          waitFor(cb){ addEventListener('WebComponentsReady', cb) }
+        }
+
+        WebComponents.waitFor(async () => { 
+          import('./path-to/some-element.js');
+        });
+      </script>
+    </head>
+    <body>
+      <!-- Add the element to the page -->
+      <some-element></some-element>
+    </body>
+    ```
+
+3.  Ensure that `node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js` and `node_modules/@webcomponents/webcomponentsjs/bundles/**.*` are included in your build.
+
+<div class="alert"> 
+
+**Do not transpile the polyfills.** Bundling them is okay.
+
+</div>
+
+See [the Webcomponentsjs documentation](https://github.com/webcomponents/webcomponentsjs) for more information.