feat(text-field): Add properties for value, disable, value, and required (#1873)

BREAKING CHANGE:
- The return type for `MDCTextFieldAdapter.getNativeInput()` has changed. See the 'NativeInputType` typedef in the adapter.
- MDCTextFieldLabelFoundation has removed:
  - `floatAbove`
  - `deactivateFocus`
  - `setValidity`
- They are replaced with methods for updating the label float and label shake styles:
  - `styleFloat`
  - `styleShake`

Author: lynnmercier

packages/mdc-textfield/README.md

@@ -205,8 +205,10 @@ See [Importing the JS component](../../docs/importing-js.md) for more informatio
 
 Property | Value Type | Description
 --- | --- | ---
-`disable` | Boolean | Proxies to the foundation's `isDisabled`/`setDisabled` methods when retrieved/set respectively
-`valid` | Boolean | Proxies to the foundation's `setValid` method when set
+`value` | String | Proxies to the foundation's `getValue`/`setValue` methods.
+`disabled` | Boolean | Proxies to the foundation's `isDisabled`/`setDisabled` methods.
+`valid` | Boolean | Proxies to the foundation's `isValid`/`setValid` methods.
+`required` | Boolean | Proxies to the foundation's `isRequired`/`setRequired` methods.
 `helperTextContent` | String | Proxies to the foundation's `setHelperTextContent` method when set
 `ripple` | `MDCRipple` | The `MDCRipple` instance for the root element that `MDCTextField` initializes
 
@@ -248,9 +250,14 @@ Returns the idle outline element's computed style value of the given css propert
 
 Method Signature | Description
 --- | ---
+`getValue() => string` | Returns the input's value.
+`setValue(value: string)` | Sets the input's value.
+`isValid() => boolean` | If a custom validity is set, returns that value. Otherwise, returns the result of native validity checks.
+`setValid(isValid: boolean)` | Sets custom validity. Once set, native validity checking is ignored.
 `isDisabled() => boolean` | Returns whether or not the input is disabled
 `setDisabled(disabled: boolean) => void` | Updates the input's disabled state
-`setValid(isValid: boolean) => void` | Sets the validity state of the Text Field. Triggers custom validity checking
+`isRequired() => boolean` | Returns whether the input is required.
+`setRequired(isRequired: boolean)` | Sets whether the input is required.
 `handleTextFieldInteraction(evt: Event) => void` | Handles click and keydown events originating from inside the Text Field component
 `activateFocus() => void` | Activates the focus state of the Text Field. Normally called in response to the input focus event.
 `deactivateFocus() => void` | Deactivates the focus state of the Text Field. Normally called in response to the input blur event.

packages/mdc-textfield/adapter.js

@@ -28,7 +28,10 @@ import MDCTextFieldLabelFoundation from './label/foundation';
  *   value: string,
  *   disabled: boolean,
  *   badInput: boolean,
- *   checkValidity: (function(): boolean)
+ *   validity: {
+ *     badInput: boolean,
+ *     valid: boolean,
+ *   },
  * }}
  */
 let NativeInputType;

packages/mdc-textfield/foundation.js

@@ -95,6 +95,8 @@ class MDCTextFieldFoundation extends MDCFoundation {
     this.receivedUserInput_ = false;
     /** @private {boolean} */
     this.useCustomValidityChecking_ = false;
+    /** @private {boolean} */
+    this.isValid_ = true;
     /** @private {function(): undefined} */
     this.inputFocusHandler_ = () => this.activateFocus();
     /** @private {function(): undefined} */
@@ -112,8 +114,9 @@ class MDCTextFieldFoundation extends MDCFoundation {
   init() {
     this.adapter_.addClass(MDCTextFieldFoundation.cssClasses.UPGRADED);
     // Ensure label does not collide with any pre-filled value.
-    if (this.getNativeInput_().value && this.label_) {
-      this.label_.floatAbove();
+    if (this.label_ && this.getValue()) {
+      this.label_.styleFloat(
+        this.getValue(), this.isFocused_, this.isBadInput_());
     }
 
     if (this.adapter_.isFocused()) {
@@ -181,21 +184,22 @@ class MDCTextFieldFoundation extends MDCFoundation {
    * Activates the text field focus state.
    */
   activateFocus() {
-    const {FOCUSED} = MDCTextFieldFoundation.cssClasses;
-    this.adapter_.addClass(FOCUSED);
+    this.isFocused_ = true;
+    this.styleFocused_(this.isFocused_);
     if (this.bottomLine_) {
       this.bottomLine_.activate();
     }
     if (this.outline_) {
       this.updateOutline();
     }
     if (this.label_) {
-      this.label_.floatAbove();
+      this.label_.styleShake(this.isValid(), this.isFocused_);
+      this.label_.styleFloat(
+        this.getValue(), this.isFocused_, this.isBadInput_());
     }
     if (this.helperText_) {
       this.helperText_.showToScreenReader();
     }
-    this.isFocused_ = true;
   }
 
   /**
@@ -233,54 +237,67 @@ class MDCTextFieldFoundation extends MDCFoundation {
   }
 
   /**
-   * Deactives the Text Field's focus state.
+   * Deactivates the Text Field's focus state.
    */
   deactivateFocus() {
-    const {FOCUSED} = MDCTextFieldFoundation.cssClasses;
+    this.isFocused_ = false;
     const input = this.getNativeInput_();
     const shouldRemoveLabelFloat = !input.value && !this.isBadInput_();
-
-    this.isFocused_ = false;
-    this.adapter_.removeClass(FOCUSED);
+    const isValid = this.isValid();
+    this.styleValidity_(isValid);
+    this.styleFocused_(this.isFocused_);
     if (this.label_) {
-      this.label_.deactivateFocus(shouldRemoveLabelFloat);
+      this.label_.styleShake(this.isValid(), this.isFocused_);
+      this.label_.styleFloat(
+        this.getValue(), this.isFocused_, this.isBadInput_());
     }
     if (shouldRemoveLabelFloat) {
       this.receivedUserInput_ = false;
     }
+  }
 
-    if (!this.useCustomValidityChecking_) {
-      this.changeValidity_(input.checkValidity());
-    }
+  /**
+   * @return {string} The value of the input Element.
+   */
+  getValue() {
+    return this.getNativeInput_().value;
   }
 
   /**
-   * Updates the Text Field's valid state based on the supplied validity.
-   * @param {boolean} isValid
-   * @private
+   * @param {string} value The value to set on the input Element.
    */
-  changeValidity_(isValid) {
-    const {INVALID} = MDCTextFieldFoundation.cssClasses;
-    if (isValid) {
-      this.adapter_.removeClass(INVALID);
-    } else {
-      this.adapter_.addClass(INVALID);
-    }
-    if (this.helperText_) {
-      this.helperText_.setValidity(isValid);
-    }
+  setValue(value) {
+    this.getNativeInput_().value = value;
+    const isValid = this.isValid();
+    this.styleValidity_(isValid);
     if (this.label_) {
-      this.label_.setValidity(isValid);
+      this.label_.styleShake(isValid, this.isFocused_);
+      this.label_.styleFloat(
+        this.getValue(), this.isFocused_, this.isBadInput_());
     }
   }
 
   /**
-   * @return {boolean} True if the Text Field input fails validity checks.
-   * @private
+   * @return {boolean} If a custom validity is set, returns that value.
+   *     Otherwise, returns the result of native validity checks.
    */
-  isBadInput_() {
-    const input = this.getNativeInput_();
-    return input.validity ? input.validity.badInput : input.badInput;
+  isValid() {
+    return this.useCustomValidityChecking_
+      ? this.isValid_ : this.isNativeInputValid_();
+  }
+
+  /**
+   * @param {boolean} isValid Sets the validity state of the Text Field.
+   */
+  setValid(isValid) {
+    this.useCustomValidityChecking_ = true;
+    this.isValid_ = isValid;
+    // Retrieve from the getter to ensure correct logic is applied.
+    isValid = this.isValid();
+    this.styleValidity_(isValid);
+    if (this.label_) {
+      this.label_.styleShake(isValid, this.isFocused_);
+    }
   }
 
   /**
@@ -294,17 +311,25 @@ class MDCTextFieldFoundation extends MDCFoundation {
    * @param {boolean} disabled Sets the text-field disabled or enabled.
    */
   setDisabled(disabled) {
-    const {DISABLED, INVALID} = MDCTextFieldFoundation.cssClasses;
     this.getNativeInput_().disabled = disabled;
-    if (disabled) {
-      this.adapter_.addClass(DISABLED);
-      this.adapter_.removeClass(INVALID);
-    } else {
-      this.adapter_.removeClass(DISABLED);
-    }
-    if (this.icon_) {
-      this.icon_.setDisabled(disabled);
-    }
+    this.styleDisabled_(disabled);
+  }
+
+  /**
+   * @return {boolean} True if the Text Field is required.
+   */
+  isRequired() {
+    return this.getNativeInput_().required;
+  }
+
+  /**
+   * @param {boolean} isRequired Sets the text-field required or not.
+   */
+  setRequired(isRequired) {
+    this.getNativeInput_().required = isRequired;
+    // Addition of the asterisk is automatic based on CSS, but validity checking
+    // needs to be manually run.
+    this.styleValidity_(this.isValid());
   }
 
   /**
@@ -316,6 +341,72 @@ class MDCTextFieldFoundation extends MDCFoundation {
     }
   }
 
+  /**
+   * @return {boolean} True if the Text Field input fails in converting the
+   *     user-supplied value.
+   * @private
+   */
+  isBadInput_() {
+    return this.getNativeInput_().validity.badInput;
+  }
+
+  /**
+   * @return {boolean} The result of native validity checking
+   *     (ValidityState.valid).
+   */
+  isNativeInputValid_() {
+    return this.getNativeInput_().validity.valid;
+  }
+
+  /**
+   * Styles the component based on the validity state.
+   * @param {boolean} isValid
+   * @private
+   */
+  styleValidity_(isValid) {
+    const {INVALID} = MDCTextFieldFoundation.cssClasses;
+    if (isValid) {
+      this.adapter_.removeClass(INVALID);
+    } else {
+      this.adapter_.addClass(INVALID);
+    }
+    if (this.helperText_) {
+      this.helperText_.setValidity(isValid);
+    }
+  }
+
+  /**
+   * Styles the component based on the focused state.
+   * @param {boolean} isFocused
+   * @private
+   */
+  styleFocused_(isFocused) {
+    const {FOCUSED} = MDCTextFieldFoundation.cssClasses;
+    if (isFocused) {
+      this.adapter_.addClass(FOCUSED);
+    } else {
+      this.adapter_.removeClass(FOCUSED);
+    }
+  }
+
+  /**
+   * Styles the component based on the disabled state.
+   * @param {boolean} isDisabled
+   * @private
+   */
+  styleDisabled_(isDisabled) {
+    const {DISABLED, INVALID} = MDCTextFieldFoundation.cssClasses;
+    if (isDisabled) {
+      this.adapter_.addClass(DISABLED);
+      this.adapter_.removeClass(INVALID);
+    } else {
+      this.adapter_.removeClass(DISABLED);
+    }
+    if (this.icon_) {
+      this.icon_.setDisabled(isDisabled);
+    }
+  }
+
   /**
    * @return {!Element|!NativeInputType} The native text input from the
    * host environment, or a dummy if none exists.
@@ -324,20 +415,14 @@ class MDCTextFieldFoundation extends MDCFoundation {
   getNativeInput_() {
     return this.adapter_.getNativeInput() ||
     /** @type {!NativeInputType} */ ({
-      checkValidity: () => true,
       value: '',
       disabled: false,
-      badInput: false,
+      validity: {
+        badInput: false,
+        valid: true,
+      },
     });
   }
-
-  /**
-   * @param {boolean} isValid Sets the validity state of the Text Field.
-   */
-  setValid(isValid) {
-    this.useCustomValidityChecking_ = true;
-    this.changeValidity_(isValid);
-  }
 }
 
 export default MDCTextFieldFoundation;

packages/mdc-textfield/index.js

@@ -160,6 +160,20 @@ class MDCTextField extends MDCComponent {
     this.disabled = this.input_.disabled;
   }
 
+  /**
+   * @return {string} The value of the input.
+   */
+  get value() {
+    return this.foundation_.getValue();
+  }
+
+  /**
+   * @param {string} value The value to set on the input.
+   */
+  set value(value) {
+    this.foundation_.setValue(value);
+  }
+
   /**
    * @return {boolean} True if the Text Field is disabled.
    */
@@ -174,13 +188,34 @@ class MDCTextField extends MDCComponent {
     this.foundation_.setDisabled(disabled);
   }
 
+  /**
+   * @return {boolean} valid True if the Text Field is valid.
+   */
+  get valid() {
+    return this.foundation_.isValid();
+  }
+
   /**
    * @param {boolean} valid Sets the Text Field valid or invalid.
    */
   set valid(valid) {
     this.foundation_.setValid(valid);
   }
 
+  /**
+   * @return {boolean} True if the Text Field is required.
+   */
+  get required() {
+    return this.foundation_.isRequired();
+  }
+
+  /**
+   * @param {boolean} required Sets the Text Field to required.
+   */
+  set required(required) {
+    this.foundation_.setRequired(required);
+  }
+
   /**
    * Sets the helper text element content.
    * @param {string} content

packages/mdc-textfield/label/README.md

@@ -88,7 +88,6 @@ Method Signature | Description
 
 Method Signature | Description
 --- | ---
-`floatAbove() => void` | Makes the label float above the text field
-`deactivateFocus(shouldRemoveLabelFloat: boolean) => void` | Deactivates the label's focus state. `shouldRemoveLabelFloat` indicates whether to also reset the label's position and size.
-`setValidity(isValid: boolean)` | Updates the label's valid state based on the supplied validity
 `getWidth() => number` | Returns the width of the label element
+`styleShake(isValid: boolean, isFocused: boolean)` | Styles the label to produce the shake effect when needed.
+`styleFloat(value: string, isFocused: boolean, isBadInput: boolean)` | Styles the label to float or defloat as necessary.