From 2512306dbd63c1e3e7812f588ee8b795a1ccf0cc Mon Sep 17 00:00:00 2001 From: Elliott Marquez Date: Fri, 8 Nov 2019 16:42:16 -0800 Subject: [PATCH] readme examples --- packages/linear-progress/README.md | 252 +++++++++++++++++++++++++---- 1 file changed, 217 insertions(+), 35 deletions(-) diff --git a/packages/linear-progress/README.md b/packages/linear-progress/README.md index 749c23c13..bdf728b43 100644 --- a/packages/linear-progress/README.md +++ b/packages/linear-progress/README.md @@ -1,64 +1,246 @@ -# mwc-linear-progress +# `` [![Published on npm](https://img.shields.io/npm/v/@material/mwc-linear-progress.svg)](https://www.npmjs.com/package/@material/mwc-linear-progress) -> :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/) linear-progress implementation using [Web Components](https://www.webcomponents.org/introduction) +Progress indicators express an unspecified wait time or display the length of a process. -## Getting started + - * The easiest way to try out mwc-linear-progress is to use one of these online tools: +[Material Design Guidelines: Progress Indicators](https://material.io/components/progress-indicators/#circular-progress-indicators) - * 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-linear-progress +``` -* 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-linear-progress 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 +### Determinate - - Install webcomponents polyfills + - ```npm i @webcomponents/webcomponentsjs``` +```html + + +``` - - Add webcomponents polyfills to your HTML page +### Indederminate - `````` + - 1. Add mwc-linear-progress to your project: +```html + +``` - ```npm i @material/mwc-linear-progress``` +### Determinate buffer - 1. Import the mwc-linear-progress definition into your HTML page: + - `````` +```html + +``` - Or into your module script: +### Reversed - ```import {LinearProgress} from "@material/mwc-linear-progress"``` + - 1. Create an instance of mwc-linear-progress in your HTML page, or via any framework that [supports rendering Custom Elements](https://custom-elements-everywhere.com/): - `````` +```html + + +``` - 1. Install the Polymer CLI: +### Styled - ```npm i -g polymer-cli``` + - 1. Run the development server and open a browser pointing to its URL: +```html + + +``` - ```polymer serve``` +## API - > mwc-linear-progress is published on [npm](https://www.npmjs.com/package/@material/mwc-linear-progress) 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-linear-progress 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. +### Slots - Tools like [WebPack](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) can also be used to serve and/or bundle mwc-linear-progress. +None -## Supported Browsers +### Properties/Attributes -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 | Type | Description +| ----------------------- | --------- |------------ +| `open` | `boolean` | Whether the linear-progress should open. +| `hideActions` | `boolean` | Hides the actions footer of the linear-progress. Needed to remove excess padding when no actions are slotted in. +| `stacked` | `boolean` | Whether to stack the action buttons. +| `heading` | `string` | Heading text of the linear-progress. +| `scrimClickAction` | `string` | _Default: 'close'_ – Action to be emitted with the `closing` and `closed` events when the linear-progress closes because the scrim was clicked (see [actions section](#actions)). +| `escapeKeyAction` | `string` | _Default: 'close'_ – Action to be emitted with the `closing` and `closed` events when the linear-progress closes because the excape key was pressed (see [actions section](#actions)). +| `defaultAction` | `string` | _Default: 'close'_ – Action to be emitted with the `closing` and `closed` events when `.open` is toggled (see [actions section](#actions)). +| `actionAttribute` | `string` | _Default: 'linear-progressAction'_ – Attribute to read in light dom of linear-progress for closing action value (see [actions section](#actions)). +| `initialFocusAttribute` | `string` | _Default: 'linear-progressInitialFocus'_ – Attribute to search for in light dom for initial focus on linear-progress open. + +### Methods + +| Name | Description +| -------- | ------------- +| `forceLayout() => void` | Forces linear-progress to relayout (animation frame time). May be required if linear-progress size is incorrect or if stacked layout has not been triggered correctly. +| `focus() => void` | Focuses on the initial focus element if defined (see [focus section](#focus)). +| `blur() => void` | Blurs the active element. + +### Listeners +| Event Name | Target | Description +| ------------------- | ------------ | ----------- +| `click` | root element | Detects if clicked target is a linear-progress action. +| `resize` | `window ` | Performs linear-progress layout (passive). +| `orientationchange` | `window` | Performs linear-progress layout (passive). +| `keydown` | `mwc-linear-progress` | Listens for the enter key to click the default button (passive). +| `keydown` | `document` | Listens for the escape key to close the linear-progress (see [`escapeKeyAction`](#properties)). + +### Events + +| Event Name | Target | Detail | Description +| ---------- | ------------ | ------------------ | ----------- +| `opening` | `mwc-linear-progress` | `{}` | Fired when the linear-progress is beginning to open. +| `opened` | `mwc-linear-progress` | `{}` | Fired once the linear-progress is finished opening (after animation). +| `closing` | `mwc-linear-progress` | `{action: string}` | Fired when the linear-progress is is beginning to close. Detail is the action that closed the linear-progress (see [actions section](#actions)). +| `closed` | `mwc-linear-progress` | `{action: string}` | Fired once the linear-progress is finished closing (after animation). Detail is the action that closed the linear-progress (see [actions section](#actions)). + +### CSS Custom Properties + +| Name | Default | Description +| ----------------------------------- | --------------------- |------------ +| `--mdc-theme-surface` | ![](images/color_fff.png) `#fff` | Color of the linear-progress surface's background. +| `--mdc-linear-progress-scrim-color` | ![](images/color_0,0,0,32.png) `rgba(0, 0, 0, 0.32)` | Color of the scrim. (**Note:** setting alpha to 0 will still make scrim clickable but transparent). +| `--mdc-linear-progress-heading-ink-color` | ![](images/color_0,0,0,87.png) `rgba(0, 0, 0, 0.87)` | Color of the heading text. +| `--mdc-linear-progress-content-ink-color` | ![](images/color_0,0,0,6.png) `rgba(0, 0, 0, 0.6)` | Color applied to the projected content. (**Note:** it may also be possible to style the content via the light DOM since it is not encapsulated in a shadow root). +| `--mdc-linear-progress-scroll-divider-color` | ![](images/color_0,0,0,12.png) `rgba(0, 0, 0, 0.12)` | Color of the dividers present when linear-progress is scrollable. +| `--mdc-linear-progress-min-width` | `280px` | min-width ofthe linear-progress surface. +| `--mdc-linear-progress-max-width` | `560px` | max-width of the linear-progress surface. (**Note:** if max-width is < `560px`, there is a visual jank bug that will occur causing the max width to be `560px` when the window is sized to <= than `560px`). +| `--mdc-linear-progress-max-height` | `calc(100% - 32px)` | Max height of the linear-progress surface. +| `--mdc-linear-progress-shape-radius` | `4px` | Corner radius of the linear-progress surface. + +### Actions + +Actions close the linear-progress on click. You can define an action by slotting an +element with the `linear-progressAction="..."` string attribute. The name of the +attribute can be customized by the +[`actionAttribute` property](#propertiesattributes). When a clickable element +with the `linear-progressAction` attribute is clicked, `mwc-linear-progress` will get the value +of the attribute and fire the `closing` and subsequent `closed` events with a +detail of `{action: }`. + +For example: + + + +```html + +
+
+ This is my content. Here is an actionable button: + +
+
+ This is my content. Here is a diabled actionable button: + +
+
+ ok + cancel + +``` + +In this example we have 3 actionable elements: +```html + +``` + +```html + +``` + +```html +ok +``` + +* Clicking button 1 will close the linear-progress and fire a `closing` and subsequently +a `closed` event with a detail of `{action: 'contentButton'}`. +* Clicking button 2 will not close the linear-progress since it is disabled +* Clicking the cancel `mwc-button` will not close the linear-progress as it does not have +a `linear-progressAction` attribute set on it. +* Clicking the ok `mwc-button` will close the linear-progress and fire a `closing` and +subsequently a `closed` event with a detail of `{action: 'ok'}`. +* Setting `document.querySelector('mwc-linear-progress').open = false;` will close the +linear-progress and fire a `closing` and subsequently a `closed` event with a detail of +`{action: 'close'}` (action is configurable via +[`defaultAction` property](#propertiesattributes)). + +### Focus + +Initial focus can be set on an element with the `linear-progressInitialFocus` boolean +attribute (configurable via the +[`initialFocusAttribute` property](#propertiesattributes)). + +For example: + + + +```html + +
+ In this example we set "linear-progressInitialFocus" on the mwc-textfield. + When this linear-progress opens, it is auto-focused. +
+ + + + Primary + + + Secondary + + +``` + +In this example we set `linear-progressInitialFocus` on the `mwc-textfield`, so +`mwc-textfield.focus()` will be called on the button. This attribute can also be +set on anything in the light DOM of `mwc-linear-progress` or the light dom of the +flattened, distributed nodes including the primary and secondary actions. Only +one element designated with this attribute will be focused. + +Calling `focus()` on the `mwc-linear-progress` itself will call `focus()` on any +`linear-progressInitialFocus` element in the light DOM of `mwc-linear-progress`. + +Calling `blur()` on the `mwc-linear-progress` will attempt to blur the +[`activeElement`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/activeElement) +of the shadow root of `mwc-linear-progress` or the +[root node](https://developer.mozilla.org/en-US/docs/Web/API/Node/getRootNode) +of the linear-progress. + +## Additional references + +- [MDC Web linear-progresss](https://material-components.github.io/material-components-web-catalog/#/component/linear-progress-indicator)