From 082e2f3647cf47d65090132a3a13e05634be76f3 Mon Sep 17 00:00:00 2001 From: Andy Dvorak Date: Wed, 17 Jan 2018 09:19:39 -0800 Subject: [PATCH] WIP: Squashed commit of the following: commit bffadd343207387c8f0a4fa09f084145ced1287e Author: Andrew C. Dvorak Date: Wed Jan 17 09:09:56 2018 -0800 style(demos): Clean up theme demo Sass and HTML (#1973) - Remove unused code - IE 11 compatible property values (`unset` -> `auto`) - Fix duplicate IDs - Use `--stroked` buttons instead of `--raised` for checkbox demo - Rename CSS classes to be more BEM-y - Rename and reorganize Sass demo vars - Reword text-field labels and helper text for clarity - Remove `getAll()` - Inline some JS vars commit 3a1786f614aff35bf047743bb0cf2e1d84814330 Author: Dominic Carretto Date: Wed Jan 17 11:37:03 2018 -0500 fix(slider): Add MDCSliderFoundation export (#1959) commit 815eadeaab27a9276621300f24b92a4d815efe4f Author: Simon Olofsson Date: Wed Jan 17 17:36:07 2018 +0100 docs(menu): Remove obsolete `mdc-simple-menu--open-from` classes. (#1927) commit 6078784954b484df575fd54bd732445add358a96 Author: Chafic Najjar Date: Wed Jan 17 18:26:00 2018 +0200 docs: Rewrite all instances of "MDC-Web" as "MDC Web" (#1960) Resolves #1924 commit e87c1102a8feabad172d5f9f041ebb2b9a6c9442 Author: pndewit Date: Wed Jan 17 17:23:03 2018 +0100 docs(drawer): Fix missing link to temporary drawer demo (#1922) commit 003dff4f7258b849cbff2124bd90d394d58c0440 Author: Chafic Najjar Date: Wed Jan 17 18:20:35 2018 +0200 docs: Fix broken links to AngularJS's Git commit guidelines (#1888) --- .github/ISSUE_TEMPLATE.md | 4 +- CONTRIBUTING.md | 16 +-- README.md | 10 +- demos/theme/_theme-shared.scss | 109 +++------------ demos/theme/index.html | 132 ++++++++---------- docs/README.md | 2 +- docs/authoring-components.md | 28 ++-- docs/closure-compiler.md | 24 ++-- .../building-beautiful-sites/README.md | 2 +- .../completed/index.html | 2 +- .../docsite/3-toolbar.md | 4 +- .../docsite/4-navigation.md | 2 +- .../docsite/5-layout.md | 2 +- .../docsite/introduction.md | 4 +- .../starter/index.html | 2 +- docs/contribute/bug_fix.md | 2 +- docs/contribute/feat.md | 2 +- docs/docsite-index.md | 4 +- docs/getting-started.md | 50 +++---- docs/integrating-into-frameworks.md | 16 +-- docs/migrating-from-mdl.md | 76 +++++----- docs/theming.md | 38 ++--- package.json | 2 +- packages/material-components-web/README.md | 4 +- packages/mdc-auto-init/README.md | 6 +- packages/mdc-base/README.md | 4 +- packages/mdc-drawer/README.md | 3 + packages/mdc-form-field/README.md | 8 +- packages/mdc-icon-toggle/README.md | 2 +- packages/mdc-list/README.md | 2 +- packages/mdc-menu/README.md | 10 +- packages/mdc-menu/simple/constants.js | 3 - packages/mdc-ripple/README.md | 6 +- packages/mdc-rtl/_mixins.scss | 2 +- packages/mdc-slider/index.js | 2 +- packages/mdc-tabs/README.md | 2 +- packages/mdc-theme/README.md | 6 +- packages/mdc-theme/_mixins.scss | 2 +- scripts/check-pkg-for-release.js | 10 +- scripts/pre-release.sh | 6 +- 40 files changed, 264 insertions(+), 347 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 05c02c0ec41..ecec351923a 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -15,7 +15,7 @@ feature requests. If you'd like to work on a component, please ensure that you *submit an Engineering Outline before submitting a pull request*. You can read more about this in our [contributing docs](https://github.com/material-components/material-components-web/blob/master/CONTRIBUTING.md#building-components). -MDC-Web is still under active development. You can see our current progress on [master](https://github.com/material-components/material-components-web/tree/master) as well as an overview of our [architecture and practices](https://github.com/material-components/material-components-web/blob/master/docs/code). +MDC Web is still under active development. You can see our current progress on [master](https://github.com/material-components/material-components-web/tree/master) as well as an overview of our [architecture and practices](https://github.com/material-components/material-components-web/blob/master/docs/code). If you're interested in information for a specific component, check out our [component issues](https://github.com/material-components/material-components-web/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Av2-component) to see which milestone it's associated with and subscribe to updates to it. If an issue has the `in-tracker` label, you can also take a look at our [public Pivotal Tracker](https://www.pivotaltracker.com/n/projects/1664011) for a rough estimate of when we'll get to it. @@ -25,7 +25,7 @@ Our team prioritizes responding to as many engineering and user experience quest Follow the template below to ensure the quickest and most accurate response to your issue. -### What MDC-Web Version are you using? +### What MDC Web Version are you using? > Please be specific, e.g. _major.minor.patch_ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7af3e005ef3..93bbd2dc6bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Material Components Web (MDC-Web) +# Contributing to Material Components Web (MDC Web) We'd love for you to contribute and make Material Components for the web even better than it is today! Here are the guidelines we'd like you to follow: @@ -8,7 +8,7 @@ Here are the guidelines we'd like you to follow: - [Setting up your development environment](#setting-up-your-development-environment) - [Building Components](#building-components) - [Running the development server](#running-the-development-server) - - [Building MDC-Web](#building-mdc-web) + - [Building MDC Web](#building-mdc-web) - [Linting / Testing / Coverage Enforcement](#linting--testing--coverage-enforcement) - [Running Tests across browsers](#running-tests-across-browsers) - [Coding Style](#coding-style) @@ -20,11 +20,11 @@ The Material Components contributing policies and procedures can be found in the ## Development Process -We strive to make developing Material Components Web as frictionless as possible, both for ourselves and for our community. This section should get you up and running working on the MDC-Web codebase. Before beginning development, you may want to read through our overview on [architecture and best practices](./docs/code) to get a better understanding of our overall structure. +We strive to make developing Material Components Web as frictionless as possible, both for ourselves and for our community. This section should get you up and running working on the MDC Web codebase. Before beginning development, you may want to read through our overview on [architecture and best practices](./docs/code) to get a better understanding of our overall structure. ### Setting up your development environment -You'll need a recent version of [nodejs](https://nodejs.org/en/) to work on MDC-Web. We [test our builds](https://travis-ci.org/material-components/material-components-web) using both the latest and LTS node versions, so use of one of those is recommended. You can use [nvm](https://github.com/creationix/nvm) to easily install and manage different versions of node on your system. +You'll need a recent version of [nodejs](https://nodejs.org/en/) to work on MDC Web. We [test our builds](https://travis-ci.org/material-components/material-components-web) using both the latest and LTS node versions, so use of one of those is recommended. You can use [nvm](https://github.com/creationix/nvm) to easily install and manage different versions of node on your system. > **NOTE**: If you expect to commit updated or new dependencies, please ensure you are using npm 5, which will > also update `package-lock.json` correctly when you install or upgrade packages. @@ -75,12 +75,12 @@ MDC_ENV=development npm run build && gcloud app deploy app.yaml --project google gcloud app browse ``` -The above script will build and deploy the app to mdc-web's dev server with your userid as its version number, you can switch to your version by prepending `$USER-dot-` to the URL opened when you run `gcloud app browse`. This would be helpful if we need to share work-in-progress work within teams and designers. +The above script will build and deploy the app to MDC Web's dev server with your userid as its version number, you can switch to your version by prepending `$USER-dot-` to the URL opened when you run `gcloud app browse`. This would be helpful if we need to share work-in-progress work within teams and designers. -### Building MDC-Web +### Building MDC Web ``` -npm run build # Builds an unminified version of MDC-Web within build/ +npm run build # Builds an unminified version of MDC Web within build/ npm run build:min # Same as above, but enables minification npm run dist # Cleans out build/ and runs both of the above commands sequentially ``` @@ -124,7 +124,7 @@ Our entire coding style is enforced automatically through the use of linters. Ch ### Submitting Pull Requests -When submitting PRs, make sure you're following our commit message conventions (which are the same as [angular's](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit)); our `commit-msg` hook should automatically enforce this. We also support [commitizen](https://www.npmjs.com/package/commitizen), which you can +When submitting PRs, make sure you're following our commit message conventions (which are the same as [angular's](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits)); our `commit-msg` hook should automatically enforce this. We also support [commitizen](https://www.npmjs.com/package/commitizen), which you can use to auto-format commit messages for you. When submitting PRs for large changes, be sure to include an adequate background in the description diff --git a/README.md b/README.md index 07f60ca0135..d96c2c3f7a6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # Material Components for the web -Material Components for the web (MDC-Web) helps developers execute [Material Design](https://www.material.io). +Material Components for the web (MDC Web) helps developers execute [Material Design](https://www.material.io). Developed by a core team of engineers and UX designers at Google, these components enable a reliable development workflow to build beautiful and functional web projects. Material Components for the web is the successor to [Material Design Lite](https://getmdl.io/), and has 3 high-level goals: @@ -16,11 +16,11 @@ Material Components for the web is the successor to [Material Design Lite](https - [RMWC: React Material Web Components](https://github.com/jamesmfriedman/rmwc) - [Angular MDC](https://github.com/trimox/angular-mdc-web) - [Blox Material](https://blox.src.zone/material): Angular Integration Library. - - [Vue MDC Adapter](https://github.com/stasson/vue-mdc-adapter): MDC-Web Integration for Vue.js (using [foundation/adapters](./docs/integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters).) - - [Material Components Vue](https://github.com/matsp/material-components-vue): MDC-Web Integration for Vue.js (using [vanilla components](./docs/integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) + - [Vue MDC Adapter](https://github.com/stasson/vue-mdc-adapter): MDC Web Integration for Vue.js (using [foundation/adapters](./docs/integrating-into-frameworks.md#the-advanced-approach-using-foundations-and-adapters).) + - [Material Components Vue](https://github.com/matsp/material-components-vue): MDC Web Integration for Vue.js (using [vanilla components](./docs/integrating-into-frameworks.md#the-simple-approach-wrapping-mdc-web-vanilla-components)) - More coming soon! Feel free to submit a pull request adding your library to this list, so long as you meet our [criteria](docs/integrating-into-frameworks.md). -MDC-Web strives to seamlessly incorporate into a wider range of usage contexts, from simple static websites to complex, JavaScript-heavy applications to hybrid client/server rendering systems. In short, whether you're already heavily invested in another framework or not, it should be easy to incorporate Material Components into your site in a lightweight, idiomatic fashion. +MDC Web strives to seamlessly incorporate into a wider range of usage contexts, from simple static websites to complex, JavaScript-heavy applications to hybrid client/server rendering systems. In short, whether you're already heavily invested in another framework or not, it should be easy to incorporate Material Components into your site in a lightweight, idiomatic fashion. **[Demos](https://material-components-web.appspot.com/)** (updated with every release) @@ -61,7 +61,7 @@ introduction to the library. ## Installing individual components -MDC-Web is modular by design. Each component lives within its own packages under the +MDC Web is modular by design. Each component lives within its own packages under the [@material npm org](https://www.npmjs.com/org/material). ``` diff --git a/demos/theme/_theme-shared.scss b/demos/theme/_theme-shared.scss index 52816c8998b..e808d5f4dea 100644 --- a/demos/theme/_theme-shared.scss +++ b/demos/theme/_theme-shared.scss @@ -43,7 +43,10 @@ // stylelint-disable selector-class-pattern, selector-max-type, scss/dollar-variable-pattern $demo-section-margin: 48px; -$demo-custom-color: $material-color-red-500; + +$demo-color-custom: $material-color-red-500; +$demo-color-low-luminance: $material-color-brown-900; +$demo-color-high-luminance: $material-color-amber-50; // // Global styles @@ -60,7 +63,7 @@ body { } // -// Page toolbar +// Toolbar // .demo-anchor-with-toolbar-offset { @@ -117,25 +120,20 @@ body { transition: none; } -.demo-component-section__heading .demo-component-section__permalink { +.demo-component-section__permalink { color: inherit; opacity: 0; -} -.demo-component-section__permalink { .demo-component-section:hover &, - .demo-component-section__heading--focus & { + .demo-component-section__heading--focus-within & { opacity: 1; } } // -// Baseline theme color demo +// CSS class demo // -$low-luminance-color: #3e2723; -$high-luminance-color: #fff8e1; - .demo-fieldset--color { @include mdc-rtl-reflexive-box(margin, right, 36px); } @@ -151,16 +149,7 @@ $high-luminance-color: #fff8e1; flex-direction: column; } -.demo-theme-color-swatches__label { - display: inline-block; - box-sizing: border-box; - width: 130px; - margin-bottom: 1em; -} - .demo-theme-color-swatch { - // TODO(acdvorak): mdc-elevation (and other similar mixins) should figure out the correct contrast color automatically - // based on $mdc-theme-background. @include mdc-elevation(1); display: inline-block; @@ -174,27 +163,27 @@ $high-luminance-color: #fff8e1; } .demo-theme-bg--low-luminance { - background-color: $low-luminance-color; + background-color: $demo-color-low-luminance; } .demo-theme-bg--low-luminance-light { - background-color: mdc-theme-light-variant($low-luminance-color); + background-color: mdc-theme-light-variant($demo-color-low-luminance); } .demo-theme-bg--low-luminance-dark { - background-color: mdc-theme-dark-variant($low-luminance-color); + background-color: mdc-theme-dark-variant($demo-color-low-luminance); } .demo-theme-bg--high-luminance { - background-color: $high-luminance-color; + background-color: $demo-color-high-luminance; } .demo-theme-bg--high-luminance-light { - background-color: mdc-theme-light-variant($high-luminance-color); + background-color: mdc-theme-light-variant($demo-color-high-luminance); } .demo-theme-bg--high-luminance-dark { - background-color: mdc-theme-dark-variant($high-luminance-color); + background-color: mdc-theme-dark-variant($demo-color-high-luminance); } .demo-theme-bg--custom-light { @@ -228,44 +217,10 @@ $high-luminance-color: #fff8e1; // Button demo // -.mdc-button.secondary-text-button { - @include mdc-button-ink-color($mdc-theme-secondary); - @include mdc-states($mdc-theme-secondary); - - @include mdc-theme-dark(".mdc-button") { - @include mdc-button-ink-color($mdc-theme-secondary); - @include mdc-states($mdc-theme-secondary); - } -} - -.mdc-button.secondary-filled-button { - @include mdc-button-filled-accessible($mdc-theme-secondary); - - @include mdc-theme-dark(".mdc-button") { - @include mdc-button-filled-accessible($mdc-theme-secondary); - } -} - -.mdc-button.secondary-stroked-button { - @include mdc-button-ink-color($mdc-theme-secondary); - @include mdc-button-stroke-color($mdc-theme-secondary); - @include mdc-states($mdc-theme-secondary); - - @include mdc-theme-dark(".mdc-button") { - @include mdc-button-ink-color($mdc-theme-secondary); - @include mdc-button-stroke-color($mdc-theme-secondary); - @include mdc-states($mdc-theme-secondary); - } -} - .demo-fieldset--button + .demo-fieldset--button { margin-top: 16px; } -.demo-button { - margin: 10px; -} - .demo-button__code { font-size: smaller; text-transform: none; @@ -323,11 +278,11 @@ $high-luminance-color: #fff8e1; @include mdc-rtl-reflexive-box(margin, right, 10px); } -.demo-checkbox-toggle { +.demo-checkbox-toggle-button { @include mdc-rtl-reflexive-box(margin, right, 10px); } -.demo-checkbox-wrapper + .demo-checkbox-toggle { +.demo-checkbox-wrapper + .demo-checkbox-toggle-button { @include mdc-rtl-reflexive-property(margin, 20px, 10px); } @@ -337,8 +292,8 @@ $high-luminance-color: #fff8e1; .demo-dialog { position: relative; - justify-content: unset; - z-index: unset; + justify-content: flex-start; + z-index: auto; } // @@ -388,12 +343,12 @@ $high-luminance-color: #fff8e1; display: inline-flex; } -.demo-icon-toggle__row { +.demo-icon-toggle-row { display: flex; flex-wrap: wrap; } -.demo-icon-toggle__tile { +.demo-icon-toggle-tile { @include mdc-rtl-reflexive-box(margin, right, 10px); margin-top: 0; @@ -409,11 +364,11 @@ $high-luminance-color: #fff8e1; // Linear Progress demo // -.demo-linear-progress__row { +.demo-linear-progress-row { margin: 32px 0; } -.demo-linear-progress__row + .demo-linear-progress__row { +.demo-linear-progress-row + .demo-linear-progress-row { margin-top: 64px; } @@ -434,26 +389,6 @@ $high-luminance-color: #fff8e1; margin-right: 8px; } -@mixin demo-radio-color($color) { - .mdc-radio__native-control:checked + .mdc-radio__background { - &::before { - @include mdc-theme-prop(background-color, $color); - } - - .mdc-radio__outer-circle { - @include mdc-theme-prop(border-color, $color); - } - - .mdc-radio__inner-circle { - @include mdc-theme-prop(background-color, $color); - } - } -} - -.demo-radio--secondary { - @include demo-radio-color($mdc-theme-secondary); -} - // // Switch demo // diff --git a/demos/theme/index.html b/demos/theme/index.html index d32f4da4810..165a0797613 100644 --- a/demos/theme/index.html +++ b/demos/theme/index.html @@ -81,7 +81,6 @@
-

Baseline Colors

@@ -387,8 +386,8 @@

- - + + @@ -469,8 +468,8 @@

#

-
-
+
+

Enabled

Enabled
-
+

Disabled

# -
+
Indeterminate
@@ -522,7 +521,7 @@

-
+
Buffer
@@ -606,7 +605,7 @@

    -
  • +
  • Pick a food group
  • @@ -676,12 +675,12 @@

    - +
    - +
    @@ -760,10 +759,11 @@

    - - + +

    - - + +

    - Must provide a name + A valid email address is required

    -
    @@ -801,10 +804,6 @@

    diff --git a/docs/README.md b/docs/README.md index 206c1409f0e..3ab8a3f82d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,4 +11,4 @@ This section includes supporting documentation aimed to both improve the onboard To jump right in and begin using the library, check out our [Getting Started Guide](./getting-started.md) -If you're interested in a general overview of MDC-Web, check out [the MDC Repository README](../README.md). +If you're interested in a general overview of MDC Web, check out [the MDC Repository README](../README.md). diff --git a/docs/authoring-components.md b/docs/authoring-components.md index 728d57c7f43..259a72c364b 100644 --- a/docs/authoring-components.md +++ b/docs/authoring-components.md @@ -7,8 +7,8 @@ path: /docs/authoring-components/ # Authoring Components -This document serves as a reference for developing components either directly for MDC-Web or -external components that would like to interface with the MDC-Web ecosystem. +This document serves as a reference for developing components either directly for MDC Web or +external components that would like to interface with the MDC Web ecosystem. > Please note that since this project is still in its early stages of development, these practices may be subject to change. They will stabilize as we near towards a full release. @@ -31,7 +31,7 @@ may be subject to change. They will stabilize as we near towards a full release. * [Design adapter interfaces to be simple and intuitive](#design-adapter-interfaces-to-be-simple-and-intuitive) * [Do not reference host objects within foundation code.](#do-not-reference-host-objects-within-foundation-code) * [Clean up all references on destruction](#clean-up-all-references-on-destruction) -* [Authoring components for MDC-Web](#authoring-components-for-mdc-web) +* [Authoring components for MDC Web](#authoring-components-for-mdc-web) * [File Structure](#file-structure) * [License Stanzas](#license-stanzas) * [Scss](#scss) @@ -57,9 +57,9 @@ may be subject to change. They will stabilize as we near towards a full release. The first two sections of this document describe general guidelines for how to think about building a component, as well as criteria for what makes a good component. Anyone interested in building -components either directly for MDC-Web or as an external component that plays well within the -MDC-Web ecosystem should find it useful. The third section talks about authoring components -specifically for MDC-Web, and is best suited for those looking to contribute directly to the +components either directly for MDC Web or as an external component that plays well within the +MDC Web ecosystem should find it useful. The third section talks about authoring components +specifically for MDC Web, and is best suited for those looking to contribute directly to the project. Note that this document assumes you are familiar with the library and its @@ -68,7 +68,7 @@ are brand new to the project, we recommend starting with our [Getting Started Gu ## How to build a component -This section outlines the thought process behind authoring new components for MDC-Web. It is +This section outlines the thought process behind authoring new components for MDC Web. It is inspired by React's [Thinking in React](https://facebook.github.io/react/docs/thinking-in-react.html) article. Starting out from nothing and going straight to a component/adapter/foundation implementation can be @@ -79,7 +79,7 @@ following steps. To demonstrate this approach, we will build a **red-blue toggle**, very simple toggle button that toggles between a red background with blue text, and vice versa. While not a Material Design -component, it demonstrates the concepts of how to think about building for MDC-Web. +component, it demonstrates the concepts of how to think about building for MDC Web. ### Start with a simple component prototype @@ -144,10 +144,10 @@ class RedblueTogglePrototype { new RedblueTogglePrototype(document.querySelector('.redblue-toggle')); ``` -Note how the JS Component does not reference MDC-Web in any way, nor does it have any notion +Note how the JS Component does not reference MDC Web in any way, nor does it have any notion of foundations or adapters. By omitting this work, you can rapidly experiment with your component, incorporating changes quickly and easily. Nonetheless, the way the component is prototype looks -quite similar to the way that the MDC-Web component will eventually be built. +quite similar to the way that the MDC Web component will eventually be built. ### Identify host environment interactions @@ -457,9 +457,9 @@ may be retained. There are two accurate litmus tests to ensure this is being don is kept track of, and cleaned up within destroy. For example, every `setTimeout()` call should have its ID retained by the foundation/component, and have `clearTimeout()` called on it within destroy. -## Authoring components for MDC-Web +## Authoring components for MDC Web -The following guidelines are for those who wish to contribute directly to MDC-web. In addition to +The following guidelines are for those who wish to contribute directly to MDC Web. In addition to adhering to all of the practices above, we have additional conventions we expect contributors to adhere to. It's worth noting that most of these conventions - including our coding style, commit message format, and test coverage - are _automatically enforced via linters_, both so that @@ -761,13 +761,13 @@ Concretely: > NOTE: This section was introduced as part of our [closure compatibility milestone](https://github.com/material-components/material-components-web/milestone/4). Our currently existing components are in the process of being made compatible with closure. -All core MDC-Web components must be fully compatible with the Google Closure Compiler using its +All core MDC Web components must be fully compatible with the Google Closure Compiler using its advanced compilation mechanisms. We've provided a thorough explanation of this, as well as conventions, examples, and common closure patterns you may not be used to, in our [closure compiler documentation](./closure-compiler.md). ### Testing -The following guidelines should be used to help write tests for MDC-Web code. Our tests are written +The following guidelines should be used to help write tests for MDC Web code. Our tests are written using [mocha](https://mochajs.org/) with the [qunit UI](https://mochajs.org/#qunit), and are driven by [karma](https://karma-runner.github.io/1.0/index.html). We use the [chai assert API](http://chaijs.com/api/assert/) for assertions, and [testdouble](https://github.com/testdouble/testdouble.js/) for mocking and stubbing. diff --git a/docs/closure-compiler.md b/docs/closure-compiler.md index 4394d2ddc0a..20504e51097 100644 --- a/docs/closure-compiler.md +++ b/docs/closure-compiler.md @@ -5,26 +5,26 @@ section: docs path: /docs/closure-compiler/ --> -# Annotating MDC-Web for the Closure Compiler +# Annotating MDC Web for the Closure Compiler > TL;DR read the section on our [type system](#mdc-web-type-system) and our [closure compiler conventions](#mdc-web-closure-conventions). ## Who this document is for -This document is for _core contributors to MDC-Web, as well as contributors who wish to author +This document is for _core contributors to MDC Web, as well as contributors who wish to author new components, or make non-trivial changes to existing components._ It assumes you're familiar with our codebase, and have read through most of our [Authoring Components guide](./authoring-components.md). ## Why this is needed -MDC-Web - and Material Design in general - was created by Google. Therefore, it is not only a top -priority that MDC-Web works seamlessly for our external community, but also that _MDC-Web works +MDC Web - and Material Design in general - was created by Google. Therefore, it is not only a top +priority that MDC Web works seamlessly for our external community, but also that _MDC Web works seamlessly for all Google applications_. At Google, all Javascript is processed and minified by the [Closure Compiler](https://github.com/google/closure-compiler) (which will be referred to as **closure**, the **compiler**, or any combination of those terms). Thus, _in order for every Google -application to deem MDC-Web viable for use within it, the library must be compilable using +application to deem MDC Web viable for use within it, the library must be compilable using closure's [advanced compilation](https://developers.google.com/closure/compiler/docs/api-tutorial3) mechanisms_. @@ -68,12 +68,12 @@ accessor properties). You can use [this starter template](https://goo.gl/YSQkDi) to help debug your closure code, which has all of the above settings pre-configured (Even though the UI shows optimization is simple). -## MDC-Web Type System +## MDC Web Type System -The following UML-like diagram shows a conceptual overview of the basic type system for MDC-Web. The +The following UML-like diagram shows a conceptual overview of the basic type system for MDC Web. The diagram uses closure-esque type syntax, and represents what's in [mdc-base](../packages/mdc-base). -![MDC-Web Type System UML(-like) diagram](https://docs.google.com/drawings/d/1mJBPiUkdFiXkU5A6kAdpZD5nXr6NkHIIW_vMNVdIvYY/pub?w=960&h=720) +![MDC Web Type System UML(-like) diagram](https://docs.google.com/drawings/d/1mJBPiUkdFiXkU5A6kAdpZD5nXr6NkHIIW_vMNVdIvYY/pub?w=960&h=720) > Note that the actual code to express this parameterization will vary slightly from the UML above, since closure does not support bounded generics. @@ -90,13 +90,13 @@ The overall type system is relatively straightforward, and boils down to 3 main `MDCRippleAdapter`. Thus, when declaring the `MDCRipple` class, the proper JSDoc to specify this would be included: `@extends MDCComponent`. -## MDC-Web Closure Conventions +## MDC Web Closure Conventions -The following guidelines outline the general conventions for writing closurized code for MDC-Web. +The following guidelines outline the general conventions for writing closurized code for MDC Web. This section should contain most - if not all - of what you need to get up and running writing closure for our codebase. It also includes an [example component skeleton](#an-example-component-skeleton). -### Making MDC-Web aware of closure components (temporary) +### Making MDC Web aware of closure components (temporary) Until our [closure compatibility milestone](https://github.com/material-components/material-components-web/milestone/4) has been reached, please ensure that whenever a component is annotated, it's directory name under `packages/` is added to the `"closureWhitelist"` @@ -772,6 +772,6 @@ be found within that file. ## Where to go for more help -If you're working on an issue for MDC-Web and find yourself wrestling with closure, please don't +If you're working on an issue for MDC Web and find yourself wrestling with closure, please don't hesitate to [reach out on our discord channel](https://discord.gg/pRKaJB9) and we'll try and help you out. diff --git a/docs/codelabs/building-beautiful-sites/README.md b/docs/codelabs/building-beautiful-sites/README.md index 927210fab63..8ed90aa34c7 100644 --- a/docs/codelabs/building-beautiful-sites/README.md +++ b/docs/codelabs/building-beautiful-sites/README.md @@ -1,2 +1,2 @@ This directory hosts a [Google Codelab](https://codelabs.developers.google.com/) demonstrating how -to use MDC-Web to easily build beautiful sites. It will be publicly available shortly. +to use MDC Web to easily build beautiful sites. It will be publicly available shortly. diff --git a/docs/codelabs/building-beautiful-sites/completed/index.html b/docs/codelabs/building-beautiful-sites/completed/index.html index a55f59ae33f..64066e6670f 100644 --- a/docs/codelabs/building-beautiful-sites/completed/index.html +++ b/docs/codelabs/building-beautiful-sites/completed/index.html @@ -3,7 +3,7 @@ - Shrine (MDC-Web Example App) + Shrine (MDC Web Example App) diff --git a/docs/codelabs/building-beautiful-sites/docsite/3-toolbar.md b/docs/codelabs/building-beautiful-sites/docsite/3-toolbar.md index d1f2ef6b353..8e7c5ec226c 100644 --- a/docs/codelabs/building-beautiful-sites/docsite/3-toolbar.md +++ b/docs/codelabs/building-beautiful-sites/docsite/3-toolbar.md @@ -18,7 +18,7 @@ Duration: 6:00 Let’s add a [toolbar](https://material.io/guidelines/components/toolbars.html) to better convey the branding and ensure the user always knows where they are. -It is easy to implement the toolbar using MDC-Web’s [mdc-toolbar](https://github.com/material-components/material-components-web/tree/master/packages/mdc-toolbar) component. Use a [fixed toolbar](https://github.com/material-components/material-components-web/tree/master/packages/mdc-toolbar#fixed-toolbars), because it has elevation and floats above the main content. +It is easy to implement the toolbar using MDC Web’s [mdc-toolbar](https://github.com/material-components/material-components-web/tree/master/packages/mdc-toolbar) component. Use a [fixed toolbar](https://github.com/material-components/material-components-web/tree/master/packages/mdc-toolbar#fixed-toolbars), because it has elevation and floats above the main content. ## Add the toolbar in index.html @@ -30,7 +30,7 @@ In `index.html`, replace the whole file with the following: - Shrine (MDC-Web Example App) + Shrine (MDC Web Example App) diff --git a/docs/codelabs/building-beautiful-sites/docsite/4-navigation.md b/docs/codelabs/building-beautiful-sites/docsite/4-navigation.md index 810a95c9906..5ebb05ab0f7 100644 --- a/docs/codelabs/building-beautiful-sites/docsite/4-navigation.md +++ b/docs/codelabs/building-beautiful-sites/docsite/4-navigation.md @@ -28,7 +28,7 @@ Replace the entire `index.html` file with this: - Shrine (MDC-Web Example App) + Shrine (MDC Web Example App) diff --git a/docs/codelabs/building-beautiful-sites/docsite/5-layout.md b/docs/codelabs/building-beautiful-sites/docsite/5-layout.md index 83c4da63b7f..220b693fd5d 100644 --- a/docs/codelabs/building-beautiful-sites/docsite/5-layout.md +++ b/docs/codelabs/building-beautiful-sites/docsite/5-layout.md @@ -28,7 +28,7 @@ Replace the entire `index.html` with this: - Shrine (MDC-Web Example App) + Shrine (MDC Web Example App) diff --git a/docs/codelabs/building-beautiful-sites/docsite/introduction.md b/docs/codelabs/building-beautiful-sites/docsite/introduction.md index b2b87b45927..169f9bb61bb 100644 --- a/docs/codelabs/building-beautiful-sites/docsite/introduction.md +++ b/docs/codelabs/building-beautiful-sites/docsite/introduction.md @@ -17,13 +17,13 @@ edited for a non-technical audience Developed by a core team of engineers and UX designers at Google, Material Components (MDC) helps developers execute Material Design. MDC has over 20 beautiful and functional UI components for the web platform and is also available for Android and iOS. -This codelab will show you some situations where Material Components for the web (MDC-Web) can make your app more functional and beautiful, while saving you engineering time. +This codelab will show you some situations where Material Components for the web (MDC Web) can make your app more functional and beautiful, while saving you engineering time. ## What you will build In this codelab, you're going to complete Shrine, an e-commerce app that sells clothing and home goods. Your app will: -- Use a fixed header bar - called a toolbar in MDC-Web - to display a title using [Material Design’s typography guidelines](https://material.io/guidelines/style/typography.html) and a navigation icon complete with a [Material Design ink ripple](https://material.io/guidelines/motion/material-motion.html#material-motion-how-does-material-move) effect. +- Use a fixed header bar - called a toolbar in MDC Web - to display a title using [Material Design’s typography guidelines](https://material.io/guidelines/style/typography.html) and a navigation icon complete with a [Material Design ink ripple](https://material.io/guidelines/motion/material-motion.html#material-motion-how-does-material-move) effect. - Contain a side [navigation drawer](https://material.io/guidelines/patterns/navigation-drawer.html) displaying a Material Design list of different product categories. - Display a list of product [cards](https://material.io/guidelines/components/cards.html#) using [layout grid](https://material.io/guidelines/layout/responsive-ui.html#responsive-ui-breakpoints) , providing a beautiful experience regardless of form factor. diff --git a/docs/codelabs/building-beautiful-sites/starter/index.html b/docs/codelabs/building-beautiful-sites/starter/index.html index 2568ab123d0..8e34d71f39c 100644 --- a/docs/codelabs/building-beautiful-sites/starter/index.html +++ b/docs/codelabs/building-beautiful-sites/starter/index.html @@ -3,7 +3,7 @@ - Shrine (MDC-Web Example App) + Shrine (MDC Web Example App) diff --git a/docs/contribute/bug_fix.md b/docs/contribute/bug_fix.md index 2025b3396b0..fa937b14f8c 100644 --- a/docs/contribute/bug_fix.md +++ b/docs/contribute/bug_fix.md @@ -20,4 +20,4 @@ fix(foo): Short description of fix Resolves #1234 ``` -This commit message is pulled into our CHANGELOG when we [release](../open_source/README.md) and is based on [Angular's Git commit guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit). +This commit message is pulled into our CHANGELOG when we [release](../open_source/README.md) and is based on [Angular's Git commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits). diff --git a/docs/contribute/feat.md b/docs/contribute/feat.md index 837dbaaa4d3..0f906eb2248 100644 --- a/docs/contribute/feat.md +++ b/docs/contribute/feat.md @@ -20,4 +20,4 @@ The final commit message for a feature to the `mdc-foo` package should look like feat(foo): Short description of feature ``` -This commit message is pulled into our CHANGELOG when we [release](../open_source/README.md) and is based on [Angular's Git commit guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit). +This commit message is pulled into our CHANGELOG when we [release](../open_source/README.md) and is based on [Angular's Git commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits). diff --git a/docs/docsite-index.md b/docs/docsite-index.md index c5d26a52df0..26f97ff772f 100644 --- a/docs/docsite-index.md +++ b/docs/docsite-index.md @@ -36,7 +36,7 @@ Get up and running with Material Components for web 2. {: .step-list-item } ### Include the stylesheet - Include the MDC-Web stylesheet in the head of your file + Include the MDC Web stylesheet in the head of your file ```html @@ -63,7 +63,7 @@ Get up and running with Material Components for web 4. {: .step-list-item } ### Add scripts and instantiate - Add the MDC-Web scripts and call MDC Auto Init. + Add the MDC Web scripts and call MDC Auto Init. ```html diff --git a/docs/getting-started.md b/docs/getting-started.md index 271527c6b4a..cfabfca9c27 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -7,18 +7,18 @@ path: /docs/getting-started/ # Getting Started -This guide will help you get started using MDC-Web on your own sites and within your own projects. +This guide will help you get started using MDC Web on your own sites and within your own projects. -> If you are interested in integrating MDC-Web into a framework, or building a component library for -your framework that wraps MDC-Web, check out our [framework integration guide](./integrating-into-frameworks.md). +> If you are interested in integrating MDC Web into a framework, or building a component library for +your framework that wraps MDC Web, check out our [framework integration guide](./integrating-into-frameworks.md). -## MDC-Web quick start: building a simple greeting app +## MDC Web quick start: building a simple greeting app The best way to learn any new technology is to get your hands dirty and build something with it, so that is what we will do here! You will be building a simple greeting page which lets you enter a name and greets you as such. As you go through this guide, we encourage you to code along with it. By the end, you will have -learned the fundamentals incorporating MDC-Web into simple sites, as well as worked with some of the +learned the fundamentals incorporating MDC Web into simple sites, as well as worked with some of the components we have to offer. ### Setting up the project @@ -48,7 +48,7 @@ will be available on your `$PATH`. ### Creating the skeleton index.html file Now that you have a directory set up, create a simple `index.html` file, and include -the assets needed for MDC-Web. Put the following within `index.html` in the `greeting-app` directory: +the assets needed for MDC Web. Put the following within `index.html` in the `greeting-app` directory: ```html @@ -81,22 +81,22 @@ refresh after every change you make! Let's take a look at a few aspects of the above HTML. * **No JavaScript necessary (yet)** - Because we aren't using any dynamic components, we only need - to include the MDC-Web CSS, so that we can apply the proper CSS classes to our elements. With MDC-Web, + to include the MDC Web CSS, so that we can apply the proper CSS classes to our elements. With MDC Web, JavaScript is only necessary for dynamic components whose UI needs to be made aware of events happening on the page. As we develop our greeting app, we'll add in the necessary JavaScript. -* **No automatic DOM rendering** - For all components, MDC-Web does not render _any_ DOM elements - itself. MDC-Web is similar to [Bootstrap](http://getbootstrap.com/) in this respect; it expects you to render the DOM using the proper CSS classes. This avoids a litany of problems for integrating MDC-Web into +* **No automatic DOM rendering** - For all components, MDC Web does not render _any_ DOM elements + itself. MDC Web is similar to [Bootstrap](http://getbootstrap.com/) in this respect; it expects you to render the DOM using the proper CSS classes. This avoids a litany of problems for integrating MDC Web into complex applications. * **Elements are not natively styled** - Notice how above, we give the `` element a class of `mdc-typography`, the `

    ` element a class of `mdc-typography--display1`, and the button a class - of `mdc-button`, along with multiple _modifier classes_. MDC-Web _never_ makes any assumptions about + of `mdc-button`, along with multiple _modifier classes_. MDC Web _never_ makes any assumptions about which elements are being used for our components, instead relying on CSS classes for maximum - flexibility. MDC-Web's CSS class names follow a slightly modified version of the [BEM](http://getbem.com/) system. + flexibility. MDC Web's CSS class names follow a slightly modified version of the [BEM](http://getbem.com/) system. ### Adding in JavaScript for dynamic components -Now that we've gotten the gist of MDC-Web, let us continue to build our greeting app. +Now that we've gotten the gist of MDC Web, let us continue to build our greeting app. The app consists of two input fields and a submit button. Material Design text input fields and buttons contain a lot of dynamism and animation that require the usage of JavaScript. @@ -152,14 +152,14 @@ fields along with a Material Design styled button. The button shows an ink rippl Two important points that are demonstrated in the code that was added: -#### MDC-Web does not instantiate any components automatically +#### MDC Web does not instantiate any components automatically -This avoids the headaches involved with lifecycle handlers management in Material Design Lite (the predecessor to MDC-Web). +This avoids the headaches involved with lifecycle handlers management in Material Design Lite (the predecessor to MDC Web). Initialization is done through the `data-mdc-auto-init` attributes added to those elements that are initialized when mdc.autoInit() is called. When `mdc.autoInit()` is called, it looks for all elements with a `data-mdc-auto-init` attribute, -and attaches the MDC-Web JS Component with the given class name to that element.. So when it sees `MDCTextField`, +and attaches the MDC Web JS Component with the given class name to that element.. So when it sees `MDCTextField`, it instantiates a [MDCTextField](../packages/mdc-textfield) instance to the corresponding elements. It does the same thing for the button, attaching a [MDCRipple](../packages/mdc-ripple) instance to the element. @@ -176,7 +176,7 @@ Even the `autoInit()` function [lives in its own package](../packages/mdc-auto-i `material-components-web` package uses to register all of the individual components to their names used within `data-mdc-auto-init`. Each component can be used as a standalone package, and can be mixed and matched at will. This allows for custom builds requiring the minimum possible amount of CSS/JS -code. It also means that MDC-Web works extremely well with module loading systems and modern +code. It also means that MDC Web works extremely well with module loading systems and modern front-end toolchains. ### Adding the business logic @@ -216,7 +216,7 @@ hit the button, and get a pleasant greeting :wave: You may have noticed that the button background, as well as the label and underline on focused text input fields, defaults to the Indigo 500 (`#673AB7`) color from the [Material Design color palette](https://material.io/guidelines/style/color.html#color-color-palette). -This is part of the default theme that ships with MDC-Web; it uses Indigo 500 for a primary color, and +This is part of the default theme that ships with MDC Web; it uses Indigo 500 for a primary color, and Pink A200 (`#FF4081`) for a secondary color. Let's change the theme's primary color. A common misconception when implementing Material Design is that the colors you use _must_ come from @@ -225,7 +225,7 @@ Design is that it has "bold hues juxtaposed with muted environments, deep shadow highlights". Let's change our theme's primary color to `#0E4EAD`, the "Afternoon_Skyblue" color from the [Deep_Skyblues Colourlovers Palette](http://www.colourlovers.com/palette/334208/Deep_Skyblues). -The easiest way to change the theme of an MDC-Web application is via [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables). Simply add the +The easiest way to change the theme of an MDC Web application is via [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables). Simply add the following to the `` tag of `index.html`: ```html @@ -239,7 +239,7 @@ following to the `` tag of `index.html`: If you're using any supported browser, besides IE 11, you'll see that the button background as well as the focused underline and label on text fields are now a nice, dark shade of blue. -> Note that using CSS Variables is just one way of theming using MDC-Web. Check out our +> Note that using CSS Variables is just one way of theming using MDC Web. Check out our [theming documentation](./theming.md) for more info. ### Finishing touches: adding custom styles @@ -249,7 +249,7 @@ anticipates every design choice a user may want. #### SASS mixins -MDC-Web provides SASS mixins to some components to help users do customization. Let's +MDC Web provides SASS mixins to some components to help users do customization. Let's change the background color of the raised button to be a bright orange color (#FF9800) using one of those mixins. @@ -264,7 +264,7 @@ Add the following to your `scss` file if you are using SASS: #### CSS -MDC-Web also uses plain old CSS to make it trivial to customize and modify its +MDC Web also uses plain old CSS to make it trivial to customize and modify its styles to your liking. Let's add some auxiliary styles to bump up the vertical spacing between the form fields and the submit button. @@ -276,14 +276,14 @@ Add the following to the `