address comments

Author: tinayuangao

src/lib/chips/chip-input.ts

@@ -34,26 +34,8 @@ export interface MdChipInputEvent {
 }
 
 /**
- * A material design chips input component working with chip list component.
- * To be placed inside <md-form-field>. Can be placed inside <md-chip-list> or outside
- * <md-chip-list>.
- *
- * Example:
- *     <md-form-field>
- *       <md-chip-list #chipList>
- *         <md-chip>Chip 1<md-chip>
- *         <md-chip>Chip 2<md-chip>
- *       </md-chip-list>
- *       <input mdChipInputFor="chipList">
- *     </md-form-field>
- *
- *     <md-form-field>
- *       <md-chip-list #chipList>
- *         <md-chip>Chip 1<md-chip>
- *         <md-chip>Chip 2<md-chip>
- *         <input mdChipInputFor="chipList">
- *       </md-chip-list>
- *     </md-form-field>
+ * Directive that adds chip-specific behaviors to an input element inside <md-form-field>.
+ * May be placed inside or outside of an <md-chip-list>.
  */
 @Directive({
   selector: 'input[mdChipInputFor], input[matChipInputFor]',

src/lib/chips/chip-list.ts

@@ -71,6 +71,7 @@ export class MdChipListChange {
     '[attr.aria-required]': 'required.toString()',
     '[attr.aria-disabled]': 'disabled.toString()',
     '[attr.aria-invalid]': 'errorState',
+    '[attr.aria-multiselectable]': 'true',
     '[class.mat-chip-list-disabled]': 'disabled',
     '[class.mat-chip-list-invalid]': 'errorState',
     '[class.mat-chip-list-required]': 'required',
@@ -164,6 +165,7 @@ export class MdChipList implements MdFormFieldControl<any>, ControlValueAccessor
   /** Comparison function to specify which option is displayed. Defaults to object equality. */
   private _compareWith = (o1: any, o2: any) => o1 === o2;
 
+  /** The array of selected chips inside chip list. */
   get selected(): MdChip[] {
     return this._selectionModel.selected;
   }
@@ -219,22 +221,23 @@ export class MdChipList implements MdFormFieldControl<any>, ControlValueAccessor
     return this._chipInput ? this._chipInput.placeholder : this._placeholder;
   }
 
-  /** For FormFieldControl. If any of the chips has focus, or the chip input has focus */
+  /** Whether any chips or the mdChipInput inside of this chip-list has focus. */
   get focused() {
     return this.chips.some(chip => chip._hasFocus) ||
       (this._chipInput && this._chipInput.focused);
   }
 
-  /** For FormFieldControl. The chip list is empty if there's no chip and there's no input */
+  /** Whether this chip-list contains no chips and no mdChipInput. */
   get empty(): boolean {
     return (!this._chipInput || this._chipInput.empty) && this.chips.length === 0;
   }
 
-  /** For FormFieldControl. The disabled is not depend on chip input */
+  /** Whether this chip-list is disabled. */
   @Input()
   get disabled() { return this.ngControl ? this.ngControl.disabled : this._disabled; }
   set disabled(value: any) { this._disabled = coerceBooleanProperty(value); }
 
+  /** Whether the chip list is in an error state. */
   get errorState(): boolean {
     const isInvalid = this.ngControl && this.ngControl.invalid;
     const isTouched = this.ngControl && this.ngControl.touched;
@@ -584,22 +587,28 @@ export class MdChipList implements MdFormFieldControl<any>, ControlValueAccessor
     this._changeDetectorRef.markForCheck();
   }
 
+  /** When blurred, mark the field as touched when focus moved outside the chip list. */
   _blur() {
     if (!this.disabled) {
       if (this._chipInput) {
-        // Check if focus moved to chip input. If not, do real on blur
+        // If there's a chip input, we should check whether the focus moved to chip input.
+        // If the focus is not moved to chip input, mark the field as touched. If the focus moved
+        // to chip input, do nothing.
+        // Timeout is needed to wait for the focus() event trigger on chip input.
         setTimeout(() => {
           if (!this.focused) {
-            this._onBlur();
+            this._markAsTouched();
           }
         });
       } else {
-        this._onBlur();
+        // If there's no chip input, then mark the field as touched.
+        this._markAsTouched();
       }
     }
   }
 
-  _onBlur() {
+  /** Mark the field as touched */
+  _markAsTouched() {
     this._onTouched();
     this._changeDetectorRef.markForCheck();
     this.stateChanges.next();

src/lib/chips/chips.md

@@ -22,13 +22,38 @@ _Hint: `<md-basic-chip>` receives the `mat-basic-chip` CSS class in addition to
 Chips can be selected via the `selected` property. Selection can be disabled by setting
 `selectable` to `false` on the `<md-chip-list>`.
 
-Selection emits the `(select)` output while deselecting emits the `(deselect)` output. Both outputs
-receive a ChipEvent object with a structure of `{ chip: alteredChip }`.
+Selection and deselecting emit the `(onSelectionChange)` output. The output receive a
+ChipSelectionChange object with a structure of `{ source: alteredChip, isUserInput: boolean }`.
 
 ### Disabled chips
 Individual chips may be disabled by applying the `disabled` attribute to the chip. When disabled,
 chips are neither selectable nor focusable. Currently, disabled chips receive no special styling.
 
+### Chip input
+Chip input can work with chip list to add new chips to the chip list. It implements chip-specified
+behaviors to an input element inside `<md-form-field>`. Chip input may be placed inside or outside of
+an `<md-chip-list>`.
+
+```html
+<md-form-field>
+  <md-chip-list #chipList>
+    <md-chip>Chip 1<md-chip>
+   <md-chip>Chip 2<md-chip>
+ </md-chip-list>
+ <input mdChipInputFor="chipList">
+</md-form-field>
+```
+
+```html
+<md-form-field>
+ <md-chip-list #chipList>
+   <md-chip>Chip 1<md-chip>
+   <md-chip>Chip 2<md-chip>
+   <input mdChipInputFor="chipList">
+ </md-chip-list>
+</md-form-field>
+```
+
 ### Keyboard interaction
 Users can move through the chips using the arrow keys and select/deselect them with the space. Chips
 also gain focus when clicked, ensuring keyboard navigation starts at the appropriate chip.