From 9ec9cab98b6860e765b95f9cb76e379c534eb310 Mon Sep 17 00:00:00 2001 From: Elliott Marquez Date: Mon, 19 Aug 2019 19:53:37 -0700 Subject: [PATCH] first pass at textfield readme --- packages/textfield/README.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/packages/textfield/README.md b/packages/textfield/README.md index 38918db81..83bf449f4 100644 --- a/packages/textfield/README.md +++ b/packages/textfield/README.md @@ -160,13 +160,21 @@ npm install @material/mwc-textfield | `icon` | `string` | Leading icon to display in input. See [`mwc-icon`](https://github.com/material-components/material-components-web-components/tree/master/packages/icon). | `iconTrailing` | `string` | Trailing icon to display in input. See [`mwc-icon`](https://github.com/material-components/material-components-web-components/tree/master/packages/icon). | `disabled` | `boolean` | Whether or not the input should be disabled. -| `required` | `boolean` | Displays error state if value is empty and input is blurred. -| `maxlength` | `number` | Maximum length to accept input. | `charCounter` | `boolean` | **Note: requries `maxlength` to be set.** Display character counter with max length. | `outlined` | `boolean` | Whether or not to show the material outlined variant. | `fullwidth` | `boolean` | Whether or not to make the input fullwidth. No longer displays `label`; only `placeholder` and `helper`. | `helper` | `string` | Helper text to display below the input. Display default only when focused. | `helperPersistent` | `boolean` | Always show the helper text despite focus. +| `required` | `boolean` | Displays error state if value is empty and input is blurred. +| `maxlength` | `number` | Maximum length to accept input. +| `validationMessage` | `string` | Message to show in the error color when the textfield is invalid. (Helper text will not be visible) +| `pattern` | `string` | [`HTMLInputElement.prototype.pattern`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation#Validation-related_attributes) (empty string will unset attribute) +| `min` | `number|string` | [`HTMLInputElement.prototype.min`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation#Validation-related_attributes) (empty string will unset attribute) +| `max` | `number|string` | [`HTMLInputElement.prototype.max`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation#Validation-related_attributes) (empty string will unset attribute) +| `step` | `number|null` | [`HTMLInputElement.prototype.step`](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation#Validation-related_attributes) (null will unset attribute) +| `validity` | `ValidityState` (readonly) | The [`ValidityState`](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) of the textfield. +| `willValidate` | `boolean` (readonly) | [`HTMLInputElement.prototype.willValidate`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement#Properties) +| `validator` | `Validator**|null` | Callback called before each validation check. See the [validation section](#Validation) for more details. \* `TextFieldType` is exported by `mwc-textfield` and `mwc-textfield-base` ```ts @@ -174,6 +182,19 @@ type TextFieldType = 'text'|'search'|'tel'|'url'|'email'|'password'| 'date'|'month'|'week'|'time'|'datetime-local'|'number'|'color'; ``` +\*\* `Validator` is not exported. See the [validation section](#Validation) for more details. +```ts +type Validator = (value: string, nativeValidity: ValidityState) => Partial +``` + +### Methods + +| Name | Description +| -------- | ------------- +| `checkValidity() => boolean` | Returns `true` if the textfield passes validity checks. Returns `false` and fires an [`invalid`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/invalid_event) event on the textfield otherwise. +| `reportValidity() => boolean` | Runs `checkValidity()` method, and if it returns false, then ir reports to the user that the input is invalid. +| `setCustomValidity(message:string) => void` | Sets a custom validity message (also overwrites `validationMessage`). If this message is not the empty string, then the element is suffering froma custom validity error and does not validate. + ### CSS Custom Properties Inherits CSS Custom properties from: @@ -190,6 +211,8 @@ Inherits CSS Custom properties from: | `--mdc-text-field-outlined-hover-border-color` | `rgba(0, 0, 0, 0.87)` | Color of the outlined textfield's outline when hovering. | `--mdc-text-field-outlined-disabled-border-color` | `rgba(0, 0, 0, 0.06)` | Color of the outlined textfield's outline when disabled. +### Validation + ## Additional references - [MDC Web textfields](https://material.io/develop/web/components/input-controls/text-field/)