fix(theme, colors): md-colors demo was broken. improve JSDoc and fix lint issues

Splaktar · Splaktar · commit 01917b37ec6a · 2020-06-30T20:14:39.000-04:00
- fix lint warning of unnecessary escape in regex and missing colon
- resolve test failures after merge
- `md-colors` demos general cleanup and fix URLs and icons
- clarify how to map the old foreground expressions in theming docs
- update links to opacity requirements for icons
- clean up Theming implementation guide
diff --git a/docs/guides/THEMES_IMPL_NOTES.md b/docs/guides/THEMES_IMPL_NOTES.md
@@ -1,35 +1,36 @@
-# Notes on ng-material's theme implementation
+# Notes on AngularJS Material's theme implementation
 
 #### TL;DR
-Themes are configured by users with `$mdThemingProvider`. The CSS is then generated at run-time by
-the `$mdTheming` service and tacked into the document head.
+You configure themes with `$mdThemingProvider`. The CSS is then generated at run-time by
+the `$mdTheming` service and appended to the document's `<head>`.
 
-## Actual explanation
+## Explanation
 
 ### At build time
-* All of the styles associated with **color** are defined in a separate scss file of the form
+* All the styles associated with **color** are defined in a separate SCSS file of the form
 `xxx-theme.scss`.
-* Instead of using hard-coded color or a SCSS variable, the colors are defined with a mini-DSL
-(described deblow).
-* The build process takes all of those `-theme.scss` files and globs them up into one enourmous
+* Instead of using a hard-coded color or a SCSS variable, you define the colors with a mini-DSL
+  (described below).
+* The build process takes all of those `-theme.scss` files and globs them up into one enormous
 string.
-* The build process wraps that string with code to set it an angular module constant:
-    ``` angular.module('material.core').constant('$MD_THEME_CSS', 'HUGE_THEME_STRING'); ```
-* That code gets dumped at the end of `angular-material.js`
+* The build process wraps that string with code to set it as an AngularJS module constant:
+  ```
+    angular.module('material.core').constant('$MD_THEME_CSS', 'HUGE_THEME_STRING');
+  ```
+* That code gets dumped at the end of `angular-material.js`.
 
 ### At run time
 * The user defines some themes with `$mdThemingProvider` during the module config phase.
 * At module run time, the theming service takes `$MD_THEME_CSS` and, for each theme, evaluates the
 mini-DSL, applies the colors for the theme, and appends the resulting CSS into the document head.
 
-
 ### The mini-DSL
-* Each color is written in the form `'{{palette-hue-contrast-opacity}}'`, where `hue`, `contrast`,
+* You write each color in the form `'{{palette-hue-contrast-opacity}}'`, where `hue`, `contrast`,
 and opacity are optional.
-* For example, `'{{primary-500}}'`
-* Palettes are `primary`, `accent`, `warn`, `background`
+* For example, `'{{primary-500}}'`.
+* Palettes are `primary`, `accent`, `warn`, `background`.
 * The hues for each type use the Material Design hues. When not specified, each palette defaults
-`hue` to `500` with the exception of `background`
+`hue` to `500` except for `background`.
 * The `opacity` value can be a decimal between 0 and 1 or one of the following values based on the
 hue's contrast type (dark, light, or strongLight):
   * `icon`: icon (0.54 / 0.87 / 1.0)
@@ -41,4 +42,4 @@ hue's contrast type (dark, light, or strongLight):
 For example, `accent-contrast` will be a contrast color for the accent color, for use as a text
 color on an accent-colored background. Adding an `opacity` value as in `accent-contrast-icon` will
 apply the Material Design icon opacity. Using a decimal opacity value as in `accent-contrast-0.25`
-will apply the contrast color for the accent color at 25% opacity.
+will apply the contrast color for the accent color at 25% opacity.
diff --git a/src/components/colors/demoBasicUsage/index.html b/src/components/colors/demoBasicUsage/index.html
@@ -1,25 +1,25 @@
 <div layout="column" ng-cloak class="md-padding">
   <p style="margin-bottom: 10px;">
-    Custom component implementations using Material elements often want to easily apply Theme colors
+    Custom component implementations using Material elements often want to easily apply theme colors
     to their custom components. Consider the custom <code>&lt;user-card&gt;</code> component below
     where the <code>md-colors</code> attribute is used to color the background and text colors
-    using either the current or specified Theme palette colors.
+    using either the current or specified theme palette colors.
   </p>
   <!-- Example 1 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> without md-color features</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> without md-color features</h4>
   <regular-card name="User name" md-theme="default"></regular-card>
   <!-- Example 2 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'default' Theme</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'default' theme</h4>
   <user-card name="User name"></user-card>
   <!-- Example 3 -->
-  <span class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'forest' Theme</span>
+  <h4 class="card-title"> <code>&lt;user-card&gt;</code> coloring using the 'forest' theme</h4>
   <user-card name="User name" theme="forest"></user-card>
   <!-- Footnote -->
   <p class="footnote">
-    Note: The <code>md-colors</code> directive allows pre-defined theme colors to be easily applied
-    as CSS style properties. <code>md-colors</code> uses the Palettes defined at
-    <a class="md-accent" href="https://material.io/archive/guidelines/style/color.html#">Material Design Colors</a>
-    and the Themes defined using <code>$mdThemingProvider</code>. This feature is simply an
-    extension of the <code>$mdTheming</code> features.
+    Note: The <code>md-colors</code> directive allows pre-defined theme colors to be applied
+    as CSS style properties. <code>md-colors</code> uses the palettes defined in the
+    <a class="md-accent" href="https://material.io/archive/guidelines/style/color.html#color-color-palette">
+      Material Design Colors</a> and the themes defined using <code>$mdThemingProvider</code>.
+    This directive is an extension of the <code>$mdTheming</code> features.
   </p>
 </div>
diff --git a/src/components/colors/demoBasicUsage/regularCard.tmpl.html b/src/components/colors/demoBasicUsage/regularCard.tmpl.html
@@ -2,7 +2,7 @@
   <md-card-title>
     <md-card-title-media>
       <div class="md-media-sm card-media" layout>
-        <md-icon md-svg-icon="person" style="color:grey"></md-icon>
+        <md-icon md-svg-icon="social:person" style="color: grey"></md-icon>
       </div>
     </md-card-title-media>
     <md-card-title-text>
diff --git a/src/components/colors/demoBasicUsage/script.js b/src/components/colors/demoBasicUsage/script.js
@@ -5,7 +5,7 @@ angular.module('colorsDemo', ['ngMaterial'])
       .accentPalette('green');
 
     $mdIconProvider
-      .defaultIconSet('img/icons/sets/social-icons.svg', 24);
+      .iconSet('social', 'img/icons/sets/social-icons.svg', 24);
   })
   .directive('regularCard', function () {
     return {
diff --git a/src/components/colors/demoBasicUsage/style.css b/src/components/colors/demoBasicUsage/style.css
@@ -14,22 +14,21 @@
   color: rgba(255, 255, 255, 0.87);
 }
 
-span.card-title {
-  padding-left: 15px;
-  margin-top: 20px;
+h4.card-title {
+  margin: 24px 8px 0;
 }
 
 code.css {
   background-color: #fffcc2;
 }
 
 p.footnote code {
-  font-size:0.85em;
+  font-size: 0.85em;
 }
 
 p.footnote {
-  font-size:0.85em;
-  margin: 30px;
-  padding:5px;
-  background-color: rgba(205,205,205,0.45);
+  font-size: 0.85em;
+  margin: 30px 8px;
+  padding: 16px;
+  background-color: rgba(205, 205, 205, 0.45);
 }
diff --git a/src/components/colors/demoBasicUsage/userCard.tmpl.html b/src/components/colors/demoBasicUsage/userCard.tmpl.html
@@ -2,7 +2,7 @@
   <md-card-title>
     <md-card-title-media>
       <div class="md-media-sm card-media" layout md-colors="::{background: '{{theme}}-accent'}">
-        <md-icon md-svg-icon="person"></md-icon>
+        <md-icon md-svg-icon="social:person"></md-icon>
       </div>
     </md-card-title-media>
     <md-card-title-text>
diff --git a/src/components/colors/demoThemePicker/index.html b/src/components/colors/demoThemePicker/index.html
@@ -1,6 +1,6 @@
 <div layout="column" ng-cloak ng-controller="ThemeDemoCtrl" class="md-padding">
   <p>
-    Select a color from the <a class="md-accent" href="{{mdURL}}">Theme Color Palettes</a>
+    Select two of the <a class="md-accent" href="{{mdURL}}">Material Palettes</a>
     below:
   </p>
   <!-- Theme Options -->
@@ -26,8 +26,8 @@
   <!-- Footnote -->
   <p class="footnote">
     Notice that the foreground colors are automatically determined (from the theme configurations)
-    based on the specified background palette selection. Of course, you could easily override the
-    foreground color also...
+    based on the specified background palette selection. You can also override the foreground color,
+    if desired.
   </p>
 
 </div>
diff --git a/src/components/colors/demoThemePicker/script.js b/src/components/colors/demoThemePicker/script.js
@@ -3,7 +3,7 @@ angular
   .controller('ThemeDemoCtrl', function ($scope, $mdColorPalette) {
     $scope.colors = Object.keys($mdColorPalette);
 
-    $scope.mdURL = 'https://material.google.com/style/color.html#color-color-palette';
+    $scope.mdURL = 'https://material.io/archive/guidelines/style/color.html#color-color-palette';
     $scope.primary = 'purple';
     $scope.accent = 'green';
 
diff --git a/src/components/colors/demoThemePicker/style.css b/src/components/colors/demoThemePicker/style.css
@@ -18,10 +18,10 @@
 }
 
 p.footnote {
-  font-size:0.85em;
-  margin: 30px;
-  padding:5px;
-  background-color: rgba(205,205,205,0.45);
+  font-size: 0.85em;
+  margin: 30px 8px;
+  padding: 16px;
+  background-color: rgba(205, 205, 205, 0.45);
 }
 
 .componentTag {
diff --git a/src/core/services/theming/theming.js b/src/core/services/theming/theming.js
diff --git a/src/core/services/theming/theming.spec.js b/src/core/services/theming/theming.spec.js

Original file line number	Diff line number	Diff line change
`@@ -14,22 +14,21 @@`
`14`	`14`	`color: rgba(255, 255, 255, 0.87);`
`15`	`15`	`}`
`16`	`16`
`17`		`-span.card-title {`
`18`		`- padding-left: 15px;`
`19`		`- margin-top: 20px;`
	`17`	`+h4.card-title {`
	`18`	`+ margin: 24px 8px 0;`
`20`	`19`	`}`
`21`	`20`
`22`	`21`	`code.css {`
`23`	`22`	`background-color: #fffcc2;`
`24`	`23`	`}`
`25`	`24`
`26`	`25`	`p.footnote code {`
`27`		`- font-size:0.85em;`
	`26`	`+ font-size: 0.85em;`
`28`	`27`	`}`
`29`	`28`
`30`	`29`	`p.footnote {`
`31`		`- font-size:0.85em;`
`32`		`- margin: 30px;`
`33`		`- padding:5px;`
`34`		`- background-color: rgba(205,205,205,0.45);`
	`30`	`+ font-size: 0.85em;`
	`31`	`+ margin: 30px 8px;`
	`32`	`+ padding: 16px;`
	`33`	`+ background-color: rgba(205, 205, 205, 0.45);`
`35`	`34`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,10 +18,10 @@`
`18`	`18`	`}`
`19`	`19`
`20`	`20`	`p.footnote {`
`21`		`- font-size:0.85em;`
`22`		`- margin: 30px;`
`23`		`- padding:5px;`
`24`		`- background-color: rgba(205,205,205,0.45);`
	`21`	`+ font-size: 0.85em;`
	`22`	`+ margin: 30px 8px;`
	`23`	`+ padding: 16px;`
	`24`	`+ background-color: rgba(205, 205, 205, 0.45);`
`25`	`25`	`}`
`26`	`26`
`27`	`27`	`.componentTag {`