Material Web Components

:warning: These components are still a work in progress. :warning:

Material Web Components helps developers execute Material Design using web components.

Built on top of the Material Components Web project and LitElement, the Material Web Components enable a reliable development workflow to build beautiful and functional web projects.

Web Components can be seamlessly incorporated into a wide range of usage contexts. Whether you're already heavily invested in another framework or not, it's easy to incorporate Material Web Components into your site in a lightweight, idiomatic fashion.

DEMOS

Authentic release instructions

1. Merge with develop branch

   git merge origin develop

   Fix all merge conflicts.

   Don't worry about renaming @material to @authentic at this point.

2. Rename packages names from @material to @authentic

   npm run rescope:authentic

3. Remove node_modules folder and package-lock.json file

   rm -Rf node_modules && rm package-lock.json

4. Install dependencies and create the @authentic folder

   npm i && mkdir node_modules/@authentic

   TODO: automate this step

5. Bootstrap the project

   npm run bootstrap

6. Test the project

   npm run dev

   Test the new functionality.

   :warning: If something is broken at this point: roll back your changes, fix the issue on develop branch and start again from step 1. :warning:

7. PUSH your changes

   If you have new changes at this point, add them to the stash and combine them with the previous commit.

   git commit -a --amend

   A new screen will appear with the previous commit description, you just need to save an quit by typing :wq and then clicking ENTER.

   Then:

   git push origin publish

8. Use lerna to help you with the release

   lerna publish

   Follow lerna instructions in order to move forward with the release

   Every new release will follow the PATCH release approach based on master's version currently at 0.5.0, so from now on it will continue with 0.5.X.

   Lerna will automatically change all packages versions and push a new commit & tag labeled as v0.5.X, right after that it will update the git head of them.

9. Since at this point lerna has updated all of our package.json again, we will need to COMMIT and PUSH our changes.

   git commit -am 'git head updated' && git push origin publish

Quick start

Note: This guide assumes you have npm installed locally.

The easiest way to try out the Material Web Components is to use one of these online tools:

• Runs in all supported browsers: Glitch

• Runs in browsers with JavaScript Modules: JSBin, CodePen.

Or you can also copy this HTML file into a local file and run it in any browser that supports JavaScript Modules.

When you're ready to use the Material Web Components in your web application:

1. Ensure the webcomponents polyfills are included in your HTML page

   • Install webcomponents polyfills

     npm i @webcomponents/webcomponentsjs

   • Add webcomponents polyfills to your HTML page

     <script src="@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>

2. Add one of the MWC elements to your project, for example for icon:

   npm i @material/mwc-icon

3. Import the element definition into your HTML page:

   <script type="module" src="@material/mwc-icon/index.js"></script>

   Or into your module script:

   import {Icon} from "@material/mwc-icon"

4. Create an instance of element in your HTML page, or via any framework that supports rendering Custom Elements:

   <mwc-icon>sentiment_very_satisfied</mwc-icon>

5. Install the Polymer CLI:

   npm i -g polymer-cli

6. Run the development server and open a browser pointing to its URL:

   polymer serve

The Material Web Components are published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.

However, since the Material Web Components use npm convention to reference dependencies by name, a light transform to rewrite specifiers to URLs is required to get it to run in the browser. The polymer-cli's development server polymer serve automatically handles this transform.

Tools like WebPack and Rollup can also be used to serve and/or bundle.

Contributing guide

Below are instructions for setting up project development.

1. Clone this repo with git clone.
2. Install dependencies by running npm run bootstrap
3. Run a development server with npm run dev
   • View the demos by accessing <dev server url>/demos/index.html
   • This will also build the project.
4. Build the project with npm run build
5. Run tests with npm run test

Developing Components

Components are written in Typescript, and compiled to Javascript Modules.

The output Javascript Modules can be used in every modern browser directly, and are supported a wide variety of popular bundler and build tools.

The components render output structure, handle styling, and manage data flow with lit-html while integrating with Material Design's common logic library for each component.

Styling Components

Components define their styling using SASS.

The SASS output is built into a javascript module which exports the component's styling as a lit-html template.

Component styling is compiled with both npm run build and npm run watch.

To compile the component SASS manually, use npm run build-styling

Useful Links

• All Components
• Demos
• Contributing
• Material.io (external site)
• Material Design Guidelines (external site)

Browser Support

We officially support the last two versions of every major browser. Specifically, we test on the following browsers:

• Chrome
• Safari
• Firefox
• IE 11/Edge
• Opera
• Mobile Safari
• Chrome on Android

Change Log

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

• Upgrade lerna to 3.x
• Upgrade typescript to 3.4, add config for tsbuildinfo files needed for incremental compilation mode

[0.5.0] - 2019-03-26

• Update to mdc 1.0
• Rewrite Adapters and Foundations with Typescript types
• Disable pointer-events on disabled buttons

[0.4.0] - 2019-03-11

• Update to mdc 0.44
• fix button label issues

[0.3.6] - 2019-02-05

• Use static get styles() on all components
• Clean up dependencies
• Implement drawer focus trapping
• Add tests
• Setup travis CI
• Update to lit-html 1.0

[0.3.5] - 2019-01-11

• Update lit and lit-element dependencies
• Publish mwc-drawer

[0.3.4] - 2018-12-13

• Update to lit-element 0.6.5 and lit-html 1.0.0-rc.1

[0.3.3] - 2018-12-03

• Fix ripple directive for lit-html 0.13

[0.3.2] - 2018-11-16

• Move event listeners to the class with lit-element 0.6.2
• Add @eventOptions({passive: true}) to event handlers in tab-bar-scroller
  • More efficient scrolling behavior, as preventDefault is never called
• Implement icon-button in typescript

[0.3.1] - 2018-10-08

• Fix demo publishing
• Update to lit-element 0.6.2
• Add dependencies to lit-html where necessary
• Add explicit .js endings to imports, where necessary
• Fill in CHANGELOG

[0.3.0] - 2018-10-04

• Rewrite elements in typescript
• Add ripple lit directive to add a material ripple to any component
• Add @observe decorator to tie data changes into base MDC Foundation handlers
• Add a watcher for styling and typescript changes

[0.2.1] - 2018-09-21

• Update to lit-element 0.6.1

[0.2.0] - 2018-09-13

• Use lit-element 0.6

[0.1.2] - 2018-06-14

• Use lit-element 0.5

[0.1.1] - 2018-05-09

• Add READMEs and examples

[0.1.0] - 2018-05-08

• Initial WIP of components