Merge pull request #366 from material-components/button-readme

Better readme for button
material-components · Aug 14, 2019 · 4dd027b · 4dd027b
2 parents cb1c152 + 93638d6
commit 4dd027b
Show file tree

Hide file tree

Showing 20 changed files with 133 additions and 106 deletions.
diff --git a/demos/button.html b/demos/button.html
@@ -24,22 +24,12 @@
   <script type="module" src="../node_modules/@material/mwc-icon/mwc-icon.js"></script>
   <link rel="stylesheet" href="demo-component.css">
   <style>
-    .light {
-      --mdc-theme-on-primary: black;
-      --mdc-theme-primary: white;
-      --mdc-theme-on-secondary: black;
-      --mdc-theme-secondary: white;
+    mwc-button {
+      margin: 20px;
     }
-
     .pink {
       --mdc-theme-on-primary: white;
       --mdc-theme-primary: #e9437a;
-      --mdc-theme-on-secondary: white;
-      --mdc-theme-secondary: #e9437a;
-    }
-
-    .wide {
-      width: 250px;
     }
   </style>
 </head>
@@ -50,57 +40,24 @@
   </header>
 
   <main>
-
-    <h4>labeled</h4>
-
-    <div class="demo-group-spaced">
-      <mwc-button label="Normal"></mwc-button>
-      <mwc-button class="light" raised label="raised"></mwc-button>
-      <mwc-button unelevated label="unelevated"></mwc-button>
-      <mwc-button outlined label="outlined"></mwc-button>
-      <mwc-button class="pink" dense label="dense"></mwc-button>
-      <mwc-button class="pink wide" raised label="wide"></mwc-button>
-      <mwc-button disabled label="disabled"></mwc-button>
-    </div>
-
-    <h4>icon labeled</h4>
-
-    <div class="demo-group-spaced">
-      <mwc-button label="Normal" icon="explore"></mwc-button>
-      <mwc-button class="light" raised label="raised" icon="code"></mwc-button>
-      <mwc-button unelevated label="unelevated" icon="check"></mwc-button>
-      <mwc-button outlined label="outlined" icon="alarm"></mwc-button>
-      <mwc-button class="pink" dense label="dense" icon="feedback"></mwc-button>
-      <mwc-button class="pink wide" raised label="wide" icon="code"></mwc-button>
-      <mwc-button disabled label="disabled" icon="fingerprint"></mwc-button>
-    </div>
-
-    <h4>trailing icon labeled</h4>
-
-    <mwc-button label="Normal" icon="explore" trailingIcon></mwc-button>
-
-    <script type="module">
-      import {html, css} from 'lit-element/lit-element.js';
-      import {Button} from '@material/mwc-button/mwc-button.js';
-      class CustomButton extends Button {
-        static get styles() {
-          return [
-            Button.styles,
-            css`.mdc-button{border-radius: 8px}`,
-          ];
-        }
-      }
-      customElements.define('custom-button', CustomButton);
-    </script>
-
-    <h4>custom button</h4>
-
-    <custom-button label="Custom!" raised></custom-button>
-
-    <script>
-      addEventListener('load', () => document.body.classList.remove('unresolved'));
-    </script>
-
+    <mwc-button label="standard"></mwc-button>
+    <mwc-button label="standard" icon="code"></mwc-button>
+    <mwc-button outlined label="outlined"></mwc-button>
+    <mwc-button outlined label="outlined" icon="code"></mwc-button>
+    <mwc-button raised label="raised"></mwc-button>
+    <mwc-button raised label="raised" icon="code"></mwc-button>
+    <mwc-button unelevated label="unelevated"></mwc-button>
+    <mwc-button unelevated label="unelevated" icon="code"></mwc-button>
+    <mwc-button dense unelevated label="dense"></mwc-button>
+    <mwc-button dense unelevated label="dense" icon="code"></mwc-button>
+    <mwc-button label="trailing icon" icon="code" trailingIcon></mwc-button>
+    <mwc-button disabled label="disabled"></mwc-button>
+    <mwc-button disabled label="disabled" icon="code"></mwc-button>
+    <mwc-button raised class="pink" icon="code" label="custom color"></mwc-button>
   </main>
+
+  <script>
+    addEventListener('load', () => document.body.classList.remove('unresolved'));
+  </script>
 </body>
 </html>
diff --git a/package.json b/package.json
@@ -25,8 +25,8 @@
     "update-gh-pages": "npm run bootstrap && ./scripts/publish-demos.sh",
     "static-urlify-readme-images": "npm run build:scripts && node scripts/tsc-out/static-urlify-readme-images.js packages/*/README.md",
     "prepack": "npm run build && npm run static-urlify-readme-images",
-    "watch": "npm run bootstrap && node scripts/watcher.js",
-    "watch:tests": "npm run bootstrap && tsc --build test/tsconfig.json -w & tsc --build test/tsconfig-node.json -w"
+    "watch": "npm run build && node scripts/watcher.js",
+    "watch:tests": "npm run build && tsc --build test/tsconfig.json -w & tsc --build test/tsconfig-node.json -w"
   },
   "devDependencies": {
     "@types/command-line-args": "^5.0.0",

diff --git a/packages/button/README.md b/packages/button/README.md
@@ -1,64 +1,138 @@
-# mwc-button
+# `<mwc-button>` [![Published on npm](https://img.shields.io/npm/v/@material/mwc-button.svg)](https://www.npmjs.com/package/@material/mwc-button)
 
-> :warning: These components are a work in progress. They are pre-release and should be considered experimental, as they may undergo major changes before release. We are experimenting with alternate architectures and approaches with the goal of allowing us to bring the most correct and optimal implementation of Material components to the widest possible audiences. Visible progress may be slow, as this research is across teams and repositories so is not consistently reflected in commits to this codebase. :warning:
+> IMPORTANT: The Material Web Components are a work in progress and subject to
+> major changes until 1.0 release.
 
-A [Material Components](https://material.io/components/) button implementation using [Web Components](https://www.webcomponents.org/introduction)
+Buttons allow users to take actions, and make choices, with a single tap.
 
-## Getting started
+[Material Design Guidelines: Button](https://material.io/design/components/buttons.html)
 
-* The easiest way to try out mwc-button is to use one of these online tools:
+## Installation
 
-  * Runs in all [supported](#supported-browsers) browsers: [StackBlitz](https://stackblitz.com/edit/mwc-button-example?file=index.js), [Glitch](https://glitch.com/edit/#!/mwc-button-example?path=index.html)
+```sh
+npm install @material/mwc-button
+```
 
-  * Runs in browsers with [JavaScript Modules](https://caniuse.com/#search=modules): [JSBin](http://jsbin.com/qibisux/edit?html,output),
-[CodePen](https://codepen.io/azakus/pen/deZLja).
+> NOTE: The Material Web Components are distributed as ES2017 JavaScript
+> Modules, and use the Custom Elements API. They are compatible with all modern
+> browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional
+> tooling step is required to resolve *bare module specifiers*, as well as
+> transpilation and polyfills for Edge and IE11. See
+> [here](https://github.com/material-components/material-components-web-components#quick-start)
+> for detailed instructions.
 
-* You can also copy [this HTML file](https://gist.githubusercontent.com/azakus/f01e9fc2ed04e781ad5a52ded7b296e7/raw/266f2f4f91cbfe89b2acc6ec63957b1a3cfe9b39/index.html) into a local file and run it in any browser that supports [JavaScript Modules]((https://caniuse.com/#search=modules)).
+## Example Usage
 
-* When you're ready to use mwc-button in a project, install it via [npm](https://www.npmjs.com/). To run the project in the browser, a module-compatible toolctain is required. We recommend installing the [Polymer CLI](https://github.com/Polymer/polymer-cli) and using its development server as follows.
+### Standard
 
-  1. Ensure the webcomponents polyfills are included in your HTML page
+![](images/standard.png)
+![](images/standard_with_icon.png)
 
-      - Install webcomponents polyfills
+```html
+<mwc-button label="standard"></mwc-button>
+<mwc-button label="standard" icon="code"></mwc-button>
+```
 
-          ```npm i @webcomponents/webcomponentsjs```
+### Outlined
 
-      - Add webcomponents polyfills to your HTML page
+![](images/outlined.png)
+![](images/outlined_with_icon.png)
 
-          ```<script src="@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>```
+```html
+<mwc-button outlined label="outlined"></mwc-button>
+<mwc-button outlined label="outlined" icon="code"></mwc-button>
+```
 
-  1. Add mwc-button to your project:
+### Raised
 
-      ```npm i @material/mwc-button```
+![](images/raised.png)
+![](images/raised_with_icon.png)
 
-  1. Import the mwc-button definition into your HTML page:
+```html
+<mwc-button raised label="raised"></mwc-button>
+<mwc-button raised label="raised" icon="code"></mwc-button>
+```
 
-      ```<script type="module" src="@material/mwc-button/index.js"></script>```
+### Unelevated
 
-      Or into your module script:
+![](images/unelevated.png)
+![](images/unelevated_with_icon.png)
 
-      ```import {Button} from "@material/mwc-button"```
+```html
+<mwc-button unelevated label="unelevated"></mwc-button>
+<mwc-button unelevated label="unelevated" icon="code"></mwc-button>
+```
 
-  1. Create an instance of mwc-button in your HTML page, or via any framework that [supports rendering Custom Elements](https://custom-elements-everywhere.com/):
+### Dense
 
-      ```<mwc-button>Click Here!</mwc-button>```
+![](images/dense.png)
+![](images/dense_with_icon.png)
 
-  1. Install the Polymer CLI:
+```html
+<mwc-button dense unelevated label="dense"></mwc-button>
+<mwc-button dense unelevated label="dense" icon="code"></mwc-button>
+```
 
-      ```npm i -g polymer-cli```
+### Trailing Icon
 
-  1. Run the development server and open a browser pointing to its URL:
+![](images/trailing_icon.png)
 
-      ```polymer serve```
+```html
+<mwc-button label="trailing icon" icon="code" trailingIcon></mwc-button>
+```
 
-  > mwc-button is published on [npm](https://www.npmjs.com/package/@material/mwc-button) using JavaScript Modules.
-  This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.
-  >
-  > However, since mwc-button uses 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.
+### Disabled
 
-  Tools like [WebPack](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) can also be used to serve and/or bundle mwc-button.
+![](images/disabled.png)
+![](images/disabled_with_icon.png)
 
-## Supported Browsers
+```html
+<mwc-button disabled label="disabled"></mwc-button>
+<mwc-button disabled label="disabled" icon="code"></mwc-button>
+```
 
-The last 2 versions of all modern browsers are supported, including
-Chrome, Safari, Opera, Firefox, Edge. In addition, Internet Explorer 11 is also supported.
+### Customize Colors
+
+![](images/custom_color.png)
+
+```css
+mwc-button {
+  --mdc-theme-primary: #e9437a;
+  --mdc-theme-on-primary: white;
+}
+```
+
+## API
+
+### Slots
+*None*
+
+### Properties/Attributes
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| `icon` | `string` | `''` | Icon to display, and `aria-label` value when `label` is not defined.
+| `label` | `string` | `''` | Label to display for the button, and `aria-label`
+| `raised` | `boolean` | `false` | Creates a contained button that is elevated above the surface.
+| `unelevated` | `boolean` | `false` | Creates a contained button that is flush with the surface.
+| `outlined` | `boolean` | `false` | Creates an outlined button that is flush with the surface.
+| `dense` | `boolean` | `false` | Makes the button text and container slightly smaller.
+| `disabled` | `boolean` | `false` | Disabled buttons cannot be interacted with and have no visual interaction effect.
+| `trailingIcon` | `boolean` | `false` | When `true`, `icon` will be displayed _after_ `label`
+
+### Methods
+*None*
+
+### Events
+*None*
+
+### CSS Custom Properties
+
+| Name | Default | Description
+| ---- | ------- | -----------
+| `--mdc-icon-font` | [`Material Icons`](https://google.github.io/material-design-icons/) | Font to use for the icon.
+| `--mdc-theme-primary` | ![](images/color_6200ee.png) `#6200ee` | Background color of the button
+| `--mdc-theme-on-primary` | ![](images/color_ffffff.png) `#ffffff` | Text color of the button
+
+## Additional references
+
+- [MDC Web: Button](https://material.io/develop/web/components/buttons/)
diff --git a/packages/button/images/color_6200ee.png b/packages/button/images/color_6200ee.png
diff --git a/packages/button/images/color_ffffff.png b/packages/button/images/color_ffffff.png
diff --git a/packages/button/images/custom_color.png b/packages/button/images/custom_color.png
diff --git a/packages/button/images/dense.png b/packages/button/images/dense.png
diff --git a/packages/button/images/dense_with_icon.png b/packages/button/images/dense_with_icon.png
diff --git a/packages/button/images/disabled.png b/packages/button/images/disabled.png
diff --git a/packages/button/images/disabled_with_icon.png b/packages/button/images/disabled_with_icon.png
diff --git a/packages/button/images/outlind_with_icon.png b/packages/button/images/outlind_with_icon.png
diff --git a/packages/button/images/outlined.png b/packages/button/images/outlined.png
diff --git a/packages/button/images/raised.png b/packages/button/images/raised.png
diff --git a/packages/button/images/raised_with_icon.png b/packages/button/images/raised_with_icon.png
diff --git a/packages/button/images/standard.png b/packages/button/images/standard.png
diff --git a/packages/button/images/standard_with_icon.png b/packages/button/images/standard_with_icon.png
diff --git a/packages/button/images/trailing_icon.png b/packages/button/images/trailing_icon.png
diff --git a/packages/button/images/unelevated.png b/packages/button/images/unelevated.png
diff --git a/packages/button/images/unelevated_with_icon.png b/packages/button/images/unelevated_with_icon.png
diff --git a/packages/button/src/mwc-button.scss b/packages/button/src/mwc-button.scss
@@ -23,14 +23,10 @@ limitations under the License.
 }
 
 :host {
-  display: inline-flex;
+  display: inline-block;
   outline: none;
 }
 
 :host([disabled]) {
   pointer-events: none;
-}
-
-.mdc-button {
-  flex: auto;
-}
+}