add user documantation README

Author: annieyw

src/material-experimental/mdc-progress-spinner/README.md

@@ -0,0 +1,88 @@
+This is prototype of an alternate version of `<mat-progress-spinner>` built on top of
+[MDC Web](https://github.com/material-components/material-components-web). It demonstrates how
+Angular Material could use MDC Web under the hood while still exposing the same API Angular users as
+the existing `<mat-progress-spinner>`. This component is experimental and should not be used in
+production.
+
+## How to use
+Assuming your application is already up and running using Angular Material, you can add this
+component by following these steps:
+
+1. Install Angular Material Experimental & MDC WEB:
+
+   ```bash
+   npm i material-components-web @angular/material-experimental
+   ```
+
+2. In your `angular.json`, make sure `node_modules/` is listed as a Sass include path. This is
+   needed for the Sass compiler to be able to find the MDC Web Sass files.
+
+   ```json
+   ...
+   "styles": [
+     "src/styles.scss"
+   ],
+   "stylePreprocessorOptions": {
+     "includePaths": [
+       "node_modules/"
+     ]
+   },
+   ...
+   ```
+
+3. Import the experimental `MatProgressSpinnerModule` and add it to the module that declares your
+   component:
+
+   ```ts
+   import {MatProgressSpinnerModule} from '@angular/material-experimental/mdc-progress-spinner';
+
+   @NgModule({
+     declarations: [MyComponent],
+     imports: [MatProgressSpinnerModule],
+   })
+   export class MyModule {}
+   ```
+
+4. Add use `<mat-progress-spinner>` in your component's template, just like you would the normal
+   `<mat-progress-spinner>`:
+
+   ```html
+   <mat-progress-spinner [value]="42"></mat-progress-spinner>
+   ```
+
+5. Add the theme and typography mixins to your Sass. (There is currently no pre-built CSS option for
+   the experimental `<mat-progress-spinner>`):
+
+   ```scss
+   @import '~@angular/material/theming';
+   @import '~@angular/material-experimental/mdc-progress-spinner';
+
+   $my-primary: mat-palette($mat-indigo);
+   $my-accent:  mat-palette($mat-pink, A200, A100, A400);
+   $my-theme:   mat-light-theme((
+     color: (
+       primary: $my-primary, 
+       accent: $my-accent
+     )
+   ));
+
+   @include mat-mdc-progress-spinner-theme($my-theme);
+   @include mat-mdc-progress-spinner-typography();
+   ```
+
+## Replacing the standard progress spinner in an existing app
+Because the experimental API mirrors the API for the standard progress spinner, it can easily be swapped
+in by just changing the import paths. There is currently no schematic for this, but you can run the
+following string replace across your TypeScript files:
+
+```bash
+grep -lr --include="*.ts" --exclude-dir="node_modules" \
+  --exclude="*.d.ts" "['\"]@angular/material/progress-spinner['\"]" | xargs sed -i \
+  "s/['\"]@angular\/material\/progress-spinner['\"]/'@angular\/material-experimental\/mdc-progress-spinner'/g"
+```
+
+CSS styles and tests that depend on implementation details of mat-progress-spinner (such as getting
+elements from the template by class name) will need to be manually updated.
+
+There are some small visual differences between this progress and the standard `mat-progress-spinner`.
+This progress spinner has slightly different animation timings and easing curves.

src/material-experimental/mdc-progress-spinner/progress-spinner.html

@@ -20,6 +20,7 @@
             cx="50%" cy="50%"/>
   </svg>
 </div>
+<!--TODO: figure out why there are 3 separate svgs-->
 <div class="mdc-circular-progress__indeterminate-container">
   <div class="mdc-circular-progress__spinner-layer">
     <div class="mdc-circular-progress__circle-clipper mdc-circular-progress__circle-left">

src/material-experimental/mdc-progress-spinner/progress-spinner.ts

@@ -81,9 +81,6 @@ export class MatProgressSpinner extends _MatProgressSpinnerMixinBase implements
   /** Implements all of the logic of the MDC circular progress. */
   _foundation: MDCCircularProgressFoundation;
 
-  /** Root element of MDCCircularProgress. */
-  // @ViewChild('spinnerRoot') _elementRef: ElementRef<HTMLElement>;
-
   /** The element of the determinate spinner. */
   @ViewChild('determinateSpinner') _determinateCircle: ElementRef<HTMLElement>;