@material/web 0.1.0-alpha.0 → 0.1.0-alpha.1

package/textfield/lib/text-field.js

@@ -6,16 +6,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { __decorate, __metadata } from "tslib";
-import { redispatchEvent } from '@material/web/controller/events.js';
-import { FormController, getFormValue } from '@material/web/controller/form-controller.js';
-import { stringConverter } from '@material/web/controller/string-converter.js';
-import { ariaProperty } from '@material/web/decorators/aria-property.js';
 import { html, LitElement } from 'lit';
 import { property, query, queryAssignedElements, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
+import { styleMap } from 'lit/directives/style-map.js';
 import { html as staticHtml } from 'lit/static-html.js';
+import { redispatchEvent } from '../../controller/events.js';
+import { FormController, getFormValue } from '../../controller/form-controller.js';
+import { stringConverter } from '../../controller/string-converter.js';
+import { ariaProperty } from '../../decorators/aria-property.js';
 /** @soyCompatible */
 export class TextField extends LitElement {
     constructor() {
@@ -73,9 +74,10 @@ export class TextField extends LitElement {
          */
         this.supportingText = '';
         /**
-         * The ID on the supporting text element, used for SSR.
+         * Override the input text CSS `direction`. Useful for RTL languages that use
+         * LTR notation for fractions.
          */
-        this.supportingTextId = 'support';
+        this.textDirection = '';
         // ARIA
         // TODO(b/210730484): replace with @soyParam annotation
         this.ariaAutoComplete = null;
@@ -119,7 +121,13 @@ export class TextField extends LitElement {
          */
         this.pattern = '';
         this.placeholder = '';
-        this.readonly = false;
+        /**
+         * Indicates whether or not a user should be able to edit the text field's
+         * value.
+         *
+         * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#readonly
+         */
+        this.readOnly = false;
         /**
          * Returns or sets the element's step attribute, which works with min and max
          * to limit the increments at which a numeric or date-time value can be set.
@@ -135,8 +143,41 @@ export class TextField extends LitElement {
          */
         this.dirty = false;
         this.focused = false;
+        /**
+         * When set to true, the error text's `role="alert"` will be removed, then
+         * re-added after an animation frame. This will re-announce an error message
+         * to screen readers.
+         */
+        this.refreshErrorAlert = false;
+        /**
+         * Returns true when the text field's `value` property has been changed from
+         * it's initial value.
+         *
+         * Setting `value` should always overwrite `defaultValue`, even when `value`
+         * is an empty string. This flag ensures that behavior.
+         */
+        this.valueHasChanged = false;
+        /**
+         * Whether or not to ignore the next `value` change when computing
+         * `valueHasChanged`.
+         */
+        this.ignoreNextValueChange = false;
+        /**
+         * Whether or not a native error has been reported via `reportValidity()`.
+         */
+        this.nativeError = false;
+        /**
+         * The validation message displayed from a native error via
+         * `reportValidity()`.
+         */
+        this.nativeErrorText = '';
+        /** @soyUniqueAttribute */
+        this.counterId = 'counter';
+        /** @soyUniqueAttribute */
+        this.supportingTextId = 'support';
         this.addController(new FormController(this));
-        this.addEventListener('click', this.focus);
+        // TODO(b/244574653): replace this.handleClick with this.focus
+        this.addEventListener('click', this.handleClick);
         this.addEventListener('focusin', this.handleFocusin);
         this.addEventListener('focusout', this.handleFocusout);
     }
@@ -235,6 +276,9 @@ export class TextField extends LitElement {
         const { valid } = this.checkValidityAndDispatch();
         return valid;
     }
+    /**
+     * Focuses the text field's input text.
+     */
     focus() {
         if (this.disabled || this.matches(':focus-within')) {
             // Don't shift focus from an element within the text field, like an icon
@@ -245,18 +289,26 @@ export class TextField extends LitElement {
         // delegating focus
         this.getInput().focus();
     }
+    /**
+     * Unfocuses the text field.
+     */
+    blur() {
+        this.getInput().blur();
+    }
     /**
      * Checks the text field's native validation and returns whether or not the
      * element is valid.
      *
      * If invalid, this method will dispatch the `invalid` event.
      *
-     * This method will update `error` to the current validity state and
-     * `errorText` to the current `validationMessage`, unless the invalid event is
-     * canceled.
+     * This method will display or clear an error text message equal to the text
+     * field's `validationMessage`, unless the invalid event is canceled.
      *
      * Use `setCustomValidity()` to customize the `validationMessage`.
      *
+     * This method can also be used to re-announce error messages to screen
+     * readers.
+     *
      * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity
      *
      * @return true if the text field is valid, or false if not.
@@ -264,8 +316,13 @@ export class TextField extends LitElement {
     reportValidity() {
         const { valid, canceled } = this.checkValidityAndDispatch();
         if (!canceled) {
-            this.error = !valid;
-            this.errorText = this.validationMessage;
+            const prevMessage = this.getErrorText();
+            this.nativeError = !valid;
+            this.nativeErrorText = this.validationMessage;
+            const needsRefresh = this.shouldErrorAnnounce() && prevMessage === this.getErrorText();
+            if (needsRefresh) {
+                this.refreshErrorAlert = true;
+            }
         }
         return valid;
     }
@@ -340,43 +397,53 @@ export class TextField extends LitElement {
      */
     reset() {
         this.dirty = false;
+        this.valueHasChanged = false;
+        this.ignoreNextValueChange = true;
         this.value = this.defaultValue;
+        this.nativeError = false;
+        this.nativeErrorText = '';
     }
     /** @soyTemplate */
     render() {
         return html `
-      <span class="md3-text-field ${classMap(this.getRenderClasses())}">
-        ${this.renderField()}
-      </span>
-    `;
+       <span class="md3-text-field ${classMap(this.getRenderClasses())}">
+         ${this.renderField()}
+       </span>
+     `;
     }
     /** @soyTemplate */
     getRenderClasses() {
         return {
             'md3-text-field--disabled': this.disabled,
-            'md3-text-field--error': this.error,
+            'md3-text-field--error': this.getError(),
         };
     }
     /** @soyTemplate */
+    getError() {
+        return this.error || this.nativeError;
+    }
+    /** @soyTemplate */
     renderField() {
         const prefix = this.renderPrefix();
         const suffix = this.renderSuffix();
         const input = this.renderInput();
+        const inputValue = this.getInputValue();
         return staticHtml `<${this.fieldTag}
       class="md3-text-field__field"
       ?disabled=${this.disabled}
-      ?error=${this.error}
+      ?error=${this.getError()}
       ?focused=${this.focused}
       ?hasEnd=${this.hasTrailingIcon}
       ?hasStart=${this.hasLeadingIcon}
       .label=${this.label}
-      ?populated=${!!this.value}
+      ?populated=${!!inputValue}
       ?required=${this.required}
     >
       ${this.renderLeadingIcon()}
       ${prefix}${input}${suffix}
       ${this.renderTrailingIcon()}
       ${this.renderSupportingText()}
+      ${this.renderCounter()}
     </${this.fieldTag}>`;
     }
     /**
@@ -385,11 +452,11 @@ export class TextField extends LitElement {
      */
     renderLeadingIcon() {
         return html `
-      <span class="md3-text-field__icon md3-text-field__icon--leading" 
-          slot="start">
-        <slot name="leadingicon" @slotchange=${this.handleIconChange}></slot>
-      </span>
-    `;
+       <span class="md3-text-field__icon md3-text-field__icon--leading"
+           slot="start">
+         <slot name="leadingicon" @slotchange=${this.handleIconChange}></slot>
+       </span>
+     `;
     }
     /**
      * @soyTemplate
@@ -397,11 +464,11 @@ export class TextField extends LitElement {
      */
     renderTrailingIcon() {
         return html `
-      <span class="md3-text-field__icon md3-text-field__icon--trailing" 
-          slot="end">
-        <slot name="trailingicon" @slotchange=${this.handleIconChange}></slot>
-      </span>
-    `;
+       <span class="md3-text-field__icon md3-text-field__icon--trailing"
+           slot="end">
+         <slot name="trailingicon" @slotchange=${this.handleIconChange}></slot>
+       </span>
+     `;
     }
     /** @soyTemplate */
     renderInput() {
@@ -410,7 +477,7 @@ export class TextField extends LitElement {
         const ariaActiveDescendantValue = this.ariaActiveDescendant || undefined;
         const ariaAutoCompleteValue = this.ariaAutoComplete || undefined;
         const ariaControlsValue = this.ariaControls || undefined;
-        const ariaDescribedByValue = this.getSupportingText() ? this.supportingTextId : undefined;
+        const ariaDescribedByValue = this.getAriaDescribedBy() || undefined;
         const ariaExpandedValue = this.ariaExpanded || undefined;
         const ariaLabelValue = this.ariaLabel || this.label || undefined;
         const ariaLabelledByValue = this.ariaLabelledBy || undefined;
@@ -421,35 +488,52 @@ export class TextField extends LitElement {
         const patternValue = this.pattern || undefined;
         const roleValue = this.role || undefined;
         const stepValue = this.step || undefined;
+        /** @styleMap */
+        const style = { direction: this.textDirection };
         // TODO(b/243805848): remove `as unknown as number` once lit analyzer is
         // fixed
         return html `<input
-      class="md3-text-field__input"
-      aria-activedescendant=${ifDefined(ariaActiveDescendantValue)}
-      aria-autocomplete=${ifDefined(ariaAutoCompleteValue)}
-      aria-controls=${ifDefined(ariaControlsValue)}
-      aria-describedby=${ifDefined(ariaDescribedByValue)}
-      aria-expanded=${ifDefined(ariaExpandedValue)}
-      aria-invalid=${this.error}
-      aria-label=${ifDefined(ariaLabelValue)}
-      aria-labelledby=${ifDefined(ariaLabelledByValue)}
-      ?disabled=${this.disabled}
-      max=${ifDefined(maxValue)}
-      maxlength=${ifDefined(maxLengthValue)}
-      min=${ifDefined(minValue)}
-      minlength=${ifDefined(minLengthValue)}
-      pattern=${ifDefined(patternValue)}
-      placeholder=${ifDefined(placeholderValue)}
-      role=${ifDefined(roleValue)}
-      ?readonly=${this.readonly}
-      ?required=${this.required}
-      step=${ifDefined(stepValue)}
-      type=${this.type}
-      .value=${live(this.value)}
-      @change=${this.redispatchEvent}
-      @input=${this.handleInput}
-      @select=${this.redispatchEvent}
-    >`;
+       class="md3-text-field__input"
+       style=${styleMap(style)}
+       aria-activedescendant=${ifDefined(ariaActiveDescendantValue)}
+       aria-autocomplete=${ifDefined(ariaAutoCompleteValue)}
+       aria-controls=${ifDefined(ariaControlsValue)}
+       aria-describedby=${ifDefined(ariaDescribedByValue)}
+       aria-expanded=${ifDefined(ariaExpandedValue)}
+       aria-invalid=${this.getError()}
+       aria-label=${ifDefined(ariaLabelValue)}
+       aria-labelledby=${ifDefined(ariaLabelledByValue)}
+       ?disabled=${this.disabled}
+       max=${ifDefined(maxValue)}
+       maxlength=${ifDefined(maxLengthValue)}
+       min=${ifDefined(minValue)}
+       minlength=${ifDefined(minLengthValue)}
+       pattern=${ifDefined(patternValue)}
+       placeholder=${ifDefined(placeholderValue)}
+       role=${ifDefined(roleValue)}
+       ?readonly=${this.readOnly}
+       ?required=${this.required}
+       step=${ifDefined(stepValue)}
+       type=${this.type}
+       .value=${live(this.getInputValue())}
+       @change=${this.redispatchEvent}
+       @input=${this.handleInput}
+       @select=${this.redispatchEvent}
+     >`;
+    }
+    /** @soyTemplate */
+    getInputValue() {
+        const alwaysShowValue = this.dirty || this.valueHasChanged;
+        return alwaysShowValue ? this.value : this.defaultValue || this.value;
+    }
+    /** @soyTemplate */
+    getAriaDescribedBy() {
+        const hasSupport = !!this.getSupportingText();
+        const hasCounter = this.hasCounter();
+        // TODO(b/244609052): remove parens
+        return (hasSupport || hasCounter) ?
+            `${hasSupport ? this.supportingTextId : ''} ${hasCounter ? this.counterId : ''}` :
+            '';
     }
     /** @soyTemplate */
     renderPrefix() {
@@ -472,37 +556,95 @@ export class TextField extends LitElement {
      * @slotName supporting-text
      */
     renderSupportingText() {
+        const shouldAlert = this.shouldErrorAnnounce();
         const text = this.getSupportingText();
-        return text ?
-            html `<span id=${this.supportingTextId} slot="supporting-text">${text}</span>` :
-            html ``;
+        const template = html `<span id=${this.supportingTextId} 
+      slot="supporting-text" 
+      role=${ifDefined(shouldAlert ? 'alert' : undefined)}>${text}</span>`;
+        return text ? template : html ``;
     }
     /** @soyTemplate */
     getSupportingText() {
-        return this.error && this.errorText ? this.errorText : this.supportingText;
+        const errorText = this.getErrorText();
+        return this.getError() && errorText ? errorText : this.supportingText;
+    }
+    /** @soyTemplate */
+    getErrorText() {
+        return this.error ? this.errorText : this.nativeErrorText;
+    }
+    /** @soyTemplate */
+    shouldErrorAnnounce() {
+        // Announce if there is an error and error text visible.
+        // If refreshErrorAlert is true, do not announce. This will remove the
+        // role="alert" attribute. Another render cycle will happen after an
+        // animation frame to re-add the role.
+        return this.getError() && !!this.getErrorText() && !this.refreshErrorAlert;
     }
-    willUpdate(changedProperties) {
-        if (!changedProperties.has('value') && !this.dirty) {
-            // Do this here instead of in a setter so that the order of setting both
-            // value and defaultValue does not matter.
-            this.value = this.value || this.defaultValue;
+    /**
+     * @soyTemplate
+     * @slotName supporting-text-end
+     */
+    renderCounter() {
+        const counter = html `<span id=${this.counterId}
+       class="md3-text-field__counter"
+       slot="supporting-text-end">${this.getCounterText()}</span>`;
+        // TODO(b/244473435): add aria-label and announcements
+        return this.hasCounter() ? counter : html ``;
+    }
+    // TODO(b/244197198): replace with !!this.getCounterText()
+    /** @soyTemplate */
+    hasCounter() {
+        return this.maxLength > -1;
+    }
+    /** @soyTemplate */
+    getCounterText() {
+        // TODO(b/244197198): replace with string return
+        const length = this.value.length;
+        return this.hasCounter() ? html `${length} / ${this.maxLength}` : html ``;
+    }
+    update(changedProperties) {
+        // Consider a value change anything that is not the initial empty string
+        // value.
+        const valueHasChanged = changedProperties.has('value') &&
+            changedProperties.get('value') !== undefined;
+        if (valueHasChanged && !this.ignoreNextValueChange) {
+            this.valueHasChanged = true;
+        }
+        if (this.ignoreNextValueChange) {
+            this.ignoreNextValueChange = false;
         }
-        super.willUpdate(changedProperties);
+        super.update(changedProperties);
     }
-    updated() {
+    updated(changedProperties) {
         // If a property such as `type` changes and causes the internal <input>
         // value to change without dispatching an event, re-sync it.
         const value = this.getInput().value;
         if (this.value !== value) {
+            // Don't consider these updates (such as setting `defaultValue`) as
+            // the developer directly changing the `value`.
+            this.ignoreNextValueChange = true;
             // Note this is typically inefficient in updated() since it schedules
             // another update. However, it is needed for the <input> to fully render
             // before checking its value.
             this.value = value;
         }
+        if (this.refreshErrorAlert) {
+            // The past render cycle removed the role="alert" from the error message.
+            // Re-add it after an animation frame to re-announce the error.
+            requestAnimationFrame(() => {
+                this.refreshErrorAlert = false;
+            });
+        }
+    }
+    /** @bubbleWizEvent */
+    handleClick() {
+        this.focus();
     }
+    /** @bubbleWizEvent */
     handleFocusin(event) {
         this.focused = true;
     }
+    /** @bubbleWizEvent */
     handleFocusout(event) {
         if (this.matches(':focus-within')) {
             // Changing focus to another child within the text field, like a button
@@ -601,7 +743,7 @@ __decorate([
 __decorate([
     property({ type: String }),
     __metadata("design:type", Object)
-], TextField.prototype, "supportingTextId", void 0);
+], TextField.prototype, "textDirection", void 0);
 __decorate([
     property({ type: String, attribute: 'data-aria-autocomplete', noAccessor: true }),
     ariaProperty // tslint:disable-line:no-new-decorators
@@ -675,7 +817,7 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true }),
     __metadata("design:type", Object)
-], TextField.prototype, "readonly", void 0);
+], TextField.prototype, "readOnly", void 0);
 __decorate([
     property({ type: String }),
     __metadata("design:type", Object)
@@ -692,6 +834,22 @@ __decorate([
     state(),
     __metadata("design:type", Object)
 ], TextField.prototype, "focused", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], TextField.prototype, "refreshErrorAlert", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], TextField.prototype, "valueHasChanged", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], TextField.prototype, "nativeError", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], TextField.prototype, "nativeErrorText", void 0);
 __decorate([
     query('.md3-text-field__input'),
     __metadata("design:type", HTMLInputElement)