Merge pull request #361 from material-components/fab-readme

README for mwc-fab
material-components · Aug 13, 2019 · 5bb2eaa · 5bb2eaa
2 parents 6aaf412 + f02a6b4
commit 5bb2eaa
Show file tree

Hide file tree

Showing 29 changed files with 164 additions and 67 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,10 +7,11 @@ node_modules
 /packages/*/*.js
 /packages/*/*.js.map
 /packages/*/*.d.ts
+/packages/*/*.tgz
 /packages/*/src/*-css.ts
 /packages/*/package-lock.json
 .tsbuildinfo
 !packages/*/custom_types/**
 /test/benchmark/**/*.js
 /test/benchmark/**/*.js.map
-/test/benchmark/**/*.d.ts
+/test/benchmark/**/*.d.ts
diff --git a/demos/demo-component.css b/demos/demo-component.css
@@ -1,4 +1,4 @@
-@import "https://fonts.googleapis.com/css?family=Roboto|Material+Icons";
+@import "https://fonts.googleapis.com/css?family=Roboto:300,500,600|Material+Icons";
 
 body {
   font-family: Roboto, sans-serif;

diff --git a/demos/fab.html b/demos/fab.html
@@ -24,30 +24,13 @@
   <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;
+    mwc-fab {
+      margin-right: 50px;
+    }
+    .blackAndWhite {
       --mdc-theme-on-secondary: black;
       --mdc-theme-secondary: white;
     }
-
-    .pink {
-      --mdc-theme-on-primary: white;
-      --mdc-theme-primary: #e9437a;
-      --mdc-theme-on-secondary: white;
-      --mdc-theme-secondary: #e9437a;
-    }
-
-    .abs {
-      position: absolute;
-      left: calc(100vw - 128px);
-      top: calc(100vh - 128px);
-    }
-
-
-    .demo-fab-group {
-      max-width: 500px;
-    }
   </style>
 </head>
 <body class="unresolved">
@@ -57,15 +40,10 @@
   </header>
 
   <main>
-
-    <div class="demo-fab-group demo-group-spaced">
-      <mwc-fab icon="explore" label="Explore the world. (This is an example label.)"></mwc-fab>
-      <mwc-fab class="light" icon="code" label="Show me the code. (This is an example label.)"></mwc-fab>
-      <mwc-fab icon="feedback" label="Provide feedback. (This is an example label.)"></mwc-fab>
-      <mwc-fab class="pink" icon="gavel" mini></mwc-fab>
-      <mwc-fab icon="fingerprint" disabled></mwc-fab>
-    </div>
-
+    <mwc-fab icon="edit"></mwc-fab>
+    <mwc-fab icon="add" mini></mwc-fab>
+    <mwc-fab icon="shopping_cart" extended label="Add To Cart"></mwc-fab>
+    <mwc-fab icon="share" class="blackAndWhite"></mwc-fab>
   </main>
 
   <script>

diff --git a/packages/base/.npmignore b/packages/base/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/button/.npmignore b/packages/button/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/checkbox/.npmignore b/packages/checkbox/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/drawer/.npmignore b/packages/drawer/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/fab/.npmignore b/packages/fab/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/fab/README.md b/packages/fab/README.md
@@ -1,64 +1,106 @@
-# mwc-fab
+# `<mwc-fab>` [![Published on npm](https://img.shields.io/npm/v/@material/mwc-fab.svg)](https://www.npmjs.com/package/@material/mwc-fab)
 
-> :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/) icon implementation using [Web Components](https://www.webcomponents.org/introduction)
+A floating action button (FAB) represents the primary action of a screen.
 
-## Getting started
+![](images/standard.png)
+![](images/mini.png)
+![](images/extended.png)
+![](images/custom_color.png)
 
- * The easiest way to try out mwc-fab is to use one of these online tools:
+[Material Design Guidelines: Floating Action Button](https://material.io/design/components/buttons-floating-action-button.html)
 
-    * Runs in all [supported](#supported-browsers) browsers: [StackBlitz](https://stackblitz.com/edit/mwc-icon-example?file=index.js), [Glitch](https://glitch.com/edit/#!/mwc-icon-example?path=index.html)
+## Installation
 
-    * 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).
+```sh
+npm install @material/mwc-fab
+```
 
-* 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)).
+> 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.
 
-* When you're ready to use mwc-fab 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.
+## Example usage
 
-  1. Ensure the webcomponents polyfills are included in your HTML page
+### Standard
 
-      - Install webcomponents polyfills
+![](images/standard.png)
 
-          ```npm i @webcomponents/webcomponentsjs```
+```html
+<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
 
-      - Add webcomponents polyfills to your HTML page
+<mwc-fab icon="favorite"></mwc-fab>
 
-          ```<script src="@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>```
+<script type="module">
+  import '@material/mwc-fab';
+  const fab = document.querySelector('mwc-fab');
+  fab.addEventListener('click', () => {
+    addFavorite();
+  });
+</script>
+```
 
-  1. Add mwc-fab to your project:
+### Mini
 
-      ```npm i @material/mwc-fab```
+![](images/mini.png)
 
-  1. Import the mwc-fab definition into your HTML page:
+```html
+<mwc-fab mini icon="add"></mwc-fab>
+```
 
-      ```<script type="module" src="@material/mwc-fab/index.js"></script>```
+### Extended
 
-      Or into your module script:
+![](images/extended.png)
 
-      ```import {Fab} from "@material/mwc-fab"```
+```html
+<mwc-fab extended icon="shopping_cart" label="Add to cart"></mwc-fab>
+```
+### Customize colors
 
-  1. Create an instance of mwc-fab in your HTML page, or via any framework that [supports rendering Custom Elements](https://custom-elements-everywhere.com/):
+![](images/custom_color.png)
 
-      ```<mwc-fab>sentiment_very_satisfied</mwc-fab>```
+```css
+mwc-fab {
+  --mdc-theme-secondary: white;
+  --mdc-theme-on-secondary: black;
+}
+```
 
-  1. Install the Polymer CLI:
+## API
 
-      ```npm i -g polymer-cli```
+### Slots
+*None*
 
-  1. Run the development server and open a browser pointing to its URL:
+### Properties/Attributes
 
-      ```polymer serve```
+| Name            | Type      | Description
+| --------------- | --------- |------------
+| `icon`          | `string`  | The icon to display.
+| `label`         | `string`  | The label to display when using the `extended` layout, and the `aria-label` attribute in all layouts.
+| `mini`          | `boolean` | Modifies the FAB to be a smaller size, for use on smaller screens. Defaults to `false`.
+| `extended`      | `boolean` | Enable the *extended* layout which includes a text label. Defaults to `false`.
+| `showIconAtEnd` | `boolean` | When in the *extended* layout, position the icon after the label, instead of before. Defaults to `false`.
 
-  > mwc-fab is published on [npm](https://www.npmjs.com/package/@material/mwc-fab) 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-fab 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.
+### Methods
+*None*
 
-  Tools like [WebPack](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) can also be used to serve and/or bundle mwc-fab.
+### Events
+*None*
 
-## Supported Browsers
+### CSS Custom Properties
 
-The last 2 versions of all modern browsers are supported, including
-Chrome, Safari, Opera, Firefox, Edge. In addition, Internet Explorer 11 is also supported.
+| Name                       | Default                                | Description
+| -------------------------- | -------------------------------------- |------------
+| `--mdc-icon-font`          | [`Material Icons`](https://google.github.io/material-design-icons/) | Font to use for the icon.
+| `--mdc-theme-on-secondary` | ![](images/color_ffffff.png) `#ffffff` | Foreground color of the label and icon.
+| `--mdc-theme-secondary`    | ![](images/color_018786.png) `#018786` | Background color of the FAB.
+
+## Additional references
+
+- [MDC Web: Floating Action Button](https://material.io/develop/web/components/buttons/floating-action-buttons/)
diff --git a/packages/fab/images/color_018786.png b/packages/fab/images/color_018786.png
diff --git a/packages/fab/images/color_ffffff.png b/packages/fab/images/color_ffffff.png
diff --git a/packages/fab/images/custom_color.png b/packages/fab/images/custom_color.png
diff --git a/packages/fab/images/extended.png b/packages/fab/images/extended.png
diff --git a/packages/fab/images/mini.png b/packages/fab/images/mini.png
diff --git a/packages/fab/images/standard.png b/packages/fab/images/standard.png
diff --git a/packages/formfield/.npmignore b/packages/formfield/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/icon-button/.npmignore b/packages/icon-button/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/icon/.npmignore b/packages/icon/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/linear-progress/.npmignore b/packages/linear-progress/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/radio/.npmignore b/packages/radio/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/ripple/.npmignore b/packages/ripple/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/slider/.npmignore b/packages/slider/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/snackbar/.npmignore b/packages/snackbar/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/switch/.npmignore b/packages/switch/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/tab-bar/.npmignore b/packages/tab-bar/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/tab-indicator/.npmignore b/packages/tab-indicator/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/tab-scroller/.npmignore b/packages/tab-scroller/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/tab/.npmignore b/packages/tab/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*
diff --git a/packages/top-app-bar/.npmignore b/packages/top-app-bar/.npmignore
@@ -0,0 +1,4 @@
+.tsbuildinfo
+tsconfig.json
+*.tgz
+images/*